MultiSitePlaneWaveExcitationEngine

• full name: tenpy.algorithms.plane_wave_excitation.MultiSitePlaneWaveExcitationEngine

• parent module: tenpy.algorithms.plane_wave_excitation

• type: class

Inheritance Diagram

Methods

MultiSitePlaneWaveExcitationEngine.__init__(...)
MultiSitePlaneWaveExcitationEngine.attach_left(VL, ...)	attach excitation tensors to a left environment
MultiSitePlaneWaveExcitationEngine.attach_right(VL, ...)	attach excitation tensors to a right environment
MultiSitePlaneWaveExcitationEngine.energy(p, X)	Compute the energy of excited states
MultiSitePlaneWaveExcitationEngine.estimate_RAM([...])	Gives an approximate prediction for the required memory usage.
MultiSitePlaneWaveExcitationEngine.get_resume_data([...])	Return necessary data to resume a run() interrupted at a checkpoint.
MultiSitePlaneWaveExcitationEngine.infinite_sum_left(p, X)	Infinite sum to the left, see Eq.
MultiSitePlaneWaveExcitationEngine.infinite_sum_right(p, X)	Infinite sum to the right, see Eq.
MultiSitePlaneWaveExcitationEngine.initial_guess(...)	Initial guess for the X tensors within a fixed charge sector.
MultiSitePlaneWaveExcitationEngine.resume_run()	Resume a run that was interrupted.
MultiSitePlaneWaveExcitationEngine.run(p[, ...])	Run the plane-wave algorithm to find excited states of the given model.
MultiSitePlaneWaveExcitationEngine.switch_engine(...)	Initialize algorithm from another algorithm instance of a different class.

class tenpy.algorithms.plane_wave_excitation.MultiSitePlaneWaveExcitationEngine(psi, model, options, **kwargs)

Bases: Algorithm

Engine to compute quasiparticle excitations across multiple sites for uniform MPS. For each site in the unit cell one multi-site excitation tensor is computed.

Parameters are the same as for Algorithm.

Options

config MultiSitePlaneWaveExcitationEngine

option	summary
excitation_size	Number of sites of the excitation, i.e. how many sites in the uniform MPS a [...]
init_env_data	Dictionary as returned by ``self.env.get_initialization_data()`` from [...]
lambda_C1	Energy shift from contracting the infinite environments. If `None`, compute [...]
lanczos_params	Lanczos parameters as described in :cfg:config:`KrylovBased`.
max_N_sites_per_ring (from Algorithm) in Algorithm	Threshold for raising errors on too many sites per ring. Default ``18``. [...]
trunc_params (from Algorithm) in Algorithm	Truncation parameters as described in :cfg:config:`truncation`.

option lanczos_params: dict

Lanczos parameters as described in KrylovBased.

option lambda_C1: float

Energy shift from contracting the infinite environments. If None, compute it again.

option init_env_data: dict

Dictionary as returned by self.env.get_initialization_data() from get_initialization_data().

option excitation_size: int

Number of sites of the excitation, i.e. how many sites in the uniform MPS are replaced with orthogonal tensors. This can be larger than the unit cell or incommensurate.

psi

The uniform MPS for which we compute (orthogonal) excitations.

Type:

UniformMPS

model

The model defining the Hamiltonian.

Type:

MPOModel

ACs

The ‘center-site’ tensors of psi.

Type:

list of Array

ALs

The ‘left-orthonormal’ tensors of psi.

Type:

list of Array

AR

The ‘right-orthonormal’ tensors of psi.

Type:

list of Array

Cs

The center matrices of psi.

Type:

list of Array

Ws

The matrices of the MPO.

Type:

list of Array

VLs

The orthogonal complements for each AL.

Type:

list of Array

run(p, qtotal_change=None, orthogonal_to=[], E_boosts=[], num_ev=1)

Run the plane-wave algorithm to find excited states of the given model.

Parameters:

• p (float) – The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

• qtotal_change (list of int) – Charge sectors for each of the defined charges.

• orthogonal_to (list of list of Array) – Find excitations orthogonal to previously found tensors X.

• E_boosts (list of float) – energy boosts for orthogonal states

• num_ev (int) – Number of eigenvalues and eigenvectors, that we extract from a single Arnoldi/ Lanczos run

Returns:

• Es (list of float) – Energies of the lowest-energy excitations. Number equal to num_ev.

• psis (list of MomentumMPS) – MomentumMPS corresponding to the lowest-energy excitations. Number equal to num_ev.

Options

config PlaneWaveExcitationEngine

option	summary
E_boost	uniform strength of the energy boosts (instead of specifying a list), defau [...]
init_env_data in PlaneWaveExcitationEngine	Dictionary as returned by ``self.env.get_initialization_data()`` from [...]
lambda_C1 in PlaneWaveExcitationEngine	Energy shift from contracting the infinite environments. If `None`, compute [...]
lanczos_params in PlaneWaveExcitationEngine	Lanczos parameters as described in :cfg:config:`KrylovBased`.
max_N_sites_per_ring (from Algorithm) in Algorithm	Threshold for raising errors on too many sites per ring. Default ``18``. [...]
sum_iterations in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Maximum number of iterations for the explicit summation (default sum_iterat [...]
sum_method in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Whether to explicitly sum the environment by applying the unit cell tensors [...]
sum_tol in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Convergence criterion for the explicit summation.
trunc_params (from Algorithm) in Algorithm	Truncation parameters as described in :cfg:config:`truncation`.

option E_boost: float

uniform strength of the energy boosts (instead of specifying a list), default to E_boost=100

resume_run()

Resume a run that was interrupted.

In case we saved an intermediate result at a checkpoint, this function allows to resume the run() of the algorithm (after re-initialization with the resume_data). Since most algorithms just have a while loop with break conditions, the default behavior implemented here is to just call run().

energy(p, X)

Compute the energy of excited states

Parameters:

• p (float) – The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

• X (list of Array) – Excitation tensors for each site of the unit cell.

Returns:

energy – Energy

Return type:

float

attach_right(VL, X, As, R, Ws=None)

attach excitation tensors to a right environment

infinite_sum_right(p, X)

Infinite sum to the right, see Eq. (194) in [vanderstraeten2019]

pfloat

The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

Xlist of Array

Current excitation tensors for each site of the unit cell.

Returns:

R_sum – Array representing the right environment including the B tensors at each site.

Return type:

Array

Options

config PlaneWaveExcitationEngine

option	summary
E_boost in MultiSitePlaneWaveExcitationEngine.run	uniform strength of the energy boosts (instead of specifying a list), defau [...]
init_env_data in PlaneWaveExcitationEngine	Dictionary as returned by ``self.env.get_initialization_data()`` from [...]
lambda_C1 in PlaneWaveExcitationEngine	Energy shift from contracting the infinite environments. If `None`, compute [...]
lanczos_params in PlaneWaveExcitationEngine	Lanczos parameters as described in :cfg:config:`KrylovBased`.
max_N_sites_per_ring (from Algorithm) in Algorithm	Threshold for raising errors on too many sites per ring. Default ``18``. [...]
sum_iterations	Maximum number of iterations for the explicit summation (default sum_iterat [...]
sum_method	Whether to explicitly sum the environment by applying the unit cell tensors [...]
sum_tol	Convergence criterion for the explicit summation.
trunc_params (from Algorithm) in Algorithm	Truncation parameters as described in :cfg:config:`truncation`.

option sum_method: explicit | GMRES

Whether to explicitly sum the environment by applying the unit cell tensors until convergence (default) or solving the geometric series with the GMRES method.

option sum_tol: float

Convergence criterion for the explicit summation.

option sum_iterations: int

Maximum number of iterations for the explicit summation (default sum_iterations=100).

attach_left(VL, X, As, L, Ws=None)

attach excitation tensors to a left environment

infinite_sum_left(p, X)

Infinite sum to the left, see Eq. (194) in [vanderstraeten2019]

pfloat

The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

Xlist of Array

Current excitation tensors for each site of the unit cell.

Returns:

L_sum – Array representing the left environment including the B tensors at each site.

Return type:

Array

Options

config PlaneWaveExcitationEngine

option	summary
E_boost in MultiSitePlaneWaveExcitationEngine.run	uniform strength of the energy boosts (instead of specifying a list), defau [...]
init_env_data in PlaneWaveExcitationEngine	Dictionary as returned by ``self.env.get_initialization_data()`` from [...]
lambda_C1 in PlaneWaveExcitationEngine	Energy shift from contracting the infinite environments. If `None`, compute [...]
lanczos_params in PlaneWaveExcitationEngine	Lanczos parameters as described in :cfg:config:`KrylovBased`.
max_N_sites_per_ring (from Algorithm) in Algorithm	Threshold for raising errors on too many sites per ring. Default ``18``. [...]
sum_iterations in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Maximum number of iterations for the explicit summation (default sum_iterat [...]
sum_method in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Whether to explicitly sum the environment by applying the unit cell tensors [...]
sum_tol in MultiSitePlaneWaveExcitationEngine.infinite_sum_right	Convergence criterion for the explicit summation.
trunc_params (from Algorithm) in Algorithm	Truncation parameters as described in :cfg:config:`truncation`.

option sum_method: explicit | GMRES

Whether to explicitly sum the environment by applying the unit cell tensors until convergence (default) or solving the geometric series with the GMRES method.

option sum_tol: float

Convergence criterion for the explicit summation.

option sum_iterations: int

Maximum number of iterations for the explicit summation (default sum_iterations=100).

class Aligned_Effective_H(outer, p)

Bases: NpcLinearOperator

Class defining the effective Hamiltonian for the multi-site excitation tensors X, where there is overlap between B tensors and the unit cell we want to update.

Parameters:

• outer (PlaneWaveExcitationEngine) – Parent engine for the plane wave excitation ansatz.

• p (float) – The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

matvec(vec)

Calculate the action of the operator on a vector vec.

Note that we don’t require vec to be one-dimensional. However, for square operators we require that the result of matvec has the same legs (in the same order) as vec such that they can be added. Note that this excludes a non-trivial qtotal for square operators.

adjoint()

Return the hermitian conjugate of self

If self is hermitian, subclasses can choose to implement this to define the adjoint operator of self.

to_matrix()

Contract self to a matrix.

If self represents an operator with very small shape, e.g. because the MPS bond dimension is very small, an algorithm might choose to contract self to a single tensor.

Returns:

matrix – Contraction of the represented operator.

Return type:

Array

class Unaligned_Effective_H(outer, p)

Bases: NpcLinearOperator

Class defining the effective Hamiltonian for the multi-site excitation tensors X, where the B tensors are in left (LB) or right (RB) environment.

Parameters:

• outer (PlaneWaveExcitationEngine) – Parent engine for the plane wave excitation ansatz.

• p (float) – The momentum of the state; for unit cells larger than 1, we already include the factor of the smaller Brillouin zone: p*L.

adjoint()

Return the hermitian conjugate of self

If self is hermitian, subclasses can choose to implement this to define the adjoint operator of self.

to_matrix()

Contract self to a matrix.

If self represents an operator with very small shape, e.g. because the MPS bond dimension is very small, an algorithm might choose to contract self to a single tensor.

Returns:

matrix – Contraction of the represented operator.

Return type:

Array

matvec(vec)

Calculate the action of the operator on a vector vec.

Note that we don’t require vec to be one-dimensional. However, for square operators we require that the result of matvec has the same legs (in the same order) as vec such that they can be added. Note that this excludes a non-trivial qtotal for square operators.

estimate_RAM(mem_saving_factor=None)

Gives an approximate prediction for the required memory usage.

This calculation is based on the requested bond dimension, the local Hilbert space dimension, the number of sites, and the boundary conditions.

Parameters:

mem_saving_factor (float) – Represents the amount of RAM saved due to conservation laws. By default, it is ‘None’ and is extracted from the model automatically. However, this is only possible in a few cases and needs to be estimated in most cases. This is due to the fact that it is dependent on the model parameters. If one has a better estimate, one can pass the value directly. This value can be extracted by building the initial state psi (usually by performing DMRG) and then calling print(psi.get_B(0).sparse_stats()) TeNPy will automatically print the fraction of nonzero entries in the first line, for example, 6 of 16 entries (=0.375) nonzero. This fraction corresponds to the mem_saving_factor; in our example, it is 0.375.

Returns:

usage – Required RAM in MB.

Return type:

float

See also

tenpy.simulations.simulation.estimate_simulation_RAM

global function calling this.

get_resume_data(sequential_simulations=False)

Return necessary data to resume a run() interrupted at a checkpoint.

At a checkpoint, you can save psi, model and options along with the data returned by this function. When the simulation aborts, you can resume it using this saved data with:

eng = AlgorithmClass(psi, model, options, resume_data=resume_data)
eng.resume_run()

An algorithm which doesn’t support this should override resume_run to raise an Error.

Parameters:

sequential_simulations (bool) – If True, return only the data for re-initializing a sequential simulation run, where we “adiabatically” follow the evolution of a ground state (for variational algorithms), or do series of quenches (for time evolution algorithms); see run_seq_simulations().

Returns:

resume_data – Dictionary with necessary data (apart from copies of psi, model, options) that allows to continue the algorithm run from where we are now. It might contain an explicit copy of psi.

Return type:

dict

classmethod switch_engine(other_engine, *, options=None, **kwargs)

Initialize algorithm from another algorithm instance of a different class.

You can initialize one engine from another, not too different subclasses. Internally, this function calls get_resume_data() to extract data from the other_engine and then initializes the new class.

Note that it transfers the data without making copies in most case; even the options! Thus, when you call run() on one of the two algorithm instances, it will modify the state, environment, etc. in the other. We recommend to make the switch as engine = OtherSubClass.switch_engine(engine) directly replacing the reference.

Parameters:

• cls (class) – Subclass of Algorithm to be initialized.

• other_engine (Algorithm) – The engine from which data should be transferred. Another, but not too different algorithm subclass-class; e.g. you can switch from the TwoSiteDMRGEngine to the OneSiteDMRGEngine.

• options (None | dict-like) – If not None, these options are used for the new initialization. If None, take the options from the other_engine.

• **kwargs – Further keyword arguments for class initialization. If not defined, resume_data is collected with get_resume_data().

initial_guess(qtotal_change)

Initial guess for the X tensors within a fixed charge sector.

Parameters:

qtotal_change (list of int) – For each charge sector specify how X should change the charge.

Returns:

X_init – Initial guess for excitation tensors for each site of the unit cell.

Return type:

list of Array