symmray ¶

symmray.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.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:

symmray.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:

symmray.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:

symmray.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:

symmray.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:

symmray.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:

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

Construct the fermionic spin 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:

Bases: symmray.flat.flat_array_common.FlatArrayCommon, symmray.flat.flat_data_common.FlatCommon, symmray.bosonic_common.BosonicCommon, symmray.array_common.ArrayCommon, symmray.common.SymmrayCommon

class symmray.AbelianArrayFlat(sectors, blocks, indices, symmetry=None, label=None)[source]¶

Base class for abelian arrays with flat storage and cyclic symmetry.

Parameters:

sectors (array_like) – The stack of sector keys, with shape (num_blocks, ndim). Each row represents a sector of a corresponding block, and each column represents a charge in a given axis.
blocks (array_like) – The stack of array blocks, with shape (num_blocks, *shape_block), i.e. ndim + 1 dimensions, where the first dimension is the block index, which should match the first dimension of sectors, and the rest are the dimensions of individual blocks.
indices (sequence[FlatIndex]) – Indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

__slots__ = ('_blocks', '_indices', '_label', '_sectors', '_symmetry', 'backend')¶

fermionic = False¶

static_symmetry = None¶

check()[source]¶: Check the internal consistency of the array.

new_with(sectors, blocks, indices, label=None) → AbelianArrayFlat[source]¶: Create a new flat abelian array of the same class as this one. Unlike copy, this does not copy over any existing data and drops for example label.

copy(deep=False) → AbelianArrayFlat[source]¶: Create a copy of the array.

copy_with(sectors=None, blocks=None, indices=None) → AbelianArrayFlat[source]¶: A copy of this block array with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

modify(sectors=None, blocks=None, indices=None) → AbelianArrayFlat[source]¶: Modify this flat array in place with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

set_params(params)[source]¶: Set the underlying array blocks.

classmethod from_pytree(pytree) → AbelianArrayFlat[source]¶: Create a flat abelian array from a pytree purely of non-symmray containers and objects.

classmethod from_blocks(blocks, indices, symmetry=None, label=None) → AbelianArrayFlat[source]¶

Create a flat array from an explicit dictionary of blocks, and sequence of indices or duals.

Parameters:

blocks (dict[tuple[int, ...], array_like]) – A dictionary mapping sector keys (tuples of charges) to blocks (arrays).
indices (sequence[FlatIndex] | sequence[bool]) – A sequence of indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.
label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.

Return type:

AbelianArrayFlat

classmethod from_blocksparse(x: symmray.sparse.sparse_abelian_array.AbelianArray, symmetry=None) → AbelianArrayFlat[source]¶

Create a flat abelian array from a blocksparse abelian array.

Parameters:

x (AbelianArray) – The blocksparse abelian array to convert.
symmetry (str or Symmetry, optional) – The symmetry to use. If not supplied, the symmetry of x is used.

to_blocksparse() → symmray.sparse.sparse_abelian_array.AbelianArray[source]¶: Create a blocksparse abelian array from this flat abelian array.

_map_blocks(fn_sector=None, fn_block=None)[source]¶

sort_stack(axes=None, all_axes=None, inplace=False) → AbelianArrayFlat[source]¶

Lexicgraphic sort the stack of sectors and blocks according to the values of charges in the specified axes, optionally filling in the rest of the axes with the remaining axes in the order they appear.

Parameters:

axes (int | tuple[int, ...], optional) – The axes to sort by. If a single integer is given, it will be interpreted as the axis to sort by. If a tuple of integers is given, it will be interpreted as the axes to sort by in order. Default is None, if all_axes is also None or True, this will sort all axes in their current order.
all_axes (bool, optional) – Whether to include all non-specified axes as tie-breakers, after the specified axes. If None, the default, this will be True if axes is not supplied explicitly, and False otherwise.
inplace (bool, optional) – Whether to perform the operation inplace or return a new array. Default is False, which returns a new array.

class symmray.Z2ArrayFlat(sectors, blocks, indices, symmetry=None, label=None)[source]¶

Bases: AbelianArrayFlat

Base class for abelian arrays with flat storage and cyclic symmetry.

Parameters:

sectors (array_like) – The stack of sector keys, with shape (num_blocks, ndim). Each row represents a sector of a corresponding block, and each column represents a charge in a given axis.
blocks (array_like) – The stack of array blocks, with shape (num_blocks, *shape_block), i.e. ndim + 1 dimensions, where the first dimension is the block index, which should match the first dimension of sectors, and the rest are the dimensions of individual blocks.
indices (sequence[FlatIndex]) – Indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

static_symmetry¶

class symmray.FermionicArrayFlat(sectors, blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None)[source]¶

Bases: symmray.fermionic_common.FermionicCommon, symmray.flat.flat_array_common.FlatArrayCommon, symmray.flat.flat_data_common.FlatCommon, symmray.array_common.ArrayCommon, symmray.common.SymmrayCommon

Fermionic abelian symmetric array with flat backend.

Parameters:

sectors (array_like) – The stack of sector keys, with shape (num_blocks, ndim). Each row represents a sector of a corresponding block, and each column represents a charge in a given axis.
blocks (array_like) – The stack of array blocks, with shape (num_blocks, *shape_block), i.e. ndim + 1 dimensions, where the first dimension is the block index, which should match the first dimension of sectors, and the rest are the dimensions of individual blocks.
indices (sequence[FlatIndex]) – Indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
phases (array_like, optional) – An array of +/- 1 phases, with shape (num_blocks,), giving the phase of each block. If not supplied, all phases are assumed to be +1.
label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.
dummy_modes (sequence[FermionicOperator], optional) – A sequence of dummy fermionic modes representing to effectively prepend to the array.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

