inquanto.express

Express drivers

class DriverGeneralizedHubbard1D(n, e=0.0, t=-1.0, u=0.0, v=0.0, ring=False)

Bases: DriverGeneralizedHubbard

Creates 1D Generalized Hubbard Hamiltonian with ring and chain topology.

Parameters:

  • e (float | list[float], default: 0.0) – On-site energies. If a float is given, applied to all sites. If list is given, its len must equal n, and index corresponds to site.

  • t (float, default: -1.0) – Nearest neighbor coupling.

  • u (float, default: 0.0) – On-site repulsion.

  • v (float, default: 0.0) – Nearest neighbor coulomb repulsion.

  • n (int) – Number of sites.

  • ring (bool, default: False) – ring (True) or open chain (False).

static generate_chain(n, diagonal, off_diagonal)

Generates nearest neighbor connectivity matrix for chain topology.

Parameters:

  • n (int) – Size of the matrix.

  • diagonal (float | list[float]) – Value(s) substituted to all diagonals.

  • off_diagonal (float) – Value substituted to the off-diagonals.

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

static generate_ring(n, diagonal, off_diagonal)

Generates nearest neighbor connectivity matrix for ring topology.

Parameters:

  • n (int) – Size of the matrix.

  • diagonal (float | list[float]) – Value(s) substituted to the diagonals.

  • off_diagonal (float) – Value substituted to the off-diagonals.

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

get_fermion_space()

Creates the Fermion space for 1D Hubbard model.

Returns:

FermionSpace – A representation of the fermionic Hilbert space.

get_initial_state()

Creates the initial state for 1D Hubbard model.

It assumes half-filling and arranges particles anti-ferromagnetically on neighboring sites.

Returns:

FermionState – Initial state.

get_one_two_body_terms()

Generates the one- and two-electron integrals for 1D Hubbard model.

Returns:

tuple[ndarray, ndarray] – One-electron integrals and two-electron integrals.

get_system()

Generates the Hubbard system.

Returns:

tuple[FermionOperator, FermionSpace, FermionState] – Hamiltonian fermion operator, Fock space, Hartree-Fock state.

property n_electron: int

Returns the number of electrons in the total system.

property n_orb: int

Returns the number of orbitals in the total system.

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverGeneralizedHubbard2D(n_x, n_y, e=0.0, t=-1.0, u=0.0, v=0.0, pbc=False, site_labelling=SiteLabelling2D.grid)

Bases: DriverGeneralizedHubbard

Creates 2D Generalized Hubbard Hamiltonian on a square lattice with/without periodic boundary conditions (PBC).

Parameters:

  • e (float | list[float], default: 0.0) – On-site energies. If a float is given, it is applied to all sites. If list is given, its length must be equal to the number of sites, with each entry corresponding to a site.

  • t (float, default: -1.0) – Nearest neighbor coupling.

  • u (float, default: 0.0) – U on-site repulsion.

  • v (float, default: 0.0) – Nearest neighbor coulomb repulsion.

  • n_x (int) – Number of sites in x direction, must be >1.

  • n_y (int) – Number of sites in y direction, must be >1.

  • pbc (bool, default: False) – Periodic boundary conditions (True) or open boundary conditions (False).

  • site_labelling (SiteLabelling2D, default: SiteLabelling2D.grid) – Type of site labelling using :class: “SiteLabelling2D”. It defaults to a row-major ordered grid.

static generate_grid(n_x, n_y, on_site, inter_site, pbc)

Generates nearest neighbor connectivity matrix for a 2D square grid.

Parameters:

  • n_x (int) – Size of the grid in x direction, must be >1.

  • n_y (int) – Size of the grid in y direction, must be >1.

  • on_site (float | list[float]) – Value(s) substituted to all diagonals.

  • inter_site (float) – Value substituted to the off-diagonals.

  • pbc (bool) – Periodic boundary conditions (True) or open boundary conditions (False).

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

static generate_snake(n_x, n_y, on_site, inter_site, pbc)

Generates nearest neighbor connectivity matrix for a 2D square grid with snaking pattern.

Parameters:

  • n_x (int) – Size of the grid in x direction, must be >1.

  • n_y (int) – Size of the grid in y direction, must be >1.

  • on_site (float | list[float]) – Value(s) substituted to all diagonals.

  • inter_site (float) – Value substituted to the off-diagonals.

  • pbc (bool) – Periodic boundary conditions (True) or open boundary conditions (False).

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

