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 thetisrun 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
DEBUGor below the caller should re-raise so the traceback also reaches the screen.
- Returns:
reraise (boolean) –
Truewhen 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.
ShortPathErrorattaches 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_pointandscratch_dirare 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
ShortPathErroris 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
trueis not1, 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
tisrun (_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
tisrun of that ensemble:[simulation] task = "tis"andzero_ensemble = false. The input of the TIS run of the ensembleNNNholds the settings with effect on that run (_tis_input_settings()) and the[simulation] seedof the input plusNNN, 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
tisrun of one ensemble.The
[tis] shooting_moveof the ensemble is its entry of a[tis] shooting_moveslist (pyretis.inout.settings.fill_up_tis_and_retis_settings()), and the settings leave a list with entries out: atisrun of one ensemble makes the move of the first entry of a list, and the move ofshooting_movewithout 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_moveslist 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
pyretisrunentry point: warn, then runpyretis run.The standalone
pyretisruncommand is deprecated in favour ofpyretis run; the warning names PyRETIS 5 as the release that removes it. This wrapper emits that warning and then delegates toentry_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. Amethod = "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.
pyretisruncalls 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 aspyretis.inout.staged_paths.INITIATED_PATHS_KEY, and True skips the checks ofpyretis.simulation.setup.refuse_before_staged_load().staged (bytes, optional) – The run file a continuation staged (
_stage_continuation()), read in place ofinputfile; the scheduler writes it, once the set-up checks pass, intooutput.tomlof the working directory (InfSwapState.write_toml()), the run file itself when it isoutput.toml; a run file of another name is left as it is. None (the default) readsinputfile.
- 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 tooutput.tomlof the run directory, and the scheduler builds its configuration from them (run_infinite_swapping()) and records its state with them.pyretis run -i output.tomlresumes 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.tomlof 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
mdrunorwmdrun), 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.tomlis 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’sload_dirwhen 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(withmethod = "kick"andkick-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 throughpropagate()/_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-parallelis opt-in. It then writes the canonical sections of the input, every default resolved (pyretis.inout.run_record.canonical_record()), to the singleoutput.tomland hands it to the scheduler viarun_infinite_swapping(), which builds its configuration from them.A
kickorloadstarts a new simulation, and stops with aValueErrorbefore initiation when one of its ensemble directories holds apathensemble.txtwith data rows: those rows are the record of a simulation thatmethod = "restart"continues (see_refuse_to_overwrite_a_simulation()). It stops with aFileExistsErrorbefore 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 (seepyretis.simulation.setup.refuse_before_initiation()). The scheduler then loads the paths the initiation generated (initiatedofrun_infinite_swapping()).Every route, a restart continuation included, stops with a
ValueErrorbefore 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 withoutmdrunin 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] workersthan 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
loadand the translatedoutput.tomlare 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] temperatureis the temperature the run runs at (pyretis.engines.run_temperature.resolve_run_temperature()), and a.tomlfile carries the tablepyretis.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.rstfile carries no mark: the.rstformat 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
.tomlrun writesout.tomland a.rstrun writesout.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
cleanarguments to an argument parser.- Parameters:
parser (argparse.ArgumentParser) – The parser (or sub-parser) to extend with the
directorypositional and the--dry-runflag.- Returns:
argparse.ArgumentParser – The same parser, for convenience.
- pyretis.bin.pyretisclean.entry_point()¶
Entry point for the deprecated
pyretis cleanalias.pyretis cleanis deprecated in favour ofpyretis tools clean; it prints a one-line notice and then runs.
- pyretis.bin.pyretisclean.main(argv=None)¶
Parse
cleanarguments 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.directoryandargs.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.txtis written to.
- Returns:
out (integer) –
- Raises:
ValueError – If
[analysis] methodasks 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.txtlives directly in it, or it holds the numbered per-ensemble output directories the matrix is reconstructed from – seepyretis.analysis.wham_analysis.get_path_data_matrix().report_dir (string) – Directory the
wham_analysis.txtreport is written to.skip_begin (int, optional) – Number of first cycles to leave out (equilibration) – the
skip_initial_cyclesanalysis setting, counted as the crossing analysis counts it (seepyretis.analysis.wham_analysis.get_path_data_matrix()). Defaults to 0.skip_end (int, optional) – Number of last cycles to leave out – the
skip_final_cyclesanalysis 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:
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, 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
pyretisanalyseentry: warn, then runpyretis analyse.The standalone
pyretisanalysecommand is deprecated in favour ofpyretis analyse; the warning names PyRETIS 5 as the release that removes it. This wrapper emits that warning and then delegates toentry_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
tisrun 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_cyclessetting.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_cyclessetting.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 fileoutput.toml(andout.tomlof 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] unitsset and registered.[system] betais set in place, to1 / (k_B T)with the Boltzmann constant of[system] units, when[system] temperatureis 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.rstthat name runs of one ensemble each: atisrun samples one ensemble, and the inputsmake-tis-fileswrites aretisruns.
- 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:
objectA minimal stand-in for a path ensemble backed by a file.
The readers in
pyretis.analysis.path_analysisneed only afilenameattribute, so a fullPathEnsemble– which would require the simulation settings to build – is not needed here. That is what letspyretis statusrun 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/awhen 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.dumpswrites a bareNaNtoken, which is not JSON and is rejected by strict parsers (includingjqand most languages’ standard libraries). A ratio that does not exist isnull, 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
Trialcolumn, 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
tistask with three interfaces, as each inputmake-tis-fileswrites) 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 analyseof themake-tis-filesinput 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, andpyretis analysecounts the cycles of that run.The run file is read in this order:
output.toml, therestart.tomlan earlier version of this PyRETIS wrote in its place (names_single_tis_run()), and theout.rstof PyRETIS 3 (names_pyretis3_separate_runs()). A directory with none of these files holds one run, aspyretis analysecounts every task butmake-tis-files.- Parameters:
root (string) – The directory the simulation ran in.
- Returns:
out (boolean) – True when the run file of
rootnames single TIS runs; False when it names another run or no task (anout.rstwithout a task), or whenrootholds 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.rstof PyRETIS 3 names runs of one ensemble.PyRETIS 3 wrote the settings of each run to the
out.rstof its directory. The inputsmake-tis-fileswrites there aretisruns of one ensemble each, which share the directory, and theout.rstholds the run made last (make-tis-filesitself before any of them). Only the[simulation] taskof the file is read, from its sections as the file holds them (pyretis.inout.settings.read_settings_sections()), so anout.rstwith keywords this PyRETIS does not parse is read too. Anout.rstwithout a task (for instance an empty file) names one run over the cycles of the run.- Parameters:
run_file (string) – The
out.rstto read.- Returns:
out (boolean) – True when the
[simulation] taskof the file is one ofPYRETIS3_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.tomlthis PyRETIS writes) names it by its task and interfaces (pyretis.inout.checker.is_single_tis()). A run file with the scheduler configuration (theoutput.tomland therestart.tomlan 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_recalculateandpyvisa_compressorcan 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_dataandonly_orderare read here (seemain()).
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 toolsarguments 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.inputandargs.workdir.- Returns:
list of float – The interface set after the final iteration.