__slots__ = ('_blocks', '_dummy_modes', '_indices', '_phases', '_sectors', '_symmetry', 'backend')¶

fermionic = True¶

static_symmetry = None¶

_dummy_modes = ()¶

property phases¶: The phases for each block.

property parity¶: The total parity of the array, 0 for even, 1 for odd.

check()[source]¶: Check the internal consistency of the array.

new_with(sectors, blocks, indices, label=None) → FermionicArrayFlat[source]¶: Create a new flat fermionic array of the same class as this one. Unlike copy, this does not copy over any existing data and drops by default label, phases, and dummy_modes.

copy(deep=False) → FermionicArrayFlat[source]¶: Create a copy of the array.

copy_with(sectors=None, blocks=None, indices=None, phases=None) → FermionicArrayFlat[source]¶: A copy of this fermionic flat array with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

modify(sectors=None, blocks=None, indices=None, phases=None, dummy_modes=None) → FermionicArrayFlat[source]¶: Modify this fermionic flat array in place with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

set_params(params)[source]¶: Set the underlying array blocks.

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

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

_map_blocks(fn_sector=None, fn_block=None)[source]¶

classmethod from_blocks(blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None) → FermionicArrayFlat[source]¶

Create a fermionic flat array from an explicit dictionary of blocks, and sequence of indices or duals.

Parameters:

blocks (dict[tuple[int, ...], array_like]) – A dictionary mapping sector keys (tuples of charges) to blocks (arrays).
indices (sequence[FlatIndex] | sequence[bool]) – A sequence of indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
phases (dict[tuple[int, ...], int], optional) – A dictionary mapping sector keys to +/- 1 phases. If not supplied, all phases are assumed to be +1.
label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.
dummy_modes (sequence[FermionicOperator], optional) – A sequence of dummy fermionic modes representing to effectively prepend to the array.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

classmethod from_blocksparse(x: symmray.sparse.sparse_fermionic_array.FermionicArray, symmetry=None)[source]¶

Create a fermionic flat array from a fermionic blocksparse array.

Parameters:

x (FermionicArray) – The fermionic blocksparse array to convert.
symmetry (str or Symmetry, optional) – The symmetry to use. If not supplied, the symmetry of x is used.

to_blocksparse() → symmray.sparse.sparse_fermionic_array.FermionicArray[source]¶

Convert this fermionic flat array to a fermionic blocksparse array.

Returns:: The equivalent fermionic blocksparse array.
Return type:: FermionicArray

sort_stack(axes=None, all_axes=None, inplace=False) → FermionicArrayFlat[source]¶

Parameters:

axes (int | tuple[int, ...], optional) – The axes to sort by. If a single integer is given, it will be interpreted as the axis to sort by. If a tuple of integers is given, it will be interpreted as the axes to sort by in order. Default is None, if all_axes is also None or True, this will sort all axes in their current order.
all_axes (bool, optional) – Whether to include all non-specified axes as tie-breakers, after the specified axes. If None, the default, this will be True if axes is not supplied explicitly, and False otherwise.
inplace (bool, optional) – Whether to perform the operation inplace or return a new array. Default is False, which returns a new array.

phase_sync(inplace=False) → FermionicArrayFlat[source]¶

Multiply all lazy phases into the block arrays.

Parameters:: inplace (bool, optional) – Whether to perform the operation in place.
Returns:: The resolved array, which now has all trivial (+1) phases.
Return type:: FermionicArrayFlat

phase_flip(*axs, inplace=False) → FermionicArrayFlat[source]¶

Flip the phase of all sectors with odd parity at the given axis.

Parameters:

ax (int) – The axis along which to flip the phase.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The phase-flipped array.

Return type:

phase_transpose(axes=None, inplace=False) → FermionicArrayFlat[source]¶

Phase this fermionic array as if it were transposed virtually, i.e. the actual arrays are not transposed. Useful when one wants the actual data layout to differ from the required fermionic mode layout.

Parameters:

axes (tuple of int, optional) – The permutation of axes, by default None.
inplace (bool, optional) – Whether to perform the operation in place.

Return type:

abstractmethod phase_sector(sector, inplace=False)[source]¶

phase_global(inplace=False)[source]¶

Flip the global phase of the array.

Parameters:: inplace (bool, optional) – Whether to perform the operation in place.
Return type:: FermionicArray

_resolve_dummy_modes_conj(phase_permutation=True)[source]¶: Assuming we have effectively taken the conjugate of a fermionic array with dummy modes, get their new order and compute any phase changes coming from moving back to the beginning of the index order.

_resolve_dummy_modes_combine(a, b)[source]¶: Calculate the new combined dummy modes and any associated global phases combing from contracting two fermionic arrays a and b. This modifies this array in place.

_resolve_dummy_modes_squeeze(axes_squeeze)[source]¶: Assuming we are about to squeeze away axes_squeeze, compute the phases associated with moving them to the beginning of the array, and then turn them into dummy modes.

transpose(axes=None, phase=True, inplace=False) → FermionicArrayFlat[source]¶

Transpose this flat fermionic array, by default accounting for the phases accumulated from swapping odd charges.

Parameters:

