pyretis.tools package¶

Tools which can help with setting up simulations.

This package defines some simple tools which may be useful for creating simulations.

Package structure¶

Modules¶

lattice.py (pyretis.tools.lattice): Defines tools for setting up and generating lattice points.
recalculate_order.py (pyretis.tools.recalculate_order): Methods for recalculating order parameters on external paths.
infinit.py (pyretis.tools.interface_optimizer): The iterative infinit interface-placement driver.

Important methods defined in this package¶

generate_lattice (generate_lattice()): Generates points on a lattice.
recalculate_order (recalculate_order()): Recalculate order parameter(s).
run_infinit (run_infinit()): Run the iterative infinit interface-placement driver.

pyretis.tools.lattice module¶

Some methods for generating initial lattice structures.

Important methods defined here¶

generate_lattice (generate_lattice()): Generate points on a simple lattice.

Examples

>>> from pyretis.tools.lattice import generate_lattice
>>> xyz, size = generate_lattice('diamond', [1, 1, 1], lcon=1)

pyretis.tools.lattice.generate_lattice(lattice, repeat=None, lcon=None, density=None)¶

Generate points on a simple lattice.

The lattice is one of the defined keys in the global variable UNIT_CELL. This lattice will be repeated a number of times. The lattice spacing can be given explicitly, or it can be given implicitly by the number density.

Parameters:

lattice (string) – Select the kind of lattice. The following options are currently defined in UNIT_CELL:
- 1d : 1D lattice
- sc : Simple cubic lattice.
- sq : Square lattice (2D) with one atom in the unit cell.
- sq2 : Square lattice with two atoms in the unit cell.
- bcc : Body-centred cubic lattice.
- fcc : Face-centred cubic lattice.
- hcp : Hexagonal close-packed lattice.
- diamond : Diamond structure.
repeat (list of integers, optional.) – How many time the cell is replicated.
lcon (float, optional) – The lattice constant.
density (float, optional) – The desired density. If this is given, lcon is calculated. Note that density will be interpreted as given in internal units.

Returns:

positions (numpy.array) – The lattice positions.
size (list of floats) – The corresponding size(s), can be used to define a simulation box.

pyretis.tools.recalculate_order module¶

Method to re-calculate order parameters for external trajectories.

Important methods defined here¶

recalculate_order (recalculate_order()): Generic method for recalculating order parameters.
recalculate_from_trj (recalculate_from_trj()): Recalculate order parameters using a GROMACS .trr file.
recalculate_from_xyz (recalculate_from_xyz()): Recalculate order parameters using a .xyz file.
recalculate_from_frame (recalculate_from_frame()): Recalculate order parameters using a .gro or .g96 file.
recalculate_from_ase_traj (recalculate_from_ase_traj()): Recalculate order parameters using an ASE .traj file.
xyz_frame_box (xyz_frame_box()): The box an .xyz frame is evaluated in.
engine_cell (engine_cell()): The cell an engine gives a stored frame that records none.

pyretis.tools.recalculate_order.engine_cell(engine, filename)¶

Return the cell an engine gives a stored frame that records none.

Of the formats read back by format, only an .xyz frame can lack a cell; the other formats carry their own box. The cell is the one of EngineBase.frame_cell(), and an engine object without that method gives none.

Parameters:

engine (object like EngineBase or None) – The engine that wrote the frame.
filename (string) – The file the frame is stored in.

Returns:

out (list of floats or None) – The cell for a frame of filename, or None.

pyretis.tools.recalculate_order.recalculate_from_ase_traj(order_parameter, traj_file, options)¶

Re-calculate order parameters from an ASE trajectory (.traj).

Each frame is read into a System as the ASE engine reads it when it samples (pyretis.engines.ase.ASEEngine.calculate_order()): the positions in Angstrom, the velocities in ASE’s velocity unit and the cell of the frame as the box (set_ase_box()).

Parameters:

