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 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 long d, const qnumber *qsite, const 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 move_mps_data(struct mps *src, struct mps *dst)¶: Move MPS data (without allocating new memory).

void construct_random_mps(const enum numeric_type dtype, const int nsites, const long d, const qnumber *qsite, const qnumber qnum_sector, const 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 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 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 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 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 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 long d[2], const qnumber *new_qsite[2], const double tol, const 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

long d¶: local physical dimension of each site

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_AUXILIARY¶: auxiliary (dummy) axis, for reaching non-zero quantum number sectors

enumerator TTNS_TENSOR_AXIS_VIRTUAL¶: virtual bond axis

Functions

void allocate_ttns(const enum numeric_type dtype, const int nsites_physical, const struct abstract_graph *topology, const long *d, const qnumber **qsite, const qnumber qnum_sector, const 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 construct_random_ttns(const enum numeric_type dtype, const int nsites_physical, const struct abstract_graph *topology, const long *d, const qnumber **qsite, const qnumber qnum_sector, const 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.

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

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.

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 ttns *ttns, 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’.

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 site 0 contains an additional (dummy) auxiliary second 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)