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
pyretis analyse -i analysis.txt    # analyse output
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 deprecated standalone pyretisrun and pyretisanalyse commands, which run the same tools after a warning that PyRETIS 5 removes them; pyretis <command> -h shows the options. pyretis clean is 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 = {'biretis': 'the ensembles of states A and B and the shared ones', 'explore': 'an exploration without the [0^-] ensemble', 'interfaces_b': 'the interfaces of the ensembles of state B', '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', 'shared': 'the number of shared ensembles', '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', ('simulation', 'biretis')), ('interfaces_b', ('simulation', 'interfaces_b')), ('shared', ('simulation', 'shared')), ('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 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. 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.

temperature is the temperature of the run, [system] temperature, and engine temperature the temperature the engine of an engine section runs at. The internal integrators, TurtleMD and ASE run at [system] temperature; GROMACS, LAMMPS, CP2K, OpenMM and AMS run at the temperature their own input states, which the run set-up records as [system] temperature when the engines of the run agree, and else as the temperature of each engine section (pyretis.engines.run_temperature.resolve_run_temperature()). A continuation whose engine input states another temperature is compared on them (_temperature_comparison()). 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_TEMPERATURE_SETTINGS = ('temperature', 'engine temperature')¶: The settings of RESUME_LOCKED_SETTINGS that hold a temperature, compared by _temperature_comparison().

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.'), ('earlier', 'recorded by an earlier PyRETIS, which does not record the temperature the engines of the run ran at in full', 'The state file does not record "temperature_rule" in its [current] provenance: an engine that reads its temperature from its own input ran at its input of that run, which the file does not record, so an equal value does not verify it. Compare the engine inputs of the two runs by hand.'), ('partly', 'recorded by an earlier PyRETIS for a part of the run of its engine only', 'The state file does not record "temperature_rule" in its [current] provenance: a LAMMPS engine took the beta of its acceptance from the temperature of its engine section, and ran its dynamics at the lammps.in of that run, which the file does not record, so an equal value does not verify it. Compare the engine inputs of the two runs 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()); earlier is a temperature a previous run without pyretis.core.provenance.TEMPERATURE_RULE_KEY records, and that does not tell the temperature its engines ran at in full, and partly the temperature such a previous run records for the engine section of a LAMMPS engine, which used it for a part of its run only (_earlier_temperature_comparison()).

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: absent metadata means compatibility could not be verified. 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, so that a run file that records no value for the setting, as one of an earlier PyRETIS may, can be resumed. 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._compared_temperatures(before, after, exact)¶

Return how two temperatures of a resume compare.

Parameters:

before (float or None) – The temperature of the previous run.
after (float or None) – The temperature of the continuation.
exact (boolean) – True to compare a temperature an engine section gives as it is given; False to compare within the tolerance of pyretis.engines.run_temperature.temperatures_agree().

Returns:

out[0] (string) – A reason of RESUME_UNVERIFIED_REASONS for a temperature one run or both runs hold none of; same or changed otherwise.
out[1] (float or None) – before.
out[2] (float or None) – after.

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._earlier_temperature_comparison(name, path, earlier, run_after, sections)¶

Compare a continuation with an earlier run on a temperature.

The earlier run ran its engines as pyretis.engines.run_temperature.EarlierTemperatures describes. temperature compares the one temperature its engines that take [system] temperature ran at with [system] temperature of the continuation, within the tolerance. For a run whose engines all read their temperature from their own input, the temperature of each engine is compared by engine temperature; when the run file does not record the temperature of one of them, temperature is not verified, whatever the temperature of the continuation. engine temperature compares the temperature the engine of a section ran at, as the run file records it, with the temperature the engine of the continuation runs at; the section of an engine whose temperature the run file does not record is not verified, and is left to temperature for a run whose engines all read their temperature from their own input and a continuation that gives the section no temperature. Such a section that the run file gives a temperature is compared on it as it is given (_unrecorded_section_comparison()). The section of an engine that used the temperature the run file records for a part of its run only (pyretis.engines.run_temperature.EarlierTemperatures.partly_recorded, LAMMPS) is compared on it, and an equal value is not verified, with the reason partly of RESUME_UNVERIFIED_REASONS. A temperature an engine section gives, in the run file or in the continuation, is compared as it is given. Any other temperature that is not verified has the reason previous when the run file records none, and else the reason earlier.