order_parameter (object like OrderParameter) – The order parameter to use.
traj_file (string) – The path to the ASE trajectory file we should read.
options (dict) – It contains:
- reverse: boolean, optional If True, we reverse the velocities.
- maxidx: integer, optional This is the maximum frame we will read.
- minidx: integer, optional This is the first frame we will read.

Yields:

out (list of floats) – The order parameters of a frame.

pyretis.tools.recalculate_order.recalculate_from_frame(order_parameter, frame_file, options)¶

Re-calculate order parameters from a .g96/.gro file.

Every configuration in frame_file is evaluated, in file order: a .gro file can hold several frames, a .g96 file holds one (read_gromacs_configs()).

Parameters:

order_parameter (object like OrderParameter) – The order parameter to use.
frame_file (string) – The path to the frame file we should read.
options (dict) – It contains:
- ext: string File extension for the frame_file.
- reverse: boolean, optional If True, we reverse the velocities.
- maxidx: integer, optional The last frame to evaluate.
- minidx: integer, optional The first frame to evaluate.

Returns:

out (list of lists of floats) – The order parameters, one list per frame evaluated.

pyretis.tools.recalculate_order.recalculate_from_trj(order_parameter, trr_file, options)¶

Re-calculate order parameters from a .trr file.

Parameters:

order_parameter (object like OrderParameter) – The order parameter to use.
trr_file (string) – The path to the trr file we should read.
options (dict) – It contains:
- reverse: boolean, optional If True, we reverse the velocities.
- maxidx: integer, optional This is the maximum frame we will read. Can be used in case the .trr file contains extra frames not needed by us.
- minidx: integer, optional This is the first frame we will read. Can be used in case we want to skip some frames from the .trr file.
- idx: integer, optional This allows the selection of a single frame to recompute.

Yields:

out (list of lists of floats) – The order parameters, calculated per frame.

pyretis.tools.recalculate_order.recalculate_from_xyz(order_parameter, traj_file, options)¶

Re-calculate order parameters from a .xyz file.

Parameters:

order_parameter (object like OrderParameter) – The order parameter to use.
traj_file (string) – The path to the trajectory file we should read.
options (dict) – It contains:
- reverse: boolean, optional If True, we reverse the velocities.
- maxidx: integer, optional This is the maximum frame we will read. Can be used in case the .trr file contains extra frames not needed by us.
- minidx: integer, optional This is the first frame we will read. Can be used in case we want to skip some frames from the .trr file.
- box: list of floats, optional The box lengths of the cell a frame that records none is evaluated in (xyz_frame_box()).

Yields:

out (list of lists of floats) – The order parameters as a list.

pyretis.tools.recalculate_order.recalculate_order(order_parameter, traj_file, options)¶

Re-calculate order parameters.

Parameters:

order_parameter (object like OrderParameter) – The order parameter to use.
traj_file (string) – Path to the trajectory file to recalculate for.
options (dict) – It contains:
- reverse: boolean, optional If True, we reverse the velocities.
- maxidx: integer, optional This is the maximum frame we will read. Can be used in case the .trr file contains extra frames not needed by us.
- minidx: integer, optional This is the first frame we will read. Can be used in case we want to skip some frames from the .trr file.

pyretis.tools.recalculate_order.xyz_frame_box(header_box, cell, dim)¶

Return the box an .xyz frame is evaluated in.