get_fermion_space()

Creates the Fermion space for 2D Hubbard model.

Returns:

FermionSpace – Fermion space.

get_initial_state()

Creates the initial state for 1D Hubbard model.

It assumes half-filling and arranges particle anti-ferromagnetically on neighboring sites.

Returns:

FermionState – Initial state.

get_one_two_body_terms()

Generates the one- and two-electron integrals for 2D Hubbard model.

Returns:

tuple[ndarray, ndarray] – One-electron integrals and two-electron integrals.

get_system()

Generates the Hubbard system.

Returns:

tuple[FermionOperator, FermionSpace, FermionState] – Hamiltonian fermion operator, Fock space, Hartree-Fock state.

property n_electron: int

Returns the number of electrons in the total system.

property n_orb: int

Returns the number of orbitals in the total system.

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverHubbardDimer(t=0.2, u=2.0)

Bases: GeneralDriver

Driver creating a dimer Hubbard Hamiltonian.

Parameters:

  • t (float, default: 0.2) – Coupling energy. Note that here t is negated in the hamiltonian_operator generated by self.get_system(), which is not the case in DriverGeneralizedHubbard.get_system().

  • u (float, default: 2.0) – On-site repulsion.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

get_system()

Generates the Hubbard dimer.

Returns:

tuple[FermionOperator, FermionSpace, FermionState] – Hamiltonian fermion operator, Fermion space, initial state.

property n_electron: int

Returns the number of electrons in the total system.

property n_orb: int

Returns the number of orbitals in the total system.

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverIsingCustomConnectivity(j, h, connectivity_matrix)

Bases: GeneralDriver

Driver for a transverse-field Ising hamiltonian with general lattice topology from a qubit connectivity matrix.

Builds the hamiltonian: \(H = \sum_{i<j}^{N_q} J_{ij} Z_i Z_j + h\sum_i^{N_q} X_i\), where \(N_q\) is the number of qubits, and \(J_{ij}\) is the product of the interaction strength j and the connectivity matrix.

