OrthogonalExcitations

• full name: tenpy.simulations.ground_state_search.OrthogonalExcitations

• parent module: tenpy.simulations.ground_state_search

• type: class

Inheritance Diagram

Methods

OrthogonalExcitations.__init__(options, *[, ...])
OrthogonalExcitations.estimate_RAM()	Estimates the RAM usage for the simulation, without running it.
OrthogonalExcitations.extract_segment_from_infinite(...)	Extract a finite segment from the infinite model/state.
OrthogonalExcitations.final_measurements()	Perform a last set of measurements.
OrthogonalExcitations.fix_output_filenames()	Determine the output filenames.
OrthogonalExcitations.from_saved_checkpoint([...])	Re-initialize a given simulation class from checkpoint results.
OrthogonalExcitations.get_backup_filename(...)	Extract the name used for backups of output_filename.
OrthogonalExcitations.get_measurement_psi_model(...)	Get psi for measurements.
OrthogonalExcitations.get_output_filename()	Read out the output_filename from the options.
OrthogonalExcitations.get_resume_data()	Get resume data for a Simulation.
OrthogonalExcitations.get_version_info()	Try to save version info which is necessary to allow reproducibility.
OrthogonalExcitations.group_sites_for_algorithm()	Coarse-grain the model and state for the algorithm.
OrthogonalExcitations.group_split()	Split sites of psi that were grouped in group_sites_for_algorithm().
OrthogonalExcitations.handle_abort_signal(...)	Handle a SIGINT signal, usually caused by a CTRL-C press.
OrthogonalExcitations.init_algorithm(**kwargs)	Initialize the algorithm.
OrthogonalExcitations.init_cache()	Initialize the cache from the options.
OrthogonalExcitations.init_measurements()	Initialize and prepare measurements.
OrthogonalExcitations.init_model()	Initialize a model from the model parameters.
OrthogonalExcitations.init_orthogonal_from_groundstate()	Initialize orthogonal_to from the ground state.
OrthogonalExcitations.init_state()	Initialize the state.
OrthogonalExcitations.make_measurements()	Perform measurements and merge the results into self.results['measurements'].
OrthogonalExcitations.perform_measurements()	Emits the measurement_event to call measurement functions and collect results.
OrthogonalExcitations.prepare_results_for_save()	Bring the results into a state suitable for saving.
OrthogonalExcitations.resume_run()	Resume a simulation that was initialized from a checkpoint.
OrthogonalExcitations.resume_run_algorithm()	Run the algorithm.
OrthogonalExcitations.run()	Run the whole simulation.
OrthogonalExcitations.run_algorithm()	Run the algorithm.
OrthogonalExcitations.run_post_processing()	Apply (several) post-processing steps.
OrthogonalExcitations.save_at_checkpoint(...)	Save the intermediate results at the checkpoint of an algorithm.
OrthogonalExcitations.save_results([results])	Save the results to an output file.
OrthogonalExcitations.switch_charge_sector()	Change the charge sector of psi in place.
OrthogonalExcitations.walltime()	Wall time evolved since initialization of the simulation class.
OrthogonalExcitations.write_converged_environments(...)	Write converged environments back into the file with the ground state.

Class Attributes and Properties

OrthogonalExcitations.default_algorithm	name of the default algorithm engine class
OrthogonalExcitations.default_measurements	tuples as for Simulation.connect_measurements that get added if the Simulation.use_default_measurements is True.
OrthogonalExcitations.default_post_processing	tuples as for Simulation.run_post_processing, same structure as for measurements
OrthogonalExcitations.logger	class attribute.

class tenpy.simulations.ground_state_search.OrthogonalExcitations(options, *, orthogonal_to=None, **kwargs)

Bases: GroundStateSearch

Find excitations by another GroundStateSearch orthogonalizing against previous states.

If the ground state is an infinite MPS, it is converted to segment boundary conditions at the beginning of this simulation.

