inquanto.express

Express drivers

class DriverGeneralizedHubbard(e=0.0, u=2.0, t=-1.0, v=0.0, n=2, ring=False)

Bases: GeneralDriver

Creates Generalized Hubbard Hamiltonian with ring and chain topology.

Parameters:

  • e (Union[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.

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

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

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

  • n (int, default: 2) – Number of sites.

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

static generate_chain(n, diagonal, off_diagonal)

Generates nearest neighbour connectivity matrix for chain topology.

Parameters:

  • n (int) – Size of the matrix.

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

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

Returns:

The nearest neighbour connectivity matrix as a sparse matrix.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

static generate_ring(n, diagonal, off_diagonal)

Generates nearest neighbour connectivity matrix for ring topology.

Parameters:

  • n (int) – Size of the matrix.

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

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

Returns:

The nearest neighbour connectivity matrix as a sparse matrix.

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.

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.

get_system()

Generates the Hubbard dimer.

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.

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[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Lattice connectivity matrix. Only the lower triangular elements are used.

generate_report(*args, **kwargs)

Generates report in a hierarchical dictionary format.

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.

class DriverIsing1D(j, h, n)

Bases: DriverIsingCustomConnectivity

Driver for a 1D, nearest-neighbour 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.

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.

class DriverIsing1DRing(j, h, n)

Bases: DriverIsingCustomConnectivity

Driver for a 1D, nearest-neighbour 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.

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.

Express functions

Data for example systems for testing.

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 (Union[str, dict[str, Any], tuple]) – An express dataset file name, or previously loaded express dataset.

Returns:

Tuple[Union[ChemistryRestrictedIntegralOperator, ChemistryUnrestrictedIntegralOperator], FermionSpace, FermionState] – Fermion Hamiltonian, Fock space, Fock state.

list_h5()

Lists the predefined h5 data files in the express module.

load_h5(name, as_tuple=False)

Loads predefined results from the express module.

Parameters:

  • name (Union[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:

Union[Dict[str, Any], Tuple] – 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:

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 normalised 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:

Union[CircuitAnsatz, Tuple[CircuitAnsatz, ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]]] – 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], default: None) – initial guess for mo_coeff.

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

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

Returns:

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 hamitlonian operator.

  • n_electron (int) – Number of electrons.

  • spin (int) – Spin.

  • guess_mo_coeff (Optional[ndarray], default: None) – Initial guess for mo_coeff.

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

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

Returns:

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[Union[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 (int, default: None)

Returns:

Tuple[List[QubitState], ...] – 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)

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 (Union[QubitOperator, BaseChemistryIntegralOperator]) – a Hamiltonian object.

  • backend (Backend) – 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[SymbolDict], default: None) – a set of initial Ansatz parameters. If not provided, defaulted to all zeros.

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 – Additional data to be saved.