VUMPSEngine

• full name: tenpy.algorithms.vumps.VUMPSEngine

• parent module: tenpy.algorithms.vumps

• type: class

Inheritance Diagram

Methods

VUMPSEngine.__init__(psi, model, options, ...)
VUMPSEngine.environment_sweeps(N_sweeps)	In VUMPS we don't want to do this as we regenerate the environment each time we do an update.
VUMPSEngine.estimate_RAM([mem_saving_factor])	Gives an approximate prediction for the required memory usage.
VUMPSEngine.free_no_longer_needed_envs()	Remove no longer needed environments after an update.
VUMPSEngine.get_resume_data([...])	Return necessary data to resume a run() interrupted at a checkpoint.
VUMPSEngine.get_sweep_schedule()	Sweep from site 0 to L-1
VUMPSEngine.init_env([model, resume_data, ...])	(Re-)initialize the environment.
VUMPSEngine.is_converged()	Determines if the algorithm is converged.
VUMPSEngine.make_eff_H()	Create new instance of self.EffectiveH at self.i0.
VUMPSEngine.mixer_activate()	Set self.mixer to the class specified by options['mixer'].
VUMPSEngine.mixer_cleanup()	For uniform MPS there is no need to clean up after the mixer.
VUMPSEngine.mixer_deactivate()	Deactivate the mixer.
VUMPSEngine.post_run_cleanup()	Perform any final steps or clean up after the main loop has terminated.
VUMPSEngine.post_update_local(e_L, e_R, ...)	Perform post-update actions.
VUMPSEngine.pre_run_initialize()	Perform preparations before run_iteration() is iterated.
VUMPSEngine.prepare_update_local()	For each update, we need to rebuild the environments from scratch using the most recent tensors
VUMPSEngine.reset_stats([resume_data])	Reset the statistics, useful if you want to start a new sweep run.
VUMPSEngine.resume_run()	Resume a run that was interrupted.
VUMPSEngine.run()	Run the VUMPS simulation to find the ground state.
VUMPSEngine.run_iteration()	Perform a single iteration, consisting of N_sweeps_check sweeps.
VUMPSEngine.status_update(iteration_start_time)	Emits a status message to the logging system after an iteration.
VUMPSEngine.stopping_criterion(...)	Determines if the main loop should be terminated.
VUMPSEngine.sweep([optimize])	One 'sweep' of a sweeper algorithm.
VUMPSEngine.switch_engine(other_engine, *[, ...])	Initialize algorithm from another algorithm instance of a different class.
VUMPSEngine.tangent_projector_test(env_data)	The ground state projector P_GS
VUMPSEngine.update_env(**update_data)	Update the left and right environments after an update of the state.
VUMPSEngine.update_local(theta, **kwargs)	Perform algorithm-specific local update.

Class Attributes and Properties

VUMPSEngine.DefaultMixer
VUMPSEngine.EffectiveH
VUMPSEngine.S_inv_cutoff
VUMPSEngine.n_optimize	The number of sites to be optimized at once.
VUMPSEngine.use_mixer_by_default

class tenpy.algorithms.vumps.VUMPSEngine(psi, model, options, **kwargs)

Bases: IterativeSweeps

VUMPS base class with common methods for the TwoSiteVUMPS and SingleSiteVUMPS.

This engine is implemented as a subclass of Sweep. It contains all methods that are generic between SingleSiteVUMPSEngine and TwoSiteVUMPSEngine. Use the latter two classes for actual VUMPS runs.

Options

config VUMPSEngine

option	summary
check_overlap in SingleSiteVUMPSEngine.post_run_cleanup	Since AL C = C AR is not identically true, the MPS defined by AL and AR are [...]
chi_list in SingleSiteVUMPSEngine.reset_stats	A dictionary to gradually increase the `chi_max` parameter of [...]
chi_list_reactivates_mixer (from Sweep) in IterativeSweeps.sweep	If True, the mixer is reset/reactivated each time the bond dimension growth [...]
combine (from Sweep) in Sweep	Whether to combine legs into pipes. This combines the virtual and [...]
cutoff in SingleSiteVUMPSEngine.run_iteration	During DMRG with a mixer, `S` may be a matrix for which we need the inverse [...]
diagonal_gauge_frequency in SingleSiteVUMPSEngine.run_iteration	Number of sweeps how often we restore the UniformMPS to the diagonal gauge
lanczos_params (from Sweep) in Sweep	Lanczos parameters as described in :cfg:config:`KrylovBased`.
max_E_err in SingleSiteVUMPSEngine.is_converged	Convergence if the change of the energy in each step [...]
max_hours (from IterativeSweeps) in DMRGEngine.stopping_criterion	If the DMRG took longer (measured in wall-clock time), [...]
max_N_sites_per_ring (from Algorithm) in Algorithm	Threshold for raising errors on too many sites per ring. Default ``18``. [...]
max_S_err in SingleSiteVUMPSEngine.is_converged	Convergence if the relative change of the entropy in each step [...]
max_split_err in SingleSiteVUMPSEngine.is_converged	Convergence if the norm error between AC=AL-C and AC=C_AR is [...]
max_sweeps (from IterativeSweeps) in DMRGEngine.stopping_criterion	Maximum number of sweeps to perform.
max_trunc_err (from IterativeSweeps) in IterativeSweeps	Threshold for raising errors on too large truncation errors. Default ``0.00 [...]
min_sweeps (from IterativeSweeps) in DMRGEngine.stopping_criterion	Minimum number of sweeps to perform.
mixer (from Sweep) in DMRGEngine.mixer_activate	Specifies which :class:`Mixer` to use, if any. [...]
mixer_params (from Sweep) in DMRGEngine.mixer_activate	Mixer parameters as described in :cfg:config:`Mixer`.
norm_tol in SingleSiteVUMPSEngine.post_run_cleanup	Check if final state is in canonical form.
start_env (from Sweep) in DMRGEngine.init_env	Number of sweeps to be performed without optimization to update the environment.
sweep_0 in SingleSiteVUMPSEngine.reset_stats	The number of sweeps already performed. (Useful for re-start).
trunc_params (from Algorithm) in Algorithm	Truncation parameters as described in :cfg:config:`truncation`.

EffectiveH

Class for the effective Hamiltonian, i.e., a subclass of EffectiveH. Has a length class attribute which specifies the number of sites updated at once (e.g., whether we do single-site vs. two-site VUMPS).

Type:

class type

chi_list

See DMRGEngine.chi_list

Type:

dict | None

eff_H

Effective single-site or two-site Hamiltonian.

Type:

EffectiveH

shelve

If a simulation runs out of time (time.time() - start_time > max_seconds), the run will terminate with shelve = True.

Type:

bool

sweeps

The number of sweeps already performed. (Useful for re-start).

Type:

int

time0

Time marker for the start of the run.

Type:

float

update_stats

A dictionary with detailed statistics of the convergence at local update-level. For each key in the following table, the dictionary contains a list where one value is added each time VUMPSEngine.update_bond() is called.

key	description
i0	An update was performed on sites i0, i0+1.
e_L	Energy from left transfer matrix.
e_R	Energy from right transfer matrix.
e_C1	Energy from the left center matrix.
e_C2	Energy from the right center matrix.
e_theta	Energy from the single-site or two-site wave function.
N_lanczos	Dimension of the Krylov space used in the lanczos diagonalization.
split_err_L	Error between AC_i and AL_i C_{i+1}
split_err_R	Error between AC_i and C_i AR_i
time	Wallclock time evolved since time0 (in seconds).

Type:

dict

sweep_stats

A dictionary with detailed statistics at the sweep level. For each key in the following table, the dictionary contains a list where one value is added each time VUMPSEngine.sweep() is called (with optimize=True).

key	description
sweep	Number of sweeps (excluding environment sweeps) performed so far.
N_updates	Number of updates (including environment sweeps) performed so far.
E	The energy obtained from the contracted environments.
Delta_E	The change in E (above) since the last iteration.
S	Mean entanglement entropy (over bonds).
Delta_S	The change in S (above) since the last iteration.
max_S	Max entanglement entropy (over bonds).
time	Wallclock time evolved since time0 (in seconds).
max_split_err	The maximum split error in the last sweep.
max_N_lanczos	Maximum number of used Lanczos vectors in last sweep.
max_chi	Maximum bond dimension used.
norm_err	Error of canonical form np.linalg.norm(psi.norm_test()).