For finite systems, the first algorithm (say DMRG) run when switching the charge sector can be replaced by a normal DMRG run with a different initial state (in the desired sector). For infinite systems, the conversion to segment boundary conditions leads to a different state! Using the ‘segment’ boundary conditions, this class can e.g. study a single spin flip excitation in the background of the ground state, localized by the segment environments.

Note that the segment environments are soft boundaries: the spin flip can be outside the segment where we vary the MPS tensors, as far as it contained in the Schmidt states of the original ground state.

Parameters:

orthogonal_to (None list) – States to orthogonalize against.

Options

config OrthogonalExcitations

option	summary
algorithm_class (from Simulation) in Simulation.init_algorithm	Class or name of a subclass of :class:`~tenpy.algorithms.algorithm.Algorith [...]
algorithm_params (from Simulation) in Simulation.init_algorithm	Dictionary with parameters for the algorithm; see the documentation of the [...]
apply_local_op in OrthogonalExcitations.init_orthogonal_from_groundstate	If not `None`, apply :meth:`~tenpy.networks.mps.MPS.apply_local_op` with gi [...]
cache_params (from Simulation) in GroundStateSearch.init_cache	Dictionary with parameters for the cache, see [...]
cache_threshold_chi (from Simulation) in GroundStateSearch.init_cache	If the `algorithm_params.trunc_params.chi_max` in :attr:`options` is smalle [...]
canonicalize_before_measurement (from Simulation) in GroundStateSearch.init_measurements	If True, call `psi.canonical_form()` on the state used for measurement.
connect_algorithm_checkpoint (from Simulation) in Simulation.init_algorithm	Functions to connect to the :attr:`~tenpy.algorithms.Algorithm.checkpoint` [...]
connect_measurements (from Simulation) in GroundStateSearch.init_measurements	Functions to connect to the :attr:`measurement_event`. [...]
directory (from Simulation) in Simulation	If not None (default), switch to that directory at the beginning of the sim [...]
ground_state_filename in OrthogonalExcitations.init_orthogonal_from_groundstate	File from which the ground state should be loaded.
group_sites (from Simulation) in GroundStateSearch.group_sites_for_algorithm	How many sites to group. 1 means no grouping.
group_to_NearestNeighborModel (from Simulation) in GroundStateSearch.group_sites_for_algorithm	If True, convert the grouped model to a [...]
initial_state_builder_class (from Simulation) in GroundStateSearch.init_state	Class or name of a subclass of :class:`~tenpy.networks.mps.InitialStateBuil [...]
initial_state_params in OrthogonalExcitations.init_state	The initial state parameters, :cfg:config:`ExcitationInitialState` defined [...]
log_params (from Simulation) in Simulation	Log parameters; see :cfg:config:`log`.
max_errors_before_abort (from Simulation) in Simulation	We safeguard measurements with a try-except block to avoid loosing results [...]
measure_at_algorithm_checkpoints (from Simulation) in GroundStateSearch.init_measurements	Defaults to False. If True, make measurements at each algorithm checkpoint. [...]
measure_initial (from Simulation) in GroundStateSearch.init_measurements	Whether to perform a measurement on the initial state, i.e., before startin [...]
model_class (from Simulation) in GroundStateSearch.init_model	Mandatory. Class or name of a subclass of :class:`~tenpy.models.model.Model`.
model_params (from Simulation) in GroundStateSearch.init_model	Dictionary with parameters for the model; see the documentation of the [...]
N_excitations	Number of excitations to find. [...]
orthogonal_norm_tol in OrthogonalExcitations.init_orthogonal_from_groundstate	Tolerance how large :meth:`~tenpy.networks.mps.MPS.norm_err` may be for sta [...]
output_filename (from Simulation) in GroundStateSearch.get_output_filename	If ``None`` (default), no output is written to files. [...]
output_filename_params (from Simulation) in GroundStateSearch.get_output_filename	Instead of specifying the `output_filename` directly, this dictionary descr [...]
overwrite_output (from Simulation) in GroundStateSearch.fix_output_filenames	Only makes a difference if `skip_if_output_exists` is False and the file ex [...]
random_seed (from Simulation) in Simulation	If not ``None``, initialize the (legacy) numpy random generator with the gi [...]
safe_write (from Simulation) in GroundStateSearch.fix_output_filenames	If True (default), perform a "safe" overwrite of `output_filename` as descr [...]
save_every_x_seconds (from Simulation) in GroundStateSearch.save_at_checkpoint	By default (``None``), this feature is disabled. [...]
save_psi (from Simulation) in GroundStateSearch.init_state	Whether the final :attr:`psi` should be included into the output :attr:`res [...]
save_stats (from GroundStateSearch) in GroundStateSearch.init_algorithm	Whether to include the `sweep_stats` and `update_stats` of the engine into [...]
segment_enlarge in OrthogonalExcitations.init_orthogonal_from_groundstate	Only for initially infinite ground states. [...]
segment_first in OrthogonalExcitations.init_orthogonal_from_groundstate	Only for initially infinite ground states. [...]
segment_last in OrthogonalExcitations.init_orthogonal_from_groundstate	Only for initially infinite ground states. [...]
sequential (from Simulation) in Simulation	Parameters for running simulations sequentially, see :cfg:config:`sequentia [...]
skip_if_output_exists (from Simulation) in GroundStateSearch.fix_output_filenames	If True, raise :class:`Skip` if the output file already exists.
switch_charge_sector in OrthogonalExcitations.init_orthogonal_from_groundstate	If given, change the charge sector of the excitations compared to the groun [...]
switch_charge_sector_site in TopologicalExcitations.init_from_groundstate	To the left of which site we switch charge sector. [...]
use_default_measurements (from Simulation) in GroundStateSearch.init_measurements	Each Simulation class defines a list of :attr:`default_measurements` in the [...]
write_back_converged_ground_state_environments in OrthogonalExcitations.init_orthogonal_from_groundstate	Only used for infinite ground states, indicating that we should write conve [...]

option N_excitations: int

Number of excitations to find. Don’t make this too big, it’s gonna perform that many algorithm runs!

orthogonal_to

States to orthogonalize against.

Type:

list

excitations

Tensor network states representing the excitations. The ground state in orthogonal_to is not included in the excitations. While being optimized, a state is saved as psi and not yet included in excitations.

Type:

list

init_env_data

Initialization data for the MPOEnvironment. Passed to the algorithm class.

Type:

dict

results

In addition to results, it contains

ground_state_energyfloat

Reference energy for the ground state.

excitationslist

Tensor network states representing the excitations. Only defined if Simulation.save_psi is True.

Type:

dict

run()

Run the whole simulation.

Returns:

results – The results as returned by prepare_results_for_save().

Return type:

dict

resume_run()

Resume a simulation that was initialized from a checkpoint.

Returns:

results – The results as returned by prepare_results_for_save().

Return type:

dict

init_orthogonal_from_groundstate()

Initialize orthogonal_to from the ground state.

Load the ground state. If the ground state is infinite, call extract_segment_from_infinite().

An empty orthogonal_to indicates that we will switch_charge_sector() in the first init_algorithm() call.

Options

option OrthogonalExcitations.ground_state_filename

File from which the ground state should be loaded.

option OrthogonalExcitations.orthogonal_norm_tol: float

Tolerance how large norm_err() may be for states to be added to orthogonal_to.

option OrthogonalExcitations.segment_enlarge: int | None

option OrthogonalExcitations.segment_first: int | None

option OrthogonalExcitations.segment_last: int | None

Only for initially infinite ground states. Arguments for extract_segment().

option OrthogonalExcitations.apply_local_op: dict | None

