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:
- 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 areTrue
if the spin-orbital is acted upon by the operator or an operator in the list, otherwiseFalse
.- Parameters:
operators (
Union
[FermionOperator
,List
[FermionOperator
]]) – An operator orlist
of operators.- Returns:
- 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}\).
- 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 referencefermion_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
.- Parameters:
fermion_state (
FermionState
) – Reference fermionic occupation state.- Returns:
FermionOperatorList
– The double excitation UCC operators stored independently.
- construct_generalised_double_excitation_operators()¶
Construct generalised double excitations conserving azimuthal spin.
Generalised excitations include occupied-to-occupied and virtual-to-virtual excitation operators.
- Returns:
FermionOperatorList
– Generalised double excitation operators stored independently.
- construct_generalised_double_ucc_operators()¶
Generate a
FermionOperatorList
of generalised 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 generalised indices, virtual-virtual, occupied-occupied, and occupied-virtual excitations are all allowed.
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
– Generalised double UCC operators stored independently.
- construct_generalised_pair_double_excitation_operators()¶
Generalised pair-double excitations from molecular orbital to molecular orbital.
Generalised 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}\).
- Returns:
FermionOperatorList
– Generalised MO-MO double excitations
- construct_generalised_pair_double_ucc_operators()¶
Generate a
FermionOperatorList
of generalised 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 generalised indices, but restricted to paired spins, so that \(p\), \(r\) are in one spatial orbital, and \(q\), \(s\) are in another spatial orbital.
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
– Generalised MO-MO double excitations stored independently
- construct_generalised_single_excitation_operators()¶
Construct generalised single excitations conserving azimuthal spin.
Generalised 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}\).
- Returns:
FermionOperatorList
– Generalised single excitation operators stored independently.
- construct_generalised_single_ucc_operators()¶
Generate a
FermionOperatorList
of generalised anti-Hermitian single 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 generalised indices, virtual-virtual, occupied-occupied, and occupied-virtual excitations are all allowed.
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
– Generalised 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:
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}\) withordering="p^r^sq"
, or \(\sum_{\sigma\tau} a_{p_\sigma}^{\dagger} a_{q_\tau}^{\dagger} a_{s_\tau} a_{r_\sigma}\) withordering="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}\) withordering="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}\) withordering="p^q^sr"
, where \(\sigma, \tau, \mu\) are spin indices.
- Returns:
ndarray
[Any
,dtype
[FermionOperator
]] – A \(2n\)-dimensional matrix ofFermionOperator
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:
- 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
withFermionOperator
as the data type.- Parameters:
spins (
Tuple
[int
,int
]) – The corresponding spins as \((s_i,s_j)\).spatial_mask (
List
[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 2tuple
containing ones and zeros, which correspond to creation and annihilation operators, respectively.
- Returns:
ndarray
[Any
,dtype
[FermionOperator
]] – The one body spatial RDM operator as a rank-2 array ofFermionOperator
objects.
- static construct_operator_from_string(input)¶
Construct an operator from a string.
- Parameters:
input (
str
) – String representation of aFermionOperator
.- Returns:
FermionOperator
– An instance ofFermionOperator
corresponding to the string provided.
- construct_orbital_number_operators()¶
Construct a
list
ofFermionOperator
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.- 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_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.
- 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 referencefermion_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.
- 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 referencefermion_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
.- 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_generalised_double_excitation_operators()¶
Construct generalised double excitations conserving azimuthal spin and adapted for singlet spin symmetry.
Generalised 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 generalised double excitations.
- construct_singlet_generalised_single_excitation_operators()¶
Generalised single excitations conserving azimuthal spin and adapted for singlet spin symmetry.
Generalised 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} + a_{p_1}^{\dagger} a_{q1}\), where 0 and 1 indicate alpha and beta spin, respectively.
- Returns:
FermionOperatorList
– The singlet generalised single excitations.
- construct_singlet_generalised_single_ucc_operators()¶
Generate a
FermionOperatorList
of generalised 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.
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
– The singlet generalised UCC single excitations.
- construct_singlet_single_excitation_operators(fermion_state)¶
Generate a
FermionOperatorList
of spin-adapted singlet single excitation operators based on a referencefermion_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.
- 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 referencefermion_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
.- 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_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_triplet_generalised_single_excitation_operators()¶
Construct generalised 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.
- Returns:
FermionOperatorList
– The triplet generalised single excitation operators.
- construct_triplet_generalised_single_ucc_operators()¶
Generate a
FermionOperatorList
of generalised 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 generalised indices.
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
– Generalised 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:
- 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 thetwo_body_spatial
argument toconstruct_two_body_operator_from_integral()
is how the two electron integral is encoded in a tensor format. It is recommended to useconstruct_two_body_operator_from_integral()
andtwo_body_spatial[i,j,k,l]
= \((ij|kl)\). This method is for compatibility.- Parameters:
- 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
]) – The corresponding spins as \((s_i,s_j,s_k,s_l)\).spatial_mask (
Optional
[List
[bool
]], default:None
) – Mask filtering the generations of terms in the operator.operator_pattern (
Tuple
[int
], default:(1, 1, 0, 0)
) – The creation and annihilation ordering of the terms in the array. Must be a length 4tuple
containing ones and zeros, which correspond to creation and annihilation operators, respectively.
- Returns:
ndarray
[Any
,dtype
[FermionOperator
]] – The two body spatial RDM operators.
- contract_occupation_space(active_spatial_orbs)¶
Generate an occupation space with a set of restricted spatial orbitals.
- static contract_occupation_state(occupation_state, contraction_mask)¶
Contracts fermion state according to a mask.
- Parameters:
occupation_state (
FermionState
) – AFermionState
to be contracted.contraction_mask (
List
[bool
]) – Mask, whereTrue
, 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, whereTrue
, the spin-orbital is frozen.operator (
Union
[List
[FermionOperator
],FermionOperator
]) – The operator to be contracted.
- Returns:
Union
[List
[FermionOperator
],FermionOperator
] – The contracted operator.
- static contract_state_mask(state_mask, contraction_mask)¶
Contracts mask according to another 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, whereTrue
, the orbital is frozen.fermion_state (
FermionState
) – Fermionic occupation state to be contracted.operators (
FermionOperator
) – One or moreFermionOperator
instances to be contracted.
- Returns:
Tuple
[FermionSpace
,FermionState
,FermionOperator
] – The contractedFermionSpace
, contractedFermionState
, and contractedFermionOperator
objects.
- static convert_mask_to_index_map(mask)¶
Convert a mask into an index mapping.
- 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 (
FermionState
, default:None
) – AFermionState
object.state_value (
int
, default:1
) – 1/0 signifying occupied/unoccupied, respectively.column (
int
, default:None
) – The column index in the quantum number table.column_value (
int
, default:None
) – The value to be counted.state_mask (
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
) – AFermionState
instance representing a fermionic state vector.- Returns:
FermionSpace
– An instance ofFermionSpace
with \(C_1\) point group symmetry andn_spin_orb
equal to the size of theFermionState
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:
- Returns:
ndarray
[Any
,dtype
[TypeVar
(_ScalarType_co
, bound=generic
, covariant=True)]] – 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 theshift
determining the start index of the window. See below for example.- Parameters:
window (
int
) – Number of spin orbitals within the window.shift (default:
0
) – The position in the occupation number vector to begin the window.
- Returns:
ndarray
[Any
,dtype
[TypeVar
(_ScalarType_co
, bound=generic
, covariant=True)]] – 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:
- 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 (
List
[int
], default:None
) – Represents spin-orbital occupations. Default value isNone
, which returns the all zerosFermionState
(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.- Return type:
- 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.- Return type:
- 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.- Return type:
- 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.
- classmethod load_h5(name)¶
Loads operator object from .h5 file.
- 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 (
Union
[FermionOperator
,FermionOperatorString
]) – Operator to convert to LaTeX representation.**kwargs – Keyword arguments passed to the
FermionOperatorString.to_latex()
method of component operator strings,FermionOperatorString
.
- Returns:
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}
- point_group(as_string=True)¶
Return the point group symmetry of the space.
- Parameters:
as_string (
bool
, default:True
) – IfTrue
, returns name of point group as string. IfFalse
, returns an InQuantoPointGroup
object.- Returns:
Union
[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 anX
marking the elements of the mask which areTrue
.- Parameters:
fermion_state (
FermionState
) – Fermion state to print.state_masks (
List
[bool
]) – A mask to include in the print, as described above.
- Return type:
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.
- 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.
- quantum_number_orb(i)¶
Get spatial orbital index from a spin orbital index.
- quantum_number_spin(i)¶
Get spin index from a spin orbital index.
- save_h5(name)¶
Dumps operator object to .h5 file.
- select(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶
Select elements from the underlying table which satisfy the input arguments.
For example, in a 2-electron, 4-spin orbital
FermionSpace
, the underlying table is[[0, 0], [0, 1], [1, 0], [1, 1]]
, where the first element of each list corresponds to a spin (0 for alpha, 1 for beta) and the second element corresponds to the underlying spatial orbital. So to select the table elements for a given spin, the arguments arecolumn=0
,column_value=0
for spin alpha, andcolumn=0
,column_value=1
for spin beta. To select elements of the table corresponding to a given spatial orbitalx
, the arguments arecolumn=1
andcolumn_value=x
.Warning
This method is deprecated and will be removed in InQuanto v5.0.0
- Parameters:
fermion_state (
FermionState
, default:None
) – AFermionState
object.state_value (default:
1
) – State value.column (
int
, default:None
) – The column in the underlying table to select from, 0 for spin, 1 for orbital.column_value (
int
, default:None
) – The value of interest for the given column.state_mask (
List
[bool
], default:None
) – A boolean mask for for the providedFermionState
.
- Yields:
Elements of the underlying table which satisfy the input arguments.
- Return type:
- 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 toFalse
(the default behaviour!) this may blow up exponentially. Setreturn_factorized
toTrue
to avoid this problem by returning symmetry operators asSymmetryOperatorFermionicFactorised
.- Parameters:
spin_ordering (
Optional
[str
], default:"abab"
) – The spin-orbital ordering -"abab"
for alpha-beta-alpha-beta or"aabb"
for alpha-alpha-beta-beta. PassNone
to skip spin parity symmetry entirely.point_group (
bool
, default:True
) – Set toFalse
to not return point group symmetries.return_factorized (
bool
, default:False
) – Set toTrue
to return symmetry operators asSymmetryOperatorFermionicFactorised
. This avoids exponential growth in terms when expanding the symmetry operator, but returns as the less generalSymmetryOperatorFermionicFactorised
class.
- Returns:
List
[Union
[SymmetryOperatorFermionic
,SymmetryOperatorFermionicFactorised
]] – The \(\mathbb{Z}_2\) symmetry operators in a format determined by thereturn_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 tosymmetry_operators_z2()
, which returns operators without an additional global phase.Danger
Where
return_factorized
is set toFalse
(the default behaviour!) this may blow up exponentially. Setreturn_factorized
toTrue
to avoid this problem by returning symmetry operators asSymmetryOperatorFermionicFactorised
.- 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. PassNone
to skip spin parity symmetry entirely.point_group (
bool
, default:True
) – Set toFalse
to not return point group symmetries.return_factorized (
bool
, default:False
) – Set toTrue
to return symmetry operators asSymmetryOperatorFermionicFactorised
. This avoids exponential growth in terms when expanding the symmetry operator, but returns as the less generalSymmetryOperatorFermionicFactorised
class.
- Returns:
List
[Union
[SymmetryOperatorFermionic
,SymmetryOperatorFermionicFactorised
]] – The \(\mathbb{Z}_2\) symmetry operators in format determined by thereturn_factorized
argument.
- class FermionSpaceBrillouin(n_spin_orb, n_kp, conservation)¶
Bases:
OccupationSpace
FermionSpace
for the momentum representation of a periodic system.- Parameters:
- 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 areTrue
if the spin-orbital is acted upon by the operator or an operator in the list, otherwiseFalse
.- Parameters:
operators (
Union
[FermionOperator
,List
[FermionOperator
]]) – An operator orlist
of operators.- Returns:
- 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
[Any
,dtype
[float
]]) – 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
[List
[bool
]], default:None
) – Mask filtering the generations of terms in the operator.
- Returns:
A one-body operator.
- static construct_scalar_operator(value)¶
Construct a scalar
FermionOperator
object.- Parameters:
value (
float
) – The coefficient in the scalar operator.- Returns:
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
(116)¶\[\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
[Any
,dtype
[float
]]) – Integrals in chemist’s notation.spins (
Tuple
[int
]) – The corresponding spins as \(s_i,s_j,s_k,s_l\).kpoints (
Tuple
[int
]) – The corresponding k-points as \(k_i,k_j,k_k,k_l\).spatial_mask (
List
[bool
], default:None
) – A mask filtering the generations of terms in the operator.
- Returns:
Two-body operator.
- contract_occupation_space(active_orbs, active_kps=None)¶
Contract the occupation space with respect to the given active space.
- static contract_occupation_state(occupation_state, contraction_mask)¶
Contracts fermion state according to a mask.
- Parameters:
occupation_state (
FermionState
) – AFermionState
object.
- Returns:
ndarray
[Any
,dtype
[int
]] – 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. WhereTrue
, the spin-orbital is frozen.operator (
Union
[List
[FermionOperator
],FermionOperator
]) – Operator to be contracted.
- Returns:
Union
[List
[FermionOperator
],FermionOperator
] – The contracted operator.
- static contract_state_mask(state_mask, contraction_mask)¶
Contracts mask according to another mask.
- static convert_mask_to_index_map(mask)¶
Convert a mask into an index mapping.
- 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 (
FermionState
, default:None
) – AFermionState
object.state_value (
int
, default:1
) – 1/0 signifying occupied/unoccupied, respectively.column (
int
, default:None
) – The column index in the quantum number table.column_value (
int
, default:None
) – The value to be counted.state_mask (
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:
- Returns:
FermionState
– The generatedFermionState
.
- 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.
- classmethod load_h5(name)¶
Loads operator object from .h5 file.
- 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 (
Union
[FermionOperator
,FermionOperatorString
]) – Operator to convert to LaTeX representation.**kwargs – Keyword arguments passed to the
FermionOperatorString.to_latex()
method of component operator strings,FermionOperatorString
.
- Returns:
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 anX
marking the elements of the mask which areTrue
.- Parameters:
fermion_state (
FermionState
) – Fermion state to print.state_masks (
List
[bool
]) – A mask to include in the print, as described above.
- Return type:
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.
- quantum_number_kp(i)¶
Get k-point quantum number from an index.
- quantum_number_orb(i)¶
Get spatial orbital quantum number from an index.
- 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.
- select(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶
Select elements from the underlying table which satisfy the input arguments.
For example, in a 2-electron, 4-spin orbital
FermionSpace
, the underlying table is[[0, 0], [0, 1], [1, 0], [1, 1]]
, where the first element of each list corresponds to a spin (0 for alpha, 1 for beta) and the second element corresponds to the underlying spatial orbital. So to select the table elements for a given spin, the arguments arecolumn=0
,column_value=0
for spin alpha, andcolumn=0
,column_value=1
for spin beta. To select elements of the table corresponding to a given spatial orbitalx
, the arguments arecolumn=1
andcolumn_value=x
.Warning
This method is deprecated and will be removed in InQuanto v5.0.0
- Parameters:
fermion_state (
FermionState
, default:None
) – AFermionState
object.state_value (default:
1
) – State value.column (
int
, default:None
) – The column in the underlying table to select from, 0 for spin, 1 for orbital.column_value (
int
, default:None
) – The value of interest for the given column.state_mask (
List
[bool
], default:None
) – A boolean mask for for the providedFermionState
.
- Yields:
Elements of the underlying table which satisfy the input arguments.
- Return type:
- class FermionSpaceSupercell(n_spin_orb, n_rp)¶
Bases:
OccupationSpace
Represents a fermionic Fock Space with periodicity in real space.
- Parameters:
- 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:
Union
[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 areTrue
if the spin-orbital is acted upon by the operator or an operator in the list, otherwiseFalse
.- Parameters:
operators (
Union
[FermionOperator
,List
[FermionOperator
]]) – An operator orlist
of operators.- Returns:
- construct_number_operator(rp, spin=None)¶
Creates and returns a
FermionOperator
representation of the number operator for a cell with spin.- Parameters:
- 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
[Any
,dtype
[TypeVar
(_ScalarType_co
, bound=generic
, covariant=True)]]) – Integrals in chemist’s notation for the supercell.spins (
Tuple
[int
,int
]) – The spins, e.g.(0,0)
=(SPIN_UP, SPIN_UP)
.spatial_mask (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 (
Union
[ndarray
[Any
,dtype
[int
]],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:
- 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
(117)¶\[\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:
- 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
) – AFermionState
object.
- Returns:
ndarray
[Any
,dtype
[int
]] – 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. WhereTrue
, the spin-orbital is frozen.operator (
Union
[List
[FermionOperator
],FermionOperator
]) – Operator to be contracted.
- Returns:
Union
[List
[FermionOperator
],FermionOperator
] – The contracted operator.
- static contract_state_mask(state_mask, contraction_mask)¶
Contracts mask according to another mask.
- static convert_mask_to_index_map(mask)¶
Convert a mask into an index mapping.
- 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 (
FermionState
, default:None
) – AFermionState
object.state_value (
int
, default:1
) – 1/0 signifying occupied/unoccupied, respectively.column (
int
, default:None
) – The column index in the quantum number table.column_value (
int
, default:None
) – The value to be counted.state_mask (
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
.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 theshift
determining the start index of the window. See below for example.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 tofock_state_list
.- Parameters:
fock_state_list (
List
[int
], default:None
) – A representation of the desired occupation number vector.- Returns:
FermionState
– AFermionState
object corresponding to the occupation number vector represented byfock_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 alist
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:
- Returns:
FermionState
–FermionState
object representing the Fock state.
- index(rp, orb, spin)¶
Get the index of the space corresponding to the input arguments.
- static is_operator_permutation_invariant(operator, permutation, threshold=1e-8)¶
Check if the operator is invariant under a permutation.
- classmethod load_h5(name)¶
Loads operator object from .h5 file.
- 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 (
Union
[FermionOperator
,FermionOperatorString
]) – Operator to convert to LaTeX representation.**kwargs – Keyword arguments passed to the
FermionOperatorString.to_latex()
method of component operator strings,FermionOperatorString
.
- Returns:
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_matrix(permutation)¶
Convert a permutation to a 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 anX
marking the elements of the mask which areTrue
.- Parameters:
fermion_state (
FermionState
) – Fermion state to print.state_masks (
List
[bool
]) – A mask to include in the print, as described above.
- Return type:
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
.
- quantum_number(i)¶
Compute the quantum numbers corresponding to the space element indexed by the argument
i
.
- quantum_number_orb(i)¶
Compute the orbital quantum number corresponding to the space element indexed by the argument
i
.
- quantum_number_rp(i)¶
Compute the regional block quantum number corresponding to the space element indexed by the argument
i
.
- quantum_number_spin(i)¶
Compute the spin quantum number corresponding to the space element indexed by the argument
i
.
- reverse_rp_permutation()¶
Construct a permutation list of the indices that reverses the order of the cells.
- save_h5(name)¶
Dumps operator object to .h5 file.
- select(fermion_state=None, state_value=1, column=None, column_value=None, state_mask=None)¶
Select elements from the underlying table which satisfy the input arguments.
For example, in a 2-electron, 4-spin orbital
FermionSpace
, the underlying table is[[0, 0], [0, 1], [1, 0], [1, 1]]
, where the first element of each list corresponds to a spin (0 for alpha, 1 for beta) and the second element corresponds to the underlying spatial orbital. So to select the table elements for a given spin, the arguments arecolumn=0
,column_value=0
for spin alpha, andcolumn=0
,column_value=1
for spin beta. To select elements of the table corresponding to a given spatial orbitalx
, the arguments arecolumn=1
andcolumn_value=x
.Warning
This method is deprecated and will be removed in InQuanto v5.0.0
- Parameters:
fermion_state (
FermionState
, default:None
) – AFermionState
object.state_value (default:
1
) – State value.column (
int
, default:None
) – The column in the underlying table to select from, 0 for spin, 1 for orbital.column_value (
int
, default:None
) – The value of interest for the given column.state_mask (
List
[bool
], default:None
) – A boolean mask for for the providedFermionState
.
- Yields:
Elements of the underlying table which satisfy the input arguments.
- Return type:
- shift_rp_permutation(shift)¶
Construct a permutation list of the indices that translate cells by a given number of cells.
- swap_rp_permutation(rp1, rp2)¶
Construct a permutation
ndarray
of the indices that swap two cells.
- 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 (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:
- 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 theQubitOperatorList
is associated with a fresh coefficient symbol.- Returns:
A
QubitOperatorList
containingQubitOperator
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 ofQubitOperator
.- 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 theQubitOperatorList
is associated with a fresh coefficient symbol.- Returns:
QubitOperatorList
– AQubitOperatorList
containingQubitOperator
objects with an odd number of Pauli-\(Y\) operators and a unit coefficient.
- static construct_scalar_operator(value)¶
Generates
QubitOperator
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 orbitali
.- 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.
- classmethod load_h5(name)¶
Loads operator object from .h5 file.
- 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.
- quantum_label(i)¶
Generates a label for a given basis
i
.
- quantum_number(i)¶
Converts the index to a tuple of quantum numbers.
- quantum_number_orb(i)¶
Get spatial orb from an index.
- quantum_number_spin(i)¶
Get the spin quantum number from an index.
- save_h5(name)¶
Dumps operator object to .h5 file.
- 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
[SymmetryOperatorPauli
] – 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 theQubitOperatorList
is associated with a fresh coefficient symbol.- Returns:
A
QubitOperatorList
containingQubitOperator
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 ofQubitOperator
.- 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 theQubitOperatorList
is associated with a fresh coefficient symbol.- Returns:
QubitOperatorList
– AQubitOperatorList
containingQubitOperator
objects with an odd number of Pauli-\(Y\) operators and a unit coefficient.
- classmethod load_h5(name)¶
Loads operator object from .h5 file.
- save_h5(name)¶
Dumps operator object to .h5 file.
- 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
[SymmetryOperatorPauli
] – 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:
Callable
[[Generator
[FermionOperatorString
,None
,None
]],Generator
[FermionOperatorString
,None
,None
]] – A fermionic excitation filter accounting for all filters provided in the *functions argument.