pyblock3.algebra

pyblock3.algebra.core

Basic definitions for block-sparse tensors and block-sparse tensors with fermion factors.

class pyblock3.algebra.core.FermionTensor(*args: Any, **kwargs: Any)

Bases: NDArrayOperatorsMixin

block-sparse tensor with fermion factors.

Attributes:
oddSparseTensor

Including blocks with odd fermion parity.

evenSparseTensor

Including blocks with even fermion parity.

conj()

Complex conjugate. Note that np.conj() is a ufunc (no need to be defined). But np.real and np.imag are array_functions

copy()
deflate(cutoff=0)
diag()
property dtype

Element datatype.

fuse(*idxs, info=None, pattern=None)

Fuse several legs to one leg.

Args:
idxstuple(int)

Leg indices to be fused. The new fused index will be idxs[0].

infoBondFusingInfo (optional)

Indicating how quantum numbers are collected. If not specified, the direct sum of quantum numbers will be used. This will generate minimal and (often) incomplete fused shape.

patternstr (optional)

A str of ‘+’/’-’. Only required when info is not specified. Indicating how quantum numbers are linearly combined.

hdot(b, out=None)

Horizontally contract operator tensors (contracting connected virtual dimensions).

property imag
property infos

Return the quantum number layout of the FermionTensor, similar to numpy.ndarray.shape.

item()

Return scalar element.

kron_add(b, infos=None)

Direct sum of first and last legs. Middle legs are summed.

kron_product_info(*idxs, pattern=None)
kron_sum_info(*idxs, pattern=None)
left_canonicalize(mode='reduced')

Left canonicalization (using QR factorization). Left canonicalization needs to collect all left indices for each specific right index. So that we will only have one R, but left dim of q is unchanged.

Returns:

q, r : (FermionTensor, SparseTensor (gauge))

left_svd(full_matrices=True)

Left svd needs to collect all left indices for each specific right index.

Returns:

l, s, r : (FermionTensor, SparseTensor (vector), SparseTensor (gauge))

lq(mode='reduced')
property n_blocks

Number of (non-zero) blocks.

property nbytes

Number bytes in memory.

property ndim

Number of dimensions.