Type:

dict

_entropy_approx

While the mixer is on, the S stored in the MPS is a non-diagonal 2D array. To check convergence, we use the approximate singular values based on which we truncated instead to calculate the entanglement entropy and store it inside this list.

Type:

list of {None, 1D array}

run_iteration()

Perform a single iteration, consisting of N_sweeps_check sweeps.

Options

option VUMPSEngine.diagonal_gauge_frequency: int

Number of sweeps how often we restore the UniformMPS to the diagonal gauge

option VUMPSEngine.cutoff: float

During DMRG with a mixer, S may be a matrix for which we need the inverse. This is calculated as the Penrose pseudo-inverse, which uses a cutoff for the singular values.

Returns:

• E (float) – The energy of the current ground state approximation.

• psi (UniformMPS) – The current ground state approximation, i.e. just a reference to psi.

status_update(iteration_start_time: float)

Emits a status message to the logging system after an iteration.

Parameters:

iteration_start_time (float) – The time.time() at the start of the last iteration

is_converged()

Determines if the algorithm is converged.

Does not cover any other reasons to abort, such as reaching a time limit. Such checks are covered by stopping_condition().

Options

option VUMPSEngine.max_E_err: float

Convergence if the change of the energy in each step satisfies |Delta E / max(E, 1)| < max_E_err. Note that this might be satisfied even if Delta E > 0, i.e., if the energy increases (due to truncation).

option VUMPSEngine.max_S_err: float

Convergence if the relative change of the entropy in each step satisfies |Delta S|/S < max_S_err

option VUMPSEngine.max_split_err: float

Convergence if the norm error between AC=AL-C and AC=C_AR is smaller than max_split_err.

post_run_cleanup()

Perform any final steps or clean up after the main loop has terminated. Try to convert uniform MPS back to iMPS.

Options

option VUMPSEngine.check_overlap: bool

Since AL C = C AR is not identically true, the MPS defined by AL and AR are not exactly the same. We can compute the overlap of the two to check.

option VUMPSEngine.norm_tol: float

Check if final state is in canonical form.

mixer_cleanup()

For uniform MPS there is no need to clean up after the mixer.

run()

Run the VUMPS simulation to find the ground state.

Returns:

• E (float) – The energy of the resulting ground state MPS.

• psi (MPS) – The MPS representing the ground state after the simulation, i.e. just a reference to psi.

environment_sweeps(N_sweeps)

In VUMPS we don’t want to do this as we regenerate the environment each time we do an update.

reset_stats(resume_data=None)

Reset the statistics, useful if you want to start a new sweep run.

option VUMPSEngine.chi_list: dict | None

A dictionary to gradually increase the chi_max parameter of trunc_params. The key defines starting from which sweep chi_max is set to the value, e.g. {0: 50, 20: 100} uses chi_max=50 for the first 20 sweeps and chi_max=100 afterwards. Overwrites trunc_params[‘chi_list’]`. By default (None) this feature is disabled.

option VUMPSEngine.sweep_0: int

The number of sweeps already performed. (Useful for re-start).

get_sweep_schedule()

Sweep from site 0 to L-1

prepare_update_local()

For each update, we need to rebuild the environments from scratch using the most recent tensors

make_eff_H()

Create new instance of self.EffectiveH at self.i0. Also create zero-site Hamiltonians left of self.i0 and right of self.i0+self.n_optimize.

post_update_local(e_L, e_R, eps_L, eps_R, e_C1, e_C2, e_theta, N0_L, N0_R, N1, **update_data)

Perform post-update actions.

Collect statistics.

Parameters:

**update_data (dict) – What was returned by update_local().

free_no_longer_needed_envs()

Remove no longer needed environments after an update.

This allows to minimize the number of environments to be kept. For large MPO bond dimensions, these environments are by far the biggest part in memory, so this is a valuable optimization to reduce memory requirements.

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().

tangent_projector_test(env_data)

The ground state projector P_GS

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

init_env(model=None, resume_data=None, orthogonal_to=None)

(Re-)initialize the environment.

This function is useful to (re-)start a Sweep with a slightly different model or different (engine) parameters. Note that we assume that we still have the same psi. Calls reset_stats().

Parameters:

• model (MPOModel) – The model representing the Hamiltonian for which we want to find the ground state. If None, keep the model used before.

• resume_data (None | dict) – Given when resuming a simulation, as returned by get_resume_data(). Can contain another dict under the key init_env_data; the contents of init_env_data get passed as keyword arguments to the environment initialization.

• orthogonal_to (None | list of MPS | list of dict) – List of other matrix product states to orthogonalize against. Instead of just the state, you can specify a dict with the state as ket and further keyword arguments for initializing the MPSEnvironment; the psi to be optimized is used as bra. Works only for finite or segment MPS; for infinite MPS it must be None. This can be used to find (a few) excited states as follows. First, run DMRG to find the ground state, and then run DMRG again while orthogonalizing against the ground state, which yields the first excited state (in the same symmetry sector), and so on. Note that resume_data['orthogonal_to'] takes precedence over the argument.

Options

option Sweep.start_env: int

Number of sweeps to be performed without optimization to update the environment.

Raises:

ValueError – If the engine is re-initialized with a new model, which legs are incompatible with those of hte old model.

mixer_activate()

Set self.mixer to the class specified by options[‘mixer’].

option Sweep.mixer: str | class | bool | None

Specifies which Mixer to use, if any. A string stands for one of the mixers defined in this module. A class is assumed to have the same interface as Mixer and is used to instantiate the mixer. None uses no mixer. True uses the mixer specified by the DefaultMixer class attribute. The default depends on the subclass of Sweep.

option Sweep.mixer_params: dict

Mixer parameters as described in Mixer.

See also

mixer_deactivate

mixer_deactivate()

Deactivate the mixer.

Set self.mixer=None and revert any other effects of mixer_activate().

property n_optimize

The number of sites to be optimized at once.

Indirectly set by the class attribute EffectiveH and it’s length. For example, TwoSiteDMRGEngine uses the TwoSiteH and hence has n_optimize=2, while the SingleSiteDMRGEngine has n_optimize=1.

pre_run_initialize()

Perform preparations before run_iteration() is iterated.

Returns:

The object to be returned by run() in case of immediate convergence, i.e. if no iterations are performed.

Return type:

result

stopping_criterion(iteration_start_time: float) → bool

Determines if the main loop should be terminated.

Parameters:

iteration_start_time (float) – The time.time() at the start of the last iteration

Options

option IterativeSweeps.min_sweeps: int

Minimum number of sweeps to perform.

option IterativeSweeps.max_sweeps: int

Maximum number of sweeps to perform.

option IterativeSweeps.max_hours: float

If the DMRG took longer (measured in wall-clock time), ‘shelve’ the simulation, i.e. stop and return with the flag shelve=True.

Returns:

should_break – If True, the main loop in run() is broken.

Return type:

bool

sweep(optimize=True)

One ‘sweep’ of a sweeper algorithm.

Iterate over the bond which is optimized, to the right and then back to the left to the starting point.

Parameters:

optimize (bool, optional) – Whether we actually optimize the state, e.g. to find the ground state of the effective Hamiltonian in case of a DMRG. (If False, just update the environments).

Options

option Sweep.chi_list_reactivates_mixer: bool

If True, the mixer is reset/reactivated each time the bond dimension growths due to Sweep.chi_list.

Returns:

max_trunc_err – Maximal truncation error introduced.

Return type:

float

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().

update_env(**update_data)

Update the left and right environments after an update of the state.

Parameters:

**update_data – Whatever is returned by update_local().

update_local(theta, **kwargs)

Perform algorithm-specific local update.

For two-site algorithms with n_optimize = 2, this always optimizes the sites i0 and i0 + 1. For single-site algorithms, the effective H only acts on site i0, but afterwards it also updates the bond to the right if move_right is True, or the bond to the left if move_right is False. Since the svd for truncation gives tensors to be multiplied into the tensors on both sides of the bond, tensors of two sites are updated even for single-site algorithms: when right-moving, site i0 + 1 is also updated; site i0 - 1 when left-moving.

Parameters:

theta (Array) – Local single- or two-site wave function, as returned by prepare_update_local().

Returns:

update_data – Data to be processed by update_env() and post_update_local(), e.g. containing the truncation error as err. If combine is set, it should also contain the U and VH from the SVD.

Return type:

dict