Quantum states (C code)¶

Matrix product states (MPS)¶

Matrix product state (MPS) data structure.

Enums

enum mps_orthonormalization_mode¶

MPS orthonormalization mode.

Values:

enumerator MPS_ORTHONORMAL_LEFT¶: left-orthonormal

enumerator MPS_ORTHONORMAL_RIGHT¶: right-orthonormal

Functions

void allocate_empty_mps(const int nsites, const ct_long d, const qnumber *qsite, struct mps *mps)¶: Allocate an “empty” matrix product state, without the actual tensors.

void allocate_mps(const enum numeric_type dtype, const int nsites, const ct_long d, const qnumber *qsite, const ct_long *dim_bonds, const qnumber **qbonds, struct mps *mps)¶: Allocate memory for a matrix product state. ‘dim_bonds’ and ‘qbonds’ must be arrays of length ‘nsites + 1’.

void delete_mps(struct mps *mps)¶: Delete a matrix product state (free memory).

void copy_mps(const struct mps *src, struct mps *dst)¶: Copy a matrix product state and its block sparse tensors.

void construct_random_mps(const enum numeric_type dtype, const int nsites, const ct_long d, const qnumber *qsite, const qnumber qnum_sector, const ct_long max_vdim, struct rng_state *rng_state, struct mps *mps)¶: Construct a matrix product state with random normal tensor entries, given an overall quantum number sector and maximum virtual bond dimension.

bool mps_is_consistent(const struct mps *mps)¶: Internal consistency check of the MPS data structure.

bool mps_allclose(const struct mps *chi, const struct mps *psi, const double tol)¶: Test whether two matrix product states agree in terms of sites, quantum numbers and entries within tolerance ‘tol’.

static inline ct_long mps_bond_dim(const struct mps *mps, const int i)¶: Dimension of i-th virtual bond of a matrix product state, starting with the leftmost (dummy) bond.

void mps_vdot(const struct mps *chi, const struct mps *psi, void *ret)¶: Compute the dot (scalar) product <chi | psi> of two MPS, complex conjugating chi.

double mps_norm(const struct mps *psi)¶

Compute the Euclidean norm of the MPS.

Result is returned as double also for single-precision tensor entries.

void mps_add(const struct mps *chi, const struct mps *psi, struct mps *ret)¶: Compute the logical addition of two MPS chi and psi (summing their virtual bond dimensions).

void mps_local_orthonormalize_qr(struct block_sparse_tensor *a, struct block_sparse_tensor *a_next)¶: Left-orthonormalize a local MPS site tensor by QR decomposition, and update tensor at next site.

void mps_local_orthonormalize_rq(struct block_sparse_tensor *a, struct block_sparse_tensor *a_prev)¶: Right-orthonormalize a local MPS site tensor by RQ decomposition, and update tensor at previous site.

double mps_orthonormalize_qr(struct mps *mps, const enum mps_orthonormalization_mode mode)¶

Left- or right-orthonormalize the MPS using QR decompositions, and return the normalization factor.

Assuming that rightmost (dummy) virtual bond dimension is 1.

int mps_local_orthonormalize_left_svd(const double tol, const ct_long max_vdim, const bool renormalize, struct block_sparse_tensor *a, struct block_sparse_tensor *a_next, struct trunc_info *info)¶: Left-orthonormalize a local MPS site tensor by a SVD with truncation, and update tensor at next site.

int mps_local_orthonormalize_right_svd(const double tol, const ct_long max_vdim, const bool renormalize, struct block_sparse_tensor *a, struct block_sparse_tensor *a_prev, struct trunc_info *info)¶: Right-orthonormalize a local MPS site tensor by a SVD with truncation, and update tensor at previous site.

int mps_compress(const double tol, const ct_long max_vdim, const enum mps_orthonormalization_mode mode, struct mps *mps, double *norm, double *trunc_scale, struct trunc_info *info)¶

Compress and orthonormalize an MPS by site-local SVDs and singular value truncations.

Returns original norm and scaling factor due to compression.

int mps_compress_rescale(const double tol, const ct_long max_vdim, const enum mps_orthonormalization_mode mode, struct mps *mps, double *trunc_scale, struct trunc_info *info)¶

Compress an MPS and rescale it by its original norm.

The rescaling is applied to the first tensor for right orthonormalization and to the last tensor for left orthonormalization.

