TopologicalExcitations

full name: tenpy.simulations.ground_state_search.TopologicalExcitations
parent module: tenpy.simulations.ground_state_search
type: class

Inheritance Diagram

Methods

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

Class Attributes and Properties

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

class tenpy.simulations.ground_state_search.TopologicalExcitations(options, *, gs_data_alpha=None, gs_data_beta=None, **kwargs)[source]

Bases: OrthogonalExcitations

init_from_groundstate()[source]

Initialize orthogonal_to from the ground state.

Load the ground state and initialize the model from it. Calls extract_segment().

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.apply_local_op: list | None: If not None, use apply_local_op() to change the charge sector compared to the ground state. Should have the form [site1, operator1, site2, operator2, ...]. with the operators given as strings (to be read out from the site class). Alternatively, use switch_charge_sector. site# are MPS indices in the original ground state, not the segment!

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 bond in the desired charge sector to update the state.

option OrthogonalExcitations.switch_charge_sector_site: int: To the left of which site we switch charge sector. MPS index in the original ground state, not the segment!

Returns:: gs_data – The data loaded from OrthogonalExcitations.ground_state_filename.
Return type:: dict

extract_segment(psi0_alpha_Orig, psi0_beta_Orig, model_orig, resume_data_alpha, resume_data_beta)[source]

Extract a finite segment from the original model and states.

In case the original state is already finite, we might still extract a sub-segment (if segment_first and/or segment_last are given) or just use the full system.

Defines ground_state_seg to be the ground state of the segment. Further model and init_env_data are extracted.

Options

option OrthogonalExcitations.segment_enlarge: int | None
option OrthogonalExcitations.segment_first: int | None
option OrthogonalExcitations.segment_last: int | None: Arguments for extract_segment(). segment_enlarge is only used for initially infinite ground states.

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!)

Parameters:

psi0_orig (MPS) – Original ground state.
model_orig (MPOModel) – Original model.
resume_data (dict) – Possibly contains init_env_data with environments.

Returns:

psi0_seg – Unperturbed ground state in the segment, against which to orthogonalize if we don’t switch charge sector.
write_back (bool) – Whether write_back_environments() should be called.

get_reference_energy(psi0_alpha, psi0_beta)[source]

Obtain ground state reference energy.

Excitation energies are full contractions of the MPOEnvironment with the environments defined in init_env_data. Hence, the reference energy is also the contraction of the MPOEnvironment on the segment.

Parameters:: psi0_alpha (MPS) – Infinite ground state MPS on the left, matching init_env_data_alpha.

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()[source]

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

Returns:: RAM – The expected RAM usage in kB.
Return type:: int

extract_segment_from_infinite(psi0_inf, model_inf, resume_data)[source]

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

final_measurements()[source]: Perform a last set of measurements.

fix_output_filenames()[source]

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)[source]

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)[source]

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)[source]

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()[source]

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[source]

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()[source]: Try to save version info which is necessary to allow reproducibility.

group_sites_for_algorithm()[source]

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()[source]: Split sites of psi that were grouped in group_sites_for_algorithm().

handle_abort_signal(signum, frame)[source]

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_algorithm(**kwargs)[source]

Initialize the algorithm.

Options

option GroundStateSearch.save_stats: bool: Whether to include the sweep_stats and update_stats of the engine into the output.

init_cache()[source]

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()[source]

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()[source]

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.

init_orthogonal_from_groundstate()[source]

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

init_state()[source]

Initialize the state.

Options

option OrthogonalExcitations.initial_state_params: dict: The initial state parameters, ExcitationInitialState defined below.

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()[source]: Perform measurements and merge the results into self.results['measurements'].

perform_measurements()[source]

Emits the measurement_event to call measurement functions and collect results.

Returns:: results – The results from calling the measurement functions.
Return type:: dict

prepare_results_for_save()[source]

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

resume_run()[source]

Resume a simulation that was initialized from a checkpoint.

Returns:: results – The results as returned by prepare_results_for_save().
Return type:: dict

resume_run_algorithm()[source]

Run the algorithm.

Calls self.engine.run().

run()[source]

Run the whole simulation.

Returns:: results – The results as returned by prepare_results_for_save().
Return type:: dict

run_algorithm()[source]

Run the algorithm.

Calls self.engine.run().

run_post_processing()[source]

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)[source]

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)[source]

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.

switch_charge_sector()[source]: Change the charge sector of psi in place.

walltime()[source]

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

write_converged_environments(gs_data, gs_fn)[source]

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.