static ones(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create operator tensor with ones.

pdot(b, out=None)
qr(mode='reduced')
static random(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create operator tensor with random elements.

property real
right_canonicalize(mode='reduced')

Right canonicalization (using QR factorization).

Returns:

l, q : (SparseTensor (gauge), FermionTensor)

right_svd(full_matrices=True)

Right svd needs to collect all right indices for each specific left index.

Returns:

l, s, r : (SparseTensor (gauge), SparseTensor (vector), FermionTensor)

shdot(b, out=None)

Horizontally contract operator tensors (matrices) in symbolic matrix.

symmetry_fuse(finfos, symm_map)
tensordot(b, axes=2)
to_dense(infos=None)
to_sliceable(infos=None)
to_sparse()
transpose(axes=None)
static truncate_svd(l, s, r, max_bond_dim=-1, cutoff=0.0, max_dw=0.0, norm_cutoff=0.0)

Truncate tensors obtained from SVD.

Args:
l, s, rtuple(SparseTensor/FermionTensor)

SVD tensors.

max_bond_dimint

Maximal total bond dimension. If k == -1, no restriction in total bond dimension.

cutoffdouble

Minimal kept singular value.

max_dwdouble

Maximal sum of square of discarded singular values.

norm_cutoffdouble

Blocks with norm smaller than norm_cutoff will be deleted.

Returns:
l, s, rtuple(SparseTensor/FermionTensor)

SVD decomposition.

errorfloat

Truncation error (same unit as singular value squared).

unfuse(i, info)

Unfuse one leg to several legs. May introduce some additional zero blocks.

Args:
iint

index of the leg to be unfused. The new unfused indices will be i, i + 1, …

infoBondFusingInfo

Indicating how quantum numbers are collected.

static zeros(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create operator tensor with zero elements.

class pyblock3.algebra.core.SliceableTensor(reduced, infos=None)

Bases: ndarray

Dense tensor of zero and non-zero blocks. For zero blocks, the elemenet is zero.

copy()
property density

Ratio of number of non-zero elements to total number of elements.

dot(b, out=None)
property dtype
tensordot(b, axes=2)
to_dense()

Convert to dense numpy.ndarray.

to_sparse()
class pyblock3.algebra.core.SparseTensor(*args: Any, **kwargs: Any)

Bases: NDArrayOperatorsMixin

block-sparse tensor. Represented as a list of SubTensor.

property T

Transpose.

add(b)
conj()

Complex conjugate. Note that np.conj() is a ufunc (no need to be defined). But np.real and np.imag are array_functions

copy()
deflate(cutoff=0)

Remove zero blocks.

diag()
property dtype

Element datatype.

fuse(*idxs, info=None, pattern=None)

Fuse several legs to one leg.

Args:
idxstuple(int)

Leg indices to be fused. The new fused index will be min(idxs).

infoBondFusingInfo (optional)

Indicating how quantum numbers are collected. If not specified, the direct sum of quantum numbers will be used. This will generate minimal and (often) incomplete fused shape.

patternstr (optional)

A str of ‘+’/’-’. Only required when info is not specified. Indicating how quantum numbers are linearly combined. len(pattern) == len(idxs)

hdot(b, out=None)

Horizontal contraction (contracting connected virtual dimensions).

property imag
property infos

Return the quantum number layout of the SparseTensor, similar to numpy.ndarray.shape.

item()

Return scalar element.

kron_add(b, infos=None)

Direct sum of first and last legs. Middle legs are summed.

kron_product_info(*idxs, pattern=None)

Kron product of quantum numbers along selected indices, for fusing purpose.

kron_sum_info(*idxs, pattern=None)

Kron sum of quantum numbers along selected indices, for fusing purpose.

left_canonicalize(mode='reduced')

Left canonicalization (using QR factorization). Left canonicalization needs to collect all left indices for each specific right index. So that we will only have one R, but left dim of q is unchanged.

Returns:

q, r : tuple(SparseTensor)

left_svd(full_matrices=False)

Left svd needs to collect all left indices for each specific right index.

Returns:

l, s, r : tuple(SparseTensor)

lq(mode='reduced')
property n_blocks

Number of blocks.

property nbytes

Number bytes in memory.

property ndim

Number of dimensions.

norm()
normalize_along_axis(axis)
static ones(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create tensor from tuple of BondInfo with ones.

pdot(b, out=None)

Vertical contraction (all middle dims).

qr(mode='reduced')
quick_deflate()
static random(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create tensor from tuple of BondInfo with random elements.

property real
right_canonicalize(mode='reduced')

Right canonicalization (using QR factorization).

Returns:

l, q : tuple(SparseTensor)

right_svd(full_matrices=False)

Right svd needs to collect all right indices for each specific left index.

Returns:

l, s, r : tuple(SparseTensor)

subtract(b)
symmetry_fuse(finfos, symm_map)

Change from higher symmetry to lower symmetry.

Args:
finfoslist(BondFusingInfo)

generated using BondFusingInfo.get_symmetry_fusing_info

symm_maplambda h: l

Map from higher symemtry irrep to lower symmetry irrep

tensor_svd(idx=2, linfo=None, rinfo=None, pattern=None, full_matrices=False)

Separate tensor in the middle, collecting legs as [0, idx) and [idx, ndim), then perform SVD.

Returns:

l, s, r : tuple(SparseTensor)

tensordot(b, axes=2)
to_dense(infos=None)
to_sliceable(infos=None)
to_sparse()
transpose(axes=None)
static truncate_svd(l, s, r, max_bond_dim=-1, cutoff=0.0, max_dw=0.0, norm_cutoff=0.0, eigen_values=False)

Truncate tensors obtained from SVD.

Args:
l, s, rtuple(SparseTensor)

SVD tensors.

max_bond_dimint

Maximal total bond dimension. If k == -1, no restriction in total bond dimension.

cutoffdouble

Minimal kept singular value.

max_dwdouble

Maximal sum of square of discarded singular values.

norm_cutoffdouble

Blocks with norm smaller than norm_cutoff will be deleted.

eigen_valuesbool

If True, treat s as eigenvalues.

Returns:
l, s, rtuple(SparseTensor)

SVD decomposition.

errorfloat

Truncation error (same unit as singular value squared).

unfuse(i, info)

Unfuse one leg to several legs.

Args:
iint

index of the leg to be unfused. The new unfused indices will be i, i + 1, …

infoBondFusingInfo

Indicating how quantum numbers are collected.

static zeros(bond_infos, pattern=None, dq=None, dtype=<class 'float'>)

Create tensor from tuple of BondInfo with zero elements.

class pyblock3.algebra.core.SubTensor(reduced, q_labels=None)

Bases: ndarray

A block in block-sparse tensor.

Attributes:
q_labelstuple(SZ..)

Quantum labels for this sub-tensor block. Each element in the tuple corresponds one leg of the tensor.

conj()
copy()
diag()
property imag
norm()
classmethod ones(shape, q_labels=None, dtype=<class 'float'>)
classmethod random(shape, q_labels=None, dtype=<class 'float'>)
property real
tensordot(b, axes=2)
transpose(axes=None)
classmethod zeros(shape, q_labels=None, dtype=<class 'float'>)
pyblock3.algebra.core.implements(np_func)

Wrapper for overwritting numpy methods.

pyblock3.algebra.core.method_alias(name)

Make method callable from algebra.funcs.

pyblock3.algebra.flat

pyblock3.algebra.mpe

Partially contracted tensor network (MPE) with methods for DMRG-like sweep algorithm.

CachedMPE enables swapping with disk storage to reduce memory requirement.

class pyblock3.algebra.mpe.CachedMPE(bra, mpo, ket, opts=None, do_canon=True, idents=None, tag='MPE', scratch=None, maxsize=3, mpi=False)

Bases: MPE

MPE for large system. Using disk storage to reduce memory usage.

copy()
property nbytes
class pyblock3.algebra.mpe.MPE(bra, mpo, ket, opts=None, do_canon=True, idents=None, mpi=False)

Bases: object

Matrix Product Expectation (MPE). Original and partially contracted tensor network <bra|mpo|ket>.

build_envs(l=0, r=2)

Canonicalize bra and ket around sites [l, r). Contract mpo around sites [l, r).

build_envs_no_contract(l=0, r=2)

Canonicalize bra and ket around sites [l, r).

copy()
copy_shell(bra, mpo, ket)
dmrg(bdims, noises=None, dav_thrds=None, n_sweeps=10, tol=1e-06, max_iter=500, dot=2, iprint=2, forward=True, **kwargs)
eigs(iprint=False, fast=False, conv_thrd=1e-07, max_iter=500, extra_mpes=None)

Return ground-state energy and ground-state effective MPE.

property expectation

<bra|mpo|ket> for the whole system.

greens_function(mpo, omega, eta, bdims, noises=None, cg_thrds=None, n_sweeps=10, tol=1e-06, dot=2, iprint=2)
linear(bdims, noises=None, cg_thrds=None, n_sweeps=10, tol=1e-06, dot=2, iprint=2)
multiply(fast=False)
property n_sites
property nbytes
rk4(dt, fast=False, eval_ener=True)
solve_gf(ket, omega, eta, iprint=False, fast=False, conv_thrd=1e-07)
tddmrg(bdims, dt, n_sweeps=10, n_sub_sweeps=2, dot=2, iprint=2, forward=True, normalize=True, **kwargs)
pyblock3.algebra.mpe.implements(np_func)

pyblock3.algebra.mps

1D tensor network for MPS/MPO.

class pyblock3.algebra.mps.MPS(*args: Any, **kwargs: Any)

Bases: NDArrayOperatorsMixin

Matrix Product State / Matrix Product Operator.

Attributes:
tensorslist(SparseTensor/FermionTensor)

A list of block-sparse tensors.

n_sitesint

Number of sites.

constfloat

Constant term.

optsdict or None

Options indicating how bond dimension truncation should be done after MPO @ MPS, etc. Possible options are: max_bond_dim, cutoff, max_dw, norm_cutoff

dqSZ

Delta quantum of MPO operator

property T
amplitude(det)

Return overlap <MPS|det>. MPS tensors must be sliceable.

property bond_dim
canonicalize(center)

MPS canonicalization.

Args:
centerint

Site index of canonicalization center.

compress(**opts)

MPS bond dimension compression.

Args:
max_bond_dimint

Maximal total bond dimension. If k == -1, no restriction in total bond dimension.

cutoffdouble

Minimal kept singluar value.

max_dwdouble

Maximal sum of square of discarded singluar values.

conj()
copy()
dot(b, out=None)
property dtype
fix_pattern(pattern=None)
get_bipartite_entanglement()
matmul(b, out=None)
property n_sites

Number of sites

norm()
classmethod ones(info, dtype=<class 'float'>, opts=None)

Construct unfused MPS from MPSInfo, with identity matrix elements.

classmethod random(info, low=0, high=1, dtype=<class 'float'>, opts=None)

Construct unfused MPS from MPSInfo, with random matrix elements.

show_bond_dims()
simplify()

Reduce virtual bond dimensions for symbolic sparse tensors. Only works when tensor is SparseSymbolicTensor.

symmetry_fuse(symm_map, info=None)
to_ad_sparse()
to_flat()
to_non_flat()
to_sliceable(info=None)

Get a shallow copy of MPS with SliceableTensor.

Args:
infoMPSInfo, optional

MPSInfo containing the complete basis BondInfo. If not specified, the BondInfo will be generated from the MPS, which may be incomplete.

to_sparse()
to_symbolic()
classmethod zeros(info, dtype=<class 'float'>, opts=None)

Construct unfused MPS from MPSInfo, with zero matrix elements.

class pyblock3.algebra.mps.MPSInfo(n_sites, vacuum, target, basis)

Bases: object

BondInfo in every site in MPS (a) For constrution of initial MPS. (b) For tracking basis info in construction of SliceableTensor.

Attributes:
n_sitesint

Number of sites

vacuumSZ

vacuum state

targetSZ

target state

basislist(BondInfo)

BondInfo in each site

left_dimslist(BondInfo)

Truncated states for left block

right_dimslist(BondInfo)

Truncated states for right block

set_bond_dimension(bond_dim, call_back=None)

Truncated bond dimension based on FCI quantum numbers each FCI quantum number has at least one state kept

set_bond_dimension_fci(call_back=None)

FCI bond dimensions

set_bond_dimension_occ(bond_dim, occ, bias=1)

bond dimensions from occupation numbers

set_bond_dimension_thermal_limit()

Set bond dimension for MPS at thermal-limit state in ancilla approach.

pyblock3.algebra.mps.implements(np_func)

pyblock3.algebra.symmetry

Definition of quantum numbers.

class pyblock3.algebra.symmetry.BondFusingInfo(*args, **kwargs)

Bases: BondInfo

collection of quantum labels with quantum label information for fusing/unfusing

Attributes:
selfCounter

dict of quantum label and number of states

finfodict(SZ -> dict(tuple(SZ) -> (int, tuple(int))))

For each fused q and unfused q, the starting index in fused dim and the shape of unfused block

patternstr

a str of ‘+’/’-’ indicating how quantum numbers are combined

static get_symmetry_fusing_info(info, symm_map)

Fusing info for tranfrom to lower symmetry.

Args:
infoBondInfo

BondInfo at higher symmetry

symm_maplambda h: l

Map from higher symemtry irrep to lower symmetry irrep

static kron_sum(items, ref=None, pattern=None)

Direct sum of combination of quantum numbers.

Args:
itemslist((tuple(SZ), tuple(int)))

The items to be summed. For every item, the q_labels and matrix shape are given. Repeated items are okay (will not be considered).

refBondInfo (optional)

Reference fused BondInfo.

static tensor_product(*infos, ref=None, pattern=None, trans=None)

Direct product of a collection of BondInfo.

Args:
infostuple(BondInfo)

BondInfo for each unfused leg.

refBondInfo (optional)

Reference fused BondInfo.

class pyblock3.algebra.symmetry.BondInfo(*args, **kwargs)

Bases: Counter

collection of quantum labels

Attributes:
selfCounter

dict of quantum label and number of bonds

filter(other)
item()
keep_maximal()
property n_bonds

Total number of bonds.

property symm_class
static tensor_product(a, b, ref=None)
truncate(bond_dim, ref=None)
truncate_no_keep(bond_dim, ref=None)
class pyblock3.algebra.symmetry.SZ(n=0, twos=0, pg=0)

Bases: object

non-spin-adapted spin label

static from_flat(x)
property is_fermion
static is_flat_fermion(x)
to_flat()