symmray.flat.flat_fermionic_array

Fermionic symmetric arrays with flat backend.

Classes

FermionicArrayFlat	Fermionic abelian symmetric array with flat backend.
Z2FermionicArrayFlat	Fermionic abelian symmetric array with flat backend.

Functions

perm_to_swaps(perm)

Convert a permutation to a list of swaps.

Module Contents

symmray.flat.flat_fermionic_array.perm_to_swaps(perm)

Convert a permutation to a list of swaps.

Parameters:

perm (tuple[int, ...]) – The permutation to convert. Should be a permutation of the elements in range(len(perm)).

Returns:

A tuple of swaps that will perform the permutation.

Return type:

tuple[tuple[int, int], …]

class symmray.flat.flat_fermionic_array.FermionicArrayFlat(sectors, blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None)

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()

Check the internal consistency of the array.

new_with(sectors, blocks, indices, label=None) → FermionicArrayFlat

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

Create a copy of the array.

copy_with(sectors=None, blocks=None, indices=None, phases=None) → FermionicArrayFlat

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

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)

Set the underlying array blocks.

to_pytree()

Convert this flat fermionic array to a pytree purely of non-symmray containers and objects.

classmethod from_pytree(data)

Create a flat fermionic array from a pytree purely of non-symmray containers and objects.

_map_blocks(fn_sector=None, fn_block=None)

classmethod from_blocks(blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None) → FermionicArrayFlat

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)

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

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

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.

phase_sync(inplace=False) → FermionicArrayFlat

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

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:

FermionicArrayFlat

phase_transpose(axes=None, inplace=False) → FermionicArrayFlat

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:

FermionicArrayFlat

abstractmethod phase_sector(sector, inplace=False)

phase_global(inplace=False)

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)

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)

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)

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

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:

FermionicArrayFlat

conj(phase_permutation=True, phase_dual=False, inplace=False)

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:

FermionicArrayFlat

dagger(phase_dual=False, inplace=False)

Fermionic conjugate transpose.

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

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.flat.flat_fermionic_array.Z2FermionicArrayFlat(sectors, blocks, indices, phases=None, label=None, dummy_modes=None, symmetry=None)

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