saoovqe package

Submodules

saoovqe.ansatz module

API to enable fast creation of ansatzes.

Module containing the class representing an ansatz for SA-OO-VQE method, where all the inner coefficients are either 1 or -1.

class saoovqe.ansatz.Ansatz(ansatz: AnsatzType, n_spatial_orbs: int, n_qubits: int, n_particle: Tuple[int, int], repetitions: int, rotation_blocks='ry', entanglement_blocks='cx', entanglement='linear', fermionic_mapper: qiskit_nature.second_q.mappers.fermionic_mapper.FermionicMapper = None)

Bases: NLocal

Ansatz prepared for SA-OO-VQE with all inner coefficients set to either 1 or -1.

classmethod from_problem_set(ansatz: AnsatzType, problem: ProblemSet, repetitions: int, qubit_mapper: qiskit_nature.second_q.mappers.fermionic_mapper.FermionicMapper = None)

Alternative constructor creating Ansatz instance directly from instances of problem.ProblemSet class.

Parameters:

• ansatz – Type of ansatz

• problem – problem.ProblemSetProblemSet instance

• repetitions – Number of block repetitions

• qubit_mapper – Mapper used to encode operators to qubits

Returns:

An instance of Ansatz class

class saoovqe.ansatz.AnsatzType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: NoValueEnum

Enumerator representing the set of available ansatz structures.

GUCCD = 4

GUCCSD = 6

TWO_LOCAL = 1

UCCD = 3

UCCS = 2

UCCSD = 5

class saoovqe.ansatz.NoValueEnum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Utility class for printing settings of AnsatzType elements.

saoovqe.circuits module

Module for fast manipulation with often-used circuits.

Module comprising classes implementing an orthogonal set of circuits representing parts of initial to-be-optimized state vectors.

class saoovqe.circuits.HermitianOperatorEvaluator(operator, estimator: qiskit.primitives.BackendEstimator | qiskit.primitives.BackendEstimatorV2 | qiskit_ibm_runtime.EstimatorV2)

Bases: OperatorEvaluatorBase

Expectation value evaluator for Hermitian operators.

property estimator

Estimator providing implementation of a measurement.

get_evaluation_func(circuit: qiskit.QuantumCircuit) → Callable

Obtain evaluation function (i.e. a function returning expectation values when provided parameters).

Parameters:

circuit – Quantum circuit representing a parametrized state vector w.r.t. which the expectation values are computed.

Returns:

Evaluation function

property operator

Operator whose expectation values are being evaluated.

class saoovqe.circuits.OperatorEvaluatorBase(operator, estimator: qiskit.primitives.BackendEstimator | qiskit.primitives.BackendEstimatorV2 | qiskit_ibm_runtime.EstimatorV2)

Bases: ABC

Base class for evaluator of operators’ expectation values.

abstract get_evaluation_func(circuit: qiskit.QuantumCircuit) → Callable

Returns an evaluation function, which returns expectation values for provided parameters.

Parameters:

circuit – Quantum Circuit

Returns:

Function returning expectation values

class saoovqe.circuits.OrthogonalCircuitSet(n_states: int, n_spatial_orbs: int, n_particles: tuple[int, int], qubit_mapper: qiskit_nature.second_q.mappers.QubitMapper | None = None)

Bases: object

Implementation of a circuit set representing parts of orthogonal state vectors.

add_resolution_rotation_circuit(circuit: qiskit.QuantumCircuit, rotation_angle: float | None = None)

Creates the singly-excited singlet excitation (superposition of one spin-up and one spin-down excitation) see Fig. 1 in Ref. https://doi.org/10.1021/acs.jctc.1c00995

If applied to \(|0000\rangle\) with \(\varphi=0\), transforms the state to \(|0101\rangle = |\text{HF}\rangle\).

property circuits

Constructed quantum circuits

classmethod from_problem_set(n_states: int, problem: ProblemSet)

Alternative constructor for making instance of OrthogonalCircuitSet from problem.ProblemSet instance.

Parameters:

• n_states – Number of quantum states.

• problem – problem.ProblemSet instance

:return Instance of OrthogonalCircuitSet created w.r.t. “problem” parameter

get_new_rotation_circuit()

Obtain \(|\psi_0\rangle = \cos(\varphi)|\psi_A\rangle + \sin( \varphi)|\psi_B\rangle\) by applying the rotating circuit to \(|0000\rangle\)

This DOES NOT require any knowledge of initial \(|\psi_A\rangle\) or \(|\psi_B\rangle\) vectors

property n_particles

Number of particles

property n_qubits

Number of qubits

property n_states

Number of quantum states

property qubit_converter

Qubit mapper for encoding of operators to quantum circuits

transpile(backend: qiskit.providers.BackendV1 | qiskit.providers.BackendV2)

Transpiles the circuits in-place w.r.t. the provided backend.

Parameters:

backend – The backend w.r.t. whose gate set the circuits are going to be transpiled.

saoovqe.gradient module

Module for computation of QuantumCircuit gradients.

DEPRECATED: will be replaced by qiskit.algorithms.gradients in the future. https://qiskit.org/documentation/stubs/qiskit.algorithms.gradients.html #module-qiskit.algorithms.gradients

class saoovqe.gradient.GradMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Enumerator representing the type of gradient computation being used.

FINITE_DIFF = 'fin_diff'

PARAMETER_SHIFT = 'param_shift'

class saoovqe.gradient.GradientEvaluator(ansatz_circuit: Ansatz, op_evaluator: OperatorEvaluatorBase, deriv_params: ParameterView[ParameterVectorElement] | list[Parameter | ParameterVectorElement], grad_method: GradMethod = GradMethod.PARAMETER_SHIFT, hess_method: GradMethod = GradMethod.PARAMETER_SHIFT)

Bases: object

Class for gradient and Hessian computation.

property ansatz_circuit

Ansatz quantum circuit

property deriv_params

The ansatz parameters. Derivatives are computed with respect to these parameters.

eval_grad(params: list[float] | tuple[float] | ndarray) → ndarray

Evaluates gradient w.r.t. circuit parameters.

Parameters:

params – Parameters to be passed into the circuit.

Returns:

Gradient values

eval_hess(params: list[float] | tuple[float] | ndarray) → ndarray

Evaluates Hessian w.r.t. circuit parameters.

Parameters:

params – Parameters to be passed into the circuit.

Returns:

Gradient values

property grad_method: GradMethod

Method chosen for gradient computation

property hess_method: GradMethod

Method chosen for Hessian computation

saoovqe.logger_config module

Module containing global settings for logging.

saoovqe.molecule module

Module containing implementation of a class EMolecule for dealing with the chemical system and its geometry.

class saoovqe.molecule.EMolecule(*args: Any, **kwargs: Any)

Bases: MoleculeInfo

Class containing information about the chemical system.

property geometry

Geometry in a list form.

property geometry_str

Geometry in a text-string form

property n_atoms

Number of atoms

property psi4_molecule

Psi4 instance of Molecule class

saoovqe.problem module

Module enabling definition of the problem to solve.

Module containing ProblemSet class, which comprises all the information about the relevant electronic structure problem together with all the operators and performs all the necessary operations like active space transformations etc.

class saoovqe.problem.ProblemSet(symbols: list[str], coords: list[list], charge: int, multiplicity: int, n_electrons_active: int, n_orbitals_active: int, basis_name: str = 'sto-3g', fermionic_mapper: qiskit_nature.second_q.mappers.fermionic_mapper.FermionicMapper = qiskit_nature.second_q.mappers.JordanWignerMapper, wfn: tuple[ndarray, bool] | None = None, psi4_out_file: str = 'psi4-rhf.out')

Bases: object

Class containing relevant instances of ElectronicStructureProblem together with their operators and transformers. It comprises all the information about the problem being solver including the aggregated chemistry driver.

property active_orbitals: list[int]

Indices of the active orbitals (in the active-space-transformed electronic structure problem).

property active_space_transformer: qiskit_nature.second_q.transformers.ActiveSpaceTransformer

Instance of the used active space transformer.

property as_operators: list[qiskit_nature.second_q.operators.SparseLabelOp, dict[str, qiskit_nature.second_q.operators.SparseLabelOp]]

Operators in active space transformed electronic structure problem.

property as_problem: qiskit_nature.second_q.problems.ElectronicStructureProblem

The instance of electronic structure problem after active space transformation.

property basis_name: str

Name of the basis set used for the initial HF computation.

property c_mat: ndarray

Matrix of molecular orbitals coefficients.

construct_hamiltonian_nuc_deriv_op(atom_moved: int) → None

Construct Hamiltonian nuclear derivatives operator and evaluate it for the given atom coordinates.

Parameters:

atom_moved – Index of the atom w.r.t. which coordinates the nuclear derivatives are computed.

create_1_body_exc_op_active()

