pyretis.bin

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

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 restart.toml 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 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 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.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.explore_simulation(sim, sim_settings, progress=False)

Run a RETIS simulation with PyRETIS.

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

Return True if the legacy in-process loop is forced for tis/retis.

Reads _NATIVE_LOOP_ENV (PYRETIS_NATIVE_LOOP). When set to a truthy value, native tis / retis keep the in-process PathSimulation loop instead of routing to the scheduler – a reversible escape hatch for debugging and native-vs-scheduler reference comparison.

Returns:

boolean – True when the legacy in-process loop should be forced.

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 either explicitly via [simulation] task = "infinite_swapping" or implicitly by the presence of the [runner] worker-pool section that only that sampler’s input schema uses. 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_native_retis_config(inputfile, tasks=('retis',))

Return True if the input is a native task = "retis" TOML.

Used only by the opt-in native-via-coordinator route: it must NOT fire for inputs that already select the infinite-swapping sampler (those carry a [runner] section or an infinite-swapping task). Only .toml inputs are considered. tasks lets the caller widen the accepted native task set – the ∞REPPTIS opt-in passes ('retis', 'repptis') so a native task = "repptis" config can be routed through the scheduler for the native-vs-∞REPPTIS comparison, while the default keeps the route retis-only.

Parameters:

• inputfile (string) – Path to the input file.

• tasks (tuple of str) – The native task names that may take the opt-in scheduler route.

Returns:

boolean – True for a native .toml (task in tasks) that does not already select the coordinator.

pyretis.bin.pyretisrun.is_native_scheduler_config(inputfile)

Return True if a native retis 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.native_compat.native_to_infswap_config()). Inputs that already select the infinite-swapping sampler, and the native tis / explore / pptis / repptis tasks, are excluded – they keep their existing routes (see _NATIVE_SCHEDULER_TASKS for why plain TIS is not routed). A retis config that uses a scheduler PORT GAP (see scheduler_supported_features()) also keeps the native loop. Only .toml inputs are considered (a .rst input keeps the in-process loop).

Parameters:

inputfile (string) – Path to the input file.

Returns:

boolean – True for a native tis/retis .toml that should run through the scheduler.

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

Return True if the opt-in native-via-coordinator flag is set.

Reads _NATIVE_VIA_INFSWAP_ENV. The flag is considered set for any value other than the empty string and "0" so that PYRETIS_NATIVE_VIA_INFSWAP=1 (the documented form) enables it.

Returns:

boolean – True when the opt-in route should be taken.

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_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_native_via_infswap(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.native_compat.native_to_infswap_config()), generates the coordinator’s load_dir from the native kick initiation when requested (pyretis.inout.native_compat.generate_load_dir_via_kick()), writes the translated infswap.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 infswap.toml are written).

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

Run a RETIS simulation with PyRETIS.

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.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 ARE ported (the scheduler mr/ts moves) but route only behind the PYRETIS_NATIVE_VIA_INFSWAP=1 opt-in until the supervised permeability golden regen (the committed references are native-loop RNG order), and only at n_workers = 1 (both persist a global order-function mutation on accept). Otherwise the config keeps the native loop.

• an [initial-path] method of load (a pre-existing load folder): the scheduler route kick-initialises or resumes from its own restart.toml, but does not honour a foreign load folder.

• a [simulation] restart continuation.

• a non-internal [engine] (GROMACS / LAMMPS / CP2K / OpenMM / …): only the in-process pyretis MD integrators (_SCHEDULER_INTERNAL_ENGINES) are validated through the scheduler; external-engine retis keeps the native loop.

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.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(data_file, report_dir, nskip=0)

Analyse infinite-swapping output (WHAM crossing probability).

Parameters:

• data_file (string) – Path to the infswap_data.txt produced by the infinite-swapping sampler.

• 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.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: