Creating symmetric YASTN tensors#

Initializing symmetric tensors from scratch#

Symmetric tensor can be initialized as ‘’blank`` or more precisely empty. In this case only its rank (specified through signature tuple) and symmetry needs to be known when initializing such empty symmetric tensors. The data, in a form of non-zero blocks, can be added at later time.

See examples: Create empty tensor and fill it block by block.

class yastn.Tensor(config=None, s=(), n=None, isdiag=False, **kwargs)[source]#

Initialize empty (without any blocks allocated) YASTN tensor.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • s (Sequence[int]) – a signature of tensor. Also determines the number of legs.

  • n (int | Sequence[int]) – total charge of the tensor. In case of direct product of several abelian symmetries, n is a tuple with total charge for each individual symmetry.

  • isdiag (bool) – distinguish diagonal tensor as a special case of a tensor.

Tensor.set_block(ts=(), Ds=None, val='zeros')#

Add new block to tensor or change the existing one.

This is the intended way to add new blocks by hand. Checks if bond dimensions of the new block are consistent with the existing ones and updates the legs of the tensors accordingly.

Parameters:

  • ts (Sequence[int] | Sequence[Sequence[int]]) – Charges identifing the block. Ignored if tensor has no symmetry.

  • Ds (Sequence[int]) – Dimensions of the block. If None, tries to infer dimensions from legs of the tensor.

  • val (str | tensor-like) – recognized string values are 'rand', 'ones',`or 'zeros'. Otherwise any tensor-like format such as nested list, numpy.ndarray, etc., can be used provided it is supported by tensor’s backend.

Basic creation operations#

Basic creation operations includes operations such as creating random tensors, tensors filled with zeros, or diagonal identity tensors.

The symmetry structure of the tensor can be given either by directly listing all charge sectors for each leg and dimensions of these sectors or by passing a list of legs.

See examples: Create tensors from scratch.

Import methods of yastn Tensor.

yastn.eye(config=None, legs=(), isdiag=True, **kwargs) → yastn.Tensor[source]

Initialize diagonal tensor of identity matrix. In presence of symmetries, such matrix is block-diagonal with all allowed blocks filled with identity matrices.

Note

Currently supports either one or two legs as input. In case of a single leg, an identity matrix with Leg and its conjugate yastn.Leg.conj() is returned.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • legs (Sequence[yastn.Leg]) – Specify legs of the tensor passing a list of yastn.Leg.

  • isdiag (bool) – Specify by bool whether to return explicitly diagonal tensor. If True, the signatures of the legs have to be opposite, and fused legs are not supported. If False, it supports having fused legs and any combination of signatures.

  • device (str) – Device on which the tensor should be initialized. Overrides attribute default_device specified in configuration.

  • s (Optional[Sequence[int]]) – (alternative) Tensor signature; should be (1, -1) or (-1, 1). Default is s=(1, -1).

  • t (Optional[Sequence[Sequence[int | Sequence[int]]]]) – (alternative) List of charges for each leg. Default is t=().

  • D (Optional[list]) – (alternative) List of corresponding bond dimensions. Default is D=().

Note

If any of s, t, or D are specified, legs are overriden and only t, D, and s are used.

yastn.ones(config=None, legs=(), n=None, isdiag=False, **kwargs) → yastn.Tensor[source]

Initialize tensor with all allowed blocks filled with ones.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • legs (Sequence[yastn.Leg]) – Specify legs of the tensor passing a list of yastn.Leg.

  • n (int | Sequence[int]) – total charge of the tensor.

  • isdiag (bool) – whether or not to make tensor diagonal.

  • dtype (str) – Desired datatype, overrides default_dtype specified in configuration.

  • device (str) – Device on which the tensor should be initialized. Overrides attribute default_device specified in configuration.

  • s (Optional[Sequence[int]]) – (alternative) Tensor signature. Also determines the number of legs. Default is s=().

  • t (Optional[Sequence[Sequence[int | Sequence[int]]]]) – (alternative) List of charges for each leg. Default is t=().

  • D (Optional[Sequence[Sequence[int]]]) – (alternative) List of corresponding bond dimensions. Default is D=().

Note

If any of s, t, or D are specified, legs are overriden and only t, D, and s are used.

yastn.rand(config=None, legs=(), n=None, isdiag=False, **kwargs) → yastn.Tensor[source]

Initialize tensor with all allowed blocks filled with random numbers.

Draws from a uniform distribution in [-1, 1] or [-1, 1] + 1j * [-1, 1], depending on desired dtype.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • legs (Sequence[yastn.Leg]) – Specify legs of the tensor passing a list of yastn.Leg.

  • n (int | Sequence[int]) – Total charge of the tensor.

  • isdiag (bool) – whether or not to make tensor diagonal.

  • dtype (str) – Desired datatype, overrides default_dtype specified in configuration.

  • device (str) – Device on which the tensor should be initialized. Overrides attribute default_device specified in configuration.

  • s (Optional[Sequence[int]]) – (alternative) Tensor signature. Also determines the number of legs. Default is s=().

  • t (Optional[Sequence[Sequence[int | Sequence[int]]]]) – (alternative) List of charges for each leg. Default is t=().

  • D (Optional[Sequence[Sequence[int]]]) – (alternative) List of corresponding bond dimensions. Default is D=().

Note

If any of s, t, or D are specified, legs are overriden and only t, D, and s are used.

yastn.randC(config=None, legs=(), n=None, isdiag=False, **kwargs) → yastn.Tensor[source]

Initialize tensor with all allowed blocks filled with complex random numbers, see yastn.rand().

yastn.randR(config=None, legs=(), n=None, isdiag=False, **kwargs) → yastn.Tensor[source]

Initialize tensor with all allowed blocks filled with real random numbers, see yastn.rand().

yastn.zeros(config=None, legs=(), n=None, isdiag=False, **kwargs) → yastn.Tensor[source]

Initialize tensor with all allowed blocks filled with zeros.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • legs (Sequence[yastn.Leg]) – Specify legs of the tensor passing a list of yastn.Leg.

  • n (int | Sequence[int]) – total charge of the tensor.

  • isdiag (bool) – whether or not to make tensor diagonal

  • dtype (str) – Desired datatype, overrides default_dtype specified in configuration.

  • device (str) – Device on which the tensor should be initialized. Overrides attribute default_device specified in configuration.

  • s (Optional[Sequence[int]]) – (alternative) Tensor signature. Also determines the number of legs. Default is s=().

  • t (Optional[Sequence[Sequence[int | Sequence[int]]]]) – (alternative) List of charges for each leg. Default is t=().

  • D (Optional[Sequence[Sequence[int]]]) – (alternative) List of corresponding bond dimensions. Default is D=().

Note

If any of s, t, or D are specified, legs are overriden and only t, D, and s are used.

Copying and cloning with autograd#

YASTN follows the semantics of PyTorch with regards to creating differentiable clones or non-differentiable copies of symmetric tensors. See clone and detach for PyTorch.

See YASTN examples: Clone, detach or copy tensors.

Tensor.copy() → yastn.Tensor#

Return a copy of the tensor. Data of the resulting tensor is independent from the original.

Warning

This operation does not preserve autograd on returned yastn.Tensor.

Return type:

yastn.Tensor

Tensor.clone() → yastn.Tensor#

Return a clone of the tensor preserving the autograd - resulting clone is a part of the computational graph. Data of the resulting tensor is indepedent from the original.

Tensor.detach() → yastn.Tensor#

Detach tensor from the computational graph returning a view.

Data of the resulting tensor is a view of the original data. In case of NumPy backend, returns self.

Warning

This operation does not preserve autograd on returned yastn.Tensor.

Changing tensor’s device or dtype#

Support for different compute devices, i.e. CPU, GPU, or others, depends on the selected backend. For example

  • NumPy backend supports only CPU,

  • PyTorch backend supports also GPU (and other devices).

Tensors can be moved between devices and/or their dtype may be changed

Tensor.to(device=None, dtype=None) → yastn.Tensor#

Move tensor to device and cast to given datatype.

Returns a clone of the tensor residing on device in desired datatype dtype. If tensor already resides on device, returns self. This operation preserves autograd. If no change is needed, makes only a shallow copy of the tensor data.

Parameters:

  • device (str) – device identifier

  • dtype (str) – desired dtype

Import/Export of YASTN tensors from/to different formats#

These utility operations can export and then import tensors from different formats. For example, exporting and importing tensor or MPS to and from a file.

See examples: Serialization of symmetric tensors.

yastn.Tensor.save_to_dict(a) → dict#

Export YASTN tensor to dictionary containing all the information needed to recreate the tensor.

Allows saving the tensor, e.g., with numpy.save().

Complementary function is yastn.load_from_dict().

Parameters:

a (yastn.Tensor) – tensor to export.

yastn.Tensor.save_to_hdf5(a, file, path) → Never#

Export tensor into hdf5 type file.

Complementary function is yastn.load_from_hdf5().

Parameters:

a (yastn.Tensor) – tensor to export.

yastn.Tensor.compress_to_1d(a, meta=None) → tuple[numpy.array | torch.tensor, dict]#

Return 1D array containing tensor data (without cloning the data if not necessary) and create metadata allowing re-creation of the original tensor.

Parameters:

  • a (yastn.Tensor) – Specifies tensor to export.

  • meta (dict) – There is an option to provide meta-data obtained from earlier application of yastn.Tensor.compress_to_1d(). Extra zero blocks (missing in tensor) are then included in the returned 1D array to make it consistent with structure given in meta. Raises error if tensor has some blocks which are not included in meta or otherwise meta does not match the tensor.

Note

yastn.Tensor.compress_to_1d() and yastn.decompress_from_1d() provide mechanism that allows using external matrix-free methods, such as eigs() implemented in SciPy.

Returns:

  • tensor (type derived from backend) – 1D array with tensor data.

  • dict – metadata with structure of the symmetric tensor needed to encode the 1D array into blocks.

yastn.load_from_dict(config=None, d=None) → yastn.Tensor[source]#

Create tensor from the dictionary d.

Parameters:
yastn.load_from_hdf5(config, file, path) → yastn.Tensor[source]#

Create tensor from hdf5 file.

Parameters:

  • config (module | _config(NamedTuple)) – YASTN configuration

  • file – pointer to opened HDF5 file.

  • path – path inside the file which contains the state.

yastn.decompress_from_1d(r1d, meta) → yastn.Tensor[source]#

Generate tensor from dictionary meta describing the structure of the tensor, charges and dimensions of its non-zero blocks, and 1-D array r1d containing serialized data of non-zero blocks.

Typically, the pair r1d and meta is obtained from yastn.Tensor.compress_to_1d().

Parameters:

  • r1d (rank-1 tensor) – 1-D array (of backend type) holding serialized blocks.

  • meta (dict) – structure of symmetric tensor. Non-zero blocks are indexed by associated charges. Each such entry contains block’s dimensions and the location of its data in rank-1 tensor r1d.