If not None, apply apply_local_op() with given keyword arguments to change the charge sector compared to the ground state. Alternatively, use switch_charge_sector.

option OrthogonalExcitations.switch_charge_sector: list of int | None

If given, change the charge sector of the excitations compared to the ground state. Alternative to apply_local_op where we run a small zero-site diagonalization on the (left-most/center for infinite/finite) bond in the desired charge sector to update the state.

option OrthogonalExcitations.write_back_converged_ground_state_environments: bool

Only used for infinite ground states, indicating that we should write converged environments of the ground state back to ground_state_filename. This is an optimization if you intend to run another OrthogonalExcitations simulation in the future with the same ground_state_filename. (However, it is not faster when the simulations run at the same time; instead it might even lead to errors!)

Returns:

data – The data loaded from OrthogonalExcitations.ground_state_filename.

Return type:

dict

extract_segment_from_infinite(psi0_inf, model_inf, resume_data)

Extract a finite segment from the infinite model/state.

Parameters:

• psi0_inf (MPS) – Original ground state with infinite boundary conditions.

• model_inf (MPOModel) – Original infinite model.

• resume_data (dict) – Possibly contains init_env_data with environments.

Returns:

write_back – Whether we should call write_converged_environments().

Return type:

bool

write_converged_environments(gs_data, gs_fn)

Write converged environments back into the file with the ground state.

Parameters:

• gs_data (dict) – Data loaded from the ground state file.

• gs_fn (str) – Filename where to save gs_data.

init_state()

Initialize the state.

Options

option OrthogonalExcitations.initial_state_params: dict

The initial state parameters, ExcitationInitialState defined below.

init_algorithm(**kwargs)

Initialize the algorithm.

Options

option GroundStateSearch.save_stats: bool

Whether to include the sweep_stats and update_stats of the engine into the output.

switch_charge_sector()

Change the charge sector of psi in place.

run_algorithm()

Run the algorithm.

Calls self.engine.run().

resume_run_algorithm()

Run the algorithm.

Calls self.engine.run().

prepare_results_for_save()

Bring the results into a state suitable for saving.

For example, this can be used to convert lists to numpy arrays, to add more meta-data, or to clean up unnecessarily large entries.

Options

Cfg:configoptions ::

Simulation

save_resume_databool

If True, include data returned by get_resume_data() into the output as resume_data.

Returns:

results – A copy of results containing everything to be saved. Measurement results are converted into a numpy array (if possible).

Return type:

dict

default_algorithm = 'TwoSiteDMRGEngine'

name of the default algorithm engine class

default_measurements = [('tenpy.simulations.measurement', 'm_measurement_index', {}, 1), ('tenpy.simulations.measurement', 'm_bond_dimension'), ('tenpy.simulations.measurement', 'm_entropy')]

tuples as for Simulation.connect_measurements that get added if the Simulation.use_default_measurements is True.

default_post_processing = []

tuples as for Simulation.run_post_processing, same structure as for measurements

estimate_RAM()

Estimates the RAM usage for the simulation, without running it.

Returns:

RAM – The expected RAM usage in kB.

Return type:

int

final_measurements()

Perform a last set of measurements.

fix_output_filenames()

Determine the output filenames.

This function determines the output_filename and writes a one-line text into that file to indicate that we’re running a simulation generating it. Further, _backup_filename is determined.

Options

option Simulation.skip_if_output_exists: bool

If True, raise Skip if the output file already exists.

option Simulation.overwrite_output: bool

Only makes a difference if skip_if_output_exists is False and the file exists. In that case, with overwrite_output, just save everything under that name again, or with overwrite_output`=False, replace ``filename.ext` with filename_01.ext (and further increasing numbers) until we get a filename that doesn’t exist yet.

option Simulation.safe_write: bool

If True (default), perform a “safe” overwrite of output_filename as described in save_results().

classmethod from_saved_checkpoint(filename=None, checkpoint_results=None, **kwargs)

Re-initialize a given simulation class from checkpoint results.

You should probably call resume_run() after successful initialization.

Instead of calling this directly, consider using resume_from_checkpoint().

Parameters:

• filename (None | str) – The filename of the checkpoint to be loaded. You can either specify the filename or the checkpoint_results.

• checkpoint_results (None | dict) – Alternatively to filename the results of the simulation so far, i.e. directly the data dictionary saved at a simulation checkpoint.

• **kwargs – Further keyword arguments given to the Simulation.__init__.

get_backup_filename(output_filename)

Extract the name used for backups of output_filename.

Parameters:

output_filename (pathlib.Path) – The filename where data is saved.

Returns:

backup_filename – The filename where to keep a backup while writing files to avoid.

Return type:

pathlib.Path

get_measurement_psi_model(psi, model)

Get psi for measurements.

Sometimes, the psi we want to use for measurements is different from the one the algorithm actually acts on. Here, we split sites, if they were grouped in group_sites_for_algorithm().

Parameters:

• psi – Tensor network; initially just self.psi. The method should make a copy before modification.

• model – Model matching psi (in terms of indexing, MPS order, grouped sites, …) Initially just self.model.

Returns:

• psi – The psi suitable as argument for generic measurement functions.

• model – Model matching psi (in terms of indexing, MPS order, grouped sites, …)

get_output_filename()

Read out the output_filename from the options.

You can easily overwrite this method in subclasses to customize the outputfilename depending on the options passed to the simulations.

Options

option Simulation.output_filename: path_like | None

If None (default), no output is written to files. If a string, this filename is used for output (up to modifications by fix_output_filenames() to avoid overwriting previous results).

option Simulation.output_filename_params: dict

Instead of specifying the output_filename directly, this dictionary describes the parameters that should be included into it. Entries of the dictionary are keyword arguments to output_filename_from_dict() with the simulation parameters (Simulation, or equivalently options) as options.

Returns:

output_filename – Filename for output; None disables any writing to files. Relative to Simulation.directory, if specified. The file ending determines the output format.

Return type:

str | None

get_resume_data() → dict

Get resume data for a Simulation.

Return data from get_resume_data() in base Simulation. Subclasses should override this with resume_data = super().get_resume_data(), s.t. Simulation specific data can easily be returned for resume_data.

get_version_info()

Try to save version info which is necessary to allow reproducibility.

group_sites_for_algorithm()

Coarse-grain the model and state for the algorithm.

Options

option Simulation.group_sites: int

How many sites to group. 1 means no grouping.

option Simulation.group_to_NearestNeighborModel: bool

If True, convert the grouped model to a NearestNeighborModel. Use this if you want to run TEBD with a model that was originally next-nearest neighbor.

group_split()

Split sites of psi that were grouped in group_sites_for_algorithm().

handle_abort_signal(signum, frame)

Handle a SIGINT signal, usually caused by a CTRL-C press.

When the user presses Ctrl-C the first time, we just print a message to stderr that we received the signal and set the flag received_signal_sigint. This allows the simulation to “exit gracefully”: it will continue until the next algorithm checkpoint, where save_at_checkpoint() checks for this flag, and if set, saves the results obtained so far and only then raises KeyboardInterrupt.

When Ctrl-C is presssed a second time, we immediately raise a KeyboardInterrupt.

This feature is especially handy to gracefully interrupt long-running simulations. When running in an HPC cluster linux environment, you can usually still send the SIGINT signal, e.g. with SLURM you can call scancel --signal=INT 1234 for the job ide 1234.

init_cache()

Initialize the cache from the options.

This method is only called automatically when the simulation is used in a with ... statement. This is the case if you use run_simulation(), etc.

Options

option Simulation.cache_threshold_chi: int

If the algorithm_params.trunc_params.chi_max in options is smaller than this threshold, do not initialize a (non-trivial) cache.

option Simulation.cache_params: dict

Dictionary with parameters for the cache, see open().

init_measurements()

Initialize and prepare measurements.

Options

option Simulation.connect_measurements: list of tuple

Functions to connect to the measurement_event. Each tuple can be of length 2 to 4, with entries (module, function, kwargs, priority), the last two optionally. The mandatory module and function specify a callback measurement function. kwargs can specify extra keyword-arguments for the function, priority allows to tune the order in which the measurement functions get called. See connect_by_name() for more details.

option Simulation.use_default_measurements: bool

Each Simulation class defines a list of default_measurements in the same format as Simulation.connect_measurements. This flag allows to explicitly disable them.

option Simulation.measure_initial: bool

Whether to perform a measurement on the initial state, i.e., before starting the algorithm run.

option Simulation.measure_at_algorithm_checkpoints: bool

Defaults to False. If True, make measurements at each algorithm checkpoint. This can be useful to study e.g. the DMRG convergence with the number of sweeps. Note that (depending on the algorithm) psi might not be in canonical form during the algorithm run. In that case, you might need to also enable the canonicalize_before_measurement option to get correct e.g. correct long-range correlation functions. (On the other hand, local onsite expectation values are likely fine without the explicit canonical_form() call.)

option Simulation.canonicalize_before_measurement: bool

If True, call psi.canonical_form() on the state used for measurement.

init_model()

Initialize a model from the model parameters.

Skips initialization if model is already set.

Options

option Simulation.model_class: str | class

Mandatory. Class or name of a subclass of Model.

option Simulation.model_params: dict

Dictionary with parameters for the model; see the documentation of the corresponding model_class.

logger = <Logger tenpy.simulations.simulation.Simulation (WARNING)>

class attribute.

Type:

logger

Type:

An instance of a logger; see Logging and terminal output. NB

make_measurements()

Perform measurements and merge the results into self.results['measurements'].

perform_measurements()

Emits the measurement_event to call measurement functions and collect results.

Returns:

results – The results from calling the measurement functions.

Return type:

dict

run_post_processing()

Apply (several) post-processing steps.

post_processinglist of tuple

Functions to perform post-processing with the DataLoader. This uses a similar syntax to the attr:connect_measurements in meth:init_measurements. Each tuple can be of length 2 to 3, with entries (module, function, kwargs). The kwargs can contain a results_key under which the results (unless None is returned) are saved. All other kwargs are passed on to the function.

Note

All post-processing functions should follow the syntax: def pp_function(DL, *, kwarg1, kwarg_2=default_2): where DL is an instance of the DataLoader, kwarg_1 is a necessary keyword argument (no default value), while kwarg_2 is an optional keyword argument (with default value)

save_at_checkpoint(alg_engine)

Save the intermediate results at the checkpoint of an algorithm.

Parameters:

alg_engine (Algorithm) – The engine of the algorithm. Not used in this function, mostly there for compatibility with the checkpoint event.

Options

option Simulation.save_every_x_seconds: float | None

By default (None), this feature is disabled. If given, save the results obtained so far at each checkpoint when at least save_every_x_seconds seconds evolved since the last save (or since starting the algorithm). To avoid unnecessary, slow disk input/output, the value will be increased if saving takes longer than 10% of save_every_x_seconds. Use 0. to force saving at each checkpoint.

save_results(results=None)

Save the results to an output file.

Performs a “safe” overwrite of output_filename by first moving the old file to _backup_filename, then writing the new file, and finally removing the backup.

Parameters:

results (dict | None) – The results to be saved. If not specified, call prepare_results_for_save() to allow last-minute adjustments to the saved results.

walltime()

Wall time evolved since initialization of the simulation class.

Utility measurement method. To measure it, add the following entry to the Simulation.connect_measurements option:

- - simulation_method
  - wrap walltime

Returns:

seconds – Elapsed (wall clock) time in seconds since the initialization of the simulation.

Return type:

float