symmray.fermionic_local_operators¶

Helper functions for building local fermionic operators, with ‘internal’ signs pre-computed.

Attributes¶

fermi_spin_operator_local_array

Classes¶

FermionicOperator

Simple class to represent a fermionic operator with a label, a dual

Functions¶

`labels_lt`(labela, labelb)
`_dagger_basis`(basis)	Return the conjugate basis of a given basis.
`_ensure_fermionic_operator`(op)	Possibly convert a tuple of (label, symbol) to a FermionicOperator.
`_parse_terms`(terms)	Allow ops to be specified as tuples of (site, symbol) in addition to
`_parse_bases`(bases)	Allow ops to be specified as tuples of (site, symbol) in addition to
`build_local_fermionic_elements`(terms, bases)	Compute the elements of a local fermionic operator in a given tensor
`build_local_fermionic_dense`(terms, bases[, like])	Build the local operator as a dense array of elements including internal
`build_local_fermionic_array`(terms, bases, symmetry, ...)	Compute a local fermionic operator as a FermionicArray.
`get_spinless_charge_indexmap`(symmetry)	Get a mapping of linear index to charge sector for a spinless
`get_spinful_charge_indexmap`(symmetry)	Get a mapping of linear index to charge sector for a spinful
`fermi_hubbard_spinless_local_array`(symmetry[, t, V, ...])	Construct the fermionic local tensor for the spinless Fermi-Hubbard
`fermi_hubbard_local_array`(symmetry[, t, U, mu, ...])	Construct the fermionic local tensor for the Fermi-Hubbard model. The
`fermi_number_operator_spinless_local_array`(symmetry[, ...])	Construct the fermionic number operator for the spinless Fermi-Hubbard
`fermi_number_operator_spinful_local_array`(symmetry[, ...])	Construct the fermionic number operator for the Fermi-Hubbard model. The
`fermi_number_up_local_array`(symmetry[, like, flat])	Construct the 'up' fermionic number operator for the Fermi-Hubbard
`fermi_number_down_local_array`(symmetry[, like, flat])	Construct the 'down' fermionic number operator for the Fermi-Hubbard
`fermi_spin_z_local_array`(symmetry[, like, flat])	Construct the fermionic `S^z` operator for the Fermi-Hubbard model.
`fermi_spin_plus_local_array`(symmetry[, like, flat])	Construct the fermionic spin raising operator
`fermi_spin_minus_local_array`(symmetry[, like, flat])	Construct the fermionic spin lowering operator
`fermi_double_occupancy_local_array`(symmetry[, like, flat])	Construct the on-site double occupancy operator `D = n↑ n↓` for the
`fermi_pairing_onsite_local_array`(symmetry[, like, flat])	Construct the on-site s-wave (singlet) pair annihilation operator
`fermi_pairing_bond_local_array`(symmetry[, like, flat])	Construct the nearest-neighbor spin-singlet pair annihilation operator

Module Contents¶

symmray.fermionic_local_operators.labels_lt(labela, labelb)[source]¶

class symmray.fermionic_local_operators.FermionicOperator(label, dual=False, parity=1)[source]¶

Simple class to represent a fermionic operator with a label, a dual flag, and a parity ‘switch’ indicating whether the fermion is present.

__slots__ = ('_label', '_dual', '_parity')¶

_label¶

_dual = False¶

_parity = 1¶

to_pytree()[source]¶: Convert this fermionic operator to a pytree purely of non-symmray containers and objects.

classmethod from_pytree(data)[source]¶: Create a fermionic operator from a pytree purely of non-symmray containers and objects.

property label¶

property dual¶

property parity¶

property dag¶

__eq__(other)[source]¶

__lt__(other)[source]¶

__repr__()[source]¶

symmray.fermionic_local_operators._dagger_basis(basis)[source]¶: Return the conjugate basis of a given basis.

symmray.fermionic_local_operators._ensure_fermionic_operator(op)[source]¶: Possibly convert a tuple of (label, symbol) to a FermionicOperator.