Parameters:

  • j (float) – Interaction strength (negative for ferromagnetic, positive for antiferromagnetic).

  • h (float) – Transverse field.

  • connectivity_matrix (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Lattice connectivity matrix. Only the lower triangular elements are used.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

get_system()

Return the qubit hamiltonian, space and state.

Returns:

tuple[QubitOperator, QubitSpace, QubitState] – TFIM qubit hamiltonian, corresponding qubit space, qubit state of zeroes (uniform ferromagnetic state).

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverIsing1D(j, h, n)

Bases: DriverIsingCustomConnectivity

Driver for a 1D, nearest-neighbor transverse-field Ising hamiltonian with open boundary conditions.

Builds the hamiltonian: \(H = J\sum_{i}^{N_q} Z_i Z_{i+1} + h\sum_i^{N_q} X_i\), where \(N_q\) is the number of qubits.

Parameters:

  • j (float) – Interaction strength (negative for ferromagnetic, positive for antiferromagnetic).

  • h (float) – Transverse field.

  • n (int) – Number of sites (qubits).

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

get_system()

Return the qubit hamiltonian, space and state.

Returns:

tuple[QubitOperator, QubitSpace, QubitState] – TFIM qubit hamiltonian, corresponding qubit space, qubit state of zeroes (uniform ferromagnetic state).

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverIsing1DRing(j, h, n)

Bases: DriverIsingCustomConnectivity

Driver for a 1D, nearest-neighbor transverse-field Ising hamiltonian with periodic boundary conditions.

Builds the hamiltonian: \(H = J\sum_{i}^{N_q} Z_i Z_{i+1} + h\sum_i^{N_q} X_i\), where \(N_q\) is the number of qubits. The first and last qubits are connected to form a ring geometry.

Parameters:

  • j (float) – Interaction strength (negative for ferromagnetic, positive for antiferromagnetic).

  • h (float) – Transverse field.

  • n (int) – Number of sites (qubits).

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

get_system()

Return the qubit hamiltonian, space and state.

Returns:

tuple[QubitOperator, QubitSpace, QubitState] – TFIM qubit hamiltonian, corresponding qubit space, qubit state of zeroes (uniform ferromagnetic state).

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

Express functions

Data for example systems for testing.

class DriverGeneralizedHubbard1D(n, e=0.0, t=-1.0, u=0.0, v=0.0, ring=False)

Bases: DriverGeneralizedHubbard

Creates 1D Generalized Hubbard Hamiltonian with ring and chain topology.

Parameters:

  • e (float | list[float], default: 0.0) – On-site energies. If a float is given, applied to all sites. If list is given, its len must equal n, and index corresponds to site.

  • t (float, default: -1.0) – Nearest neighbor coupling.

  • u (float, default: 0.0) – On-site repulsion.

  • v (float, default: 0.0) – Nearest neighbor coulomb repulsion.

  • n (int) – Number of sites.

  • ring (bool, default: False) – ring (True) or open chain (False).

static generate_chain(n, diagonal, off_diagonal)

Generates nearest neighbor connectivity matrix for chain topology.

Parameters:

  • n (int) – Size of the matrix.

  • diagonal (float | list[float]) – Value(s) substituted to all diagonals.

  • off_diagonal (float) – Value substituted to the off-diagonals.

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

static generate_ring(n, diagonal, off_diagonal)

Generates nearest neighbor connectivity matrix for ring topology.

Parameters:

  • n (int) – Size of the matrix.

  • diagonal (float | list[float]) – Value(s) substituted to the diagonals.

  • off_diagonal (float) – Value substituted to the off-diagonals.

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

get_fermion_space()

Creates the Fermion space for 1D Hubbard model.

Returns:

FermionSpace – A representation of the fermionic Hilbert space.

get_initial_state()

Creates the initial state for 1D Hubbard model.

It assumes half-filling and arranges particles anti-ferromagnetically on neighboring sites.

Returns:

FermionState – Initial state.

get_one_two_body_terms()

Generates the one- and two-electron integrals for 1D Hubbard model.

Returns:

tuple[ndarray, ndarray] – One-electron integrals and two-electron integrals.

get_system()

Generates the Hubbard system.

Returns:

tuple[FermionOperator, FermionSpace, FermionState] – Hamiltonian fermion operator, Fock space, Hartree-Fock state.

property n_electron: int

Returns the number of electrons in the total system.

property n_orb: int

Returns the number of orbitals in the total system.

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class DriverGeneralizedHubbard2D(n_x, n_y, e=0.0, t=-1.0, u=0.0, v=0.0, pbc=False, site_labelling=SiteLabelling2D.grid)

Bases: DriverGeneralizedHubbard

Creates 2D Generalized Hubbard Hamiltonian on a square lattice with/without periodic boundary conditions (PBC).

Parameters:

  • e (float | list[float], default: 0.0) – On-site energies. If a float is given, it is applied to all sites. If list is given, its length must be equal to the number of sites, with each entry corresponding to a site.

  • t (float, default: -1.0) – Nearest neighbor coupling.

  • u (float, default: 0.0) – U on-site repulsion.

  • v (float, default: 0.0) – Nearest neighbor coulomb repulsion.

  • n_x (int) – Number of sites in x direction, must be >1.

  • n_y (int) – Number of sites in y direction, must be >1.

  • pbc (bool, default: False) – Periodic boundary conditions (True) or open boundary conditions (False).

  • site_labelling (SiteLabelling2D, default: SiteLabelling2D.grid) – Type of site labelling using :class: “SiteLabelling2D”. It defaults to a row-major ordered grid.

static generate_grid(n_x, n_y, on_site, inter_site, pbc)

Generates nearest neighbor connectivity matrix for a 2D square grid.

Parameters:

  • n_x (int) – Size of the grid in x direction, must be >1.

  • n_y (int) – Size of the grid in y direction, must be >1.

  • on_site (float | list[float]) – Value(s) substituted to all diagonals.

  • inter_site (float) – Value substituted to the off-diagonals.

  • pbc (bool) – Periodic boundary conditions (True) or open boundary conditions (False).

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

Parameters:
Return type:

dict[Any, Any]

static generate_snake(n_x, n_y, on_site, inter_site, pbc)

Generates nearest neighbor connectivity matrix for a 2D square grid with snaking pattern.

Parameters:

  • n_x (int) – Size of the grid in x direction, must be >1.

  • n_y (int) – Size of the grid in y direction, must be >1.

  • on_site (float | list[float]) – Value(s) substituted to all diagonals.

  • inter_site (float) – Value substituted to the off-diagonals.

  • pbc (bool) – Periodic boundary conditions (True) or open boundary conditions (False).

Returns:

ndarray – The nearest neighbor connectivity matrix as a sparse matrix.

get_fermion_space()

Creates the Fermion space for 2D Hubbard model.

Returns:

FermionSpace – Fermion space.

get_initial_state()

Creates the initial state for 1D Hubbard model.

It assumes half-filling and arranges particle anti-ferromagnetically on neighboring sites.

Returns:

FermionState – Initial state.

get_one_two_body_terms()

Generates the one- and two-electron integrals for 2D Hubbard model.

Returns:

tuple[ndarray, ndarray] – One-electron integrals and two-electron integrals.

get_system()

Generates the Hubbard system.

Returns:

tuple[FermionOperator, FermionSpace, FermionState] – Hamiltonian fermion operator, Fock space, Hartree-Fock state.

property n_electron: int

Returns the number of electrons in the total system.

property n_orb: int

Returns the number of orbitals in the total system.

print_json_report(*args, **kwargs)

Prints report in json format.

Parameters:
Return type:

None

class SiteLabelling2D(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of site labelling schemes for 2D Hubbard model on a square lattice.

grid

row-major ordering of sites.

snake

ordering of rows in a snaking pattern where sites indexed i & i+1 are always neighbors.

grid = 1
snake = 2
get_noisy_backend(n_qubits, cx_err=0.008, ro_err=0.01)

Makes a noisy Aer backend with specified error rates.

This function uses the AerBackend from pytket.extensions.qiskit and sets up a custom noise model with specified depolarizing error rates for CX gates and readout errors for qubits.

Parameters:

  • n_qubits (int) – The number of qubits for the noisy backend.

  • cx_err (float, default: 0.008) – The depolarizing error rate for CX gates. Defaults to 0.008.

  • ro_err (float, default: 0.01) – The readout error rate for the qubits. Defaults to 0.01.

Returns:

Backend – A noisy Aer backend instance constructed with the specified noise model.

Examples

>>> backend = get_noisy_backend(5)
>>> type(backend)
<class 'pytket.extensions.qiskit.backends.aer.AerBackend'>
get_system(data_in)

Return the fermionic Hamiltonian operator, Fock space, and Hartree Fock state from an express dataset.

Parameters:

data_in (str | dict[str, Any] | tuple[Any, ...]) – An express dataset file name, or previously loaded express dataset.

Returns:

tuple[ChemistryRestrictedIntegralOperator | ChemistryUnrestrictedIntegralOperator, FermionSpace, FermionState] – Fermion Hamiltonian, Fock space, Fock state.

list_h5()

Lists the predefined h5 data files in the express module.

Return type:

list[str]

load_h5(name, as_tuple=False)

Loads predefined results from the express module.

Parameters:

  • name (str | Group) – The name of the h5 file with extension in the express module.

  • as_tuple (bool, default: False) – If set to True, output will be returned as a namedtuple.

Returns:

dict[str, Any] | tuple[Any, ...] – Dictionary or namedtuple format of the results.

Raises:

TypeError – If unsupported operator type is loaded.

propagate(qubit_hamiltonian, qubit_state, t)

Propagate a qubit state with a Hamiltonion to a point of time.

Parameters:
Returns:

QubitState – The evolved qubit state, \(|\Psi(t)\rangle = e^{-itH} |\Psi(0)\rangle\)

random_circuit_ansatz(n_qubit=3, seed=0, return_sv=False)

Constructs a random circuit ansatz.

A random normalized complex statevector will be generated with a seed, and by using StatePreparationBox a circuit will be built.

Parameters:

  • n_qubit (int, default: 3) – Number of qubits.

  • seed (int, default: 0) – Random seed.

  • return_sv (bool, default: False) – If True, the function also returns the statevector.

Returns:

CircuitAnsatz | tuple[CircuitAnsatz, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]] – A circuit ansatz built with StatePreparationBox from pytket, and optionally the statevector.

run_rhf(hamiltonian_operator, n_electron, guess_mo_coeff=None, maxit=MAXIT, conv=CONV)

Runs a simple RHF calculation for hamiltonian_operator.

Warning

It is not advised for production calculation, but for testing.

Parameters:

  • hamiltonian_operator (ChemistryRestrictedIntegralOperator) – A Hamiltonian operator.

  • n_electron (int) – number of electrons.

  • guess_mo_coeff (Optional[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]], default: None) – initial guess for mo_coeff.

  • maxit (int, default: MAXIT) – Maximum number of iteration.

  • conv (float, default: CONV) – Criterion for convergence.

