pyretis.bin¶

Here, the PyRETIS executables can be found. These are:

pyretis.bin.cli module ¶

pyretis - The unified PyRETIS command-line interface.

This is the single entry point for PyRETIS. It dispatches a sub-command to the matching tool:

pyretis run -i input.toml          # run a simulation  (was pyretisrun)
pyretis analyse -i analysis.txt    # analyse output    (was pyretisanalyse)
pyretis status                     # per-ensemble sampling summary
pyretis tools init -i input.toml   # auto-place interfaces (infinit driver)
pyretis tools clean                # remove run artifacts in a directory

Run with no command (or pyretis -h) it prints the logo and this usage; pyretis -v / --version prints the version.

The run and analyse sub-commands take exactly the same options as the standalone command they replace; pyretis <command> -h shows them. The standalone pyretisrun and pyretisanalyse commands still work but are deprecated: from PyRETIS 5 only pyretis run and pyretis analyse will be supported. pyretis clean is likewise kept as a deprecated alias of pyretis tools clean.

pyretis.bin.cli.entry_point()¶

Dispatch pyretis <command> ... to the matching tool.

The first argument selects the sub-command; every remaining argument is handed unchanged to that tool’s own argument parser.

pyretis.bin.cli.print_welcome()¶: Print the PyRETIS logo followed by the usage text.

pyretis.bin.cli.usage()¶

Return the top-level usage text for the unified CLI.

Returns:: string – The multi-line usage / help text.

pyretis.bin.pyretisrun module ¶

pyretisrun - An application for running PyRETIS simulations.

This script is a part of the PyRETIS library and can be used for running simulations from an input script.

usage: pyretisrun.py [-h] -i INPUT [-V] [-f LOG_FILE] [-l LOG_LEVEL] [-p]

PyRETIS

optional arguments:

-h, --help: show this help message and exit
-i INPUT, --input INPUT: Location of PyRETIS input file
-V, --version: show program’s version number and exit
-f LOG_FILE, --log_file LOG_FILE: Specify log file to write
-l LOG_LEVEL, --log_level LOG_LEVEL: Specify log level for log file
-p, --progress: Display a progress meter instead of text output for the simulation

More information about running PyRETIS can be found at: www.pyretis.org

pyretis.bin.pyretisrun.ENSEMBLE_ENGINES_PATH = ('simulation', 'ensemble_engines')¶: Where the scheduler configuration holds the engine sections of each ensemble, as the key table places [simulation] ensemble_engines.

pyretis.bin.pyretisrun.HIGH_ACCEPT_PATH = ('simulation', 'tis_set', 'high_accept')¶: Where the scheduler configuration records [tis] high_accept, as the key table places it; the moves read pyretis.core.moves.HIGH_ACCEPT_DEFAULT when it is absent.

pyretis.bin.pyretisrun.MOVES_PATH = ('simulation', 'shooting_moves')¶: Where the scheduler configuration lists the move each ensemble runs, as the key table places [tis] shooting_moves.

pyretis.bin.pyretisrun.RESUME_ANALYSIS_ENGINE_SETTINGS = ('timestep', 'subcycles')¶: The [engine] settings of RESUME_LOCKED_SETTINGS a continuation keeps when no ensemble of either run takes its MD from [engine]: the analysis converts the path lengths of the run to time with timestep * subcycles of [engine] (pyretis.core.engine_time.engine_time_per_step()), the time per step every engine section of the run has (pyretis.core.engine_time.one_time_per_step_problem()). A continuation kicks no path, so the other [engine] settings take no effect on it.

pyretis.bin.pyretisrun.RESUME_ENGINE_DEFAULTS = {('subcycles', 'langevin'): 1, ('subcycles', 'openmm'): 1, ('subcycles', 'velocityverlet'): 1, ('subcycles', 'verlet'): 1}¶: The value an engine runs a locked setting with when its engine section leaves the setting out, as {(setting, engine class): value}. An absent key is compared as this value. The internal integrators store every integration step when subcycles is left out (the default of pyretis.engines.internal.MDEngine.setup_streaming()), and so does OpenMM (the default of its constructor). The GROMACS, LAMMPS, CP2K, AMS, ASE and TurtleMD engines require subcycles.

pyretis.bin.pyretisrun.RESUME_ENGINE_INPUT_SETTINGS = {'timestep': (('lammps', 'lammps2', 'lammps_steps', 'openmm'), "The LAMMPS or OpenMM time step is read from the engine's own input; stating {key} as well records it, and the engine checks that the two agree.")}¶: The locked settings an engine reads from its own input, as {setting: (engine classes, advice)}. LAMMPS reads the time step from its input file and OpenMM from its integrator, and each checks a time step stated in its engine section against its own. The advice, with {key} the input key of the setting, ends the warning about a continuation that leaves such a setting out.

pyretis.bin.pyretisrun.RESUME_EVERY_ENGINE_SETTINGS = ('timestep', 'subcycles')¶

each engine stores a frame every subcycles integration steps of length timestep. Each engine takes both from the engine section it is built from. The internal integrators take timestep through their constructor and read subcycles from that section when a scheduler worker sets them up for streaming (pyretis.engines.internal.MDEngine.setup_streaming()); the other engines of pyretis.engines.factory.build_engine_map() take both through their constructor. Any other engine setting applies to an engine whose constructor takes it.

Type:: The locked engine settings that apply to every engine

pyretis.bin.pyretisrun.RESUME_LAYOUT_MEANINGS = {'explore': 'an exploration without the [0^-] ensemble', 'lambda_minus_one': 'the lambda_{-1} interface of the [0^-] ensemble', 'noswap': 'the ensembles exchange no paths', 'permeability': 'the permeability layout of the [0^-] ensemble', 'pptis_no_minus': 'a pptis layout without the [0^-] ensemble', 'pptis_no_zero_plus': 'a pptis layout without the [0^+] ensemble', 'repptis': 'partial-path ensembles', 'repptis_memory': 'the memory of the partial-path windows', 'single_tis': 'a single TIS ensemble'}¶: What each scheduler setting of RESUME_LOCKED_LAYOUT fixes, keyed by the last name of its path, as a refusal states it.

pyretis.bin.pyretisrun.RESUME_LOCKED_DEFAULTS = {'enforce_must_cross_m': True}¶: The value the sampler uses for a locked setting that the scheduler configuration does not carry. The key table carries [tis] enforce_must_cross_m only when the input sets it, and every reader takes it with a default of True, so an absent key records True: it is compared as True rather than reported as a missing record.

pyretis.bin.pyretisrun.RESUME_LOCKED_LAYOUT = (('task', ('simulation', 'noswap')), ('task', ('simulation', 'repptis')), ('task', ('simulation', 'explore')), ('task', ('simulation', 'single_tis')), ('task, zero_left, flux', ('simulation', 'pptis_no_minus')), ('task, zero_ensemble', ('simulation', 'pptis_no_zero_plus')), ('zero_left', ('simulation', 'tis_set', 'lambda_minus_one')), ('permeability', ('simulation', 'tis_set', 'permeability')), ('memory', ('simulation', 'repptis_memory')))¶: The scheduler settings that fix the ensemble layout, as (input keywords, path-into-the-config). The translation (pyretis.inout.config_adapter.to_scheduler_config()) sets them from [simulation] task, zero_left, flux, zero_ensemble and permeability, and from the PPTIS memory ([pptis] memory or [repptis] memory). The scheduler reads each flag with a default of False, so an absent key is compared as False. The translation sets repptis_memory for every pptis and repptis run, and a run of another task builds no window with it, so an absent memory is compared as False as well. They decide which ensembles a run builds, the window of each, which paths it accepts and whether the ensembles exchange paths, so the paths the ensembles hold across the resume were accepted in the recorded layout. flux and zero_ensemble enter the layout of a pptis run only; the translation of every other task builds the same ensembles whatever they are set to. The memory sets the local window [lambda_{i-memory}, lambda_i, lambda_{i+memory}] of each ensemble of a pptis or repptis run. A refusal names the input keys the key table reads a setting from (pyretis.inout.key_table.input_keys()) and what the setting fixes (RESUME_LAYOUT_MEANINGS).

pyretis.bin.pyretisrun.RESUME_LOCKED_SETTINGS = (('maxlength', ('tis', 'maxlength')), ('allowmaxlength', ('tis', 'allowmaxlength')), ('enforce_must_cross_m', ('tis', 'enforce_must_cross_m')), ('temperature', ('system', 'temperature')), ('engine temperature', ('engine', 'temperature')), ('timestep', ('engine', 'timestep')), ('subcycles', ('engine', 'subcycles')), ('order parameter', ('orderparameter',)), ('exchange format', ('engine', 'gmx_format')))¶

Settings a restart continuation may not change, as (description, input key). The input key is the path of the key in the canonical input; the key table places it in the scheduler configuration (pyretis.inout.key_table.scheduler_place()), where the two runs are compared (_locked_place()). The number of ensembles and the interfaces are checked separately, with their own messages, and the ensemble layout with RESUME_LOCKED_LAYOUT.

maxlength is here because it does NOT “only cap”: a binding cap changes which trials can be accepted, so a continuation that raises or lowers it samples a different ensemble from the one whose state it is resuming. It is therefore fixed across a continuation rather than treated as an analysis-only cap. allowmaxlength decides whether the shooting move draws a random length cap from the old path’s length, which enters the acceptance probability, so it carries the same weight. enforce_must_cross_m decides which paths are members of a PPTIS/REPPTIS ensemble: the occupants carried across the resume were accepted under the recorded value.