symmray.fermionic_local_operators._parse_terms(terms)[source]¶: Allow ops to be specified as tuples of (site, symbol) in addition to FermionicOperator instances. E.g. (-t, [('a', '+'), ('b', '-')]).

symmray.fermionic_local_operators._parse_bases(bases)[source]¶: Allow ops to be specified as tuples of (site, symbol) in addition to FermionicOperator instances.

symmray.fermionic_local_operators.build_local_fermionic_elements(terms, bases)[source]¶

Compute the elements of a local fermionic operator in a given tensor basis, including ‘internal’ signs.

Parameters:

terms (tuple[tuple[float, tuple[FermionicOperator, ...]]]) – The terms in the operator, each a tuple of a coefficient and a tuple of FermionicOperator or tuple[label, op] instances.
bases (tuple[tuple[tuple[FermionicOperator]]]) – The tensor bases to compute the operator elements in. Each basis is a sequence of multiple FermionicOperator instancess acting on the vacuum.

Returns:

A list of tuples of tensor indices and the corresponding tensor element, including phases.

Return type:

list[tuple[tuple[int], float]]

Examples

Compute the elements of a local fermionic operator in a tensor basis:

a, b = map(FermionicOperator, "ab")
basis_a = [(), (a.dag,)]
basis_b = [(), (b.dag,)]
bases = (basis_a, basis_b)

t = 1.0
U = 8.0

terms = (
    (-t, (a.dag, b)),
    (-t, (b.dag, a)),
    (U, (a.dag, a, b.dag, b)),
)

build_local_fermionic_elements(terms, bases)
# {(0, 1, 1, 0): -1.0, (1, 0, 0, 1): -1.0, (1, 1, 1, 1): -8.0}

symmray.fermionic_local_operators.build_local_fermionic_dense(terms, bases, like='numpy')[source]¶: Build the local operator as a dense array of elements including internal fermionic signs - this is the raw tensor data, not the bare operator matrix (whose true action is only recovered under fermionic contraction).

symmray.fermionic_local_operators.build_local_fermionic_array(terms, bases, symmetry, index_maps, like='numpy', flat=False)[source]¶

Compute a local fermionic operator as a FermionicArray.

Parameters:

terms (tuple[tuple[float, tuple[FermionicOperator, ...]]]) – The terms in the operator, each a tuple of a coefficient and a tuple of FermionicOperator instances.
bases (tuple[tuple[tuple[FermionicOperator]]]) – The tensor bases to compute the operator elements in. Each basis is a sequence of multiple FermionicOperator instances acting on the vacuum.
symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2” or “U1U1”.
index_maps (Sequence[Sequence[hashable]]) – For each basis, the sequence mapping linear index to charge sector.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.get_spinless_charge_indexmap(symmetry)[source]¶

Get a mapping of linear index to charge sector for a spinless fermion model.

Parameters:: symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
Return type:: list[hashable]

symmray.fermionic_local_operators.get_spinful_charge_indexmap(symmetry)[source]¶

Get a mapping of linear index to charge sector for a spinful fermion model.

Parameters:: symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
Return type:: list[hashable]

symmray.fermionic_local_operators.fermi_hubbard_spinless_local_array(symmetry, t=1.0, V=8.0, mu=0.0, delta=0.0, coordinations=(1, 1), like='numpy', flat=False)[source]¶

Construct the fermionic local tensor for the spinless Fermi-Hubbard model. The indices are ordered as (a, b, a’, b’).

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
t (float, optional) – The hopping parameter, by default 1.0.
V (float, optional) – The nearest-neighbor interaction parameter, by default 8.0.
mu (float or (float, float), optional) – The chemical potential, by default 0.0. If a tuple, then the chemical potential is different for each site.
delta (float, optional) – The nearest neighbor superconducting pairing parameter, by default 0.0.
coordinations (tuple[int, int], optional) – The coordinations of the sites, by default (1, 1). If applying this local operator to every edge in a graph, then the single site contributions can be properly accounted for if the coordinations are provided.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_hubbard_local_array(symmetry, t=1.0, U=8.0, mu=0.0, coordinations=(1, 1), like='numpy', flat=False)[source]¶