Creates 1-body excitation operator in the active space.

create_1_body_exc_op_full()

Creates 1-body excitation operator in the full space (without active-space transformation).

create_2_body_exc_op_active()

Creates 2-body excitation operator in the active space.

create_2_body_exc_op_full()

Creates 2-body excitation operator in the full space (without active-space transformation).

property e_nuc_der

Derivative of nuclear energy repulsion as computed by Psi4.

property fermionic_mapper

Instance of mapper used to map fermionic operators to qubits.

property frozen_orbitals_indices: list[int]

Indices of the frozen orbitals (in the active-space-transformed electronic structure problem).

property full_ham_one_body_integrals_ao

1-body electronic integrals of the full (non-transformed) Hamiltonian in the atomic basis.

property full_ham_one_body_integrals_mo

1-body electronic integrals of the full (non-transformed) Hamiltonian in the molecular basis.

property full_ham_two_body_integrals_ao

2-body electronic integrals of the full (non-transformed) Hamiltonian in the atomic basis.

property full_ham_two_body_integrals_mo

2-body electronic integrals of the full (non-transformed) Hamiltonian in the molecular basis.

property full_problem: qiskit_nature.second_q.problems.ElectronicStructureProblem

The full electronic structure problem instance, before any transformation applied.

general_basis_change(general_tensor, key, c_mat=None)

Change the basis of a general interaction tensor. Motivated by OpenFermion.

property geometry_str: str | None

Geometry string used in Psi4 calculations.

get_qubit_hamiltonian_nuclear_derivative_op(atom_moved: int) → list[qiskit.quantum_info.SparsePauliOp | None]

Obtain the nuclear derivative Hamiltonian operator in the active space.

Parameters:

atom_moved – Index of the atom w.r.t. which coordinates the nuclear derivatives are computed.

Returns:

Nuclear derivative Hamiltonian operator.

property molecule: EMolecule

Instance comprising the information about the molecule itself like its geometry, elements etc.

property molecule_driver: qiskit_nature.second_q.drivers.Psi4Driver

Instance of Psi4 driver performing initial HF computation and providing some derivatives in atomic-orbital basis.

property n_molecular_orbitals: int

Number of molecular orbitals in the full electronic structure problem, i.e. before any transformation happened.

property n_orbitals_active: int

Number of molecular orbitals in the active-space-transformed electronic structure problem.

property n_orbitals_frozen: int

Number of frozen orbitals (in the active-space-transformed electronic structure problem).

property n_orbitals_virtual: int

Number of virtual orbitals (in the active-space-transformed electronic structure problem).

property n_qubits

Number of qubits used to encode an active-space Hamiltonian.

property nuclear_repulsion_eng

Nuclear repulsion energy as obtained from Psi4.

property one_body_el_int_nuc_der

Nuclear derivatives of 1-body electronic integrals in the molecular basis.

property one_body_el_int_nuc_der_explicit_ao

Nuclear derivatives of 1-body electronic integrals in atomic-orbital basis.

property one_body_el_int_nuc_der_explicit_mo

Nuclear derivatives of 1-body electronic integrals in molecular-orbital basis.

property one_body_exc_op_active

1-body excitation operator (part of Hamiltonian) in the active-space-transformed electronic structure problem.

property overlap_el_int_nuc_der_explicit_ao

Nuclear derivatives of overlap electronic integrals in atomic-orbital basis.

property overlap_el_int_nuc_der_explicit_mo

Nuclear derivatives of overlap electronic integrals in molecular-orbital basis.

property psi4_mints

Psi4 molecular integrals.

property qubit_active_hamiltonian

Hamiltonian in the active-space-transformed electronic structure problem.

property qubit_s_squared

S^2 operator in the active-space-transformed electronic structure problem.

property transform_eng_shift

Energy shifted caused by active space transformation. This value is added to the final result to compensate for it.

property two_body_el_int_nuc_der

Nuclear derivatives of 2-body electronic integrals in the molecular basis.

property two_body_el_int_nuc_der_explicit_ao

Nuclear derivatives of 2-body electronic integrals in atomic-orbital basis.

property two_body_el_int_nuc_der_explicit_mo

Nuclear derivatives of 2-body electronic integrals in molecular-orbital basis.

property two_body_exc_op_active

2-body excitation operator (part of Hamiltonian) in the active-space-transformed electronic structure problem.

property unit_constants: dict[str, float]

Constants used for unit conversions.

update_problem_from_mo_coeffs(c: array)

