pyretis.bin

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

pyretis.bin.cli module

pyretis - The unified PyRETIS command-line interface.

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

pyretis run -i input.toml         # run a simulation  (was pyretisrun)
pyretis analyse -i analysis.txt   # analyse output    (was pyretisanalyse)
pyretis clean                     # remove run artifacts in a directory

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

pyretis.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.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._apply_restart_steps(restart_file, steps)

Set the step target in a scheduler run file in place.

On a continuation the native config carries the new (usually higher) total step target. The scheduler stops once cstep reaches [simulation] steps, so a resumed restart must adopt the new target or it would have nothing left to run. This reads, updates and rewrites the run TOML (output.toml, or a legacy restart.toml), leaving every other key (the persisted current state – RNG, frac, active paths – and all settings) untouched.

Parameters:

• restart_file (string) – Path to the scheduler run file (output.toml or a legacy restart.toml).

• steps (int) – The new total step target to write into [simulation] steps.

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 native 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._warn_infretis_dialect_deprecated(inputfile)

Emit a single DeprecationWarning for infretis-flavour input.

Mirrors pyretis.inout.settings._warn_rst_deprecated()’s rst precedent: the legacy dialect keeps running (via the same normalize/translate pipeline every native config already goes through, see run_infretis_flavour_config()), this only warns.

pyretis.bin.pyretisrun.bye_bye_world()

Print out the goodbye message for PyRETIS.

pyretis.bin.pyretisrun.entry_point()

entry_point - The entry point for the pip install of pyretisrun.

pyretis.bin.pyretisrun.entry_point_deprecated()

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

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

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

Print out a politically correct greeting for PyRETIS.

Parameters:

• infile (string) – String showing the location of the input file.

• rundir (string) – String showing the location we are running in.

• logfile (string) – The output log file

pyretis.bin.pyretisrun.is_infinite_swapping_config(inputfile)

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

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

Parameters:

inputfile (string) – Path to the input file.

Returns:

boolean – True if the infinite-swapping scheduler should run this input.

pyretis.bin.pyretisrun.is_infretis_flavour_config(inputfile)

Return True if inputfile needs the infretis-flavour pipeline.

The structural marker is [simulation.tis_set] – the infretis-flavour dialect’s own placement of its path-sampling knobs (vs. native’s [tis]) – checked directly rather than inferred from task: real configs in the validation suite carry an explicit task = "infinite_swapping" for unambiguous routing while still using [simulation.tis_set] throughout, so task presence alone does not distinguish the two dialects here (see MERGE_TODO.md S5.6).

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

Parameters:

inputfile (string) – Path to the input file.

Returns:

boolean – True if this is a fresh infretis-flavour config that should be routed through run_infretis_flavour_config().

pyretis.bin.pyretisrun.is_native_scheduler_config(inputfile)

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

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

Parameters:

inputfile (string) – Path to the input file.

Returns:

boolean – True for a native path-sampling .toml the scheduler can run.

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

Execute PyRETIS.

Parameters:

• infile (string) – The input file to open with settings for PyRETIS.

• indir (string) – The folder containing the settings file.

• exe_dir (string) – The directory we are working from.

• progress (boolean) – Determines if we should use a progress bar or not.

• log_level (integer) – Determines if we should display the error traceback or not.

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

Create TIS simulations input files PyRETIS.

It just writes out input files for single TIS simulations and

exit without running a simulation.

Parameters:

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

pyretis.bin.pyretisrun.native_scheduler_port_gap(inputfile)

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

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

Parameters:

inputfile (string) – Path to the input file.

Returns:

string or None – The first unsupported-feature reason, or None.

pyretis.bin.pyretisrun.remove_exit_file(exit_file)

Remove the EXIT file after a completed soft exit.

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)

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.

Parameters:

inputfile (string) – Path to the infinite-swapping input TOML.

pyretis.bin.pyretisrun.run_infretis_flavour_config(inputfile, runpath)

Run a legacy infretis-flavour config via the native-schema pipeline.