axes (tuple of int, optional) – The permutation of axes, by default None.
phase (bool, optional) – Whether to flip the phase of sectors whose odd charges undergo a odd permutation. By default True.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The transposed array.

Return type:

conj(phase_permutation=True, phase_dual=False, inplace=False)[source]¶

Conjugate this flat fermionic array. By default this include phases from both the virtual flipping of all axes, but not the conjugation of dual indices, such that:

(
    tensordot_fermionic(x.conj(), x, ndim) ==
    tensordot_fermionic(x, x.conj(), ndim)
)

If all indices have matching dualness (i.e. all bra or all ket), or you set phase_dual=True then the above contractions will also be equal to x.norm() ** 2.

Parameters:

phase_permutation (bool, optional) – Whether to flip the phase of sectors whose odd charges undergo a odd permutation due to virtually flipping the order of axes, by default True.
phase_dual (bool, optional) – Whether to flip the phase of dual indices, by default False. If a FermionicArrayFlat has a mix of dual and non-dual indices, and you are explicitly forming the norm, you may want to set this to True. But if it is part of a large tensor network you only need to flip the phase of true ‘outer’ dual indices.

Return type:

Bases: symmray.flat.flat_data_common.FlatCommon, symmray.vector_common.VectorCommon, symmray.common.SymmrayCommon

dagger(phase_dual=False, inplace=False)[source]¶: Fermionic conjugate transpose.

eigh(phase_eigenvalues=True) → tuple[symmray.flat.flat_vector.FlatVector, FermionicArrayFlat][source]¶

Hermitian eigen-decomposition of this flat fermionic array.

Parameters:

phase_eigenvalues (bool, optional) – If True, any local phase will be absorbed into the eigenvalues, such that U @ diag(w) @ U.H == a always holds. By default True. If False then one of U or U.H should be phased individually to account for local phasesin the above expression.

Returns:

eigenvalues (FlatVector) – The eigenvalues.
eigenvectors (FermionicArrayFlat) – The abelian array of right eigenvectors.

class symmray.Z2FermionicArrayFlat(sectors, blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None)[source]¶

Bases: FermionicArrayFlat

Fermionic abelian symmetric array with flat backend.

Parameters:

sectors (array_like) – The stack of sector keys, with shape (num_blocks, ndim). Each row represents a sector of a corresponding block, and each column represents a charge in a given axis.
blocks (array_like) – The stack of array blocks, with shape (num_blocks, *shape_block), i.e. ndim + 1 dimensions, where the first dimension is the block index, which should match the first dimension of sectors, and the rest are the dimensions of individual blocks.
indices (sequence[FlatIndex]) – Indices describing the dualness and any subindex information for each dimension of the array. If bools are supplied, they will be converted to a FlatIndex with the corresponding dualness, and no subindex information.
phases (array_like, optional) – An array of +/- 1 phases, with shape (num_blocks,), giving the phase of each block. If not supplied, all phases are assumed to be +1.
label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.
dummy_modes (sequence[FermionicOperator], optional) – A sequence of dummy fermionic modes representing to effectively prepend to the array.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

static_symmetry¶

class symmray.FlatVector(sectors, blocks)[source]¶

Class for storing block vectors with flat storage, e.g. for the singular- or eigen- values of a matrix.

This is equivalent to the diagonal of a zero charge abelian matrix.

Parameters:

sectors (array_like) – The vector of charges, with shape (num_blocks,).
blocks (array_like) – The stack of vectors, with shape (num_blocks, charge_subsize).

__slots__ = ('_blocks', '_sectors', 'backend')¶

classmethod from_blocks(blocks)[source]¶

Create a flat vector from a dictionary of blocks.

Parameters:: blocks (dict) – Dictionary mapping sector (charge) to block (array).

classmethod from_blockvector(blockvector)[source]¶

Create a flat backend vector from a sparse backend BlockVector.

Parameters:: blockvector (BlockVector) – The BlockVector to convert.

to_blockvector()[source]¶: Convert to a sparse backend BlockVector.

classmethod from_fill_fn(fill_fn, sectors, charge_size)[source]¶

Create a flat vector by filling blocks using a function that takes a shape and returns an array.

Parameters:

fill_fn (callable) – Function that takes a shape tuple and returns an array of that shape.
sectors (array_like or int or str) – The vector of charges, with shape (num_blocks,). If an integer is given, it is assumed to be Z{N} symmetry and the sectors are set to range(N). If a string is given, it is assumed to be of the form “ZN” for some integer N.
charge_size (int) – The size of each charge block.
like (str or array_like, optional)

classmethod rand(sectors, charge_size, dist='normal', seed=None, like='numpy')[source]¶

property size¶: The total size of all elements in the vector.

property shape: tuple[int, Ellipsis]¶: Get the effective shape of the vector.

copy(deep=False) → FlatVector[source]¶

copy_with(sectors=None, blocks=None) → FlatVector[source]¶: Create a copy of the vector with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

modify(sectors=None, blocks=None)[source]¶: Modify the vector in place with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

check()[source]¶

sort_stack(inplace=False)[source]¶: Sort the sectors and associated blocks in ascending order of charge.

_binary_blockwise_op(other, fn, missing=None, inplace=False)[source]¶

to_dense()[source]¶

__repr__()[source]¶

symmray.ham_fermi_hubbard_from_edges(symmetry, edges, t=1.0, U=8.0, mu=0.0, like='numpy', flat=False)[source]¶