int mps_split_tensor_svd(const struct block_sparse_tensor *a, const ct_long d[2], const qnumber *new_qsite[2], const double tol, const ct_long max_vdim, const bool renormalize, const enum singular_value_distr svd_distr, struct block_sparse_tensor *a0, struct block_sparse_tensor *a1, struct trunc_info *info)¶: Split a MPS tensor with dimension D0 x d0*d1 x D2 into two MPS tensors with dimensions D0 x d0 x D1 and D1 x d1 x D2, respectively, using SVD.

void mps_merge_tensor_pair(const struct block_sparse_tensor *a0, const struct block_sparse_tensor *a1, struct block_sparse_tensor *a)¶: Merge two neighboring MPS tensors.

void mps_to_statevector(const struct mps *mps, struct block_sparse_tensor *vec)¶: Merge all tensors of a MPS to obtain the vector representation on the full Hilbert space. The (dummy) virtual bonds are retained in the output tensor.

int save_mps(const char *filename, const struct mps *mps)¶

Save an MPS in an HDF5 file.

Note

Uses an HDF5 compound type for single and double complex numbers.

Returns:: 0 on success, a negative integer otherwise

int load_mps(const char *filename, struct mps *mps)¶

Load an MPS from an HDF5 file.

Note

Uses an HDF5 compound type for single and double complex numbers.

Returns:: 0 on success, a negative integer otherwise

struct mps¶

#include <mps.h>

Matrix product state (MPS) data structure.

Public Members

struct block_sparse_tensor *a¶: tensors associated with sites, with dimensions \(D_i \times d \times D_{i+1}\); array of length ‘nsites’

qnumber *qsite¶: physical quantum numbers at each site

ct_long d¶: local physical dimension of each site

int nsites¶: number of sites

SU(2) symmetric matrix product state (MPS) data structure.

Functions

void allocate_empty_su2_mps(const int nsites, struct su2_mps *mps)¶: Allocate an “empty” SU(2) symmetric matrix product state, without the actual tensors.

void allocate_su2_mps(const enum numeric_type dtype, const int nsites, const struct su2_irreducible_list *site_irreps, const ct_long *site_dim_degen, const struct su2_irreducible_list *bond_irreps, const ct_long **bond_dim_degen, struct su2_mps *mps)¶: Allocate memory for an SU(2) symmetric matrix product state.

void delete_su2_mps(struct su2_mps *mps)¶: Delete an SU(2) symmetric matrix product state (free memory).

void construct_random_su2_mps(const enum numeric_type dtype, const int nsites, const struct su2_irreducible_list *site_irreps, const ct_long *site_dim_degen, const qnumber irrep_sector, const qnumber max_bond_irrep, const ct_long max_bond_dim_degen, struct rng_state *rng_state, struct su2_mps *mps)¶: Construct an SU(2) matrix product state with random normal tensor entries.

bool su2_mps_is_consistent(const struct su2_mps *mps)¶: Internal consistency check of the SU(2) MPS data structure.

void su2_mps_contract_tensor_pair(const struct su2_tensor *a0, const struct su2_tensor *a1, struct su2_tensor *a)¶: Contract two neighboring SU(2) MPS tensors along the virtual bond (without merging the physical axes).

void su2_mps_merge_tensor_pair(const struct su2_tensor *a0, const struct su2_tensor *a1, struct su2_tensor *a)¶: Merge two neighboring SU(2) MPS tensors.

void su2_mps_to_statevector(const struct su2_mps *mps, struct su2_tensor *vec)¶: Contract all tensors of an SU(2) MPS to obtain the vector representation on the full Hilbert space. All physical axes and the (dummy) virtual bonds are retained in the output tensor.

struct su2_mps¶

#include <su2_mps.h>

SU(2) symmetric matrix product state (MPS) data structure.

Public Members

struct su2_tensor *a¶: tensors associated with sites, with axis ordering “left virtual, physical, right virtual”, and a fusion-splitting tree with a single node; array of length ‘nsites’

int nsites¶: number of sites

Tree tensor network states (TTNS)¶

Tree tensor network state (TTNS) data structure.

Enums

enum ttns_tensor_axis_type¶

TTNS tensor axis type.

Values:

enumerator TTNS_TENSOR_AXIS_PHYSICAL¶: physical axis

enumerator TTNS_TENSOR_AXIS_VIRTUAL¶: virtual bond axis

enumerator TTNS_TENSOR_AXIS_AUXILIARY¶: auxiliary (dummy) axis, for reaching non-zero quantum number sectors

Functions

void allocate_ttns(const enum numeric_type dtype, const int nsites_physical, const struct abstract_graph *topology, const ct_long *d, const qnumber **qsite, const qnumber qnum_sector, const ct_long *dim_bonds, const qnumber **qbonds, struct ttns *ttns)¶: Allocate memory for a tree tensor network state. ‘dim_bonds’ and ‘qbonds’ are indexed by site index tuples (i, j) with i < j.

void delete_ttns(struct ttns *ttns)¶: Delete a tree tensor network state (free memory).

void copy_ttns(const struct ttns *src, struct ttns *dst)¶: Copy a tree tensor network state and its block sparse tensors.

void construct_random_ttns(const enum numeric_type dtype, const int nsites_physical, const struct abstract_graph *topology, const ct_long *d, const qnumber **qsite, const qnumber qnum_sector, const ct_long max_vdim, struct rng_state *rng_state, struct ttns *ttns)¶: Construct a tree tensor network state with random normal tensor entries, given a maximum virtual bond dimension.

bool ttns_is_consistent(const struct ttns *ttns)¶: Internal consistency check of the TTNS data structure.

ct_long ttns_local_dimension(const struct ttns *ttns, const int i_site)¶: Get the local physical dimension at ‘i_site’.

ct_long ttns_maximum_bond_dimension(const struct ttns *ttns)¶: Get the maximum virtual bond dimension of the TTNS.

int ttns_tensor_bond_axis_index(const struct abstract_graph *topology, const int i_site, const int i_neigh)¶: Get the tensor axis index of the virtual bond at site ‘i_site’ to neighbor ‘i_neigh’.

static inline qnumber ttns_quantum_number_sector(const struct ttns *ttns)¶: Quantum number sector of a TTNS.

void ttns_vdot(const struct ttns *chi, const struct ttns *psi, void *ret)¶: Compute the dot (scalar) product <chi | psi> of two TTNS, complex conjugating chi.

void local_ttns_inner_product(const struct block_sparse_tensor *chi, const struct block_sparse_tensor *psi, const struct abstract_graph *topology, const int i_site, const int i_parent, struct block_sparse_tensor *inner_bonds)¶: Compute the local inner product <chi | psi> at ‘i_site’ given the averages of the connected child nodes. The virtual bonds towards the parent node (if any) remain open. The output is stored in inner_bonds[i_site].

double ttns_norm(const struct ttns *psi)¶

Compute the Euclidean norm of the TTNS.

Result is returned as double also for single-precision tensor entries.

void ttns_tensor_get_axis_desc(const struct abstract_graph *topology, const int i_site, struct ttns_tensor_axis_desc *desc)¶: Fill the axis descriptions of a TTNS tensor; ‘desc’ must point to an array of the same length as the degree of the tensor at ‘i_site’.

double ttns_orthonormalize_qr(const int i_root, struct ttns *ttns)¶: Orthonormalize the TTNS in-place using QR decompositions, and return the normalization factor.

int ttns_compress(const int i_root, const double tol, const bool relative_thresh, const ct_long max_vdim, struct ttns *ttns)¶

Recursively compress the tree from the specified root node to the leaves.

Returns:: 0 on success, a negative integer otherwise

void ttns_to_statevector(const struct ttns *ttns, struct block_sparse_tensor *vec)¶

Merge all tensors of a TTNS to obtain the vector representation on the full Hilbert space.

The output has a physical and (dummy) auxiliary axis of dimension 1 describing the quantum number sector.

struct ttns¶

#include <ttns.h>

Tree tensor network state (TTNS) data structure.

Sites are enumerated as physical sites first, then branching sites. The tensor at the last site contains an additional (dummy) auxiliary axis for reaching non-zero quantum number sectors. The TTNS supports non-uniform local physical dimensions. The branching sites have a (dummy) physical axis of dimension 1 and quantum number 0.

Public Members

struct block_sparse_tensor *a¶: tensors associated with sites, with interleaved physical and virtual bond dimensions (ordered by site indices)

struct abstract_graph topology¶: logical tree topology; nodes correspond to physical and branching sites

int nsites_physical¶: number of physical sites

int nsites_branching¶: number of branching sites

struct ttns_tensor_axis_desc¶

#include <ttns.h>

TTNS tensor axis description.

Public Members

enum ttns_tensor_axis_type type¶: tensor axis type

int index¶: local site index (for a physical axis), or neighbor site index (for a virtual bond)