Reshapes the raw infretis-flavour dict (pyretis.inout.config_adapter.normalize_infretis_dialect()), parses the result through the same strict native-schema validator every hand-written native TOML goes through (pyretis.inout.settings.parse_settings_toml()), translates it (pyretis.inout.config_adapter.native_to_infswap_config()), and hands the result to the unchanged scheduler via run_infinite_swapping() – the same three-stage pipeline run_pyretis_path_sampling() uses for native input, so both dialects now share one code path from this point on.

A restart continuation is excluded from this: it is always invoked by pointing -i directly at the scheduler’s own restart.toml (never the original config – setup_config itself refuses a fresh input file alongside an existing restart.toml), and restart.toml is already in the coordinator’s own shape, not a user-authored dialect needing translation.

Parameters:

• inputfile (string) – Path to the infretis-flavour input TOML.

• runpath (string) – The directory the simulation runs from (where the intermediate native-shaped TOML and the final translated infswap.toml are 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)

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

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

Parameters:

• inputfile (string) – Path to the native RETIS input TOML.

• runpath (string) – The directory the simulation runs from (where load and the translated output.toml are written).

pyretis.bin.pyretisrun.scheduler_supported_features(config)

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

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

• shooting moves other than sh/wt/wf/ss.

• the permeability mirror (mirror_freq) and target swap (target_freq) moves route through the scheduler but only at n_workers = 1 (both persist a global order-function mutation on accept).

• an [initial-path] method of load for non-explore tasks.

• a [simulation] restart continuation.

Parameters:

config (dict) – The parsed native TOML configuration.

Returns:

(boolean, string) – (True, '') when the scheduler faithfully covers the config; (False, reason) naming the first unsupported feature.

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

Run all the needed generic set-up.

Parameters:

• inputfile (string) – The input file which defines the simulation.

• runpath (string) – The base path we are running the simulation from.

Returns:

• runner (method) – A method which can be used to execute the simulation.

• sim (object like Simulation) – The simulation defined by the input file.

• syst (object like System) – The system created.

• sim_settings (dict) – The input settings read from the input file.

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

Manage the KeyboardInterrupt exception.

Parameters:

• turn_keyboard_interruption_off (boolean) – If True, instead of regular exiting from the program, the file ‘EXIT’ is created to stop the PyRETIS.

• exe_dir (string, optional) – The path where EXIT file is expected.

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

Store the parsed input settings.

Parameters:

• settings (dict) – The simulation settings.

• indir (string) – The directory which contains the input script.

• backup (boolean) – If True, an existing settings file will be backed up.

• ext (string) – Extension for the regenerated settings dump. Matches the input file extension, so a .toml run writes out.toml and a .rst run writes out.rst. Defaults to .rst for backwards compatibility.

pyretis.bin.pyretisrun.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 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 clean [-h] [–dry-run] [directory]

pyretis.bin.pyretisclean.entry_point()

Entry point for pyretis clean.

pyretis.bin.pyretisanalyse module

pyretisanalyse - An application for analysing PyRETIS simulations.

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

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

optional arguments:

-h, --help

show this help message and exit

-i INPUT, --input INPUT

Location of PyRETIS input file

-V, --version

show program’s version number and exit

-f LOG_FILE, --log_file LOG_FILE

Specify log file to write

-l LOG_LEVEL, --log_level LOG_LEVEL

Specify log level for log file

pyretis.bin.pyretisanalyse._countered_report_name(reportfile, report_base, counter)

Insert the archive counter before the cycle descriptor.

pyretis.bin.pyretisanalyse._format_cycle_suffix(cycles)

Return a file-name suffix for the number of analysed cycles.

pyretis.bin.pyretisanalyse._latest_report_pattern(report_base, extension)

Return a regexp matching uncountered latest report names.

pyretis.bin.pyretisanalyse._next_report_counter(path, report_base, extension)

Return the next free archive counter for a report family.

pyretis.bin.pyretisanalyse._path_cycles(result)

Return the cycle count from a path-ensemble analysis result.

pyretis.bin.pyretisanalyse._report_base(report_type, prefix=None)

Return the base name for a report without counter or cycles.

pyretis.bin.pyretisanalyse._report_counter_pattern(report_base, extension)

Return a regexp matching countered report archive names.

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

Analyse infinite-swapping output (WHAM crossing probability).

Parameters:

