symmray.fermionic_common

Common methods for any fermionic arrays.

Classes

FermionicCommon

Functions

parse_dummy_modes(parity, label, dummy_modes[, ...])

Parse the dummy modes for a fermionic array, possibly creating a single

Module Contents

symmray.fermionic_common.parse_dummy_modes(parity, label, dummy_modes, warn_odd=False, prune_even=False)

Parse the dummy modes for a fermionic array, possibly creating a single mode from the array label to mimic an overall even parity array.

class symmray.fermionic_common.FermionicCommon

property dummy_modes: tuple[symmray.fermionic_local_operators.FermionicOperator, Ellipsis]

A sequence of dummy fermionic modes effectively prepended to the array, used to describe odd parity arrays.

_binary_blockwise_op(other, fn, inplace=False, **kwargs)

Need to sync phases before performing blockwise operations.

This is used across many basic methods defined in AbelianArray such as __add__, __imul__ etc.

_fuse_core(*axes_groups, inplace=False) → FermionicCommon

Fermionic fusion of axes groups. This includes three sources of phase changes:

1. Initial fermionic transpose to make each group contiguous.

2. Flipping of non dual indices, if merged group is overall dual.

3. Virtual transpose within a group, if merged group is overall dual.

A grouped axis is overall dual if the first axis in the group is dual.

Parameters:

• axes_groups (Sequence[Sequence[int]]) – The axes groups to fuse. See AbelianArray.fuse for more details.

• inplace (bool, optional) – Whether to perform the operation inplace or return a new array.

Return type:

FermionicArray

unfuse(axis, inplace=False)

Fermionic unfuse, which includes two sources of phase changes:

1. Flipping of non dual sub indices, if overall index is dual.

2. Virtual transpose within group, if overall index is dual.

Parameters:

axis (int) – The axis to unfuse.

einsum(eq, preserve_array=False)

Einsum for fermionic arrays, currently only single term.

Parameters:

• eq (str) – The einsum equation, e.g. “abcb->ca”. The output indices must be specified and only trace and permutations are allowed.

• preserve_array (bool, optional) – If tracing to a scalar, whether to return an AbelianArray object with no indices, or simply scalar itself (the default).

Return type:

FermionicCommon or scalar

trace()

Fermionic matrix trace.

_prepare_for_tensordot_fermionic(other, axes)

Perform necessary fermionic phase operations to prepare two arrays for an abelian tensordot.

tensordot(other, axes=2, preserve_array=False, **kwargs) → FermionicCommon

Contract two fermionic arrays along the specified axes, accounting for phases from both transpositions and contractions.

Parameters:

• a (FermionicArray) – The first fermionic array.

• b (FermionicArray) – The second fermionic array.

• axes (int or (tuple[int], tuple[int]), optional) – The axes to contract over, by default 2.

• preserve_array (bool, optional) – Whether to preserve the array structure even if the result is a scalar, by default False.

• kwargs – Passed to the underlying (non-fermionic) tensordot call.

Return type:

FermionicCommon or scalar

__matmul__(other: FermionicCommon, preserve_array=False)

Matrix or vector multiplication, accounting for fermionic phases.

Parameters:

• other (FermionicCommon) – The other fermionic array to multiply.

• preserve_array (bool, optional) – Whether to preserve the array structure even if the result is a scalar, by default False.

to_dense()

Return dense representation of the fermionic array, with lazy phases multiplied in.

squeeze(axis=None, inplace=False) → FermionicCommon

Squeeze the fermionic array, removing axes of size 1. If those axes correspond to odd parity charges, then they are converged into dummy dummy_modes modes effectively to the left of the array. The sorting label of the array is then required to have been set.

Parameters:

• axis (int or tuple[int], optional) – The axis or axes to squeeze. If None, all axes of size 1 are removed, by default None.

• inplace (bool, optional) – Whether to perform the operation inplace or return a new array.

Return type:

FermionicCommon

dagger_compose_left() → FermionicCommon

Take the dagger (conjugate transpose) of this fermionic array, assuming we have the right factor of a hermitian decomposition and want the left factor.

dagger_project_left() → FermionicCommon

Take the dagger (conjugate transpose) of this fermionic array, assuming we are going to use to project from the left on another operator.

dagger_compose_right() → FermionicCommon

Take the dagger (conjugate transpose) of this fermionic array, assuming we have the left factor of a hermitian decomposition and want the right factor.

dagger_project_right() → FermionicCommon

Take the dagger (conjugate transpose) of this fermionic array, assuming we are going to use to project from the right on another operator.

allclose(other, **kwargs)

Check if two fermionic arrays are element-wise equal within a tolerance, accounting for phases.

Parameters:

other (FermionicArray) – The other fermionic array to compare.

test_allclose(other, **allclose_opts)

Assert that this SparseArrayCommon is close to another, that is, has all the same sectors, and the corresponding arrays are close. Unlike allclose, this raises an AssertionError with details if not.

Parameters:

• other (SparseArrayCommon) – The other array to compare to.

• allclose_opts – Keyword arguments to pass to allclose.

Raises:

AssertionError – If the arrays are not close.

_split(*args, charge_side='auto', drop_dummy_modes='auto', **kwargs)

Fermionic array splitting, involving a phase sync, the abelian split which is handled by the backend, and then a possible phase flip depending of the dualness of the inner bond.

Parameters:

drop_dummy_modes ({"auto", bool}, optional) – Whether to drop dummy_modes (and the array label) from the returned factors. Useful is using the factors as projectors rather than replacements for the original array. If “auto”, will drop if the method is “eigh”.

cholesky(*, upper=False, drop_dummy_modes='auto') → FermionicCommon

Cholesky decomposition of a fermionic array.

Parameters:

• upper (bool, optional) – Whether to return the upper triangular Cholesky factor. Default is False, returning the lower triangular factor.

• drop_dummy_modes ({"auto", bool}, optional) – Whether to drop dummy_modes (and the array label) from the returned factors. Useful is using the factors as projectors rather than replacements for the original array. If “auto”, will drop.

Returns:

l_or_r – The Cholesky factor. Lower triangular if upper=False, upper triangular if upper=True.

Return type:

FermionicCommon

cholesky_regularized(absorb=0, shift=True, drop_dummy_modes='auto') → FermionicCommon

Cholesky decomposition with optional diagonal regularization, returning results in an SVD-like (left, None, right) format for compatibility with tensor network split drivers. Handles fermionic phase synchronization automatically.

Parameters:

• absorb ({-12, 0, 12}, optional) –

  How to return the factors:

  • 0 ('both'): return (L, None, L^H).

  • -12 ('lsqrt'): return (L, None, None).

  • 12 ('rsqrt'): return (None, None, L^H).

• shift (float, optional) – Diagonal regularization shift. If True or negative, auto-compute from dtype machine epsilon. The shift is always applied as a relative shift scaled by the trace of each block. Default is True.

• drop_dummy_modes ({"auto", bool}, optional) – Whether to drop dummy_modes (and the array label) from the returned factors. Useful is using the factors as projectors rather than replacements for the original array. If “auto”, will drop.

Returns:

• left (FermionicCommon or None) – The lower Cholesky factor, or None.

• s (None) – Always None (no singular values).

• right (FermionicCommon or None) – The conjugate transpose of the Cholesky factor, or None.

solve(b: FermionicCommon, **kwargs) → FermionicCommon

Solve linear system Ax = b for x, where A is this fermionic array.

Parameters:

b (FermionicCommon) – The right hand side array.

Returns:

x – The solution array.

Return type:

FermionicCommon