Python Interface API

Python interface of block2.

class pyblock2.driver.core.SymmetryTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Enumeration of symmetry modes (symmetry groups, complex/real types, and floating-point precision).

CPX, SP, SAny can be combined with some other types using operator |. For example, SymmetryTypes.CPX | SymmetryTypes.SU2 is the SU(2) mode with the complex number.

Nothing = 0

Real number and double precision.

SU2 = 1

Spin-adapted Fermion mode, U(1) x SU(2) x AbelianPG.

SZ = 2

Non-spin-adapted Fermion mode, U(1) x U(1)[Sz] x AbelianPG.

SGF = 4

General spin Fermion mode. U(1)[Fermion number] x AbelianPG.

SGB = 8

General spin Boson mode. U(1)[Boson number] x AbelianPG.

CPX = 16

Complex number. Can be combined with Fermion/Boson symmetry types.

SP = 32

Single precision. Can be combined with Fermion/Boson symmetry types.

SGFCPX = 20

Complex number general spin Fermion mode, for relativistic DMRG.

SPCPX = 48

Single precision complex number.

SAny = 64

General symmetry type.

SAnySU2 = 65

Equivalent to ‘SU2’, implemented using general symmetry types.

SAnySZ = 66

Equivalent to ‘SZ’, implemented using general symmetry types.

SAnySGF = 68

Equivalent to ‘SGF’, implemented using general symmetry types.

SAnySGFCPX = 84

Equivalent to ‘SGFCPX’, implemented using general symmetry types.

SO4 = 128

PHSU2 = 256

SO3 = 512

LZ = 1024

SAnySO4 = 192

SO(4) symmetry for 2-D Hubbard model with NN interactions.

SAnyPHSU2 = 320

Particle-hole symmetry for 2-D Hubbard model with NN interactions.

SAnySO3 = 576

SO(3) spatial symmetry for atoms.

SAnySU2LZ = 1089

Spin-adapted mode for diatomic molecules, U(1) x SU(2) x U(1)[Lz].

SAnySZLZ = 1090

Non-spin-adapted mode for diatomic molecules, U(1) x U(1)[Sz] x U(1)[Lz].

SAnySGFLZ = 1092

General spin mode for diatomic molecules, U(1) x U(1)[Lz].

class pyblock2.driver.core.ParallelTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Enumeration of strategies for distributing the quantum chemistry h1e and g2e integrals. See Eq. (2) in J. Chem. Phys. 154, 224116 (2021).

Nothing = 0

Serial computation.

I = 1

Distribute integrals over the first index.

J = 2

Distribute integrals over the second index.

SI = 3

Distribute integrals over the smallest index.

SJ = 4

Distribute integrals over the second smallest index.

SIJ = 5

Distribute integrals over the unordered tuple of the two smallest indices (IJ) of g2e. When J == K, distribute over J. Same as ‘SI’ for h1e. See Eq. (5) in J. Chem. Phys. 154, 224116 (2021).

SKL = 6

Distribute integrals over the unordered tuple of the two largest indices (KL) of g2e. When J == K, distribute over J. Same as ‘SJ’ for h1e. See Eq. (6) in J. Chem. Phys. 154, 224116 (2021).

UIJ = 7

Distribute integrals over the unordered tuple of the two smallest indices (IJ) of g2e. When J == K, distribute over IJ. Same as ‘SI’ for h1e.

UKL = 8

Distribute integrals over the unordered tuple of the two largest indices (KL) of g2e. When J == K, distribute over KL. Same as ‘SJ’ for h1e.

UIJM2 = 9

Similar to ‘UIJ’, but distribute over IJ / 2.

UKLM2 = 10

Similar to ‘UKL’, but distribute over KL / 2.

UIJM4 = 11

Similar to ‘UIJ’, but distribute over IJ / 4.

UKLM4 = 12

Similar to ‘UKL’, but distribute over KL / 4.

MixUIJUKL = 1000

Two-layer nested UIJ (outer) and UKL (inner). Not a good strategy.

MixUKLUIJ = 1001

Two-layer nested UKL (outer) and UIJ (inner). Not a good strategy.

MixUIJSI = 1002

Two-layer nested UIJ (outer) and SI (inner).

class pyblock2.driver.core.MPOAlgorithmTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Enumeration of strategies for building MPO from symbolic expression of second quantized operators. Algorithms (such as Bipartite) and modifiers (such as Fast) can be combined using operator |.

Nothing = 0

No algorithm specified (invalid).

Bipartite = 1

Bipartite algorithm. See J. Chem. Phys. 153, 084118 (2020).

SVD = 2

SVD algorithm. See J. Chem. Phys. 145, 014102 (2016).

Rescaled = 4

Use rescaled singular values for truncation. Optional for ‘SVD’, cannot be used alone.

Fast = 8

Fast implementation for dense integrals. Optional for ‘SVD’ and ‘Bipartite’, cannot be used alone.

Blocked = 16

Separate SVD for blocks. Optional for ‘SVD’ and ‘Bipartite’, cannot be used alone.

Sum = 32

Sum of MPO approach. See J. Chem. Phys. 145, 014102 (2016). Optional for ‘SVD’ and ‘Bipartite’, cannot be used alone.

Constrained = 64

SVD with constraints on sparsity. See PLoS ONE 14 e0211463 (2019). Optional for ‘SVD’, cannot be used alone.

Disjoint = 128

SVD with block-diagonal sparsity preserved. Optional for ‘SVD’, cannot be used alone.

Length = 8192

Separate SVD for different operator widths. Optional for ‘SVD’ and ‘Bipartite’, cannot be used alone.

DisjointSVD = 130

BlockedSumDisjointSVD = 178

FastBlockedSumDisjointSVD = 186

BlockedRescaledSumDisjointSVD = 182

FastBlockedRescaledSumDisjointSVD = 190

BlockedDisjointSVD = 146

FastBlockedDisjointSVD = 154

BlockedRescaledDisjointSVD = 150

FastBlockedRescaledDisjointSVD = 158

RescaledDisjointSVD = 134

FastDisjointSVD = 138

FastRescaledDisjointSVD = 142

ConstrainedSVD = 66

BlockedSumConstrainedSVD = 114

FastBlockedSumConstrainedSVD = 122

BlockedRescaledSumConstrainedSVD = 118

FastBlockedRescaledSumConstrainedSVD = 126

BlockedConstrainedSVD = 82

FastBlockedConstrainedSVD = 90

BlockedRescaledConstrainedSVD = 86

FastBlockedRescaledConstrainedSVD = 94

RescaledConstrainedSVD = 70

FastConstrainedSVD = 74

FastRescaledConstrainedSVD = 78

BlockedSumSVD = 50

FastBlockedSumSVD = 58

BlockedRescaledSumSVD = 54

FastBlockedRescaledSumSVD = 62

BlockedSumBipartite = 49

FastBlockedSumBipartite = 57

BlockedSVD = 18

FastBlockedSVD = 26

Fast algorithm for blocked SVD.

BlockedRescaledSVD = 22

FastBlockedRescaledSVD = 30

BlockedLengthSVD = 8210

FastBlockedLengthSVD = 8218

BlockedBipartite = 17

FastBlockedBipartite = 25

RescaledSVD = 6

FastSVD = 10

FastRescaledSVD = 14

FastBipartite = 9

Fast algorithm for bipartite (recommended).

NC = 256

Normal-Complementary (NC) partition in conventional quantum chemistry DMRG. Optional for ‘Conventional’, cannot be used alone.

CN = 512

Complementary-Normal (CN) partition in conventional quantum chemistry DMRG. Optional for ‘Conventional’, cannot be used alone.

Conventional = 1024

Mixed NC/CN partition in conventional quantum chemistry DMRG. See Sec. III.A in J. Chem. Phys. 154, 224116 (2021).

ConventionalNC = 1280

Normal-Complementary (NC) partition in conventional quantum chemistry DMRG. See Eq. (B5) in J. Chem. Phys. 154, 224116 (2021).

ConventionalCN = 1536

Complementary-Normal (CN) partition in conventional quantum chemistry DMRG. See Eq. (B6) in J. Chem. Phys. 154, 224116 (2021).

NoTranspose = 2048

Allow different bra and ket in conventional quantum chemistry MPO. Optional for ‘Conventional’, cannot be used alone.

NoRIntermed = 4096

Not use R complementary operator intermediates in conventional quantum chemistry MPO. Optional for ‘Conventional’, cannot be used alone.

NoTransConventional = 3072

NoTransConventionalNC = 3328

NoTransConventionalCN = 3584

NoRIntermedConventional = 5120

NoTransNoRIntermedConventional = 7168

class pyblock2.driver.core.NPDMAlgorithmTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Enumeration of strategies for computing N-particle density matrices (NPDM). See Sec. II.E.1 in J. Chem. Phys. 159, 234801 (2023). Items can be combined using operator |.

Nothing = 0

No algorithm specified (invalid).

SymbolFree = 1

Symbol-free NPDM algorithm.

Normal = 2

Normal algorithm with explicit symbols. Conflict with ‘SymbolFree’.

Fast = 4

Fast algorithm with explicit symbols. Conflict with ‘SymbolFree’.

Compressed = 8

Reduced disk storage. Optional for ‘SymbolFree’, cannot be used alone.

LowMem = 16

Reduced memory usage. Optional for ‘SymbolFree’, cannot be used alone.

Default = 9

Same as NPDMAlgorithmTypes.SymbolFree | NPDMAlgorithmTypes.Compressed (recommended).

Conventional = 32

Old manual implementation for 1pdm and 2pdm (less efficient).

class pyblock2.driver.core.STTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Enumeration of truncation of expression in DMRG for similarity-transformed Hamiltonians. See Sec. II.D.3.iii in J. Chem. Phys. 159, 234801 (2023).

H = 1

Terms in H.

HT = 2

Terms in [H, T].

HT2T2 = 4

Terms in 1/2 [[H, T2], T2].

HT1T2 = 8

Terms in 1/2 [[H, T1], T1] + [[H, T2], T1].

HT1T3 = 16

Terms in [[H, T3], T1].

HT2T3 = 32

Terms in [[H, T3], T2].

H_HT = 3

Sum of ‘H’ and ‘HT’.

H_HT_HT2T2 = 7

Sum of ‘H’, ‘HT’ and ‘HT2T2’.

H_HT_HTT = 15

Sum of ‘H’, ‘HT’, ‘HT2T2’, and ‘HT1T2’.

H_HT_HTT_HT1T3 = 31

Sum of ‘H_HT_HTT’, and ‘HT1T3’.

H_HT_HTT_HT2T3 = 47

Sum of ‘H_HT_HTT’, and ‘HT2T3’.

H_HT_HTT_HT3 = 63

Sum of ‘H_HT_HTT’, ‘HT1T3’, and ‘HT2T3’.

H_HT_HT2T2_HT1T3 = 23

Sum of ‘H_HT_HT2T2’, and ‘HT1T3’.

H_HT_HT2T2_HT2T3 = 39

Sum of ‘H_HT_HT2T2’, and ‘HT2T3’.

H_HT_HT2T2_HT3 = 55

Sum of ‘H_HT_HT2T2’, ‘HT1T3’, and ‘HT2T3’.

class pyblock2.driver.core.Block2Wrapper(symm_type=SymmetryTypes.SU2)

Bases: object

Wrapper for low-level block2 C++ type bindings for different symmetries.

Attributes:

symm_typeSymmetryTypes

The symmetry/floating point number mode.

bmodule

The block2 module.

bxmodule

Sub-module of block2 for the floating point number type.

bcmodule

Sub-module of block2 for the complex variant of the floating point number type. For example, for bx = block2 or block2.cpx, bc = block2.cpx.

bsmodule

Sub-module of block2 for the symmetry mode and floating point number types. For example, when symm_type = SymmetryTypes.SU2, bs = block2.su2.

brsmodule

Sub-module of block2 for the symmetry mode and the real variant of the floating point number types. For example, when symm_type = SymmetryTypes.SU2, brs = block2.su2.

bcsmodule

Sub-module of block2 for the symmetry mode and the complex variant of the floating point number types. For example, when symm_type = SymmetryTypes.SU2, brs = block2.cpx.su2.

SXtype

The quantum number type. For example, when symm_type = SymmetryTypes.SU2, SX = block2.SU2.

VectorFLtype

Vector of the floating point number type.

VectorFPtype

Vector of the real variant of the floating point number type. For example, for FL = complex<double>/double, FP = double.

VectorPGtype

Vector of the point group irrep integer type.

VectorSXtype

Vector of the quantum number type. For example, when symm_type = SymmetryTypes.SU2, VectorSX = block2.VectorSU2.

VectorVectorSXtype

Vector of Vector of the quantum number type. For example, when symm_type = SymmetryTypes.SU2, VectorSX = block2.VectorVectorSU2.

__init__(symm_type=SymmetryTypes.SU2)

set_symmetry_groups(*args)

Set the combination of symmetry sub-groups for symm_type = SAny.

Args:

argslist[str]

List of names of (Abelian) symmetry groups. 0 <= len(args) <= 6 is required. Possible sub-group names are “U1”, “Z1”, “Z2”, “Z3”, …, “Z2055”, “U1Fermi”, “Z1Fermi”, “Z2Fermi”, “Z3Fermi”, …, “Z2055Fermi”, “LZ”, and “AbelianPG”.

class pyblock2.driver.core.DMRGDriver(stack_mem=1073741824, scratch='./nodex', clean_scratch=True, restart_dir=None, n_threads=None, n_mkl_threads=1, symm_type=SymmetryTypes.SU2, mpi=None, stack_mem_ratio=0.4, fp_codec_cutoff=1e-16)

Bases: object

Simple Python interface for DMRG calculations.

Attributes:

symm_typeSymmetryTypes

The symmetry/floating point number mode.

bwBlock2Wrapper

Wrapper for low-level type bindings.

mpiMPICommunicator or None

MPI Communicator.

__init__(stack_mem=1073741824, scratch='./nodex', clean_scratch=True, restart_dir=None, n_threads=None, n_mkl_threads=1, symm_type=SymmetryTypes.SU2, mpi=None, stack_mem_ratio=0.4, fp_codec_cutoff=1e-16)

Initialize DMRGDriver.

Args:

symm_typeSymmetryTypes

The symmetry/floating point number mode. Default: SymmetryTypes.SU2.

scratchstr

The working directory (scratch space). Default is “./nodex”.

clean_scratchbool

If True, large temporary files in the scratch space will be removed once the DMRG finishes successfully. MPS files will not be removed. Default is True.

restart_dirNone or str

If not None, MPS will be copied to the given directory after each DMRG sweep. Default is None (MPS will not be copied).

n_threadsNone or int

Number of threads. When MPI is used, this is the number of threads for each MPI processor. Default is None, and the max number of threads available on this node will be used.

n_mkl_threadsint

Number of threads for parallelization inside MKL (for dense matrix multiplication). n_mkl_threads should be a factor of n_threads. When n_mkl_threads is not 1, nested threading will be used. Default is 1.

mpiNone or bool

If True, MPI parallelization is used. If False or None, serial implementation is used. Default is None.

stack_memint

The memory used for storing renormalized operators (in bytes). Default is 1 GB. When MPI is used, this is the number per MPI processor. Note that this argument is only responsible for part of the memory consumption in block2. The other part will be dynamically determined.

stack_mem_ratiofloat

The fraction of stack space occupied by the main stacks. Default is 0.4.

fp_codec_cutofffloat

Floating-point number (absolute) precision for compressed storage of renormalized operators. Default is 1E-16.

property symm_type

The symmetry/floating point number mode.

property scratch

The working directory (scratch space).

property restart_dir

If not None, MPS will be copied to the given directory after each DMRG sweep.

set_symm_type(symm_type, reset_frame=True)

Change the symmetry type of this DMRGDriver.

Args:

symm_typeSymmetryTypes

The symmetry/floating point number mode. Default: SymmetryTypes.SU2.

reset_framebool

Whether the data frame should be reset. This is required to be True after switching between single precision and double precision. Default is True.

set_symmetry_groups(*args)

Set the combination of symmetry sub-groups for symm_type = SAny.

Args:

argslist[str]

List of names of (Abelian) symmetry groups. 0 <= len(args) <= 6 is required. Possible sub-group names are “U1”, “Z1”, “Z2”, “Z3”, …, “Z2055”, “U1Fermi”, “Z1Fermi”, “Z2Fermi”, “Z3Fermi”, …, “Z2055Fermi”, “LZ”, and “AbelianPG”.

initialize_system(n_sites, n_elec=0, spin=0, pg_irrep=None, orb_sym=None, heis_twos=-1, heis_twosz=0, singlet_embedding=True, pauli_mode=False, vacuum=None, left_vacuum=None, target=None, hamil_init=True)

Set the basic information of the system. Required before invoking self.get_mpo, self.get_random_mps, etc. Note that one can directly set the target and vacuum, so that n_elec, spin, pg_irrep, heis_twos, and heis_twosz are not required.

Args:

n_sitesint

Number of sites (orbitals).

n_elecint

Number of electrons int the target state.

spinint

Two times total spin (in SU2 mode) or two times projected spin (in SZ mode) int the target state.

pg_irrepNone or int

Point group irreducible representation in the target state. 0 is the trivial point group irrep.

orb_symNone or list[int]

The point group irreducible representation of each site (orbital). If None, this is [0] * n_sites.

heis_twosint

For non-Heisenberg model, this should be -1 (default). For Heisenberg model, this is two times the total spin of each site. For example, heis_twos = 1 for the most common spin-1/2 Heisenberg model.

heis_twoszint

For Heisenberg model in SGB mode, spin is not used and heis_twosz is used to specify two times the projected spin of the target state. Default is zero. Not used for non-Heisenberg model.

singlet_embeddingbool

Whether singlet embedding is used for non-singlet target state in SU2 mode. Default is True. Note that when this is True, DMRGDriver.target will always be the singlet even if the actual target state is not singlet.

pauli_modebool

Whether Pauli mode should be activated. Default is False. When Pauli mode is activated, quantum numbers are not used. Only n_sites is required in initialize_system. The SGB or SGB|CPX symmetry types are required for this case. In Pauli mode one can use DMRGDriver.get_mpo_any_pauli to construct MPO from XYZ Pauli operators.

vacuumSX or None

The quantum number of the reference vacuum state. If None, will be set according to other parameters. Default is None.

targetSX or None

The quantum number of the target state. If None, will be set according to other parameters. Default is None.

left_vacuumSX or None

For non-singlet states in non-Abelian symmetry modes (such as SU2), and when singlet_embedding = True, left_vacuum is an adjusted vacuum to represent the non-singlet fictitious non-singlet spin. For most cases, this can be automatically determined and stored as DMRGDriver.left_vacuum. For Abelian symmetry mode or singlet states in non-Abelian symmetry modes, this should be equal to vacuum.

hamil_initbool

Whether the Hamiltonian object DMRGDriver.ghamil should be initialized. Default is True. When a custom symmetry type is used and symm_type = SymmetryTypes.SAny, one can set this to False and manually initialize DMRGDriver.ghamil later using the return value of DMRGDriver.get_custom_hamiltonian.

divide_nprocs(n)

Helper method for two-level MPI parallelization. This purpose of this method is to almost evenly divide n procs to two levels. Faster than a pure sqrt method when n >= 20000000.

Args:

nint

Number of MPI processors.

Returns:

(a, b)tuple[int, int]

Number of MPI processors at two levels such that a * b == n and abs(a - b) is minimized.

parallelize_integrals(para_type, h1e, g2e, const, msize=None, mrank=None)

Prepare integrals for parallel quantum chemistry DMRG.

Args:

para_typeParallelTypes

The strategy for distributing the integrals (when self.mpi is not None).

h1enp.ndarray[float|complex]

ndim = 2 one-electron integral (serial/complete version).

g2enp.ndarray[float|complex]

ndim = 4 unpacked two-electron integral (serial/complete version).

constfloat|complex

Constant term.

msizeNone or int

Total number of MPI processors. If None, will be determined from self.mpi.size. Default is None.

mrankNone or int

The rank of current MPI processor. If None, will be determined from self.mpi.rank. Default is None.

Returns:

h1enp.ndarray[float|complex]

One-electron integral with elements belonging to other processors set to zero.

g2enp.ndarray[float|complex]

Two-electron integral with elements belonging to other processors set to zero.

constfloat or complex

Constant energy (non-zero only at the root processor).

get_pauli_hamiltonian()

Internal method for setting Hamiltonian in the Pauli/SGB mode.

get_so4_hamiltonian()

Internal method for setting Hamiltonian in the SAnySO4 mode.

get_phsu2_hamiltonian()

Internal method for setting Hamiltonian in the SAnyPHSU2 mode.

get_so3_hamiltonian()

Internal method for setting Hamiltonian in the SAnySO3 mode.

get_lz_hamiltonian()

Internal method for setting Hamiltonian in the SAnySU2LZ/SAnySZLZ/SAnySGFLZ modes.

get_custom_hamiltonian(site_basis, site_ops, orb_dependent_ops='cdCD')

Setting Hamiltonian in the general symmetry mode. SZ or SAny symmetry mode is required.

Args:

site_basislist[list[tuple[SX, int]]]

The set of quantum numbers (SX) and number of states (int) in the local Hilbert space at each site.

site_opslist[dict[str, np.ndarray[float|complex]]]

The matrix representation of elementary operators in the local Hilbert space at each site. Matrices must have ndim == 2. The indices of rows and columns correspond to the list given in site_basis. For example, When site_basis[0] = [(Q1, 2), (Q2, 3), (Q3, 1)], each matrix in site_ops[0] should have shape (6, 6) where the first 2 rows/columns correspond to the Q1 block, the next 3 rows/columns correspond to the Q2 block, etc. The operator name can only have one character.

orb_dependent_opsstr

List of operator names that can have point group irrep. If point group or orb_sym is not used, this can be empty. Default is “cdCD”.

Returns:

ghamilCustomHamiltonian

The Hamiltonian object, implicitly required for MPO and MPS construction.

write_fcidump(h1e, g2e, ecore=0, filename=None, h1e_symm=False, pg='d2h')

Write quantum chemistry integrals as a FCIDUMP format file. Supports SZ, SU2, and SGF modes.

Args:

h1enp.ndarray[float|complex] or list[np.ndarray[float|complex]]

ndim = 2 one-electron integral. For SZ mode, this is a list/tuple of two np.ndarray, for the aa and bb components, respectively.

g2enp.ndarray[float|complex] or list[np.ndarray[float|complex]] or None

ndim = 4 or 2 or 1 unpacked/packed two-electron integral. For SZ mode, this is a list/tuple of three np.ndarray, for the aa, ab, and bb components, respectively.

ecorefloat or complex

Constant energy. Default is 0.

filenamestr or None

If not None, will write the integrals in the FCIDUMP format to a file named filename. Otherwise, no files will be written. Default is None.

h1e_symmbool

If True, the h1e is assumed symmetric/Hermitian and only the triangular part of it will be stored. This is the standard FCIDUMP format. If False, the full h1e will be stored, which will ensure the correctness for non-Hermitian/anti-Hermitian integrals. Default is False. Set to True if this FCIDUMP format will be read by other programs.

pgstr

Point group name. The MOLPRO convention for orb_sym is required for FCIDUMP files. This point group name is used to translate from the XOR convention (used by block2) to MOLPRO convention.

Returns:

fcidumpFCIDUMP

The block2 fcidump object.

read_fcidump(filename, pg='d2h', rescale=None, iprint=1)

Read the quantum chemistry integrals from a FCIDUMP format file. Supports SZ, SU2, and SGF modes. When this method returns, self.h1e, self.g2e, self.ecore, self.n_sites, self.n_elec, self.spin, self.pg_irrep, and self.pg will be set.

Args:

filenamestr

The name of the FCIDUMP format file.

pgstr

Point group name, used to translate from the MOLPRO convention (used in FCIDUMP format) to the XOR convention (used by block2).

rescaleNone or float or True

If None, will not rescale (default). If zero or True, will adjust h1e and the const energy so that the average diagonal element of h1e is zero. If non-zero float, will adjust h1e and the const energy so that the const energy becomes the given rescale number. After rescale, the integrals will only be correct for the given n_elec.

iprintint

Verbosity. Default is 1.

Returns:

fcidumpFCIDUMP

The block2 fcidump object.

su2_to_sgf()

Transform the spin-restricted integrals h1e and g2e to general spin orbital integrals h1e and g2e. Assuming self.h1e and self.g2e available and unpacked. The transformed integrals will be stored as self.h1e and self.g2e. This will also change self.n_sites and self.orb_sym (if available) accordingly.

integral_symmetrize(orb_sym, h1e=None, g2e=None, hxe=None, k_symm=None, iprint=1)

Symmetrize quantum chemistry integrals so that all elements violating point group restrictions are set to zero. Integrals (if not None) will be changed inplace.

Args:

orb_symlist[int]

The point group irreducible representation of each site (orbital), or the K-space irreducible representation of each site (orbital) if k_symm is not None.

h1enp.ndarray[float|complex] or None

ndim = 2 one-electron integral.

g2enp.ndarray[float|complex] or None

ndim = 4 unpacked two-electron integral.

hxenp.ndarray[float|complex] or None

Arbitrary ndim integrals or amplitudes.

k_symmNone or True

If None, orb_sym is understood as point group irreps. Otherwise, orb_sym is understood as K-space irreps.

iprintint

Verbosity. Default is 1.

get_conventional_qc_mpo(fcidump, algo_type=None, iprint=1)

Construct MPO for quantum chemistry Hamiltonian, using conventional methods. This method cannot take care of MPI parallelization (one may use self.parallelize_integrals to parallelize the integrals before invoking this method).

Args:

fcidumpFCIDUMP

The block2 fcidump object.

algo_typeMPOAlgorithmTypes or None

Strategies for building MPO from symbolic expression of second quantized operators. Only the Conventional|NC|CN based algorithms are accepted in this method. If None (default), MPOAlgorithmTypes.Conventional will be used.

iprintint

Verbosity. Default is 1.

Returns:

mpoMPO

The block2 MPO object.

get_identity_mpo(ancilla=False)

Construct MPO for the identity operator.

Args:

ancillabool

If True, will generate identity MPO including ancilla sites (used in finite temperature DMRG). Default is False.

Returns:

mpoMPO

The block2 MPO object.

unpack_g2e(g2e, n_sites=None)

Unfold the 8-fold or 4-fold or 1-fold two-electron integral to the 1-fold (unpacked) two-electron integral.

Args:

g2enp.ndarray[float|complex]

ndim = 4 or 2 or 1 packed/unpacked two-electron integral.

n_sitesint or None

Number of sites (orbitals). If None, will look at self.n_sites.

Returns:

g2enp.ndarray[float|complex]

ndim = 4 unpacked two-electron integral.

get_qc_mpo(h1e, g2e, ecore=0.0, para_type=None, reorder=None, cutoff=1e-20, integral_cutoff=1e-20, post_integral_cutoff=1e-20, fast_cutoff=1e-20, unpack_g2e=True, algo_type=None, normal_order_ref=None, normal_order_single_ref=None, normal_order_wick=True, symmetrize=True, sum_mpo_mod=-1, compute_accurate_svd_error=True, csvd_sparsity=0.0, csvd_eps=1e-10, csvd_max_iter=1000, disjoint_levels=None, disjoint_all_blocks=False, disjoint_multiplier=1.0, block_max_length=False, add_ident=True, esptein_nesbet_partition=False, ancilla=False, reorder_imat=None, gaopt_opts=None, iprint=1)

Construct MPO from integrals in a quantum chemistry Hamiltonian.

For quantum chemistry Hamiltonians, the unpacked 2-electron integral g2e uses chemists’ notation.

In SU2 symmetry (spin restricted) mode, the quantum chemistry Hamiltonian is given by

\[H = \sum_{\sigma,ij} [\mathrm{h1e}]_{ij}\ a^{\dagger}_{i\sigma} a_{j\sigma} + \frac{1}{2} \sum_{\sigma\sigma',ijkl} [\mathrm{g2e}]_{ijkl}\ a^{\dagger}_{i\sigma} a^\dagger_{k\sigma'} a_{l\sigma'} a_{j\sigma} + \mathrm{ecore}\]

In SZ symmetry (spin unrestricted) mode, the quantum chemistry Hamiltonian is given by

\[H = \sum_{\sigma,ij} [\mathrm{h1e}]_{\sigma,ij}\ a^{\dagger}_{i\sigma} a_{j\sigma} + \frac{1}{2} \sum_{\sigma\sigma',ijkl} [\mathrm{g2e}]_{\sigma\sigma',ijkl} \ a^{\dagger}_{i\sigma} a^\dagger_{k\sigma'} a_{l\sigma'} a_{j\sigma} + \mathrm{ecore}\]

with

\[\begin{split}[\mathrm{h1e}][0] = [\mathrm{h1e}]_{\alpha} \\ [\mathrm{h1e}][1] = [\mathrm{h1e}]_{\beta} \\ [\mathrm{g2e}][0] = [\mathrm{g2e}]_{\alpha\alpha} \\ [\mathrm{g2e}][1] = [\mathrm{g2e}]_{\alpha\beta} \\ [\mathrm{g2e}][2] = [\mathrm{g2e}]_{\beta\beta}\end{split}\]

In SGF symmetry (general spin) mode, the quantum chemistry Hamiltonian is given by

\[H = \sum_{ij} [\mathrm{h1e}]_{ij}\ a^{\dagger}_{i} a_{j} + \frac{1}{2} \sum_{ijkl} [\mathrm{g2e}]_{ijkl}\ a^{\dagger}_{i} a^\dagger_{k} a_{l} a_{j} + \mathrm{ecore}.\]

Args:

h1enp.ndarray[float|complex] or list[np.ndarray[float|complex]]

ndim = 2 one-electron integral. For SZ mode, this can be a list/tuple of two np.ndarray, for the aa and bb components, respectively. For SZ mode, if only one np.ndarray is given, the two components will be assumed the same.

g2enp.ndarray[float|complex] or list[np.ndarray[float|complex]]

ndim = 4 or 2 or 1 unpacked/packed two-electron integral. For SZ mode, this can be a list/tuple of three np.ndarray, for the aa, ab, and bb components, respectively. For SZ mode, if only one np.ndarray is given, the three components will be assumed the same.

ecorefloat or complex

Constant term. Default is 0.

para_typeParallelTypes or None

The strategy for distributing the integrals (when self.mpi is not None). If None, the strategy ParallelTypes.SIJ will be used. Default is None. If the input integrals are already manually distributed, one should set this to ParallelTypes.Nothing. This argument has no effect if MPI is not activated (namely, when self.mpi is None).

reorderNone or str or np.ndarray[int] or True

The strategy for site/orbital reordering. If None, orbital will not be reordered. If np.ndarray[int], the orbital will be reordered using the given permutation. If this is “irrep”, orbitals with the same point group irrep will be put together. If this is “fiedler” or True, the fiedler method will be used. See also reorder_imat. If this is “gaopt”, the genetic algorithm will be used to find the optimal orbital reordering, using the “fiedler” ordering as the initial guess. See also reorder_imat and gaopt_opts. Note that this argument will perform the orbital reordering implicitly. This implicit ordering can be recognized by DMRGDriver.dmrg and DMRGDriver.get_npdm but it may not be compatible to some other operations in DMRGDriver. It is recommended to manually to perform the reordering on the integrals h1e, g2e and orb_sym before invoking this method to prevent any ambiguity.

cutofffloat

Cutoff of singular values when MPOAlgorithmTypes.SVD is used for MPO construction. Default is 1E-20.

integral_cutofffloat

Cutoff of individual elements in the integrals. Default is 1E-20.

post_integral_cutofffloat

Cutoff of individual elements in the transformed integrals. Default is 1E-20. Only have effect if normal_order_ref is not None.

fast_cutofffloat

Cutoff of individual elements in the integrals, implemented using C++ code. Default is 1E-20. This is intended to be used when the integrals are very large and any copying or unpacking of the integrals should be avoided to save memory. This should be used together with unpack_g2e = False, integral_cutoff = 0 and symmetrize = False to avoid copying or unpacking. Default is 1E-20. Only have effect if normal_order_ref is None.

unpack_g2ebool

Whether the g2e should be unpacked (using the Python code). Setting this to False may save some amount of memory, but many other operations on the integrals (including symmetrization and distributed parallelization) may fail. Default is True.

algo_typeNone or MPOAlgorithmTypes

Strategies for building MPO from symbolic expression of second quantized operators. If None, MPOAlgorithmTypes.FastBipartite will be used (default).

normal_order_refNone or np.ndarray[bool]

If not None, the integrals will be normal ordered, using normal_order_ref as the reference. Elements in normal_order_ref indicate whether the orbital is doubly occupied (True) or empty/singly occupied (False) in the reference state. Default is None (the integrals will not be normal ordered).

normal_order_single_refNone or np.ndarray[bool]

Only have effect if normal_order_ref is not None. Elements in normal_order_single_ref indicate whether the orbital is singly occupied (True) or empty/doubly occupied (False) in the reference state.

normal_order_wickbool

Only have effect if normal_order_ref is not None. If True, will use WickNormalOrder implementation (via automatic symbolic derivation). Otherwise, will use the manual implementation. Default is True.

symmetrizebool

Only have effect if self.orb_sym is not None (when point group symmetry is used). If True, will symmetrize integrals so that integral elements violating point group restrictions are set to zero. Default is True. May generate runtime error during DMRG when point group is used but the integrals are not symmetrized.

sum_mpo_modint

Only have effect if MPOAlgorithmTypes.Sum modifier appears in algo_type. Set the denominator for grouping indices in the sum of MPO approach. When this is -1, indices will not be grouped. Default is -1.

compute_accurate_svd_errorbool

Only have effect if MPOAlgorithmTypes.SVD appears in algo_type. If True, will compute and print the accurate error due to SVD truncation by comparing the difference between the original tensor and the contraction of its decomposed parts. Setting this to False may reduce some time cost of the SVD approach. Default is True.

csvd_sparsityfloat

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Sparsity for constrained SVD. Default is 0.0.

csvd_epsfloat

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Threshold for constrained SVD. Default is 1E-10.

csvd_max_iterint

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Maximal iteration number for constrained SVD. Default is 1000.

disjoint_levelsNone or list[float]

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. Threshold for finding connected elements at each level. Default is None.

disjoint_all_blocksbool

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. If False, only SVD for part of blocks will be done using disjoint SVD. Default is False.

disjoint_multiplierfloat

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. Allowing the number of singular values to exceed the maximal number, but no more than disjoint_multiplier times the maximal number. Default is 1.0.

block_max_lengthbool

Only have effect if MPOAlgorithmTypes.SVD or MPOAlgorithmTypes.Bipartite appears in algo_type. If True, will separate the SVD or Bipartite for one- and two-electron integrals. Default is False.

add_identbool

If True, the hidden identity operator will be added into the MPO. This is required when ecore is not zero and DMRGDriver.expectation will be invoked using this MPO. Default is True. One needs to set this to False to allow the MPO to be transformed into the Python format.

esptein_nesbet_partitionbool

If True, will only keep the “diagonal” part of the integrals for building MPO. This can be used to build the MPO for the zeroth-order Hamiltonian in the Esptein-Nesbet perturbation theory (used in perturbative DMRG). Default is False.

ancillabool

If True, will insert ancilla sites in the MPO, which can then be used for finite-temperature DMRG. Default is False.

reorder_imatNone or np.ndarray[float]

Only have effect when reorder == "fiedler" or reorder == "gaopt". The orbital interaction matrix (ndim == 2) used for computing the cost function for orbital reordering. If None, the exchange integral Kij will be used.

gaopt_optsdict or None

Only have effect when reorder == "gaopt". Custom options for the genetic orbital ordering algorithm. Possible keys are n_tasks, n_generations, n_configs, n_elite, clone_rate, and mutate_rate.

iprintint

Verbosity. Default is 1.

Returns:

mpoMPO

The block2 MPO object.

get_mpo(expr, iprint=0, cutoff=1e-14, left_vacuum=None, algo_type=None, sum_mpo_mod=-1, compute_accurate_svd_error=True, csvd_sparsity=0.0, csvd_eps=1e-10, csvd_max_iter=1000, disjoint_levels=None, disjoint_all_blocks=False, disjoint_multiplier=1.0, block_max_length=False, add_ident=True, ancilla=False)

Construct MPO from arbitrary symbolic expression of second quantized operators.

Args:

exprGeneralFCIDUMP

The block2 GeneralFCIDUMP object. This is often obtained from the ExprBuilder.finalize method.

iprintint

Verbosity. Default is 0 (quiet).

cutofffloat

Cutoff of singular values when MPOAlgorithmTypes.SVD is used for MPO construction. Default is 1E-20.

left_vacuumSX or None

The left_vacuum of MPO. If None, this will be automatically determined.

algo_typeNone or MPOAlgorithmTypes

Strategies for building MPO from symbolic expression of second quantized operators. If None, MPOAlgorithmTypes.FastBipartite will be used (default).

sum_mpo_modint

Only have effect if MPOAlgorithmTypes.Sum modifier appears in algo_type. Set the denominator for grouping indices in the sum of MPO approach. When this is -1, indices will not be grouped. Default is -1.

compute_accurate_svd_errorbool

Only have effect if MPOAlgorithmTypes.SVD appears in algo_type. If True, will compute and print the accurate error due to SVD truncation by comparing the difference between the original tensor and the contraction of its decomposed parts. Setting this to False may reduce some time cost of the SVD approach. Default is True.

csvd_sparsityfloat

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Sparsity for constrained SVD. Default is 0.0.

csvd_epsfloat

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Threshold for constrained SVD. Default is 1E-10.

csvd_max_iterint

Only have effect if MPOAlgorithmTypes.Constrained modifier appears in algo_type. Maximal iteration number for constrained SVD. Default is 1000.

disjoint_levelsNone or list[float]

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. Threshold for finding connected elements at each level. Default is None.

disjoint_all_blocksbool

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. If False, only SVD for part of blocks will be done using disjoint SVD. Default is False.

disjoint_multiplierfloat

Only have effect if MPOAlgorithmTypes.Disjoint modifier appears in algo_type. Allowing the number of singular values to exceed the maximal number, but no more than disjoint_multiplier times the maximal number. Default is 1.0.

block_max_lengthbool

Only have effect if MPOAlgorithmTypes.SVD or MPOAlgorithmTypes.Bipartite appears in algo_type. If True, will separate the SVD or Bipartite for one- and two-electron integrals. Default is False.

add_identbool

If True, the hidden identity operator will be added into the MPO. This is required when ecore is not zero and DMRGDriver.expectation will be invoked using this MPO. Default is True. One needs to set this to False to allow the MPO to be transformed into the Python format.

ancillabool

If True, will insert ancilla sites in the MPO, which can then be used for finite-temperature DMRG. Default is False.

Returns:

mpoMPO

The block2 MPO object.

get_site_mpo(op, site_index, iprint=1)

Construct MPO from the creation (C) or destroy (D) operator on a single site. Supports SU2, SZ, and SGF modes.

Args:

opstr

The name of the operator.

site_indexint

The index (subscript) of the operator.

iprintint

Verbosity. Default is 1.

Returns:

mpoMPO

The block2 MPO object.

get_spin_square_mpo(iprint=1)

Construct MPO for the S^2 operator where S is the total spin operator. Supports SU2, SZ, and SGF modes.

Args:

iprintint

Verbosity. Default is 1.

Returns:

mpoMPO

The block2 MPO object.

get_mpo_any_fermionic(op_list, ecore=None, **kwargs)

Construct MPO from a list of second quantized fermionic operators and coefficients. Supports the SGF mode only.

Args:

op_listlist[tuple[str, float]]

A list of second quantized fermionic operators and coefficients. + is creation, - is destroy. For example,

[ ('+_3 +_4 -_1 -_3', 0.0068705380508780715),
  ('+_3 +_4 -_4 -_3', -0.009852150878546906) ]

ecorefloat|complex or None

Constant term. Default is None (0.0).

kwargsdict

Other options that should be passed to DMRGDriver.get_mpo.

Returns:

mpoMPO

The block2 MPO object.

get_mpo_any_pauli(op_list, ecore=None, **kwargs)

Construct MPO from a list of Pauli strings and coefficients. Supports the SGB mode with the pauli_mode = True in DMRGDriver.initialize_system only.

Args:

op_listlist[tuple[str, float]]

A list of Pauli strings and coefficients. Characters in the string can be IXYZ. For example,

[ ('IIXXXIIX', 0.0559742284070319),
  ('IIIXIIXZ', 0.0018380565450674) ]

ecorefloat|complex or None

Constant term. Default is None (0.0).

kwargsdict

Other options that should be passed to DMRGDriver.get_mpo.

Returns:

mpoMPO

The block2 MPO object.

orbital_reordering(h1e, g2e, method='fiedler', **kwargs)

Find optimal orbital ordering for integrals h1e and g2e. Note that this method will not actually perform any orbital ordering. The exchange integral Kij (constructed from the given h1e and g2e) will be used for computing the cost function.

Args:

h1enp.ndarray[float|complex]

ndim = 2 one-electron integral.

g2enp.ndarray[float|complex]

ndim = 4 unpacked two-electron integral.

methodstr

The algorithm name for orbital reordering. Can be “gaopt” or “fiedler” (default).

kwargsdict

Only have effect when method == "gaopt". Custom options for the genetic orbital ordering algorithm. Possible keys are n_tasks, n_generations, n_configs, n_elite, clone_rate, and mutate_rate.

Returns:

idxnp.ndarray[int]

Optimal orbital ordering (permutation array).

orbital_reordering_interaction_matrix(imat, method='fiedler', **kwargs)

Find optimal orbital ordering using the orbital interaction matrix to compute the cost function. Note that this method will not actually perform any orbital ordering.

Args:

imatnp.ndarray[float]

The orbital interaction matrix (ndim == 2) used for computing the cost function.

methodstr

The algorithm name for orbital reordering. Can be “gaopt” or “fiedler” (default).

kwargsdict

Only have effect when method == "gaopt". Custom options for the genetic orbital ordering algorithm. Possible keys are n_tasks, n_generations, n_configs, n_elite, clone_rate, and mutate_rate.

Returns:

idxnp.ndarray[int]

Optimal orbital ordering (permutation array).

dmrg(mpo, ket, n_sweeps=10, tol=1e-08, bond_dims=None, noises=None, thrds=None, iprint=0, dav_type=None, cutoff=1e-20, twosite_to_onesite=None, dav_max_iter=4000, dav_def_max_size=50, proj_mpss=None, proj_weights=None, store_wfn_spectra=True, spectra_with_multiplicity=False, lowmem_noise=False, sweep_start=0, forward=None)

Perform the ground state and/or excited state Density Matrix Renormalization Group (DMRG) algorithm, which finds the solution of the following optimization problem:

\[E_0 = \min_{\mathrm{ket}} \frac{\langle \mathrm{ket} | \mathrm{mpo} | \mathrm{ket} \rangle} {\langle \mathrm{ket} | \mathrm{ket} \rangle}.\]

Statistics during the sweeps can be obtained from self._dmrg after the method returns.

Args:

mpoMPO

The block2 MPO object.

ketMPS

The block2 MPS object. The given MPS ket will be used as the initial guess for DMRG. When this method returns, the MPS ket will contain the optimized (ground and/or excited) state. If ket.nroots != 1, state-averaged DMRG will be done to find the ground and excited states. If ket.dot == 2, will perform 2-site DMRG algorithm. If ket.dot == 1, will perform 1-site DMRG algorithm. The initial input ket is not required to be normalized. The output ket will always be normalized.

n_sweepsint

Maximal number of DMRG sweeps. Default is 10.

tolfloat

Energy converge threshold. If the absolute value of the total energy difference between two consecutive sweeps is below tol, and the noise for the current sweep is zero, the algorithm will terminate. Default is 1E-8.

bond_dimsNone or list[int]

List of MPS bond dimensions for each sweep. Default is None. If None, the bond dimension of the initial MPS will be used for all sweeps.

noisesNone or list[float]

List of prefactor of the noise for each sweep. Default is None. If None, this is set to [1e-5] * 5 + [0]. Typically, this should be zero for the last few sweeps.

thrdsNone or list[float]

List of the convergence threshold (square of the residual) of the Davidson algorithms each sweep. Default is None. If None, this is set to [1e-6] * 4 + [1e-7] * 1 for double precision and [1e-5] * 4 + [5e-6] * 1 for single precision.

iprintint

Verbosity. Default is 0 (quiet).

dav_typeNone or str

The type of the Davidson algorithm. If None, this is set to “Normal”. Possible other options are “NonHermitian” (required for non-Hermitian Hamiltonian), “Exact” (constructing the full dense effective Hamiltonian and find all eigenvalues), “ExactNonHermitian”, “DavidsonPrecond”, and “NoPrecond”. “Normal” will use the Olsen preconditioning, “DavidsonPrecond” will use the Davidson preconditioning, and “NoPrecond” will not use any preconditioning. Default is None.

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-20.

twosite_to_onesiteNone or int

If not None and ket.dot == 2 in the initial MPS, will perform twosite_to_onesite 2-site sweeps and then switch to the 1-site algorithm for the remaining sweeps. Default is None (no switching).

dav_max_iterint

Maximal number of Davidson iteration. Default is 4000.

dav_def_max_sizeint

Maximal size of the Davidson deflation space (Krylov space). Default is 50. For very large MPS bond dimension and very small MPO bond dimension, one may reduce this number to save memory.

proj_mpssNone or list[MPS]

If not None, the MPS given in proj_mpss will be projected out during sweeps. Can be used for performing state-specific excited state DMRG. Default is None.

proj_weightsNone or list[float]

The weights of the MPS projection. This should be larger than the energy gap between the targeted state and the projected state. But if this is too large, the error in the projected state will affect the quality of the targeted state.

store_wfn_spectrabool

If True, the MPS singular value spectra will be stored as self._sweep_wfn_spectra which can be later used to compute the bipartite entropy. If False, the spectra will not be computed. Default is True.

spectra_with_multiplicitybool

If True, in SU2 mode, the MPS singular value will be multiplied by the multiplicity of the spin quantum number. Default is False.

lowmem_noisebool

If True, the noise step will cost less memory. Default is False.

sweep_startint

The starting sweep index in bond_dims, noises, and thrds. Default is 0. This may be useful in restarting, when one wants to skip the sweep parameters for a few already finished sweeps.

forwardNone or bool

The direction of the first sweep (forward == True means the left-to-right direction). If None, will use the canonical center of MPS to determine the direction. Default is None. This may be useful in restarting.

Returns:

energyfloat|complex or list[float|complex]

When ket.nroots == 1, this is the ground state energy. When ket.nroots != 1, this is a list of ground and excited state energies.

td_dmrg(mpo, ket, delta_t=None, target_t=None, final_mps_tag=None, te_type='rk4', n_steps=None, bond_dims=None, n_sub_sweeps=2, normalize_mps=False, hermitian=False, iprint=0, cutoff=1e-20, krylov_conv_thrd=5e-06, krylov_subspace_size=20)

Perform the time-dependent DMRG algorithm, which computes:

\[|\mathrm{ket'}\rangle = \exp (-t \cdot \mathrm{mpo} ) |\mathrm{ket}\rangle.\]

Statistics during the sweeps can be obtained from self._te after the method returns.

Args:

mpoMPO

The block2 MPO object.

ketMPS

The block2 MPS object at time zero. When this MPS has a very low bond dimension, this implementation of td-DMRG may be inaccurate. When this method returns, this MPS will not be modified.

delta_tNone or float or complex

The time step. When this is complex, SymmetryTypes.CPX must be used. If None, will be determined using delta_t = target_t / n_steps.

target_tNone or float or complex

The target time (the time parameter in the final state). If None, will be determined using target_t = delta_t * n_steps.

final_mps_tagNone or str

The tag of the output MPS. If None, the output MPS tag will be "TD-" + ket.info.tag. One can set this to be same as the tag of ket, then the ket object should not be used after calling this method.

te_typestr

The time evolution algorithm. Can be “rk4” (the time-step-targeting method) or “tdvp” (the time-dependent variational principle method).

n_stepsNone or int

The number of time steps. If None, will be determined using n_steps = int(abs(target_t) / abs(delta_t) + 0.1).

bond_dimsNone or list[int]

MPS bond dimension for each time step. If None, will be set to the bond dimension of the initial MPS for all steps.

n_sub_sweepsint

For te_type = "rk4", this is the number of sweeps performed for each time step. Default is 2.

normalize_mpsbool

If True, MPS will be normalized after each time step. Default is False.

hermitianbool

If True, the mpo operator will be assumed to be Hermitian. Default is False. Only have effects when te_type = "tdvp".

iprintint

Verbosity. Default is 0 (quiet).

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-20.

krylov_conv_thrdfloat

Convergence threshold (square of the residual) of the Matrix exponentiation algorithm. Default is 5E-6. Only have effects when te_type = "tdvp".

krylov_subspace_sizeint

Maximal size of the Krylov space of the Matrix exponentiation algorithm. Default is 20. Only have effects when te_type = "tdvp".

Returns:

final_mpsMPS

The time evolved MPS.

get_dmrg_results()

Obtain the statistics of DMRG sweeps. This should be called after DMRGDriver.dmrg.

Returns:

bond_dimsnp.ndarray[int]

The MPS bond dimension for each sweep.

dwsnp.ndarray[float]

The maximal discarded weight (sum of discarded eigenvalues) for each sweep.

energiesnp.ndarray[list[float]]

The list of ground (and possibly excited) state energies at each sweep.

get_bipartite_entanglement(ket=None)

Compute the bipartite entanglement of the MPS.

Args:

ketMPS or None

The MPS. If None, will use self._sweep_wfn_spectra computed during the DMRG/expectation sweeps if this is called after calling DMRGDriver.dmrg or DMRGDriver.expectation. Default is None.

Returns:

bip_entnp.ndarray[float]

The bipartite entanglement of the MPS after each non-terminating site.

get_n_orb_rdm_mpos(orb_type=1, ij_symm=True, iprint=0)

Internal method for MPO construction for computing the 1- or 2-orbital reduced density matrices.

Args:

orb_typeint

1 or 2. Indicating whether the 1- or 2-orbital reduced density matrices should be computed. Default is 1.

ij_symmbool

Whether the ij index symmetry should be used. Default is True.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

mposdict[tuple[int…], list[MPO]]

The MPOs for computing the 1- or 2-orbital reduced density matrices.

get_orbital_entropies(ket, orb_type=1, ij_symm=True, use_npdm=True, iprint=0)

Compute the 1- or 2- orbital entropies for the given MPS.

Args:

ketMPS

The given MPS for computing orbital entropies.

orb_typeint

1 or 2. Indicating whether the 1- or 2-orbital reduced density matrices should be computed. Default is 1.

ij_symmbool

Whether the ij index symmetry should be used. Default is True.

use_npdmbool

Whether the more efficient algorithm based on N-PDM should be used. Default is True.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

entsnp.ndarray[float]

When orb_type == 1, this is ndim == 1 vector containing the 1-orbital entropies. When orb_type == 2, this is ndim == 2 matrix containing the 2-orbital entropies.

get_orbital_entropies_use_npdm(ket, orb_type=1, iprint=0)

Compute the 1- or 2- orbital entropies for the given MPS using the efficient algorithm based on N-PDM.

Args:

ketMPS

The given MPS for computing orbital entropies.

orb_typeint

1 or 2. Indicating whether the 1- or 2-orbital reduced density matrices should be computed. Default is 1.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

entsnp.ndarray[float]

When orb_type == 1, this is ndim == 1 vector containing the 1-orbital entropies. When orb_type == 2, this is ndim == 2 matrix containing the 2-orbital entropies.

get_orbital_interaction_matrix(ket, use_npdm=True, iprint=0)

Compute orbital interaction matrix based on the 1- or 2- orbital entropies for the given MPS.

Args:

ketMPS

The given MPS for computing orbital interaction matrix.

use_npdmbool

Whether the more efficient algorithm based on N-PDM should be used. Default is True.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

imatnp.ndarray[float]

The ndim == 2 orbital interaction matrix.

get_conventional_npdm(ket, pdm_type=1, bra=None, soc=False, site_type=1, iprint=0, max_bond_dim=None)

Compute the N-Particle Density Matrix (NPDM) for the given MPS using the conventional method.

Args:

ketMPS

The given MPS for computing NPDM.

pdm_typeint

1 or 2. Whether the 1PDM or 2PDM should be computed. Default is 1. For pdm_type == 2, the SGF mode is not supported.

braMPS or None

If None, will compute the normal NPDM. If not None, will compute the transition NPDM between bra and ket.

socbool

When pdm_type == 1 this indicates whether the 1 particle transition triplet density matrix (for spin-orbit coupling) should be computed instead of the normal 1PDM. Only have effects in the SU2 mode. Default is False.

site_typeint

0 or 1 or 2. Indicates whether the NPDM should be computed using the 0- or 1- or 2-site algorithms. Default is 1. 0-site and 1-site are faster than the 2-site algorithm for this purpose.

iprintint

Verbosity. Default is 0 (quiet).

max_bond_dimNone or int

If not None, the MPS bond dimension will be restricted during the sweeps. Default is None.

Returns:

dmnp.ndarray[float|complex]

When pdm_type == 1:

\[\begin{split}\begin{cases} \mathrm{dm}[\sigma, i, j] = \langle a_{i\sigma}^\dagger a_{j\sigma} \rangle & (\mathrm{SZ}) \\ \mathrm{dm}[i, j] = \sum_{\sigma} \langle a_{i\sigma}^\dagger a_{j\sigma} \rangle & (\mathrm{SU2}) \\ \mathrm{dm}[i, j] = \langle T_{ij} \rangle & (\mathrm{SU2/\ soc}) \\ \mathrm{dm}[i, j] = \langle a_{i}^\dagger a_{j} \rangle & (\mathrm{SGF}) \end{cases}\end{split}\]

When pdm_type == 2 (for SU2/SZ only):

\[\begin{split}\begin{cases} \mathrm{dm}[0, i, j, k, l] = \langle a_{i\alpha}^\dagger a_{j\alpha}^\dagger a_{k\alpha} a_{l\alpha} \rangle \\ \mathrm{dm}[1, i, j, k, l] = \langle a_{i\alpha}^\dagger a_{j\beta}^\dagger a_{k\beta} a_{l\alpha} \rangle \\ \mathrm{dm}[2, i, j, k, l] = \langle a_{i\beta}^\dagger a_{j\beta}^\dagger a_{k\beta} a_{l\beta} \rangle \end{cases}\end{split}\]

get_conventional_1pdm(ket, *args, **kwargs)

Compute the 1-Particle Density Matrix (1PDM) for the given MPS using the conventional method. See DMRGDriver.get_conventional_npdm.

get_conventional_2pdm(ket, *args, **kwargs)

Compute the 2-Particle Density Matrix (2PDM) for the given MPS using the conventional method. See DMRGDriver.get_conventional_npdm.

get_conventional_trans_1pdm(bra, ket, *args, **kwargs)

Compute the Transition 1-Particle Density Matrix (T-1PDM) between the given bra and ket MPSs using the conventional method. See DMRGDriver.get_conventional_npdm.

get_conventional_trans_2pdm(bra, ket, *args, **kwargs)

Compute the Transition 2-Particle Density Matrix (T-2PDM) between the given bra and ket MPSs using the conventional method. See DMRGDriver.get_conventional_npdm.

get_npdm(ket, pdm_type=1, bra=None, soc=False, site_type=0, algo_type=None, npdm_expr=None, mask=None, simulated_parallel=0, fused_contraction_rotation=True, cutoff=1e-24, iprint=0, max_bond_dim=None)

Compute the N-Particle Density Matrix (NPDM) for the given MPS. Supports SU2, SZ, and SGF modes.

Args:

ketMPS

The given MPS for computing NPDM.

pdm_typeint

Integer >= 1. The order of the PDM. Default is 1.

braMPS or None

If None, will compute the normal NPDM. If not None, will compute the transition NPDM between bra and ket.

socbool

When pdm_type == 1 this indicates whether the 1 particle transition triplet density matrix (for spin-orbit coupling) should be computed instead of the normal 1PDM. Only have effects in the SU2 mode. Default is False. If True, NPDMAlgorithmTypes.Conventional is required in algo_type.

site_typeint

0 or 1 or 2. Indicates whether the NPDM should be computed using the 0- or 1- or 2-site algorithms. Default is 0. 0-site and 1-site are faster than the 2-site algorithm for this purpose.

algo_typeNone or NPDMAlgorithmTypes

Strategies for computing N-particle density matrices. If None, this is set to NPDMAlgorithmTypes.Default. Default is None.

npdm_exprNone or str or list[str]

The operator expression for the NPDM. If None, this will be determined automatically. Multiple operator expressions are allowed in the SZ and SGF modes. Default is None.

maskNone or list[int] or list[list[int]]

The mask for setting repeated indices for the operator expression. Default is None, meaning that all indices can be different.

simulated_parallelint

Number of processors for simulating parallel algorithm serially. Default is zero, meaning that the serial algorithm is used if self.mpi is None or the parallel algorithm is used if self.mpi is not None. When self.mpi is None, one can optionally set this to a positive number to simulate the parallel algorithm which will be computationally less efficient but requiring less amount of memory.

fused_contraction_rotationbool

Indicating whether contraction and rotation should be done within one-step, without using large memory for blocking (only saving memory when no explicit left/right_contact is invoked, which is the case for site_type == 0). Default is True.

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-24.

iprintint

Verbosity. Default is 0 (quiet).

max_bond_dimNone or int

If not None, the MPS bond dimension will be restricted during the sweeps. Default is None.

Returns:

dmsnp.ndarray[flat|complex] or list[np.ndarray[flat|complex]]

A list of density matrices for different spin components in the SZ mode, or the spin-traced density matrix in the SU2 mode, or the spin-orbit density matrix in the SGF mode.

In the SU2 mode (when npdm_expr is None):

\[\mathrm{dm}[i, j, \cdots, b, a] = \sum_{\sigma,\sigma',\cdots} \langle a_{i\sigma}^\dagger a_{j\sigma'}^\dagger \cdots a_{b\sigma'} a_{a\sigma} \rangle\]

In the SZ mode (when npdm_expr is None):

\[\begin{split}\mathrm{dms}[0][i, \cdots, j, k, c, b, \cdots, a] = \langle a_{i\alpha}^\dagger \cdots a_{j\alpha}^\dagger a_{k\alpha} a_{c\alpha} a_{b\alpha} \cdots a_{a\alpha} \rangle \\ \mathrm{dms}[1][i, \cdots, j, k, c, b, \cdots, a] = \langle a_{i\alpha}^\dagger \cdots a_{j\alpha}^\dagger a_{k\beta} a_{c\beta} a_{b\alpha} \cdots a_{a\alpha} \rangle \\ \mathrm{dms}[2][i, \cdots, j, k, c, b, \cdots, a] = \langle a_{i\alpha}^\dagger \cdots a_{j\beta}^\dagger a_{k\beta} a_{c\beta} a_{b\beta} \cdots a_{a\alpha} \rangle \\ \cdots \\ \mathrm{dms}[\mathrm{pdm\_type}][i, \cdots, j, k, c, b, \cdots, a] = \langle a_{i\beta}^\dagger \cdots a_{j\beta}^\dagger a_{k\beta} a_{c\beta} a_{b\beta} \cdots a_{a\beta} \rangle\end{split}\]

In the SGF mode (when npdm_expr is None):

\[\mathrm{dm}[i, j, \cdots, b, a] = \langle a_{i}^\dagger a_{j}^\dagger \cdots a_{b} a_{a} \rangle\]

get_1pdm(ket, *args, **kwargs)

Compute the 1-Particle Density Matrix (1PDM) for the given MPS. See DMRGDriver.get_npdm.

get_2pdm(ket, *args, **kwargs)

Compute the 2-Particle Density Matrix (2PDM) for the given MPS. See DMRGDriver.get_npdm.

get_3pdm(ket, *args, **kwargs)

Compute the 3-Particle Density Matrix (3PDM) for the given MPS. See DMRGDriver.get_npdm.

get_4pdm(ket, *args, **kwargs)

Compute the 4-Particle Density Matrix (4PDM) for the given MPS. See DMRGDriver.get_npdm.

get_trans_1pdm(bra, ket, *args, **kwargs)

Compute the Transition 1-Particle Density Matrix (T-1PDM) between the given bra and ket MPSs. Note that there can be an overall phase uncertainty for transition NPDMs. See DMRGDriver.get_npdm.

get_trans_2pdm(bra, ket, *args, **kwargs)

Compute the Transition 2-Particle Density Matrix (T-2PDM) between the given bra and ket MPSs. Note that there can be an overall phase uncertainty for transition NPDMs. See DMRGDriver.get_npdm.

get_trans_3pdm(bra, ket, *args, **kwargs)

Compute the Transition 3-Particle Density Matrix (T-3PDM) between the given bra and ket MPSs. Note that there can be an overall phase uncertainty for transition NPDMs. See DMRGDriver.get_npdm.

get_trans_4pdm(bra, ket, *args, **kwargs)

Compute the Transition 4-Particle Density Matrix (T-4PDM) between the given bra and ket MPSs. Note that there can be an overall phase uncertainty for transition NPDMs. See DMRGDriver.get_npdm.

get_csf_coefficients(ket, cutoff=0.1, given_dets=None, max_print=200, iprint=1)

Find the dominant Configuration State Functions (CSFs, in SU2 mode) or determinants (DETs, in SZ/SGF mode) and their coefficients in the given MPS.

Args:

ketMPS

The given MPS for computing CSF/DET coefficients. If targeting non-singlet state in the SU2 mode, the MPS should be in the singlet embedding format.

cutofffloat

The lower bound for the absolute value of the CSF/DET coefficients that should be searched. Default is 0.1. If cutoff == 0.0, will compute coefficients for all CSF/DET, which may take an exponential amount of time.

given_detsNone or list[str]

If not None, will compute the coefficients for the given CSF/DET set. If cutoff != 0.0 and (given_dets == [] or given_dets is None), will consider all possible CSF/DET with the absolute value of the coefficients above cutoff. If cutoff != 0.0 and given_dets is not None and len(given_dets) != 0, the cutoff and given_dets will apply simultaneously, namely, a subset of given_dets which satisfies the cutoff constraint will be computed.

max_printint

The max number of CSF/DET and their coefficients that should be print. When the number of computed CSF/DET is larger than this number, only the dominant ones will be printed. When iprint == 0, this argument has no effect and nothing will be printed.

iprintint

Verbosity. Default is 1.

Returns:

detsnp.ndarray[np.uint8]

Array of CSF/DET, represented as a matrix with shape (n_dets, n_sites). The occupancy value 0, 1, 2, 3 represents “0” (empty), “+” (spin-up coupling), “-” (spin-down coupling), and “2” (doubly occupied) in the SU2 mode, or “0” (empty), “a” (alpha occupied), “b” (beta occupied), and “2” (doubly occupied) in the SZ/SGF mode.

dvalsnp.ndarray[float|complex]

Array of coefficients for each CSF/DET with size n_dets. Note that the weight is the square of coefficient. There can be an overall phase uncertainty for all coefficients.

compress_mps(ket, max_bond_dim=None)

Compress the MPS to change its maximal bond dimension (inplace).

Args:

ketMPS

The block2 MPS object.

max_bond_dimNone or int

If not None, will restrict the maximal bond dimension of the MPS to the given number. Default is None.

Returns:

ketMPS

The MPS with changed bond dimension. Note that this operation can change the canonical center of the MPS as a side effect.

align_mps_center(ket, ref, max_bond_dim=None)

Change the canonical center of the given MPS, or align the canonical center for two MPSs (inplace).

Args:

ketMPS

The block2 MPS object.

refMPS or int

If this is MPS, will change the canonical center of ket so that its center is the same as that of ref. If this is int, will set the canonical center of ket to the given number. Only the left/right canonical forms are allowed, namely, ref cannot correspond to a canonical center in the middle of MPS.

max_bond_dimNone or int

If not None, will restrict the maximal bond dimension of the resulting MPS to the given number. Default is None.

adjust_mps(ket, dot=None)

Adjust the MPS (inplace) for performing 1-site or 2-site sweep algorithms, and find the direction of the next sweep. When restarting from the middle, this method should not be called.

Args:

ketMPS

The block2 MPS object.

dotNone or int

If not None, should be 1 or 2 and the “site type” of the MPS will be changed to “1-site” or “2-site”. If None, the “site type” of the MPS will not be changed. Default is None.

Returns:

ketMPS

The MPS with the desired “site type”.

forwardbool

Indicating whether the direction of the next sweep should be forward or not.

split_mps(ket, iroot, tag)

Split a state-averaged MPS into individual MPSs.

Args:

ketMPS

The state-averaged MPS object with ket.nroots > 1.

irootint

The root index to extract from the state-averaged MPS. Counting from zero. 0 <= iroot < ket.nroots.

tagstr

The tag of the extracted MPS.

Returns:

iketMPS

The extracted MPS.

multiply(bra, mpo, ket, n_sweeps=10, tol=1e-08, bond_dims=None, bra_bond_dims=None, noises=None, noise_mpo=None, thrds=None, left_mpo=None, cutoff=1e-24, linear_max_iter=4000, iprint=0)

Apply the MPO to the MPS to get a new MPS (when left_mpo is None), which is

\[|\mathrm{bra}\rangle = \mathrm{mpo} |\mathrm{ket}\rangle\]

or apply the inverse of an MPO to the MPS to get a new MPS,

\[|\mathrm{bra}\rangle = \frac{\mathrm{mpo} |\mathrm{ket}\rangle}{\mathrm{left\_mpo}}\]

or fit the MPS to an MPS with a different bond dimension (when left_mpo is None and mpo is the identity MPO).

Args:

braMPS

The block2 MPS object. The given MPS bra will be used as the initial guess for the left-hand side MPS. When this method returns, the MPS bra will contain the optimized state fitted to the value of the right-hand side.

mpoMPO

The block2 MPO object (the right-hand side operator).

ketMPS

The block2 MPS object (the right-hand side state).

n_sweepsint

Maximal number of sweeps. Default is 10.

tolfloat

converge threshold for the norm of bra (when left_mpo is None) or the overlap <bra|ket> (when left_mpo is not None). Default is 1E-8.

bond_dimsNone or list[int]

List of ket bond dimensions for each sweep. Default is None. If None, the bond dimension of ket will be used.

bra_bond_dimsNone or list[int]

List of bra bond dimensions for each sweep. Default is None. If None, the bond dimension of initial bra will be used.

noisesNone or list[float]

List of prefactor of the noise for each sweep. Default is None. If None or [0], will not add any noise.

noise_mpoNone or MPO

If not None and noises is not zero or None, This MPO will be used for computing noise and left_mpo will be ignored. This should be used for the MPS compression with perturbative noise task.

thrdsNone or list[float]

List of the convergence threshold (square of the residual) of the linear solver. Default is None. If None, this is set to [1e-6] * 4 + [1e-7] * 1 for double precision and [1e-5] * 4 + [5e-6] * 1 for single precision.

left_mpoNone or MPO

If not None and noise_mpo is None, will apply the inverse of this MPO to the right-hand side.

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-24.

linear_max_iterint

Maximal number of iteration in the linear solver. Default is 4000.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

normfloat|complex

The norm of bra (when left_mpo is None) or the overlap <bra|ket> (when left_mpo is not None).

addition(bra, ket_a, ket_b, mpo_a=None, mpo_b=None, n_sweeps=10, tol=1e-08, bra_bond_dims=None, ket_a_bond_dims=None, ket_b_bond_dims=None, noises=None, noise_mpo=None, cutoff=1e-24, iprint=0)

Perform the addition of two MPSs to generate a new MPS (using fitting):

\[|\mathrm{bra}\rangle = \mathrm{mpo\_a} |\mathrm{ket\_a}\rangle + \mathrm{mpo\_b} |\mathrm{ket\_b}\rangle.\]

Args:

braMPS

The block2 MPS object. The given MPS bra will be used as the initial guess for the left-hand side MPS. When this method returns, the MPS bra will contain the optimized state fitted to the value of the right-hand side.

ket_aMPS

The first input block2 MPS object.

ket_bMPS

The second input block2 MPS object.

mpo_aNone or int or float or complex or MPO

The first input block2 MPO object. If None or a scalar, this will be the identity MPO or a scalar times the identity MPO. Default is None.

mpo_bNone or int or float or complex or MPO

The second input block2 MPO object. If None or a scalar, this will be the identity MPO or a scalar times the identity MPO. Default is None.

n_sweepsint

Maximal number of sweeps. Default is 10.

tolfloat

converge threshold for the norm of bra. Default is 1E-8.

bra_bond_dimsNone or list[int]

List of bra bond dimensions for each sweep. Default is None. If None, the bond dimension of initial bra will be used.

ket_a_bond_dimsNone or list[int]

List of ket_a bond dimensions for each sweep. Default is None. If None, the bond dimension of ket_a will be used.

ket_b_bond_dimsNone or list[int]

List of ket_b bond dimensions for each sweep. Default is None. If None, the bond dimension of ket_b will be used.

noisesNone or list[float]

List of prefactor of the noise for each sweep. Default is None. If None or [0], will not add any noise.

noise_mpoNone or MPO

If not None and noises is not zero or None, This MPO will be used for computing noise.

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-24.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

normfloat|complex

The norm of bra.

expectation(bra, mpo, ket, store_bra_spectra=False, store_ket_spectra=False, iprint=0)

Compute the expectation value between MPO and bra and ket MPSs:

\[X = \langle \mathrm{bra} | \mathrm{mpo} | \mathrm{ket} \rangle.\]

Args:

braMPS

The “bra” MPS. In complex mode, the complex conjugate of bra is implied.

mpoMPO

The block2 MPO object, representing the operator.

ketMPS

The “ket” MPS.

store_bra_spectrabool

If True, the bra MPS singular value spectra will be stored as self._sweep_wfn_spectra which can be later used to compute the bipartite entropy. If False, the spectra will not be computed. Default is False. Only one of store_bra_spectra and store_ket_spectra can be True.

store_ket_spectrabool

If True, the ket MPS singular value spectra will be stored as self._sweep_wfn_spectra which can be later used to compute the bipartite entropy. If False, the spectra will not be computed. Default is False. Only one of store_bra_spectra and store_ket_spectra can be True.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

exfloat|complex

The expectation value.

greens_function(bra, mpo, rmpo, ket, omega, eta, n_sweeps=10, tol=1e-08, bra_bond_dims=None, ket_bond_dims=None, noises=None, thrds=None, cutoff=1e-24, linear_max_iter=4000, iprint=0)

Compute the correction vector MPS for Green’s function:

\[|\mathrm{bra}\rangle = \frac {\mathrm{rmpo} |\mathrm{ket} \rangle} {\mathrm{mpo} + \omega + \eta \mathrm{i}}\]

and returns the diagonal element of Green’s function:

\[G = \langle \mathrm{bra}|\mathrm{rmpo}|\mathrm{ket}\rangle.\]

Args:

braMPS

The block2 MPS object. The given MPS bra will be used as the initial guess for the correction vector MPS. When this method returns, the MPS bra will contain the optimized state fitted to the value of the right-hand side of the correction vector equation.

mpoMPO

The input block2 MPO object in the denominator.

rmpoMPO

The input block2 MPO object in the numerator.

ketMPS

The input block2 MPS object in the numerator.

omegafloat

The frequency.

etafloat

The broadening factor.

n_sweepsint

Maximal number of sweeps. Default is 10.

tolfloat

Converge threshold for the absolute value of the diagonal Green’s function value <bra|rmpo|ket>. Default is 1E-8.

bra_bond_dimsNone or list[int]

List of bra bond dimensions for each sweep. Default is None. If None, the bond dimension of initial bra will be used.

ket_bond_dimsNone or list[int]

List of ket bond dimensions for each sweep. Default is None. If None, the bond dimension of ket will be used.

noisesNone or list[float]

List of prefactor of the noise for each sweep. Default is None. If None or [0], will not add any noise.

thrdsNone or list[float]

List of the convergence threshold (square of the residual) of the linear solver. Default is None. If None, this is set to [1e-6] * 4 + [1e-7] * 1 for double precision and [1e-5] * 4 + [5e-6] * 1 for single precision.

cutofffloat

States with eigenvalue below this number will be discarded, even when the bond dimension is large enough to keep this state. Default is 1E-24.

linear_max_iterint

Maximal number of iteration in the linear solver. Default is 4000.

iprintint

Verbosity. Default is 0 (quiet).

Returns:

gfcomplex

The diagonal element of Green’s function <bra|rmpo|ket>.

fix_restarting_mps(mps)

Internal method for fixing the canonical form of MPS loaded from disk when the calculation was interrupted in the middle of a sweep.

Args:

mpsMPS

The MPS loaded from disk.

copy_mps(mps, tag)

Make a deep copy of an MPS.

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS (for disk storage).

Returns:

ketMPS

The copy of MPS.

load_mps(tag, nroots=1)

Load an MPS from disk (from the DMRGDriver.scratch folder).

Args:

tagstr

The tag of the MPS to be loaded.

nrootsint

Number of roots in the MPS. Default is 1.

Returns:

mpsMPS

The loaded MPS.

mps_change_singlet_embedding(mps, tag, forward, left_vacuum=None)

Change MPS between the Singlet-Embedding (SE) and Non-Singlet-Embedding (NSE) formats.

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

forwardbool

If True, will change from NSE to SE. Otherwise, will change from SE to NSE.

left_vacuumNone or SX

If forward == True and left_vacuum is not None, this is the left vacuum to be used in SE MPS. If None, the left vacuum quantum number will be automatically determined. Default is None.

Returns:

cp_mpsMPS

The output MPS.

mps_change_to_singlet_embedding(mps, tag, left_vacuum=None)

Change MPS from Non-Singlet-Embedding (NSE) to Singlet-Embedding (SE).

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

left_vacuumNone or SX

If not None, this is the left vacuum to be used in SE MPS. If None, the left vacuum quantum number will be automatically determined. Default is None.

Returns:

cp_mpsMPS

The output MPS.

mps_change_from_singlet_embedding(mps, tag, left_vacuum=None)

Change MPS from Singlet-Embedding (SE) to Non-Singlet-Embedding (NSE).

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

left_vacuumNone or SX

Not used. Default is None.

Returns:

cp_mpsMPS

The output MPS.

mps_change_precision(mps, tag)

Change MPS from single to double precision (when symm_type has the SymmetryTypes.SP modifier) or from double to single precision (when symm_type does not have the SymmetryTypes.SP modifier).

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

Returns:

rMPS

The output MPS.

mps_change_complex(mps, tag)

Change MPS from complex to real (when symm_type has the SymmetryTypes.CPX modifier) or from real to complex (when symm_type does not have the SymmetryTypes.CPX modifier). For complex to real transformation, the imaginary part will be discarded.

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

Returns:

rMPS

The output MPS.

mps_change_to_sz(mps, tag, sz=None)

Change MPS from spin-adapted to non-spin-adapted. Only works in SU2 mode. The resulting MPS should be used in SZ mode.

Args:

mpsMPS

The input MPS.

tagstr

The tag of the output MPS.

szNone or int

If not None, will restrict two times the project spin of the output MPS to be the given number. If None, the output MPS will contain all possible project spin components. Default is None.

Returns:

zmpsMPS

The output MPS.

get_random_mps(tag, bond_dim=500, center=0, dot=2, target=None, nroots=1, occs=None, full_fci=True, left_vacuum=None, casci_ncore=0, casci_nvirt=0, mrci_order=0, orig_dot=False)

Create a random MPS, which can be used as initial guess for various sweep algorithms, such as DMRG.

Args:

tagstr

The tag of the output MPS, for disk storage.

bond_dimint

The maximal bond dimension hint of the MPS. Default is 500. Note that the output MPS may not have exactly the given bond dimension.

centerint

The canonical center of the MPS. Default is zero.

dotint

Can be 1 or 2. The “site type” of the MPS. Default is 2.

targetNone or SX.

The target quantum number of the MPS. If None, will use self.target. Default is None.

nrootsint

Number of roots in the MPS. Default is 1. nroots > 1 indicates the state-averaged MPS (which may be used for excited state DMRG).

occsNone or list[float]

If not None, the hint of the occupancy information at each site of the MPS. Default is None, and a uniform probability of occupancy will be assumed.

full_fcibool

If True, the full fci space is used (including block quantum numbers outside the space of the target quantum number). Default is True.

left_vacuumNone or SX

If not None, this is the left vacuum to be used in SE MPS. If None, self.left_vacuum will be used. Only has effects in SU2 mode for SE MPS with non-singlet target.

casci_ncoreint

If not zero, The number of core orbitals in a CASCI MPS. These orbitals will always be kept doubly occupied (if mrci_order == 0). Default is zero.

casci_nvirtint

If not zero, The number of virtual orbitals in a CASCI MPS. These orbitals will always be kept empty (if mrci_order == 0). Default is zero.

mrci_orderint

If not zero, the core and virtual orbitals will have at most mrci_order holes and electrons, respectively. Default is zero.

orig_dotbool

If False, will always create “1-site” MPS and then change to the suitable “site type”. Otherwise, the “1-site” or “2-site” MPS will be directly created. Default is False.

Returns:

mpsMPS

The output MPS (normalized).

get_ancilla_mps(tag, center=0, dot=2, target=None, full_fci=True)

Create the MPS with ancilla sites for finite-temperature algorithms. This is the MPS at infinite temperature.

Args:

tagstr

The tag of the output MPS, for disk storage.

centerint

The canonical center of the MPS. Default is zero.

dotint

Can be 1 or 2. The “site type” of the MPS. Default is 2.

targetNone or SX.

The target quantum number of the MPS. If None, will use self.target. Default is None.

full_fcibool

If True, the full FCI space is used (including block quantum numbers outside the space of the target quantum number). Default is True.

Returns:

mpsMPS

The output MPS.

get_mps_from_csf_coefficients(dets, dvals, tag, dot=2, target=None, full_fci=True, left_vacuum=None)

Construct an MPS from the given linear combination of Configuration State Functions (CSFs, in SU2 mode) or determinants (DETs, in SZ/SGF mode).

Args:

detsnp.ndarray[np.uint8] or list[str]

Array of CSF/DET, represented as a matrix with shape (n_dets, n_sites). The occupancy value 0, 1, 2, 3 represents “0” (empty), “+” (spin-up coupling), “-” (spin-down coupling), and “2” (doubly occupied) in the SU2 mode, or “0” (empty), “a” (alpha occupied), “b” (beta occupied), and “2” (doubly occupied) in the SZ/SGF mode.

dvalsnp.ndarray[float|complex]

Array of coefficients for each CSF/DET with size n_dets.

tagstr

The tag of the output MPS, for disk storage.

dotint

Can be 1 or 2. The “site type” of the MPS. Default is 2.

targetNone or SX.

The target quantum number of the MPS. If None, will use self.target. Default is None.

full_fcibool

If True, the full fci space is used (including block quantum numbers outside the space of the target quantum number). Default is True.

left_vacuumNone or SX

If not None, this is the left vacuum to be used in SE MPS. If None, self.left_vacuum will be used. Only has effects in SU2 mode for SE MPS with non-singlet target.

Returns:

mpsMPS

The output MPS.

expr_builder()

Get the ExprBuilder object for setting terms in second quantized operators.

Returns:

builderExprBuilder

The ExprBuilder object.

finalize()

Release stack memory allocated for this DMRGDriver object. Once finalized, this object should not be used.

class pyblock2.driver.core.SOCDMRGDriver(*args, **kwargs)

Bases: DMRGDriver

Simple Python interface for DMRG calculations with Spin-Orbit-Coupling (SOC).

__init__(*args, **kwargs)

Initialize DMRGDriver.

Args:

symm_typeSymmetryTypes

The symmetry/floating point number mode. Default: SymmetryTypes.SU2.

scratchstr

The working directory (scratch space). Default is “./nodex”.

clean_scratchbool

If True, large temporary files in the scratch space will be removed once the DMRG finishes successfully. MPS files will not be removed. Default is True.

restart_dirNone or str

If not None, MPS will be copied to the given directory after each DMRG sweep. Default is None (MPS will not be copied).

n_threadsNone or int

Number of threads. When MPI is used, this is the number of threads for each MPI processor. Default is None, and the max number of threads available on this node will be used.

n_mkl_threadsint

Number of threads for parallelization inside MKL (for dense matrix multiplication). n_mkl_threads should be a factor of n_threads. When n_mkl_threads is not 1, nested threading will be used. Default is 1.

mpiNone or bool

If True, MPI parallelization is used. If False or None, serial implementation is used. Default is None.

stack_memint

The memory used for storing renormalized operators (in bytes). Default is 1 GB. When MPI is used, this is the number per MPI processor. Note that this argument is only responsible for part of the memory consumption in block2. The other part will be dynamically determined.

stack_mem_ratiofloat

The fraction of stack space occupied by the main stacks. Default is 0.4.

fp_codec_cutofffloat

Floating-point number (absolute) precision for compressed storage of renormalized operators. Default is 1E-16.

hybrid_mpo_dmrg(mpo, mpo_cpx, ket, n_sweeps=10, iprint=0, tol=1e-08, **kwargs)

Perform the ground state and excited state Density Matrix Renormalization Group (DMRG) algorithm using the sum of a real MPO and a complex MPO.

Args:

mpoMPO

The real MPO.

mpo_cpxMPO

The complex MPO.

ketMPS

The block2 MPS object. The given MPS ket will be used as the initial guess for DMRG. When this method returns, the MPS ket will contain the optimized (ground and/or excited) state. If ket.nroots != 1, state-averaged DMRG will be done to find the ground and excited states. If ket.dot == 2, will perform 2-site DMRG algorithm. If ket.dot == 1, will perform 1-site DMRG algorithm. The initial input ket is not required to be normalized. The output ket will always be normalized.

n_sweepsint

Maximal number of DMRG sweeps. Default is 10.

tolfloat

Energy converge threshold. If the absolute value of the total energy difference between two consecutive sweeps is below tol, and the noise for the current sweep is zero, the algorithm will terminate. Default is 1E-8.

iprintint

Verbosity. Default is 0 (quiet).

kwargsdict

Other options that should be passed to DMRGDriver.dmrg.

Returns:

energyfloat|complex or list[float|complex]

When ket.nroots == 1, this is the ground state energy. When ket.nroots != 1, this is a list of ground and excited state energies.

soc_two_step(energies, twoss, pdms_dict, hsomo, iprint=1)

The second step in the two-step SOC-DMRG.

Args:

energieslist[float|complex]

Energy of the spin-free states.

twosslist[int]

Two times the total spin for each spin-free state.

pdms_dictdict[tuple[int, int], np.ndarray[float|complex]]

The 1-particle triplet transition density matrix for each pair of states.

hsomonp.ndarray[complex]

The spin-orbit coupling integral in molecular orbitals.

iprintint

Verbosity. Default is 1.

Returns:

heiglist[float|complex]

The ground and excited state energies including SOC effects.

class pyblock2.driver.core.NormalOrder

Bases: object

Static methods for normal ordering for quantum chemistry integrals.

static def_ix(cidx)

Internal method for index slicing.

static def_gctr(cidx, h1e, g2e)

Internal method for contraction with integrals.

static def_gctr_sz(cidx, h1e, g2e)

Internal method for contraction with integrals in the SZ mode.

static make_su2(h1e, g2e, const_e, cidx, use_wick)

Perform normal ordering of quantum chemistry integrals in the SU2 mode.

static make_sz(h1e, g2e, const_e, cidx, use_wick)

Perform normal ordering of quantum chemistry integrals in the SZ mode.

static make_sgf(h1e, g2e, const_e, cidx, use_wick)

Perform normal ordering of quantum chemistry integrals in the SGF mode.

class pyblock2.driver.core.WickNormalOrder

Bases: object

Static methods for normal ordering for quantum chemistry integrals implemented using automatic symbolic derivation.

static make_su2(h1e, g2e, const_e, cidx, iprint=1)

Perform normal ordering of quantum chemistry integrals in the SU2 mode.

static make_su2_open_shell(h1e, g2e, const_e, cidx, midx, iprint=1)

Perform normal ordering of quantum chemistry integrals in the SU2 mode for non-singlet reference states.

static make_sz(h1e, g2e, const_e, cidx, iprint=1)

Perform normal ordering of quantum chemistry integrals in the SZ mode.

static make_sgf(h1e, g2e, const_e, cidx, iprint=1)

Perform normal ordering of quantum chemistry integrals in the SGF mode.

class pyblock2.driver.core.ExprBuilder(bw=None)

Bases: object

Helper class for setting terms in second quantized operators.

Attributes:

bwBlock2Wrapper

The wrapper for low-level block2 modules.

dataGeneralFCIDUMP

The block2 GeneralFCIDUMP object.

__init__(bw=None)

Initialize ExprBuilder.

Args:

bwBlock2Wrapper or None

The wrapper for low-level block2 modules. If None, will assume the SU2 symmetry mode.

add_const(x)

Add a constant term.

Args:

xint or float or complex

A scalar constant.

Returns:

selfExprBuilder

The ExprBuilder object.

add_term(expr, idx, val)

Add a string of elementary operators with the given coefficient (when the length of idx matches the length of expr), or a sum of strings of elementary operators with the same name, but different site indices and coefficients (when the length of idx is multiple of the length of expr).

Args:

exprstr

The names of elementary operators, such as “cdCD”.

idxlist[int]

The site index of each elementary operator.

vallist[float|complex] or float or complex

The coefficient of the term or the coefficients of multiple terms.

Returns:

selfExprBuilder

The ExprBuilder object.

add_sum_term(expr, arr, cutoff=1e-12, fast=True, factor=1.0, perm=None)

Add terms with coefficients as a tensor.

Args:

exprstr

The names of elementary operators, such as “cdCD”.

arrnp.ndarray[float|complex]

The coefficients as a tensor. The ndim of this tensor should match the length of expr.

cutofffloat

If the absolute value of any coefficient is below this threshold, the term will not be included. Default is 1E-12.

fastbool

If True, will use the fast C++ implementation. Default is True.

factorfloat

The scale factor for all terms.

permNone or list[int]

If not None, a permutation will be applied on the coefficient tensor indices. Default is None.

Returns:

selfExprBuilder

The ExprBuilder object.

add_terms(expr, arr, idx, cutoff=1e-12)

Add a sum of strings of elementary operators with the same name, but different site indices and coefficients.

Args:

exprstr

The names of elementary operators, such as “cdCD”.

arrlist[float|complex]

The list of coefficients.

idxlist[list[int]]

The list of operator indices.

cutofffloat

If the absolute value of any coefficient is below this threshold, the term will not be included. Default is 1E-12.

Returns:

selfExprBuilder

The ExprBuilder object.

iscale(d)

Scale the coefficients of all terms by a scalar factor.

Args:

dfloat or complex

The scalar factor.

Returns:

selfExprBuilder

The ExprBuilder object.

finalize(adjust_order=True, merge=True, is_drt=False, fermionic_ops=None)

Finalize the symbolic expression.

Args:

adjust_orderbool

If True, the order of operator indices will be automatically adjusted. This is normally required for MPO construction, unless the operator indices have already been sorted. Default is True.

mergebool

If True, will merge terms whenever possible. Default is True.

is_drtbool

If True, the DRT rule will be used. Only have effects in SU2 mode. Default is False.

fermionic_opsNone or str

If not None, the given set of operator names will be treated as Fermion operators (for computing signs for swapping operators). Default is None, and operators like “cdCD” will be treated as Fermion operators.

Returns:

gfdGeneralFCIDUMP

The block2 GeneralFCIDUMP object.

class pyblock2.driver.core.FermionTransform

Bases: object

Static methods for fermion to spin operator transforms.

static jordan_wigner(h1e, g2e)

Jordan-Wigner transform of quantum chemistry integrals.

class pyblock2.driver.core.OrbitalEntropy

Bases: object

Static methods for orbital entropy computations.

ops = ['1-n-N+nN', 'D-nD', 'd-Nd', 'Dd', 'C-nC', 'N-nN', 'Cd', '-Nd', 'c-Nc', 'Dc', 'n-nN', 'nD', 'Cc', '-Nc', 'nC', 'nN']

Entropy operators in SZ mode. See Table 4. in J. Chem. Theory Comput. 9, 2959-2973 (2013).

ops_ghf = ['1-N', 'D', 'C', 'N']

Entropy operators in SGF mode.

static parse_expr(x)

Internal method for paring entropy operator expressions.

static get_one_orb_rdm_h_terms(n_sites, is_sgf=False)

Internal method for computing symbolic terms in one-orbital RDM.

static get_two_orb_rdm_h_terms(n_sites, ij_symm=True, block_symm=True, is_sgf=False)

Internal method for computing symbolic terms in two-orbital RDM.

static get_one_orb_rdm_exprs(is_sgf=False)

Internal method for computing one-orbital RDM expressions (for NPDM engine).

static get_two_orb_rdm_exprs(is_sgf=False)

Internal method for computing two-orbital RDM expressions (for NPDM engine).

static get_two_orb_rdm_eigvals(ld, diag_only=False)

Internal method for solving eigenvalue problem for two-orbital RDM.

class pyblock2.driver.core.WickSpinAdaptation

Bases: object

Static methods for symbolic expression processing for normal ordering.

static spin_tag_to_pattern(x)

Internal method for transforming [1, 2, 2, 1] -> ((.+(.+.)0)1+.)0.

static adjust_spin_coupling(eq)

Internal method for the adjustment of spin coupling. Correct up to 4-body terms.

static get_eq_exprs(eq)

Internal method for transforming from symbolic equations to second quantized operator expressions that can be used in the SU2 mode.

class pyblock2.driver.core.SimilarityTransform

Bases: object

Static methods for DMRG with similarity transformed Hamiltonians.

static make_su2(h1e, g2e, ecore, t1, t2, scratch, n_elec, t3=None, ncore=0, ncas=-1, st_type=STTypes.H_HT_HT2T2, iprint=1)

Construct expression for the similarity transformed Hamiltonians in the SU2 mode.

static make_sz(h1e, g2e, ecore, t1, t2, scratch, n_elec, ncore=0, ncas=-1, st_type=STTypes.H_HT_HT2T2, iprint=1)

Construct expression for the similarity transformed Hamiltonians in the SZ mode.

static make_sgf(h1e, g2e, ecore, t1, t2, scratch, n_elec, t3=None, ncore=0, ncas=-1, st_type=STTypes.H_HT_HT2T2, iprint=1)

Construct expression for the similarity transformed Hamiltonians in the SGF mode.