Parameters:

name (string) – The setting’s description, one of RESUME_TEMPERATURE_SETTINGS.
path (tuple of strings) – The input key of the setting.
earlier (object like EarlierTemperatures) – The temperatures the engines of the earlier run ran at.
run_after (float or None) – [system] temperature of the continuation.
sections (tuple of (float or None)) – The temperature of the engine section of path in the previous run and in the continuation; None for temperature.

Returns:

out (tuple) – As _temperature_comparison() returns it.

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: a trial’s trajectories can be large, and a rename is atomic and costs nothing 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.

The temperatures (RESUME_TEMPERATURE_SETTINGS) apply to every engine, and are compared by _temperature_comparison() instead.

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._marked_temperature_comparison(name, path, previous, run_after, section_after)¶

Compare a continuation with a previous run that marks its temperatures.

temperature compares [system] temperature of the two runs, within the tolerance; a run whose engines run at different temperatures records none, and each engine section then records the temperature of its engine. engine temperature compares the temperature the engine of a section runs at: the temperature the section records, else [system] temperature. A temperature an engine section gives is compared as it is given. A section that neither run records a temperature of is compared by temperature.

Parameters:

name (string) – The setting’s description, one of RESUME_TEMPERATURE_SETTINGS.
path (tuple of strings) – The input key of the setting.
previous (dict) – The previous run’s persisted configuration.
run_after (float or None) – [system] temperature of the continuation.
section_after (float or None) – The temperature of the engine section of path in the continuation; None for temperature.

Returns:

out (tuple) – As _temperature_comparison() returns it.

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._previous_temperatures(resume_file, previous)¶

Return the temperatures the engines of an earlier previous run ran at.

Parameters:

resume_file (string) – The state file being resumed from, named in the refusal.
previous (dict) – The previous run’s persisted configuration, with its [current] state.

Returns:

out (object like EarlierTemperatures or None) – For a state without pyretis.core.provenance.TEMPERATURE_RULE_KEY, written by an earlier PyRETIS, the temperatures the engines of the sections the ensembles take their MD from (_run_engine_sections()) ran at (pyretis.engines.run_temperature.earlier_engine_temperatures()), with the class of each section that pyretis.engines.run_temperature.known_engine_class() knows. None for a state with the key, which records the temperature each engine runs at.

Raises:

ValueError – If the engines of the previous run that take [system] temperature ran at different temperatures. The message names each engine section and the temperature it ran at, and says that a new run is needed.

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, without the [particles.velocity] temperature the state of a run without the temperature_rule mark records, which is left out or refused as in a run file (pyretis.inout.run_record.leave_out_earlier_velocity_temperature()); its [system] temperature and the temperature of its engine sections are refused, with the mark or without it, when they are not finite, positive numbers (pyretis.engines.run_temperature.refuse_temperatures_not_numbers()). 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.
Raises:: ValueError – As pyretis.inout.run_record.load_run(), pyretis.engines.run_temperature.refuse_temperatures_not_numbers() and pyretis.inout.run_record.leave_out_earlier_velocity_temperature() raise it.

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 scheduler set-up refuses the engine sections the run cannot run (pyretis.simulation.setup.refuse_run_engines()) and more workers than live path ensembles (pyretis.simulation.setup.refuse_too_many_workers()). 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; the scheduler set-up logs the warnings of the engines.

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 and the paths 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._refuse_unrecorded_temperatures(resume_file, previous, settings)¶

Refuse a marked state that records no temperature for an engine.

A state with pyretis.core.provenance.TEMPERATURE_RULE_KEY records the temperature of its run as [system] temperature, and when its engines run at different temperatures the temperature of each engine section. A state that holds neither for an engine section the continuation is compared on gives no temperature to compare with.

Parameters:

resume_file (string) – The state file being resumed from, named in the refusal.
previous (dict) – The previous run’s persisted configuration, with its [current] state, which carries the key.
settings (list of (string, tuple of strings)) – The locked settings the continuation is compared on (_locked_settings()).

Raises:

ValueError – If the state records no [system] temperature and, for an engine section of settings, no temperature of the section.

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. a converted config that kept the routing marker of the legacy-runner schema) is neither. The scheduler set-up reads the [simulation.tis_set] table such a config lacks (pyretis.simulation.setup.apply_config_defaults()), so the config is refused here, with a message that says 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._run_engine_sections(config)¶

Return the engine sections the ensembles of a run take their MD from.

Parameters:: config (dict) – A scheduler configuration.
Returns:: out (list of strings) – Each section of the engines of the ensembles (_ensemble_engines()), once, in their order, that the configuration holds with a class; [engine] for a configuration that holds neither the engines nor the interfaces of its ensembles.

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: settings from the input file, state from the restart file. The setting changes 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) therefore take effect.

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._temperature_comparison(name, path, previous, config, earlier)¶

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

temperature compares the temperatures of the two runs, [system] temperature, and engine temperature the temperature the engine of an engine section runs at, for a previous run whose state carries pyretis.core.provenance.TEMPERATURE_RULE_KEY as it records them (_marked_temperature_comparison()), for one whose state lacks it as the earlier PyRETIS that wrote it ran them (_earlier_temperature_comparison()), and for one whose state lacks it and whose engine sections name no class on the temperatures it records (_unclassed_temperature_comparison()). Two values of [system] temperature are the same within the tolerance of pyretis.engines.run_temperature.temperatures_agree(); a temperature an engine section gives is compared as it is given.

Parameters:

name (string) – The setting’s description, one of RESUME_TEMPERATURE_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.
earlier (object like EarlierTemperatures or None) – The temperatures the engines of a previous run whose state lacks the key ran at (_previous_temperatures()); None for a state that carries it.

Returns:

out[0] (string) – skip for a temperature that is compared on another setting or that neither run records; a reason of RESUME_UNVERIFIED_REASONS for a temperature that cannot be compared; same or changed otherwise.
out[1] (object) – The temperature of the previous run, or None.
out[2] (object) – The temperature of the continuation, or None.

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._unclassed_temperature_comparison(name, path, previous, run_after, section_after)¶

Compare a continuation with an earlier run that names no engine class.

The state of the previous run lacks pyretis.core.provenance.TEMPERATURE_RULE_KEY, and no engine section of it names a class, so nothing tells how its engines ran: the two runs are compared on the temperatures they record. temperature compares [system] temperature within the tolerance, and a value one run records and the other does not is not verified. engine temperature compares the temperature the section gives, else [system] temperature, as it is given.

Parameters:

name (string) – The setting’s description, one of RESUME_TEMPERATURE_SETTINGS.
path (tuple of strings) – The input key of the setting.
previous (dict) – The previous run’s persisted configuration.
run_after (float or None) – [system] temperature of the continuation.
section_after (float or None) – The temperature of the engine section of path in the continuation; None for temperature.

Returns:

out (tuple) – As _temperature_comparison() returns it.

pyretis.bin.pyretisrun._unrecorded_section_comparison(section_before, run_after, section_after)¶

Compare a section given a temperature its engine may not have run at.

The run file gives the engine section a temperature, and does not record the temperature its engine ran at: the temperature took no effect on the engine, or the class of the engine is not known. The temperature is compared as it is given with the temperature of the section in the continuation, else [system] temperature of the continuation, so that a continuation that changes it or leaves it out for another temperature is refused. An equal value says nothing of the temperature the engine ran at, which is not verified.

Parameters:

section_before (float) – The temperature the run file gives the section.
run_after (float or None) – [system] temperature of the continuation.
section_after (float or None) – The temperature of the section in the continuation.

Returns:

out (tuple) – As _temperature_comparison() returns it: changed for another value, and else the reason earlier of RESUME_UNVERIFIED_REASONS, or the reason of a value the continuation does not hold.

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 of pyretis run.

pyretis.bin.pyretisrun.entry_point_deprecated()¶

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

The standalone pyretisrun command is deprecated in favour of pyretis run; the warning names PyRETIS 5 as the release that removes it. 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 its alias infswap or infretis). 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 (an input of the legacy runner schema need not set 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 marker is the [simulation.tis_set] table, in which the legacy-runner schema holds its path-sampling settings (a canonical input holds them in [tis]), whatever task the input sets (pyretis.inout.run_record.is_legacy_runner_input()).

A state file is excluded, so that it is not re-normalized: its [current] section is state, not input. Both a file named restart.toml (the state file of an earlier PyRETIS) and a document with a [current] section are excluded.

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.

Canonical .toml inputs of the retis, tis, explore, pptis and repptis tasks are run through the infinite-swapping scheduler (their config is translated by pyretis.inout.config_adapter.to_scheduler_config()). Inputs that select the infinite-swapping sampler (is_infinite_swapping_config()) are excluded. A canonical path-sampling config the scheduler cannot run (see scheduler_port_gap()) returns False here and is rejected with a clear error by the caller. 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, and a path simulation runs only through the scheduler (PathSimulation.run() raises). The caller therefore translates a legacy .rst path-sampling 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 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 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. The file tis-NNN of the ensemble NNN holds the [simulation] seed of the input plus NNN, so the TIS runs draw independent streams.

Parameters:: settings (dict) – The settings of the simulation, with the settings of each ensemble in settings['ensemble'].

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;
an engine section of the input integrates with an integrator a path-sampling run cannot use (pyretis.engines.run_temperature.refuse_path_sampling_inputs()), checked before the conversion reads a temperature of the input;
the conversion refuses the input;
the run cannot run an engine section of the input (an integrator a path-sampling run cannot use, a GROMACS engine without mdrun or wmdrun), or 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.

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 sequential, single-process initiation (pyretis.inout.config_adapter.generate_load_dir()). 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): engines that drive their kick search through propagate()/_propagate_from() (e.g. TurtleMD) kick from the bootstrap frame file, and OpenMM and the internal integrators kick a phase point with particles in memory as the sequential route does (pyretis.initiation.initiate_kick.run_parallel_kick_job()). kick-parallel is opt-in. 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 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, or the directory of an initial path in the per-ensemble store (see pyretis.simulation.setup.refuse_before_initiation()). The scheduler then loads the paths the initiation generated (initiated of run_infinite_swapping()).

Every route, a restart continuation included, stops with a ValueError before it writes a file of the run when an engine section of the run integrates with an integrator a path-sampling run cannot use, with a message that starts with the section, [engine1], or is a GROMACS engine without mdrun in an input without [runner] wmdrun (pyretis.simulation.setup.refuse_run_engines()). The input of each engine section is checked for such an integrator before a temperature is read (pyretis.engines.run_temperature.refuse_path_sampling_inputs()). A run with more [runner] workers than live path ensembles is refused there too (pyretis.simulation.setup.refuse_too_many_workers()). The warnings of the engines it accepts are logged once per engine section, after these checks: before the initiation of a new simulation, and by the scheduler set-up of a continuation.

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 why the scheduler cannot run a canonical path-sampling TOML.

A path-sampling task (tis/retis/explore/pptis/repptis) whose config the scheduler cannot run (see scheduler_supported_features()) has NO execution path, since path sampling runs only through the scheduler, so the caller rejects it with this reason. 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 runs a canonical path-sampling config unless the config uses a feature the scheduler cannot run. This helper detects those features and reports the first one found:

a shooting move the scheduler does not have (one outside pyretis.inout.key_table._INF_MOVE_CODES).
the permeability mirror (mirror_freq) and target swap (target_freq) moves at more than one worker: they route through the scheduler only at n_workers = 1 (both persist a global order-function mutation on accept).
an [initial-path] method that is not kick, restart, load or empty.
a [simulation] restart continuation without [initial-path] method = "restart".

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.
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. Their [system] temperature is the temperature the run runs at (pyretis.engines.run_temperature.resolve_run_temperature()), and a .toml file carries the table pyretis.core.provenance.STORED_SETTINGS_PROVENANCE (pyretis.core.provenance.stored_settings_provenance()), the mark of that record, as the run file of a path-sampling run carries it in its [current] state: the analysis reads the file as the record of its run (pyretis.inout.run_record.read_settings()). The settings parse leaves the table out. A .rst file carries no mark: the .rst format holds no such table.

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.

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 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]

[-skipb SKIPB] [-skipe SKIPE]

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

-skipb SKIPB (--skip-begin SKIPB) and -skipe SKIPE (--skip-end SKIPE) give how many cycles to discard at the beginning of the sampling (equilibration) and at its end (e.g. after an interrupted run); they override the [analysis] keywords skip_initial_cycles and skip_final_cycles of the input 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_biretis_analysis(settings, run_path, report_dir)¶

Analyse a biretis run and write its report.

Parameters:

settings (dict) – The settings of the run.
run_path (string) – The directory of the run.
report_dir (string) – The directory the report biretis_report.txt is written to.

Returns:

out (integer) –

Raises:

ValueError – If [analysis] method asks for an estimator other than the crossing probabilities.

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._stopped_analyses_status(results, task)¶

Say which analyses of a task did not run, and give the exit status.

Parameters:

results (object) – The results of pyretis.inout.analysisio.analysisio.run_analysis().
task (string) – The task of the run, as the message names it.

Returns:

out (integer) – 1 when an analysis did not run (pyretis.inout.analysisio.analysisio.stopped_analyses()), with an error that names it; 0 otherwise.

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 of pyretis analyse.

pyretis.bin.pyretisanalyse.entry_point_deprecated()¶

Standalone pyretisanalyse entry: warn, then run pyretis analyse.

The standalone pyretisanalyse command is deprecated in favour of pyretis analyse; the warning names PyRETIS 5 as the release that removes it. 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 the report of a tis run of one ensemble with its ensemble number.
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.

An analysis of the task that the settings let not run (the energy analysis of settings without [system] temperature) stops alone, with its message (pyretis.inout.analysisio.analysisio.run_analysis_files()); the other analyses complete and the reports are written, and the exit status is then 1.

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.

Returns:

out (integer) – 0 when every analysis ran; 1 when one failed or did not run.

pyretis.bin.pyretisanalyse.set_analysis_beta(settings)¶

Set the inverse temperature of the run the analysis reads.

The temperature of the run is [system] temperature. The run file output.toml (and out.toml of an MD run) records it for every run, with the temperature that an engine reading its temperature from its own input runs at (pyretis.engines.run_temperature.resolve_run_temperature()). The run file of a run an earlier PyRETIS ran is read at the temperature its engines ran at (pyretis.engines.run_temperature.read_analysed_temperatures()). An input file whose engines read their temperature from their own input can leave it out; the analysis of such an input file has no inverse temperature.

Parameters:: settings (dict) – The settings the analysis reads, with [system] units set and registered. [system] beta is set in place, to 1 / (k_B T) with the Boltzmann constant of [system] units, when [system] temperature is set.

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(), the one place that knows every layout of them: a moves.txt beside pathensemble.txt and, in the output of an earlier PyRETIS, trials merged into pathensemble.txt, a separate trials.txt, or rejections written among the ordinary rows. This command therefore reads every layout the analysis reads.

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, 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 of an earlier PyRETIS also holds trial rows, flagged in its Trial column, and those are skipped.

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 pyvisa.

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; pyvisa_data and only_order are read here (see main()).

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 ¶