[system] temperature is the temperature of the system PyRETIS builds, which the internal integrators run at. An engine whose constructor takes a temperature reads its own from [engine]: TurtleMD and ASE run at it; GROMACS, CP2K and LAMMPS draw Maxwell velocities at it, and GROMACS couples at it through the ref-t it writes into the mdp. The temperature sets the Boltzmann distribution the ensembles sample, the velocities a shooting move draws and the energy criterion of the acceptance, so paths sampled at two temperatures are not samples of one distribution.

The [tis] settings that select the distribution of the shooting draws, zero_momentum and rescale_energy, are compared on the draws the two runs make (_check_velocity_draws()).

The timestep and the subcycle count fix the time grid the estimator assumes. Different numerical trajectories do not by themselves prove different statistics, but a changed grid cannot be silently pooled. The order parameter and the exchange format complete the list of the contract. The order parameter is compared on its whole [orderparameter] table, its class and every setting the class reads (the particle index, the dimension, the periodicity, …): a different order parameter is a different reaction coordinate, so the saved per-ensemble state describes windows in a quantity the continuation leaves uncomputed. The exchange format decides the precision a configuration survives a round trip at, and so whether a shooting point reproduces the frame it was drawn from.

pyretis.bin.pyretisrun.RESUME_MISSING_VALUE_REASONS = {(False, False): 'neither', (False, True): 'previous', (True, False): 'continuation'}¶: The reason of RESUME_UNVERIFIED_REASONS for a locked setting one run or both runs hold no value for, keyed by (the previous run holds a value, the continuation holds a value).

pyretis.bin.pyretisrun.RESUME_UNVERIFIED_REASONS = (('previous', 'not recorded by the previous run', 'An archive written before a setting was persisted, or a run whose engine took it from its own input, cannot be checked.'), ('continuation', 'recorded by the previous run and not by the continuation', 'The continuation runs with the value its engine takes from its own input or its own default.'), ('neither', 'recorded by neither run', 'Compare the two inputs by hand.'), ('engine', 'applies to the engine of one of the two runs only (engine class {before!r} -> {after!r})', 'The engine of the other run takes no such setting.'), ('stream', 'set for a module engine, which the previous run streamed with [engine] subcycles if it is an internal integrator', 'The state file does not record "subcycles_rule" in its [current] provenance, the mark of a run whose internal integrators stream with the subcycles of their own section. Compare the two inputs by hand.'))¶: Why a locked setting could not be compared on a resume, as (reason, clause, advice): the warning names the settings, the clause and ends with the advice. previous, continuation and neither name the run(s) without a value for a setting that applies to both engines; engine is a setting that applies to the engine of one run only; stream is the subcycles of a module engine of a section other than [engine] in a previous run without pyretis.core.provenance.SUBCYCLES_RULE_KEY, when the section does not hold the subcycles of [engine] (_previous_stream_rule()).

pyretis.bin.pyretisrun.SCHEDULER_STATE_FILES = ('output.toml', 'restart.toml')¶: The state files of a scheduler simulation in its run directory: output.toml, and the legacy restart.toml. A method = "restart" continuation continues the simulation from either (see _stage_continuation()), and pyretis run -i from a run file with the canonical sections of the run (resume_run_file()).

pyretis.bin.pyretisrun._check_resume_compatibility(resume_file, previous, config)¶

Refuse a continuation that changes a setting it must not.

The locked settings of the two runs (_locked_settings()) are compared one by one (_locked_comparison()). A setting that applies to the engine of its section in both runs (_locked_setting_applies()) is compared on the value each run uses (_locked_value()): the value the section gives, or the default the engine runs with when it gives none. The previous run used the subcycles of [engine] for an internal integrator of another section when its state lacks pyretis.core.provenance.SUBCYCLES_RULE_KEY (_previous_locked_value()), which a refusal of such a setting says. A setting that applies to the engine of neither run is skipped. Every other case is reported as UNKNOWN rather than passed: absent metadata means compatibility could not be verified, which is not the same as verified compatible. The warning names the reason, from RESUME_UNVERIFIED_REASONS: the previous run, the continuation or neither run has a value, the setting applies to the engine of one run only, or it is the subcycles of a module engine the previous run may have streamed with [engine] subcycles. That is a warning and not a refusal, because every archive written before the setting was persisted would otherwise become unresumable. The ensemble layout (RESUME_LOCKED_LAYOUT) is compared for every run (_layout_changes()), and so are the engine sections each ensemble takes its MD from and their classes (_engine_pool_changes()).

Parameters:

resume_file (string) – The state file being resumed from, named in the diagnostics.
previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.

Raises:

ValueError – If a locked setting applies to the engine of both runs and the two runs use different values for it, if the two runs have different ensemble layouts, or if they take the MD of an ensemble from different engine sections or classes.

pyretis.bin.pyretisrun._check_velocity_draws(resume_file, previous, state, config)¶

Refuse a continuation that draws the shooting velocities differently.

[tis] zero_momentum and rescale_energy select the distribution of every shooting draw, and the paths the ensembles hold were shot with the draws of the previous run. Those are the draws its tis_set selects when its state carries pyretis.core.velocity_draws.VELOCITY_RULE_KEY, and the draws of pyretis.core.velocity_draws.unmarked_draws() otherwise; the continuation draws as its tis_set selects. [simulation] allow_setting_change skips the comparison, as it skips _check_resume_compatibility(), which says so.

Parameters:

resume_file (string) – The state file being resumed from, named in the diagnostics.
previous (dict) – The previous run’s persisted configuration.
state (dict) – Its [current] section.
config (dict) – The continuation’s translated configuration.

Raises:

ValueError – If the continuation draws the shooting velocities from another distribution than the previous run (pyretis.core.velocity_draws.refuse_changed_draws()).

pyretis.bin.pyretisrun._comparable(value)¶

Return a locked value in the form both records of it share.

A configuration read back from TOML holds neither None nor a tuple: a setting that is None is absent from it, and a tuple is a list. Both values of a comparison are brought to that form, so a table such as [orderparameter] compares equal exactly when its settings do.

Parameters:: value (object) – A locked value, as _locked_value() returns it.
Returns:: out (object) – The value with the None settings of a table left out and every tuple turned into a list.

pyretis.bin.pyretisrun._describe_change(key, before, after)¶

Describe how a continuation changes a locked setting.

Parameters:

key (string) – The setting’s input key, as _locked_key_name() names it.
before (object) – The value of the previous run, as _recorded() returns it.
after (object) – The value of the continuation, in the same form.

Returns:

out (string) – The setting and its two values; for a table, each setting of the table that differs.

pyretis.bin.pyretisrun._dig(config, path)¶: Return a nested config value, or None if any level is absent.

pyretis.bin.pyretisrun._discard_stale_state(output_file, legacy_restart)¶

Remove the state files that would make a LATER run resume.

A fresh run rewrites output.toml itself, but its .prev and .tmp siblings and the legacy restart.toml would survive it and be picked up as a resume point by the next run. That is the silent failure this guards against: a new calculation continuing someone else’s cycle count without saying so.

Parameters:

output_file (string) – The run file this run will write.
legacy_restart (string) – The legacy restart.toml path.

Returns:

out (list of string) – The files actually removed, in the order they were removed.

pyretis.bin.pyretisrun._engine_class_name(config, section='engine')¶

Return the class of an engine section of a configuration, lower case.

Parameters:

config (dict) – A translated or persisted configuration.
section (string, optional) – The engine section; engine by default.

Returns:

out (string) – The class name in lower case, the key pyretis.engines.factory.create_inf_engine() looks the engine up by; an empty string when the section names no engine class.

pyretis.bin.pyretisrun._engine_input_advice(settings, config)¶

Return the advice for settings a continuation’s engine reads itself.

Parameters:

settings (list of (string, tuple of strings)) – Locked settings, as (description, input key).
config (dict) – The continuation’s translated configuration.

Returns:

out (list of strings) – The advice of RESUME_ENGINE_INPUT_SETTINGS for each setting that the continuation leaves out and the engine of its section reads from its own input.

pyretis.bin.pyretisrun._engine_parameters(config, section='engine')¶

Return the constructor parameters of the engine of a section.

The class is resolved through pyretis.engines.factory.build_engine_map(), the map pyretis.engines.factory.create_inf_engine() builds the engine from.

Parameters:

config (dict) – A translated or persisted configuration.
section (string, optional) – The engine section; engine by default.

Returns:

out (set of strings or None) – The parameter names of the engine constructor; None when the class is not in the map (a module-provided engine, whose class is imported when the run starts, or a section that names no engine class).

pyretis.bin.pyretisrun._engine_pool_changes(previous, config)¶

Return how the engines of the ensembles of two runs differ.

Each ensemble takes its MD from the engine sections of its entry of [simulation] ensemble_engines (_ensemble_engines()), so the two runs name the same sections for each ensemble, and each section other than [engine] holds the same engine class in both runs. The locked settings of those sections are compared as the ones of [engine] (_locked_settings()).

Parameters:

previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.

Returns:

out (list of strings) – One description for each difference, naming the input key and the two values; empty when the two runs take their MD from the same engine sections and classes, and when a configuration holds neither the engines nor the interfaces of its ensembles, as the interfaces are compared only when both runs hold them.

pyretis.bin.pyretisrun._engine_section_value(config, section, key)¶

Return a key of an engine section as the scheduler reads it.

Parameters:

config (dict) – A scheduler configuration.
section (string) – The engine section.
key (string) – The key.

Returns:

out (object) – The value, or None when the section leaves the key out. The class of a built-in engine is compared in lower case, the case the engine map is looked up in; a module-provided class keeps its case.

pyretis.bin.pyretisrun._engine_stream_subcycles(previous)¶

Return the subcycles a run without the streaming rule used.

