Creating MPS and MPO#

Initializing empty MPS/MPO#

MPS and MPO are instances of class yastn.tn.mps.MpsMpoOBC.

class yastn.tn.mps.MpsMpoOBC(N=1, nr_phys=1)[source]#

Initialize empty MPS (nr_phys=1) or MPO (nr_phys=2) for system of N sites. Empty MPS/MPO has no tensors assigned.

MpsMpoOBC tensors (sites) are indexed by integers \(0,1,2,\ldots,N-1\), where \(0\) corresponds to the 'first' site. They can be accessed with [] operator. MPS/MPO can contain a central block associated with a bond and indexed by a tuple \((n,n+1)\). At most one central block is allowed.

The legs’ order of each tensor is: (0) virtual leg pointing towards the first site, (1) 1st physical leg, i.e., \(|\textrm{ket}\rangle\), (2) virtual leg pointing towards the last site, and, in case of MPO, (3) 2nd physical leg, i.e., \(\langle \textrm{bra}|\).

Parameter self.factor allows separating the norm of the object (potentially different from \(1\)) from the canonical form of MPS or MPO tensors.

One can directly create a new empty MPS of N sites using yastn.tn.mps.Mps(N). Similarly, yastn.tn.mps.Mpo(N) initializes MPO. The new instances start without any tensors defined.

yastn.tn.mps.Mps(N) → MpsMpoOBC[source]#

Generate empty MPS for system of N sites, fixing nr_phys=1.

yastn.tn.mps.Mpo(N, periodic=False) → MpsMpoOBC | MpoPBC[source]#

Generate empty MPO for system of N sites, fixing nr_phys=2.

A flag periodic allows initializing periodic MPO, which is a special class supported as an operator in MPS environments.

Setting MPS/MPO tensors by hand#

An empty MPS/MPO can be filled with tensors by setting them one by one.

import yastn
import yastn.tn.mps as mps

# create empty MPS over three sites
psi = mps.Mps(3)

# create 3x2x3 random dense tensor
config = yastn.make_config()  # config for dense tensors
legs = [yastn.Leg(config, s=-1, D=(3,)),
        yastn.Leg(config, s=1, D=(2,)),
        yastn.Leg(config, s=1, D=(3,))]
A_1 = yastn.rand(config, legs=legs)

# assign tensor to site 1
psi[1] = A_1

Tensor should be of the rank expected for MPS or MPO. The virtual dimensions/spaces of the neighboring MPS/MPO tensors should be consistent, which, however, is not tested during assigment. For examples showing creation of MPS/MPO by hand, see Ground state of Spin-1 AKLT model and MPO for hopping model with U(1) symmetry.

Initializing product MPS/MPO#

yastn.tn.mps.product_mps(vectors, N=None) → yastn.tn.mps.MpsMpoOBC[source]#

Generate an MPS with bond-dimension 1 from a list of vectors that get assigned to consecutive MPS sites.

If N is provided, vectors are cyclicly iterated to fill in N MPS sites.

Parameters:

  • vectors (Sequence[yastn.Tensor] | yastn.Tensor) – Tensors will be attributed to consecutive MPS sites. They can have non-zero charges that will be converted into matching MPS virtual legs. Each tensor should have ndim=1.

  • N (Optional[int]) – number of MPS sites. By default, it is equal to the number of provided vectors.

yastn.tn.mps.product_mpo(operators, N=None) → yastn.tn.mps.MpsMpoOBC[source]#

Generate an MPO with bond-dimension 1 from a list of operators that get assigned to consecutive MPO sites.

If N is provided, operators are cyclicly iterated to fill in N MPO sites.

Parameters:

  • operators (Sequence[yastn.Tensor] | yastn.Tensor) – Tensors will be attributed to consecutive MPS sites. They can have non-zero charges, that will be converted into matching MPO virtual legs. Each tensor should have ndim=2.

  • N (Optional[int]) – number of MPO sites. By default, it is equal to the number of provided operators.

Example

# This function can help set up an identity MPO,
# which is the base ingredient for a few other functions
# generating more complicated MPOs and MPSs.

import yastn
import yastn.tn.mps as mps

ops = yastn.operators.Spin12(sym='Z2')
I = mps.product_mpo(ops.I(), N=8)

# Here, each site has the same local physical Hilbert space
# of dimension 2, consistent with predefined spin-1/2 operators.
# The MPO I uniquely identifies those local Hilbert spaces.

Initializing random MPS/MPO#

yastn.tn.mps.random_mps(I, n=None, D_total=8, sigma=1, dtype='float64') → yastn.tn.mps.MpsMpoOBC[source]#

Generate a random MPS of total charge n and bond dimension D_total.

Local Hilbert spaces are read from ket spaces of provided MPS or MPO I. For instance, I can be an identity MPO. The number of sites and Tensor config is also inherited from I.

Parameters:

  • I (yastn.tn.mps.MpsMpoOBC) – MPS or MPO that defines local Hilbert spaces.

  • n (int) – Total charge of MPS. Virtual MPS spaces are drawn randomly from a normal distribution, whose mean value changes linearly along the chain from n to 0.

  • D_total (int) – Largest bond dimension. Note that due to the random and local nature of the procedure, the desired total bond dimension might not be reached on some bonds, in particular, for higher symmetries.

  • sigma (int) – The standard deviation of the normal distribution.

  • dtype (string) – Number format, i.e., 'float64' or 'complex128'

Example

import yastn
import yastn.tn.mps as mps

ops = yastn.operators.SpinlessFermions(sym='U1')
I = mps.product_mpo(ops.I(), N=13)
psi = mps.random_mps(I, n=6, D_total=8)

# Random MPS with 13 sites occupied by 6 fermions (fixed by U1 symmetry),
# and maximal bond dimension 8.
yastn.tn.mps.random_mpo(I, D_total=8, sigma=1, dtype='float64') → yastn.tn.mps.MpsMpoOBC[source]#

Generate a random MPO with bond dimension D_total.

The number of sites and local bra and ket spaces of MPO follow from provided MPO I, e.g., an identity MPO. I can be an MPS, in which case its ket spaces are used and conjugated for bra spaces.

Parameters:

  • I (yastn.tn.mps.MpsMpoOBC) – MPS or MPO that defines local spaces.

  • D_total (int) – Largest bond dimension. Note that due to the random and local nature of the procedure, the desired total bond dimension might not be reached on some bonds, in particular, for higher symmetries.

  • sigma (int) – Standard deviation of a normal distribution from which dimensions of charge sectors are drawn.

  • dtype (string) – number format, i.e., 'float64' or 'complex128'

Generating MPO using Hterm#

See examples at Building MPO using Hterm.

We provide functionality to build MPO representations for a broad class of operators, e.g., Hamiltonians, given as a sum of products of local (on-site) operators. They are encoded as a list of mps.Hterm, where each mps.Hterm represents a product of local operators, including the numerical coefficient (amplitude) in front of that product.

To generate the corresponding MPO use mps.generate_mpo(I, terms), where terms is a list of Hterm-s and I is the identity MPO. The latter can be conveniently created as shown in mps.product_mpo. For an example, see MPO for spinless fermions with long-range hopping via Hterms.

class yastn.tn.mps.Hterm(amplitude: float = 1.0, positions: tuple = (), operators: tuple = ())[source]#

Defines a product operator \(O= amplitude {\times} \bigotimes_i o_i\) of local operators \(o_i\). Local operators that are not explicitly specified are assumed to be identity operators.

If operators are fermionic, execution of swap gates enforces fermionic order, with the last operator in operators acting first.

Parameters:

  • amplitude (number) – numerical multiplier in front of the operator product.

  • positions (Sequence[int]) – positions of the local operators \(o_i\) in the product different than identity.

  • operators (Sequence[yastn.Tensor]) – local operators in the product that are different than the identity. i-th operator is acting at positions[i]. Each operator should have ndim=2 and signature matching local identity.

Create new instance of Hterm(amplitude, positions, operators)

yastn.tn.mps.generate_mpo(I, terms=None, opts_svd=None, N=None) → yastn.tn.mps.MpsMpoOBC[source]#

Generate MPO provided a list of Hterm-s and identity operator I.

Apply yastn.swap_gate() to introduce fermionic degrees of freedom, where the fermionic order matches the order of sites in Mps. With this respect, local operators specified in term.operators are applied starting with the last element, i.e., from right to left.

The function compresses MPO using a series of SVDs. It might get expensive if the number of terms is large, e.g., for all-to-all 2-site terms and N in hundreds. If this becomes an issue, it is best to use some divide-and-conquer strategy or precompute desired MPO.

Parameters:

  • I (yastn.tn.mps.MpsMpoOBC | yastn.Tensor | Sequence[yastn.Tensor]) – Identity MPO, which specifies local identity operators at each site and the number of sites. It is also possible to provide a local identity operator or list of such operators, together with N, following the syntax of mps.product_mpo.

  • terms (Sequence[yastn.tn.mps.Hterm]) – Product operators making up MPO.

  • opts_svd (dict) – Options passed to yastn.linalg.svd_with_truncation(). The function employs SVD while compressing the MPO bond dimensions. Default None sets truncation tol close to the numerical precision, which typically results in lossless compression.

  • N (int) – Number of MPO sites. If identity MPO is provided, it is overridden by I.N.

Generator class for MPO/MPS (beta)#

A class supporting automatizes generation of MPOs from LaTeX-like expressions.

See examples at Generator class for MPO/MPS.

class yastn.tn.mps.Generator(N, operators, map=None, Is=None, parameters=None, opts={'tol': 1e-13})[source]#

Generator is a convenience class building MPOs from a set of local operators.

Parameters:

  • N (int) – number of sites of MPO.

  • operators (object or dict[str, yastn.Tensor]) – a set of local operators, e.g., an instance of yastn.operators.Spin12. Or a dictionary with string-labeled local operators, including at least {'I': <identity operator>,...}.

  • map (dict[int, int]) – custom labels of N sites indexed from 0 to N-1 , e.g., {3: 0, 21: 1, ...}. If None, the sites are labled as {site: site for site in range(N)}.

  • Is (dict[int, str]) – For each site (using default or custom label), specify identity operator by providing its string key as defined in operators. If None, assumes {i: 'I' for i in range(N)}, which is compatible with all predefined operators.

  • parameters (dict) – Default parameters used by the interpreters Generator.mpo() and Generator.mps(). If None, uses default {'sites': [*map.keys()]}.

  • opts (dict) – used if compression is needed. Options passed to yastn.linalg.svd_with_truncation().

We can directly output identity MPO built from the identity I from the operator generator class.

Generator.I() → yastn.tn.mps.MpsMpoOBC[source]#

Identity MPO derived from identity in local operators class.

Generator.mpo_from_latex(H_str, parameters=None, opts=None) → yastn.tn.mps.MpsMpoOBC[source]#

Convert latex-like string to yastn.tn.mps MPO.

Parameters:

  • H_str (str) – The definition of the MPO given as latex expression. The definition uses string names of the operators given in. The assignment of the location is given e.g. for ‘cp’ operator as ‘cp_{j}’ (always with {}-brackets!) for ‘cp’ operator acting on site ‘j’. The space and * are interpreted as multiplication by a number of by an operator. E.g., to multiply by a number use ‘g * cp_j c_{j+1}’ where ‘g’ has to be defines in ‘parameters’ or writen directly as a number, You can define automatic summation with expression ‘sum_{j in A}’, where A has to be iterable, one-dimensional object with specified values of ‘j’.

  • parameters (dict) – Keys for the dict define the expressions that occur in H_str

Generator allows initialization of MPS and MPO filled with random tensors, where local Hilbert spaces are read from the identity operator in the Generator. It also provides a direct link to a random number generator in the backend to fix the seed.

Generator.random_mps(n=None, D_total=8, sigma=1, dtype='float64') → yastn.tn.mps.MpsMpoOBC[source]#

Generate a random MPS of total charge n and bond dimension D_total.

Equivalent to mps.random_mps.

Generator.random_mpo(D_total=8, sigma=1, dtype='float64') → yastn.tn.mps.MpsMpoOBC[source]#

Generate a random MPO with bond dimension D_total.

Equivalent to mps.random_mps.

Generator.random_seed(seed)[source]#

Set seed for random number generator used in backend (of self.config).

Parameters:

seed (int) – Seed number for random number generator.

Making a copy of MPS/MPO#

To create an independent copy or clone of MPS/MPO psi call psi.copy() or psi.clone(), respectively. It is also possible to make a shallow copy with psi.shallow_copy(), where explicit copies of data tensors are not created.

MpsMpoOBC.shallow_copy() → yastn.tn.mps.MpsMpoOBC#

New instance of yastn.tn.mps.MpsMpoOBC pointing to the same tensors as the old one.

Shallow copy is usually sufficient to retain the old MPS/MPO.

MpsMpoOBC.copy() → yastn.tn.mps.MpsMpoOBC#

Makes a copy of MPS or MPO by copying all yastn.Tensor’s into a new and independent yastn.tn.mps.MpsMpoOBC.

MpsMpoOBC.clone() → yastn.tn.mps.MpsMpoOBC#

Makes a clone of MPS or MPO by cloning all yastn.Tensor’s into a new and independent yastn.tn.mps.MpsMpoOBC.

Import and export MPS/MPO from/to different formats#

See examples at Save and load MPS/MPO.

MPS/MPO can be saved as Python dict or HDF5 file. The MPS/MPO previously serialized by yastn.tn.mps.MpsMpoOBC.save_to_dict() or yastn.tn.mps.MpsMpoOBC.save_to_hdf5() can be again deserialized into MPS/MPO.

MpsMpoOBC.save_to_dict() → dict[str, dict | Number]#

Serialize MPS/MPO into a dictionary.

Each element represents serialized yastn.Tensor (see, yastn.Tensor.save_to_dict()) of the MPS/MPO. Absorbs central block if it exists.

MpsMpoOBC.save_to_hdf5(file, my_address)#

Save MPS/MPO into a HDF5 file.

Parameters:

  • file (File) – A pointer to a file opened by the user

  • my_address (str) – Name of a group in the file, where the Mps will be saved, e.g., ‘state/’

mps.load_from_dict(in_dict) → yastn.tn.mps.MpsMpo#

Create MPS/MPO from dictionary.

Parameters:

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

  • in_dict (dict) – dictionary containing serialized MPS/MPO, i.e., a result of yastn.tn.mps.MpsMpo.save_to_dict().

mps.load_from_hdf5(file, my_address) → yastn.tn.mps.MpsMpo#

Create MPS/MPO from HDF5 file.

Parameters:

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

  • file (File) – A pointer to a file opened by the user

  • my_address (str) – Name of a group in the file, where the Mps is saved, e.g., ‘./state/’