The box line of an .xyz frame gives the extent of each dimension. A finite length is the length of a periodic cell. A non-periodic dimension is written as inf and a dimension the system does not use as 0.0000 (# Box: inf 0.0000 0.0000 for a 1-D system); both kinds of dimension are unbounded, and nothing is wrapped in them.

A frame without a box line, or with a box line of zeros only, records no extent. It is evaluated in cell, the cell of the engine that wrote it (EngineBase.frame_cell()), and, when that is None, in a box that is unbounded in each of the dim dimensions of the frame.

Parameters:

header_box (numpy.array or None) – The box read from the frame.
cell (list of floats or None) – The box lengths of the engine’s cell.
dim (integer) – The number of coordinates of each particle in the frame.

Returns:

out (object like BoxBase) – The box of the frame.

pyretis.tools.convert_settings module¶

Convert a legacy PyRETIS .rst settings file to TOML.

Usage:: python -m pyretis.tools.convert_settings path/to/retis.rst python -m pyretis.tools.convert_settings path/to/retis.rst out.toml

If the output path is omitted, the converter writes alongside the input with the extension swapped to .toml (retis.rst → retis.toml). The original .rst is left in place.

The converter validates each conversion by re-reading the produced TOML and comparing the resulting raw settings dict to the rst one; any mismatch aborts with an error.

pyretis.tools.convert_settings._strip_heading(value)¶

Drop heading keys recursively for converter equality checks.

The TOML schema intentionally omits the decorative heading text, so any nested copy (created by ensemble-inheritance during defaulting) is ignored when comparing raw dicts.

pyretis.tools.convert_settings.convert(rst_path, toml_path=None, *, force=False, validate=True)¶

Convert one rst file to TOML and (optionally) verify the round-trip.

Returns the path of the written TOML file.

pyretis.tools.convert_settings.main(argv=None)¶: Run the settings converter command line interface.

pyretis.tools.convert_settings.toml_twin_matches(rst_path, toml_path)¶

Return True if toml_path holds the translation of rst_path.

The comparison criterion is the converter’s own round-trip check: both files are read to their raw settings dicts (heading stripped from the rst side; the TOML schema never carries one) and compared for equality. Used by pyretisrun to decide whether an existing .toml twin of a legacy input can be run in its place.

Parameters:

rst_path (string) – The legacy .rst input.
toml_path (string) – The candidate translated input.

Returns:

boolean – True when the TOML parses to the same raw settings.

pyretis.tools.convert_legacy_schema module¶

Convert a legacy-runner TOML config to canonical syntax.

The legacy-runner schema (a [runner] section, the path-sampling settings under [simulation.tis_set], no [simulation] task) is deprecated. PyRETIS 4 reads an input of that schema in its canonical form, converted when it reads the file (load_legacy_input(), with a deprecation notice), and PyRETIS 5 reads it no more. This module holds the conversion, and the command that writes it to a file once:

python -m pyretis.tools.convert_legacy_schema path/to/infswap.toml
python -m pyretis.tools.convert_legacy_schema path/to/infswap.toml         out.toml

If the output path is omitted, the file is converted in place (canonical syntax is still .toml, so there is no extension change the way pyretis.tools.convert_settings has for .rst -> .toml).

The conversion (convert_legacy_document()) reshapes the input (pyretis.inout.config_adapter.normalize_legacy_schema()) and parses the result with the parser of the canonical input, which refuses a key that takes no effect on the run and names the key of the legacy-runner input with the canonical one. It is checked before it is trusted, as pyretis.tools.convert_settings.convert() checks its round trip: the coordinator config of the ORIGINAL input, read as the scheduler reads a file of its own configuration, is compared with the one the key table builds from the canonical settings, both prepared by pyretis.simulation.setup.fresh_scheduler_config(). Any mismatch raises a RuntimeError; the command then leaves the output path as it was, and a run of the input stops before it writes a file.

class pyretis.tools.convert_legacy_schema.LegacyConversion(document: dict[str, Any], settings: dict[str, Any])¶

Bases: object

The canonical form of an input of the legacy-runner schema.

Variables:

document (dict) – The canonical input, as the TOML document of a file (pyretis.inout.config_adapter.normalize_legacy_schema() of the input).
settings (dict) – The settings the parser of the canonical input gives from document, in the working directory of the conversion.

document: dict[str, Any]¶

settings: dict[str, Any]¶

pyretis.tools.convert_legacy_schema.convert(legacy_path, output_path=None, *, force=False, validate=True)¶

Convert one legacy-runner TOML file to canonical syntax in place.

Returns the path of the written TOML file.

Parameters:

legacy_path (str) – Path to the legacy-runner input TOML.
output_path (str, optional) – Output path. Defaults to overwriting legacy_path (canonical syntax is still .toml, unlike the rst -> toml converter).
force (bool, optional) – Overwrite output_path if it already exists and differs from legacy_path.
validate (bool, optional) – Parse and verify the conversion (see convert_legacy_document()) before writing. Runs with the working directory changed to legacy_path’s directory, since the config’s own relative references (engine modules, load/, …) require it; restored afterwards regardless of outcome. False writes the reshaped input (pyretis.inout.config_adapter.normalize_legacy_schema()) unparsed.

pyretis.tools.convert_legacy_schema.convert_legacy_document(raw, name)¶

Convert a legacy-runner input to its canonical form, and check it.

The input is reshaped by pyretis.inout.config_adapter.normalize_legacy_schema() and parsed by the parser of the canonical input (pyretis.inout.settings.parse_settings_dict()), in the working directory. The parse refuses a key that takes no effect on the run (pyretis.inout.key_table.NO_EFFECT), as it refuses it in a canonical input, and names the key of the legacy-runner input with the canonical one (pyretis.inout.config_adapter.legacy_input_keys()). The conversion is then checked (_validate_conversion()).

Parameters:

raw (dict) – The legacy-runner input, as tomllib reads it. It is left unchanged.
name (str) – The input file, as the messages name it.

Returns:

LegacyConversion – The canonical input document and its settings.

Raises:

ValueError – If the input has no canonical form (pyretis.inout.config_adapter.normalize_legacy_schema()), or the parse refuses its canonical form.
RuntimeError – If the canonical form does not give the scheduler configuration of the input.

pyretis.tools.convert_legacy_schema.legacy_schema_notice(name)¶

Return the deprecation notice of an input of the legacy-runner schema.

Parameters:: name (str) – The input file, as the notice names it.
Returns:: str – The notice: the schema is converted when PyRETIS reads it, and PyRETIS 5 will not read it; the command that writes the canonical form of the file.

pyretis.tools.convert_legacy_schema.load_legacy_input(path, name=None)¶

Read an input of the legacy-runner schema in its canonical form.

Every entry that reads such an input converts it here: pyretis run, the scheduler set-up (pyretis.simulation.setup.setup_config()), pyretis analyse (pyretis.inout.run_record.read_settings()) and the interface optimiser. The deprecation notice is logged (warn_legacy_input()), and the input is converted and checked (convert_legacy_document()) in the working directory.

Parameters:

path (str) – The legacy-runner input.
name (str, optional) – The input file, as the notice and the messages name it; path when not given.

Returns:

LegacyConversion – The canonical input document and its settings.

pyretis.tools.convert_legacy_schema.main(argv=None)¶: Run the legacy-runner -> canonical converter CLI.

pyretis.tools.convert_legacy_schema.warn_legacy_input(name)¶

Log and warn the deprecation notice of a legacy-runner input.

The notice (legacy_schema_notice()) is logged at WARNING level, so it shows on screen and in the run log, and issued as a DeprecationWarning, as pyretis.bin._cli_common.warn_deprecated_executable() does for the deprecated commands.

Parameters:: name (str) – The input file, as the notice names it.

pyretis.tools.interface_optimizer module¶

Iterative infinit interface-placement driver for PyRETIS.

Ported (and adapted to the PyRETIS run interface) from the upstream inftools infinit tool. infinit automatically places TIS/RETIS interfaces by repeating:

run a short infinite-swapping simulation with the current interfaces;
re-estimate the crossing probability with WHAM and re-place the interfaces so every ensemble carries roughly the same local crossing probability (via pyretis.analysis.interface_estimation.interfaces_from_data());
re-select the most-decorrelated active paths from the run as the initial paths for the next iteration’s interface set;
repeat for the configured number of iterations.

The scientific core (binless WHAM crossing probability + geometric interface placement) lives in pyretis.analysis.interface_estimation; this module is the orchestration around the PyRETIS infinite-swapping scheduler (pyretis.simulation.scheduler.scheduler()).

Unlike the upstream driver – which mutates one run file in place and threads a cstep state machine through it – each PyRETIS iteration runs in its own <workdir>/step_<i> directory from a fresh run file (no [current] section). The starting config may be written in EITHER schema: a legacy-runner one is read in its canonical form, with the validated conversion and the deprecation notice of pyretis run (pyretis.tools.convert_legacy_schema.convert_legacy_document()), so a canonical-shaped config (task = "retis", [tis]) and a legacy-runner one behave identically. The run file of a step, step_<i>/output.toml, holds the canonical sections of the step’s input (pyretis.inout.run_record.canonical_record()): the starting input with the step’s interfaces, shooting moves and cycle target, and [initial-path] method = "load" from the folder the step’s initial paths are copied from. The scheduler builds its configuration from those sections, and the driver reads the finished step back with pyretis.inout.run_record.load_run(). Each iteration’s initial paths are seeded into the step’s per-ensemble trajectory archive (<ensemble>/<load_dir>/<n>, the layout pyretis.core.path_load.load_paths_from_disk() reads), and the post-run re-selection reads the surviving paths back from that same archive. This keeps every iteration’s I/O isolated and reproducible.

The driver does not generate the very first set of initial paths (cstep == -1 / zero-path generation in the upstream): supply a flat library of starting paths (one numbered sub-directory per ensemble, the same layout the infinite-swapping examples stage) next to the config.

pyretis.tools.interface_optimizer.reselect_initial_paths(src_paths, active_pnums, interfaces, dest_dir)¶

Re-select active paths for a new interface set into dest_dir.

Ported from the upstream initial_path_from_iretis (the restart-active branch). The [0-] path is kept; the remaining active paths are sorted by their maximum order parameter and assigned to increasing positive ensembles (a path is valid in the highest ensemble whose interface it crosses). Any ensemble still empty is filled by cloning a path from a higher ensemble. Selected paths are copied into dest_dir as 0 .. len(interfaces)-1.

Parameters:

src_paths (dict or str) – The previous iteration’s paths: either a mapping path number -> path directory (as collected from the run’s per-ensemble trajectory archive) or a flat directory holding one numbered sub-directory per path.
active_pnums (list of int) – The active path numbers from the previous run’s output.toml ([current].active), one per old ensemble.
interfaces (list of float) – The new interface positions.
dest_dir (str) – The directory to create and fill with the re-selected paths.

Returns:

chosen (dict) – Mapping ensemble index -> source path directory.

pyretis.tools.interface_optimizer.run_infinit(toml='infswap.toml', workdir='.', log_file='infinit.log')¶

Run the iterative infinit interface-placement driver.

Parameters:

toml (str) – The starting config, in either the canonical or the legacy-runner schema. Must contain an [infinit] section (see set_default_infinit()), and a flat library of starting paths must exist next to it (one numbered sub-directory per ensemble, named by [simulation] load_dir, default load).
workdir (str) – Directory in which the per-iteration step_<i> sub-directories are created (default: the current directory). A step directory of the run that already holds files stops the run before its first step (see _refuse_used_step_dirs()).
log_file (str) – File (under workdir) for the per-iteration interface log.

Returns:

interfaces (list of float) – The interface set after the final iteration.

pyretis.tools.interface_optimizer.set_default_infinit(config)¶

Validate and fill the [infinit] section of a config dict.

Parameters:: config (dict) – The parsed TOML config; must contain an [infinit] table with at least steps_per_iter (a list of per-iteration step counts).
Returns:: iset (dict) – The validated [infinit] settings (defaults filled in place).