Parameters:: previous (dict) – The previous run’s persisted configuration.
Returns:: out (integer) – The subcycles of [engine], 1 when it leaves it out, as every internal integrator of a run without the mark of _streams_section_subcycles() read it.

pyretis.bin.pyretisrun._ensemble_engines(config)¶

Return the engine sections each ensemble of a run takes its MD from.

Parameters:: config (dict) – A scheduler configuration.
Returns:: out (list of lists of strings or None) – The [simulation] ensemble_engines of the configuration, or, when it holds none, the default the scheduler gives it (pyretis.simulation.setup.default_ensemble_engines()); None for a configuration that holds neither the engines nor the interfaces of its ensembles.

pyretis.bin.pyretisrun._is_engine_section(section)¶

Return whether an input section is an engine section.

Parameters:: section (string) – The name of the section.
Returns:: out (boolean) – True for [engine], [engine0] and the numbered engine sections of a pool (pyretis.inout.settings.is_pool_engine_section()).

pyretis.bin.pyretisrun._keep_failing_scratch(scratch_dir, cycle=None)¶

Rename a failing trial’s scratch directory so it is not overwritten.

The directory is renamed rather than copied: a trial’s trajectories can be large, and a rename is atomic and costs nothing, while a copy can fail or fill the disk on the way out of a run that is already stopping.

Parameters:

scratch_dir (string) – The engine scratch directory to keep.
cycle (integer, optional) – The cycle the run stopped on, used in the new name when known.

Returns:

out (string or None) – The path the scratch was renamed to, or None if it could not be renamed.

pyretis.bin.pyretisrun._layout_change(path, before, after)¶

Return how a refusal states a change of the ensemble layout.

Parameters:

path (tuple of strings) – The scheduler path of a setting of RESUME_LOCKED_LAYOUT.
before (object) – The value of the previous run.
after (object) – The value of the continuation.

Returns:

out (string) – The input keys the key table reads the setting from (pyretis.inout.key_table.input_keys()), what the setting fixes (RESUME_LAYOUT_MEANINGS) and the two values.

pyretis.bin.pyretisrun._layout_changes(previous, config)¶

Return how the ensemble layouts of two runs differ.

Parameters:

previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.

Returns:

out (list of strings) – One description for each setting of RESUME_LOCKED_LAYOUT the two runs hold different values for, naming the input keys that set it (_layout_change()). A setting a configuration does not hold is compared as False.

pyretis.bin.pyretisrun._locked_comparison(name, path, previous, config)¶

Return how a previous run and its continuation compare on a setting.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting.
previous (dict) – The previous run’s persisted configuration, with its [current] state.
config (dict) – The continuation’s translated configuration.

Returns:

out[0] (string) – skip for a setting that applies to the engine of neither run (_setting_applies_to_run()); a reason of RESUME_UNVERIFIED_REASONS for a setting the two runs cannot be compared on; same or changed for a setting compared on the value the previous run ran with (_previous_locked_value()) and the value the continuation runs with (_locked_value()).
out[1] (object) – The value of the previous run; None when it holds none, or when the setting is not compared on the values.
out[2] (object) – The value of the continuation; None when it holds none, or when the setting is not compared on the values.

pyretis.bin.pyretisrun._locked_key_name(path)¶

Return how a message names a locked setting.

Parameters:: path (tuple of strings) – The input key of the setting, e.g. ('tis', 'maxlength') or ('engine1', 'timestep').
Returns:: out (string) – The input key, as the input writes it (pyretis.inout.key_table.input_key_name()), e.g. [tis] maxlength or [engine1] timestep.

pyretis.bin.pyretisrun._locked_place(path)¶

Return where the scheduler configuration holds a locked input key.

Parameters:: path (tuple of strings) – The input key of a locked setting, as in RESUME_LOCKED_SETTINGS.
Returns:: out (tuple of strings) – The path of the scheduler configuration the key table carries the key to (pyretis.inout.key_table.scheduler_place()).

pyretis.bin.pyretisrun._locked_setting_applies(name, path, parameters)¶

Return whether a locked setting applies to a run.

A setting outside the engine sections applies to every run, and so do the time step and subcycles (RESUME_EVERY_ENGINE_SETTINGS). Any other engine setting applies when the constructor of the engine of its section takes it: gmx_format applies to the GROMACS engines. An engine whose constructor is not known here takes every engine setting, so a value it lacks is reported as UNKNOWN.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting; a key of an engine section is the keyword of the engine constructor of the same name.
parameters (set of strings or None) – The parameter names of the constructor of the engine of the section, as _engine_parameters() returns them.

Returns:

out (boolean) – True when the setting applies to the run.

pyretis.bin.pyretisrun._locked_settings(previous, config)¶

Return the locked settings a continuation is compared on.

The settings of RESUME_LOCKED_SETTINGS, and the engine settings among them for each engine section other than [engine] that the ensembles take their MD from, when the two runs name the same sections for each ensemble and the same class for the section (_engine_pool_changes() states every other case). When no ensemble of either run takes its MD from [engine], of the [engine] settings only those the analysis reads are compared (RESUME_ANALYSIS_ENGINE_SETTINGS).

Parameters:

previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.

Returns:

out[0] (list of (string, tuple of strings)) – The settings, as (description, input key): those of RESUME_LOCKED_SETTINGS in their order, then those of each other engine section in the order of the ensembles.
out[1] (boolean) – True when an ensemble of either run takes its MD from [engine] (_runs_engine_section()).

pyretis.bin.pyretisrun._locked_value(name, path, config)¶

Return the value a configuration runs a locked setting with.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting; the value is read at its place in the scheduler configuration (_locked_place()).
config (dict) – A scheduler configuration: the one a continuation runs with, or the one the state file of the previous run gives.

Returns:

out (object) – The recorded value. For a setting the configuration leaves out, the value the sampler (RESUME_LOCKED_DEFAULTS) or the engine of the section (RESUME_ENGINE_DEFAULTS) runs with, and None when neither table holds one.

pyretis.bin.pyretisrun._mark_high_accept_change(resume_file, previous, config, state)¶

Keep the paths held across a change of high_accept out of the data.

[tis] high_accept selects the acceptance rule of stone skipping, so a resume may change it, but the paths the ensembles hold at that point were accepted under the other rule. When an ensemble runs stone skipping before or after the resume (or the move lists are not recorded), each held path is re-tagged with pyretis.core.path.HELD_ACROSS_RULE_CHANGE, an initialisation code, in the persisted [current] generated record the resume restores the paths from; a path already carrying an initialisation code keeps it. The change is appended to [current] high_accept_changes in the state file, so the boundary can be read back from the run’s files.

Parameters:

resume_file (string) – The state file being resumed from, named in the diagnostics.
previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.
state (dict) – The persisted [current] state, updated in place.

Returns:

out (list of integers) – The path numbers that were re-tagged; empty when high_accept did not change.

Raises:

ValueError – If a held path has no recorded move, so it cannot be marked.

pyretis.bin.pyretisrun._pool_sections(engines)¶

Return the engine sections other than [engine] a run names.

Parameters:: engines (list of lists of strings) – The engine sections of each ensemble (_ensemble_engines()).
Returns:: out (list of strings) – Each section other than [engine], once, in the order of the ensembles.

pyretis.bin.pyretisrun._previous_locked_value(name, path, previous)¶

Return the value a previous run ran a locked setting with.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting.
previous (dict) – The previous run’s persisted configuration, with its [current] state.

Returns:

out (object) – For the subcycles an internal integrator of the previous run took from [engine] (_previous_stream_rule()), the subcycles of [engine], 1 when it leaves it out, as the engine read it; the value of _locked_value() otherwise.

pyretis.bin.pyretisrun._previous_stream_rule(name, path, previous)¶

Return where a previous run took a locked subcycles from.

In a run whose state lacks the mark of _streams_section_subcycles(), every internal integrator streamed with the subcycles of [engine], whatever section it was built from.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting.
previous (dict) – The previous run’s persisted configuration, with its [current] state.

Returns:

out (string or None) – 'engine' when the setting is the subcycles of an engine section other than [engine] whose class is a built-in internal integrator (pyretis.engines.factory.is_internal_integrator()) and the state lacks the mark: the engine streamed with [engine] subcycles. 'unknown' for such a section whose class is not in pyretis.engines.factory.build_engine_map(), a module engine, which streamed with [engine] subcycles if it is an internal integrator, when the section holds another value or none. None when the previous run took the setting from its own section (_locked_value()), or when the section of a module engine holds the value of [engine], which the engine ran with either way.

pyretis.bin.pyretisrun._read_previous_run(resume_file)¶

Return the scheduler configuration and state a previous run records.

A run file with the canonical sections of a run is read by pyretis.inout.run_record.load_run(): the key table builds the scheduler configuration of the previous run from the sections, and the scheduler defaults are applied to it, as the scheduler applies them to the configuration it runs. A state file of the scheduler configuration, the output.toml or restart.toml of an earlier PyRETIS with its [simulation.tis_set] table, holds the configuration that run ran with, defaults applied, and is taken as it is. The resume compares the two runs on these configurations: a locked input key at the scheduler path the key table carries it to (_locked_place()), the path the scheduler of the earlier PyRETIS read it from as well, and a refusal names the input key (pyretis.inout.key_table.input_keys()).

Parameters:: resume_file (string) – The run file of the previous run: an output.toml with the canonical sections of the run (pyretis.inout.run_record.is_run_record()), or a state file of the scheduler configuration, an output.toml or a legacy restart.toml.
Returns:: out (dict) – The scheduler configuration of the previous run, with its defaults applied (as the state file of the scheduler shape records them) and the [current] state of the file when it holds one.

pyretis.bin.pyretisrun._record_ss_weight_boundary(previous, state)¶

Record what wrote the rows before the stone-skipping weight boundary.

Every row of a state without SS_WEIGHT_RULE_KEY may carry the crossing count of a stone-skipping path, and the resume sets the boundary after them (pyretis.simulation.setup.setup_config()). The continuation may change the move list and the task, so the previous run’s settings and the paths held now are recorded under SS_WEIGHT_BEFORE_KEY for the analysis to read those rows with.

Parameters:

previous (dict) – The previous run’s persisted configuration.
state (dict) – The persisted [current] state, updated in place.

pyretis.bin.pyretisrun._recorded(value)¶

Return what a run records of a locked setting, or None.

Parameters:: value (object) – A locked value, as _locked_value() returns it.
Returns:: out (object or None) – The value as _comparable() returns it, and None for no value or for a table that holds no setting: such a table records nothing to compare.

pyretis.bin.pyretisrun._recorded_high_accept(config)¶: Return the high_accept a configuration runs its moves with.

pyretis.bin.pyretisrun._refuse_before_the_load(config, runpath)¶

Make the checks of the load of a new simulation before it starts.

The scheduler loads the initial paths of a new simulation with a fresh [current] and the configuration defaults applied (pyretis.simulation.setup.setup_config()), and the load checks the run directory before it reads or writes anything (pyretis.simulation.setup.refuse_before_staged_load()). The same checks are made here, on a copy of config prepared the same way, so a refusal comes before the run writes the record of its input.

Parameters:

config (dict) – The scheduler config the key table builds from the canonical form of the input, without a [current]. It is left unchanged.
runpath (string) – The directory the simulation runs from.

pyretis.bin.pyretisrun._refuse_beside_a_state_file(inputfile, runpath)¶

Refuse a new simulation in a run directory holding a state file.

The scheduler keeps the state of a simulation in a state file of the run directory (SCHEDULER_STATE_FILES), the [current] section, and a restart continues the simulation from it with the ensemble output, the paths and the CP2K wavefunction store beside it. A run of a legacy-runner input starts a new simulation, so it stops here, before the checks that name files of the run directory for removal, and every file stays in place. An output.toml without [current] records the settings of a run whose scheduler wrote no state; the new run writes its own record over it, as a run of a canonical input does.

Parameters:

inputfile (string) – The legacy-runner input of the new simulation.
runpath (string) – The directory the simulation runs from.

Raises:

ValueError – If the run directory holds a state file, a file of SCHEDULER_STATE_FILES with a [current] section. The message names it, how to continue that simulation, and how to start a new one: a run file with the canonical sections of the run is continued by pyretis run -i of it (pyretis.inout.run_record.is_run_record()), and a state file of the scheduler configuration by a canonical input of the simulation with [initial-path] method = "restart".

pyretis.bin.pyretisrun._refuse_to_overwrite_a_simulation(config, runpath, method)¶

Stop a new simulation where a simulation has sampled already.

kick and load start a new simulation: its ensemble output files and output.toml are written afresh. When one of those ensemble files records a sampled cycle, starting would erase the simulation that method = "restart" continues, so the run stops before initiation writes anything. The message names the ensemble directories, the method that continues the simulation, and how to start a new one.

Parameters:

config (dict) – The translated scheduler config of the new simulation, with its defaults applied.
runpath (string) – The directory the simulation runs from.
method (string) – The [initial-path] method of the new simulation.

Raises:

ValueError – When an ensemble directory of the new simulation holds a pathensemble.txt with a data row.

pyretis.bin.pyretisrun._refuse_to_record_over_the_input(inputfile, output_file)¶

Refuse a legacy-runner input that is the run file of its run.

A run of a legacy-runner input records the canonical form of the input in output.toml of the run directory, the run file the scheduler writes its state into. An input file of that name in the run directory would be replaced by the record of its run.

Parameters:

inputfile (string) – The legacy-runner input.
output_file (string) – The run file of the run directory.

Raises:

ValueError – If output_file is inputfile, by the same name or by another name of the same file (os.path.samefile()). The message asks for the input file to be renamed.

pyretis.bin.pyretisrun._reject_untranslated_scheduler_input(inputfile)¶

Fail with an actionable error on an input the scheduler cannot read.

run_infinite_swapping() reads two kinds of file. The run file of a canonical path-sampling run holds the canonical sections of a tis / retis / explore / pptis / repptis input, with or without the [current] state (the output.toml run_pyretis_path_sampling() and run_legacy_runner_config() write, see pyretis.inout.run_record). A file with a [simulation.tis_set] table is an input of the legacy-runner schema, which the scheduler set-up reads in its canonical form, or a state file of the scheduler configuration, the restart.toml or output.toml of an earlier PyRETIS, which it reads as it is. A canonical-shaped config that carries task = "infinite_swapping" (e.g. one produced by a converter version that preserved the schema’s routing marker instead of rewriting it to the canonical task) is neither, and would otherwise crash deep in apply_config_defaults with a bare KeyError('tis_set'). Detect that here and say how to fix it.

Parameters:: inputfile (string) – Path to the input TOML handed to the scheduler.

pyretis.bin.pyretisrun._report_execution_error(error, log_level)¶

Log a stopped execution and write its traceback to the log only.

Shared by both CLI flows (the in-process simulation and the infinite-swapping scheduler) so a failure is reported the same way regardless of which path ran. The friendly one-line message goes to the screen; the full traceback goes to the log file only.

Parameters:

error (Exception) – The exception currently being handled.
log_level (integer) – The active log level. At DEBUG or below the caller should re-raise so the traceback also reaches the screen.

Returns:

reraise (boolean) – True when the caller should re-raise (debug mode), so the error is never silently swallowed.

pyretis.bin.pyretisrun._report_short_path_evidence(error, cycle=None)¶

Surface the evidence a short-path stop carries, and preserve it.

ShortPathError attaches the offending path, the ensemble, its interfaces and where the path came from, so the failure can be explained afterwards. Every attribute it carries is logged here; path, shooting_point and scratch_dir are logged through what they describe (length, order span, status; order and index; the kept directory).

Parameters:

error (Exception) – The exception being handled. Anything that is not a ShortPathError is ignored.
cycle (integer, optional) – The cycle the run stopped on. It names the kept scratch directory when one is kept.

pyretis.bin.pyretisrun._runs_engine_section(config, section)¶

Return whether an ensemble of a run takes its MD from a section.

Parameters:

config (dict) – A scheduler configuration.
section (string) – The engine section.

Returns:

out (boolean) – True when an entry of the engines of the ensembles (_ensemble_engines()) names the section, and for a configuration that holds neither the engines nor the interfaces of its ensembles.

pyretis.bin.pyretisrun._sampled_ensemble_output(config, runpath)¶

Return the pathensemble.txt files of a sampled simulation.

A new simulation writes the output files of every ensemble directory it runs in afresh. These are the pathensemble.txt files among them that record a sampled cycle, and that the new simulation would therefore erase (pyretis.inout.pathensemble_output. sampled_ensemble_output()). The directories are the ones the scheduler writes for config (pyretis.inout.pathensemble_output. ensemble_output_dirs()). A run directory can hold the ensemble directories of other runs beside them: the single-ensemble TIS inputs make-tis-files writes run in one directory, each in its own ensemble directory.

Parameters:

config (dict) – The translated scheduler config of the new simulation, with its defaults applied.
runpath (string) – The directory the simulation runs from.

Returns:

out (list of string) – The pathensemble.txt files that hold a data row, in ensemble order.

pyretis.bin.pyretisrun._scheduler_worker_count(inputfile)¶

Return the worker count the scheduler will use for inputfile.

Resolved exactly like pyretis.inout.config_adapter. to_scheduler_config(): the environment override wins, then a [runner] section (legal canonical syntax), then the default of 1. Reports the effective count when routing a path-sampling config, so the progress line matches the run.

Parameters:: inputfile (string) – Path to the input TOML (already validated by is_path_sampling_config()).
Returns:: integer – The number of scheduler workers the run will start.

pyretis.bin.pyretisrun._setting_applies_to_run(name, path, config)¶

Return whether a locked setting applies to a run.

Parameters:

name (string) – The setting’s description in RESUME_LOCKED_SETTINGS.
path (tuple of strings) – The input key of the setting.
config (dict) – The run’s scheduler configuration.

Returns:

out (boolean) – _locked_setting_applies() with the constructor parameters of the engine of the setting’s section (_engine_parameters()) when the section is an engine section.

pyretis.bin.pyretisrun._settings_with_effect(settings)¶

Return a copy of parsed settings without the keys of no effect.

The keys and sections that take no effect on the run (pyretis.inout.key_table.keys_without_effect()) are left out: the settings parse of a file that holds them refuses it, and their value in parsed settings is the parse’s own (the parse adds an [engine0] section to every input, for instance).

Parameters:: settings (dict) – The parsed settings of a run.
Returns:: out (dict) – A copy of the settings without those keys and sections.

pyretis.bin.pyretisrun._stage_continuation(resume_file, restart_file, config, record=None)¶

Merge the new settings with the persisted scheduler state.

A restart continuation takes its SETTINGS from the new config (already translated by the caller into config) and only the running [current] state – cstep, RNG state, frac weights, the active path numbers and their birth-ensemble map – from the previous run’s state file. This restores the classic restart contract (settings from the input file, state from the restart file): resuming the previous run file verbatim would silently discard every setting change the continuation config makes (a new step target, a different engine or output options – e.g. the engine change the gromacs1-vs-gromacs2 example suite exercises).

Parameters:

resume_file (string) – Path to the previous run’s state file (output.toml, or a legacy restart.toml).
restart_file (string) – Path to the run file to write the merged config to (the run directory’s output.toml).
config (dict) – The translated scheduler config (defaults already applied), WITHOUT a [current] section. Mutated in place: the persisted [current] state is grafted onto it.
record (dict, optional) – The canonical sections of the continuation’s input (pyretis.inout.run_record.canonical_record()), which the run file records with the state. None writes config itself, with the state.

pyretis.bin.pyretisrun._streams_section_subcycles(previous)¶

Return whether a previous run marks its streaming rule of subcycles.

Parameters:: previous (dict) – The previous run’s persisted configuration, with its [current] state.
Returns:: out (boolean) – True when the [current] provenance of the state holds pyretis.core.provenance.SUBCYCLES_RULE_KEY (pyretis.core.provenance.has_subcycles_rule()): every internal integrator of the run streamed with the subcycles of its own engine section.
Raises:: ValueError – If the key holds a value other than pyretis.core.provenance.SUBCYCLES_RULE.

pyretis.bin.pyretisrun._tis_input_settings(ens_settings)¶

Return the settings of the TIS input make-tis-files writes.

The settings are a copy of the settings of the ensemble, with a human-friendly order-parameter name when the input gives none, and without the keys and sections that take no effect on the tis run (_settings_with_effect()).

Parameters:: ens_settings (dict) – The settings of the ensemble, with [simulation] task = "tis".
Returns:: out (dict) – The settings to write.

pyretis.bin.pyretisrun._unverified_groups(reason, settings)¶

Return the groups of unverified settings one warning each names.

Parameters:

reason (string) – A reason of RESUME_UNVERIFIED_REASONS.
settings (list of (string, tuple of strings)) – The settings of the reason, as (description, input key).

Returns:

out (list of lists) – For the engine reason, whose clause names the engine classes of a section, one group per engine section, in the order of the settings; for every other reason, the settings as one group. Empty when there are no settings.

pyretis.bin.pyretisrun._warn_unverified(resume_file, unverified, previous, config)¶

Warn about the locked settings a resume could not compare.

One warning is logged for each reason in RESUME_UNVERIFIED_REASONS that holds a setting, and for the engine reason one for each engine section (_unverified_groups()), naming each setting by its input key (_locked_key_name()). It ends with the reason’s advice, followed by the advice of _engine_input_advice() for the settings it names.

Parameters:

resume_file (string) – The state file being resumed from, named in the warnings.
unverified (dict) – The settings that could not be compared, as lists of (description, input key) keyed by reason.
previous (dict) – The previous run’s persisted configuration.
config (dict) – The continuation’s translated configuration.

pyretis.bin.pyretisrun.bye_bye_world()¶: Print out the goodbye message for PyRETIS.

pyretis.bin.pyretisrun.entry_point()¶: entry_point - The entry point for the pip install of pyretisrun.

pyretis.bin.pyretisrun.entry_point_deprecated()¶

Legacy pyretisrun entry point: warn, then run pyretis run.

The standalone pyretisrun command is kept working for now but is deprecated in favour of pyretis run; from PyRETIS 5 only the unified command will be supported. This wrapper emits that warning and then delegates to entry_point() unchanged.

pyretis.bin.pyretisrun.hello_world(infile, rundir, logfile)¶

Print out a politically correct greeting for PyRETIS.

Parameters:

infile (string) – String showing the location of the input file.
rundir (string) – String showing the location we are running in.
logfile (string) – The output log file

pyretis.bin.pyretisrun.holds_run_state(inputfile)¶

Tell whether an input is a run file with the state of a run.

Parameters:: inputfile (string) – Path to the input file.
Returns:: boolean – True for a .toml file with a [current] section, the state the scheduler writes into output.toml.

pyretis.bin.pyretisrun.is_infinite_swapping_config(inputfile)¶

Return True if the input selects the infinite-swapping sampler.

The infinite-swapping (replica-exchange) sampler is selected explicitly via [simulation] task = "infinite_swapping" (or a legacy alias). A recognised path-sampling task (_PATH_SAMPLING_TASKS: retis/tis/explore/pptis/repptis) is NEVER treated as infinite-swapping, even if its [runner] section is present – [runner] (worker count / multi-engine pools) is legal canonical syntax too, translated by pyretis.inout.config_adapter.to_scheduler_config() just like every other canonical section. Only an input with NO recognised task at all falls back to the [runner]-presence heuristic (the still-supported legacy runner schema, which never sets task). Only .toml inputs are considered; the in-process simulation flow handles everything else.

Parameters:: inputfile (string) – Path to the input file.
Returns:: boolean – True if the infinite-swapping scheduler should run this input.

pyretis.bin.pyretisrun.is_legacy_runner_config(inputfile)¶

Return True if inputfile is an input of the legacy-runner schema.

The structural marker is [simulation.tis_set] – the legacy runner schema’s own placement of its path-sampling knobs (vs. the canonical [tis]) – checked directly rather than inferred from task: real configs in the validation suite carry an explicit task = "infinite_swapping" for unambiguous routing while still using [simulation.tis_set] throughout, so task presence alone does not distinguish the two schemas here (pyretis.inout.run_record.is_legacy_runner_input()).

A restart continuation is excluded: it is always invoked by pointing -i directly at the scheduler’s own restart.toml (never the original config), which is already in the coordinator’s own shape (its [current] section is state, not input) and must not be re-normalized. Both the conventional filename and [current]’s presence are checked, since the restart-continuation convention in pyretis.simulation.setup.setup_config() already depends on the exact restart.toml name, not just this function.

Parameters:: inputfile (string) – Path to the input file.
Returns:: boolean – True if this is a fresh legacy-runner config that should be routed through run_legacy_runner_config().

pyretis.bin.pyretisrun.is_path_sampling_config(inputfile)¶

Return True if a canonical path-sampling TOML routes to the scheduler.

As of the Stage C collapse, canonical task = "retis" .toml inputs are run through the infinite-swapping scheduler at n_workers = 1 (their config is translated by pyretis.inout.config_adapter.to_scheduler_config()). The canonical tis, explore, pptis, and repptis tasks all route through the scheduler too (validated by VALIDITY, not byte-identity – the coordinator RNG differs from the in-process loop’s). Inputs that already select the infinite-swapping sampler are excluded. A canonical path-sampling config that hits a scheduler PORT GAP (see scheduler_port_gap()) returns False here and is rejected with a clear error by the caller – it is NOT dispatched to the retired in-process loop. Only .toml inputs are considered (a .rst input is not a scheduler config).

Parameters:: inputfile (string) – Path to the input file.
Returns:: boolean – True for a path-sampling .toml the scheduler can run.

pyretis.bin.pyretisrun.legacy_input_path_sampling_task(inputfile)¶

Return the path-sampling task of a legacy (non-TOML) input, or None.

The scheduler routing predicates (is_path_sampling_config(), is_infinite_swapping_config()) read .toml inputs only, so a legacy .rst path-sampling input skips them and would fall through to the retired in-process loop – crashing deep in PathSimulation.run() only after every ensemble output directory has already been created, with an error that names the very command the user just ran. The caller must instead translate such an input to its TOML twin (translate_legacy_input()) before routing, so the run proceeds through the scheduler like any canonical config.

The settings are parsed with defaults (a no-defaults parse crashes in the shared _finalise_settings post-processing for any input without a simulation/task entry – the very task-less case this helper must survive), so a malformed input raises the same error from here that set_up_simulation raises. The parse refuses a key that takes no effect on the run, as the parse of a TOML input does (pyretis.inout.settings.parse_settings_rst() with refuse_without_effect): the legacy input of every task is refused here, with the key to set instead where one is named, before it is translated or run. The default task is md, so a task-less legacy input keeps its in-process route.

Parameters:: inputfile (string) – Path to the input file.
Returns:: string or None – The retired path-sampling task the legacy input selects, or None when translation does not apply: a .toml input (the scheduler routing owns those), a missing file (set_up_simulation raises its own descriptive error), or a legacy input whose task still runs in-process (md / md-flux / make-tis-files / …).

pyretis.bin.pyretisrun.main(infile, indir, exe_dir, progress, log_level)¶

Execute PyRETIS.

Parameters:

infile (string) – The input file to open with settings for PyRETIS.
indir (string) – The folder containing the settings file.
exe_dir (string) – The directory we are working from.
progress (boolean) – Determines if we should use a progress bar or not.
log_level (integer) – Determines if we should display the error traceback or not.

pyretis.bin.pyretisrun.make_tis_files(_, settings, progress=False)¶

Create TIS simulations input files PyRETIS.

It just writes out input files for single TIS simulations and: exit without running a simulation.

Parameters:: settings (list of dicts or Simulation objects) – The settings for the simulations.

pyretis.bin.pyretisrun.remove_exit_file(exit_file)¶: Remove the EXIT file after a completed soft exit.

pyretis.bin.pyretisrun.resume_run_file(inputfile, progress=False)¶

Resume the simulation a run file records, as pyretis run -i.

The run file holds the canonical sections of the run and its [current] state; the scheduler builds its configuration from the sections (pyretis.inout.run_record.load_run()) and continues from the state, up to [simulation] steps.

Parameters:

inputfile (string) – Path to the run file, e.g. output.toml.
progress (boolean, optional) – If True, display a progress bar over the sampling cycles.

Raises:

ValueError – If the file holds no canonical sections of a run (see pyretis.inout.run_record.is_run_record()): a state file of the scheduler configuration, with [simulation.tis_set], or a state without a [simulation] task. A method = "restart" continuation reads the state of such a file.

pyretis.bin.pyretisrun.run_generic_simulation(sim, sim_settings, progress=False)¶

Run a generic PyRETIS simulation.

These are simulations that are just going to complete a given number of steps. Other simulation may consist of several simulations tied together and these are NOT handled here.

Parameters:

sim (object like Simulation) – This is the simulation to run.
sim_settings (dict) – The simulation settings.
progress (boolean, optional) – If True, we will display a progress bar, otherwise, we print results to the screen.

pyretis.bin.pyretisrun.run_infinite_swapping(inputfile, progress=False, initiated=False)¶

Run an infinite-swapping (replica-exchange) input via its scheduler.

This is the programmatic entry for the infinite-swapping sampler (the scheduler + config loader), run from the current working directory. pyretisrun calls it for inputs that select infinite swapping, so it is the single way to drive that sampler. The scheduler set-up (pyretis.simulation.setup.setup_config()) reads an input of the legacy-runner schema in its canonical form, with the deprecation notice, so the run file of the run holds the canonical sections.

Parameters:

inputfile (string) – Path to the infinite-swapping input TOML.
progress (boolean, optional) – If True, display a progress bar over the sampling cycles (restart-aware: a resumed run starts the bar at its restored cycle) instead of relying on the log only.
initiated (boolean, optional) – True when the caller has just generated the initial paths of this new simulation into the per-ensemble store, having refused before its initiation a run directory with files of an earlier run, as run_pyretis_path_sampling() does. The value is handed to the load of the scheduler as pyretis.inout.staged_paths.INITIATED_PATHS_KEY, and True skips the checks of pyretis.simulation.setup.refuse_before_staged_load().

pyretis.bin.pyretisrun.run_legacy_runner_config(inputfile, runpath, progress=False)¶

Run a legacy-runner input in its canonical form.

The input is converted in memory with the validated conversion of python -m pyretis.tools.convert_legacy_schema (pyretis.tools.convert_legacy_schema.convert_legacy_document()): it is reshaped into the canonical schema, parsed by the parser of the canonical input, which refuses a key that takes no effect on the run and names the key of the input with the canonical one, and checked against the scheduler configuration of the input. A conversion that fails the check stops the run. The deprecation notice of the schema is logged once, first (pyretis.tools.convert_legacy_schema.warn_legacy_input()).

The canonical form then runs as a canonical input does: its canonical sections, every default resolved (pyretis.inout.run_record.canonical_record()), are written to output.toml of the run directory, and the scheduler builds its configuration from them (run_infinite_swapping()) and records its state with them. pyretis run -i output.toml resumes the run, and the canonical form of the input with [initial-path] method = "restart" continues it, as for a run of a canonical input. A legacy-runner input has no [initial-path] section: the run starts from the initial paths placed in the run directory, and no engine of the run runs before the scheduler loads them. The record holds the [initial-path] of the canonical form, method = "kick" (pyretis.inout.config_adapter.normalize_legacy_schema()), the initiation of a new run of the canonical form.

The run stops before it writes a file in the run directory when:

the input file is the output.toml of the run directory (_refuse_to_record_over_the_input());
the run directory holds the state file of a simulation, which a restart continues (_refuse_beside_a_state_file()). This check leaves the files of that simulation in place;
the run directory holds a CP2K wavefunction store, which an earlier run wrote (pyretis.simulation.setup.refuse_left_wavefunction_store());
the conversion refuses the input;
the load of the new simulation refuses the run directory (_refuse_before_the_load()).

Parameters:

inputfile (string) – Path to the legacy-runner input TOML.
runpath (string) – The directory the simulation runs from, the working directory (where output.toml is written).

pyretis.bin.pyretisrun.run_md_flux_simulation(sim, sim_settings, progress=False)¶

Run a MD-FLUX simulation.

Parameters:

sim (object like Simulation) – This is the simulation to run.
sim_settings (dict) – The simulation settings.
progress (boolean, optional) – If True, we will display a progress bar, otherwise, we print results to the screen.

pyretis.bin.pyretisrun.run_md_simulation(sim, sim_settings, progress=False)¶

Run a MD simulation.

Parameters:

sim (object like Simulation) – This is the simulation to run.
sim_settings (dict) – The simulation settings.
progress (boolean, optional) – If True, we will display a progress bar, otherwise, we print results to the screen.

pyretis.bin.pyretisrun.run_pyretis_path_sampling(inputfile, runpath, progress=False)¶

Run a canonical RETIS config through the infinite-swapping coordinator.

This is the opt-in compatibility route. It translates the canonical configuration to the coordinator’s config dictionary (pyretis.inout.config_adapter.to_scheduler_config()) and generates the coordinator’s load_dir when requested. By default (method = "load", or "kick") this goes through the proven, sequential, single-process classic initiation (pyretis.inout.config_adapter.generate_load_dir()), unchanged. Opting into [initial-path] kick-parallel = true (with method = "kick" and kick-from = "initial", the default) instead routes through the parallel, engine-agnostic kick phase (pyretis.simulation.setup.run_kick_phase(), one job per ensemble across a worker pool) – proven so far only for engines that drive their kick search through propagate()/_propagate_from() (e.g. TurtleMD); internal engines’ own kick_across_middle is not yet streaming-aware, so kick-parallel stays opt-in rather than the default until that gap is closed. It then writes the canonical sections of the input, every default resolved (pyretis.inout.run_record.canonical_record()), to the single output.toml and hands it to the unchanged scheduler via run_infinite_swapping(), which builds its configuration from them.

A kick or load starts a new simulation, and stops with a ValueError before initiation when one of its ensemble directories holds a pathensemble.txt with data rows: those rows are the record of a simulation that method = "restart" continues (see _refuse_to_overwrite_a_simulation()). It stops with a FileExistsError before initiation when the run directory holds files of an earlier run that the new run would read: an initial path staged flat, the directory of an initial path in the per-ensemble store, or a CP2K wavefunction store (see pyretis.simulation.setup.refuse_before_initiation()). The scheduler then loads the paths the initiation generated (initiated of run_infinite_swapping()).

Parameters:

inputfile (string) – Path to the canonical RETIS input TOML.
runpath (string) – The directory the simulation runs from (where load and the translated output.toml are written).

pyretis.bin.pyretisrun.scheduler_port_gap(inputfile)¶

Return the scheduler port-gap reason for a canonical path-sampling TOML.

A path-sampling task (tis/retis/explore/pptis/repptis) whose config the scheduler cannot yet run (see scheduler_supported_features()) has NO execution path – the in-process loop is retired – so the caller must reject it with this reason rather than dispatch the retired loop. Returns None for inputs that are not path-sampling .toml tasks (md / md-flux / a .rst input / an infinite-swapping config), which run their normal route, and None for a canonical path-sampling config the scheduler does cover.

Parameters:: inputfile (string) – Path to the input file.
Returns:: string or None – The first unsupported-feature reason, or None.

pyretis.bin.pyretisrun.scheduler_supported_features(config)¶

Return (supported, reason) for routing a canonical retis config.

The infinite-swapping scheduler at n_workers = 1 faithfully reproduces the canonical RETIS loop for the kick- (or restart-) initialised internal-engine RETIS family with the sh/wt/wf/ ss shooting moves (wf/ss via the WHAM Cxy/HA unweighting on the per-ensemble-output route). Several classic features are still scheduler PORT GAPS and must keep the in-process loop until they are ported, so this helper detects them and reports the first one found:

shooting moves other than sh/wt/wf/ss.
the permeability mirror (mirror_freq) and target swap (target_freq) moves route through the scheduler but only at n_workers = 1 (both persist a global order-function mutation on accept).
an [initial-path] method of load for non-explore tasks.
a [simulation] restart continuation.

Parameters:: config (dict) – The parsed canonical TOML configuration.
Returns:: (boolean, string) – (True, '') when the scheduler faithfully covers the config; (False, reason) naming the first unsupported feature.

pyretis.bin.pyretisrun.set_up_simulation(inputfile, runpath)¶

Run all the needed generic set-up.

Parameters:

inputfile (string) – The input file which defines the simulation.
runpath (string) – The base path we are running the simulation from.

Returns:

runner (method) – A method which can be used to execute the simulation.
sim (object like Simulation) – The simulation defined by the input file.
syst (object like System) – The system created.
sim_settings (dict) – The input settings read from the input file.

pyretis.bin.pyretisrun.soft_exit_ignore(turn_keyboard_interruption_off=True, exe_dir=None)¶

Manage the KeyboardInterrupt exception.

Parameters:

turn_keyboard_interruption_off (boolean) – If True, instead of regular exiting from the program, the file ‘EXIT’ is created to stop the PyRETIS.
exe_dir (string, optional) – The path where EXIT file is expected.

pyretis.bin.pyretisrun.store_simulation_settings(settings, indir, backup, ext='.rst')¶

Store the parsed input settings.

The file holds the settings without the keys and sections that take no effect on the run (_settings_with_effect()), so the settings parse reads it as an input.

Parameters:

settings (dict) – The simulation settings.
indir (string) – The directory which contains the input script.
backup (boolean) – If True, an existing settings file will be backed up.
ext (string) – Extension for the regenerated settings dump. Matches the input file extension, so a .toml run writes out.toml and a .rst run writes out.rst. Defaults to .rst for backwards compatibility.

pyretis.bin.pyretisrun.translate_legacy_input(inputfile, task)¶

Translate a legacy path-sampling input to its TOML twin and return it.

Path sampling runs only through the scheduler, which reads TOML, so a legacy .rst input is translated to <stem>.toml with the same round-trip-validated converter behind python -m pyretis.tools.convert_settings. The legacy file is left untouched. If the twin already exists it is REUSED when it parses to the same raw settings as the legacy input (the run then behaves identically however it was invoked); a twin with DIFFERENT content is refused – two conflicting inputs for one run, and guessing which is the truth is exactly the kind of silent wrong answer this codebase forbids.

Parameters:

inputfile (string) – The legacy (non-TOML) input file.
task (string) – The path-sampling task it selects (for the log/error text).

Returns:

string – The path of the TOML input to run instead.

pyretis.bin.pyretisrun.use_tqdm(progress)¶

Return a progress bar if we want one.

Parameters:: progress (boolean) – If True, we should use a progress bar, otherwise not.
Returns:: out (object like tqdm.tqdm) – The progress bar, if requested. Otherwise, just a dummy iterator.

pyretis.bin.pyretisclean module ¶

pyretisclean - Remove the artifacts of a PyRETIS run.

This is the implementation behind pyretis tools clean. It deletes the output a PyRETIS run leaves in a directory (logs, out.toml / out.rst, restart files, the NNN ensemble directories, report, byte-code caches, …), so an example or run directory can be reset to its committed inputs. A per-directory clean.toml extends or overrides the built-in defaults; see pyretis.inout.clean.

usage: pyretis tools clean [-h] [–dry-run] [directory]

The pieces are factored so both the canonical pyretis tools clean sub-command (pyretis.bin.pyretistools) and the deprecated pyretis clean alias share one argument definition and one runner.

pyretis.bin.pyretisclean.add_clean_arguments(parser)¶

Add the clean arguments to an argument parser.

Parameters:: parser (argparse.ArgumentParser) – The parser (or sub-parser) to extend with the directory positional and the --dry-run flag.
Returns:: argparse.ArgumentParser – The same parser, for convenience.

pyretis.bin.pyretisclean.entry_point()¶

Entry point for the deprecated pyretis clean alias.

pyretis clean still works but is deprecated in favour of pyretis tools clean; it prints a one-line notice and then runs.

pyretis.bin.pyretisclean.main(argv=None)¶

Parse clean arguments and run it.

Parameters:: argv (list of str, optional) – The argument list (default: sys.argv[1:]).

pyretis.bin.pyretisclean.run_clean(args)¶

Clean a directory and report what was removed.

Parameters:: args (argparse.Namespace) – Parsed arguments; uses args.directory and args.dry_run.

pyretis.bin.pyretisanalyse module ¶

pyretisanalyse - An application for analysing PyRETIS simulations.

This script is a part of the PyRETIS library and can be used for analysing the result from simulations.

usage: pyretisanalyse.py [-h] -i INPUT [-V] [-f LOG_FILE] [-l LOG_LEVEL]

optional arguments:

-h, --help: show this help message and exit
-i INPUT, --input INPUT: Location of PyRETIS input file
-V, --version: show program’s version number and exit
-f LOG_FILE, --log_file LOG_FILE: Specify log file to write
-l LOG_LEVEL, --log_level LOG_LEVEL: Specify log level for log file

pyretis.bin.pyretisanalyse._countered_report_name(reportfile, report_base, counter)¶: Insert the archive counter before the cycle descriptor.

pyretis.bin.pyretisanalyse._format_cycle_suffix(cycles)¶: Return a file-name suffix for the number of analysed cycles.

pyretis.bin.pyretisanalyse._latest_report_pattern(report_base, extension)¶: Return a regexp matching uncountered latest report names.

pyretis.bin.pyretisanalyse._next_report_counter(path, report_base, extension)¶: Return the next free archive counter for a report family.

pyretis.bin.pyretisanalyse._path_cycles(result)¶: Return the cycle count from a path-ensemble analysis result.

pyretis.bin.pyretisanalyse._report_base(report_type, prefix=None)¶: Return the base name for a report without counter or cycles.

pyretis.bin.pyretisanalyse._report_counter_pattern(report_base, extension)¶: Return a regexp matching countered report archive names.

pyretis.bin.pyretisanalyse._run_wham_analysis(run_dir, report_dir, nskip=0)¶

Analyse infinite-swapping output (WHAM crossing probability).

Parameters:

run_dir (string) – The run directory: either a literal infswap_data.txt lives directly in it, or it holds the numbered per-ensemble output directories the matrix is reconstructed from – see pyretis.analysis.wham_analysis.get_path_data_matrix().
report_dir (string) – Directory the wham_analysis.txt report is written to.
nskip (int, optional) – Number of initial paths to discard as equilibration – the skip_initial_cycles analysis setting: the first nskip rows of a literal data file, or the first nskip paths of the run’s full path list, the initialisation paths included (see pyretis.analysis.wham_analysis.get_path_data_matrix()). Defaults to 0.

Returns:

int – 0 on success, 1 if the interfaces could not be read.

pyretis.bin.pyretisanalyse.backup_latest_reports(reportfile, report_base)¶: Back up uncountered reports from a report family.

pyretis.bin.pyretisanalyse.bye_bye_world()¶: Print out the goodbye message for PyRETIS.

pyretis.bin.pyretisanalyse.completed_cycles(analysis_results)¶: Return the number of cycles represented by an analysis result.

pyretis.bin.pyretisanalyse.configure_file_logging(log_file, log_level)¶: Add the analysis file logger and return the numeric log level.

pyretis.bin.pyretisanalyse.create_pdf_report(texfile, pdflatex='pdflatex', report_base=None)¶: Compile a LaTeX report to PDF if pdflatex is available.

pyretis.bin.pyretisanalyse.create_reports(settings, analysis_results, report_path)¶

Create some reports to display the output.

Parameters:

settings (dict) – Settings for analysis (and the simulation).
analysis_results (dict) – Results from the analysis.
report_path (string) – The path to the directory where the reports should be saved.

Yields:

out (string) – The report files created.

pyretis.bin.pyretisanalyse.entry_point()¶: entry_point - The entry point for the pip install of pyretisanalyse.

pyretis.bin.pyretisanalyse.entry_point_deprecated()¶

Legacy pyretisanalyse entry: warn, then run pyretis analyse.

The standalone pyretisanalyse command is kept working for now but is deprecated in favour of pyretis analyse; from PyRETIS 5 only the unified command will be supported. This wrapper emits that warning and then delegates to entry_point() unchanged.

pyretis.bin.pyretisanalyse.get_report_name(report_type, ext, prefix=None, path=None, cycles=None, counter=None)¶

Generate file name for a report.

Parameters:

report_type (string) – Identifier for the report we are writing.
ext (string) – Extension for the file to write.
prefix (string, optional) – A prefix to add to the file name. Usually just for marking reports with ensemble number for report_type equal to ‘tis-single’
path (string) – A directory to use for saving the report to.
cycles (int, optional) – Number of completed cycles represented by the report.
counter (int, optional) – Archive counter to insert before the cycle descriptor.

Returns:

out (string) – The name of the file written.

pyretis.bin.pyretisanalyse.hello_world(infile, run_dir, report_dir, log_file=None)¶

Output a standard greeting for PyRETIS analysis.

Parameters:

infile (string) – String showing the location of the input file.
run_dir (string) – The location where we are executing the analysis.
report_dir (string) – String showing the location of where we write the output.
log_file (string, optional) – The output log file.

pyretis.bin.pyretisanalyse.main(input_file, run_path, report_dir, skip_begin=None, skip_end=None)¶

Run the analysis.

Parameters:

input_file (string) – The input file with settings for the analysis.
run_path (string) – The location from which we are running the analysis.
report_dir (string) – The location where we will write the report.
skip_begin (int, optional) – Cycles to discard at the beginning of the sampling; overrides the [analysis] skip_initial_cycles setting. None (the default) leaves the setting alone.
skip_end (int, optional) – Cycles to discard at the end of the sampling; overrides the [analysis] skip_final_cycles setting. None (the default) leaves the setting alone.

pyretis.bin.pyretisanalyse.write_file(outname, report_txt, backup=True, report_base=None)¶

Write a generated report to a given file.

Parameters:

outname (string) – The name of the file to write/create.
report_txt (string) – This is the generated report as a string.
backup (boolean, optional) – If True, back up an existing report before writing the new one.
report_base (string, optional) – Base report name used to back up the previous uncountered report.

Returns:

out (string) – The name of the file written.

pyretis.bin.pyretisanalyse.write_traceback(filename)¶: Write the error traceback to the given file.

pyretis.bin.pyretisstatus module ¶

pyretis status - what a simulation is doing, per ensemble.

This answers the questions a scientist asks while a run is in progress, or right after it stops, without running the full analysis:

how much has each ensemble sampled?
how many trials were accepted, and how many rejected?
WHY were they rejected – which rejection dominates?
which moves are doing the work, and how well is each one accepted?
for the high-acceptance moves, what weight is collected per attempt?

It reads the per-ensemble output in place and computes nothing that needs the whole analysis machinery: no crossing probabilities, no rate, no matching. It is deliberately cheap, so it can be run against a directory while the simulation is still writing to it.

The trial records are read through pyretis.analysis.path_analysis._read_trials(), which is the one place that knows every layout PyRETIS has written – trials merged into pathensemble.txt, a separate trials.txt, or a classic run that wrote its rejections among the ordinary rows. Sitting on that function rather than parsing the files here means this command keeps working for old output, and keeps working if the layout changes again.

class pyretis.bin.pyretisstatus._FileEnsemble(directory)¶

Bases: object

A minimal stand-in for a path ensemble backed by a file.

The readers in pyretis.analysis.path_analysis need only a filename attribute, so a full PathEnsemble – which would require the simulation settings to build – is not needed here. That is what lets pyretis status run in a bare output directory.

__init__(directory)¶

Point the ensemble at a directory’s pathensemble file.

Parameters:: directory (string) – The ensemble’s output directory (000, 001, …).

pyretis.bin.pyretisstatus._fmt_cycles(status)¶

Return the sampled cycle range as text.

Parameters:: status (dict) – One ensemble’s status.
Returns:: out (string) – The range, or - when the ensemble recorded nothing.

pyretis.bin.pyretisstatus._fmt_ratio(value)¶

Return a ratio as text, or n/a when it is not defined.

A move that was never attempted has no acceptance ratio. Printing 0.000 or 1.000 there would be inventing a number, so it is reported as n/a.

Parameters:: value (float) – The ratio, possibly nan.
Returns:: out (string) – The formatted ratio.

pyretis.bin.pyretisstatus._json_safe(value)¶

Return a value with every NaN replaced by None.

json.dumps writes a bare NaN token, which is not JSON and is rejected by strict parsers (including jq and most languages’ standard libraries). A ratio that does not exist is null, which every parser understands and which keeps the “not attempted is not a ratio of one” distinction intact.

Parameters:: value (object) – A value, list or dict from the status report.
Returns:: out (object) – The same structure with NaN replaced by None.

pyretis.bin.pyretisstatus._occupancy_cycles(ensemble)¶

Return the first and last cycle the ensemble recorded.

Only occupancy rows are considered, since those are the rows that say what the ensemble held; a merged file also holds trial rows, and an older file holds only occupancy rows.

Parameters:: ensemble (object like _FileEnsemble) – The ensemble to read.
Returns:: out (tuple of (int or None, int or None, int)) – The first cycle, the last cycle, and the number of occupancy rows. The cycles are None when the file holds no rows.

pyretis.bin.pyretisstatus.build_settings(skip_begin, skip_end)¶

Return the analysis settings the readers expect.

Parameters:

skip_begin (int) – Cycles to discard at the start.
skip_end (int) – Cycles to discard at the end.

Returns:

out (dict) – The settings dictionary.

pyretis.bin.pyretisstatus.collect_ensemble_status(directory, settings)¶

Gather the status of a single ensemble.

Parameters:

directory (string) – The ensemble’s output directory.
settings (dict) – The analysis settings, read for the cycle window.

Returns:

out (dict) – The ensemble’s status, ready to print or to serialise.

pyretis.bin.pyretisstatus.entry_point()¶: Parse the arguments and run the status command.

pyretis.bin.pyretisstatus.find_ensemble_dirs(root)¶

Return the ensemble output directories found under a directory.

An ensemble directory is recognised by its name – 000, 001, and so on – and by containing a pathensemble file. Both tests are applied, so an unrelated numeric directory is not mistaken for an ensemble.

Parameters:: root (string) – The directory the simulation ran in.
Returns:: out (list of strings) – The ensemble directories, sorted by ensemble number.

pyretis.bin.pyretisstatus.format_moves(statuses)¶

Return the per-move breakdown for every ensemble.

Parameters:: statuses (list of dicts) – The per-ensemble statuses.
Returns:: out (list of strings) – The lines of the breakdown.

pyretis.bin.pyretisstatus.format_rejections(statuses)¶

Return the rejection breakdown for every ensemble.

Parameters:: statuses (list of dicts) – The per-ensemble statuses.
Returns:: out (list of strings) – The lines of the breakdown.

pyretis.bin.pyretisstatus.format_status(statuses, show_moves=True, show_rejections=True)¶

Return the full status report.

Parameters:

statuses (list of dicts) – The per-ensemble statuses.
show_moves (boolean, optional) – Whether to include the per-move breakdown.
show_rejections (boolean, optional) – Whether to include the rejection breakdown.

Returns:

out (string) – The report.

pyretis.bin.pyretisstatus.format_table(statuses)¶

Return the per-ensemble summary table.

Parameters:: statuses (list of dicts) – The per-ensemble statuses.
Returns:: out (list of strings) – The lines of the table.

pyretis.bin.pyretisstatus.get_parser()¶

Return the argument parser for pyretis status.

Returns:: out (object like argparse.ArgumentParser) – The parser.

pyretis.bin.pyretisstatus.main(args)¶

Run the status command.

Parameters:: args (object like argparse.Namespace) – The parsed arguments.
Returns:: out (int) – The exit code: zero on success, one when no ensemble output was found.

pyretis.bin.pyvisa module ¶

pyvisa - An application for analysing PyRETIS simulations.

This script is a part of the PyRETIS library and can be used for analysing the result from simulations.

Usage:

pyvisa.py [-h] [-i INPUT] [-V] [-cmp] [-data DATA] [-recalculate]
          [-oo] [-p] [-w N]

Optional arguments:

-cmp --pyvisa_compressor  compress raw simulation output to a .hdf5 file.
-data --pyvisa-data       select the data source (file or folder).
-h, --help                show this help message and exit.
-i INPUT, --input INPUT   location of PyRETIS input files
                          or PyVisA compressed file.
-oo --only_order          use only data from order.txt files (faster).
-p, --progress            show progress bars during recalculation.
-recalculate              recalculate order parameter and cv data.
-V, --version             show program's version number and exit.
-w N, --workers N         number of parallel worker processes for
                          recalculation (default: all CPU cores).

Flags may be combined. Valid combinations include:

pyvisa -i out.rst -cmp                       # compress only
pyvisa -i out.rst -cmp -oo                   # compress, order files only
pyvisa -i out.rst -recalculate               # recalculate only
pyvisa -i out.rst -recalculate -p            # recalculate with progress
pyvisa -i out.rst -recalculate -w 4          # recalculate with 4 workers
pyvisa -i out.rst -recalculate -p -w 4       # recalculate, progress, 4 wk
pyvisa -i out.rst -recalculate -data 000     # recalculate one ensemble
pyvisa -i out.rst -recalculate -cmp          # recalculate then compress
pyvisa -i out.rst -recalculate -cmp -oo      # recalc then compress (oo)
pyvisa -i out.rst                            # open GUI
pyvisa -i out.rst -data 000                  # open GUI with one ensemble

pyretis.bin.pyvisa.bye_pyvisa()¶: Print out the goodbye message for PyVisA.

pyretis.bin.pyvisa.entry_point()¶: entry_point - The entry point for the pip install of pyretisanalyse.

pyretis.bin.pyvisa.hello_pyvisa(run_dir, infile)¶

Output a standard greeting for PyVISA.

Parameters:

run_dir (string) – The location where we are executing the analysis.
infile (string) – String showing the location of the input file.

pyretis.bin.pyvisa.main(basepath, input_file, pyvisa_dict=None)¶

Run the analysis.

Parameters:

basepath (string) – The execution folder where the input files are.
input_file (string) – The input file with settings for the analysis.
pyvisa_dict (dictionary, optional) –

It determines the section of pyvisa to use, it contains:
- pyvisa_compressor, boolean If true, compress raw output to a .hdf5 file.
- pyvisa_data, str If given, the file or folder containing the files that will be used to feed to PyVisA.
- pyvisa_recalculate, boolean If true, use the recalculation tool to compute new op and cv values.
- only_order, boolean If true, use only data from order.txt files when compressing.
Flags may be combined: pyvisa_recalculate and pyvisa_compressor can both be set to run recalculation followed by compression in a single invocation. If neither is set, the visualization GUI is launched.

pyretis.bin.pyvisa.pyvisa_visual(basepath, input_file, pyvisa_dict)¶

Load data to PyVisA.

Parameters:

basepath (string) – The execution folder where the input files are.
input_file (string) – The input file with settings for the analysis.
pyvisa_dict (dictionary, optional) – It determines the section of pyvisa to use, it contains:

pyretis.bin.pyretistools module ¶

pyretis tools - auxiliary PyRETIS tools.

Dispatches the pyretis tools <tool> sub-commands:

pyretis tools init -i input.toml    # auto-place the interfaces
pyretis tools clean [directory]     # remove a run's artifacts

pyretis tools init runs the iterative infinit driver to place the TIS/RETIS interfaces automatically – it repeatedly runs a short infinite-swapping simulation, re-estimates the crossing probability with WHAM, and re-places the interfaces so every ensemble carries roughly the same local crossing probability (see pyretis.tools.interface_optimizer.run_infinit()).

pyretis tools clean removes the output a run leaves in a directory so it can be reset to its committed inputs (see pyretis.bin.pyretisclean / pyretis.inout.clean).

pyretis.bin.pyretistools.build_parser()¶

Build the argument parser for pyretis tools.

Returns:: argparse.ArgumentParser – The parser with one sub-parser per available tool.

pyretis.bin.pyretistools.entry_point()¶: Entry point for pyretis tools.

pyretis.bin.pyretistools.main(argv=None)¶

Parse pyretis tools arguments and dispatch the chosen tool.

Parameters:: argv (list of str, optional) – The argument list (default: sys.argv[1:]).
Returns:: int – A process exit code (0 on success, 2 when no tool was given).

pyretis.bin.pyretistools.run_init(args)¶

Run pyretis tools init (the infinit interface driver).

Parameters:: args (argparse.Namespace) – Parsed arguments; uses args.input and args.workdir.
Returns:: list of float – The interface set after the final iteration.

pyretis.bin¶

pyretis.bin.cli module¶

pyretis.bin.pyretisrun module¶

pyretis.bin.pyretisclean module¶

pyretis.bin.pyretisanalyse module¶

pyretis.bin.pyretisstatus module¶

pyretis.bin.pyvisa module¶

pyretis.bin.pyretistools module¶

pyretis.bin.cli module ¶

pyretis.bin.pyretisrun module ¶

pyretis.bin.pyretisclean module ¶

pyretis.bin.pyretisanalyse module ¶

pyretis.bin.pyretisstatus module ¶

pyretis.bin.pyvisa module ¶

pyretis.bin.pyretistools module ¶