inquanto.spaces¶

This module provides classes for representing various types of Hilbert spaces; chiefly useful in the generation of operators on those spaces.

class FermionSpace(n_spin_orb, point_group=None, orb_irreps=None)¶

Bases: OccupationSpace

A class providing utilities associated with a fermionic occupation space.

This mostly consists of tools to generate specific operators acting on and states within a given fermionic Hilbert space.

Parameters:

n_spin_orb (int) – The number of spin orbitals in the system.
point_group (UnionType[PointGroup, str, None], default: None) – The point group symmetry of the system.
orb_irreps (Optional[list[str]], default: None) – The point group irreducible representations of the orbitals.

COLUMN_ORB = 1¶: The orbital column in the table underlying this object.

COLUMN_SPIN = 0¶: The spin column in the table underlying this object.

SPIN_ALPHA = 0¶: Integer representation of alpha spin.

SPIN_BETA = 1¶: Integer representation of beta spin.

SPIN_DOWN = 1¶: Integer representation of spin down.

SPIN_UP = 0¶: Integer representation of spin up.

construct_contraction_mask_from_operators(operators)¶

Constructs a contraction mask based on the occurring indices in the operators.

This generates a boolean list, where the elements are True if the spin-orbital is acted upon by the operator or an operator in the list, otherwise False.

Parameters:: operators (FermionOperator | list[FermionOperator]) – An operator or list of operators.
Returns:: list[bool] – The mask defining the contraction.

construct_double_excitation_operators(fermion_state)¶

State-specific, occupied-to-virtual double excitations conserving azimuthal spin.

This corresponds to \(\hat{a}_{p}^{\dagger} \hat{a}_{q} \hat{a}_{r}^{\dagger} \hat{a}_{s}\).

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Representation of the reference fermionic number occupation vector.
Returns:: FermionOperatorList – The double excitation operators stored independently.

construct_double_ucc_operators(fermion_state)¶

Generate a FermionOperatorList of anti-Hermitian double excitation operators based on a reference fermion_state.

Each excitation is chemist ordered and consists of an “excitation” - “de-excitation”, \(a_p^{\dagger} a_q a_r^{\dagger} a_s - a_s^{\dagger} a_r a_q^{\dagger} a_p\), where \(p\) is virtual, \(q\) is occupied, \(r\) is virtual and \(s\) is occupied in fermion_state.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Reference fermionic occupation state.
Returns:: FermionOperatorList – The double excitation UCC operators stored independently.

construct_generalized_double_excitation_operators()¶

Construct generalized double excitations conserving azimuthal spin.

Generalized excitations include occupied-to-occupied and virtual-to-virtual excitation operators.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Returns:: FermionOperatorList – Generalized double excitation operators stored independently.

construct_generalized_double_ucc_operators()¶

Generate a FermionOperatorList of generalized anti-Hermitian double excitation operators.

Each UCC excitation consists of an “excitation - de-excitation”, \(\left( a_p^{\dagger} a_q - a_q^{\dagger} a_p \right)\), where \(p\), \(q\) are generalized indices, virtual-virtual, occupied-occupied, and occupied-virtual excitations are all allowed.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Notes

These excitations do not distinguish occupied and virtual spaces, therefore no reference state is required here. Note that spin crossover excitations (that change number of alphas/betas) are not allowed. See acs.jctc.8b01004 for further details.

Returns:: FermionOperatorList – Generalized double UCC operators stored independently.

construct_generalized_pair_double_excitation_operators()¶

Generalized pair-double excitations from molecular orbital to molecular orbital.

Generalized pair-double excitations include occupied-occupied, virtual-virtual and occupied-virtual double excitations from two spin orbitals with equivalent spatial components, to two spin orbitals with equivalent spatial components. This corresponds to \(\hat{a}_{p}^{\dagger} \hat{a}_{q} \hat{a}_{r}^{\dagger} \hat{a}_{s}\).

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Returns:: FermionOperatorList – Generalized MO-MO double excitations

construct_generalized_pair_double_ucc_operators()¶

Generate a FermionOperatorList of generalized anti-Hermitian pair-double excitation operators.

Each UCC excitation consists of an “excitation - de-excitation”, \(a_p^{\dagger} a_q a_r^{\dagger} a_s - a_s^{\dagger} a_r a_q^{\dagger} a_p\), where \(p\), \(q\), \(r\), \(s\) are generalized indices, but restricted to paired spins, so that \(p\), \(r\) are in one spatial orbital, and \(q\), \(s\) are in another spatial orbital.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Notes

Returns:: FermionOperatorList – Generalized MO-MO double excitations stored independently

construct_generalized_single_excitation_operators()¶

Construct generalized single excitations conserving azimuthal spin.

Generalized excitations include occupied-to-occupied and virtual-to-virtual excitations. This corresponds to \(\hat{a}_{p}^{\dagger} \hat{a}_{q} \hat{a}_{r}^{\dagger} \hat{a}_{s}\).

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Returns:: FermionOperatorList – Generalized single excitation operators stored independently.

construct_generalized_single_ucc_operators()¶

Generate a FermionOperatorList of generalized anti-Hermitian single excitation operators.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Notes

Returns:: FermionOperatorList – Generalized single UCC operators stored independently

construct_n_body_spinless_pdm_operators(rank)¶

Return an array of FermionOperator objects for measurement of spin-traced \(n\)-body pre-density matrix.

PDM is what is called the pre-density matrix in Orca and returned by pyscf.fci.rdm.make_dm1234. In this function, pdm2[p,q,r,s] is \(\sum_{\sigma\tau}a_{p_\sigma}^{\dagger} a_{q_\sigma} a_{r_\tau}^{\dagger} a_{s_\tau}\) pdm3[p,q,r,s,t,u] is \(\sum_{\sigma\tau\mu}a_{p_\sigma}^{\dagger} a_{q_\sigma} a_{r_\tau}^{\dagger} a_{s_\tau} a_{t_\mu}^{\dagger} a_{u_\mu}\). pdm4[p,q,r,s,t,u,v,w] is \(\sum_{\sigma\tau\mu\nu} a_{p_\sigma}^{\dagger}a_{q_\sigma} a_{r_\tau}^{\dagger} a_{s_\tau} a_{t_\mu}^{\dagger} a_{u_\mu} a_{v_\nu}^{\dagger} a_{w_\nu}\). where \(\sigma, \tau, \mu, \nu\) are spin indices. The 1-PDM is the same as the 1-RDM.

Parameters:: rank (int) – Rank \(n\) of the \(n\)-PDM.
Returns:: ndarray[tuple[Any, ...], dtype[Any]] – A \(2n\)-dimensional matrix of FermionOperator objects.

construct_n_body_spinless_rdm_operators(rank, ordering='p^r^sq')¶

Return an array of FermionOperator objects for measurement of spin-traced \(n\)-body reduced density matrix.

Parameters:

rank (int) – Rank \(n\) of the \(n\)-RDM.
ordering (str, default: "p^r^sq") –
Ordering of the spatial orbital indices given by either "p^r^sq" or "p^q^sr". This choice is expressed in terms of the indices of the 2-RDM because that is the lowest rank of RDM for which these orderings are non-equivalent. The returned array element of the e.g. 2-RDM accessed with indices [p,q,r,s] corresponds to operator terms of either \(\sum_{\sigma\tau} a_{p_\sigma}^{\dagger} a_{r_\tau}^{\dagger} a_{s_\tau} a_{q_\sigma}\) with ordering="p^r^sq", or \(\sum_{\sigma\tau} a_{p_\sigma}^{\dagger} a_{q_\tau}^{\dagger} a_{s_\tau} a_{r_\sigma}\) with ordering="p^q^sr", where \(\sigma, \tau\) are spin indices.

The returned array element of the e.g. 3-RDM accessed with indices [p,q,r,s,t,u] corresponds to operator terms of either \(\sum_{\sigma\tau\mu} a_{p_\sigma}^{\dagger} a_{r_\tau}^{\dagger} a_{t_\mu}^{\dagger} a_{u_\tau} a_{s_\sigma} a_{q_\mu}\) with ordering="p^r^sq", or \(\sum_{\sigma\tau\mu} a_{p_\sigma}^{\dagger} a_{q_\tau}^{\dagger} a_{r_\mu}^{\dagger} a_{u_\tau} a_{t_\sigma} a_{s_\mu}\) with ordering="p^q^sr", where \(\sigma, \tau, \mu\) are spin indices.

Returns:

ndarray[tuple[Any, ...], dtype[Any]] – A \(2n\)-dimensional matrix of FermionOperator objects.

construct_number_alpha_operator()¶

Construct a FermionOperator which represents a number operator acting on all alpha spin orbitals.

Returns:: FermionOperator – The number operator over alpha spin-orbitals only.

construct_number_beta_operator()¶

Construct a FermionOperator which represents a number operator acting on all beta spin orbitals.

Returns:: FermionOperator – The number operator over beta spin-orbitals only.

construct_number_operator()¶

Creates and returns a FermionOperator representation of the number operator.

The FermionOperator acts on the entire set of spin orbitals.

Returns:: FermionOperator – The number operator of the fermionic space.

construct_one_body_operator_from_integral(one_body_spatial, spins, spatial_mask=None)¶

Constructs a one-body operator from a one-body spatial integral array.

The indices are transformed to spin-orbital notation, with spin-minor ordering (i.e. alternating alpha and beta spins). The one-body operator is given by \(\hat{h} = \sum_{pq} h_{pq} a^\dagger_p a_q\), where \(h_{pq}\) are the one-body integrals.

Parameters:

one_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation.
spins (tuple[int, int]) – The spin configuration, e.g. (0,0) = (SPIN_UP, SPIN_UP).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.

Returns:

FermionOperator – The one-body Hamiltonian operator.

construct_one_body_spatial_rdm_operators(spins, spatial_mask=None, operator_pattern=(1, 0))¶

Construct a rank-2 numpy.ndarray with FermionOperator as the data type.

Parameters:

spins (tuple[int, int]) – The corresponding spins as \((s_i,s_j)\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.
operator_pattern (tuple[int, int], default: (1, 0)) – The creation and annihilation ordering of the terms in the array. Must be a length 2 tuple containing ones and zeros, which correspond to creation and annihilation operators, respectively.

Returns:

ndarray[tuple[Any, ...], dtype[Any]] – The one body spatial RDM operator as a rank-2 array of FermionOperator objects.

static construct_operator_from_string(input)¶

Construct an operator from a string.

Parameters:: input (str) – String representation of a FermionOperator.
Returns:: FermionOperator – An instance of FermionOperator corresponding to the string provided.

construct_orbital_number_operators()¶

Construct a list of FermionOperator objects, where each element is a number operator on a specific spin orbital.

The position in the returned list corresponds to the spin orbital index.

Returns:: list[FermionOperator] – The individual orbital number operators.

static construct_scalar_operator(value)¶

Construct a FermionOperator consisting of only the identity term multiplied by a scalar coefficient.

Parameters:: value (float) – Coefficient multiplying the identity term.
Returns:: FermionOperator – A fermionic operator containing a single identity term multiplied by a scalar coefficient.

construct_single_excitation_operators(fermion_state)¶

State-specific single excitations conserving azimuthal spin.

This includes only occupied-to-virtual excitations corresponding to the fermion_state argument.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Representation of the reference fermionic number occupation vector.
Returns:: FermionOperatorList – The single excitation operators which excite occupied orbitals in the input state.

construct_single_tUPS_layer(layer_idx=0, orbital_optimisation=False, orbital_perfect_pairing=False)¶

Construct a full tUPS layer.

Join the first half and second half layers together as shown in Eq 3 and Fig 1a of https://doi.org/10.1103/PhysRevResearch.6.023300. The indices refer to qubit indices, rather than spatial orbital indices due to the implementation of perfect pairing. These will get permuted to ensure that the tUPS boxes only connect nearest neighbour qubits.

Parameters:

layer_idx (int, default: 0) – Default 0. Index of the layer to produce the tiling.
orbital_optimisation (bool, default: False) – Default False. If true construct the orbital optimisation tiles.
orbital_perfect_pairing (bool, default: False) – Default False. If True, connect spatial orbitals as bonding-antibonding pairs instead of nearest neighbours. This introduces extra Z strings in the operators.
qubit_perfect_pairing (bool) – Default False. If True, “move” the qubits such that nearest neighbours correspond to bonding-antibonding pairs.

Returns:

tiled_layer – Base initialised FermionOperatorList corresponding to the full tiled layer.

construct_single_ucc_operators(fermion_state)¶

Generate anti-Hermitian single excitation operators based on a reference fermion_state.

Each UCC excitation consists of an “excitation - de-excitation”, \(\left( a_p^{\dagger} a_q - a_q^{\dagger} a_p \right)\), where \(p\) is virtual and \(q\) is occupied.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Reference fermionic occupation state.
Returns:: FermionOperatorList – The UCC single operators which excite occupied orbitals in the provided state.

construct_singlet_double_excitation_operators(fermion_state)¶

Generate a FermionOperatorList of spin-adapted singlet double excitation operators based on a reference fermion_state.

Each excitation is chemist ordered and spin-traced, \(a_{p_0}^{\dagger} a_{q_0} a_{r_0}^{\dagger} a_{s_0} +\) \(a_{p_1}^{\dagger} a_{q_1} a_{r_0}^{\dagger} a_{s_0} +\) \(a_{p_0}^{\dagger} a_{q_0} a_{r_1}^{\dagger} a_{s_1} +\) \(a_{p_1}^{\dagger} a_{q_1} a_{r_1}^{\dagger} a_{s_1}\), where \(p\) is virtual, \(q\) is occupied, \(r\) is virtual and \(s\) is occupied.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Representation of the reference fermionic number occupation vector.
Returns:: FermionOperatorList – The spin-adapted singlet double excitation operators which excite occupied orbitals in the reference state.

construct_singlet_double_ucc_operators(fermion_state)¶

Generate a FermionOperatorList of anti-Hermitian singlet double excitation operators based on a reference fermion_state.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Reference fermionic occupation state.
Returns:: FermionOperatorList – The singlet UCC double excitations which excite occupied orbitals in the input state.

construct_singlet_generalized_double_excitation_operators()¶

Construct generalized double excitations conserving azimuthal spin and adapted for singlet spin symmetry.

Generalized excitations include occupied-to-occupied, virtual-to-virtual and occupied-to-virtual excitations.

Each excitation is chemist ordered and spin-traced, \(a_{p_0}^{\dagger} a_{q_0}^{\dagger} a_{r_0} a_{s_0} + a_{p_1}^{\dagger} a_{q_1}^{\dagger} a_{r_1} a_{s_1}\), where 0 and 1 indicate alpha and beta spin, respectively.

Returns:: FermionOperatorList – The generalized double excitations.

construct_singlet_generalized_single_excitation_operators()¶

Generalized single excitations conserving azimuthal spin and adapted for singlet spin symmetry.

Generalized excitations include occupied-to-occupied, virtual-to-virtual and occupied-to-virtual excitations.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Each excitation is chemist ordered and spin-traced, \(a_{p_0}^{\dagger} a_{q_0} + a_{p_1}^{\dagger} a_{q1}\), where 0 and 1 indicate alpha and beta spin, respectively.

Returns:: FermionOperatorList – The singlet generalized single excitations.

construct_singlet_generalized_single_ucc_operators()¶

Generate a FermionOperatorList of generalized anti-Hermitian single singlet spin-adapted excitation operators.

Each UCC excitation consists of an “excitation - de-excitation”, \(\left( a_p^{\dagger} a_q - a_q^{\dagger} a_p \right)\), where both \(p\) and \(q\) run over occupied and virtual orbitals.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Notes

Returns:: FermionOperatorList – The singlet generalized UCC single excitations.

construct_singlet_single_excitation_operators(fermion_state)¶

Generate a FermionOperatorList of spin-adapted singlet single excitation operators based on a reference fermion_state.

Each excitation is chemist ordered and spin-traced, \(a_{p_0}^{\dagger} a_{q_0} + a_{p_1}^{\dagger} a_{q1}\), where \(p\) is virtual, \(q\) is occupied, and 0 or 1 determine alpha or beta spin, respectively.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – Representation of the reference fermionic number occupation vector.
Returns:: FermionOperatorList – The singlet single excitation operators which excite occupied orbitals in the input state.

construct_singlet_single_ucc_operators(fermion_state)¶

Generate a FermionOperatorList of anti-Hermitian singlet single excitation operators based on a reference fermion_state.

Each UCC excitation consists of an “excitation - de-excitation”, \(\left( a_p^{\dagger} a_q - a_q^{\dagger} a_p \right)\), where \(p\) is virtual and \(q\) is occupied in fermion_state.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Parameters:: fermion_state (FermionState) – A fermionic occupation state.
Returns:: FermionOperatorList – The singlet UCC single excitation operators which excite occupied orbitals in the input state

construct_spatial_indexed_pair_double_operators(spatial_indices=None)¶

Construct the specified generalised anti-Hermitian pair double excitations.

If none are specified, generate 1 instance of each pair double excitation for all pairs of spatial orbitals in the space.

Parameters:

spatial_orbital_indices – Default None. If None, iterate once through all combinations, else use the provided ordered sequence, annhiliate index is first. If None, the operator list should be identical to self.construct_generalized_pair_double_ucc_operators()
spatial_indices (Optional[Sequence[tuple[int, int]]], default: None)

Returns:

FermionOperatorList – fermion_operator_list (FermionOperatorList) –

Base initialised FermionOperatorList using: the sequence of operators provided, coefficient 1 and symbols constructed as ‘(_{annhilate_idx}^{create_idx}d_{index})’

construct_spatial_indexed_sUPS_operators(excitations)¶

Construct the specified sequence of spin adapted singles and pair double excitations.

These are operators as defined in https://doi.org/10.1038/s41534-023-00744-2. Operators can be repeated and appear as many times as required.

Parameters:

excitations (Sequence[tuple[str, int, int]]) – Sequence of excitations indexed by (s/d, annihilate_idx, create_idx) where “s”/”d” refer to single or double excitations respectively.

Returns:

FermionOperatorList – fermion_operator_list –

Base initialised FermionOperatorList using: the sequence of operators provided, coefficient 1 and symbols constructed as ‘(_{annhilate_idx}^{create_idx}{operator_type}_{index})’

construct_spatial_indexed_spin_adapted_single_operators(spatial_indices=None)¶

Construct the specified generalised anti-Hermitian spin adapted single excitations.

If none are specified, generate 1 instance of each spin adapted single for all pairs of spatial orbitals in the space.

Parameters:

spatial_orbital_indices – Default None. If None, iterate once through all combinations, else use the provided ordered sequence, annhiliate index is first. If None, the operator sequence should be identical to self.construct_singlet_generalized_single_ucc_operators()
spatial_indices (Optional[Sequence[tuple[int, int]]], default: None)

Returns:

FermionOperatorList – fermion_operator_list –

Base initialised FermionOperatorList using: the sequence of operators provided, coefficient 1 and symbols constructed as ‘(_{annhilate_idx}^{create_idx}s_{index})’

construct_spin_operator()¶

This function creates and returns a FermionOperator representation of the \(\hat{S}^2\) operator.

Returns:: FermionOperator – The \(\hat{S}^2\) operator.

construct_sz_operator()¶

This function creates and returns a FermionOperator representation of the \(\hat{S}_z\) operator.

Returns:: FermionOperator – The \(\hat{S}_z\) operator.

construct_tUPS_orbital_optimisation_operators(orbital_perfect_pairing=False)¶

Construct the orbital optimisation circuit to be appended to the tUPS circuit.

This is shown in Fig 3 in https://doi.org/10.1103/PhysRevResearch.6.023300. The number of layers is defined through requiring (N)(N-1)/2 total operators, where N is number of spatial MOs.

Parameters:

orbital_perfect_pairing (bool, default: False) – Default False. If True, connect spatial orbitals as bonding-antibonding pairs instead of nearest neighbours.This introduces extra Z strings in the operators.
qubit_perfect_pairing – Default False. If True, “move” the qubits such that nearest neighbours correspond to bonding-antibonding pairs.

Returns:

FermionOperatorList – orbital_optimisation_tiled –

Base initialised FermionOperatorList corresponding to the: layered orbital optimisation circuit.

construct_triplet_generalized_single_excitation_operators()¶

Construct generalized single excitations conserving azimuthal spin and adapted for triplet spin symmetry.

Each excitation is chemist ordered and spin-traced, \(a_{p_0}^{\dagger} a_{q_0} - a_{p_1}^{\dagger} a_{q1}\), \(a_{p_0}^{\dagger} a_{q_1}\), or \(a_{p_1}^{\dagger} a_{q_0}\), where \(p\) is virtual, \(q\) is occupied, and 0 or 1 determine alpha or beta spin, respectively.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Returns:: FermionOperatorList – The triplet generalized single excitation operators.

construct_triplet_generalized_single_ucc_operators()¶

Generate a FermionOperatorList of generalized anti-Hermitian single excitation operators, spin adapted to a triplet.

Each UCC excitation consists of an “excitation - de-excitation”, \(\left( a_p^{\dagger} a_q - a_q^{\dagger} a_p \right)\), where p, q are generalized indices.

If the FermionSpace instance has a defined point group symmetry it is used by default, possibly reducing the number of excitation operators.

Notes

Returns:: FermionOperatorList – Generalized triplet anti-Hermitian single excitation operators

construct_two_body_operator_from_integral(two_body_spatial, spins, spatial_mask=None)¶

Constructs a two-body operator from a two-body spatial integral array.

\(\sum_{ijkl} (ij|kl) a^{\dagger}_{i,s_i} a^{\dagger}_{k,s_k} a_{l,s_l} a_{j,s_j}\) where \(s_i,s_j,s_k,s_l \in \{0, 1\}\) are the elements of spins.

Notes

The integrals are in chemist’s notation, i.e. two_body_spatial[i,j,k,l] = \((ij|kl)\).

Parameters:

two_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation.
spins (tuple[int, ...]) – The corresponding spins as \((s_i,s_j,s_k,s_l)\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – mask filtering the generations of terms in the operator.

Returns:

FermionOperator – The two-body Hamiltonian operator.

construct_two_body_operator_from_tensor(two_body_tensor, spins, spatial_mask=None)¶

Constructs a two-body operator from a two-body spatial integral array.

That is, \(\sum_{ijkl} (ij|kl) a^{\dagger}_{i,s_i} a^{\dagger}_{k,s_k} a_{l,s_l} a_{j,s_j}\) where \(s_i,s_j,s_k,s_l \in \{0, 1\}\) are the elements of spins.

Notes

The integrals are in chemist’s notation, that is two_body_tensor[i,k,l,j] = \((ij|kl)\). The difference from the two_body_spatial argument to construct_two_body_operator_from_integral() is how the two electron integral is encoded in a tensor format. It is recommended to use construct_two_body_operator_from_integral() and two_body_spatial[i,j,k,l] = \((ij|kl)\). This method is for compatibility.

Parameters:

two_body_tensor (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation.
spins (tuple[int, int, int, int]) – The corresponding spins as \((s_i,s_j,s_k,s_l)\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.

Returns:

FermionOperator – The two-body Hamiltonian operator.

construct_two_body_spatial_rdm_operators(spins, spatial_mask=None, operator_pattern=(1, 1, 0, 0))¶

Construct a rank-4 array of FermionOperator objects corresponding to two-particle reduced density matrix elements.

Parameters:

spins (tuple[int, int, int, int]) – The corresponding spins as \((s_i,s_j,s_k,s_l)\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.
operator_pattern (tuple[int, int, int, int], default: (1, 1, 0, 0)) – The creation and annihilation ordering of the terms in the array. Must be a length 4 tuple containing ones and zeros, which correspond to creation and annihilation operators, respectively.

Returns:

ndarray[tuple[Any, ...], dtype[Any]] – The two body spatial RDM operators.

contract_occupation_space(active_spatial_orbs)¶

Generate an occupation space with a set of restricted spatial orbitals.

Parameters:: active_spatial_orbs (list[int]) – Indices of spatial orbitals considered to be active.
Returns:: tuple[FermionSpace, list[bool]] – The contracted occupation space and the contraction mask.

static contract_occupation_state(occupation_state, contraction_mask)¶

Contracts fermion state according to a mask.

Parameters:

occupation_state (FermionState) – A FermionState to be contracted.
contraction_mask (list[bool]) – Mask, where True, the spin-orbital is frozen.

Returns:

FermionState – The contracted state.

static contract_operator(fermion_state, contraction_mask, operator)¶

Contracts operator according to a mask and the fermion state.

Freezes spin-orbitals according to the known occupation numbers in fermion state.

Notes

This currently works only with inquanto.operators.FermionOperator.

Parameters:

fermion_state (FermionState) – The reference fermionic state.
contraction_mask (list[bool]) – Mask, where True, the spin-orbital is frozen.
operator (list[FermionOperator] | FermionOperator) – The operator to be contracted.

Returns:

list[FermionOperator] | FermionOperator – The contracted operator.

static contract_state_mask(state_mask, contraction_mask)¶

Contracts mask according to another mask.

Parameters:

state_mask (list[bool]) – A state mask.
contraction_mask (list[bool]) – Mask defining a contraction.

Returns:

list[bool] – The contracted mask.

contracted_system(contraction_mask, fermion_state, *operators)¶

Contract system (space, state and operator(s)) according to the reference state and a contraction mask.

Parameters:

contraction_mask (list[bool]) – Mask, where True, the orbital is frozen.
fermion_state (FermionState) – Fermionic occupation state to be contracted.
operators (FermionOperator) – One or more FermionOperator instances to be contracted.

Returns:

tuple[FermionSpace, FermionState, list[FermionOperator]] – The contracted FermionSpace, contracted FermionState, and contracted FermionOperator objects.

static convert_mask_to_index_map(mask)¶

Convert a mask into an index mapping.

Parameters:: mask (ndarray[tuple[Any, ...], dtype[bool]] | list[bool]) – A boolean mask with the length of the fock space.
Returns:: list[Optional[int]] – Positional indices of mask elements with value True.

count(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶

Counts spin orbitals or modes according to the relevant quantum number and state value.

This is a deprecated legacy method and will be removed in subsequent releases.

Notes

If some value is None, then it is counted.

Parameters:

fermion_state (Optional[FermionState], default: None) – A FermionState object.
state_value (int, default: 1) – 1/0 signifying occupied/unoccupied, respectively.
column (Optional[int], default: None) – The column index in the quantum number table.
column_value (Optional[int], default: None) – The value to be counted.
state_mask (Optional[list[bool]], default: None) – State mask defining which spin orbitals or modes are included in the count.

Returns:

int – Number of orbitals or modes satisfying the input arguments.

static from_state(fermion_state)¶

Initialize a FermionSpace from an input fermion state.

Parameters:: fermion_state (FermionState) – A FermionState instance representing a fermionic state vector.
Returns:: FermionSpace – An instance of FermionSpace with \(C_1\) point group symmetry and n_spin_orb equal to the size of the FermionState input.

generate_cyclic_masks(window, shift=None)¶

Generate a complete set of masks with windows shifted by window/2 if the shift argument is not provided.

Parameters:

window (int) – Number of spin orbitals in the window.
shift (Optional[int], default: None) – Size of the steps to take along the occupation number vector when defining the windows.

Returns:

ndarray[tuple[Any, ...], dtype[bool]] – Complete set of masks.

Examples

>>> space = FermionSpace(8)
>>> space.generate_cyclic_masks(window=4, shift=2)
array([[ True,  True,  True,  True, False, False, False, False],
       [False, False,  True,  True,  True,  True, False, False],
       [False, False, False, False,  True,  True,  True,  True],
       [ True,  True, False, False, False, False,  True,  True]])

generate_cyclic_window_mask(window, shift=0)¶

Generate a mask with a window and shift.

The window defines how many elements in the result are True, with the shift determining the start index of the window. See below for example.

Parameters:

window (int) – Number of spin orbitals within the window.
shift (int, default: 0) – The position in the occupation number vector to begin the window.

Returns:

ndarray[tuple[Any, ...], dtype[float64]] – Booleans defining the mask.

Examples

>>> space = FermionSpace(8)
>>> space.generate_cyclic_window_mask(window=4, shift=2)
array([False, False,  True,  True,  True,  True, False, False])

generate_occupation_state(n_fermion=0, multiplicity=None)¶

Generate an instance of FermionState with a variable number of fermions.

Fermions are placed in lower indexed orbitals first. The number of unpaired alpha electrons is given by the multiplicity minus one.

Parameters:

n_fermion (int, default: 0) – Number of Fermions to include in FermionState.
multiplicity (Optional[int], default: None) – Multiplicity of the generated FermionState.

Returns:

FermionState – The generated fermionic state.

generate_occupation_state_from_list(occupation_state_list=None)¶

Convert spin-orbital occupation numbers to a FermionState.

Parameters:: occupation_state_list (Optional[list[int]], default: None) – Represents spin-orbital occupations. Default value is None, which returns the all zeros FermionState (i.e. the vacuum state).
Returns:: FermionState – The generated fermionic state.

generate_occupation_state_from_spatial_occupation(occupation)¶

Generates a state from spatial orbital occupation numbers.

Parameters:: occupation (list[int]) – \(n\) entries with values of 0, 1, or 2, where \(n\) is the number of spatial orbitals. Each entry indicates the occupation number of the corresponding spatial orbital.
Returns:: FermionState – The generated fermionic state.

generate_subspace_singles()¶

Sequentially yield all single excitation operators as FermionOperator objects.

Yields:: FermionOperator objects corresponding to single excitations.

generate_subspace_singlet_singles()¶

Sequentially yield spin-adapted singlet-single excitation operators to maintaining spin symmetry.

Yields:: FermionOperator objects corresponding to spin-adapted singlet single excitation operators.

generate_subspace_triplet_singles()¶

Sequentially yield triplet-single excitation operators (subspace of the singlet-singles operators).

Yields:: FermionOperator objects corresponding to spin-adapted, triplet single excitation operators.

get_orb_irreps_dataframe()¶

Return a pandas DataFrame listing orbitals and their respective irreducible representations.

Assumes spin minor ordering of spin orbitals i.e. [0a, 0b, 1a, 1b...].

Returns:: DataFrame – Dataframe detailing orbital irreps.

index(orb, spin)¶

Encode spatial orbital index and spin index as a spin orbital index.

Parameters:

orb (int) – Spatial orbital index.
spin (int) – Alpha spin (0) or beta spin (1).

Returns:

int – The spin-orbital index.

classmethod load_h5(name)¶

Loads operator object from .h5 file.

Parameters:: name (str | Group) – The filename to load from.
Return type:: Self

property n_orb: int¶: Number of spatial orbitals.

property n_spin_orb: int¶: Return the number of spin-orbitals.

operator_to_latex(fermion_operator, **kwargs)¶

Generate a LaTeX representation of an operator in this occupation space.

Operator indices will show degrees of freedom relevant to parent occupation space.

Parameters:

fermion_operator (FermionOperator | FermionOperatorString) – Operator to convert to LaTeX representation.
**kwargs (Any) – Keyword arguments passed to the FermionOperatorString.to_latex() method of component operator strings, FermionOperatorString.

Returns:

str – LaTeX compilable equation string.

Examples

>>> from inquanto.spaces import FermionSpace
>>> fs = FermionSpace(10)
>>> fo = FermionOperator([(1.0, "F1 F1^"), (2+4j, "F2^ F0")])
>>> print(fs.operator_to_latex(fo))
a_{0\downarrow} a_{0\downarrow}^{\dagger} + (2.0+ 4.0\text{i}) a_{1\uparrow}^{\dagger} a_{0\uparrow}

orb_irreps()¶

Get orbital irreducible representations.

Returns:: list[str] – Orbital irreps.

point_group(as_string=True)¶

Return the point group symmetry of the space.

Parameters:: as_string (bool, default: True) – If True, returns name of point group as string. If False, returns an InQuanto PointGroup object.
Returns:: str | PointGroup – Point group symmetry.

print_state(fermion_state, *state_masks)¶

Prints a fermion state with quantum number information.

If the state_masks argument is provided, a column is added to the print for, with an X marking the elements of the mask which are True.

Parameters:

fermion_state (FermionState) – Fermion state to print.
state_masks (list[bool]) – A mask to include in the print, as described above.

Return type:

None

Examples

>>> from inquanto.spaces import FermionSpace
>>> space = FermionSpace(8)
>>> mask = space.generate_cyclic_window_mask(window=4, shift=2)
>>> state = space.generate_occupation_state_from_list([1, 1, 1, 1, 0, 0, 0, 0])
>>> space.print_state(state, mask)
 0 0a         :  1    .
 1 0b         :  1    .
 2 1a         :  1    X
 3 1b         :  1    X
 4 2a         :  0    X
 5 2b         :  0    X
 6 3a         :  0    .
 7 3b         :  0    .

quantum_label(i)¶

Generates a label for a given spin-orbital formed as a concatenation of its quantum numbers.

Parameters:: i (int) – Spin orbital index.
Returns:: str – Label storing all quantum numbers.

quantum_number(i)¶

Converts the spin orbital index to a tuple of quantum numbers.

These quantum numbers are spatial orbital and spin index corresponding to the input spin orbital index.

Parameters:: i (int) – Spin orbital index.
Returns:: tuple[int, int] – Spatial orbital and spin index.

quantum_number_orb(i)¶

Get spatial orbital index from a spin orbital index.

Parameters:: i (int) – Spin orbital index.
Returns:: int – The spatial orbital index.

quantum_number_spin(i)¶

Get spin index from a spin orbital index.

Parameters:: i (int) – Spin orbital index.
Returns:: int – Spin index, alpha spin is 0, and beta spin is 1.

save_h5(name)¶

Dumps operator object to .h5 file.

Parameters:: name (str | Group) – The filename to save to.
Return type:: None

symmetry_operators_z2(spin_ordering='abab', point_group=True, return_factorized=False)¶

Constructs symmetry operators corresponding to point group, spin- and particle-number parity \(\mathbb{Z}_2\) symmetries.

Danger

Where return_factorized is set to False (the default behavior!) this may blow up exponentially. Set return_factorized to True to avoid this problem by returning symmetry operators as SymmetryOperatorFermionicFactorized.

Parameters:

spin_ordering (Optional[str], default: "abab") – The spin-orbital ordering - "abab" for alpha-beta-alpha-beta or "aabb" for alpha-alpha-beta-beta. Pass None to skip spin parity symmetry entirely.
point_group (bool, default: True) – Set to False to not return point group symmetries.
return_factorized (bool, default: False) – Set to True to return symmetry operators as SymmetryOperatorFermionicFactorized. This avoids exponential growth in terms when expanding the symmetry operator, but returns as the less general SymmetryOperatorFermionicFactorized class.

Returns:

list[SymmetryOperatorFermionicFactorized] | list[SymmetryOperatorFermionic] – The \(\mathbb{Z}_2\) symmetry operators in a format determined by the return_factorized argument.

symmetry_operators_z2_in_sector(fermion_state, spin_ordering='abab', point_group=True, return_factorized=False)¶

Constructs \(\mathbb{Z}_2\) symmetry operators which stabilize a provided state.

Symmetry operators returned correspond to the point group, spin parity and particle number parity \(\mathbb{Z}_2\) symmetries, as per symmetry_operators_z2().

Global phases on the symmetry operators here are such that the returned operators stabilize the provided fermion_state - i.e. if the symmetry operator has an expectation value of -1 with the provided fermion state, then the symmetry operator will be multiplied by -1. This is in contrast to symmetry_operators_z2(), which returns operators without an additional global phase.

Danger

Parameters:

fermion_state (FermionState) – A reference state required to define a symmetry sector.
spin_ordering (Optional[str], default: "abab") – The spin-orbital ordering - "abab" for alpha-beta-alpha-beta or "aabb" for alpha-alpha-beta-beta. Pass None to skip spin parity symmetry entirely.
point_group (bool, default: True) – Set to False to not return point group symmetries.
return_factorized (bool, default: False) – Set to True to return symmetry operators as SymmetryOperatorFermionicFactorized. This avoids exponential growth in terms when expanding the symmetry operator, but returns as the less general SymmetryOperatorFermionicFactorized class.

Returns:

list[SymmetryOperatorFermionic | SymmetryOperatorFermionicFactorized] – The \(\mathbb{Z}_2\) symmetry operators in format determined by the return_factorized argument.

class FermionSpaceBrillouin(n_spin_orb, n_kp, conservation)¶

Bases: OccupationSpace

FermionSpace for the momentum representation of a periodic system.

Parameters:

n_spin_orb (int) – The number of spin orbitals.
n_kp (int) – The number of k-points.
conservation (list[list[list[int]]]) – Momentum conservation table generated by PySCF.

COLUMN_KP = 0¶: Column of the underlying table corresponding to k-points.

COLUMN_ORB = 1¶: Column of the underlying table corresponding to orbitals.

COLUMN_SPIN = 2¶: Column of the underlying table corresponding to spin.

SPIN_ALPHA = 0¶: Integer representation of alpha spin.

SPIN_BETA = 1¶: Integer representation of beta spin.

SPIN_DOWN = 1¶: Integer representation of spin down.

SPIN_UP = 0¶: Integer representation of spin up.

construct_contraction_mask_from_operators(operators)¶

Constructs a contraction mask based on the occurring indices in the operators.

This generates a boolean list, where the elements are True if the spin-orbital is acted upon by the operator or an operator in the list, otherwise False.

Parameters:: operators (FermionOperator | list[FermionOperator]) – An operator or list of operators.
Returns:: list[bool] – The mask defining the contraction.

construct_number_operator(kp)¶

Creates and returns a FermionOperator representation of the number operator for a given k-point.

Parameters:: kp (int) – The k-point index.
Returns:: FermionOperator – The number operator for the provided k-point.

construct_one_body_operator_from_integral(one_body_spatial, spins, kpoints, spatial_mask=None)¶

Constructs a one-body operator from one-body spatial integral.

Parameters:

one_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist notation.
spins (tuple[int, int]) – The spins, e.g. (0,0) = (SPIN_UP, SPIN_UP).
kpoints (tuple[int, int]) – The k-points, e.g. (0,1) = (ki, kj).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.

Returns:

FermionOperator – A one-body operator.

static construct_scalar_operator(value)¶

Construct a scalar FermionOperator object.

Parameters:: value (float) – The coefficient in the scalar operator.
Returns:: FermionOperator – A FermionOperator corresponding to the provided value.

construct_two_body_operator_from_integral(two_body_spatial, spins, kpoints, spatial_mask=None)¶

Constructs a two-body operator from two-body spatial integral.

That is

(122)¶\[\sum_{ijkl} (ij|kl) a^{\dagger}_{i,s_i,k_i} a^{\dagger}_{k,s_k,k_k} a_{l,s_l,k_l} a_{j,s_j,k_j}\]

where \(s_i,s_j,s_k,s_l\) are spin indices and \(k_i,k_j,k_k,k_l\) are k-points.

Notes

The integrals are in chemist’s notation, i.e. two_body_spatial[i,j,k,l] = \((ij|kl)\).

Parameters:

two_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation.
spins (tuple[int, int, int, int]) – The corresponding spins as \(s_i,s_j,s_k,s_l\).
kpoints (tuple[int, int, int, int]) – The corresponding k-points as \(k_i,k_j,k_k,k_l\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – A mask filtering the generations of terms in the operator.

Returns:

FermionOperator – Two-body operator.

contract_occupation_space(active_orbs, active_kps=None)¶

Contract the occupation space with respect to the given active space.

Parameters:

active_orbs (list[int]) – Active spatial orbital indices.
active_kps (Optional[list[int]], default: None) – Active k-points.

Returns:

tuple[FermionSpaceBrillouin, list[bool]] – The contracted occupation space object and the contraction mask.

static contract_occupation_state(occupation_state, contraction_mask)¶

Contracts fermion state according to a mask.

Parameters:

occupation_state (FermionState) – A FermionState object.
contraction_mask (list[bool]) – The contraction mask.

Returns:

Union[TypeVar(OccupationSpaceT), ndarray[tuple[Any, ...], dtype[int64]]] – An array corresponding to a contracted occupation number vector.

static contract_operator(fermion_state, contraction_mask, operator)¶

Contracts operator according to a mask and the fermion state.

That is, freezes spin-orbitals according to the known occupation numbers in the provided fermionic state.

Notes

This currently works only with FermionOperator.

Parameters:

fermion_state (FermionState) – A state providing reference occupation numbers.
contraction_mask (list[bool]) – A mask where entries correspond to spin-orbitals. Where True, the spin-orbital is frozen.
operator (list[FermionOperator] | FermionOperator) – Operator to be contracted.

Returns:

list[FermionOperator] | FermionOperator – The contracted operator.

static contract_state_mask(state_mask, contraction_mask)¶

Contracts mask according to another mask.

Parameters:

state_mask (list[bool]) – A state mask.
contraction_mask (list[bool]) – Mask defining a contraction.

Returns:

list[bool] – The contracted mask.

static convert_mask_to_index_map(mask)¶

Convert a mask into an index mapping.

Parameters:: mask (ndarray[tuple[Any, ...], dtype[bool]] | list[bool]) – A boolean mask with the length of the fock space.
Returns:: list[Optional[int]] – Positional indices of mask elements with value True.

count(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶

Counts spin orbitals or modes according to the relevant quantum number and state value.

This is a deprecated legacy method and will be removed in subsequent releases.

Notes

If some value is None, then it is counted.

Parameters:

fermion_state (Optional[FermionState], default: None) – A FermionState object.
state_value (int, default: 1) – 1/0 signifying occupied/unoccupied, respectively.
column (Optional[int], default: None) – The column index in the quantum number table.
column_value (Optional[int], default: None) – The value to be counted.
state_mask (Optional[list[bool]], default: None) – State mask defining which spin orbitals or modes are included in the count.

Returns:

int – Number of orbitals or modes satisfying the input arguments.

generate_occupation_state(n_fermion=0, multiplicity=None)¶

Generates a Fock state with specified number of fermions and multiplicity.

Parameters:

n_fermion (int, default: 0) – Number of fermions per k-point.
multiplicity (Optional[int], default: None) – Multiplicity of the state per k-point.

Returns:

FermionState – The generated FermionState.

generate_occupation_state_from_list(fermion_state_list=None)¶

Convert occupations to an occupation state.

Parameters:: fermion_state_list (Optional[list[int]], default: None) – Occupation numbers.
Returns:: FermionState – The generated fermion state.

generate_occupation_state_from_spatial_occupation(occupation)¶

Generates a FermionState from spatial orbital occupations per k-point.

Parameters:: occupation (list[list[int]]) – list instances that contain occupation values of 0, 1, or 2. The length of the occupation argument should be the number of k-points.
Returns:: FermionState – The generated fermionic state.

index(kp, orb, spin)¶

Converts the set of quantum numbers to an index.

Parameters:

kp (int) – The k-point index.
orb (int) – Orbital index.
spin (int) – Spin.

Returns:

int – Index of the occupation state.

classmethod load_h5(name)¶

Loads operator object from .h5 file.

Parameters:: name (str | Group) – The filename to load from.
Return type:: Self

property n_kp: int¶

Number of k-points.

Returns:: Number of k-points.

property n_spin_orb: int¶: Return the number of spin-orbitals.

operator_to_latex(fermion_operator, **kwargs)¶

Generate a LaTeX representation of an operator in this occupation space.

Operator indices will show degrees of freedom relevant to parent occupation space.

Parameters:

fermion_operator (FermionOperator | FermionOperatorString) – Operator to convert to LaTeX representation.
**kwargs (Any) – Keyword arguments passed to the FermionOperatorString.to_latex() method of component operator strings, FermionOperatorString.

Returns:

str – LaTeX compilable equation string.

Examples

>>> from inquanto.spaces import FermionSpace
>>> fs = FermionSpace(10)
>>> fo = FermionOperator([(1.0, "F1 F1^"), (2+4j, "F2^ F0")])
>>> print(fs.operator_to_latex(fo))
a_{0\downarrow} a_{0\downarrow}^{\dagger} + (2.0+ 4.0\text{i}) a_{1\uparrow}^{\dagger} a_{0\uparrow}

print_state(fermion_state, *state_masks)¶

Prints a fermion state with quantum number information.

If the state_masks argument is provided, a column is added to the print for, with an X marking the elements of the mask which are True.

Parameters:

fermion_state (FermionState) – Fermion state to print.
state_masks (list[bool]) – A mask to include in the print, as described above.

Return type:

None

Examples

>>> from inquanto.spaces import FermionSpace
>>> space = FermionSpace(8)
>>> mask = space.generate_cyclic_window_mask(window=4, shift=2)
>>> state = space.generate_occupation_state_from_list([1, 1, 1, 1, 0, 0, 0, 0])
>>> space.print_state(state, mask)
 0 0a         :  1    .
 1 0b         :  1    .
 2 1a         :  1    X
 3 1b         :  1    X
 4 2a         :  0    X
 5 2b         :  0    X
 6 3a         :  0    .
 7 3b         :  0    .

quantum_label(i)¶

Generates a label for a given basis state index, based on the quantum numbers.

Parameters:: i (int) – Serial index.
Returns:: str – A label for a given serial index.

quantum_number(i)¶

Converts the index to a tuple of quantum numbers.

Parameters:: i (int) – Index.
Returns:: tuple[int, int, int] – Quantum numbers for k-points, spatial orbitals, and spins.

quantum_number_kp(i)¶

Get k-point quantum number from an index.

Parameters:: i (int) – Serial index.
Returns:: int – The k-point quantum number.

quantum_number_orb(i)¶

Get spatial orbital quantum number from an index.

Parameters:: i (int) – Serial index.
Returns:: int – Spatial orbital quantum number.

quantum_number_spin(i)¶

Get spin quantum number from an index.

Parameters:: i (int) – Serial index.
Returns:: qn_spins – Spin quantum number.

save_h5(name)¶

Dumps operator object to .h5 file.

Parameters:: name (str | Group) – The filename to save to.
Return type:: None

class FermionSpaceSupercell(n_spin_orb, n_rp)¶

Bases: OccupationSpace

Represents a fermionic Fock Space with periodicity in real space.

Parameters:

n_spin_orb (int) – The number of spatial orbitals.
n_rp (int) – The number of regional blocks.

COLUMN_ORB = 1¶: The column in the underlying table which corresponds to orbitals.

COLUMN_RP = 0¶: The column in the underlying table which corresponds to regional blocks.

COLUMN_SPIN = 2¶: The column in the underlying table which corresponds to spin.

SPIN_ALPHA = 0¶: Integer representation of spin alpha.

SPIN_BETA = 1¶: Integer representation of spin beta.

SPIN_DOWN = 1¶: Integer representation of spin down.

SPIN_UP = 0¶: Integer representation of spin up.

check_translation_invariance(operator)¶

Checks the translational invariance of an operator according to this supercell.

Parameters:: operator (FermionOperator) – A fermion operator.
Returns:: complex | float – The norm of the difference between the operator and its translated version.

construct_contraction_mask_from_operators(operators)¶

Constructs a contraction mask based on the occurring indices in the operators.

This generates a boolean list, where the elements are True if the spin-orbital is acted upon by the operator or an operator in the list, otherwise False.

Parameters:: operators (FermionOperator | list[FermionOperator]) – An operator or list of operators.
Returns:: list[bool] – The mask defining the contraction.

construct_number_operator(rp, spin=None)¶

Creates and returns a FermionOperator representation of the number operator for a cell with spin.

Parameters:

rp (int) – Cell index.
spin (Optional[int], default: None) – A 0, 1 or None. If None then the resulting number operator will be the sum of up and down.

Returns:

FermionOperator – The number operator.

construct_one_body_operator_from_big_integral(one_body_spatial, spins, spatial_mask=None)¶

Constructs a one-body operator from one-body spatial integral for the supercell.

Parameters:

one_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation for the supercell.
spins (tuple[int, int]) – The spins, e.g. (0,0) = (SPIN_UP, SPIN_UP).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.

Returns:

FermionOperator – The one-body operator.

construct_permutation_operator(permutation)¶

Construct a fermionic permutation operator from a permutation.

The iterable of length two iterables must contain the two indices to be swapped.

Parameters:: permutation (ndarray[tuple[Any, ...], dtype[int64]] | list[int]) – Permutation array.
Returns:: FermionOperator – The generated permutation operator.

Examples

>>> space = FermionSpaceSupercell(4, 1)
>>> print(space.construct_permutation_operator([1, 0]))
(1.0, ), (-1.0, F0^ F0 ), (-1.0, F1^ F1 ), (1.0, F0^ F1 ), (1.0, F1^ F0 )

construct_reverse_rp_permutation_operator()¶

Construct a permutation operator of the indices that reverses the order of the cells.

Returns:: FermionOperator – The permutation operator.

static construct_scalar_operator(value)¶

Construct a FermionOperator with identity operation and the value input as a coefficient.

Parameters:: value (float) – Coefficient of the scalar operator.
Returns:: FermionOperator – A scalar fermionic operator.

construct_shift_rp_permutation_operator(shift)¶

Construct a permutation operator of the indices that translate cells by shift cell.

Parameters:: shift (int) – Number of cells to be translated with.
Returns:: FermionOperator – The permutation operator.

construct_swap_rp_permutation_operator(rp1, rp2)¶

Construct a permutation operator of the indices that swap two cells.

Parameters:

rp1 (int) – Index of cell 1.
rp2 (int) – Index of cell 2.

Returns:

FermionOperator – The permutation operator.

construct_two_body_operator_from_big_integral(two_body_spatial, spins, spatial_mask=None)¶

Constructs a two-body operator from two-body spatial integral for the supercell.

That is

(123)¶\[\sum_{ijkl} (ij|kl) a^{\dagger}_{i,s_i} a^{\dagger}_{k,s_k} a_{l,s_l} a_{j,s_j}.\]

Where \(s_i,s_j,s_k,s_l\) are the spin indices.

Notes

The integrals are in chemist’s notation, that is two_body_spatial[i,j,k,l] = \((ij|kl)\).

Parameters:

two_body_spatial (ndarray[tuple[Any, ...], dtype[float64]]) – Integrals in chemist’s notation for the supercell.
spins (tuple[int, int, int, int]) – The corresponding spins as \(s_i,s_j,s_k,s_l\).
spatial_mask (Optional[ndarray[tuple[Any, ...], dtype[bool]]], default: None) – Mask filtering the generations of terms in the operator.

Returns:

FermionOperator – The two-body operator.

static contract_occupation_state(occupation_state, contraction_mask)¶

Contracts fermion state according to a mask.

Parameters:

occupation_state (FermionState) – A FermionState object.
contraction_mask (list[bool]) – The contraction mask.

Returns:

Union[TypeVar(OccupationSpaceT), ndarray[tuple[Any, ...], dtype[int64]]] – An array corresponding to a contracted occupation number vector.

static contract_operator(fermion_state, contraction_mask, operator)¶

Contracts operator according to a mask and the fermion state.

That is, freezes spin-orbitals according to the known occupation numbers in the provided fermionic state.

Notes

This currently works only with FermionOperator.

Parameters:

fermion_state (FermionState) – A state providing reference occupation numbers.
contraction_mask (list[bool]) – A mask where entries correspond to spin-orbitals. Where True, the spin-orbital is frozen.
operator (list[FermionOperator] | FermionOperator) – Operator to be contracted.

Returns:

list[FermionOperator] | FermionOperator – The contracted operator.

static contract_state_mask(state_mask, contraction_mask)¶

Contracts mask according to another mask.

Parameters:

state_mask (list[bool]) – A state mask.
contraction_mask (list[bool]) – Mask defining a contraction.

Returns:

list[bool] – The contracted mask.

static convert_mask_to_index_map(mask)¶

Convert a mask into an index mapping.

Parameters:: mask (ndarray[tuple[Any, ...], dtype[bool]] | list[bool]) – A boolean mask with the length of the fock space.
Returns:: list[Optional[int]] – Positional indices of mask elements with value True.

count(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶

Counts spin orbitals or modes according to the relevant quantum number and state value.

This is a deprecated legacy method and will be removed in subsequent releases.

Notes

If some value is None, then it is counted.

Parameters:

fermion_state (Optional[FermionState], default: None) – A FermionState object.
state_value (int, default: 1) – 1/0 signifying occupied/unoccupied, respectively.
column (Optional[int], default: None) – The column index in the quantum number table.
column_value (Optional[int], default: None) – The value to be counted.
state_mask (Optional[list[bool]], default: None) – State mask defining which spin orbitals or modes are included in the count.

Returns:

int – Number of orbitals or modes satisfying the input arguments.

generate_cyclic_masks(window, shift=None)¶

Generate a complete set of masks with windows shifted by window/2.

Parameters:

window (int) – Number of spin orbitals in the window.
shift (Optional[int], default: None) – Shift along the state indices.

Returns:

ndarray[tuple[Any, ...], dtype[bool]] – A numpy ndarray of masks.

Examples

>>> fss = FermionSpaceSupercell(n_spin_orb=4, n_rp=2)
>>> fss.generate_cyclic_masks(window=2, shift=2)
array([[ True,  True, False, False, False, False, False, False],
       [False, False,  True,  True, False, False, False, False],
       [False, False, False, False,  True,  True, False, False],
       [False, False, False, False, False, False,  True,  True]])

generate_cyclic_window_mask(window, shift=0)¶

Generate a mask with a window and shift.

The window defines how many elements in the result are True, with the shift determining the start index of the window. See below for example.

Parameters:

window (int) – Number of spin orbitals within the window.
shift (int, default: 0) – Shift along the state indices.

Returns:

ndarray[tuple[Any, ...], dtype[bool]] – A numpy ndarray of booleans defining the mask.

Examples

>>> fss = FermionSpaceSupercell(n_spin_orb=4, n_rp=2)
>>> fss.generate_cyclic_window_mask(window=2, shift=2)
array([False, False,  True,  True, False, False, False, False])

generate_fock_state_from_list(fock_state_list=None)¶

Create a FermionState object corresponding to fock_state_list.

Parameters:: fock_state_list (Optional[list[int]], default: None) – A representation of the desired occupation number vector.
Returns:: FermionState – A FermionState object corresponding to the occupation number vector represented by fock_state_list.

generate_fock_state_from_spatial_big_occupation(occupation)¶

Generates a FermionState from spatial orbital occupations of the supercell.

Parameters:: occupation (list[int]) – Occupation numbers \(\in \{0,1,2\}\) for each spatial orbital.
Returns:: FermionState – The generated fermionic state.

generate_fock_state_from_spatial_occupation(occupation)¶

Generates a FermionState from spatial orbital occupations of each cell in the supercell.

Parameters:: occupation (list[list[int]]) – Occupations, each a list with entries \(\in \{0,1,2\}\) and length equal to the number of spatial orbitals.
Returns:: FermionState – The generated fermionic state.

generate_occupation_state(n_fermion=0, multiplicity=None)¶

Generates a fermion state with the specified number of fermions and multiplicity.

Parameters:

n_fermion (int, default: 0) – Number of fermions per region.
multiplicity (Optional[int], default: None) – Multiplicity of the state per region.

Returns:

FermionState – FermionState object representing the Fock state.

index(rp, orb, spin)¶

Get the index of the space corresponding to the input arguments.

Parameters:

rp (int) – Index of the regional block of interest.
orb (int) – Index of the spatial orbital of interest.
spin (int) – The spin of interest. 0 for alpha, 1 for beta.

Returns:

int – The index of the space corresponding to the input arguments.

static is_operator_permutation_invariant(operator, permutation, threshold=FOCK_SPACE_INVARIANCE_THRESHOLD)¶

Check if the operator is invariant under a permutation.

Parameters:

operator (FermionOperator) – A fermion operator.
permutation (dict[Any, int] | list[int]) – The permuted order.
threshold (float, default: FOCK_SPACE_INVARIANCE_THRESHOLD) – Numerical threshold for invariance.

Returns:

bool – True if the operator is permutationally invariant, else False.

classmethod load_h5(name)¶

Loads operator object from .h5 file.

Parameters:: name (str | Group) – The filename to load from.
Return type:: Self

property n_rp: int¶: Return the number of regional blocks.

property n_spin_orb: int¶: Return the number of spin-orbitals.

operator_to_latex(fermion_operator, **kwargs)¶

Generate a LaTeX representation of an operator in this occupation space.

Operator indices will show degrees of freedom relevant to parent occupation space.

Parameters:

fermion_operator (FermionOperator | FermionOperatorString) – Operator to convert to LaTeX representation.
**kwargs (Any) – Keyword arguments passed to the FermionOperatorString.to_latex() method of component operator strings, FermionOperatorString.

Returns:

str – LaTeX compilable equation string.

Examples

>>> from inquanto.spaces import FermionSpace
>>> fs = FermionSpace(10)
>>> fo = FermionOperator([(1.0, "F1 F1^"), (2+4j, "F2^ F0")])
>>> print(fs.operator_to_latex(fo))
a_{0\downarrow} a_{0\downarrow}^{\dagger} + (2.0+ 4.0\text{i}) a_{1\uparrow}^{\dagger} a_{0\uparrow}

permutation(swaps)¶

Convert a list of swap pairs into a permutation.

Parameters:: swaps (list[tuple[int, int]]) – The index pairs to be swapped.
Returns:: ndarray[tuple[Any, ...], dtype[int64]] – An array of indices which have been permuted according to the swaps argument.

permutation_matrix(permutation)¶

Convert a permutation to a permutation matrix.

Parameters:: permutation (list[int] | ndarray[tuple[Any, ...], dtype[int64]]) – Permuted indices.
Returns:: ndarray[tuple[Any, ...], dtype[float64]] – The permutation matrix.

print_state(fermion_state, *state_masks)¶

Prints a fermion state with quantum number information.

If the state_masks argument is provided, a column is added to the print for, with an X marking the elements of the mask which are True.

Parameters:

fermion_state (FermionState) – Fermion state to print.
state_masks (list[bool]) – A mask to include in the print, as described above.

Return type:

None

Examples

>>> from inquanto.spaces import FermionSpace
>>> space = FermionSpace(8)
>>> mask = space.generate_cyclic_window_mask(window=4, shift=2)
>>> state = space.generate_occupation_state_from_list([1, 1, 1, 1, 0, 0, 0, 0])
>>> space.print_state(state, mask)
 0 0a         :  1    .
 1 0b         :  1    .
 2 1a         :  1    X
 3 1b         :  1    X
 4 2a         :  0    X
 5 2b         :  0    X
 6 3a         :  0    .
 7 3b         :  0    .

quantum_label(i)¶

Get the quantum label corresponding to the space element indexed by the argument i.

Parameters:: i (int) – Index of the space element.
Returns:: str – The r-point, spatial orbital and spin quantum numbers as a formatted string.

quantum_number(i)¶

Compute the quantum numbers corresponding to the space element indexed by the argument i.

Parameters:: i (int) – Index of the space element.
Returns:: tuple[int, int, int] – The regional block index, spatial orbital index and spin quantum number of the space element with index i.

quantum_number_orb(i)¶

Compute the orbital quantum number corresponding to the space element indexed by the argument i.

Parameters:: i (int) – Index of the space element.
Returns:: int – The orbital quantum number of the space element with index i.

quantum_number_rp(i)¶

Compute the regional block quantum number corresponding to the space element indexed by the argument i.

Parameters:: i (int) – Index of the space element.
Returns:: int – The regional block quantum number of the ith space element.

quantum_number_spin(i)¶

Compute the spin quantum number corresponding to the space element indexed by the argument i.

Parameters:: i (int) – Index of the space element.
Returns:: int – The spin quantum number of the space element with index i.

reverse_rp_permutation()¶

Construct a permutation list of the indices that reverses the order of the cells.

Returns:: ndarray[tuple[Any, ...], dtype[int64]] – Permutation list.

save_h5(name)¶

Dumps operator object to .h5 file.

Parameters:: name (str | Group) – The filename to save to.
Return type:: None

shift_rp_permutation(shift)¶

Construct a permutation list of the indices that translate cells by a given number of cells.

Parameters:: shift (int) – Number of cells to be translated with.
Returns:: ndarray[tuple[Any, ...], dtype[int64]] – Permutation list.

swap_rp_permutation(rp1, rp2)¶

Construct a permutation ndarray of the indices that swap two cells.

Parameters:

rp1 (int) – Index of cell 1.
rp2 (int) – Index of cell 2.

Returns:

ndarray[tuple[Any, ...], dtype[int64]] – Permutation ndarray.

translate_operator(operator, translation=None)¶

Constructs a new operator that is translated by the cell translation function.

The default cell translation is \(R\rightarrow R+1\), i.e. it shifts to the next indices. In 1D this is a simple translation along the axis.

Parameters:

operator (FermionOperator) – Fermion operator.
translation (Optional[Callable[[int], int]], default: None) – Cell translation function.

Returns:

FermionOperator – The translated fermion operator.

class ParaFermionSpace(n_spin_orb, point_group=None, orb_irreps=None)¶

Bases: QubitSpace

Represents a parafermionic Hilbert space, for the purposes of simulating fermions.

This class is specifically intended for the use of simulating fermionic systems, rather than a general abstract parafermionic space. As such, it is constructed via the specification of the number of spin-orbitals in the simulated fermionic system. Optionally, information regarding the fermionic symmetries may be provided.

Unlike conventional mapping techniques, fermionic anticommutation relations are not encoded into the operators generated by this class. This may be useful in circumstances where the fermionic anticommutation relations are “already included” in other parts of a simulation – for instance, in the generation of chemical ansatz states.

Parameters:

n_spin_orb (int) – Number of spin orbitals.
point_group (UnionType[PointGroup, str, None], default: None) – Point group of the molecule of interest.
orb_irreps (Optional[list[str]], default: None) – Point group irreducible representations of the orbitals.

construct_double_qubit_excitation_operators()¶

Generate all unique double qubit excitation operators \(T_{ijkl}\).

The list of double qubit excitations is based on a given number of qubits. Fresh parameter symbols are generated for each unique excitation operator.

Warning

Jordan-Wigner encoding of Hamiltonian is assumed: state of qubit \(i\) represents occupation of spin orbital \(i\).

Returns:: QubitOperatorList – Every unique double qubit excitation.

construct_imag_pauli_exponent_operators()¶

Constructs a QubitOperatorList containing operators with even Pauli-\(Y\) count and an imaginary unit coefficient.

Each created QubitOperator in the QubitOperatorList is associated with a fresh coefficient symbol.

Returns:: QubitOperatorList – A QubitOperatorList containing QubitOperator objects with even Pauli-\(Y\) count and an imaginary unit coefficient.

static construct_operator_from_string(input)¶

Construct a QubitOperator from the string provided as input.

See from_string() for further details.

Parameters:: input (str) – String representation of QubitOperator.
Returns:: QubitOperator – The generated qubit operator.

construct_real_pauli_exponent_operators()¶

Constructs a QubitOperatorList containing operators with odd Pauli-\(Y\) count and a unit coefficient.

Each created QubitOperator in the QubitOperatorList is associated with a fresh coefficient symbol.

Returns:: QubitOperatorList – A QubitOperatorList containing QubitOperator objects with an odd number of Pauli-\(Y\) operators and a unit coefficient.

static construct_scalar_operator(value)¶

Generates QubitOperator representing a scalar multiplier.

Parameters:: value (complex | float) – A scalar multiplier.
Returns:: QubitOperator – An operator representing a scalar multiplier.

construct_single_qubit_excitation_operators()¶

Generate a list of all unique single qubit excitation operators \(T_{ik}\).

The list of unique single qubit excitation operators is based on a given number of qubits. Each operator is equivalent to an exchange-interaction operation between two qubits \(i\) and \(k\), \(T_{ik} = \frac{1}{2}([X_i Y_k] - [Y_i X_k])\). Fresh parameter symbols are generated for each operator.

Warning

Jordan-Wigner encoding of Hamiltonian is assumed: state of qubit i represents occupation of spin orbital i.

Returns:: QubitOperatorList – All unique single qubit excitation operators.

static count_spin(qstate)¶

Counts total spin of a QubitState assuming a Jordan-Wigner mapped state.

The value returned should equal \(\langle\hat{S}_z\rangle\). Will not distinguish open and closed shells.

Parameters:: qstate (QubitState) – A qubit space object.
Returns:: int – The sum of the spins.

index(orb, spin)¶

Converts the set of quantum numbers to an index.

Parameters:

orb (int) – The orbital quantum number of interest.
spin (int) – The spin quantum number of interest.

Returns:

int – The element of the space corresponding to the provided orbital and spin quantum numbers.

classmethod load_h5(name)¶

Loads operator object from .h5 file.

Parameters:: name (str | Group) – The filename to load from.
Return type:: Self

n_ones(fock_state)¶

Count the number of ones in the given Fock state.

Returns:: int – Integer count of the number of ones in the provided fock state.
Parameters:: fock_state (list[int])

property n_orb: int¶: Returns the number of spatial orbitals.

property n_spin_orb: int¶: Returns the number of spin-orbitals.

property paulis: set[str]¶: Returns a set of python strings {"I", "X", "Y", "Z"}.

quantum_label(i)¶

Generates a label for a given basis i.

Parameters:: i (int) – Indexed element of the space to be labeled.
Returns:: str – Quantum label of the element indexed by i as a string, formatted at the orbital quantum number followed by spin label (a or b).

quantum_number(i)¶

Converts the index to a tuple of quantum numbers.

Parameters:: i (int) – Index of a given basis state.
Returns:: tuple[int, int] – Tuple containing the spatial orbital number and the spin quantum number of the index.

quantum_number_orb(i)¶

Get spatial orb from an index.

Parameters:: i (int) – Index of a given basis state.
Returns:: int – Spatial orbital quantum number.

quantum_number_spin(i)¶

Get the spin quantum number from an index.

Parameters:: i (int) – Index of a given basis state.
Returns:: int – The spin quantum number.

save_h5(name)¶

Dumps operator object to .h5 file.

Parameters:: name (str | Group) – The filename to save to.
Return type:: None

static symmetry_operators_z2(operator)¶

Given a QubitOperator, find an independent generating set for the \(\mathbb{Z}_2\) symmetries of the operator.

The independent generating set is found by finding the kernel of the symplectic form of the operator. See arXiv 1701.08213 for more details.

Parameters:: operator (QubitOperator) – A qubit operator to find the \(\mathbb{Z}_2\) symmetries of.
Returns:: list[SymmetryOperatorPauli] – Pauli representations of the \(\mathbb{Z}_2\) symmetry operators.

static symmetry_operators_z2_in_sector(operator, state)¶

Constructs \(\mathbb{Z}_2\) symmetry operators which stabilize a provided state.

An independent generating set of symmetry operators is found by finding the kernel of the symplectic form of the operator (arXiv 1701.08213). Operators which stabilize a desired symmetry sector are then returned.

Global phases on the symmetry operators here are such that the returned operators stabilize the provided qubit state - i.e. if the symmetry operator has an expectation value of -1 with the provided qubit state, then the found symmetry operator will be multiplied by -1. This is in contrast to symmetry_operators_z2(), which returns operators without an additional global phase.

Parameters:

operator (QubitOperator) – A qubit operator to find the \(\mathbb{Z}_2\) symmetries of.
state (QubitState) – A state with which the returned symmetry operators will have an eigenvalue of +1.

Returns:

list[QubitOperator] – Pauli representations of the \(\mathbb{Z}_2\) symmetry operators which stabilize the desired symmetry sectors.

class QubitSpace(n_qubits)¶

Bases: object

Represents a Hilbert space comprised of \(N\) qubits, described in a basis of Pauli vectors.

Parameters:: n_qubits (int) – The number of qubits.

construct_imag_pauli_exponent_operators()¶

Constructs a QubitOperatorList containing operators with even Pauli-\(Y\) count and an imaginary unit coefficient.

Each created QubitOperator in the QubitOperatorList is associated with a fresh coefficient symbol.

Returns:: QubitOperatorList – A QubitOperatorList containing QubitOperator objects with even Pauli-\(Y\) count and an imaginary unit coefficient.

static construct_operator_from_string(input)¶

Construct a QubitOperator from the string provided as input.

See from_string() for further details.

Parameters:: input (str) – String representation of QubitOperator.
Returns:: QubitOperator – The generated qubit operator.

construct_real_pauli_exponent_operators()¶

Constructs a QubitOperatorList containing operators with odd Pauli-\(Y\) count and a unit coefficient.

Each created QubitOperator in the QubitOperatorList is associated with a fresh coefficient symbol.

Returns:: QubitOperatorList – A QubitOperatorList containing QubitOperator objects with an odd number of Pauli-\(Y\) operators and a unit coefficient.

classmethod load_h5(name)¶

Loads operator object from .h5 file.

Parameters:: name (str | Group) – The filename to load from.
Return type:: Self

property paulis: set[str]¶: Returns a set of python strings {"I", "X", "Y", "Z"}.

save_h5(name)¶

Dumps operator object to .h5 file.

Parameters:: name (str | Group) – The filename to save to.
Return type:: None

static symmetry_operators_z2(operator)¶

Given a QubitOperator, find an independent generating set for the \(\mathbb{Z}_2\) symmetries of the operator.

The independent generating set is found by finding the kernel of the symplectic form of the operator. See arXiv 1701.08213 for more details.

Parameters:: operator (QubitOperator) – A qubit operator to find the \(\mathbb{Z}_2\) symmetries of.
Returns:: list[SymmetryOperatorPauli] – Pauli representations of the \(\mathbb{Z}_2\) symmetry operators.

static symmetry_operators_z2_in_sector(operator, state)¶

Constructs \(\mathbb{Z}_2\) symmetry operators which stabilize a provided state.

Parameters:

operator (QubitOperator) – A qubit operator to find the \(\mathbb{Z}_2\) symmetries of.
state (QubitState) – A state with which the returned symmetry operators will have an eigenvalue of +1.

Returns:

list[QubitOperator] – Pauli representations of the \(\mathbb{Z}_2\) symmetry operators which stabilize the desired symmetry sectors.

chain_filters(*functions)¶

Combine the callable fermionic excitation filters into one function.

Parameters:: functions – Callable functions, each of which returns a filtered list of fermionic excitations.
Returns:: A fermionic excitation filter accounting for all filters provided in the *functions argument.