Updates Hamiltonian with electronic integrals, basis transformer and matrix of molecular-orbital coefficients. If the integrals are passed in atomic orbital basis, they will be transformed to the molecular one using ‘c’ matrix.

Parameters:

c – Matrix of molecular orbital coefficients.

property virtual_orbitals_indices: list[int]

Indices of the virtual orbitals (in the active-space-transformed electronic structure problem).

classmethod with_dia_orbs_from_prev_wfn(symbols: list[str], coords: list[list], charge: int, multiplicity: int, n_electrons_active: int, n_orbitals_active: int, prev_wfn: psi4.core.RHF, basis_name: str = 'sto-3g', fermionic_mapper: qiskit_nature.second_q.mappers.fermionic_mapper.FermionicMapper = qiskit_nature.second_q.mappers.JordanWignerMapper)

Constructor for ProblemSet allowing passing of a wavefunction belonging to previous point (geometry) for computations in a chain-like manner. Subsequently, it performs diabatization of the orbitals, before they’re used.

Parameters:

• symbols – Symbols of atoms in molecule

• coords – Coordinates of atoms

• charge – System’s charge

• multiplicity – System’s multiplicity

• n_electrons_active – Number of electrons present in an active space

• n_orbitals_active – Number of molecular orbitals present in an active space

• prev_wfn – Wavefunction for the previous geometry in the computation

• basis_name – Name of the basis set used in preliminary SCF computation

• fermionic_mapper – Instance of FermionicMapper to map necessary operators to qubits

Returns:

An instance of ProblemSet

saoovqe.vqe_optimization module

Module containing the core SAOOVQE engine.

Core SA-OO-VQE module comprising implementation of the core SA-OO-VQE solver class together with optimizer interfaces etc. The module aims to contain all the logic behind SA-OO-VQE solution, which is not directly connected to the properties of the electronic structure problem being solved or to the properties of logically-independent circuits like an initial orthogonal set or an ansatz.

class saoovqe.vqe_optimization.NoValueEnum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Class specifying printing of enumerator elements.

class saoovqe.vqe_optimization.SAOOVQE(estimator: BackendEstimator | BackendEstimatorV2 | EstimatorV2, initial_circuits: OrthogonalCircuitSet, ansatz: Ansatz, problem: ProblemSet, sampler: BaseSampler = None, weight_attribution: WeightAttribution = <WeightAttribution.EQUIVALENT>, orbital_optimization_settings: Optional[dict] = None)

Bases: object

The SA-OO-VQE solver.

This class comprises all the logic of the method except its logically-independent parts (e.g. ansatz) or the parts directly connected to the electronic structure properties.

property active_hamiltonian_evaluator: HermitianOperatorEvaluator

The expected-value estimator of Hamiltonian after active-space transformation.

property ansatz: Ansatz

The ansatz representing to-be-optimized part of a state vector.

property ansatz_param_values: ndarray | None

The optimal set of ansatz parameters after running vqe_optimization.SAOOVQE.get_energy().

property ci_nacs: list[ndarray | None]

Non-adiabatic CI couplings obtained by running vqe_optimization.SAOOVQE.eval_nac().

property csf_nacs: list[ndarray | None]

Non-adiabatic CSF couplings obtained by running vqe_optimization.SAOOVQE.eval_nac().

property dHab: list[ndarray | None]

<<<<<<< HEAD

derivative of H_AB = <Psi_A | H | Psi_B> coupling obtained by running vqe_optimization.SAOOVQE.eval_dHab().

property estimator: qiskit.primitives.BaseEstimator

The estimator object used to obtain expected values.

eval_dHab(atom_idx: int) → array

Computes derivative of H_AB coupling for a given atom in a specific state.

Parameters:

atom_idx – Index of the atom (with respect to the provided geometry), w.r.t. whose position the coupling is evaluated.

Returns:

Vector of dH_AB coupling.

eval_eng_gradient(state_idx: int, atom_moved: int) → ndarray

Function to evaluate the energy gradient dE_{I}/dx.

Parameters:

• state_idx – Index I of the relevant state (0 - ground state, 1 - first excited state)

• atom_moved – Index of the atom (with respect to the provided geometry), w.r.t. whose position the gradient is evaluated.

Returns:

Energy gradient of the I-th state evaluated at the Cartesian coordinates of the selected atom.

Return type:

tuple

eval_nac(atom_idx: int) → array

Computes non-adiabatic couplings for a given atom in a specific state.

Parameters:

atom_idx – Index of the atom (with respect to the provided geometry), w.r.t. whose position the coupling is evaluated.

Returns:

Vector of non-adiabatic couplings.

eval_state_overlap(circuit1: qiskit.QuantumCircuit, circuit2: qiskit.QuantumCircuit) → float

Measurement of state overlap utilizing Hadamard test.

Parameters:

• circuit1 – The circuit representing the first state of the overlap

• circuit2 – The circuit representing the second state of the overlap

Returns:

The coefficient of the state overlap.

get_energy(st_avg_optimizer: qiskit_algorithms.optimizers.Optimizer = qiskit_algorithms.optimizers.SciPyOptimizer, angle_optimizer: ~saoovqe.vqe_optimization.UnivariateOptimizer = <saoovqe.vqe_optimization.UnivariateOptimizer object>, initial_ansatz_parameters: ~typing.List | ~numpy.ndarray = None, resolution_rotation: bool = True, s_squared_cost_coeff: float = 1, optim_thresh: float = 1e-08)

Extract the circuit-parameters, energies and states after the optimization of SA-VQE.

Set resolution_rotation = False for diabatic calculations, for adiabatic leave True.

get_state_couplings(idx_a: int, idx_b: int) → float

This method computes interstate coupling :math:`left< psi_{a} | hat{H} | psi_{b}

ight>`

param idx_a:

Index of the first state that is used to compute the interstate coupling

param idx_b:

Index of the second state that is used to compute the interstate coupling

return:

Interstate coupling

property initial_circuits: OrthogonalCircuitSet

The set of circuits representing initial mutually orthogonal states.

property n_mo_optim: float | None

The number of optimized molecular orbitals.

property optimized_state_circuits: list[qiskit.QuantumCircuit] | None

The set of circuits representing approximately-optimal state vectors obtained after running vqe_optimization.SAOOVQE.get_energy().

orb_opt_newton(circuits)

Performs orbital-optimization process via Newton-Raphson method.

property orbital_optimization_settings: dict | None

The options of orbital-optimization process.

property problem: ProblemSet

The electronic structure problem properties, relevant operators and the relevant methods.

property resolution_angle: float | None

The optimal resolution angle in radians after running vqe_optimization.SAOOVQE.get_energy().

property s_squared_evaluator: HermitianOperatorEvaluator

The expected-value estimator of S^2 operator after active-space transformation.

property total_nacs: list[ndarray | None]

Total non-adiabatic (CI + CSF) couplings obtained by running vqe_optimization.SAOOVQE.eval_nac().

property weights: list[float]

The weights corresponding to computed states.

class saoovqe.vqe_optimization.UnivariateOptimizer(method: Callable | UnivariateOptimizerMethod = UnivariateOptimizerMethod.BOUNDED, bracket: tuple[float] | list[float] | None = None, bounds: tuple[float] | list[float] | None = (0, 6.283185307179586), args: tuple | None = None, tol: float | None = None, options: dict | None = None)

Bases: object

This class represents an object (method + numerical parameters) passable to scipy.optimize.minimize_scalar() function.

SciPy Docs reference: https://docs.scipy.org/doc/scipy/reference /generated/scipy.optimize.minimize_scalar.html

property args: tuple | None

The set of extra parameters for the optimized function.

property bounds: tuple[float] | list[float] | None

The bounds \((a, b)\) for Bounded method. This setting denotes its optimization domain.

property bracket: tuple[float] | list[float] | None

The bracketing interval \((a, b, c)\) with \(a < b < c\) or \((a, c)\), for methods Brent and Golden. It serves as an initial interval, NOT limiting the location of an obtained solution.

property method: Callable | UnivariateOptimizerMethod

The univariate optimization method being used.

property options: dict | None

The dictionary of solver-specific options.

property tol: float | None

The termination threshold. Its behavior differs among solvers - check with the referenced SciPy documentation!

class saoovqe.vqe_optimization.UnivariateOptimizerMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The enumerator denoting the set of supported univariate optimizers.

BOUNDED = 'bounded'

BRENT = 'brent'

GOLDEN = 'golden'

class saoovqe.vqe_optimization.WeightAttribution(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: NoValueEnum

The description of the state-weight attribution in the SA-OO-VQE method. The weights can be distributed equally or in a decreasing manner.

DECREASING = 2

EQUIVALENT = 1

Module contents

Init file for module saoovqe.

This file imports everything from the project to prove all-encompassing interface.