Return a dict of local 2-body Hamiltonian terms for the Fermi-Hubbard model on the given lattice defined by edges. 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”.
edges (Sequence[tuple[Hashable, Hashable]]) – A list of edges representing the lattice, each edge is a tuple of two nodes, each node is some hashable label.
t (float, dict or callable, optional) – The hopping parameter, by default 1.0. If a dict is given it should map edges to values, if a callable it should take the two sites as input.
U (float dict or callable, optional) – The interaction parameter, by default 8.0. If a dict is given it should map sites to values, if a callable it should take the site as input.
mu (float, optional) – The chemical potential, by default 0.0.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return flat arrays, by default False.

Returns:

A dictionary mapping edges to local Hamiltonian terms.

Return type:

dict[tuple[Hashable, Hashable], FermionicArray | FermionicArrayFlat]

symmray.ham_fermi_hubbard_spinless_from_edges(symmetry, edges, t=1.0, V=0.0, mu=0.0, delta=0.0, like='numpy', flat=False)[source]¶

Return a dict of local 2-body Hamiltonian terms for the ‘spinless Fermi-Hubbard’ or (‘t-V’) model on the given lattice defined by edges. model on the given lattice defined by edges.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
edges (Sequence[tuple[Hashable, Hashable]]) – A list of edges representing the lattice, each edge is a tuple of two nodes, each node is some hashable label.
t (float, optional) – The hopping parameter, by default 1.0.
V (float, optional) – The nearest neighbor interaction parameter, by default 0.0.
mu (float, optional) – The chemical potential, by default 0.0.
delta (float, optional) – The nearest neighbor superconducting pairing parameter, by default 0.0.
like (str, optional) – The backend to use, by default “numpy”.
flat (bool, optional) – Whether to return flat arrays, by default False.

Returns:

A dictionary mapping edges to local Hamiltonian terms.

Return type:

dict[tuple[Hashable, Hashable], FermionicArray | FermionicArrayFlat]

symmray.ham_heisenberg_from_edges(symmetry, edges, flat=False, **kwargs)[source]¶

Return a dict of local 2-body Hamiltonian abelian symmetric terms for the Heisenberg model on the given lattice defined by edges.

Parameters:

symmetry (str) – The symmetry of the model. Either “Z2” or “U1”.
edges (Sequence[tuple[Hashable, Hashable]]) – A list of edges representing the lattice, each edge is a tuple of two nodes, each node is some hashable label.
flat (bool, optional) – Whether to return flat arrays, by default False.

Returns:

A dictionary mapping edges to local Hamiltonian terms.

Return type:

dict[tuple[Hashable, Hashable], AbelianArray | AbelianArrayFlat]

symmray.ham_tfim_from_edges(symmetry, edges, jx=-1.0, hz=-3.0, flat=False)[source]¶

Return a dict of local 2-body Hamiltonian abelian symmetric terms for the transverse field Ising model on the given lattice defined by edges:

H = jx * sum_ij X_i X_j + hz * sum_i Z_i

Note that its rotated into the x-basis so that the Z2 symmetry is manifest.

Parameters:

symmetry (str) – The symmetry of the model. Should be “Z2”.
edges (Sequence[tuple[Hashable, Hashable]]) – A list of edges representing the lattice, each edge is a tuple of two nodes, each node is some hashable label.
jx (float, dict, or callable, optional) – The coupling strength for the X-X interactions, by default -1.0. If a dict is given it should map edges to values, if a callable it should take the two sites as input.
hz (float, dict or callable, optional) – The coupling strength for the Z interactions, by default -3.0. If a dict is given it should map sites to values, if a callable it should take the site as input.
flat (bool, optional) – Whether to return flat arrays, by default False.

Returns:

A dictionary mapping edges to local Hamiltonian terms.

Return type:

dict[tuple[Hashable, Hashable], AbelianArray | AbelianArrayFlat]

symmray.abs(x)[source]¶: Return the absolute value of a symmray array.

symmray.align_axes(x, y, axes)[source]¶

symmray.all(x)[source]¶: Check if all elements of a symmray array are true.

symmray.any(x)[source]¶: Check if any elements of a symmray array are true.

symmray.clip(x, a_min, a_max)[source]¶: Clip the values of a symmray array.

symmray.conj(x, **kwargs)[source]¶: Conjugate a symmray array.

symmray.einsum(*args, **kwargs)[source]¶: Perform an Einstein summation on a symmray array, this simply uses cotengra to dispatch the full expression into pairwise tensordot (or einsum if necessary) calls.

symmray.expand_dims(x, axis)[source]¶: Expand the shape of a symmray array.

symmray.fuse(x, *axes_groups)[source]¶: Fuse multiple axes of a symmray array.

symmray.imag(x)[source]¶: Return the imaginary part of a symmray array.

symmray.isfinite(x)[source]¶: Check if a symmray array contains only finite values.

symmray.lddiv(v, x)[source]¶: Left divide a symmray matrix x by a vector v.

symmray.ldmul(v, x)[source]¶: Left multiply a symmray matrix x by a vector v.

symmray.log(x)[source]¶: Return the natural logarithm of a symmray array.

symmray.log2(x)[source]¶: Return the base-2 logarithm of a symmray array.

symmray.log10(x)[source]¶: Return the base-10 logarithm of a symmray array.

symmray.max(x)[source]¶: Return the maximum value of a symmray array.

symmray.min(x)[source]¶: Return the minimum value of a symmray array.

symmray.multiply_diagonal(x, v, axis)[source]¶: Multiply a symmray array by a vector as if contracting a diagonal matrix into one axis.

symmray.rddiv(x, v)[source]¶: Right divide a symmray matrix x by a vector v.

symmray.rdmul(x, v)[source]¶: Right multiply a symmray matrix x by a vector v.

symmray.real(x)[source]¶: Return the real part of a symmray array.

symmray.reshape(a, newshape, **kwargs)[source]¶: Reshape a symmray array, via fusing or unfusing.

symmray.sqrt(x)[source]¶: Return the square root of a symmray array.

symmray.squeeze(x, axis=None)[source]¶: Remove single-dimensional entries from shape of a symmray array.

symmray.sum(x)[source]¶: Return the sum of a symmray array.

symmray.take(a, indices, axis, **kwargs)[source]¶: Take elements from a symmray array along an axis.

symmray.tensordot(a, b, axes=2, **kwargs)[source]¶

Contract two symmray arrays along the specified axes.

Parameters:

a (AbelianArray or FermionicArray) – First array to contract.
b (AbelianArray or FermionicArray) – Second array to contract, with same type as a.
axes (int or tuple of int, optional) – If an integer, the number of axes to contract. If a tuple, the axes to contract. Default is 2.

symmray.trace(a)[source]¶: Return the trace of a symmray array.

symmray.transpose(a, axes=None, **kwargs)[source]¶: Transpose a symmray array.

