YASTN configuration

All YASTN tensors have to be provided with configuration, which defines:

1. linear algebra backend

2. abelian symmetry group

3. default data type (float64, complex128) and device (provided it is supported by backend) of a tensor

4. fermionic statistics (controlling action of yastn.swap_gate())

The configuration can be provided as a Python module, types.SimpleNamespace, typing.NamedTuple, or similar, which defines the following members.

• required: backend, sym,

• optional: default_device, default_dtype, fermionic, default_fusion, force_fusion, tensordot_policy, meta_tensordot_policy, lazy_threshold.

The configuration can be conveniently generated using

yastn.make_config(**kwargs) → _config

Create a YASTN configuration object.

Parameters:

• backend (backend module or str) – Specify backend providing linear algebra and base dense tensors. Currently supported backends are

  • NumPy as yastn.backend.backend_np

  • PyTorch as yastn.backend.backend_torch

  The above backends can be specified as strings: “np”, “torch”. Defaults to NumPy backend.

• sym (symmetry module or compatible object or str) – Specify abelian symmetry. To see how YASTN defines symmetries, see yastn.sym.sym_abelian. Defaults to yastn.sym.sym_none, effectively a dense tensor. For predefined symmetries, takes string input from ‘none’ (or ‘dense’), ‘Z2’, ‘Z3’, ‘U1’, ‘U1xU1’, ‘U1xU1xZ2’.

• default_device (str) –

  Tensors can be stored on various devices as supported by backend

  • NumPy supports only 'cpu' device

  • PyTorch supports multiple devices, see https://pytorch.org/docs/stable/tensor_attributes.html#torch.torch.device

  If not specified, the default device is 'cpu'.

• default_dtype (str) – Default data type (dtype) of YASTN tensors. Supported options are: 'float64', 'complex128'. If not specified, the default dtype is 'float64'.

• fermionic (bool or tuple[bool,…]) – Specify behavior of yastn.swap_gate() function, allowing to introduce fermionic statistics. Allowed values: False, True, or a tuple (True, False, ...) with one bool for each component charge vector, i.e., of length sym.NSYM. The default is False.

• default_fusion (str) – Specify default strategy to handle leg fusion: 'hard' or 'meta'. See yastn.Tensor.fuse_legs() for details. The default is 'hard'.

• force_fusion (str) – Overrides fusion strategy provided in yastn.Tensor.fuse_legs(). The default is None.

• tensordot_policy (str) –

  Contraction approach used by yastn.tensordot()

  • 'fuse_to_matrix' Tensordot involves suitable permutation of each tensor while performing a fusion of each tensor into a sequence of matrices and calling matrix-matrix multiplication. Postprocessing includes unfusing the remaining legs in the result, which often copy data adding extra overhead.

  • 'fuse_contracted' Tensordot involves suitable permutation of each tensor while performing a fusion of to-be-contracted legs of each tensor and calling multiplication. It involves a larger number of multiplication calls for smaller objects, but unfusing the legs of the result is not needed.

  • 'no_fusion' Tensordot involves suitable permutation of tensor blocks and calling matrix-matrix multiplication for a potentially large number of small objects. Resulting contributions to new blocks get added. However, overheads of initial fusion (copying data) can sometimes be avoided in this approach.

• lazy_threshold (float = 0 if backend is cuTensor, else 0.5) – Not all symmetry-allowed blocks need to be present in “lazy” tensor. Hence, when computing a contractions with “lazy” tensors, not all blocks allowed by the symmetry need to exist in the resulting tensor. If the fraction (retained blocks / all allowed blocks) < lazy_threshold, then blocks are initialized lazily, i.e., only when they are needed. On cuTensor backend, defaults to 0, otherwise 0.5

  Impact:

  Decreases memory usage and flop count in contractions. The block-sparsity algebra is more expensive.

  Relevant scenarios:

  Outer-product-like contractions, where number of legs of resulting tensor is larger than the number of legs of the input tensors. In such cases, the number of allowed blocks can be much larger than the number of retained blocks.

• meta_tensordot_policy (str = “cpu”|”gpu”|”auto”) – Block-sparsity algorithm used by yastn.tensordot(). The default is 'auto', which uses the optimized GPU algorithm if available, otherwise the CPU algorithm. When “auto” can be also overriden by setting the environment variable YASTN_META_CUTENSOR to "GPU" or "CPU".

Example

config = yastn.make_config(backend='np', sym='U1')

Below is an example of configuration defined as a plain Python module, using NumPy backend and \(U(1)\) symmetry.

import yastn.backend.backend_np as backend
from yastn.sym import sym_U1 as sym

default_device: str = 'cpu'
default_dtype: str = 'float64'
fermionic = False
default_fusion: str = 'hard'
force_fusion: str = None