symmray.fermionic_common ======================== .. py:module:: symmray.fermionic_common .. autoapi-nested-parse:: Common methods for any fermionic arrays. Classes ------- .. autoapisummary:: symmray.fermionic_common.FermionicCommon Functions --------- .. autoapisummary:: symmray.fermionic_common.parse_dummy_modes Module Contents --------------- .. py:function:: 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. .. py:class:: FermionicCommon .. py:property:: dummy_modes :type: tuple[symmray.fermionic_local_operators.FermionicOperator, Ellipsis] A sequence of dummy fermionic modes effectively prepended to the array, used to describe odd parity arrays. .. py:method:: _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. .. py:method:: _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. :param axes_groups: The axes groups to fuse. See `AbelianArray.fuse` for more details. :type axes_groups: Sequence[Sequence[int]] :param inplace: Whether to perform the operation inplace or return a new array. :type inplace: bool, optional :rtype: FermionicArray .. py:method:: 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. :param axis: The axis to unfuse. :type axis: int .. py:method:: einsum(eq, preserve_array=False) Einsum for fermionic arrays, currently only single term. :param eq: The einsum equation, e.g. "abcb->ca". The output indices must be specified and only trace and permutations are allowed. :type eq: str :param preserve_array: If tracing to a scalar, whether to return an AbelianArray object with no indices, or simply scalar itself (the default). :type preserve_array: bool, optional :rtype: FermionicCommon or scalar .. py:method:: trace() Fermionic matrix trace. .. py:method:: _prepare_for_tensordot_fermionic(other, axes) Perform necessary fermionic phase operations to prepare two arrays for an abelian tensordot. .. py:method:: 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. :param a: The first fermionic array. :type a: FermionicArray :param b: The second fermionic array. :type b: FermionicArray :param axes: The axes to contract over, by default 2. :type axes: int or (tuple[int], tuple[int]), optional :param preserve_array: Whether to preserve the array structure even if the result is a scalar, by default False. :type preserve_array: bool, optional :param kwargs: Passed to the underlying (non-fermionic) tensordot call. :rtype: FermionicCommon or scalar .. py:method:: __matmul__(other: FermionicCommon, preserve_array=False) Matrix or vector multiplication, accounting for fermionic phases. :param other: The other fermionic array to multiply. :type other: FermionicCommon :param preserve_array: Whether to preserve the array structure even if the result is a scalar, by default False. :type preserve_array: bool, optional .. py:method:: to_dense() Return dense representation of the fermionic array, with lazy phases multiplied in. .. py:method:: 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. :param axis: The axis or axes to squeeze. If None, all axes of size 1 are removed, by default None. :type axis: int or tuple[int], optional :param inplace: Whether to perform the operation inplace or return a new array. :type inplace: bool, optional :rtype: FermionicCommon .. py:method:: 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. .. py:method:: 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. .. py:method:: 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. .. py:method:: 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. .. py:method:: allclose(other, **kwargs) Check if two fermionic arrays are element-wise equal within a tolerance, accounting for phases. :param other: The other fermionic array to compare. :type other: FermionicArray .. py:method:: 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. :param other: The other array to compare to. :type other: SparseArrayCommon :param allclose_opts: Keyword arguments to pass to `allclose`. :raises AssertionError: If the arrays are not close. .. py:method:: _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. :param drop_dummy_modes: 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". :type drop_dummy_modes: {"auto", bool}, optional .. py:method:: cholesky(*, upper=False, drop_dummy_modes='auto') -> FermionicCommon Cholesky decomposition of a fermionic array. :param upper: Whether to return the upper triangular Cholesky factor. Default is False, returning the lower triangular factor. :type upper: bool, optional :param drop_dummy_modes: 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. :type drop_dummy_modes: {"auto", bool}, optional :returns: **l_or_r** -- The Cholesky factor. Lower triangular if ``upper=False``, upper triangular if ``upper=True``. :rtype: FermionicCommon .. py:method:: 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. :param absorb: 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)``. :type absorb: {-12, 0, 12}, optional :param shift: 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. :type shift: float, optional :param drop_dummy_modes: 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. :type drop_dummy_modes: {"auto", bool}, optional :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. .. py:method:: solve(b: FermionicCommon, **kwargs) -> FermionicCommon Solve linear system Ax = b for x, where A is this fermionic array. :param b: The right hand side array. :type b: FermionicCommon :returns: **x** -- The solution array. :rtype: FermionicCommon