symmray.array_common¶

Methods that apply to all Abelian symmetric arrays, regardless of backend.

Classes¶

ArrayCommon

Common base class for all abelian arrays with symmetry, fermionic or

Functions¶

`_is_squeeze_entry`(entry)
`_is_matched_axis_entry`(entry)
`_match_reshape_forward`(shape, subshapes, newshape, ...)	Match `shape[i_start:i_stop]` to `newshape[j_start:j_stop]` from
`_match_reshape_reverse`(shape, subshapes, newshape, ...)	Match `shape[i_start:i_stop]` to `newshape[j_start:j_stop]` from
`_absorb_squeeze_entries`(entries)	Attach squeezed singleton axes to a neighbouring kept dimension.
`_entries_to_reshape_args`(entries, ndim_old)	Convert target entries to unfuse/fuse/expand operation arguments.
`calc_reshape_args`(shape, newshape, subshapes)	Given a current block sparse shape `shape` a target shape `newshape`
`without`(it, remove)	Return a tuple of the elements in `it` with those at positions
`parse_tensordot_axes`(axes, ndim_a, ndim_b)	Parse the axes argument for single integer and also negative indices.
`maybe_keep_label`(label_a, label_b)	Decide whether to keep labels from operands when combining two arrays.

Module Contents¶

symmray.array_common._is_squeeze_entry(entry)[source]¶

symmray.array_common._is_matched_axis_entry(entry)[source]¶

symmray.array_common._match_reshape_forward(shape, subshapes, newshape, i_start, i_stop, j_start, j_stop)[source]¶: Match shape[i_start:i_stop] to newshape[j_start:j_stop] from left to right, returning target entries and the first unconsumed input axis.

symmray.array_common._match_reshape_reverse(shape, subshapes, newshape, i_start, i_stop, j_start, j_stop)[source]¶: Match shape[i_start:i_stop] to newshape[j_start:j_stop] from right to left, returning target entries and the first consumed input axis.

symmray.array_common._absorb_squeeze_entries(entries)[source]¶: Attach squeezed singleton axes to a neighbouring kept dimension.

symmray.array_common._entries_to_reshape_args(entries, ndim_old)[source]¶: Convert target entries to unfuse/fuse/expand operation arguments.

symmray.array_common.calc_reshape_args(shape, newshape, subshapes)[source]¶

Given a current block sparse shape shape a target shape newshape and current sub index sizes subshapes (i.e. previously fused dimensions) compute the sequence of axes to unfuse, fuse and expand to reshape the array.

A single -1 entry in newshape is interpreted structurally: it consumes whichever input axes are not matched by the rest of the target shape (fusing them if there is more than one). This avoids the division-by-size resolution which can be ambiguous for sparse arrays whose fused-axis sizes do not equal the product of their subshape.

Parameters:

shape (tuple[int]) – The current shape of the array.
newshape (tuple[int]) – The target shape of the array. May contain at most one -1.
subshapes (tuple[None or tuple[int]]) – The sizes of the subindices that were previously fused.

Returns:

axs_unfuse (tuple[int]) – The axes to unfuse.
axs_fuse (tuple[tuple[tuple[int]]]) – The axes (after unfusing) to fuse, grouped by contiguous groups.
axs_expand (tuple[int]) – The axes (after unfusing and fusing) to expand.

class symmray.array_common.ArrayCommon[source]¶

Common base class for all abelian arrays with symmetry, fermionic or not, sparse or flat etc.

property symmetry: symmray.symmetries.Symmetry¶: The symmetry object of the array.

property indices: tuple[symmray.index_common.Index, Ellipsis]¶: The indices of the array.

is_fused(ax: int) → bool[source]¶: Does axis ax carry subindex information, i.e., is it a fused index?

property duals: tuple[bool, Ellipsis]¶: The dual-ness of each index.

classmethod get_class_symmetry(symmetry=None) → symmray.symmetries.Symmetry[source]¶

property signature: str¶

__add__(other, inplace=False)[source]¶

__iadd__(other)[source]¶

__sub__(other, inplace=False)[source]¶

__isub__(other)[source]¶

__truediv__(other, inplace=False)[source]¶

__itruediv__(other)[source]¶

__pow__(other, inplace=False)[source]¶

property T: ArrayCommon¶: The transpose of the block array.

_dagger_abelian(inplace=False) → ArrayCommon[source]¶: Conjugate transpose or adjoint, implements the .H property.

property H: ArrayCommon¶

fuse(*axes_groups, expand_empty=True, inplace=False, **kwargs) → ArrayCommon[source]¶

Fuse the given group or groups of axes. The new fused axes will be inserted at the minimum index of any fused axis (even if it is not in the first group). For example, x.fuse([5, 3], [7, 2, 6]) will produce an array with axes like:

groups inserted at axis 2, removed beyond that.
       ......<--
(0, 1, g0, g1, 4, 8, ...)
       |   |
       |   g1=(7, 2, 6)
       g0=(5, 3)

The fused axes will carry subindex information, which can be used to automatically unfuse them back into their original components. Depending on expand_empty, any empty groups can be expanded to new singlet dimensions, or simply ignored.

Parameters:

axes_groups (Sequence[Sequence[int]]) – The axes to fuse. Each group of axes will be fused into a single axis.
expand_empty (bool, optional) – Whether to expand empty groups into new axes.
mode ("auto", "insert", "concat", optional) – The method to use for fusing. “insert” creates the new fused blocks and insert the subblocks inplace. “concat” recursively concatenates the subblocks, which can be slightly slower but is more compatible with e.g. autodiff. “auto” will use “insert” if the backend is numpy, otherwise “concat”.
inplace (bool, optional) – Whether to perform the operation inplace or return a new array.
kwargs (dict, optional) – Additional keyword arguments to pass to the core fusing method.

Return type:

ArrayCommon

unfuse_all(inplace=False) → ArrayCommon[source]¶

Unfuse all indices that carry subindex information, likely from a fusing operation.

Parameters:: inplace (bool, optional) – Whether to perform the operation inplace or return a new array.
Return type:: ArrayCommon

reshape(newshape, inplace=False) → ArrayCommon[source]¶

Reshape this abelian array to newshape, assuming it can be done by any mix of fusing, unfusing, and expanding new axes.

Restrictions and complications vs normal array reshaping arise from the fact that

only previously fused axes can be unfused, and their total size may not be the product of the individual sizes due to sparsity.

the indices carry information beyond size and how they are grouped potentially matters, relevant for singleton dimensions.

Accordingly the approach here is as follows:

Unfuse any axes that match the new shape.

If there are singleton dimensions that don’t appear in the new shape, (i.e. are being ‘squeezed’) these are grouped with the axis to the their left to then be fused. If they are already left-most, they are grouped with the right.

Fuse any groups of axes required to match the new shape. Adjacent groups are fused simultaneously for efficiency.

Expand new axes required to match singlet dimensions in the new shape. By default these will have zero charge and dual-ness iherited from whichever axis is to their left, or right if they are the left-most axis already.

To avoid the effective grouping of ‘squeezed’ axes you can explicitly squeeze them before reshaping. Similarly use expand_dims to add new axes with specific charges and dual-ness.

newshape may contain at most one -1 entry, which is resolved structurally: it absorbs whichever input axes are not matched by the rest of the target shape (fusing them if there is more than one). This differs from numpy’s division-based resolution and avoids ambiguity when fused-index sizes do not equal the product of their subshape due to sparsity.

Parameters:

newshape (tuple[int]) – The new shape to reshape to. May contain at most one -1.
inplace (bool, optional) – Whether to perform the operation inplace or return a new array.

Return type:

ArrayCommon