• run_dir (string) – The run directory: either a literal infswap_data.txt lives directly in it, or it holds the numbered native ensemble directories the matrix is reconstructed from – see pyretis.analysis.wham_analysis.get_path_data_matrix().

• report_dir (string) – Directory the wham_analysis.txt report is written to.

• nskip (int, optional) – Number of initial cycles (records) to discard as equilibration – the skip_initial_cycles analysis setting. Defaults to 0.

Returns:

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

pyretis.bin.pyretisanalyse.backup_latest_reports(reportfile, report_base)

Back up uncountered reports from a report family.

pyretis.bin.pyretisanalyse.bye_bye_world()

Print out the goodbye message for PyRETIS.

pyretis.bin.pyretisanalyse.completed_cycles(analysis_results)

Return the number of cycles represented by an analysis result.

pyretis.bin.pyretisanalyse.configure_file_logging(log_file, log_level)

Add the analysis file logger and return the numeric log level.

pyretis.bin.pyretisanalyse.create_pdf_report(texfile, pdflatex='pdflatex', report_base=None)

Compile a LaTeX report to PDF if pdflatex is available.

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

Create some reports to display the output.

Parameters:

• settings (dict) – Settings for analysis (and the simulation).

• analysis_results (dict) – Results from the analysis.

• report_path (string) – The path to the directory where the reports should be saved.

Yields:

out (string) – The report files created.

pyretis.bin.pyretisanalyse.entry_point()

entry_point - The entry point for the pip install of pyretisanalyse.

pyretis.bin.pyretisanalyse.entry_point_deprecated()

Legacy pyretisanalyse entry: warn, then run pyretis analyse.

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

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

Generate file name for a report.

Parameters:

• report_type (string) – Identifier for the report we are writing.

• ext (string) – Extension for the file to write.

• prefix (string, optional) – A prefix to add to the file name. Usually just used to mark reports with ensemble number for report_type equal to ‘tis-single’

• path (string) – A directory to use for saving the report to.

• cycles (int, optional) – Number of completed cycles represented by the report.

• counter (int, optional) – Archive counter to insert before the cycle descriptor.

Returns:

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

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

Output a standard greeting for PyRETIS analysis.

Parameters:

• infile (string) – String showing the location of the input file.

• run_dir (string) – The location where we are executing the analysis.

• report_dir (string) – String showing the location of where we write the output.

• log_file (string, optional) – The output log file.

pyretis.bin.pyretisanalyse.main(input_file, run_path, report_dir)

Run the analysis.

Parameters:

• input_file (string) – The input file with settings for the analysis.

• run_path (string) – The location from which we are running the analysis.

• report_dir (string) – The location where we will write the report.

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

pyvisa - An application for analysing PyRETIS simulations.

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

Usage:

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

Optional arguments:

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

Flags may be combined. Valid combinations include:

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

pyretis.bin.pyvisa.bye_pyvisa()

Print out the goodbye message for PyVisA.

pyretis.bin.pyvisa.entry_point()

entry_point - The entry point for the pip install of pyretisanalyse.

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

Output a standard greeting for PyVISA.

Parameters:

• run_dir (string) – The location where we are executing the analysis.

• infile (string) – String showing the location of the input file.

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

Run the analysis.

Parameters:

• basepath (string) – The execution folder where the input files are.

• input_file (string) – The input file with settings for the analysis.

• pyvisa_dict (dictionary, optional) –

  It determines the section of pyvisa to use, it contains:

  • pyvisa_compressor, boolean If true, compress raw output to a .hdf5 file.

  • pyvisa_data, str If given, the file or folder containing the files that will be used to feed to PyVisA.

  • pyvisa_recalculate, boolean If true, use the recalculation tool to compute new op and cv values.

  • only_order, boolean If true, use only data from order.txt files when compressing.

  Flags may be combined: pyvisa_recalculate and pyvisa_compressor can both be set to run recalculation followed by compression in a single invocation. If neither is set, the visualization GUI is launched.

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

Load data to PyVisA.

Parameters:

• basepath (string) – The execution folder where the input files are.

• input_file (string) – The input file with settings for the analysis.

• pyvisa_dict (dictionary, optional) – It determines the section of pyvisa to use, it contains: