OrthogonalExcitations¶
full name: tenpy.simulations.ground_state_search.OrthogonalExcitations
parent module:
tenpy.simulations.ground_state_search
type: class
Inheritance Diagram

Methods
|
|
Extract a finite segment from the infinite model/state. |
|
Perform a last set of measurements. |
|
Determine the output filenames. |
|
Re-initialize a given simulation class from checkpoint results. |
|
Extract the name used for backups of output_filename. |
|
Get psi for measurements. |
|
Read out the output_filename from the options. |
|
Try to save version info which is necessary to allow reproducability. |
|
Coarse-grain the model and state for the algorithm. |
|
Split sites of psi that were grouped in |
|
|
Initialize the algorithm. |
Initialize the |
|
Initialize and prepare measurements. |
|
Initialize a |
|
Initialize |
|
Initialize the state. |
|
Perform measurements and merge the results into |
|
Emits the |
|
Bring the results into a state suitable for saving. |
|
Resume a simulation that was initialized from a checkpoint. |
|
Run the algorithm. |
|
Run the whole simulation. |
|
Run the algorithm. |
|
Save the intermediate results at the checkpoint of an algorithm. |
|
|
Save the |
Change the charge sector of |
|
Wall time evolved since initialization of the simulation class. |
|
Write converged environments back into the file with the ground state. |
Class Attributes and Properties
name of the default algorithm engine class |
|
tuples as for |
|
class attribute. |
|
|
- class tenpy.simulations.ground_state_search.OrthogonalExcitations(options, *, orthogonal_to=None, **kwargs)[source]¶
Bases:
GroundStateSearch
Find excitations by another GroundStateSearch orthogalizing 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 intial 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 algortihm; see the decoumentation 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.Algorith.checkpoint` e [...]
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`.
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 [...]
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 exciations compared to the ground [...]
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!
- exctiations¶
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
- init_env_data¶
Initialization data for the
MPOEnvironment
. Passed to the algorithm class.- Type
- 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
- run()[source]¶
Run the whole simulation.
- Returns
results – The
results
as returned byprepare_results_for_save()
.- Return type
- resume_run()[source]¶
Resume a simulation that was initialized from a checkpoint.
- Returns
results – The
results
as returned byprepare_results_for_save()
.- Return type
- 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 willswitch_charge_sector()
in the firstinit_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 toorthogonal_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 exciations 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.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
- extract_segment_from_infinite(psi0_inf, model_inf, resume_data)[source]¶
Extract a finite segment from the infinite model/state.
- Parameters
- Returns
write_back – Whether we should call
write_converged_environments()
.- Return type
- write_converged_environments(gs_data, gs_fn)[source]¶
Write converged environments back into the file with the ground state.
- init_state()[source]¶
Initialize the state.
Options
- option OrthogonalExcitations.initial_state_params: dict¶
The initial state parameters,
ExcitationInitialState
defined below.
- 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.
- 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
- 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_energy_MPO'), ('tenpy.simulations.measurement', 'm_entropy')]¶
tuples as for
Simulation.connect_measurements
that get added if theSimulation.use_default_measurements
is True.
- 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 sucessfull 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 dicitonary 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
- 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 byfix_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 equivalentlyoptions
) 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
- 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()
.
- 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 userun_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. Seeconnect_by_name()
for more details.
- option Simulation.use_default_measurements: bool¶
Each Simulation class defines a list of
default_measurements
in the same format asSimulation.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.
- 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
- 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 thetenpy.algorithms.Algorithm.checkpoint
event.
Options
- option Simulation.save_every_x_seconds: float | None¶
By default (
None
), this feature is disabled. If given, save theresults
obtained so far at eachtenpy.algorithm.Algorithm.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. Use0.
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 safed. If not specified, call
prepare_results_for_save()
to allow last-minute adjustments to the savedresults
.
- 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