DMRGEngine¶

full name: tenpy.algorithms.dmrg.DMRGEngine
parent module: tenpy.algorithms.dmrg
type: class

Inheritance Diagram

Methods

`DMRGEngine.__init__`(psi, model, options, …)	Initialize self.
`DMRGEngine.diag`(theta_guess)	Diagonalize the effective Hamiltonian represented by self.
`DMRGEngine.environment_sweeps`(N_sweeps)	Perform N_sweeps sweeps without optimization to update the environment.
`DMRGEngine.get_resume_data`()	Return necessary data to resume a `run()` interrupted at a checkpoint.
`DMRGEngine.get_sweep_schedule`()	Define the schedule of the sweep.
`DMRGEngine.init_env`([model, resume_data])	(Re-)initialize the environment.
`DMRGEngine.make_eff_H`()	Create new instance of self.EffectiveH at self.i0 and set it to self.eff_H.
`DMRGEngine.mixer_activate`()	Set self.mixer to the class specified by options[‘mixer’].
`DMRGEngine.mixer_cleanup`()	Cleanup the effects of a mixer.
`DMRGEngine.plot_sweep_stats`([axes, xaxis, …])	Plot `sweep_stats` to display the convergence with the sweeps.
`DMRGEngine.plot_update_stats`(axes[, xaxis, …])	Plot `update_stats` to display the convergence during the sweeps.
`DMRGEngine.post_update_local`(update_data)	Perform post-update actions.
`DMRGEngine.prepare_update`()	Prepare self for calling `update_local()` on sites `i0 : i0+n_optimize`.
`DMRGEngine.reset_stats`([resume_data])	Reset the statistics, useful if you want to start a new sweep run.
`DMRGEngine.resume_run`()	Resume a run that was interrupted.
`DMRGEngine.run`()	Run the DMRG simulation to find the ground state.
`DMRGEngine.sweep`([optimize, meas_E_trunc])	One ‘sweep’ of a the algorithm.
`DMRGEngine.update_LP`(_)
`DMRGEngine.update_RP`(_)
`DMRGEngine.update_local`(theta[, optimize])	Perform site-update on the site `i0`.

Class Attributes and Properties

`DMRGEngine.DMRG_params`
`DMRGEngine.DefaultMixer`
`DMRGEngine.EffectiveH`
`DMRGEngine.engine_params`
`DMRGEngine.n_optimize`	the number of sites to be optimized over at once.
`DMRGEngine.verbose`

class tenpy.algorithms.dmrg.DMRGEngine(psi, model, options, **kwargs)[source]¶

Bases: tenpy.algorithms.mps_common.Sweep

DMRG base class with common methods for the TwoSiteDMRG and SingleSiteDMRG.

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

A generic protocol for approaching a physics question using DMRG is given in /intro/protocol.

Deprecated since version 0.5.0: Renamed parameter/attribute DMRG_params to options.

Options

config DMRGEngine¶

option	summary
chi_list in DMRGEngine.reset_stats	A dictionary to gradually increase the `chi_max` parameter of [...]
combine (from Sweep) in Sweep	Whether to combine legs into pipes. This combines the virtual and [...]
diag_method in DMRGEngine.run	Method to be used for diagonalzation, default ``'default'``. [...]
E_tol_max in DMRGEngine.run	See `E_tol_to_trunc`
E_tol_min in DMRGEngine.run	See `E_tol_to_trunc`
E_tol_to_trunc in DMRGEngine.run	It's reasonable to choose the Lanczos convergence criteria [...]
init_env_data (from Sweep) in DMRGEngine.init_env	Dictionary as returned by ``self.env.get_initialization_data()`` from [...]
lanczos_params (from Sweep) in Sweep	Lanczos parameters as described in :cfg:config:`Lanczos`.
max_E_err in DMRGEngine.run	Convergence if the change of the energy in each step [...]
max_hours in DMRGEngine.run	If the DMRG took longer (measured in wall-clock time), [...]
max_N_for_ED in DMRGEngine.diag	Maximum matrix dimension of the effective hamiltonian [...]
max_S_err in DMRGEngine.run	Convergence if the relative change of the entropy in each step [...]
max_sweeps in DMRGEngine.run	Maximum number of sweeps to be performed.
min_sweeps in DMRGEngine.run	Minimum number of sweeps to be performed. [...]
N_sweeps_check in DMRGEngine.run	Number of sweeps to perform between checking convergence [...]
norm_tol in DMRGEngine.run	After the DMRG run, update the environment with at most [...]
norm_tol_iter in DMRGEngine.run	Perform at most `norm_tol_iter`*`update_env` sweeps to [...]
orthogonal_to (from Sweep) in DMRGEngine.init_env	List of other matrix product states to orthogonalize against. [...]
P_tol_max in DMRGEngine.run	See `P_tol_to_trunc`
P_tol_min in DMRGEngine.run	See `P_tol_to_trunc`
P_tol_to_trunc in DMRGEngine.run	It's reasonable to choose the Lanczos convergence criteria [...]
start_env (from Sweep) in DMRGEngine.init_env	Number of sweeps to be performed without optimization to update [...]
sweep_0 in DMRGEngine.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`.
update_env in DMRGEngine.run	Number of sweeps without bond optimizaiton to update the [...]

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

Type: class type

chi_list¶

See DMRGEngine.chi_list

Type: dict | None

eff_H¶

Effective two-site Hamiltonian.

Type: EffectiveH

mixer¶

If None, no mixer is used (anymore), otherwise the mixer instance.

Type: Mixer | None

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 DMRGEngine.update_bond() is called.

key	description
i0	An update was performed on sites `i0, i0+1`.
age	The number of physical sites involved in the simulation.
E_total	The total energy before truncation.
N_lanczos	Dimension of the Krylov space used in the lanczos diagonalization.
time	Wallclock time evolved since `time0` (in seconds).
ov_change	`1. - abs(<theta_guess\|theta_diag>)`, where `\|theta_guess>` is the initial guess for the wave function and `\|theta_diag>` is the untruncated wave function returned by `diag()`.

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 Engine.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 before truncation (as calculated by Lanczos).
S	Maximum entanglement entropy.
time	Wallclock time evolved since `time0` (in seconds).
max_trunc_err	The maximum truncation error in the last sweep
max_E_trunc	Maximum change or Energy due to truncation in the last sweep.
max_chi	Maximum bond dimension used.
norm_err	Error of canonical form `np.linalg.norm(psi.norm_test())`.

Type: dict

run()[source]¶

Run the DMRG 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 simluation, i.e. just a reference to psi.

Options

option DMRGEngine.diag_method: str¶: Method to be used for diagonalzation, default 'default'. For possible arguments see DMRGEngine.diag().

option DMRGEngine.E_tol_to_trunc: float¶: It’s reasonable to choose the Lanczos convergence criteria 'E_tol' not many magnitudes lower than the current truncation error. Therefore, if E_tol_to_trunc is not None, we update E_tol of lanczos_params to max_E_trunc*E_tol_to_trunc, restricted to the interval [E_tol_min, E_tol_max], where max_E_trunc is the maximal energy difference due to truncation right after each Lanczos optimization during the sweeps.

option DMRGEngine.E_tol_max: float¶: See E_tol_to_trunc

option DMRGEngine.E_tol_min: float¶: See E_tol_to_trunc

option DMRGEngine.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 is also satisfied if Delta E > 0, i.e., if the energy increases (due to truncation).

option DMRGEngine.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.

option DMRGEngine.max_S_err: float¶: Convergence if the relative change of the entropy in each step satisfies |Delta S|/S < max_S_err

option DMRGEngine.max_sweeps: int¶: Maximum number of sweeps to be performed.

option DMRGEngine.min_sweeps: int¶: Minimum number of sweeps to be performed. Defaults to 1.5*N_sweeps_check.

option DMRGEngine.N_sweeps_check: int¶: Number of sweeps to perform between checking convergence criteria and giving a status update.

option DMRGEngine.norm_tol: float¶: After the DMRG run, update the environment with at most norm_tol_iter sweeps until np.linalg.norm(psi.norm_err()) < norm_tol.

option DMRGEngine.norm_tol_iter: float¶: Perform at most norm_tol_iter`*`update_env sweeps to converge the norm error below norm_tol. If the state is not converged after that, call canonical_form() instead.

option DMRGEngine.P_tol_to_trunc: float¶: It’s reasonable to choose the Lanczos convergence criteria 'P_tol' not many magnitudes lower than the current truncation error. Therefore, if P_tol_to_trunc is not None, we update P_tol of lanczos_params to max_trunc_err*P_tol_to_trunc, restricted to the interval [P_tol_min, P_tol_max], where max_trunc_err is the maximal truncation error (discarded weight of the Schmidt values) due to truncation right after each Lanczos optimization during the sweeps.

option DMRGEngine.P_tol_max: float¶: See P_tol_to_trunc

option DMRGEngine.P_tol_min: float¶: See P_tol_to_trunc

option DMRGEngine.update_env: int¶: Number of sweeps without bond optimizaiton to update the environment for infinite boundary conditions, performed every N_sweeps_check sweeps.

reset_stats(resume_data=None)[source]¶

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

option DMRGEngine.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 DMRGEngine.sweep_0: int¶: The number of sweeps already performed. (Useful for re-start).

sweep(optimize=True, meas_E_trunc=False)[source]¶

One ‘sweep’ of a the algorithm.

Iteratate 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 to find the ground state of the effective Hamiltonian. (If False, just update the environments).
meas_E_trunc (bool, optional) – Whether to measure truncation energies.

Returns

max_trunc_err (float) – Maximal truncation error introduced.
max_E_trunc (None | float) – None if meas_E_trunc is False, else the maximal change of the energy due to the truncation.

prepare_update()[source]¶

Prepare self for calling update_local() on sites i0 : i0+n_optimize.

Returns: theta – Current best guess for the ground state, which is to be optimized. Labels are 'vL', 'p0', 'p1', 'vR', or combined versions of it (if self.combine). For single-site DMRG, the 'p1' label is missing.
Return type: Array

update_local(theta, optimize=True)[source]¶

Perform site-update on the site i0.

Parameters

theta (Array) – Initial guess for the ground state of the effective Hamiltonian.
optimize (bool) – Wheter we actually optimize to find the ground state of the effective Hamiltonian. (If False, just update the environments).

Returns

update_data – Data computed during the local update, as described in the following:

E0float: Total energy, obtained before truncation (if optimize=True), or after truncation (if optimize=False) (but never None).
Nint: Dimension of the Krylov space used for optimization in the lanczos algorithm. 0 if optimize=False.
ageint: Current size of the DMRG simulation: number of physical sites involved into the contraction.
U, VH: Array: U and VH returned by mixed_svd().
ov_change: float: Change in the wave function 1. - abs(<theta_guess|theta>) induced by diag(), not including the truncation!

Return type

dict

post_update_local(update_data)[source]¶

Perform post-update actions.

Compute truncation energy, remove LP/RP that are no longer needed and collect statistics.

Parameters: update_data (dict) – What was returned by update_local().

diag(theta_guess)[source]¶

Diagonalize the effective Hamiltonian represented by self.

option DMRGEngine.max_N_for_ED: int¶: Maximum matrix dimension of the effective hamiltonian up to which the 'default' diag_method uses ED instead of Lanczos.

option DMRGEngine.diag_method: str¶

One of the folloing strings:

‘default’: Same as 'lanczos' for large bond dimensions, but if the total dimension of the effective Hamiltonian does not exceed the DMRG parameter 'max_N_for_ED' it uses 'ED_block'.
‘lanczos’: lanczos() Default, the Lanczos implementation in TeNPy.
‘arpack’: lanczos_arpack() Based on scipy.linalg.sparse.eigsh(). Slower than ‘lanczos’, since it needs to convert the npc arrays to numpy arrays during each matvec, and possibly does many more iterations.
‘ED_block’: full_diag_effH() Contract the effective Hamiltonian to a (large!) matrix and diagonalize the block in the charge sector of the initial state. Preserves the charge sector of the explicitly conserved charges. However, if you don’t preserve a charge explicitly, it can break it. For example if you use a SpinChain({'conserve': 'parity'}), it could change the total “Sz”, but not the parity of ‘Sz’.
‘ED_all’: full_diag_effH() Contract the effective Hamiltonian to a (large!) matrix and diagonalize it completely. Allows to change the charge sector even for explicitly conserved charges. For example if you use a SpinChain({'conserve': 'Sz'}), it can change the total “Sz”.

Parameters

theta_guess (Array) – Initial guess for the ground state of the effective Hamiltonian.

Returns

E0 (float) – Energy of the found ground state.
theta (Array) – Ground state of the effective Hamiltonian.
N (int) – Number of Lanczos iterations used. -1 if unknown.
ov_change (float) – Change in the wave function 1. - abs(<theta_guess|theta_diag>)

plot_update_stats(axes, xaxis='time', yaxis='E', y_exact=None, **kwargs)[source]¶

Plot update_stats to display the convergence during the sweeps.

Parameters

axes (matplotlib.axes.Axes) – The axes to plot into. Defaults to matplotlib.pyplot.gca()
xaxis ('N_updates' | 'sweep' | keys of update_stats) – Key of update_stats to be used for the x-axis of the plots. 'N_updates' is just enumerating the number of bond updates, and 'sweep' corresponds to the sweep number (including environment sweeps).
yaxis ('E' | keys of update_stats) – Key of update_stats to be used for the y-axisof the plots. For ‘E’, use the energy (per site for infinite systems).
y_exact (float) – Exact value for the quantity on the y-axis for comparison. If given, plot abs((y-y_exact)/y_exact) on a log-scale yaxis.
**kwargs – Further keyword arguments given to axes.plot(...).

plot_sweep_stats(axes=None, xaxis='time', yaxis='E', y_exact=None, **kwargs)[source]¶

Plot sweep_stats to display the convergence with the sweeps.

Parameters

axes (matplotlib.axes.Axes) – The axes to plot into. Defaults to matplotlib.pyplot.gca()
xaxis (key of sweep_stats) – Key of sweep_stats to be used for the x-axis and y-axis of the plots.
yaxis (key of sweep_stats) – Key of sweep_stats to be used for the x-axis and y-axis of the plots.
y_exact (float) – Exact value for the quantity on the y-axis for comparison. If given, plot abs((y-y_exact)/y_exact) on a log-scale yaxis.
**kwargs – Further keyword arguments given to axes.plot(...).

mixer_activate()[source]¶

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

option TwoSiteDMRGEngine.mixer: str | class | bool¶: Chooses the Mixer to be used. A string stands for one of the mixers defined in this module, a class is used as custom mixer. Default (None) uses no mixer, True uses DensityMatrixMixer for the 2-site case and SingleSiteMixer for the 1-site case.

option TwoSiteDMRGEngine.mixer_params: dict¶: Mixer parameters as described in Mixer.

mixer_cleanup()[source]¶

Cleanup the effects of a mixer.

A sweep() with an enabled Mixer leaves the MPS psi with 2D arrays in S. To recover the originial form, this function simply performs one sweep with disabled mixer.

environment_sweeps(N_sweeps)[source]¶

Perform N_sweeps sweeps without optimization to update the environment.

Parameters: N_sweeps (int) – Number of sweeps to run without optimization

get_resume_data()[source]¶

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

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

Returns: resume_data – Dictionary with necessary data (apart from copies of psi, model, options) that allows to continue the simulation from where we are now.
Return type: dict

get_sweep_schedule()[source]¶

Define the schedule of the sweep.

One ‘sweep’ is a full sequence from the leftmost site to the right and back. Only those LP and RP that can be used later should be updated.

Returns: schedule – Schedule for the sweep. Each entry is (i0, move_right, (update_LP, update_RP)), where i0 is the leftmost of the self.EffectiveH.length sites to be updated in update_local(), move_right indicates whether the next i0 in the schedule is rigth (True) of the current one, and update_LP, update_RP indicate whether it is necessary to update the LP and RP. The latter are chosen such that the environment is growing for infinite systems, but we only keep the minimal number of environment tensors in memory.
Return type: iterable of (int, bool, (bool, bool))

init_env(model=None, resume_data=None)[source]¶

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

Options

Deprecated since version 0.6.0: Options LP, LP_age, RP and RP_age are now collected in a dictionary init_env_data with different keys init_LP, init_RP, age_LP, age_RP

Deprecated since version 0.8.0: Instead of passing the init_env_data as a option, it should be passed as dict entry of resume_data.

option Sweep.init_env_data: dict¶: Dictionary as returned by self.env.get_initialization_data() from get_initialization_data().

option Sweep.orthogonal_to: list of MPS¶: List of other matrix product states to orthogonalize against. Works only for finite systems. This parameter 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.

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.

make_eff_H()[source]¶: Create new instance of self.EffectiveH at self.i0 and set it to self.eff_H.

property n_optimize¶

the number of sites to be optimized over 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.

resume_run()[source]¶

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 behaviour implemented here is to just call run().