inquanto.operators

InQuanto representation of quantum operators.

class ChemistryRestrictedIntegralOperator(constant, one_body, two_body, dtype=None)

Bases: BaseChemistryIntegralOperator

Handles a (restricted-orbital) chemistry integral operator.

Stores constant, one- and two-body spatial integral values following chemistry notation, two_body[p, q, r, s] = \((pq|rs)\).

Parameters:

  • constant (float) – Constant energy term, electron independent.

  • one_body (ndarray) – One-body integrals.

  • two_body (ndarray) – Two-body electron repulsion integrals (ERI).

TOLERANCE = 1e-14

Internal tolerance used when iterating over terms. Terms with magnitude smaller than this are not returned by items().

approx_equal(other, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Test for approximate equality with another instance of this class by comparing integral arrays.

Arguments are passed directly to numpy.allclose() for equality comparison - see numpy documentation for further details.

Parameters:

  • other (ChemistryRestrictedIntegralOperator) – The other operator to compare for approximate equality.

  • rtol (float, default: NUMPY_RTOL) – The relative tolerance parameter, as defined by numpy.allclose().

  • atol (float, default: NUMPY_ATOL) – The absolute tolerance parameter, as defined by numpy.allclose().

  • equal_nan (default: False) – Whether to compare NaN’s as equal, as defined by numpy.allclose().

Returns:

bool – True if other instance is approximately equal to this one, otherwise False.

astype(dtype)

Returns a copy of the current integral operator, cast to a new dtype.

Parameters:

dtype (Any) – The dtype to cast into.

Returns:

ChemistryRestrictedIntegralOperator – New integral operator with components cast to dtype.

copy()

Performs a deep copy of object.

Return type:

BaseChemistryIntegralOperator

df()

Returns a pandas.DataFrame object showing all terms in the operator.

Return type:

DataFrame

double_factorize(tol1=-1.0, tol2=None, method=DecompositionMethod.CHOLESKY, diagonalize_one_body=True, diagonalize_one_body_offset=True, combine_one_body_terms=True)

Performs explicit double factorisation (X-DF) of Hamiltonian.

The Hamiltonian can be written as \(\hat{H} = H_0 + \hat{H}_1 + \hat{S} + \hat{V}\) where \(\hat{S}+\hat{V}\) is the Coulomb interaction. \(V = \frac{1}{2}\sum_{ijkl} (ij|kl) a_i^\dagger a_j a_k^\dagger a_l\) is a reordered two-body operator and \(\hat{S}\) is a one-body offset term given by \(\hat{S} = \sum_{ij} s_{ij} a_i^\dagger a_j\) where \(s_{ij} = -\frac{1}{2}\sum_k (ik|kj)\). \(H_0\) and \(\hat{H}_1\) are the constant and one-electron terms respectively.

The first level of factorization decomposes the electron repulsion integrals tensor into the form: \((pq|rs)=\sum_t^{N_\gamma} V_{pq}^t \gamma^t V_{rs}^t\). This may be performed using an eigenvalue decomposition (method='eig'), or a pivoted, incomplete Cholesky decomposition (method="cho") (see J. Chem. Phys. 118, 9481–9484 (2003) and J. Chem. Phys. 139, 134105 (2013)). The second factorization is diagonalization of the \(V_{pq}^t\) matrix for each t: \(V_{pq}^t = \sum_u^{N_\lambda^t} U_{pu}^t \lambda_u^t U_{qu}^t\).

At the first factorization stage, truncation depends on the decomposition method. With "eig", truncation is performed by discarding eigenvalues, starting from the smallest in magnitude, until the sum of those discarded magnitudes exceeds the threshold tol1. With "cho", the decomposition is constructed iteratively until the error is less than tol1. At the second factorization level, truncation is always performed by discarding low-magnitude eigenvalues.

One-body-like terms are consolidated and diagonalized by default: \(\tilde{h}_{pq} = h_{pq} + s_{pq} = \sum_r W_{pr} \omega_r W_{qr}\). One-body diagonalization is not truncated.

Warning

This is not intended for reduction of classical memory usage, only for truncating the two-body terms of the Hamiltonian for quantum simulation.

Parameters:

  • tol1 (float, default: -1.0) – Truncation threshold for first diagonalization of ERI matrix. If negative, no truncation is performed.

  • tol2 (Optional[float], default: None) – Truncation threshold for second diagonalization of ERI matrix. If None, same as tol1. If negative, no truncation is performed.

  • method (Union[DecompositionMethod, str], default: DecompositionMethod.CHOLESKY) – Decomposition method used for the first level of factorization. "eig" for an eigenvalue decomposition, "cho" for a pivoted, incomplete Cholesky decomposition.

  • diagonalize_one_body (bool, default: True) – Whether to diagonalize the physical one-body integrals \(h_{pq}\).

  • diagonalize_one_body_offset (bool, default: True) – Whether to diagonalize the one-body offset integrals \(s_{pq}\)

  • combine_one_body_terms (bool, default: True) – Whether to consolidate the one-body and one-body offset integrals into effective one-body integrals. Requires diagonalize_one_body == diagonalize_one_body_offset.

Returns:

Union[RestrictedDoubleFactorizedHamiltonian, UnrestrictedDoubleFactorizedHamiltonian] – Hamiltonian operator storing two-body integrals in double factorized form and, optionally, diagonalized one-body integrals.

property dtype: dtype

Returns numpy data type of the two-body integral terms.

effective_potential(rdm1)

Calculates the effective Coulombic potential for a given 1-RDM.

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

ndarray – Effective potential matrix.

effective_potential_spin(rdm1)

Calculates the contribution to the effective Coulomb potential due to a spin imbalance.

This is defined as the contribution to the effective potential matrix from the difference of the alpha and beta 1-RDMs .

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

ndarray – Effective potential matrix.

energy(rdm1, rdm2=None)

Calculate total energy based on the one- and two-body reduced density matrices.

If rdm2 is not given, this method returns the mean-field energy.

Parameters:
Returns:

float – Total energy.

energy_electron_mean_field(rdm1)

Calculates the electronic energy in the mean-field approximation.

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

Tuple[float, float] – The mean-field electronic energy (one-body + two-body), and the mean-field Coulomb contribution (two-body only).

classmethod from_FermionOperator(operator, dtype=float)

Convert a two-body fermionic operator to restricted-orbital integral operator.

The one-body terms are stored in a matrix, _one_body[p, q], and the two-body terms are stored in a tensor, _two_body[p, q, r, s].

Parameters:

  • operator (FermionOperator) – Input fermionic operator.

  • dtype (default: float) – Desired term value dtype.

Returns:

ChemistryRestrictedIntegralOperator – The converted operator.

Warning

This converter assumes that operator represents a spin-restricted operator.

static from_fcidump(filename)

Generate a ChemistryRestrictedIntegralOperator object from an FCIDUMP file.

FCIDUMP files typically contain information regarding the molecular orbital integrals, number of orbitals, number of electrons, spin and spatial symmetry. Only the symmetry information is discarded by this method.

Parameters:

filename (str) – The FCIDUMP filename.

Returns:

Tuple[ChemistryRestrictedIntegralOperator, int, int, int] – A tuple containing the operator generated from the FCIDUMP file, the number of orbitals in the system, the number of electrons in the system, and the spin multiplicity of the system.

property imag: ChemistryRestrictedIntegralOperator

Extract the imaginary part of the integral operator.

Returns:

New integral operator object with only the imaginary parts of all elements remaining.

items(yield_constant=True, yield_one_body=True, yield_two_body=True)

Generates the constant, one- and two-body operator terms contained in the operator object.

Parameters:

  • yield_constant (bool, default: True) – Whether to generate a constant term.

  • yield_one_body (bool, default: True) – Whether to generate one-body terms.

  • yield_two_body (bool, default: True) – Whether to generate two-body terms.

Yields:

Next requested FermionOperatorString and constant/integral value.

Return type:

Generator[Tuple[FermionOperatorString, float], None, None]

classmethod load_h5(name)

Loads operator object from .h5 file.

Parameters:

name (Union[str, Group]) – Name of .h5 file to be loaded.

Returns:

BaseChemistryIntegralOperator – Loaded integral operator object.

norm(*args, **kwargs)

Calculates the norm of the integral operator.

Sums the norm of the constant, one-body and two-body parts using numpy.linalg.norm().

Parameters:

  • *args – Additional arguments passed to numpy.linalg.norm().

  • **kwargs – Additional keyword arguments passed to numpy.linalg.norm().

Returns:

float – Norm of this instance.

print_table()

Prints operator terms in a table format.

Return type:

None

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping class, of this instance.

This proceeds by creation of a FermionOperator class, via the to_FermionOperator() method, before mapping to a QubitOperator using the provided mapping scheme. Please see the documentation for to_FermionOperator() for finer grained control over operator generation.

Parameters:
Returns:

QubitOperator – Mapped QubitOperator object.

property real: ChemistryRestrictedIntegralOperator

Extract the real part of the integral operator.

Returns:

New integral operator object with only the real parts of all elements remaining.

rotate(rotation, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Performs an in-place unitary rotation of the chemistry integrals.

Parameters:

  • rotation (ndarray) – Unitary rotation matrix.

  • check_unitary (bool, default: True) – Whether to perform the check for unitarity of the rotation matrix.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity check.

Returns:

ChemistryRestrictedIntegralOperator – This instance after rotation.

save_h5(name)

Dumps operator object to .h5 file.

Parameters:

name (Union[str, Group]) – Destination filename of .h5 file.

Return type:

None

to_FermionOperator(yield_constant=True, yield_one_body=True, yield_two_body=True)

Converts chemistry integral operator to FermionOperator.

Parameters:

  • yield_constant (bool, default: True) – Whether to include a constant term.

  • yield_one_body (bool, default: True) – Whether to include one-body terms.

  • yield_two_body (bool, default: True) – Whether to include two-body terms.

Returns:

FermionOperator – Integral operator in general fermionic operator form.

to_compact_integral_operator(symmetry)

Converts two-body integrals into compact form.

Compacts the two-body integrals into a CompactTwoBodyIntegrals object.

Parameters:

symmetry (Union[int, str]) – Target symmetry. Four-fold symmetry (4, "4" or "s4") or eight-fold symmetry (8, "8" or "s8") are supported.

Returns:

ChemistryRestrictedIntegralOperatorCompact – Equivalent integral operator with two-body integrals stored in compact form.

two_body_iijj()

Returns pair-diagonal elements of two-body integrals, \((ii|jj)\) in chemist notation.

Returns:

ndarray – 2D array of pair-diagonal two body-integrals.

class ChemistryRestrictedIntegralOperatorCompact(constant, one_body, two_body, dtype=None)

Bases: BaseChemistryIntegralOperator

Handles a (restricted-orbital) chemistry integral operator, with integrals stored in a compact form.

Stores constant, one- and two-body spatial integral values following chemistry notation, i.e. two_body[p, q, r, s] = \((pq|rs)\). Two-body integrals are stored as a CompactTwoBodyIntegralsS4 or CompactTwoBodyIntegralsS8 object rather than a numpy.ndarray, which reduces memory load, at the expense of some operations taking longer.

Parameters:
TOLERANCE = 1e-14

Internal tolerance used when iterating over terms. Terms with magnitude smaller than this are not returned by items().

approx_equal(other, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Test for approximate equality with another instance of this class by comparing integral arrays.

Arguments are passed directly to numpy.allclose() for equality comparison - see numpy documentation for further details.

Parameters:

  • other (ChemistryRestrictedIntegralOperatorCompact) – The other operator to compare for approximate equality.

  • rtol (float, default: NUMPY_RTOL) – The relative tolerance parameter, as defined by numpy.allclose().

  • atol (float, default: NUMPY_ATOL) – The absolute tolerance parameter, as defined by numpy.allclose().

  • equal_nan (bool, default: False) – Whether to compare NaN’s as equal, as defined by numpy.allclose().

Returns:

bool – True if other instance is approximately equal to this, otherwise False.

astype(dtype)

Returns a copy of the current integral operator, cast to a new dtype.

Parameters:

dtype (Any) – The dtype to cast into.

Returns:

ChemistryRestrictedIntegralOperatorCompact – New integral operator with components cast to dtype.

copy()

Performs a deep copy of object.

Return type:

BaseChemistryIntegralOperator

df()

Returns a pandas.DataFrame object showing all terms in the operator.

Return type:

DataFrame

double_factorize(tol1=-1.0, tol2=None, method=DecompositionMethod.CHOLESKY, diagonalize_one_body=True, diagonalize_one_body_offset=True, combine_one_body_terms=True)

Performs explicit double factorisation (X-DF) of Hamiltonian.

The Hamiltonian can be written as \(\hat{H} = H_0 + \hat{H}_1 + \hat{S} + \hat{V}\) where \(\hat{S}+\hat{V}\) is the Coulomb interaction. \(V = \frac{1}{2}\sum_{ijkl} (ij|kl) a_i^\dagger a_j a_k^\dagger a_l\) is a reordered two-body operator and \(\hat{S}\) is a one-body offset term given by \(\hat{S} = \sum_{ij} s_{ij} a_i^\dagger a_j\) where \(s_{ij} = -\frac{1}{2}\sum_k (ik|kj)\). \(H_0\) and \(\hat{H}_1\) are the constant and one-electron terms respectively.

The first level of factorization decomposes the electron repulsion integrals tensor into the form: \((pq|rs)=\sum_t^{N_\gamma} V_{pq}^t \gamma^t V_{rs}^t\). This may be performed using an eigenvalue decomposition (method='eig'), or a pivoted, incomplete Cholesky decomposition (method="cho") (see J. Chem. Phys. 118, 9481–9484 (2003) and J. Chem. Phys. 139, 134105 (2013)). The second factorization is diagonalization of the \(V_{pq}^t\) matrix for each t: \(V_{pq}^t = \sum_u^{N_\lambda^t} U_{pu}^t \lambda_u^t U_{qu}^t\).

At the first factorization stage, truncation depends on the decomposition method. With "eig", truncation is performed by discarding eigenvalues, starting from the smallest in magnitude, until the sum of those discarded magnitudes exceeds the threshold tol1. With "cho", the decomposition is constructed iteratively until the error is less than tol1. At the second factorization level, truncation is always performed by discarding low-magnitude eigenvalues.

One-body-like terms are consolidated and diagonalized by default: \(\tilde{h}_{pq} = h_{pq} + s_{pq} = \sum_r W_{pr} \omega_r W_{qr}\). One-body diagonalization is not truncated.

Warning

This is not intended for reduction of classical memory usage, only for truncating the two-body terms of the Hamiltonian for quantum simulation.

Parameters:

  • tol1 (float, default: -1.0) – Truncation threshold for first diagonalization of ERI matrix. If negative, no truncation is performed.

  • tol2 (Optional[float], default: None) – Truncation threshold for second diagonalization of ERI matrix. If None, same as tol1. If negative, no truncation is performed.

  • method (Union[DecompositionMethod, str], default: DecompositionMethod.CHOLESKY) – Decomposition method used for the first level of factorization. "eig" for an eigenvalue decomposition, "cho" for a pivoted, incomplete Cholesky decomposition.

  • diagonalize_one_body (bool, default: True) – Whether to diagonalize the physical one-body integrals \(h_{pq}\).

  • diagonalize_one_body_offset (bool, default: True) – Whether to diagonalize the one-body offset integrals \(s_{pq}\)

  • combine_one_body_terms (bool, default: True) – Whether to consolidate the one-body and one-body offset integrals into effective one-body integrals. Requires diagonalize_one_body == diagonalize_one_body_offset.

Returns:

Union[RestrictedDoubleFactorizedHamiltonian, UnrestrictedDoubleFactorizedHamiltonian] – Hamiltonian operator storing two-body integrals in double factorized form and, optionally, diagonalized one-body integrals.

property dtype: dtype

Returns numpy data type of the two-body integral terms.

effective_potential(rdm1)

Calculates the effective Coulombic potential for a given 1-RDM.

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

ndarray – Effective potential matrix.

effective_potential_spin(rdm1)

Calculates the contribution to the effective Coulomb potential due to a spin imbalance.

This is defined as the contribution to the effective potential matrix from the difference of the alpha and beta 1-RDMs.

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

ndarray – Effective potential matrix.

energy(rdm1, rdm2=None)

Calculate total energy based on the one- and two-body reduced density matrices.

If rdm2 is not given, this method returns the mean-field energy.

Parameters:
Returns:

float – Total energy.

energy_electron_mean_field(rdm1)

Calculates the electronic energy in the mean-field approximation.

Parameters:

rdm1 (RestrictedOneBodyRDM) – Restricted, one-body reduced density matrix object.

Returns:

Tuple[float, float] – The mean-field electronic energy (one-body + two-body), and the mean-field Coulomb contribution (two-body only).

classmethod from_FermionOperator(operator, dtype=float, symmetry='s4')

Convert a 2-body fermionic operator to compact, restricted-orbital integral operator.

The one-body terms are stored in a matrix, _one_body[p, q], and the two-body terms are stored in a CompactTwoBodyIntegrals object, _two_body[p, q, r, s]

Parameters:

  • operator (FermionOperator) – Input fermion operator.

  • dtype (default: float) – Desired term value dtype.

  • symmetry (Union[str, int], default: "s4") – Target symmetry. Four-fold symmetry (4, "4" or "s4") or eight-fold symmetry (8, "8" or "s8") are supported.

Returns:

Output integral operator.

Warning

Currently, this converter assumes all the terms in the integral operator are represented by the aabb and bbaa blocks of fermion operator terms, and they are supposed to overwrite the (contracted) aaaa and bbbb terms - it might give faulty results if this is not the case.

property imag

Extract the imaginary part of the integral operator.

Returns:

New integral operator object with only the imaginary parts of all elements remaining.

items(yield_constant=True, yield_one_body=True, yield_two_body=True)

Generates the constant, one- and two-body operator terms contained in the operator object.

Parameters:

  • yield_constant (bool, default: True) – Whether to generate a constant term.

  • yield_one_body (bool, default: True) – Whether to generate one-body terms.

  • yield_two_body (bool, default: True) – Whether to generate two-body terms.

Yields:

Next requested FermionOperatorString and constant/integral value.

Return type:

Generator[Tuple[FermionOperatorString, float], None, None]

classmethod load_h5(name)

Loads operator object from .h5 file.

Parameters:

name (Union[str, Group]) – Name of .h5 file to be loaded.

Returns:

BaseChemistryIntegralOperator – Loaded integral operator object.

norm()

Calculates the Frobenius norm of the integral operator.

Sums the norm of the constant, one-body and two-body parts.

Returns:

Norm of integral operator.

print_table()

Prints operator terms in a table format.

Return type:

None

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping class, of this instance.

This proceeds by creation of a FermionOperator class, via the to_FermionOperator() method, before mapping to a QubitOperator using the provided mapping scheme. Please see the documentation for to_FermionOperator() for finer grained control over operator generation.

Parameters:
Returns:

QubitOperator – Mapped QubitOperator object.

property real

Extract the real part of the integral operator.

Returns:

New integral operator object with only the real parts of all elements remaining.

rotate(rotation, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Performs an in-place unitary rotation of the chemistry integrals.

Rotation must be real-valued (orthogonal) for compact integrals.

Raises:

ValueError – If dimensions of rotation matrix are not compatible with integrals.

Parameters:

  • rotation (ndarray) – Real, unitary rotation matrix.

  • check_unitary (bool, default: True) – Whether to perform the check for unitarity of the rotation matrix.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity check.

Returns:

ChemistryRestrictedIntegralOperatorCompact – This instance after rotation.

save_h5(name)

Dumps operator object to .h5 file.

Parameters:

name (Union[str, Group]) – Destination filename of .h5 file.

Return type:

None

to_FermionOperator(yield_constant=True, yield_one_body=True, yield_two_body=True)

Converts chemistry integral operator to FermionOperator.

Parameters:

  • yield_constant (bool, default: True) – Whether to include a constant term.

  • yield_one_body (bool, default: True) – Whether to include one-body terms.

  • yield_two_body (bool, default: True) – Whether to include two-body terms.

Returns:

FermionOperator – Integral operator in general fermionic operator form.

to_uncompacted_integral_operator()

Convert to a ChemistryRestrictedIntegralOperator object.

Unpacks the compact two-body integrals into a four-dimensional numpy.ndarray.

Returns:

Equivalent integral operator object with un-compacted integrals.

two_body_iijj()

Returns pair-diagonal elements of two-body integrals, \((ii|jj)\) in chemist’s notation.

Returns:

2D array of pair-diagonal two body-integrals.

class ChemistryUnrestrictedIntegralOperator(constant, one_body_aa, one_body_bb, two_body_aaaa, two_body_bbbb, two_body_aabb)

Bases: BaseChemistryIntegralOperator

Handles a (unrestricted-orbital) chemistry integral operator.

Stores constant, one- and two-body spatial integral values following chemist notation, i.e. two_body[p, q, r, s] = \((pq|rs)\)

Parameters:

  • constant (float) – Constant energy term, electron independent.

  • one_body_aa (ndarray) – One-body integrals for the alpha (a) spin channel.

  • one_body_bb (ndarray) – One-body integrals for the beta (b) spin channel.

  • two_body_aaaa (ndarray) – Two-body electron repulsion integrals (ERI) with spatial orbitals in the aaaa spin channels respectively.

  • two_body_bbbb (ndarray) – ERI with spatial orbitals in the bbbb spin channels.

  • two_body_aabb (ndarray) – ERI with spatial orbitals in the aabb spin channels. The bbaa ERI is inferred from eri_aabb[i, j, k, l] = eri_bbaa[k, l, i, j].

TOLERANCE = 1e-14

Internal tolerance used when iterating over terms. Terms with magnitude smaller than this are not returned by items().

approx_equal(other, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Test for approximate equality with another instance of this class by comparing integral arrays.

Arguments are passed directly to numpy.allclose() for equality comparison - see numpy documentation for further details.

Parameters:

  • other (ChemistryUnrestrictedIntegralOperator) – The other operator to compare for approximate equality.

  • rtol (float, default: NUMPY_RTOL) – The relative tolerance parameter, as defined by numpy.allclose().

  • atol (float, default: NUMPY_ATOL) – The absolute tolerance parameter, as defined by numpy.allclose().

  • equal_nan (bool, default: False) – Whether to compare NaN’s as equal, as defined by numpy.allclose().

Returns:

bool – True if other instance is approximately equal to this one, otherwise False.

copy()

Performs a deep copy of object.

Return type:

BaseChemistryIntegralOperator

df()

Returns a pandas.DataFrame object showing all terms in the operator.

Return type:

DataFrame

double_factorize(tol1=-1.0, tol2=None, method=DecompositionMethod.CHOLESKY, diagonalize_one_body=True, diagonalize_one_body_offset=True, combine_one_body_terms=True)

Performs explicit double factorisation (X-DF) of Hamiltonian.

The Hamiltonian can be written as \(\hat{H} = H_0 + \hat{H}_1 + \hat{S} + \hat{V}\) where \(\hat{S}+\hat{V}\) is the Coulomb interaction. \(V = \frac{1}{2}\sum_{ijkl} (ij|kl) a_i^\dagger a_j a_k^\dagger a_l\) is a reordered two-body operator and \(\hat{S}\) is a one-body offset term given by \(\hat{S} = \sum_{ij} s_{ij} a_i^\dagger a_j\) where \(s_{ij} = -\frac{1}{2}\sum_k (ik|kj)\). \(H_0\) and \(\hat{H}_1\) are the constant and one-electron terms respectively.

The first level of factorization decomposes the electron repulsion integrals tensor into the form: \((pq|rs)=\sum_t^{N_\gamma} V_{pq}^t \gamma^t V_{rs}^t\). This may be performed using an eigenvalue decomposition (method='eig'), or a pivoted, incomplete Cholesky decomposition (method="cho") (see J. Chem. Phys. 118, 9481–9484 (2003) and J. Chem. Phys. 139, 134105 (2013)). The second factorization is diagonalization of the \(V_{pq}^t\) matrix for each t: \(V_{pq}^t = \sum_u^{N_\lambda^t} U_{pu}^t \lambda_u^t U_{qu}^t\).

At the first factorization stage, truncation depends on the decomposition method. With "eig", truncation is performed by discarding eigenvalues, starting from the smallest in magnitude, until the sum of those discarded magnitudes exceeds the threshold tol1. With "cho", the decomposition is constructed iteratively until the error is less than tol1. At the second factorization level, truncation is always performed by discarding low-magnitude eigenvalues.

One-body-like terms are consolidated and diagonalized by default: \(\tilde{h}_{pq} = h_{pq} + s_{pq} = \sum_r W_{pr} \omega_r W_{qr}\). One-body diagonalization is not truncated.

Warning

This is not intended for reduction of classical memory usage, only for truncating the two-body terms of the Hamiltonian for quantum simulation.

Parameters:

  • tol1 (float, default: -1.0) – Truncation threshold for first diagonalization of ERI matrix. If negative, no truncation is performed.

  • tol2 (Optional[float], default: None) – Truncation threshold for second diagonalization of ERI matrix. If None, same as tol1. If negative, no truncation is performed.

  • method (Union[DecompositionMethod, str], default: DecompositionMethod.CHOLESKY) – Decomposition method used for the first level of factorization. "eig" for an eigenvalue decomposition, "cho" for a pivoted, incomplete Cholesky decomposition.

  • diagonalize_one_body (bool, default: True) – Whether to diagonalize the physical one-body integrals \(h_{pq}\).

  • diagonalize_one_body_offset (bool, default: True) – Whether to diagonalize the one-body offset integrals \(s_{pq}\)

  • combine_one_body_terms (bool, default: True) – Whether to consolidate the one-body and one-body offset integrals into effective one-body integrals. Requires diagonalize_one_body == diagonalize_one_body_offset.

Returns:

Union[RestrictedDoubleFactorizedHamiltonian, UnrestrictedDoubleFactorizedHamiltonian] – Hamiltonian operator storing two-body integrals in double factorized form and, optionally, diagonalized one-body integrals.

effective_potential(rdm1)

Calculates the effective Coulombic potential for a given 1-RDM.

Parameters:

rdm1 (UnrestrictedOneBodyRDM) – Unrestricted, one-body reduced density matrix.

Returns:

List[ndarray] – Effective potentials for the alpha and beta spin channels.

energy(rdm1, rdm2=None)

Calculate total energy based on the one- and two-body reduced density matrices.

If rdm2 is not given, this method returns the mean-field energy.

Parameters:
Returns:

float – Total energy.

energy_electron_mean_field(rdm1)

Calculates the electronic energy in the mean-field approximation.

Parameters:

rdm1 (UnrestrictedOneBodyRDM) – Unrestricted, one-body reduced density matrix object.

Returns:

Tuple[float, float] – The mean-field electronic energy (one-body + two-body), and the mean-field Coulomb contribution (two-body only).

classmethod from_FermionOperator(operator)

Convert a 2-body fermionic operator to unrestricted-orbital integral operator.

The one-body terms are stored in matrices, _one_body_aa[p, q] and _one_body_bb, and the two-body terms are stored in tensors, _two_body_aaaa[p, q, r, s], _two_body_bbbb[...], _two_body_aabb[...].

Parameters:

operator (FermionOperator) – Input fermion operator.

Returns:

ChemistryUnrestrictedIntegralOperator – The converted operator.

Warning

The same-spin (aaaa and bbbb) blocks returned are contracted - this is fine for use in quantum chemistry calculations with density matrices having unit elements (e.g. Slater determinants) - for other purposes one should be careful.

items(yield_constant=True, yield_one_body=True, yield_two_body=True)

Generates the constant, one- and two-body operator terms contained in the operator object.

Parameters:

  • yield_constant (bool, default: True) – Whether to generate a constant term.

  • yield_one_body (bool, default: True) – Whether to generate one-body terms.

  • yield_two_body (bool, default: True) – Whether to generate two-body terms.

Yields:

Next requested FermionOperatorString and constant/integral value.

Return type:

Generator[Tuple[FermionOperatorString, float], None, None]

classmethod load_h5(name)

Loads operator object from .h5 file.

Parameters:

name (Union[str, Group]) – Name of .h5 file to be loaded.

Returns:

BaseChemistryIntegralOperator – Loaded integral operator object.

print_table()

Prints operator terms in a table format.

Return type:

None

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping class, of this instance.

This proceeds by creation of a FermionOperator class, via the to_FermionOperator() method, before mapping to a QubitOperator using the provided mapping scheme. Please see the documentation for to_FermionOperator() for finer grained control over operator generation.

Parameters:
Returns:

QubitOperator – Mapped QubitOperator object.

rotate(rotation_aa, rotation_bb, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Performs an in-place unitary rotation of the chemistry integrals.

Each spin block is rotated separately.

Parameters:

  • rotation_aa (ndarray) – Unitary rotation matrix for the alpha spin block.

  • rotation_bb (ndarray) – Unitary rotation matrix for the beta spin block.

  • check_unitary (bool, default: True) – Whether to perform the check for unitarity of the rotation matrices.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity checks.

Returns:

ChemistryUnrestrictedIntegralOperator – This instance after rotation.

save_h5(name)

Dumps operator object to .h5 file.

Parameters:

name (Union[str, Group]) – Destination filename of .h5 file.

Return type:

None

to_FermionOperator(yield_constant=True, yield_one_body=True, yield_two_body=True)

Converts chemistry integral operator to FermionOperator.

Parameters:

  • yield_constant (bool, default: True) – Whether to include a constant term.

  • yield_one_body (bool, default: True) – Whether to include one-body terms.

  • yield_two_body (bool, default: True) – Whether to include two-body terms.

Returns:

FermionOperator – Integral operator in general fermionic operator form.

to_compact_integral_operator(symmetry)

Converts two-body integrals into compact form.

Compacts the two-body integrals into a CompactTwoBodyIntegrals object.

Parameters:

symmetry (Union[int, str]) – Target symmetry. Four-fold symmetry (4, "4" or "s4") or eight-fold symmetry (8, "8" or "s8") are supported.

Returns:

ChemistryUnrestrictedIntegralOperatorCompact – Equivalent integral operator with two-body integrals stored in compact form.

class ChemistryUnrestrictedIntegralOperatorCompact(constant, one_body_aa, one_body_bb, two_body_aaaa, two_body_bbbb, two_body_aabb, dtype=None)

Bases: BaseChemistryIntegralOperator

Handles a (unrestricted-orbital) chemistry integral operator, with integrals stored in a compact form.

Stores constant, one- and two-body spatial integral values following chemistry notation, i.e. two_body[p, q, r, s] = \((pq|rs)\). Two-body integrals are stored as a CompactTwoBodyIntegralsS4 or CompactTwoBodyIntegralsS8 object rather than a numpy.ndarray, which reduces memory load, at the expense of some operations taking longer.

Note

The symmetry class instance attribute is determined by the symmetry of the two_body_aaaa input. The aabb and bbaa integral tensors are incompatible with s8 symmetry.

Parameters:

  • constant (float) – Constant energy term, electron independent.

  • one_body_aa (ndarray) – One-body energy integrals for the alpha (a) spin channel.

  • one_body_bb (ndarray) – One-body energy integrals for the beta (b) spin channel.

  • two_body_aaaa (Union[CompactTwoBodyIntegralsS4, CompactTwoBodyIntegralsS8]) – Two-body electron repulsion integrals (ERI) with spatial orbitals in the aaaa spin channels respectively.

  • two_body_bbbb (Union[CompactTwoBodyIntegralsS4, CompactTwoBodyIntegralsS8]) – ERI with spatial orbitals in the bbbb spin channels.

  • two_body_aabb (CompactTwoBodyIntegralsS4) – ERI with spatial orbitals in the aabb spin channels. The bbaa ERI is inferred from eri_aabb[i, j, k, l] = eri_bbaa[k, l, i, j].

TOLERANCE = 1e-14

Internal tolerance used when iterating over terms. Terms with magnitude smaller than this are not returned by items().

approx_equal(other, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Test for approximate equality with another instance of this class by comparing integral arrays.

Arguments are passed directly to numpy.allclose() for equality comparison - see numpy documentation for further details.

Parameters:

  • other (ChemistryUnrestrictedIntegralOperatorCompact) – The other operator to compare for approximate equality.

  • rtol (float, default: NUMPY_RTOL) – The relative tolerance parameter, as defined by numpy.allclose().

  • atol (float, default: NUMPY_ATOL) – The absolute tolerance parameter, as defined by numpy.allclose().

  • equal_nan (bool, default: False) – Whether to compare NaN’s as equal, as defined by numpy.allclose().

Returns:

bool – True if other instance is approximately equal to this, otherwise False.

copy()

Performs a deep copy of object.

Return type:

BaseChemistryIntegralOperator

df()

Returns a pandas.DataFrame object showing all terms in the operator.

Return type:

DataFrame

double_factorize(tol1=-1.0, tol2=None, method=DecompositionMethod.CHOLESKY, diagonalize_one_body=True, diagonalize_one_body_offset=True, combine_one_body_terms=True)

Performs explicit double factorisation (X-DF) of Hamiltonian.

The Hamiltonian can be written as \(\hat{H} = H_0 + \hat{H}_1 + \hat{S} + \hat{V}\) where \(\hat{S}+\hat{V}\) is the Coulomb interaction. \(V = \frac{1}{2}\sum_{ijkl} (ij|kl) a_i^\dagger a_j a_k^\dagger a_l\) is a reordered two-body operator and \(\hat{S}\) is a one-body offset term given by \(\hat{S} = \sum_{ij} s_{ij} a_i^\dagger a_j\) where \(s_{ij} = -\frac{1}{2}\sum_k (ik|kj)\). \(H_0\) and \(\hat{H}_1\) are the constant and one-electron terms respectively.

The first level of factorization decomposes the electron repulsion integrals tensor into the form: \((pq|rs)=\sum_t^{N_\gamma} V_{pq}^t \gamma^t V_{rs}^t\). This may be performed using an eigenvalue decomposition (method='eig'), or a pivoted, incomplete Cholesky decomposition (method="cho") (see J. Chem. Phys. 118, 9481–9484 (2003) and J. Chem. Phys. 139, 134105 (2013)). The second factorization is diagonalization of the \(V_{pq}^t\) matrix for each t: \(V_{pq}^t = \sum_u^{N_\lambda^t} U_{pu}^t \lambda_u^t U_{qu}^t\).

At the first factorization stage, truncation depends on the decomposition method. With "eig", truncation is performed by discarding eigenvalues, starting from the smallest in magnitude, until the sum of those discarded magnitudes exceeds the threshold tol1. With "cho", the decomposition is constructed iteratively until the error is less than tol1. At the second factorization level, truncation is always performed by discarding low-magnitude eigenvalues.

One-body-like terms are consolidated and diagonalized by default: \(\tilde{h}_{pq} = h_{pq} + s_{pq} = \sum_r W_{pr} \omega_r W_{qr}\). One-body diagonalization is not truncated.

Warning

This is not intended for reduction of classical memory usage, only for truncating the two-body terms of the Hamiltonian for quantum simulation.

Parameters:

  • tol1 (float, default: -1.0) – Truncation threshold for first diagonalization of ERI matrix. If negative, no truncation is performed.

  • tol2 (Optional[float], default: None) – Truncation threshold for second diagonalization of ERI matrix. If None, same as tol1. If negative, no truncation is performed.

  • method (Union[DecompositionMethod, str], default: DecompositionMethod.CHOLESKY) – Decomposition method used for the first level of factorization. "eig" for an eigenvalue decomposition, "cho" for a pivoted, incomplete Cholesky decomposition.

  • diagonalize_one_body (bool, default: True) – Whether to diagonalize the physical one-body integrals \(h_{pq}\).

  • diagonalize_one_body_offset (bool, default: True) – Whether to diagonalize the one-body offset integrals \(s_{pq}\)

  • combine_one_body_terms (bool, default: True) – Whether to consolidate the one-body and one-body offset integrals into effective one-body integrals. Requires diagonalize_one_body == diagonalize_one_body_offset.

Returns:

Union[RestrictedDoubleFactorizedHamiltonian, UnrestrictedDoubleFactorizedHamiltonian] – Hamiltonian operator storing two-body integrals in double factorized form and, optionally, diagonalized one-body integrals.

effective_potential(rdm1)

Calculates the effective Coulombic potential for a given 1-RDM.

Parameters:

rdm1 (UnrestrictedOneBodyRDM) – Unrestricted, one-body reduced density matrix.

Returns:

List[ndarray] – Effective potentials for the alpha and beta spin channels.

energy(rdm1, rdm2=None)

Calculate total energy based on the one- and two-body reduced density matrices.

If rdm2 is not given, this method returns the mean-field energy.

Parameters:
Returns:

float – Total energy.

energy_electron_mean_field(rdm1)

Calculates the electronic energy in the mean-field approximation.

Parameters:

rdm1 (UnrestrictedOneBodyRDM) – Unrestricted, one-body reduced density matrix object.

Returns:

Tuple[float, float] – The mean-field electronic energy (one-body + two-body), and the mean-field Coulomb contribution (two-body only).

classmethod from_FermionOperator(operator, symmetry='s4')

Convert a 2-body fermionic operator to unrestricted-orbital integral operator.

The one-body terms are stored in matrices, _one_body_aa[p, q] and _one_body_bb, and the two-body terms are stored in CompactTwoBodyIntegrals objects, _two_body_aaaa[p, q, r, s], _two_body_bbbb[...], _two_body_aabb[...].

Parameters:

  • operator (FermionOperator) – Input fermion operator.

  • symmetry (Union[str, int], default: "s4") – Target symmetry. Four-fold symmetry (4, "4" or "s4") or eight-fold symmetry (8, "8" or "s8") are supported.

Returns:

ChemistryUnrestrictedIntegralOperatorCompact – Output integral operator.

Warning

The same-spin (aaaa and bbbb) blocks returned are contracted - this is fine for use in quantum chemistry calculations with density matrices having unit elements (e.g. Slater determinants) - for other purposes one should be careful.

items(yield_constant=True, yield_one_body=True, yield_two_body=True)

Generates the constant, one- and two-body operator terms contained in the operator object.

Parameters:

  • yield_constant (bool, default: True) – Whether to generate a constant term.

  • yield_one_body (bool, default: True) – Whether to generate one-body terms.

  • yield_two_body (bool, default: True) – Whether to generate two-body terms.

Yields:

Next requested FermionOperatorString and constant/integral value.

Return type:

Generator[Tuple[FermionOperatorString, float], None, None]

classmethod load_h5(name)

Loads operator object from .h5 file.

Parameters:

name (Union[str, Group]) – Name of .h5 file to be loaded.

Returns:

BaseChemistryIntegralOperator – Loaded integral operator object.

print_table()

Prints operator terms in a table format.

Return type:

None

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping class, of this instance.

This proceeds by creation of a FermionOperator class, via the to_FermionOperator() method, before mapping to a QubitOperator using the provided mapping scheme. Please see the documentation for to_FermionOperator() for finer grained control over operator generation.

Parameters:
Returns:

QubitOperator – Mapped QubitOperator object.

rotate(rotation_aa, rotation_bb, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Performs an in-place unitary rotation of the chemistry integrals.

Each spin block is rotated separately. Rotation must be real-valued (orthogonal) for compact integrals.

Parameters:

  • rotation_aa (ndarray) – Real, unitary rotation matrix for the alpha spin basis.

  • rotation_bb (ndarray) – Real, unitary rotation matrix for the beta spin basis.

  • check_unitary (bool, default: True) – Whether to perform the check for unitarity of the rotation matrices.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity checks.

Returns:

ChemistryUnrestrictedIntegralOperatorCompact – This instance after rotation.

save_h5(name)

Dumps operator object to .h5 file.

Parameters:

name (Union[str, Group]) – Destination filename of .h5 file.

Return type:

None

to_FermionOperator(yield_constant=True, yield_one_body=True, yield_two_body=True)

Converts chemistry integral operator to FermionOperator.

Parameters:

  • yield_constant (bool, default: True) – Whether to include a constant term.

  • yield_one_body (bool, default: True) – Whether to include one-body terms.

  • yield_two_body (bool, default: True) – Whether to include two-body terms.

Returns:

FermionOperator – Integral operator in general fermionic operator form.

to_uncompacted_integral_operator()

Convert to a ChemistryUnrestrictedIntegralOperator object.

Unpacks the compact two-body integrals into a four-dimensional numpy.ndarray.

Returns:

ChemistryUnrestrictedIntegralOperator – Equivalent integral operator object with un-compacted integrals.

class CompactTwoBodyIntegralsS4(compact_array)

Bases: BaseCompactTwoBodyIntegrals

Stores a two-body integral tensor in s4 symmetry reduced form.

Allows simple, 4-indexed [i,j,k,l] array-like access through index transformation.

Parameters:

compact_array (ndarray) – Two-body integrals in a four-fold symmetry-reduced form. A numpy.ndarray with shape \((n_{\text{pair}_{ij}}, n_{\text{pair}_{kl}}\)) where \(n_\text{pair} = n_{\text{orb}} (n_{\text{orb}} + 1) / 2\). This array may be rectangular to due to different numbers of alpha/beta spin orbitals in the \(h_{aabb}\) ERI tensor in an unrestricted spin picture.

astype(dtype)

Returns a copy of the current compact integrals, with the compact array cast to a new type.

Parameters:

dtype (Any) – The numpy dtype to cast into.

Returns:

CompactTwoBodyIntegralsS4 – New compact integrals object with compact array cast to the given dtype.

static check_s4_symmetry(uncompact_array, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Tests whether the input ERI tensor has four-fold (s4) index symmetries.

Checks for symmetries under index swaps \(i \leftrightarrow j\) and \(k \leftrightarrow l\).

Parameters:

  • uncompact_array (ndarray) – Four-dimensional ERI tensor.

  • rtol (float, default: NUMPY_RTOL) – Relative tolerance.

  • atol (float, default: NUMPY_ATOL) – Absolute tolerance.

  • equal_nan (bool, default: False) – Whether to compare NaN’s as equal.

Returns:

bool – True if the input array has s4 symmetry, False otherwise.

property dtype: dtype

Returns numpy data type of the compact array.

classmethod from_uncompacted_integrals(two_body, symmetry, check_symmetry=False, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Builds a compact integrals object from an uncompacted array of two body integrals (a rank-4 tensor).

Parameters:

  • two_body (ndarray) – 4D array.

  • symmetry (Union[str, int]) – Code to specify target symmetry. Uses the same convention as pyscf. Currently supports s4 and s8 symmetry.

  • check_symmetry (bool, default: False) – Whether the input array should be checked for the requested symmetry.

  • rtol (float, default: NUMPY_RTOL) – Relative tolerance on symmetry checks.

  • atol (float, default: NUMPY_ATOL) – Absolute tolerance.

  • equal_nan (bool, default: False) – Whether to compare NaN values as equal.

Returns:

Union[CompactTwoBodyIntegralsS4, CompactTwoBodyIntegralsS8] – Object containing the same information as the input array in a compact form.

property imag: CompactTwoBodyIntegralsS4

Extract the imaginary part of the two-body integrals.

Returns:

New compact object containing only the imaginary part of the integrals.

static pairs(n_orb)

Yields unique index pairs, and their pair index.

Does not return multiple equivalent pairs i.e. {2, 1} will appear, but {1, 2} will not.

Parameters:

n_orb (int) – Number of orbitals over which pairs will be iterated.

Yields:

The next pair index, first orbital index, and second orbital index.

Return type:

Iterator[Tuple[int, int, int]]

property real: CompactTwoBodyIntegralsS4

Extract the real part of the two-body integrals.

Returns:

New compact object containing only the real part of the integrals.

rotate(u_ij, u_kl=None)

Perform a rotation of the compact two-body integrals.

Parameters:

  • u_ij (ndarray) – A real, orthogonal matrix of dimensions (\(n_{\text{orb}_{ij}}\), \(n_{\text{orb}_{ij}}\)). For rotating the first two indices of the two-body integrals tensor.

  • u_kl (Optional[ndarray], default: None) – A real, orthogonal matrix of dimensions (\(n_{\text{orb}_{kl}}\), \(n_{\text{orb}_{kl}}\)). For rotating the second two indices of the two-body integrals tensor.

Return type:

None

property shape: Tuple[int, int, int, int]

The shape of the corresponding rank-4 tensor.

Returns:

A tuple containing the shape \((n_p, n_q, n_r, n_s)\) of the two body tensor \((pq|rs)\).

class CompactTwoBodyIntegralsS8(compact_array)

Bases: BaseCompactTwoBodyIntegrals

Stores a two-body integral tensor in s8 symmetry reduced form.

Allows simple, 4-indexed [i,j,k,l] array-like access through index transformation.

Note

This symmetry class can only be used for ERI tensors that describe orbitals with the same spin i.e. the restricted spin ERI tensor, or the aaaa and bbbb unrestricted ERI tensors. It cannot be used for the aabb unrestricted tensor, because that block does not respect \(ij \leftrightarrow kl\) swap symmetry.

Parameters:

compact_array (ndarray) – Two-body integrals in an eight-fold symmetry-reduced form. A numpy.ndarray with shape \((n_{pp})\) where \(n_{pp} = n_\text{pair} (n_\text{pair} + 1) / 2\) and \(n_\text{pair} = n_{\text{orb}} (n_{\text{orb}} + 1) / 2.\)

astype(dtype)

Returns a copy of the current compact integrals, with the compact array cast to a new type.

Parameters:

dtype (Any) – The numpy dtype to cast into.

Returns:

CompactTwoBodyIntegralsS8 – New compact integrals object with compact array cast to the given dtype.

static check_s8_symmetry(uncompact_array, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Tests whether the input ERI tensor has eight-fold (s8) index symmetries.

Checks for symmetries under index swaps \(i \leftrightarrow j\) and \(k \leftrightarrow l\), and pair index swaps \(ij \leftrightarrow kl\).

Parameters:

  • uncompact_array (ndarray) – Four-dimensional ERI tensor.

  • rtol (float, default: NUMPY_RTOL) – Relative tolerance.

  • atol (float, default: NUMPY_ATOL) – Absolute tolerance.

  • equal_nan (bool, default: False) – Whether to compare NaN’s as equal.

Returns:

bool – True if the input array has s8 symmetry, false otherwise.

property dtype: dtype

Returns numpy data type of the compact array.

classmethod from_uncompacted_integrals(two_body, symmetry, check_symmetry=False, rtol=NUMPY_RTOL, atol=NUMPY_ATOL, equal_nan=False)

Builds a compact integrals object from an uncompacted array of two body integrals (a rank-4 tensor).

Parameters:

  • two_body (ndarray) – 4D array.

  • symmetry (Union[str, int]) – Code to specify target symmetry. Uses the same convention as pyscf. Currently supports s4 and s8 symmetry.

  • check_symmetry (bool, default: False) – Whether the input array should be checked for the requested symmetry.

  • rtol (float, default: NUMPY_RTOL) – Relative tolerance on symmetry checks.

  • atol (float, default: NUMPY_ATOL) – Absolute tolerance.

  • equal_nan (bool, default: False) – Whether to compare NaN values as equal.

Returns:

Union[CompactTwoBodyIntegralsS4, CompactTwoBodyIntegralsS8] – Object containing the same information as the input array in a compact form.

property imag: CompactTwoBodyIntegralsS8

Extract the imaginary part of the two-body integrals.

Returns:

New compact object containing only the imaginary part of the integrals.

static pairs(n_orb)

Yields unique index pairs, and their pair index.

Does not return multiple equivalent pairs i.e. {2, 1} will appear, but {1, 2} will not.

Parameters:

n_orb (int) – Number of orbitals over which pairs will be iterated.

Yields:

The next pair index, first orbital index, and second orbital index.

Return type:

Iterator[Tuple[int, int, int]]

property real: CompactTwoBodyIntegralsS8

Extract the real part of the two-body integrals.

Returns:

New compact object containing only the real part of the integrals.

rotate(u)

Perform a rotation of the compact two-body integrals.

Parameters:

u (ndarray) – A real, orthogonal matrix of dimensions (\(n_{\text{orb}}\), \(n_{\text{orb}}\)).

Return type:

None

property shape: Tuple[int, int, int, int]

The shape of the corresponding rank-4 tensor.

Returns:

A tuple containing the shape \((n_p, n_q, n_r, n_s)\) of the two body tensor \((pq|rs)\).

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

Bases: Enum

Methods for factorization of two electron integrals tensor.

CHOLESKY = 'cho'
EIG = 'eig'
class DiagonalizedOneBodyIntegrals(eigenvalues, eigenvectors)

Bases: object

Stores the eigenvalue decomposition of a hermitian square matrix.

Eigenvalue decomposition given by \(h_{pq} = \sum_r W_{rp} \omega_r W_{rq}\). Used for storing diagonalized one-body and one-body offset integrals.

Parameters:

  • eigenvalues – Eigenvalues of integral matrix. Given by \(\omega_r\) above.

  • eigenvectors – Eigenvector matrix. Each row is an eigenvector of the integral matrix. Given by \(W_{rp}\) above.

get_element(i, j)

Return the one-body integral \(h_{ij}\).

Parameters:

  • i (int) – Spatial orbital index.

  • j (int) – Spatial orbital index.

Returns:

float – One-body integral.

get_full()

Return all one-body integrals.

Multiplies out eigenvalues decomposition to recover one-body integrals.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – One-body integrals matrix.

property n_orb: int

Returns the number of orbitals.

class DoubleFactorizedTwoBodyIntegrals(rotation_matrices, outer_params=None, inner_params=None, core_tensor_as_array=None)

Bases: object

Stores the electron repulsion integral (ERI) tensor in double factorized form.

Assumes the following structure: First factorization is given by \((pq|rs)=\sum_t^{N_\gamma} V_{pq}^t \gamma^t V_{rs}^t\), which may be from an eigenvalue decomposition or LDLt/Cholesky decomposition. Second factorization is diagonalization of the \(V_{pq}^t\) matrix for each t: \(V_{pq}^t = \sum_u^{N_\lambda^t} U_{up}^t \lambda_u^t U_{uq}^t\).

Parameters:

  • rotation_matrices (List[ndarray[tuple[int, ...], dtype[float]]]) – Eigenvector matrices of second decomposition, where each row is an eigenvector. Given by \(U_{up}^t\) above, where \(t\) is the list index.

  • outer_params (Optional[ndarray[tuple[int, ...], dtype[float]]], default: None) – Eigenvalues/Cholesky factors. Given by \(\gamma^t\) above. Used to define the core tensor \(Z_{uv}^t = \lambda_u^t \gamma^t \lambda_v^t\) as an XDFCoreTensor object.

  • inner_params (Optional[List[ndarray[tuple[int, ...], dtype[float]]]], default: None) – Eigenvalues of second decomposition. Given by \(\lambda_u^t\) above, where \(t\) is the list index. Used to define the core tensor \(Z_{uv}^t = \lambda_u^t \gamma^t \lambda_v^t\) as an XDFCoreTensor object.

  • core_tensor_as_array (Optional[ndarray[tuple[int, ...], dtype[float]]], default: None) – The ‘Core tensor’ as a numpy array. If provided, the outer_params and inner_params arguments are ignored.

get_element(i, j, k, l)

Calculates the electron repulsion integral \((ij|kl)\) in chemistry notation.

\((ij|kl) = \sum_t^{N_\gamma}\gamma^t\sum_{uv}^{N_\lambda^t} U_{up}^t U_{uq}^t \lambda_u^t \lambda_v^t U_{vr}^t U_{vs}^t\).

Parameters:

  • i (int) – Orbital index.

  • j (int) – Orbital index.

  • k (int) – Orbital index.

  • l (int) – Orbital index.

Returns:

float – Electron repulsion integral.

get_full()

Return all two-body integrals.

Multiplies out both levels of decomposition for all elements to recover full tensor.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – Full ERI tensor.

class FCIDumpRestricted

Bases: object

This class reads FCIDUMP files and facilitates transformations to native InQuanto objects.

Symmetry information is not extracted from the FCIDUMP files. To be used in InQuanto, symmetry information should be passed by the user to the relevant space object. The vanilla information is, however, stored in the specification attribute, so a user can map from FCIDUMP integer values to irrep labels using their own code.

Notes

Currently this functionality is tested against pyscf, psi4 and nwchem FCIDUMP files for restricted systems only. User experience may differ when using this with files generated by packages not listed here.

Parameters:

filename – The name of the FCIDUMP file to be handled by the object.

get_system_specification()

Read the system specification block of the FCIDUMP file and process the contents into a dictionary.

Parameters:

filename – The name of the FCIDUMP file.

Returns:

Dict – A dictionary where each key is a named element of the system specification block.

load(filename)

Load the contents of the FCIDUMP file in one IO operation.

This method populates the constant, one_body_list, and two_body_list attributes.

Parameters:

filename (str) – The filename of the file to be read.

Return type:

None

one_body_to_array()

Unpack the one-body data into a \(N\times N\) matrix, where \(N\) is the number of spatial orbitals.

Elements which are permutationally equivalent to those in the FCIDUMP file are filled with the appropriate value.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The one-electron integrals as a matrix, as read from the FCIDUMP file.

to_ChemistryRestrictedIntegralOperator()

Generate a ChemistryRestrictedIntegralOperator object from the provided file.

The integrals from the file are unpacked and distributed into the full \(N\times N\) one-body matrix and \(N\times N\times N\times N\) two-body tensor, where \(N\) is the number of spatial orbitals.

Parameters:

filename – The name of the FCIDUMP file.

Returns:

ChemistryRestrictedIntegralOperator – A ChemistryRestrictedIntegralOperator object corresponding to the integrals contained in the FCIDUMP file represented by this instance.

to_arrays()

Transform the one- and two-body data into their unpacked array forms.

Chemist notation is followed, and permutationally equivalent elements to those in the FCIDUMP file are filled.

Returns:

Tuple[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]] – The one- and two-body integral arrays as a tuple.

two_body_to_tensor()

Unpack the one-body data into an \(N\times N\times N\times N\) tensor, where \(N\) is the number of spatial orbitals.

Elements which are permutationally equivalent to those in the FCIDUMP file are filled with the appropriate value.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The two-electron integrals as a tensor, as read from the FCIDUMP file.

write(filename, constant, one_body, two_body, norb, nelec, multiplicity, orbsym=None, isym=None, tolerance=CHEMISTRY_OPERATOR_TOLERANCE)

Write an FCIDUMP file corresponding to the provided constant, one body and two body quantities.

Parameters:

  • filename (str) – The name of the file to write the FCIDUMP to.

  • constant (float) – The constant term of the Hamiltonian.

  • one_body (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The spatial orbital, one-body integrals as a numpy array.

  • two_body (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The spatial orbital, two-body integrals as a numpy array.

  • norb (int) – The number of spatial orbitals in the system.

  • nelec (int) – The number of electrons in the system.

  • multiplicity (int) – The spin multiplicity of the system.

  • orbsym (Optional[List[int]], default: None) – The integer value of the irreps of the spatial orbitals.

  • isym (Optional[int], default: None) – The integer value of the point group.

  • tolerance (float, default: CHEMISTRY_OPERATOR_TOLERANCE) – Write integrals to the file with a value greater than this number.

Return type:

None

class FCIDumpUnrestricted(spin_index_format='minor')

Bases: object

This class reads FCIDUMP files and facilitates transformations to native InQuanto objects for unrestricted systems.

It is designed to handle cases where \(N_{\text{spinorb}} = 2 \times N_{\text{spatial}}\).

Notes

Currently this functionality is tested against pyscf, psi4 and nwchem FCIDUMP files for unrestricted systems. User experience may differ when using this with files generated by packages not listed here.

Parameters:

  • filename – The name of the FCIDUMP file to be handled by the object.

  • spin_index_format (str, default: "minor") – The format assumed in encoding both spatial and spin index data into the indices of the FCIDUMP file.

  • basis (Where M denotes to the number of spatial orbitals in the) –

    • ‘block’: Integrals are spatial orbital indexed in the range [1, M], with spin indices determined by the block in

    which the integral occurs. The boundaries of these blocks are indicated by the “block delimiter” line 0.0 0 0 0 0. The ordering of the spin blocks is (aa|aa), (bb|bb), (aa|bb), (a|h|a), (b|h|b). - ‘minor’: Integrals are spin-orbital indexed in the range [1, 2M], in which the `i`th odd index is the alpha spin-orbital index of the `i`th spatial orbital, and the `i`th even index is the beta spin-orbital index of the `i`th spatial orbital. - ‘major’: Integrals are spin-orbital indexed in the range [1, 2M], with the `i`th index in the range [1, M] indexing the alpha spin-orbital of the `i`th spatial orbital, and the `i`th index in the range [M+1, 2M] indexing the beta spin-orbital of the `i`th spatial orbital.

  • follows (the schemes corresponding to each spin_index_format are as) –

    • ‘block’: Integrals are spatial orbital indexed in the range [1, M], with spin indices determined by the block in

    which the integral occurs. The boundaries of these blocks are indicated by the “block delimiter” line 0.0 0 0 0 0. The ordering of the spin blocks is (aa|aa), (bb|bb), (aa|bb), (a|h|a), (b|h|b). - ‘minor’: Integrals are spin-orbital indexed in the range [1, 2M], in which the `i`th odd index is the alpha spin-orbital index of the `i`th spatial orbital, and the `i`th even index is the beta spin-orbital index of the `i`th spatial orbital. - ‘major’: Integrals are spin-orbital indexed in the range [1, 2M], with the `i`th index in the range [1, M] indexing the alpha spin-orbital of the `i`th spatial orbital, and the `i`th index in the range [M+1, 2M] indexing the beta spin-orbital of the `i`th spatial orbital.

Notes

This class supports two types of symmetries: - Four-fold symmetry (4, "4" or "s4") - Eight-fold symmetry (8, "8" or "s8") The default symmetry type is "s8".

get_system_specification()

Read the system specification block of the FCIDUMP file and process the contents into a dictionary.

Parameters:

filename – The name of the FCIDUMP file.

Returns:

dict – A dictionary where each key is a named element of the system specification block.

load(filename)

Load the contents of the FCIDUMP file in one IO operation.

This method populates the constant, one_body_list, and two_body_list attributes.

Parameters:

filename (str) – The filename of the file to be read.

Return type:

None

one_body_to_array()

Unpack the one-body data into a \(N\times N\) matrix, where \(N\) is the number of spatial orbitals.

Elements which are permutationally equivalent to those in the FCIDUMP file are filled with the appropriate value.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The one-electron integrals as a matrix, as read from the FCIDUMP file.

to_ChemistryUnrestrictedIntegralOperator()

Generate a ChemistryUnrestrictedIntegralOperator object from the provided file.

The integrals from the file are unpacked and distributed into the full \(N\times N\) one-body matrix and \(N\times N\times N\times N\) two-body tensor, where \(N\) is the number of spatial orbitals.

Parameters:

filename – The name of the FCIDUMP file.

Returns:

ChemistryUnrestrictedIntegralOperator – A ChemistryUnrestrictedIntegralOperator object corresponding to the integrals contained in the FCIDUMP file represented by this instance.

to_arrays()

Transform the one- and two-body data into their unpacked array forms.

Chemist notation is followed, and permutationally equivalent elements to those in the FCIDUMP file are filled.

Returns:

Tuple[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]] – The one- and two-body integral arrays as a tuple.

two_body_to_tensor()

Unpack the one-body data into an \(N\times N\times N\times N\) tensor, where \(N\) is the number of spatial orbitals.

Elements which are permutationally equivalent to those in the FCIDUMP file are filled with the appropriate value.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The two-electron integrals as a tensor, as read from the FCIDUMP file.

valid_formats = ['block', 'minor', 'major']
class FermionOperator(data=None, coeff=1.0)

Bases: Operator

Represents an operator on a Fermionic Hilbert space.

The operator is stored as a dict, with the keys being FermionOperatorString objects (terms) and values being the corresponding term coefficients. This can be directly instantiated with a tuple, a list of tuples, or a dict.

See examples below, and the documentation for the from_tuple() and from_list() methods for further detail.

Parameters:

Examples

>>> fos = FermionOperatorString(((1, 0), (2, 1)))
>>> op = FermionOperator(fos, 1.0)
>>> print(op)
(1.0, F1  F2^)
>>> op = FermionOperator({fos: 1.0})
>>> print(op)
(1.0, F1  F2^)
class TrotterizeCoefficientsLocation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Determines where coefficients will be stored upon performing Trotterization.

INNER = 'inner'

All coefficients will be stored in the “inner” coefficients, within the component QubitOperators in the Trotterized result.

MIXED = 'mixed'

The Trotter step factor will be stored in the “outer” coefficients, whereas the original coefficients of the original Operator will remain in the component Operators.

OUTER = 'outer'

All coefficients will be stored in the “outer” coefficients, the coefficients stored directly in the generated OperatorList.

capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=-1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

apply_bra(fock_state)

Performs an operation on a inquanto.states.FermionState representing a bra.

This transforms the provided inquanto.states.FermionState with the operator on the right. Conjugation on the inquanto.states.FermionState object is not performed.

Parameters:

fock_state (FermionState) – Object representing a bra.

Returns:

FermionState – A representation of the post-operation bra.

apply_ket(fock_state)

Performs an operation on a ket inquanto.states.FermionState state.

Parameters:

fock_state (FermionState) – FermionState object (ket state).

Returns:

FermionState – New ket state.

approx_equal_to(other, abs_tol=ABS_TOL_OPERATOR)

Checks for equality between this instance and another FermionOperator.

First, dictionary equivalence is tested for. If False, operators are compared in normal-ordered form, and difference is compared to abs_tol.

Parameters:

  • other (FermionOperator) – An operator to test for equality with.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in comparison.

Returns:

bool – True if this operator is equal to other, otherwise False.

Danger

This method may use the normal_ordered() method internally, which may be exponentially costly.

approx_equal_to_by_random_subs(other, order=1, abs_tol=ABS_TOL_OPERATOR)

Checks if object’s dictionary values are numerically identical to the other object values.

Symbols contained in the difference of the two objects, if any, are substituted by random numeric values prior to norm check.

Parameters:

  • other (LinearDictCombiner) – Object to compare to.

  • order (int, default: 1) – Parameter specifying the norm formula (see numpy.linalg.norm() documentation).

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Threshold against which the norm of the difference is checked.

Return type:

bool

as_scalar(abs_tol=None)

If the operator is a sum of identity terms or zero, return the sum of the coefficients, otherwise return None.

Note that this does not perform combination of terms and will return zero only if all coefficients are zero.

Parameters:

abs_tol (float, default: None) – Tolerance for checking if coefficients are zero. Set to None to test using a standard

:param python == comparison.:

Returns:

Union[float, complex, None] – The operator as a scalar if it can be represented as such, otherwise None.

classmethod ca(a, b)

Return object with a single one-body creation-annihilation pair with a unit coefficient in its dict.

Parameters:

  • a (int) – Index of fermionic mode to which a creation operator is applied.

  • b (int) – Index of fermionic mode to which an annihilation operator is applied.

Returns:

The creation-annihilation operator pair.

Examples

>>> print(FermionOperator.ca(2, 0))
(1.0, F2^ F0 )
classmethod caca(a, b, c, d)

Return object with a single two-body creation-annihilation pair with a unit coefficient in its dict.

Ordered as creation-annihilation-creation-annihilation.

Parameters:

  • a (int) – Index of fermionic mode to which the first creation operator is applied.

  • b (int) – Index of fermionic mode to which the first annihilation operator is applied.

  • c (int) – Index of fermionic mode to which the second creation operator is applied.

  • d (int) – Index of fermionic mode to which the second annihilation operator is applied.

Returns:

The composed two-body operator.

Examples

>>> print(FermionOperator.caca(2, 0, 3, 1))
(1.0, F2^ F0  F3^ F1 )
classmethod ccaa(a, b, c, d)

Return object with a single two-body creation-annihilation pair with a unit coefficient in its dict.

Ordered as creation-creation-annihilation-annihilation.

Parameters:

  • a (int) – Index of fermionic mode to which the first creation operator is applied.

  • b (int) – Index of fermionic mode to which the second creation operator is applied.

  • c (int) – Index of fermionic mode to which the first annihilation operator is applied.

  • d (int) – Index of fermionic mode to which the second annihilation operator is applied.

Returns:

The composed two-body operator.

Examples

>>> print(FermionOperator.ccaa(3, 2, 1, 0))
(1.0, F3^ F2^ F1  F0 )
clone()

Performs shallow copy of the object.

Return type:

TypeVar(SYMBOLICTYPE, bound= Symbolic)

property coefficients: List[int | float | complex | Expr]

Returns dictionary values.

commutator(other_operator)

Returns the commutator of this instance with other_operator.

This calculation is performed by explicit calculation through multiplication.

Parameters:

other_operator (FermionOperator) – The other fermionic operator.

Returns:

FermionOperator – The commutator.

commutes_with(other_operator, abs_tol=ABS_TOL_OPERATOR)

Returns True if this instance commutes with other_operator (within tolerance), otherwise False.

Parameters:

  • other_operator (FermionOperator) – The other fermionic operator.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in the commutator.

Returns:

bool – True if operators commute (within tolerance) otherwise False.

compress(abs_tol=ABS_TOL_OPERATOR, symbol_sub_type=CompressSymbolSubType.NONE)

Combines duplicate terms, removing those with negligible coefficient.

Parameters:

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance for comparing values to zero.

  • symbol_sub_type (Union[CompressSymbolSubType, str], default: CompressSymbolSubType.NONE) – Defines the behavior for dealing with symbolic expressions in coefficients. If “none”, symbolic expressions are left intact. If “unity”, substitutes all free symbols with 1, and removes all imaginary and real components below tolerance. If “random”, substitutes all free symbols with a random number between 0 and 1, and removes imaginary and real components below tolerance.

Warning

When symbol_sub_type != "none", this method assumes significant expression structure is known a priori, and is best suited to operators which have simple product expressions, such as excitation operators for VQE ansatzes and digital quantum simulation. Otherwise, it may remove terms relevant to computation. Each expression is of the form \(f(a_1,a_2,\ldots,a_n)\) for some symbols \(a_i\). \(|f(a_1,a_2,\ldots,a_n)|\) is assumed to monotonically increase in both real and imaginary components for all \(a_i \in [0, 1]\).

Returns:

LinearDictCombiner – Updated instance with negligible terms removed.

classmethod constant(value)

Return object with a provided constant entry in its dict.

Returns:

Operator representation of provided constant scalar.

Examples

>>> print(FermionOperator.constant(0.5))
(0.5, )
copy()

Performs deep copy of the object.

Return type:

TypeVar(SYMBOLICTYPE, bound= Symbolic)

dagger()

Returns the Hermitian conjugate of an operator.

Return type:

FermionOperator

df()

Returns a Pandas DataFrame object of the dictionary.

Return type:

DataFrame

empty()

Checks if dictionary is empty.

Return type:

bool

evalf(*args, **kwargs)

Evaluates symbolic expressions stored in dict values and replaces them with the results.

Parameters:

  • args (Any) – Args to be passed to sympy.evalf().

  • kwargs (Any) – Kwargs to be passed to sympy.evalf().

Returns:

LinearDictCombiner – Updated instance of LinearDictCombiner.

free_symbols()

Returns the free symbols in the coefficient values.

free_symbols_ordered()

Returns the free symbols in the dict, ordered alphabetically.

Returns:

SymbolEnsemble – Ordered set of symbols.

freeze(index_map, occupation)

Adaptation of OpenFermion’s freeze_orbitals method with mask and consistent index pruning.

Parameters:

  • index_map (List[int]) – A list of integers or None entries, whose size is equal to the number of spin-orbitals, where None indicates orbitals to be frozen and the remaining sequence of integers is expected to be continuous.

  • occupation (List[int]) – A list of 1s and 0s of the same length as index_map, indicating occupied and unoccupied orbitals.

Returns:

FermionOperator – New operator with frozen orbitals removed.

classmethod from_list(data)

Construct FermionOperator from a list of tuples.

Parameters:

data (List[Tuple[Union[int, float, complex, Expr], FermionOperatorString]]) – Data representing a fermion operator term or sum of fermion operator terms. Each term in the list must be a tuple containing a scalar multiplicative coefficient, followed by a FermionOperatorString or tuple (see FermionOperator.from_tuple()).

Returns:

FermionOperator – Fermion operator object corresponding to a valid input.

Examples

>>> fos0 = FermionOperatorString(((1, 0), (2, 1)))
>>> fos1 = FermionOperatorString(((1, 0), (3, 1)))
>>> op = FermionOperator.from_list([(0.9, fos0), (0.1, fos1)])
>>> print(op)
(0.9, F1  F2^), (0.1, F1  F3^)
>>> op = FermionOperator.from_list([(0.9, ((1, 0), (2, 1))), (0.1, fos1)])
>>> print(op)
(0.9, F1  F2^), (0.1, F1  F3^)
classmethod from_string(input_string)

Constructs a child class instance from a string.

Parameters:

input_string (str) – String in the format coeff1 [(coeff1_1, term1_1), ..., (coeff1_n, term1_n)], ..., coeffn [(coeffn_1, termn_1), ...].

Returns:

Child class object.

classmethod from_tuple(data, coeff=1.0)

Construct FermionOperator from a tuple of terms.

Parameters:

  • data (Tuple) – Data representing a fermion operator term, which may be a product of single fermion creation or anihilation operators. Creation and annihilation operators acting on orbital index q are given by tuples (q, 0) and (q, 1) respectively. A product of single operators is given by a tuple of tuples; for example, the number operator: ((q, 1), (q, 0)).

  • coeff (Union[int, float, complex, Expr], default: 1.0) – Multiplicative scalar coefficient.

Returns:

FermionOperator – Fermion operator object corresponding to a valid input.

Examples

>>> op = FermionOperator.from_tuple(((1, 0), (2, 1)), 1.0)
>>> print(op)
(1.0, F1  F2^)
classmethod identity()

Return object with an identity entry in its dict.

Examples

>>> print(FermionOperator.identity())
(1.0, )
infer_num_spin_orbs()

Returns the number of modes that this operator acts upon, inferring the existence of modes with index from 0 to the maximum index.

Returns:

int – The minimum number of spin orbitals in the Fock space to which this FermionOperator operates on.

Examples

>>> op = FermionOperator.from_string("(1.0, F1 F2^)")
>>> print(op.infer_num_spin_orbs())
3
is_all_coeff_complex()

Check if all coefficients have complex values.

Returns:

bool – False if a non-complex value occurs before any free symbols in the dict values, or True if no non-complex values occur.

Warning

Returns None if a free symbol occurs before any non-complex values in the coefficients.

is_all_coeff_imag()

Check if all coefficients have purely imaginary values.

Returns:

bool – False if a non-complex value occurs before any free symbols in the dict values, or True if no non-complex values occur.

Warning

Returns None if a free symbol occurs before any non-imaginary values in the coefficients.

is_all_coeff_real()

Check if all coefficients have real values.

Returns:

bool – False if a non-real value occurs before any free symbols in the dict values, or True if no non-real values occur.

Warning

Returns None if a free symbol occurs before any non-real values in the dict coefficients.

is_all_coeff_symbolic()

Check if all coefficients contain free symbols.

Returns:

bool – Whether all coefficients contain free symbols.

is_antihermitian(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator is anti-Hermitian (within a tolerance), else False.

This explicitly calculates the Hermitian conjugate, multiplies by -1 and tests for equality. Normal-ordering is performed before comparison.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in comparison.

Returns:

bool – True if operator is anti-Hermitian, otherwise False.

Danger

This method uses the normal_ordered() method internally, which may be exponentially costly.

is_any_coeff_complex()

Check if any coefficients have complex values.

Returns:

bool – True if a complex value occurs before any free symbols in the dict values, or False if no complex values occur.

Warning

Returns None if a free symbol occurs before any complex values in the coefficients.

is_any_coeff_imag()

Check if any coefficients have imaginary values.

Returns:

bool – True if an imaginary value occurs before any free symbols in the dict values, or False if no imaginary values occur.

Warning

Returns None if a free symbol occurs before any imaginary values in the coefficients.

is_any_coeff_real()

Check if any coefficients have real values.

Returns:

bool – True if a real value occurs before any free symbols in the dict values, or False if no real values occur.

Warning

Returns None if a free symbol occurs before any real values in the coefficients.

is_any_coeff_symbolic()

Check if any coefficients contain free symbols.

Returns:

bool – Whether any coefficients contain free symbols.

is_commuting_operator()

Returns True if every term in operator commutes with every other term, otherwise False.

Return type:

bool

is_hermitian(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator is Hermitian (within a tolerance), else False.

This explicitly calculates the Hermitian conjugate and tests for equality. Normal-ordering is performed before comparison.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in comparison.

Returns:

bool – True if operator is Hermitian, otherwise False.

Danger

This method uses the normal_ordered() method internally, which may be exponentially costly.

is_normal_ordered()

Returns whether or not term is in normal-ordered form.

The assumed convention for normal ordering is for all creation operators to be to the left of annihilation operators, and each “block” of creation/annihilation operators are ordered with orbital indices in descending order (from left to right).

Returns:

bool – True if operator is normal-ordered, False otherwise.

Examples

>>> op = FermionOperator.from_string("(3.5, F1 F2^)")
>>> print(op.is_normal_ordered())
False
>>> op = FermionOperator.from_string("(3.5, F1^ F2^)")
>>> print(op.is_normal_ordered())
False
is_normalized(order=2, abs_tol=ABS_TOL_OPERATOR)

Returns True if operator has unit p-norm, else False.

Parameters:

  • order (int, default: 2) – Norm order.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for comparison with unity.

Raises:

ValueError – Coefficients contain free symbols.

Return type:

bool

is_parallel_with(other, abs_tol=ABS_TOL_OPERATOR)

Returns True if other is parallel with this (i.e. a scalar multiple of this), otherwise False.

Parameters:

  • other (LinearDictCombiner) – The other object to compare against

  • abs_tol (Optional[float], default: ABS_TOL_OPERATOR) – Tolerance threshold for comparison. Set to None to test for exact equivalence.

Returns:

bool – True if other is parallel with this, otherwise False.

is_self_inverse(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator is its own inverse (within a tolerance), False otherwise.

This explicitly calculates the square of the operator and compares to the identity. Normal-ordering is performed before comparison.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in comparison.

Returns:

bool – True if operator is self-inverse, otherwise False.

Danger

This method uses the normal_ordered() method internally, which may be exponentially costly.

is_two_body_number_conserving(check_spin_symmetry=False)

Query whether operator has correct form to be a molecular Hamiltonian.

This method is a copy of the OpenFermion is_two_body_number_conserving() method.

Require that term is particle-number conserving (same number of raising and lowering operators). Require that term has 0, 2 or 4 ladder operators. Require that term conserves spin (parity of raising operators equals parity of lowering operators).

Parameters:

check_spin_symmetry (bool, default: False) – Whether to check if operator conserves spin.

Returns:

bool – True if operator conserves electron number (and, optionally, spin), False otherwise.

Examples

>>> op = FermionOperator.from_string("(1.0, F1^ F0)")
>>> print(op.is_two_body_number_conserving())
True
>>> op = FermionOperator.from_string("(1.0, F0^)")
>>> print(op.is_two_body_number_conserving())
False
>>> op = FermionOperator.from_string("(1.0, F1^ F0^)")
>>> print(op.is_two_body_number_conserving())
False
>>> op = FermionOperator.from_string("(1.0, F1^ F0)")
>>> print(op.is_two_body_number_conserving(check_spin_symmetry=True))
False
is_unit_1norm(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator has unit 1-norm, else False.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for comparison with unity.

Return type:

bool

is_unit_2norm(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator has unit 1-norm, else False.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for comparison with unity.

Return type:

bool

is_unit_norm(order=2, abs_tol=ABS_TOL_OPERATOR)

Returns True if operator has unit p-norm, else False.

Parameters:

  • order (int, default: 2) – Norm order.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for comparison with unity.

Raises:

ValueError – Coefficients contain free symbols.

Return type:

bool

is_unitary(abs_tol=ABS_TOL_OPERATOR)

Returns True if operator is unitary (within a tolerance), False otherwise.

This explicitly calculates the Hermitian conjugate, right-multiplies by the initial operator and tests for equality to the identity. Normal-ordering is performed before comparison.

Parameters:

abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance threshold for negligible terms in comparison.

Returns:

bool – True if operator is unitary, otherwise False.

Danger

This method uses the normal_ordered() method internally, which may be exponentially costly.

items()

Returns dictionary items.

Return type:

ItemsView[Any, Union[int, float, complex, Expr]]

static key_from_str(key_str)

Returns a FermionOperatorString instance initiated from the input string.

Parameters:

key_str (str) – An input string describing the FermionOperatorString to be created -

:param see FermionOperatorString.from_string() for more detail.:

Returns:

FermionOperatorString – A generated FermionOperatorString instance.

list_class

alias of FermionOperatorList

make_hashable()

Return a hashable representation of the object.

Returns:

str – A string representation of this instance.

map(mapping)

Updates dictionary values, using a mapping function provided.

Parameters:

mapping (Callable[[Union[int, float, complex, Expr]], Union[int, float, complex, Expr]]) – Mapping function to update the dict.

Returns:

LinearDictCombiner – This instance.

classmethod n(a)

Return a fermionic number operator with unit coefficient.

Parameters:

a (int) – Index of fermionic mode to which a number operator is applied.

Returns:

Number operator.

Examples

>>> print(FermionOperator.n(3))
(1.0, F3^ F3 )
property n_symbols: int

Returns the number of free symbols in the object.

norm_coefficients(order=2)

Returns the p-norm of the coefficients.

Parameters:

order (int, default: 2) – Norm order.

Return type:

Union[complex, float]

normal_ordered()

Returns a normal-ordered version of FermionOperator.

Normal-ordering the operator moves all creation operators to the left of annihilation operators, and orders orbital indices in descending order (from left to right).

Danger

This may be exponential in runtime.

Returns:

FermionOperator – The operator in normal-ordered form.

Examples

>>> op = FermionOperator.from_string("(0.5, F1 F2^), (0.2, F1 F2 F3^ F4^)")
>>> op_no = op.normal_ordered()
>>> print(op_no)
(-0.5, F2^ F1 ), (0.2, F4^ F3^ F2  F1 )
normalized(norm_value=1.0, norm_order=2)

Returns a copy of this object with normalized coefficients.

Parameters:

  • norm_value (float, default: 1.0) – The desired norm of the returned operator.

  • norm_order (int, default: 2) – The order of the norm to be used.

Returns:

LinearDictCombiner – A copy of the object with coefficients normalized to the desired value.

property num_spin_orbs: int

Return the number of spin-orbitals that this operator explicitly acts on.

permuted_operator(permutation)

Permutes the indices in a FermionOperator.

Permutation is according to a list or a dict of indices, mapping the old to a new operator order.

Parameters:

permutation (Union[Dict, List[int]]) – Mapping from the old operator terms indices to the new ones. In case if a list is given, its indices acts as keys (old indices) and its values correspond to the new indices of an operator. If a dict is given, it can only contain the indices to be permuted for higher efficiency.

Returns:

FermionOperator – Permuted FermionOperator object.

Examples

>>> op = FermionOperator.ccaa(1,4,5,6) + FermionOperator.ca(0,4)
>>> print(op)
(1.0, F1^ F4^ F5  F6 ), (1.0, F0^ F4 )
>>> print(op.permuted_operator([0,4,2,3,1,5,6]))
(1.0, F4^ F1^ F5  F6 ), (1.0, F0^ F1 )
>>> print(op.permuted_operator({1:4, 4:1}))
(1.0, F4^ F1^ F5  F6 ), (1.0, F0^ F1 )
print_table()

Print dictionary formatted as a table.

Return type:

NoReturn

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping class, of this instance.

Parameters:
Returns:

QubitOperator – Mapped QubitOperator object.

remove_global_phase()

Returns a copy with a global phase applied such that the first element has a real coefficient.

This is an alias for set_global_phase() - see this method for greater control over the phase to be applied.

Returns:

LinearDictCombiner – A copy of the object with a global phase applied such that the first element has a real coefficient.

reversed_order()

Reverses the order of terms and returns it as a new object.

Return type:

LinearDictCombiner

set_global_phase(phase=0.0)

Returns a copy with a global phase applied such that the first element has the desired phase.

Parameters:

  • phase (Union[int, float, complex, Expr], default: 0.0) – The phase to yield on the first element, in half-turns (i.e. multiples of pi).

  • phase. (A symbolic expression can be assigned to) –

Returns:

LinearDictCombiner – A copy of the object with the desired global phase applied.

simplify(*args, **kwargs)

Simplifies expressions stored in dictionary values.

Parameters:

  • args (Any) – Args to be passed to sympy.simplify().

  • kwargs (Any) – Kwargs to be passed to sympy.simplify().

Returns:

LinearDictCombiner – Updated instance of LinearDictCombiner.

split()

Generates single-term FermionOperator objects.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[Dict[Symbol, Expr], Dict[Symbol, float], Dict[Symbol, Union[float, complex, Expr]], Callable[[Symbol], Expr], str]) – A mapping for substitution of free symbols.

Returns:

TypeVar(SYMBOLICTYPE, bound= Symbolic) – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Substitutes free symbols for numerical values according to a map.

Parameters:

symbol_map (Union[Dict[Symbol, Expr], Dict[Symbol, float], Dict[Symbol, Union[float, complex, Expr]], Callable[[Symbol], Expr], str, None], default: None) –

Return type:

LinearDictCombiner

sympify(*args, **kwargs)

Sympifies dictionary values.

Replaces values with their corresponding symbolic expressions.

Parameters:

  • args (Any) – Args to be passed to sympy.sympify().

  • kwargs (Any) – Kwargs to be passed to sympy.sympify().

Returns:

LinearDictCombiner – Updated instance of LinearDictCombiner.

Raises:

RuntimeError – Sympification fails.

property terms: List[Any]

Returns dictionary keys.

to_ChemistryRestrictedIntegralOperator()

Convert fermion operator into a restricted integral operator.

Uses the ChemistryRestrictedIntegralOperator.from_FermionOperator() method internally.

Return type:

ChemistryRestrictedIntegralOperator

to_ChemistryUnrestrictedIntegralOperator()

Convert fermion operator into an unrestricted integral operator.

Uses the ChemistryUnrestrictedIntegralOperator.from_FermionOperator() method internally.

Return type:

ChemistryUnrestrictedIntegralOperator

to_latex(imaginary_unit='\\\\text{i}', **kwargs)

Generate a LaTeX representation of the operator.

Parameters:
Returns:

str – LaTeX compilable equation string.

Examples

>>> from inquanto.operators import FermionOperator
>>> from sympy import sympify
>>> c = sympify("c")
>>> fo = FermionOperator([(-c, "F1 F2^"), (c**2, "F1^"), (c, "F0 F5 F3^")])
>>> print(fo.to_latex())
- c a_{1} a_{2}^{\dagger} + c^{2} a_{1}^{\dagger} + c a_{0} a_{5} a_{3}^{\dagger}
>>> fo = FermionOperator([(1.0, "F0^ F1^ F3^"), (-1.0j, "F3 F1 F0")])
>>> print(fo.to_latex())
a_{0}^{\dagger} a_{1}^{\dagger} a_{3}^{\dagger} -\text{i} a_{3} a_{1} a_{0}
>>> from sympy import sqrt
>>> fo = FermionOperator([(sqrt(2), "F0^ F1"), (0.5-8j, "F5 F5^"), (2j, "F1^ F1^")])
>>> print(fo.to_latex(imaginary_unit=r"\text{j}", operator_symbol="f"))
\sqrt{2} f_{0}^{\dagger} f_{1} + (0.5-8.0\text{j}) f_{5} f_{5}^{\dagger} + 2.0\text{j} f_{1}^{\dagger} f_{1}^{\dagger}

>>> from inquanto.operators import QubitOperator, QubitOperatorString
>>> qos1 = QubitOperatorString.from_string("X1 Y2 Z3")
>>> qos2 = QubitOperatorString.from_string("Z0 Y1 X4")
>>> qos3 = QubitOperatorString.from_list([(("a", [0]), "I"), (("b", [1]), "Z"), (("c", [2]), "Z")])
>>> qo = QubitOperator({qos1: -1.0, qos2: 3+4j, qos3: c})
>>> print(qo.to_latex())
- X_{1} Y_{2} Z_{3} + (3.0+ 4.0\text{i}) Z_{0} Y_{1} X_{4} + c I_{0} Z_{1} Z_{2}
>>> qo = QubitOperator({qos3: 3j})
>>> print(qo.to_latex(imaginary_unit="j", show_labels=True))
3.0j I^{\text{a}}_{0} Z^{\text{b}}_{1} Z^{\text{c}}_{2}
trotterize(trotter_number=1, trotter_order=1, constant=1.0, coefficients_location=TrotterizeCoefficientsLocation.OUTER)

Trotterizes the operator, treating the operator as an exponent.

Assuming that this operator is an exponent, this will generate an instance with each element corresponding to a

single exponent in the Trotter product of exponentials.

Parameters:

  • trotter_number (int, default: 1) – The number of time-slices in the Trotter approximation.

  • trotter_order (int, default: 1) – The order of the Trotter-Suzuki approximation being used. Currently, this supports values 1 (i.e. \(AB\)) and 2 (i.e. \(A/2\,B/2\,B/2\,A/2\))

  • constant (Union[float, complex], default: 1.0) – An additional constant factor to multiply each exponent by, which may be useful when, for example, constructing a time evolution operator.

  • coefficients_location (TrotterizeCoefficientsLocation, default: TrotterizeCoefficientsLocation.OUTER) – By default, the coefficient of each term in the input operator is multiplied by the Trotter factor and stored in the outer coefficient of the returned instance, with the coefficient of each inner Operator set to 1. This behavior can be controlled with this argument - set to "outer" for default behavior. On the other hand, setting this parameter to "inner" will store all scalars in the inner Operator coefficient, with the outer coefficients of the returned instance set to 1. Setting this parameter to "mixed" will store the Trotter factor in the outer coefficients of the returned instance, with the inner coefficients of each term left untouched. See examples for a comparison.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – A Trotterized form of the exponential product, where each element is an individual exponent.

Examples

>>> from inquanto.operators import QubitOperator
>>> op1 = QubitOperator("X0 Y1 Z3", 4.6) + QubitOperator("Z1 Z2 Z3 Z5", -5.6j)
>>> trotter_operator = op1.trotterize(trotter_number=2)
>>> print(trotter_operator)
2.3       [(1.0, X0 Y1 Z3)],
-2.8j     [(1.0, Z1 Z2 Z3 Z5)],
2.3       [(1.0, X0 Y1 Z3)],
-2.8j     [(1.0, Z1 Z2 Z3 Z5)]
>>> from inquanto.operators import QubitOperator
>>> op1 = QubitOperator("X0 Y1 Z3", 4.6) + QubitOperator("Z1 Z2 Z3 Z5", -5.6j)
>>> trotter_operator = op1.trotterize(trotter_number=2,coefficients_location="inner")
>>> print(trotter_operator)
1.0       [(2.3, X0 Y1 Z3)],
1.0       [(-2.8j, Z1 Z2 Z3 Z5)],
1.0       [(2.3, X0 Y1 Z3)],
1.0       [(-2.8j, Z1 Z2 Z3 Z5)]
>>> from inquanto.operators import QubitOperator
>>> op1 = QubitOperator("X0 Y1 Z3", 4.6) + QubitOperator("Z1 Z2 Z3 Z5", -5.6j)
>>> trotter_operator = op1.trotterize(trotter_number=2,coefficients_location="mixed")
>>> print(trotter_operator)
0.5       [(4.6, X0 Y1 Z3)],
0.5       [(-5.6j, Z1 Z2 Z3 Z5)],
0.5       [(4.6, X0 Y1 Z3)],
0.5       [(-5.6j, Z1 Z2 Z3 Z5)]
truncated(tolerance=OPERATOR_PRUNE_TOLERANCE, normal_ordered=True)

Prunes FermionOperator terms with coefficients below provided threshold.

Parameters:

  • tolerance (default: OPERATOR_PRUNE_TOLERANCE) – Threshold below which terms are removed.

  • normal_ordered (default: True) – Should the operator be returned in normal-ordered form.

Returns:

FermionOperator – New, modified operator.

Examples

>>> op = FermionOperator.from_string("(0.999, F0 F1^), (0.001, F2^ F1 )")
>>> print(op.truncated(tolerance=0.005, normal_ordered=False))
(0.999, F0  F1^)
>>> print(op.truncated(tolerance=0.005))
(-0.999, F1^ F0 )
unsympify(precision=15, partial=False)

Unsympifies dictionary values.

Replaces symbolic expressions with their corresponding numeric values.

Parameters:

  • precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

  • partial (bool, default: False) – Set to True to allow partial unsympification where terms containing free symbols are present. By default, free symbols in any coefficient will cause an exception.

Returns:

LinearDictCombiner – Updated instance of LinearDictCombiner.

Raises:

TypeError – Unsympification fails.

classmethod zero()

Return object with a zero dict entry.

Examples

>>> print(LinearDictCombiner.zero())
(0)
class FermionOperatorList(data=None, coeff=1.0)

Bases: OperatorList

Stores tuples of FermionOperator objects and corresponding coefficient values in an ordered list.

In contrast to FermionOperator, this class is not assumed to represent a linear combination. Typically, this will be of use when considering sequences of operators upon which some nonlinear operation is performed. For instance, this may be used to store a Trotterized combination of exponentiated FermionOperator objects. This class may be instantiated from a FermionOperator or a FermionOperatorString object and a scalar or symbolic coefficient. It may also be instantiated with a list containing two-element tuples of scalar or symbolic coefficients and FermionOperator objects. In contrast to FermionOperator, in this class the ordering of terms is well-defined and consistent.

Parameters:

Examples

>>> from sympy import sympify
>>> op1 = FermionOperator(FermionOperatorString(((1, 0), (2, 1))), 3.5)
>>> op2 = FermionOperator(FermionOperatorString(((0, 0), (3, 1))), 1.5)
>>> fto = FermionOperatorList([(sympify("a"), op1), (sympify("b"), op2)])
>>> print(fto)
a         [(3.5, F1  F2^)],
b         [(1.5, F0  F3^)]
>>> fto = FermionOperatorList(op1)
>>> print(fto)
1.0       [(3.5, F1  F2^)]
>>> fto = FermionOperatorList(FermionOperatorString(((1, 0), (2, 1))))
>>> print(fto)
1.0       [(1.0, F1  F2^)]
class CompressScalarsBehavior(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Governs compression of scalars method behavior.

ALL = 'all'

Combine all coefficients possible, simplifying inner terms.

ONLY_IDENTITIES_AND_ZERO = 'simple'

Only compress based on terms which are a scalar multiple of the identity operator, or zero.

OUTER = 'outer'

Combine all “outer” coefficients (coefficients stored directly in the top-level OperatorList) into one.

capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=-1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

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

Bases: str, Enum

Determines where the from_Operator() method places coefficients.

INNER = 'inner'

Coefficients are left within the component operators.

OUTER = 'outer'

Coefficients are moved to be directly stored at the top-level of the OperatorList.

capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=-1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

clone()

Performs shallow copy of the object.

Return type:

TypeVar(SYMBOLICTYPE, bound= Symbolic)

collapse_as_linear_combination(ignore_outer_coefficients=False)

Treating this instance as a linear combination, return it in the form of an Operator.

By default, each term is multiplied by its corresponding scalar coefficient, then all such multiplied terms are summed to yield a single Operator. The first step may be skipped (i.e. the scalar coefficients associated with each constituent Operator may be ignored) by setting ignore_outer_coefficients to True.

Parameters:

ignore_outer_coefficients (bool, default: False) – Set to True to skip multiplication by the “outer” coefficients in the OperatorList.

Returns:

TypeVar(OperatorT, bound= Operator) – The sum of all terms in this instance, multiplied by their associated coefficients if requested.

collapse_as_product(reverse=False, ignore_outer_coefficients=False)

Treating this instqnce as a product of separate terms, return the full product as an Operator.

By default, each Operator in the OperatorList is multiplied by its corresponding coefficient, and the product is taken sequentially with the leftmost term given by the first element of the OperatorList. This behavior can be reversed with the reverse parameter - if set to True, the leftmost term will be given by the last element of OperatorList.

If ignore_outer_coefficients is set to True, the first step (the multiplication of Operator terms by their corresponding coefficients) is skipped - i.e. the “outer” coefficients stored in the OperatorList are ignored.

Danger

In the general case, the number of terms in the expansion will blow up exponentially (and thus the runtime of this method will also blow up exponentially).

Parameters:

  • reverse (bool, default: False) – Set to True to reverse the order of the product.

  • ignore_outer_coefficients (bool, default: False) – Set to True to skip multiplication by the “outer” coefficients in the OperatorList.

Returns:

TypeVar(OperatorT, bound= Operator) – The product of each component operator.

compress_scalars_as_product(abs_tol=ZERO_ONE_TOLERANCE, inner_coefficient=False, coefficients_to_compress=CompressScalarsBehavior.ONLY_IDENTITIES_AND_ZERO)

Treating the OperatorList as a product, compress identity terms or resolve to zero if possible.

To do this, we iterate through the (coefficient, operator) pairs in the OperatorList. If any coefficient or operator is zero, then return an empty OperatorList, as the product will be zero. If the iteration operator is an identity, it will be treated as a scalar multiplier, itself multiplied by its associated coefficient, with the operator itself removed from the OperatorList. These multipliers are multiplied together and – if they do not equate to 1 – are prepended to the OperatorList as a separate identity term.

By default, (coefficient, operator) pairs which are not identity or zero will be ignored. This behavior may be controlled with the coefficients_to_compress parameter. This can be set to "outer" to include all "outer" coefficients of the (coefficient, operator) pairs in the prepended identity term. It can also be set to "all" to additionally bring coefficients within the non-identity operators into the prepended identity term – i.e. for operators where all the “inner” coefficients are equal. See examples for a comparison.

The prepended identity term will, by default, store the multiplied scalar factor in the “outer” coefficient of the (coefficient, operator) pair. The inner_coefficient parameter may be set to True to instead store it within the operator.

Note

Term simplification is not performed on component operators. It is possible that a component operator will resolve on simplification to the identity or zero. This method will not catch these occurrences.

Parameters:

  • abs_tol (float, default: ZERO_ONE_TOLERANCE) – Numerical threshold for comparison of numbers to 0 and 1. Set to None to use exact identity.

  • inner_coefficient (bool, default: False) – Set to True to store generated scalar factors within the identity term, as described above.

  • coefficients_to_compress (CompressScalarsBehavior, default: CompressScalarsBehavior.ONLY_IDENTITIES_AND_ZERO) – Controls which scalar factors will be combined, as described above.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – The OperatorList with identity and zero terms combined, as described above.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> op2 = 3. * QubitOperator.identity()
>>> qol = QubitOperatorList([(5., op1), (7., op2)])
>>> result = qol.compress_scalars_as_product()
>>> print(result)
21.0      [(1.0, )],
5.0       [(2.0, X0), (2.0, Z1)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> op2 = 3. * QubitOperator.identity()
>>> qol = QubitOperatorList([(5., op1), (7., op2)])
>>> result = qol.compress_scalars_as_product(inner_coefficient=True)
>>> print(result)
1         [(21.0, )],
5.0       [(2.0, X0), (2.0, Z1)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> op2 = 3. * QubitOperator.identity()
>>> qol = QubitOperatorList([(5., op1), (7., op2)])
>>> result = qol.compress_scalars_as_product(coefficients_to_compress="outer")
>>> print(result)
105.0     [(1.0, )],
1         [(2.0, X0), (2.0, Z1)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> op2 = 3. * QubitOperator.identity()
>>> qol = QubitOperatorList([(5., op1), (7., op2)])
>>> result = qol.compress_scalars_as_product(coefficients_to_compress="all")
>>> print(result)
210.0     [(1.0, )],
1         [(1.0, X0), (1.0, Z1)]
copy()

Returns a deep copy of this instance.

Return type:

LinearListCombiner

df()

Returns a pandas DataFrame object of the dictionary.

empty()

Checks if internal list is empty.

Return type:

bool

evalf(*args, **kwargs)

Numerically evaluates symbolic expressions stored in the left and right values of list items and replaces them with the results.

Parameters:

  • args (Any) – Args to be passed to sympy.evalf().

  • kwargs (Any) – Kwargs to be passed to sympy.evalf().

Returns:

LinearListCombiner – Updated instance of LinearListCombiner.

free_symbols()

Returns the free symbols in the coefficient values.

Return type:

set

free_symbols_ordered()

Returns the free symbols in the dict, ordered alphabetically.

Returns:

SymbolEnsemble – Ordered set of symbols.

classmethod from_Operator(input, additional_coefficient=1.0, coefficients_location=FactoryCoefficientsLocation.INNER)

Converts an Operator to an OperatorList with terms in arbitrary order.

Each term in the Operator is split into a separate component Operator in the OperatorList. The resulting location of each scalar coefficient in the input Operator can be controlled with the coefficients_location parameter. Setting this to "inner" will leave coefficients stored as part of the component operators, a value of "outer" will move the coefficients to the “outer” level.

Parameters:

  • input (Operator) – The input operator to split into an OperatorList.

  • additional_coefficient (Union[int, float, complex, Expr], default: 1.0) – An additional factor to include in the “outer” coefficients of the generated OperatorList.

  • coefficients_location (FactoryCoefficientsLocation, default: FactoryCoefficientsLocation.INNER) – The destination of the coefficients of the input operator, as described above.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – An OperatorList as described above.

Raises:

ValueError – On invalid input to the coefficients_location parameter.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> qol = QubitOperatorList.from_Operator(op)
>>> print(qol)
1.0       [(2.0, X0)],
1.0       [(2.0, Z1)]
>>> op = QubitOperator("X0", 2.) + QubitOperator("Z1", 2.)
>>> qol = QubitOperatorList.from_Operator(op,coefficients_location='outer')
>>> print(qol)
2.0       [(1.0, X0)],
2.0       [(1.0, Z1)]
classmethod from_string(input_string)

Constructs a child class instance from a string.

Parameters:

input_string (str) – String in the format coeff1 [(coeff1_1, term1_1), ..., (coeff1_n, term1_n)], ..., coeffn [(coeffn_1, termn_1), ...].

Returns:

TypeVar(OperatorListT, bound= OperatorList) – Child class object.

infer_num_spin_orbs()

Returns the number of modes that the component operators act upon, inferring the existence of modes with index from 0 to the maximum index.

Returns:

int – The minimum number of spin orbitals in the Fock space to which this operator list operates on.

Examples

>>> op1 = FermionOperator(FermionOperatorString(((1, 0), (2, 1))), 1.)
>>> op2 = FermionOperator(FermionOperatorString(((0, 0), (6, 1))), 1.)
>>> fto = FermionOperatorList([(1., op1), (1., op2)])
>>> print(fto.infer_num_spin_orbs())
7
items()

Returns internal list.

Return type:

List[Tuple[Any, Union[int, float, complex, Expr]]]

make_hashable()

Return a hashable representation of the object.

Returns:

str – A string representation of this instance.

map(mapping)

Updates right values of items in-place, using a mapping function provided.

Parameters:

mapping (Callable[[Union[int, float, complex, Expr]], Union[int, float, complex, Expr]]) – A callable object which takes each original value and returns the corresponding new value.

Return type:

LinearListCombiner

property n_symbols: int

Returns the number of free symbols in the object.

property num_spin_orbs: int

Return the number of spin-orbitals that this operator explicitly acts on.

operator_class

alias of FermionOperator

print_table()

Print internal list formatted as a table.

Return type:

None

qubit_encode(mapping=None, qubits=None)

Performs qubit encoding (mapping), using provided mapping function, of the current FermionOperatorList.

Terms are treated and mapped independently.

Parameters:

  • mapping (QubitMapping, default: None) – Mapping class. Default mapping procedure is the Jordan-Wigner transformation.

  • qubits (Optional[List[Qubit]], default: None) – The qubit register. If left as None, a default register will be assumed if possible. See the mapping class documentation for further details.

Returns:

QubitOperatorList – Mapped QubitOperatorList.

retrotterize(new_trotter_number, initial_trotter_number=1, new_trotter_order=1, initial_trotter_order=1, constant=1.0, inner_coefficients=False)

Retrotterize an expression given a OperatorList representing a product of exponentials.

This method assumes that self represents a product of exponentials, with each constituent Operator corresponding to the exponentiated term of a single exponential in a product. Scalar factors within the OperatorList are treated as scalar multipliers within each exponent.

The OperatorList is first untrotterized using the provided initial_trotter_number and initial_trotter_order, then subsequently Trotterized using the provided new_trotter_number and new_trotter_order. The returned OperatorList corresponds to the generated product of exponentials, in a similar manner to the original OperatorList.

Parameters:

  • new_trotter_number (int) – The desired number of Trotter steps in the final Trotter-Suzuki expansion.

  • initial_trotter_number (int, default: 1) – The number of Trotter steps in the original Trotter-Suzuki expansion.

  • new_trotter_order (int, default: 1) – The desired order of the final Trotter-Suzuki expansion. Currently, only a first order (\(ABABAB...\)) or second order (\(ABBAABBA...\)) expansion is supported.

  • initial_trotter_order (int, default: 1) – The order of the original Trotter-Suzuki expansion used. Currently, only a first order (\(ABABAB...\)) expansion is supported.

  • constant (Union[float, complex], default: 1.0) – An additional constant multiplier in the exponent.

  • inner_coefficients (bool, default: False) – By default, generated scalar factors in each exponent are stored in the coefficients of the generated OperatorList, with the coefficient of each inner Operator unchanged. Set this to True to instead store all scalar factors as coefficients in each Operator, with the outer coefficients of the OperatorList left unchanged. See examples for a comparison.

Returns:

TypeVar(OperatorListT, bound= OperatorList) –:

The exponential product retrotterized with the provided new Trotter number and order. Each element is an

individual exponent.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1./2.,op1),(1./2.,op2),(1./2.,op1),(1./2.,op2)])
>>> retrotterised = qol.retrotterize(new_trotter_number=4,initial_trotter_number=2)
>>> print(retrotterised)
0.25      [(1.0, X0 X1)],
0.25      [(1.0, Z0)],
0.25      [(1.0, X0 X1)],
0.25      [(1.0, Z0)],
0.25      [(1.0, X0 X1)],
0.25      [(1.0, Z0)],
0.25      [(1.0, X0 X1)],
0.25      [(1.0, Z0)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1./2.,op1),(1./2.,op2),(1./2.,op1),(1./2.,op2)])
>>> retrotterised = qol.retrotterize(new_trotter_number=4,initial_trotter_number=2,inner_coefficients=True)
>>> print(retrotterised)
0.5       [(0.5, X0 X1)],
0.5       [(0.5, Z0)],
0.5       [(0.5, X0 X1)],
0.5       [(0.5, Z0)],
0.5       [(0.5, X0 X1)],
0.5       [(0.5, Z0)],
0.5       [(0.5, X0 X1)],
0.5       [(0.5, Z0)]
reversed_order()

Reverses internal list order and returns it as a new object.

Return type:

LinearListCombiner

simplify(*args, **kwargs)

Simplifies expressions stored in left and right values of list items.

Parameters:

  • args (Any) – Args to be passed to sympy.simplify().

  • kwargs (Any) – Kwargs to be passed to sympy.simplify().

Returns:

LinearListCombiner – Updated instance of LinearListCombiner.

split()

Generates pair objects from list items.

Return type:

Iterator[LinearListCombiner]

sublist(sublist_indices)

Returns a new instance containing a subset of the terms in the original object.

Parameters:

sublist_indices (list[int]) – Indices of elements in this instance selected to constitute a new object.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – A sublist of this instance.

Raises:

  • ValueError – If sublist_indices contains indices not contained in this instance, or if this instance

  • is empty. –

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 Y1 Z3", 4.6)
>>> op2 = QubitOperator("Z0", -1.6j)
>>> op3 = QubitOperator("Z1 Z2 Z3 Z5", -5.6j)
>>> long_operator = QubitOperatorList([(1, op1), (1, op2), (1, op3)])
>>> short_operator = long_operator.sublist([0, 2])
>>> print(short_operator)
1         [(4.6, X0 Y1 Z3)],
1         [(-5.6j, Z1 Z2 Z3 Z5)]
subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[Dict[Symbol, Expr], Dict[Symbol, float], Dict[Symbol, Union[float, complex, Expr]], Callable[[Symbol], Expr], str]) – A mapping for substitution of free symbols.

Returns:

TypeVar(SYMBOLICTYPE, bound= Symbolic) – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Substitutes free symbols for numerical values according to a map.

Parameters:

symbol_map (Union[Dict[Symbol, Expr], Dict[Symbol, float], Dict[Symbol, Union[float, complex, Expr]], Callable[[Symbol], Expr], str, None], default: None) – Maps symbol-representing keys to the value the symbol should be substituted for.

Returns:

LinearListCombiner – This instance with symbols key symbols replaced by their values.

sympify(*args, **kwargs)

Sympifies left and right values of list items.

Replaces left and right values with their corresponding symbolic expressions.

Parameters:

  • args (Any) – Args to be passed to sympy.sympify().

  • kwargs (Any) – Kwargs to be passed to sympy.sympify().

Returns:

LinearListCombiner – Updated instance of LinearListCombiner.

Raises:

RuntimeError – Sympification fails.

trotterize_as_linear_combination(trotter_number, trotter_order=1, constant=1.0, inner_coefficients=False)

Trotterize an exponent linear combination of Operators.

This method assumes that self represents the exponential of a linear combination of Operator objects, each corresponding to a term in this linear combination. Trotterization is performed at the level of these Operator instances. The Operator objects contained within the returned OperatorList correspond to exponents within the Trotter sequence.

Parameters:

  • trotter_number (int) – The number of Trotter steps in the Trotter-Suzuki expansion.

  • trotter_order (int, default: 1) – The order of the Trotter-Suzuki approximation to be used. The first- and the second-order options are supported.

  • constant (Union[float, complex], default: 1.0) – An additional constant multiplier in the exponent.

  • inner_coefficients (bool, default: False) – By default, generated scalar factors in each exponent are stored in the coefficients of the generated OperatorList, with the coefficient of each inner Operator unchanged. Set this to True to instead store all scalar factors as coefficients in each Operator, with the outer coefficients of the OperatorList left unchanged. See examples for a comparison.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – A Trotterized form of the exponential product, where each element is an individual exponent.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1.,op1),(1.,op2)])
>>> result = qol.trotterize_as_linear_combination(2)
>>> print(result)
0.5       [(1.0, X0 X1)],
0.5       [(1.0, Z0)],
0.5       [(1.0, X0 X1)],
0.5       [(1.0, Z0)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1.,op1),(1.,op2)])
>>> result = qol.trotterize_as_linear_combination(2,inner_coefficients=True)
>>> print(result)
1.0       [(0.5, X0 X1)],
1.0       [(0.5, Z0)],
1.0       [(0.5, X0 X1)],
1.0       [(0.5, Z0)]
unsympify(precision=15, partial=False)

Unsympifies dictionary values.

Replaces symbolic expressions with their corresponding numeric values.

Parameters:

  • precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

  • partial (default: False) – Set to True to allow partial unsympification where terms containing free symbols are present. By default, free symbols in any coefficient will cause an exception.

Returns:

LinearListCombiner – Updated instance of LinearListCombiner.

Raises:

TypeError – Unsympification fails.

untrotterize(trotter_number, trotter_order=1)

Reverse a Trotter-Suzuki expansion given a product of exponentials as an OperatorList.

This method assumes that the OperatorList represents a product of exponentials, with each Operator in the list corresponding to an exponent of a single exponential in the product. Scalar factors within the OperatorList are treated as scalar multipliers within each exponent. An Operator corresponding to the exponent of a single, untrotterized exponential is returned.

Parameters:

  • trotter_number (int) – The number of Trotter steps within the Trotter expansion to be reversed.

  • trotter_order (int, default: 1) – The order of the Trotter-Suzuki expansion used. Currently, only a first order (ABABAB…) expansion is supported.

Returns:

TypeVar(OperatorT, bound= Operator) – The exponent of the untrotterized operator.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1./2.,op1),(1./2.,op2),(1./2.,op1),(1./2.,op2)])
>>> untrotterized = qol.untrotterize(2)
>>> print(untrotterized)
(1.0, X0 X1), (1.0, Z0)
untrotterize_partitioned(trotter_number, trotter_order=1, inner_coefficients=False)

Reverse a Trotter-Suzuki expansion given a product of exponentials as an OperatorList, maintaining separation of exponents.

This method assumes that self represents a product of exponentials, with each constituent Operator corresponding to the exponentiated term of a single exponential within a product. Scalar factors within this OperatorList are treated as scalar multipliers within each exponent. A OperatorList is returned wherein each term represents a single term in the exponent of the single, untrotterized exponential.

Parameters:

  • trotter_number (int) – The number of Trotter steps within the Trotter expansion to be reversed.

  • trotter_order (int, default: 1) – The order of the Trotter-Suzuki expansion used. Currently, only a first order (\(ABABAB...\)) expansion is supported.

  • inner_coefficients (bool, default: False) – By default, generated scalar factors in each exponent are stored in the coefficients of the generated OperatorList, with the coefficient of each inner Operator unchanged. Set this to True to instead store all scalar factors as coefficients in each Operator, with the outer coefficients of the OperatorList left unchanged. See examples for a comparison.

Returns:

TypeVar(OperatorListT, bound= OperatorList) – The terms in the exponent of the untrotterized operator as a OperatorList.

Raises:

ValueError – If the provided Trotter number is not compatible with the OperatorList.

Examples

>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1./2.,op1),(1./2.,op2),(1./2.,op1),(1./2.,op2)])
>>> untrotterized = qol.untrotterize_partitioned(2)
>>> print(untrotterized)
1.0       [(1.0, X0 X1)],
1.0       [(1.0, Z0)]
>>> from inquanto.operators import QubitOperator,QubitOperatorList
>>> op1 = QubitOperator("X0 X1", 1.)
>>> op2 = QubitOperator("Z0",1.)
>>> qol = QubitOperatorList([(1./2.,op1),(1./2.,op2),(1./2.,op1),(1./2.,op2)])
>>> untrotterized = qol.untrotterize_partitioned(2,inner_coefficients=True)
>>> print(untrotterized)
0.5       [(2.0, X0 X1)],
0.5       [(2.0, Z0)]
class FermionOperatorString(initializer: tuple | List[Tuple[int, int]] | Tuple[Tuple[int, int]] = None)

Bases: tuple

Represents a single fermionic string of creation and annihilation operators.

Internally this is a tuple of tuple objects, each of which contains two integers, with the first indicating a spin orbital number, and the second being either 1 or 0, corresponding to creation and annihilation operators correspondingly. Defined to constitute a single term in inquanto.operators.FermionOperator.

Examples

>>> FermionOperatorString(((3, 1), (2, 0)))
((3, 1), (2, 0))
>>> FermionOperatorString((1, 1))
((1, 1),)
>>> print(FermionOperatorString(((3, 1), (2, 0)))) 
F3^ F2
FERMION_ANNIHILATION = 0

Integer used to indicate a fermion operator is an annihilation operator.

FERMION_CREATION = 1

Integer used to indicate a fermion operator is a creation operator.

apply_bra(fock_state, power=1)

Performs an operation on a inquanto.states.FermionState representing a bra.

This transforms the provided inquanto.states.FermionState with the operator string on the right. Conjugation on the inquanto.states.FermionState object is not performed.

Parameters:

  • fock_state (FermionState) – state object representing a bra.

  • power (int, default: 1) – Power of operation (how many times operator acts on a bra state).

Returns:

FermionState – A representation of the post-operation bra.

Examples

>>> f_op_string = FermionOperatorString.from_string("F1^ F0")
>>> bra = FermionState([0, 1])
>>> print(bra)
(1.0, {0: 0, 1: 1})
>>> print(f_op_string.apply_bra(bra))
(1.0, {0: 1, 1: 0})
>>> bra = FermionState([1, 0])
>>> print(f_op_string.apply_bra(bra))
(0)
apply_ket(fock_state, power=1)

Performs an operation on a ket inquanto.states.FermionState state.

Parameters:

  • fock_state (FermionState) – Input fermion state (ket state).

  • power (int, default: 1) – Power of operation (how many times operator acts on a ket state).

Returns:

FermionState – New ket state.

Examples

>>> f_op_string = FermionOperatorString.from_string("F1^ F0")
>>> ket = FermionState([1, 0])
>>> print(ket)
(1.0, {0: 1, 1: 0})
>>> print(f_op_string.apply_ket(ket))
(1.0, {0: 0, 1: 1})
>>> ket = FermionState([0, 1])
>>> print(f_op_string.apply_ket(ket))
(0)
apply_state(fock_state, state_type, power)

Implements a general operation on a FermionState object representing a bra or a ket.

Parameters:

  • fock_state (FermionState) – Input fermion state.

  • state_type (StateType) – Indicates whether the input state object represents a bra or a ket.

  • power (int) – Power of operation.

Returns:

FermionState – New state object.

dagger()

Performs a conjugation operation on a fermion creation-annihilation operator string.

Reverses order and swaps creation and annihilation labels.

Returns:

FermionOperatorString – The Hermitian conjugate of the current operator string.

Examples

>>> f_op_string = FermionOperatorString.from_string("F3^ F1^ F2 F0")
>>> print(f_op_string.dagger()) 
F0^ F2^ F1 F3
classmethod from_string(string)

Generates a class instance from a string.

Parameters:

string (str) – Formatted string input.

Returns:

FermionOperatorString – String of fermion creation/annihilation operators corresponding to a valid input python string.

Examples

>>> FermionOperatorString.from_string("F3^ F2")
((3, 1), (2, 0))
>>> FermionOperatorString.from_string("3^ 2")
((3, 1), (2, 0))
is_empty()

Checks if object is empty.

Return type:

bool

is_particle_conserving()

Checks if operator string is particle-conserving.

Returns:

bool – True if the operator string conserves particle number, False if not.

Examples

>>> FermionOperatorString.from_string("F3^ F2").is_particle_conserving()
True
>>> FermionOperatorString.from_string("F3^ F2 F0").is_particle_conserving()
False
items()

Returns current class instance.

Return type:

Sequence[Tuple[int, int]]

to_latex(operator_symbol='a', index_to_latex=None)

Generate a LaTeX representation of the operator string.

Parameters:

  • operator_symbol (str, default: "a") – Symbol to use for the creation/annihilation operator.

  • index_to_latex (Optional[Callable[[int], str]], default: None) – Function mapping a spin-orbital index to a latex string.

Returns:

str – LaTeX compilable equation string.

Examples

>>> fos = FermionOperatorString(((0, 1), (0, 0)))
>>> print(fos.to_latex())
a_{0}^{\dagger} a_{0}
>>> fos = FermionOperatorString(((0,1), (1, 1), (4, 5)))
>>> print(fos.to_latex(operator_symbol="c"))
c_{0}^{\dagger} c_{1}^{\dagger} c_{4}
>>> fos = FermionOperatorString.from_string("F5^ F6^ F3 F4")
>>> print(fos.to_latex(operator_symbol="f"))
f_{5}^{\dagger} f_{6}^{\dagger} f_{3} f_{4}
class IntegralType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Describes spin formalism used in integral operators.

RESTRICTED = 'r'
UNRESTRICTED = 'u'
class OrbitalOptimizer(v_init=None, occ=None, split_rotation=False, functional=None, minimizer=None, point_group=None, orbital_irreps=None, reduce_free_parameters=True)

Bases: OrbitalTransformer

Handles minimization of a functional of molecular orbital coefficients.

Parameters:

  • v_init (array, default: None) – Initial orbital coefficients.

  • occ (array, default: None) – Molecular orbital occupations (if split_rotation=True).

  • split_rotation (bool, default: False) – If True, do not allow mixing between occupied and virtual orbitals.

  • functional (Callable, default: None) – The objective function to be minimized.

  • minimizer (GeneralMinimizer, default: None) – An InQuanto minimizer.

  • point_group (Union[PointGroup, str], default: None) – If passed, symmetry information will be used to reduce free parameters.

  • orbital_irreps (list, default: None) – Orbital irreducible representations, needed if point_group is passed.

  • reduce_free_parameters (bool, default: True) – If True, the objective function will be simplified to depend on fewer parameters.

static compute_unitary(v_init=None, v_final=None, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Computes the unitary relating square matrices v_init and v_final whose columns contain the initial and final orbitals.

Computes the matrix \(U = V_\text{init}^{-1} V_\text{final}\).

Parameters:

  • v_init (Optional[ndarray], default: None) – Initial orbitals.

  • v_final (Optional[ndarray], default: None) – Final orbitals.

  • check_unitary (bool, default: True) – Whether to check for the unitarity of the resulting matrix.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity check.

Returns:

ndarray – Unitary matrix relating initial and final orbitals.

construct_random_variables(v=None, low=-0.1, high=0.1, seed=None)

Constructs \(n (n - 1)/2\) variables sampled from uniform distribution where \(n\) is the number of orbitals.

Uniform distribution is specified by given high, low and seed.

Parameters:

  • v (array, default: None) – Orbitals to be rotated.

  • low (float, default: -0.1) – Lower bound of uniform distribution domain.

  • high (float, default: 0.1) – Upper bound of uniform distribution domain.

  • seed (Optional[int], default: None) – Random number generator seed.

Returns:

ndarray – Array of random initial variables.

generate_report()

Generates a summarizing report.

Returns:

Dict – Results of the optimization.

static gram_schmidt(v, overlap=None)

Orthogonalizes column vectors in v using Gram-Schmidt algorithm with respect to an overlap matrix.

Parameters:

  • v (ndarray) – Orbitals/vectors to be orthonormalized.

  • overlap (ndarray, default: None) – Overlap matrix.

Returns:

ndarray – Orthogonalized vectors.

map_variables_to_rotation_matrix(variables=None)

Maps \(n (n - 1)/2\) variables to an \(n\times n\) unitary matrix.

Parameters:

variables (Optional[array], default: None) – Variables to be mapped to a unitary matrix.

Returns:

ndarray – Unitary rotation matrix.

map_variables_to_skew_matrix(variables=None)

Constructs an \(n\times n\) skew-symmetric matrix from \(n (n - 1)/2\) variables.

Parameters:

variables (Optional[array], default: None) – Variables to be mapped to a skew-symmetric matrix.

Returns:

ndarray – Skew symmetric matrix.

optimize(orb_init=None, initial_variables=None, functional=None, random_initial_variables=False)

Minimizes a functional which depends on orbital coefficients.

Parameters:

  • orb_init (Optional[List[float]], default: None) – Initial orbitals.

  • initial_variables (Optional[List[int]], default: None) – Initial guess variables.

  • functional (Optional[Callable], default: None) – The functional to minimize, must be callable and a function of only MO coefficients.

  • random_initial_variables (bool, default: False) – Should starting variables be randomized.

Returns:

Tuple[List, ndarray, float] – New MO coefficients, unitary for orb_init -> new orbitals, final value of objective function.

static orthonormalize(v, overlap=None)

Finds the closest orthonormal set of vectors with respect to overlap matrix.

Parameters:

  • v (ndarray) – Column vectors/molecular orbitals.

  • overlap (Optional[ndarray], default: None) – Overlap matrix.

Returns:

ndarray – Orthonormalized array of column vectors.

transform(v, tu)

Apply unitary, tu, to an array of column vectors.

Parameters:

  • v (ndarray) – Array of column vectors.

  • tu (ndarray) – Unitary matrix.

Returns:

ndarray – Transformed set of column vectors in numpy array.

class OrbitalTransformer(v_init=None, v_final=None)

Bases: object

Class holding convenience functions for manipulating molecular orbitals.

Initialized with initial and final orbital arrays.

Parameters:

  • v_init (Optional[ndarray], default: None) – Initial orbitals.

  • v_final (Optional[ndarray], default: None) – Final orbitals.

static compute_unitary(v_init=None, v_final=None, check_unitary=True, check_unitary_atol=CHECK_UNITARY_ATOL)

Computes the unitary relating square matrices v_init and v_final whose columns contain the initial and final orbitals.

Computes the matrix \(U = V_\text{init}^{-1} V_\text{final}\).

Parameters:

  • v_init (Optional[ndarray], default: None) – Initial orbitals.

  • v_final (Optional[ndarray], default: None) – Final orbitals.

  • check_unitary (bool, default: True) – Whether to check for the unitarity of the resulting matrix.

  • check_unitary_atol (float, default: CHECK_UNITARY_ATOL) – Absolute tolerance of unitarity check.

Returns:

ndarray – Unitary matrix relating initial and final orbitals.

static gram_schmidt(v, overlap=None)

Orthogonalizes column vectors in v using Gram-Schmidt algorithm with respect to an overlap matrix.

Parameters:

  • v (ndarray) – Orbitals/vectors to be orthonormalized.

  • overlap (ndarray, default: None) – Overlap matrix.

Returns:

ndarray – Orthogonalized vectors.

static orthonormalize(v, overlap=None)

Finds the closest orthonormal set of vectors with respect to overlap matrix.

Parameters:

  • v (ndarray) – Column vectors/molecular orbitals.

  • overlap (Optional[ndarray], default: None) – Overlap matrix.

Returns:

ndarray – Orthonormalized array of column vectors.

transform(v, tu)

Apply unitary, tu, to an array of column vectors.

Parameters:

  • v (ndarray) – Array of column vectors.

  • tu (ndarray) – Unitary matrix.

Returns:

ndarray – Transformed set of column vectors in numpy array.

class QubitOperator(data=None, coeff=1.0)

Bases: Operator

InQuanto’s representation of a linear operator acting on a \(2^N\) dimensional Hilbert space with Pauli operators.

Can be constructed from a string, a list or a tuple of tuples (containing a qubit index (integer) and a string with a Pauli gate symbol), a QubitOperatorString together with a single coefficient, or a dictionary with each item containing a QubitOperatorString and a coefficient.

Parameters:

Example

>>> op0 = QubitOperator("X0 Y1 Z3", 4.6)
>>> print(op0)
(4.6, X0 Y1 Z3)

>>> op1 = QubitOperator(((0, "X"), (1, "Y"), (3, "Z")), 4.6)
>>> print(op1)
(4.6, X0 Y1 Z3)

>>> op2 = QubitOperator([(0, "X"), (1, "Y"), (3, "Z")], 4.6)
>>> print(op2)
(4.6, X0 Y1 Z3)

>>> qs = QubitOperatorString.from_string("X0 Y1 Z3")
>>> op3 = QubitOperator(qs, 4.6)
>>> print(op3)
(4.6, X0 Y1 Z3)

>>> qs0 = QubitOperatorString.from_string("X0 Y1 Z3")
>>> qs1 = QubitOperatorString.from_tuple([(0, Pauli.Y), (1, Pauli.X)])
>>> dictionary = {qs0: 4.6, qs1: -1.7j}
>>> op4 = QubitOperator(dictionary)
>>> print(op4)
(4.6, X0 Y1 Z3), (-1.7j, Y0 X1)
class TrotterizeCoefficientsLocation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Determines where coefficients will be stored upon performing Trotterization.

INNER = 'inner'

All coefficients will be stored in the “inner” coefficients, within the component QubitOperators in the Trotterized result.

MIXED = 'mixed'

The Trotter step factor will be stored in the “outer” coefficients, whereas the original coefficients of the original Operator will remain in the component Operators.

OUTER = 'outer'

All coefficients will be stored in the “outer” coefficients, the coefficients stored directly in the generated OperatorList.

capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=-1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

property all_nontrivial_qubits: set[pytket._tket.unit_id.Qubit]

Returns a set of all qubits acted upon by this operator nontrivially (i.e. with an X,Y or Z).

property all_qubits: set[pytket._tket.unit_id.Qubit]

The set of all qubits the operator ranges over (including qubits that were provided explicitly as identities).

anticommutator(other_operator, abs_tol=None)

Calculates the anticommutator with another QubitOperator, within a tolerance.

Parameters:
Returns:

QubitOperator – The anticommutator of the two operators.

anticommutes_with(other_operator, abs_tol=ABS_TOL_OPERATOR)

Calculates whether operator anticommutes with another QubitOperator, within a tolerance.

If both operators are single Pauli strings, we use tket’s commutes_with() method and flip the result. Otherwise, it calculates the whole anticommutator and checks if it is zero.

Parameters:

  • other_operator (QubitOperator) – The other QubitOperator.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Threshold below which terms are deemed negligible.

Returns:

bool – True if operators anticommute, within tolerance, otherwise False.

antihermitian_part()

Return the anti-Hermitian (all imaginary-coefficient terms) part of the original QubitOperator.

In case the original QubitOperator object contains symbolic coefficients that do not have an associated type, those will be cast to the imaginary Expr type. :rtype: QubitOperator

Examples

>>> qo = QubitOperator.from_string("(1.0, X0 Y1), (0.1j, Y0 X1), (0.5 + 0.2j, Z0 Z1)")
>>> print(qo.antihermitian_part())
(0.1j, Y0 X1), (0.2j, Z0 Z1)
>>> a = Symbol('a', real=True)
>>> b = Symbol('b', imaginary=True)
>>> c = Symbol('c')
>>> p_str_a = QubitOperatorString.from_string("X0 Y1")
>>> p_str_b = QubitOperatorString.from_string("Y0 X1")
>>> p_str_c = QubitOperatorString.from_string("Z0 Z1")
>>> qo = QubitOperator({p_str_a: a, p_str_b: b, p_str_c: c})
>>> print(qo.antihermitian_part())
(b, Y0 X1), (1.0*I*im(c), Z0 Z1)
approx_equal_to(other, abs_tol=ABS_TOL_OPERATOR)

Checks if object’s dictionary values are numerically identical to the other object values.

Parameters:

  • other (LinearDictCombiner) – Object to compare to.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Threshold of comparing numeric values.

Raises:

TypeError – Comparison of two values can’t be done due to types mismatch.

Return type:

bool

approx_equal_to_by_random_subs(other, order=1, abs_tol=ABS_TOL_OPERATOR)

Checks if object’s dictionary values are numerically identical to the other object values.

Symbols contained in the difference of the two objects, if any, are substituted by random numeric values prior to norm check.

Parameters:

  • other (LinearDictCombiner) – Object to compare to.

  • order (int, default: 1) – Parameter specifying the norm formula (see numpy.linalg.norm() documentation).

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Threshold against which the norm of the difference is checked.

Return type:

bool

as_scalar(abs_tol=None)

If the operator is a sum of identity terms or zero, return the sum of the coefficients, otherwise return None.

Note that this does not perform combination of terms and will return zero only if all coefficients are zero.

Parameters:

abs_tol (float, default: None) – Tolerance for checking if coefficients are zero. Set to None to test using a standard

:param python == comparison.:

Returns:

Union[float, complex, None] – The operator as a scalar if it can be represented as such, otherwise None.

clone()

Performs shallow copy of the object.

Return type:

TypeVar(SYMBOLICTYPE, bound= Symbolic)

property coefficients: List[int | float | complex | Expr]

Returns dictionary values.

commutator(other_operator, abs_tol=None)

Calculate the commutator with another operator.

Computes commutator. Small terms in the result may be discarded.

Parameters:
Returns:

QubitOperator – The commutator.

commutes_with(other_operator, abs_tol=ABS_TOL_OPERATOR)

Calculates whether operator commutes with another QubitOperator, within a tolerance.

If both operators are single Pauli strings, we use tket. Otherwise, it calculates the whole commutator and checks if it is zero.

Parameters:

  • other_operator (QubitOperator) – The other QubitOperator.

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Threshold below which terms are deemed negligible.

Returns:

bool – True if operators commute, within tolerance, otherwise False.

compress(abs_tol=ABS_TOL_OPERATOR, symbol_sub_type=CompressSymbolSubType.NONE)

Combines duplicate terms, removing those with negligible coefficient.

Parameters:

  • abs_tol (float, default: ABS_TOL_OPERATOR) – Tolerance for comparing values to zero.

  • symbol_sub_type (Union[CompressSymbolSubType, str], default: CompressSymbolSubType.NONE) – Defines the behavior for dealing with symbolic expressions in coefficients. If “none”, symbolic expressions are left intact. If “unity”, substitutes all free symbols with 1, and removes all imaginary and real components below tolerance. If “random”, substitutes all free symbols with a random number between 0 and 1, and removes imaginary and real components below tolerance.

Warning

When symbol_sub_type != "none", this method assumes significant expression structure is known a priori, and is best suited to operators which have simple product expressions, such as excitation operators for VQE ansatzes and digital quantum simulation. Otherwise, it may remove terms relevant to computation. Each expression is of the form \(f(a_1,a_2,\ldots,a_n)\) for some symbols \(a_i\). \(|f(a_1,a_2,\ldots,a_n)|\) is assumed to monotonically increase in both real and imaginary components for all \(a_i \in [0, 1]\).

Returns:

LinearDictCombiner – Updated instance with negligible terms removed.

copy()

Performs deep copy of the object.

Return type:

TypeVar(SYMBOLICTYPE, bound= Symbolic)

dagger()

Return the Hermitian conjugate of QubitOperator.

Return type:

QubitOperator

df()

Returns a Pandas DataFrame object of the dictionary.

Return type:

DataFrame

dot_state(state, qubits=None)

Calculate the result of operating on a given qubit state.

Can accept right-hand state as a QubitState, QubitStateString or a numpy.ndarray. In the former two cases, we maintain a symbolic representation of both operator and state, and each Pauli is implemented in sequence. Resultant states are returned as QubitState. This should support sympy parametrized states and operators, but the use of parametrized states and operators is untested. In this case, the optional qubits parameter is ignored.

For a numpy.ndarray, we delegate to the dot_state_ndarray() method - this should be faster for dense states, but slower for sparse ones. Here, a register of qubits may be specified in the qubits parameter to determine the meaning of the indices of the provided state vector.

  • When qubits is an explicit list, the qubits are ordered with qubits[0] as the most significant qubit for indexing into state.

  • If None, qubits sequentially indexed from 0 in the default register and ordered by ILO-BE so Qubit(0) is the most significant.

Parameters:

  • state (Union[QubitState, QubitStateString, ndarray]) – Input qubit state to operated on.

  • qubits (Optional[List[Qubit]], default: None) – For ndarray input, determines sequencing of qubits in the state, if not mapped to the default register. Ignored for other input types.

Returns:

Union[QubitState, ndarray] – Output state.

dot_state_ndarray(state, qubits=None)

Applies the operator to the given state, mapping qubits to indexes according to qubits.

  • When qubits is an explicit list, the qubits are ordered with qubits[0] as the most significant qubit for indexing into state.

  • If None, qubits sequentially indexed from 0 in the default register and ordered by ILO-BE so Qubit(0) is the most significant.

Parameters:

  • state (ndarray) – The initial statevector.

  • qubits (Optional[list[Qubit]], default: None) – Sequencing of qubits in state, if not mapped to the default register.

Returns:

ndarray – The dot product of the operator with the statevector.

eigenspectrum(hamming_weight=None, nroots=None, threshold=HAMMING_WEIGHT_THRESHOLD, check_hermitian=False, check_hermitian_atol=ABS_TOL_OPERATOR)

Returns the eigenspectrum of a Hermitian operator, optionally filtered by a given Hamming weight.

More precisely, if hamming_weight is provided, only those eigenvalues whose eigenstates’ computational components have coefficients larger than threshold and match the provided Hamming weight will be returned.

If argument nroots is provided, an iterative sparse matrix diagonalization procedure is invoked. Otherwise, the whole dense matrix is diagonalized.

Notes

If this operator results from a Jordan-Wigner fermion-qubit encoding, filtering by Hamming weight corresponds to particle conservation. The operator is assumed to be Hermitian.

Warning

This method scales exponentially. Use only for testing on small systems.

Parameters:

  • hamming_weight (Optional[int], default: None) – Hamming weight for filtering the roots.

  • nroots (Optional[int], default: None) – How many roots to calculate (invokes iterative diagonalization).

  • threshold (float, default: HAMMING_WEIGHT_THRESHOLD) – State coefficient threshold for checking Hamming weight.

  • check_hermitian (bool, default: False) – Whether to check the hermiticity of the operator. Uses is_hermitian().

  • check_hermitian_atol (float, default: ABS_TOL_OPERATOR) – Absolute tolerance for hermiticity check. Passed to is_hermitian().

Returns:

ndarray – Array of (filtered) eigenvalues.

empty()

Checks if dictionary is empty.

Return type:

bool

ensure_hermitian(tolerance=ABS_TOL_OPERATOR)

Eliminate all insignificant imaginary parts of numeric coefficients.

Raises:

ValueError – imaginary symbolic, or significant imaginary numeric coefficient.

Parameters:

tolerance (float, default: ABS_TOL_OPERATOR) – Threshold determining whether a numerical imag coefficient is significant.

Returns:

QubitOperator – This instance.

evalf(*args, **kwargs)

Evaluates symbolic expressions stored in dict values and replaces them with the results.

Parameters:

  • args (Any) – Args to be passed to sympy.evalf().

  • kwargs (Any) – Kwargs to be passed to sympy.evalf().

Returns:

LinearDictCombiner – Updated instance of LinearDictCombiner.

exponentiate_commuting_operator(additional_exponent=1.0, check_commuting=True)

Exponentiate a QubitOperator where all terms commute, returning as a product of operators.

As all terms are mutually commuting, exponentiation reduces to a product of exponentials of individual terms (i.e. \(e^{\sum_i{P_i}} = \prod_i{e^{P_i}}\)). Each individual exponential can further be expanded trigonometrically. While storing these as a product is efficient, expanding the product will result in an exponential number of terms, and thus this method returns the result in factorized form, as a QubitOperatorList.

Parameters:

  • additional_exponent (complex, default: 1.0) – Optional additional factor in exponent.

  • check_commuting (bool, default: True) – Set to False to skip checking whether all terms commute.

Returns:

QubitOperatorList – The exponentiated operator in factorized form.

Raises:

ValueError – commutativity checking is performed and the operator is not a commuting set of terms.

exponentiate_single_term(additional_exponent=1.0, coeff_cutoff=COEFF_CUTOFF)

Exponentiates a single weighted Pauli string through trigonometric expansion.

This will except if the operator contains more than one term. It will attempt to maintain single term if rotation is sufficiently close to an integer multiple of \(pi/2\). Set coeff_cutoff to None to disable this behavior.

Parameters:

  • additional_exponent (complex, default: 1.0) – Optional additional factor in exponent.

  • coeff_cutoff (Optional[float], default: COEFF_CUTOFF) – If a Pauli string is weighted by an integer multiple of \(pi/2\) and exponentiated, the resulting expansion will have a single Pauli term (as opposed to two). If this parameter is not None, it will be used to determine a threshold for cutting off negligible terms in the trigonometric expansion to avoid floating point errors resulting in illusory growth in the number of terms. Set to None to disable this behavior.

Returns:

QubitOperator – The exponentiated operator.

Raises:

ValueError – the operator is not a single term.

free_symbols()

Returns the free symbols in the coefficient values.

free_symbols_ordered()

Returns the free symbols in the dict, ordered alphabetically.

Returns:

SymbolEnsemble – Ordered set of symbols.

classmethod from_QubitPauliOperator(qop, unsympify_coefficients=True)

Generate an instance of this class from a tket QubitPauliOperator.

Component QubitPauliStrings will be converted to QubitOperatorStrings. By default, coefficients without free symbols will be converted to float (if real) or complex (otherwise). To disable this, set unsympify_coefficients = False. For finer grained control over unsympification, generate with unsympify_coefficients = False and unsympify after generation. See unsympify() for further details.

Parameters:

  • qop (QubitPauliOperator) – The QubitPauliOperator to be converted.

  • unsympify_coefficients (bool, default: True) – Whether to cast coefficents to standard python float/complex. Set to False to disable.

Returns:

The converted operator.

classmethod from_serializable(pauli_list)

Construct a QubitOperator from a serializable JSON list format, as returned by to_list().

Parameters:

pauli_list (list[dict[str, Any]]) – The operator in serializable JSON list format.

Returns:

QubitOperator – The new QubitOperator instance.

Danger

Do not use this with untrusted input. Coefficients are unserialized with pickle, allowing arbitrary code execution.

classmethod from_string(input_string)

Constructs a child class instance from a string.

Parameters:

input_string (str) – String in the format coeff1 [(coeff1_1, term1_1), ..., (coeff1_n, term1_n)], ..., coeffn [(coeffn_1, termn_1), ...].

Returns:

Child class object.

get(key, default)

Get the coefficient value of the provided Pauli string.

Parameters:

key (QubitPauliString) –

hermitian_factorisation()

Returns a tuple of the real and imaginary parts of the original QubitOperator.

For example, both P and Q from \(O = P + iQ\).

In case the original QubitOperator object contains symbolic coefficients that do not have an associated type, those will be cast into both the real and imaginary Expr types and assigned to both objects (imaginary component will be multiplied by \(-I\) in order to return its real part).

Returns:

Tuple[QubitOperator, QubitOperator] – Real and imaginary parts of the qubit operator.

Examples

>>> qo = QubitOperator.from_string("(1.0, X0 Y1), (0.1j, Y0 X1), (0.5 + 0.2j, Z0 Z1)")
>>> re_qo, im_qo = qo.hermitian_factorisation()
>>> print(re_qo)
(1.0, X0 Y1), (0.5, Z0 Z1)
>>> print(im_qo)
(0.1, Y0 X1), (0.2, Z0 Z1)
>>> a = Symbol('a', real=True)
>>> b = Symbol('b', imaginary=True)
>>> c = Symbol('c')
>>> p_str_a = QubitOperatorString.from_string("X0 Y1")
>>> p_str_b = QubitOperatorString.from_string("Y0 X1")
>>> p_str_c = QubitOperatorString.from_string("Z0 Z1")
>>> qo = QubitOperator({p_str_a: a, p_str_b: b, p_str_c: c})
>>> re_qo, im_qo = qo.hermitian_factorisation()
>>> print(re_qo)
(a, X0 Y1), (re(c), Z0 Z1)
>>> print(im_qo)
(-I*b, Y0 X1), (im(c), Z0 Z1)
hermitian_part()

Return the Hermitian (all real-coefficient terms) part of the original QubitOperator.

In case the original QubitOperator object contains symbolic coefficients that do not have an associated type, those will be cast to the real Expr type. :rtype: QubitOperator

Examples

>>> qo = QubitOperator.from_string("(1.0, X0 Y1), (0.1j, Y0 X1), (0.5 + 0.2j, Z0 Z1)")
>>> print(qo.hermitian_part())
(1.0, X0 Y1), (0.5, Z0 Z1)
>>> a = Symbol('a', real=True)
>>> b = Symbol('b', imaginary=True)
>>> c = Symbol('c')
>>> p_str_a = QubitOperatorString.from_string("X0 Y1")
>>> p_str_b = QubitOperatorString.from_string("Y0 X1")
>>> p_str_c = QubitOperatorString.from_string("Z0 Z1")
>>> qo = QubitOperator({p_str_a: a, p_str_b: b, p_str_c: c})
>>> print(qo.hermitian_part())
(a, X0 Y1), (re(c), Z0 Z1)
classmethod identity()

Return an identity operator. :rtype: QubitOperator

Examples

>>> print(QubitOperator.identity())
(1.0, )
is_all_coeff_complex()

Check if all coefficients have complex values.

Returns:

bool – False if a non-complex value occurs before any free symbols in the dict values, or True if no non-complex values occur.

Warning

Returns None if a free symbol occurs before any non-complex values in the coefficients.

is_all_coeff_imag()

Check if all coefficients have purely imaginary values.

Returns:

bool – False if a non-complex value occurs before any free symbols in the dict values, or True if no non-complex values occur.

Warning

Returns None if a free symbol occurs before any non-imaginary values in the coefficients.

is_all_coeff_real()

Check if all coefficients have real values.

Returns:

bool – False if a non-real value occurs before any free symbols in the dict values, or True if no non-real values occur.

Warning

Returns None if a free symbol occurs before any non-real values in the dict coefficients.

is_all_coeff_symbolic()

Check if all coefficients contain free symbols.

Returns:

bool – Whether all coefficients contain free symbols.

is_antihermitian(tolerance=ABS_TOL_OPERATOR)

Check if operator is anti-Hermitian (purely imaginary coefficients).

Check is performed by looking for symbolic or significant numeric real part in at least one coefficient

Returns:

bool – True if anti-Hermitian, False otherwise.

Parameters:

tolerance (float, default: ABS_TOL_OPERATOR) –

is_any_coeff_complex()

Check if any coefficients have complex values.

Returns:

bool – True if a complex value occurs before any free symbols in the dict values, or False if no complex values occur.

Warning

Returns None if a free symbol occurs before any complex values in the coefficients.

is_any_coeff_imag()

Check if any coefficients have imaginary values.

Returns:

bool – True if an imaginary value occurs before any free symbols in the dict values, or False if no imaginary values occur.

Warning

Returns None if a free symbol occurs before any imaginary values in the coefficients.

is_any_coeff_real()

Check if any coefficients have real values.