Construct the fermionic local tensor for the Fermi-Hubbard model. The indices are ordered as (a, b, a’, b’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for site a with up (au) and down (ad) spin respectively and similar for site b.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
t (float, optional) – The hopping parameter, by default 1.0.
U (float or (float, float), optional) – The interaction parameter, by default 8.0. If a tuple, then the interaction parameter is different for each site.
mu (float or (float, float), optional) – The chemical potential, by default 0.0. If a tuple, then the chemical potential is different for each site.
coordinations (tuple[int, int], optional) – The coordinations of the sites, by default (1, 1). If applying this local operator to every edge in a graph, then the single site contributions can be properly accounted for if the coordinations are provided.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_number_operator_spinless_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the fermionic number operator for the spinless Fermi-Hubbard model. The indices are ordered as (a, a’). The local basis is like (|0>, a+|0>) for single site a.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_number_operator_spinful_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the fermionic number operator for the Fermi-Hubbard model. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for site a with up (au) and down (ad) spin respectively for single site a.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

array – The local operator in fermionic array form.

Return type:

FermionicArray

symmray.fermionic_local_operators.fermi_number_up_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the ‘up’ fermionic number operator for the Fermi-Hubbard model. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for site a with up (au) and down (ad) spin respectively for single site a.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_number_down_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the ‘down’ fermionic number operator for the Fermi-Hubbard model. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for site a with up (au) and down (ad) spin respectively for single site a.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_spin_z_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the fermionic S^z operator for the Fermi-Hubbard model. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for site a with up (au) and down (ad) spin respectively for single site a.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_spin_operator_local_array[source]¶

symmray.fermionic_local_operators.fermi_spin_plus_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the fermionic spin raising operator S^+ = c_up^dagger c_down for the Fermi-Hubbard model.

This operator conserves total particle number but transfers one particle between spin flavors, so it is only identity-charge under Z2 and U1 symmetries.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_spin_minus_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the fermionic spin lowering operator S^- = c_down^dagger c_up for the Fermi-Hubbard model.

This operator conserves total particle number but transfers one particle between spin flavors, so it is only identity-charge under Z2 and U1 symmetries.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_double_occupancy_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the on-site double occupancy operator D = n↑ n↓ for the Fermi-Hubbard model, i.e. the projector onto the doubly occupied state. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for single site a. Useful as the <U> interaction-energy observable.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2”, “U1”, “Z2Z2”, or “U1U1”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_pairing_onsite_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the on-site s-wave (singlet) pair annihilation operator Δ = c↑ c↓ for the Fermi-Hubbard model, the superconducting order parameter whose expectation <Δ> is non-zero only in a number non-conserving state. Use .dagger() for the pair creation operator Δ† = c↓† c↑†. The indices are ordered as (a, a’), with the local basis like (|00>, ad+|00>, au+|00>, au+ad+|00>) for single site a.

The operator removes two fermions, so it conserves fermion parity but not particle number: it is only an identity-charge (measurable) operator under “Z2”. Under “U1”, “Z2Z2” or “U1U1” it is charge-changing and <Δ> vanishes identically, so those symmetries are rejected.

Parameters:

symmetry (str) – The symmetry of the model, must be “Z2”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat

symmray.fermionic_local_operators.fermi_pairing_bond_local_array(symmetry, like='numpy', flat=False)[source]¶

Construct the nearest-neighbor spin-singlet pair annihilation operator Delta_ab = c_a_up c_b_down - c_a_down c_b_up.

The operator removes two fermions, so it is only identity-charge under Z2 symmetry. The indices are ordered as (a, b, a', b').

Parameters:

symmetry (str) – The symmetry of the model, must be “Z2”.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return a flat array, by default False.

Returns:

The local operator in fermionic array form.

Return type:

FermionicArray or FermionicArrayFlat