symmray.MPS_abelian_rand(symmetry, L, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{}', site_ind_id='k{}', fermionic=False, flat=False, site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random MPS with abelian symmetry.

Parameters:

symmetry (str or Symmetry) – The symmetry of the MPS.
L (int) – The number of sites.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the MPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the MPS is cyclic.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
fermionic (bool, optional) – Whether to generate fermionic tensors.
flat (bool, optional) – Whether to generate ‘flat’ backend arrays (True) or the default block-sparse backend arrays (False).
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.MatrixProductState

symmray.MPS_fermionic_rand(symmetry, L, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{}', site_ind_id='k{}', site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random fermionic MPS. This is a wrapper around MPS_abelian_rand() with fermionic=True.

Parameters:

symmetry (str or Symmetry) – The symmetry of the MPS.
L (int) – The number of sites.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the MPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the MPS is cyclic.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.MatrixProductState

symmray.PEPS3D_abelian_rand(symmetry, Lx, Ly, Lz, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{},{},{}', site_ind_id='k{},{},{}', x_tag_id='X{}', y_tag_id='Y{}', z_tag_id='Z{}', fermionic=False, site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random 3D PEPS with abelian symmetry.

Parameters:

symmetry (str or Symmetry) – The symmetry of the PEPS.
Lx (int) – Length of the PEPS in the x-direction.
Ly (int) – Length of the PEPS in the y-direction.
Lz (int) – Length of the PEPS in the z-direction.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the PEPS is cyclic in the x-direction.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
fermionic (bool, optional) – Whether to generate fermionic tensors.
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.PEPS3D

symmray.PEPS3D_fermionic_rand(symmetry, Lx, Ly, Lz, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{},{},{}', site_ind_id='k{},{},{}', x_tag_id='X{}', y_tag_id='Y{}', z_tag_id='Z{}', site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random 3D fermionic PEPS. This is a wrapper around PEPS3D_abelian_rand() with fermionic=True.

Parameters:

symmetry (str or Symmetry) – The symmetry of the PEPS.
Lx (int) – Length of the PEPS in the x-direction.
Ly (int) – Length of the PEPS in the y-direction.
Lz (int) – Length of the PEPS in the z-direction.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the PEPS is cyclic in the x-direction.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.PEPS3D

symmray.PEPS_abelian_rand(symmetry, Lx, Ly, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{},{}', site_ind_id='k{},{}', x_tag_id='X{}', y_tag_id='Y{}', fermionic=False, flat=False, site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random 2D PEPS with abelian symmetry.

Parameters:

symmetry (str or Symmetry) – The symmetry of the PEPS.
Lx (int) – The number of rows.
Ly (int) – The number of columns.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the PEPS is cyclic in the x-direction.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
fermionic (bool, optional) – Whether to generate fermionic tensors.
flat (bool, optional) – Whether to generate ‘flat’ backend arrays (True) or the default block-sparse backend arrays (False).
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.PEPS

symmray.PEPS_fermionic_rand(symmetry, Lx, Ly, bond_dim, phys_dim=2, cyclic=False, seed=None, dtype='float64', site_tag_id='I{},{}', site_ind_id='k{},{}', x_tag_id='X{}', y_tag_id='Y{}', site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random 2D fermionic PEPS. This is a wrapper around PEPS_abelian_rand() with fermionic=True.

Parameters:

symmetry (str or Symmetry) – The symmetry of the PEPS.
Lx (int) – The number of rows.
Ly (int) – The number of columns.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, a default charge distribution is chosen. If a dictionary, a custom map of physical charges to sizes.
cyclic (bool, optional) – Whether the PEPS is cyclic in the x-direction.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.PEPS

symmray.TN_abelian_from_edges_rand(symmetry, edges, bond_dim, phys_dim=None, seed=None, dtype='float64', site_tag_id='I{}', site_ind_id='k{}', fermionic=False, flat=False, site_charge=None, subsizes='maximal', **kwargs)[source]¶

Build a random abelian symmetric quimb.tensor amplitude or PEPS from edges.

Parameters:

symmetry ({"Z2", "U1", "Z2Z2", "U1U1", ZN}) – The symmetry of the PEPS. Currently only “Z2” and “U1” are supported.
edges (list of tuples) – The edges of the PEPS. Each edge is a tuple of the form (cooa, coob) where cooa and coob are hashable labels of the two sites.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (None, int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, all sites have the same dimension. If a dictionary, a custom map of physical charges to sizes.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
fermionic (bool, optional) – Whether to generate fermionic tensors.
flat (bool, optional) – Whether to generate ‘flat’ backend arrays (True) or the default block-sparse backend arrays (False).
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alternate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.TensorNetworkGen or quimb.tensor.TensorNetworkGenVector

symmray.TN_fermionic_from_edges_rand(symmetry, edges, bond_dim, phys_dim=None, seed=None, dtype='float64', site_tag_id='I{}', site_ind_id='k{}', site_charge=None, subsizes='maximal', **kwargs)[source]¶

Create a random fermionic tensor network from edges. This is a wrapper around TN_abelian_from_edges_rand() with fermionic=True.

Parameters:

symmetry ({"Z2", "U1", "Z2Z2", "U1U1", ZN}) – The symmetry of the PEPS. Currently only “Z2” and “U1” are supported.
edges (list of tuples) – The edges of the PEPS. Each edge is a tuple of the form (cooa, coob) where cooa and coob are hashable labels of the two sites.
bond_dim (int or dict) – The total (sum of charge sizes) bond dimension of the PEPS. You can also provide an explicit map of bond charges to sizes.
phys_dim (None, int or dict, optional) – The physical dimension of each site. If None, no physical sites are included. If an integer, all sites have the same dimension. If a dictionary, a custom map of physical charges to sizes.
seed (None, int or np.random.Generator, optional) – The random seed or generator to use.
dtype (str, optional) – The data type of the tensors.
site_tag_id (str, optional) – The tag format for each site tensor.
site_ind_id (str, optional) – The index format for each site tensor, if physical sites are included.
site_charge (callable, optional) – A function that takes a site index and returns the charge of that site. By default it will create all even parity tensors if Z2=0 or it will alernate between 0 and 1 for U1.
subsizes ({"maximal", "equal"}, optional) – The sizes of the charge sectors. If None, the sizes are randomly determined. If “equal”, the sizes are equal (up to remainders). If “maximal”, as many charges as possible will be chosen.
kwargs – Additional arguments to pass to symmray.utils.get_rand().

Return type:

quimb.tensor.TensorNetworkGen or quimb.tensor.TensorNetworkGenVector

symmray.parse_edges_to_site_info(edges, bond_dim, phys_dim=2, site_ind_id='k{}', bond_ind_id='b{}-{}', site_tag_id='I{}')[source]¶

Given a list of edges, return a dictionary of site information, each specifying the local shape, index identifiers, index dualnesses, and tags. The dualnesses of the bonds are set in a canonical order corresponding to sorting all the sites and the edges.

Parameters:

edges (Sequence[Tuple[hashable, hashable]]) – The edges of the graph.
bond_dim (int) – The internal bond dimension.
phys_dim (int, optional) – The physical dimension of the sites.
site_ind_id (str, optional) – The identifier for the site indices.
bond_ind_id (str, optional) – The identifier for the bond indices.
site_tag_id (str, optional) – The identifier for the site tags.

Return type:

Dict[hashable, Dict[str, Any]]

class symmray.AbelianArray(indices, charge=None, blocks=(), symmetry=None, label=None)[source]¶

Bases: symmray.sparse.sparse_array_common.SparseArrayCommon, symmray.sparse.sparse_data_common.BlockCommon, symmray.bosonic_common.BosonicCommon, symmray.array_common.ArrayCommon, symmray.common.SymmrayCommon

A block sparse array with symmetry constraints.

Parameters:

indices (tuple[BlockIndex]) – The indices of the array.
charge (hashable, optionals) – The total charge of the array, if not given it will be inferred from either the first sector or set to the identity charge, if no sectors are given.
blocks (dict[tuple[hashable], array_like]) – A mapping of each ‘sector’ (tuple of charges) to the data array.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

__slots__ = ('_blocks', '_charge', '_indices', '_label', '_symmetry')¶

fermionic = False¶

static_symmetry = None¶

new_with(indices, charge, blocks, label=None) → AbelianArray[source]¶: Create a new block sparse abelian array of the same class as this one. Unlike copy, this does not copy over any existing data and drops for example label.

copy()[source]¶: Copy this abelian block sparse array.

copy_with(indices=None, charge=None, blocks=None)[source]¶: A copy of this block array with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

modify(indices=None, charge=None, blocks=None)[source]¶: Modify this block array in place with some attributes replaced. Note that checks are not performed on the new properties, this is intended for internal use.

classmethod from_pytree(pytree)[source]¶: Create a sparse abelian array from a pytree purely of non-symmray containers and objects.

_map_blocks(fn_block=None, fn_sector=None, fn_filter=None)[source]¶: Map the blocks and their keys (sectors) of the array inplace.

solve(b: AbelianArray, **kwargs) → AbelianArray[source]¶

Solve the linear system A @ x == b for x, where A is this array.

Parameters:: b (AbelianArray) – The right-hand side array.
Returns:: x – The solution array.
Return type:: AbelianArray

class symmray.U1Array(indices, charge=None, blocks=(), symmetry=None, label=None)[source]¶

Bases: AbelianArray

A block array with U1 symmetry.

static_symmetry¶

to_pyblock3(flat=False)[source]¶

to_yastn(**config_opts)[source]¶

class symmray.U1U1Array(indices, charge=None, blocks=(), symmetry=None, label=None)[source]¶

Bases: AbelianArray

A block array with U1 x U1 symmetry.

static_symmetry¶

class symmray.Z2Array(indices, charge=None, blocks=(), symmetry=None, label=None)[source]¶

Bases: AbelianArray

A block array with Z2 symmetry.

static_symmetry¶

to_pyblock3(flat=False)[source]¶

class symmray.Z2Z2Array(indices, charge=None, blocks=(), symmetry=None, label=None)[source]¶

Bases: AbelianArray

A block array with Z2 x Z2 symmetry.

static_symmetry¶

class symmray.BlockIndex(chargemap=None, dual=False, subinfo=None, linearmap=None)[source]¶

Bases: symmray.index_common.Index

An index of a block sparse, abelian symmetric tensor. This is intended to be used immutably.

Parameters:

chargemap (dict[int, int]) – A mapping from charge to size.
dual (bool, optional) – Whether the index is ‘dual’ or not, i.e. whether the flow is ‘outwards’ / (+ve) / ket-like = False or ‘inwards’ / (-ve) / bra-like = True. The sign of charge contributions is then (-1) ** dual.
subinfo (SubIndexInfo, optional) – Information about the subindices of this index and their extents if this index was formed from fusing.
linearmap (Sequence[tuple[hashable, int], ...], optional) – If provided, a sequence of (charge, offset) pairs for a linear ordering of this index. This can be supplied instead of chargemap, in which case the chargemap is built from this. If not provided, it is built on demand from chargemap, assuming blocks of sorted charges.

__slots__ = ('_chargemap', '_dual', '_subinfo', '_hashkey', '_linearmap')¶

_dual = False¶

_subinfo = None¶

_hashkey = None¶

_linearmap = None¶

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

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

copy_with(**kwargs)[source]¶: A copy of this index with some attributes replaced. Note that checks are not performed on the new propoerties, this is intended for internal use.

to_flat()[source]¶: Convert this index to a flat index.

property chargemap¶: A mapping from charge to size.

property linearmap¶: A sequence of (charge, offset) pairs for each element of this index, in linear order. This is built on demand if not provided at creation.

property subshape¶

property charges¶: The charges of this index.

property sizes¶: The sizes of the blocks of this index.

property size_total¶: The total size of this index, i.e. the sum of the sizes of all blocks.

property num_charges¶: The number of charges.

conj()[source]¶: A copy of this index with the dualness reversed.

drop_charges(charges)[source]¶

Return a new index with all charges in charges removed.

Parameters:: charges (Sequence[hashable]) – The charges to remove.
Returns:: A new index with the charges removed.
Return type:: BlockIndex

select_charge(charge, subselect=None) → BlockIndex[source]¶

Drop all but the specified charge from this index.

Parameters:

charge (hashable) – The charge to keep.
subselect (slice or array_like, optional) – If provided, a range of indices within the selected charge block to keep. If not provided, the entire block is kept.

Return type:

BlockIndex

size_of(c)[source]¶: The size of the block with charge c.

linear_to_charge_and_offset(i)[source]¶

Given a linear index i into this index (as if it were a dense array), return the corresponding charge and offset within that charge block.

Parameters:

i (int) – The linear index into this index.

Returns:

charge (hashable) – The charge corresponding to the linear index.
offset (int) – The offset within the charge block corresponding to the linear index.

check()[source]¶: Check that the index is well-formed, i.e. all sizes are positive.

matches(other)[source]¶

Whether this index matches other index, namely, whether the chargemap of each matches, their dualnesses are opposite, and also whether their subindices match, if they have any. For debugging.

Parameters:: other (BlockIndex) – The other index to compare to.

hashkey()[source]¶: Get a hash key for this index.

abstractmethod __hash__()[source]¶

__str__()[source]¶

__repr__()[source]¶

symmray.default_tensordot_mode(mode)[source]¶

Context manager to temporarily change the default tensordot mode.

Parameters:: mode ({"auto", "fused", "blockwise"}) – The mode to use for the contraction.

symmray.get_default_tensordot_mode()[source]¶: Get the current default tensordot mode.

symmray.set_default_tensordot_mode(mode)[source]¶

Set the default tensordot mode.

Parameters:: mode ({"auto", "fused", "blockwise", None}) – The mode to use for the contraction. None is no-op.

class symmray.FermionicArray(indices, charge=None, blocks=(), phases=(), label=None, dummy_modes=None, symmetry=None)[source]¶

Bases: symmray.fermionic_common.FermionicCommon, symmray.sparse.sparse_array_common.SparseArrayCommon, symmray.sparse.sparse_data_common.BlockCommon, symmray.array_common.ArrayCommon, symmray.common.SymmrayCommon

A fermionic block symmetry array.

Parameters:

indices (tuple of Index) – The indices of the array.
charge (hashable, optionals) – The total charge of the array, if not given it will be inferred from either the first sector or set to the identity charge, if no sectors are given.
blocks (dict, optional) – The blocks of the array, by default empty.
phases (dict, optional) – The lazy phases of each block, by default empty.
label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.
symmetry (str or Symmetry, optional) – The symmetry of the array, if not using a specific symmetry class.

__slots__ = ('_blocks', '_charge', '_dummy_modes', '_indices', '_label', '_phases', '_symmetry')¶

fermionic = True¶

static_symmetry = None¶

_phases¶

_dummy_modes = ()¶

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

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

property parity¶: The parity of the total charge.

property phases¶: The lazy phases of each sector. Trivial phases are not necessarily stored.

copy()[source]¶

Create a copy of this fermionic array.

Returns:: The copied array.
Return type:: FermionicArray

new_with(indices, charge, blocks, label=None)[source]¶: Create a new block sparse fermionic array of the same class as this one. Unlike copy, this does not copy over any existing data and drops by default label, phases, and dummy_modes.

copy_with(indices=None, blocks=None, charge=None, phases=None)[source]¶

Create a copy of this fermionic array with some attributes replaced.

Parameters:

indices (tuple of Index, optional) – The new indices, if None, the original indices are used.
blocks (dict, optional) – The new blocks, if None, the original blocks are used.
charge (int, optional) – The new total charge, if None, the original charge is used.
phases (dict, optional) – The new phases, if None, the original phases are used.

modify(indices=None, blocks=None, charge=None, phases=None, dummy_modes=None)[source]¶

Modify this fermionic array inplace. This is for internal use, and does not perform any checks on the updated attributes.

Parameters:

indices (tuple of Index, optional) – The new indices, if None, the original indices are used.
blocks (dict, optional) – The new blocks, if None, the original blocks are used.
charge (int, optional) – The new total charge, if None, the original charge is used.
phases (dict, optional) – The new phases, if None, the original phases are used.
dummy_modes (object or FermionicOperator, optional) – The new dummy_modes, if None, the original dummy_modes are used.

randomize_phases(seed=None, inplace=False) → FermionicArray[source]¶

Randomize the phases of each sector to either +1 or -1. This is useful for testing.

Parameters:

seed (int or numpy.random.Generator, optional) – The random seed or generator, by default None.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The phase randomized array.

Return type:

phase_sync(inplace=False) → FermionicArray[source]¶

Multiply all lazy phases into the block arrays.

Parameters:: inplace (bool, optional) – Whether to perform the operation in place.
Returns:: The resolved array, which now has no lazy phases.
Return type:: FermionicArray

phase_flip(*axs, inplace=False) → FermionicArray[source]¶

Flip the phase of all sectors with odd parity at the given axis.

Parameters:

ax (int) – The axis along which to flip the phase.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The phase-flipped array.

Return type:

phase_transpose(axes=None, inplace=False)[source]¶

Parameters:

axes (tuple of int, optional) – The permutation of axes, by default None.
inplace (bool, optional) – Whether to perform the operation in place.

Return type:

phase_sector(sector, inplace=False)[source]¶

Flip the phase of a specific sector.

Parameters:

sector (tuple of hashable) – The sector to flip the phase of.
inplace (bool, optional) – Whether to perform the operation in place.

Return type:

phase_global(inplace=False)[source]¶

Flip the global phase of the array.

Parameters:: inplace (bool, optional) – Whether to perform the operation in place.
Return type:: FermionicArray

_map_blocks(fn_block=None, fn_sector=None, fn_filter=None)[source]¶: Map the blocks and their keys (sectors) of the array inplace.

_resolve_dummy_modes_conj(phase_permutation=True)[source]¶: Assuming we have effectively taken the conjugate of a fermionic array with dummy modes, get their new order and compute any phase changes coming from moving back to the beginning of the index order.

_resolve_dummy_modes_combine(left, right)[source]¶: Calculate the new combined dummy odd modes and any associated global phases combing from contracting two fermionic arrays a and b. This modifies this array in place.

_resolve_dummy_modes_squeeze(axes_squeeze)[source]¶: Assuming we are about to squeeze away axes_squeeze, compute the phases associated with moving them to the beginning of the array, and then turn them into dummy modes.

transpose(axes=None, phase=True, inplace=False)[source]¶

Transpose the fermionic array, by default accounting for the phases accumulated from swapping odd charges.

Parameters:

axes (tuple of int, optional) – The permutation of axes, by default None.
phase (bool, optional) – Whether to flip the phase of sectors whose odd charges undergo a odd permutation. By default True.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The transposed array.

Return type:

conj(phase_permutation=True, phase_dual=False, inplace=False)[source]¶

Conjugate this fermionic array. By default this include phases from both the virtual flipping of all axes, but not the conjugation of dual indices, such that:

(
    tensordot_fermionic(x.conj(), x, ndim) ==
    tensordot_fermionic(x, x.conj(), ndim)
)

If all indices have matching dualness (i.e. all bra or all ket), or you set phase_dual=True then the above contractions will also be equal to x.norm() ** 2.

Parameters:

phase_permutation (bool, optional) – Whether to flip the phase of sectors whose odd charges undergo a odd permutation due to virtually flipping the order of axes, by default True.
phase_dual (bool, optional) – Whether to flip the phase of dual indices, by default False. If a FermionicArray has a mix of dual and non-dual indices, and you are explicitly forming the norm, you may want to set this to True. But if it is part of a large tensor network you only need to flip the phase of true ‘outer’ dual indices.

Return type:

dagger(phase_dual=False, inplace=False)[source]¶

Fermionic adjoint, implements .H attribute.

Parameters:

phase_dual (bool, optional) – Whether to flip the phase of dual indices, by default False. If a FermionicArray has a mix of dual and non-dual indices, and you are explicitly forming the norm, you may want to set this to True. But if it is part of a large tensor network you only need to flip the phase of ‘outer’ dual indices.
inplace (bool, optional) – Whether to perform the operation in place.

Returns:

The conjugate transposed array.

Return type: