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.MAKE_TIS_FILES_KEYS = ('simulation.task', 'simulation.zero_ensemble')

The keys make-tis-files sets in the settings of each ensemble itself.

pyretis.bin.pyretisrun._dotted_value(settings, key)

Return whether nested settings hold a dotted key, and its value.

Parameters:
  • settings (dict) – The nested settings.

  • key (string) – The dotted key, such as "output.order-file".

Returns:

  • out[0] (boolean) – True when the settings hold every part of the key.

  • out[1] (object) – The value of the key, or None when the settings do not hold it.

pyretis.bin.pyretisrun._ensemble_keys_without_effect(ens_settings, settings)

Return the keys of an ensemble section the TIS run ignores.

The settings of an ensemble are the general settings with the settings of its [[ensemble]] section on top. A key without effect on the tis run of the ensemble (pyretis.inout.key_table.keys_without_effect()) whose value in the settings of the ensemble differs from its value in the general settings (_same_value()) comes from the [[ensemble]] section: the settings parse judged the general settings, and _settings_with_effect() leaves such a key out of the TIS input. A section that sets a key to its value in the general settings, the parse’s default included, sets what the TIS run does without it. A value of None is the parse’s value of a key without a default, and the keys make-tis-files sets itself (MAKE_TIS_FILES_KEYS) are left out.

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

  • settings (dict) – The general settings of the make-tis-files input.

Returns:

tuple of (NoEffect, object) – The entries of the keys the TIS run refuses and their values (pyretis.inout.key_table.refused_settings()).

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._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._same_value(first, second)

Return whether two settings values are equal and of the same type.

The values are compared item by item, so true is not 1, in a list or a section as well.

Parameters:
  • first (object) – A value of settings.

  • second (object) – Another value of settings.

Returns:

boolean – True when the values are of the same type and equal, and so is each of their items.

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._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._tis_inputs(settings)

Return the TIS inputs make-tis-files writes, one per ensemble.

The settings of each ensemble are those of a tis run of that ensemble: [simulation] task = "tis" and zero_ensemble = false. The input of the TIS run of the ensemble NNN holds the settings with effect on that run (_tis_input_settings()) and the [simulation] seed of the input plus NNN, so the TIS runs draw independent streams.

Parameters:

settings (dict) – The settings of the make-tis-files input, with the settings of each ensemble in settings['ensemble'].

Returns:

list of tuple – For each ensemble, its number, its name NNN, the name of its input file and the settings to write into it.

Raises:

ValueError – If an [[ensemble]] section gives a key that takes no effect on the TIS run of its ensemble (_ensemble_keys_without_effect()), or a value that run does not take (pyretis.inout.settings.refused_values()). The message names the input file of each such run, and each key and value as the settings parse of that input refuses them.

pyretis.bin.pyretisrun._tis_run_settings(ens_settings)

Return the settings of the tis run of one ensemble.

The [tis] shooting_move of the ensemble is its entry of a [tis] shooting_moves list (pyretis.inout.settings.fill_up_tis_and_retis_settings()), and the settings leave a list with entries out: a tis run of one ensemble makes the move of the first entry of a list, and the move of shooting_move without one. The keys that take effect on the run are those of the move of its ensemble.

Parameters:

ens_settings (dict) – The settings of the ensemble, with [simulation] task = "tis".

Returns:

out (dict) – A copy of the settings, without a [tis] shooting_moves list with entries.

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.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 writes the input files of single TIS simulations (_tis_inputs()) and exits without running a simulation. An input whose [[ensemble]] sections give a setting the TIS run of their ensemble refuses gets no file.

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. A run file whose sections were edited after its run wrote them is resumed as a continuation from a changed input file, with its checks (_stage_edited_run_file()).

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. As _stage_edited_run_file() raises it for an edited run 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, staged=None)

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().

  • staged (bytes, optional) – The run file a continuation staged (_stage_continuation()), read in place of inputfile; the scheduler writes it, once the set-up checks pass, into output.toml of the working directory (InfSwapState.write_toml()), the run file itself when it is output.toml; a run file of another name is left as it is. None (the default) reads inputfile.

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. ASE) 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.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.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, skip_begin=0, skip_end=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.

  • skip_begin (int, optional) – Number of first cycles to leave out (equilibration) – the skip_initial_cycles analysis setting, counted as the crossing analysis counts it (see pyretis.analysis.wham_analysis.get_path_data_matrix()). Defaults to 0.

  • skip_end (int, optional) – Number of last cycles to leave out – the skip_final_cycles analysis setting. 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:
Returns:

out (integer) – 1 when an analysis did not run (pyretis.inout.analysisio.analysisio.stopped_analyses()), with an error that names it, and says whether the other analyses of the task completed; 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()); so does the flux analysis of an md-flux run that gives no flux. 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.

pyretis.bin.pyretisstatus.EARLIER_RUN_FILE_NAME = 'restart.toml'

The run file an earlier PyRETIS wrote in the directory of a run, in place of output.toml: the scheduler configuration and its [current] state.

pyretis.bin.pyretisstatus.PYRETIS3_RUN_FILE_NAME = 'out.rst'

the settings of the run, with its [simulation] task.

Type:

The file PyRETIS 3 wrote in the directory of a run

pyretis.bin.pyretisstatus.PYRETIS3_SEPARATE_RUN_TASKS = ('tis', 'make-tis-files')

The tasks of a PyRETIS 3 out.rst that name runs of one ensemble each: a tis run samples one ensemble, and the inputs make-tis-files writes are tis runs.

pyretis.bin.pyretisstatus.RUN_FILE_NAME = 'output.toml'

The run file the scheduler writes in the directory of a run (pyretis.simulation.repex.InfSwapState.write_toml()).

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, cycles=None)

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.

  • cycles (list of int, optional) – The cycles of the run the skips count (pyretis.inout.pathensemble_output.run_cycles()). When None, each ensemble counts the cycles its own file records.

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.ensembles_are_separate_runs(root)

Say whether each ensemble directory holds a run of its own.

A single TIS run (a tis task with three interfaces, as each input make-tis-files writes) samples one ensemble. Such runs share their directory, each one in its own ensemble directory, and the run file there holds the run made last. pyretis analyse of the make-tis-files input counts the cycles of each ensemble’s own file for these runs. Every other run file names one run that samples all the ensemble directories, and pyretis analyse counts the cycles of that run.

The run file is read in this order: output.toml, the restart.toml an earlier version of this PyRETIS wrote in its place (names_single_tis_run()), and the out.rst of PyRETIS 3 (names_pyretis3_separate_runs()). A directory with none of these files holds one run, as pyretis analyse counts every task but make-tis-files.

Parameters:

root (string) – The directory the simulation ran in.

Returns:

out (boolean) – True when the run file of root names single TIS runs; False when it names another run or no task (an out.rst without a task), or when root holds no run file.

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.pyretisstatus.names_pyretis3_separate_runs(run_file)

Say whether the out.rst of PyRETIS 3 names runs of one ensemble.

PyRETIS 3 wrote the settings of each run to the out.rst of its directory. The inputs make-tis-files writes there are tis runs of one ensemble each, which share the directory, and the out.rst holds the run made last (make-tis-files itself before any of them). Only the [simulation] task of the file is read, from its sections as the file holds them (pyretis.inout.settings.read_settings_sections()), so an out.rst with keywords this PyRETIS does not parse is read too. An out.rst without a task (for instance an empty file) names one run over the cycles of the run.

Parameters:

run_file (string) – The out.rst to read.

Returns:

out (boolean) – True when the [simulation] task of the file is one of PYRETIS3_SEPARATE_RUN_TASKS; False for another task or for a file without a task.

pyretis.bin.pyretisstatus.names_single_tis_run(run_file)

Say whether a run file names a single TIS run.

A run file with the input of the run (the output.toml this PyRETIS writes) names it by its task and interfaces (pyretis.inout.checker.is_single_tis()). A run file with the scheduler configuration (the output.toml and the restart.toml an earlier PyRETIS wrote) names it with [simulation] single_tis = true.

Parameters:

run_file (string) – The run file to read.

Returns:

out (boolean) – True when the [simulation] section of the run file names a single TIS run.

pyretis.bin.pyretisstatus.status_settings(root, directories, skip_begin, skip_end)

Return the analysis settings of the ensembles of a directory.

The skips count the cycles of the run, as for pyretis analyse: the cycles any ensemble file of the run records (pyretis.inout.pathensemble_output.run_cycles()), the same cycles for every ensemble. The ensembles of single TIS runs (ensembles_are_separate_runs()) are separate runs: each one counts the cycles its own file records.

Parameters:
  • root (string) – The directory the simulation ran in.

  • directories (list of strings) – The ensemble directories found in root (find_ensemble_dirs()).

  • skip_begin (int) – Cycles of the run to discard at the start.

  • skip_end (int) – Cycles of the run to discard at the end.

Returns:

out (dict) – The settings dictionary (build_settings()).

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.