Returns:

tuple[float, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], RestrictedOneBodyRDM] – Total energy, orbital energies, mo orbitals, density matrix.

run_rohf(hamiltonian_operator, n_electron, spin, guess_mo_coeff=None, maxit=MAXIT, conv=CONV)

Runs a simple ROHF calculation for hamiltonian_operator.

Warning

It is not advised for production calculation, but for testing.

Parameters:

  • hamiltonian_operator (ChemistryRestrictedIntegralOperator) – A Hamiltonian operator.

  • n_electron (int) – Number of electrons.

  • spin (int) – Spin.

  • guess_mo_coeff (Optional[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]], default: None) – Initial guess for mo_coeff.

  • maxit (int, default: MAXIT) – Maximum number of iteration.

  • conv (float, default: CONV) – Criterion for convergence.

Returns:

tuple[float, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], RestrictedOneBodyRDM] – Total energy, orbital energies, mo orbitals, density matrix.

run_time_evolution(initial_state, time_span, qubit_hamiltonian, *operators, n_qubits=None, real=True)

Simulating exact time evolution.

Parameters:

  • initial_state (QubitState) – The initial qubit state for the time evolution.

  • time_span (Sequence[float | complex]) – The time span, which is a list of points of time.

  • qubit_hamiltonian (QubitOperator) – The Hamiltonian to drive the time evolution.

  • *operators (QubitOperator) – Optional operators for which the expectation value should be calculated during the evolution.

  • real (bool, default: True) – Optional to switch to imaginary time evolution. Default value is real.

  • n_qubits (Optional[int], default: None)

Returns:

tuple[list[QubitState], ndarray[tuple[Any, ...], dtype[Any]]] – The qubit states for each time in the time span and the expectation values.

run_vqe(ansatz, hamiltonian, backend, with_gradient=True, minimizer=MinimizerScipy(method=OptimizationMethod.L_BFGS_B_smooth), initial_parameters=None, **kwargs)

Performs a black-box, state-vector-only variational quantum eigensolver simulation.

This is a wrapper over the instantiation of the AlgorithmVQE class and execution of its build() and run() methods. Most of the parameters have default values.

Parameters:

  • ansatz (GeneralAnsatz) – an ansatz object.

  • hamiltonian (QubitOperator | BaseChemistryIntegralOperator) – a Hamiltonian object.

  • backend (Backend | BaseBackendConfig) – a backend object to perform calculation with.

  • with_gradient (bool, default: True) – whether to use objective function gradient in the VQE calculation

  • minimizer (GeneralMinimizer, default: MinimizerScipy(method=OptimizationMethod.L_BFGS_B_smooth)) – variational classical minimizer to perform the parameter search.

  • initial_parameters (Optional[dict[str | Symbol, int | float | complex | Expr]], default: None) – a set of initial Ansatz parameters. If not provided, defaulted to all zeros.

  • **kwargs (Any) – Keyword arguments passed to the statevector protocol.

Returns:

AlgorithmVQE – AlgorithmVQE object after the AlgorithmVQE.build().run() method has been executed.

Examples

>>> from inquanto.express import load_h5
>>> from inquanto.states import FermionState
>>> from inquanto.spaces import FermionSpace
>>> from inquanto.ansatzes import FermionSpaceAnsatzUCCSD
>>> from pytket.extensions.qiskit import AerStateBackend
>>> hamiltonian = load_h5("h2_sto3g.h5", as_tuple=True).hamiltonian_operator.qubit_encode()
>>> backend = AerStateBackend()
>>> state = FermionState([1, 1, 0, 0])
>>> space = FermionSpace(4)
>>> ansatz = FermionSpaceAnsatzUCCSD(fermion_space=space, fermion_state=state)
>>> vqe = run_vqe(ansatz, hamiltonian, backend) 
# TIMER ...
>>> print(round(vqe.final_value, 8))
-1.13684658
save_h5_system(fname, ham, fermion_space, hf_state, **kwargs)

Save essential system information to the *.h5 file.

This function can be used both for molecular and periodic systems.

Parameters:

  • fname (str) – h5 filename to save the system to.

  • ham (FermionOperator) – fermionic hamiltonian for the system.

  • fermion_space (FermionSpace) – fermion space object for the system.

  • hf_state (FermionState) – fermionic reference state for the system.

  • **kwargs (Any) – Additional data to be saved.

Return type:

None