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.

List of submodules

• pyretis.tools.lattice

• pyretis.tools.recalculate_order

• pyretis.tools.convert_settings

• pyretis.tools.convert_infretis_dialect

• pyretis.tools.interface_optimizer

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.

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

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

Here we assume that there is ONE frame in the frame_file.

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.

Returns:

out (list of lists of floats) – The order parameters for the current frame.

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 It contains the box vector lenght. It is required in the case that .xyz do not normally contains the simulation box dimension.

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

Convert an infretis-flavour TOML config to pyretis-native syntax.

Usage:

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

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

Mirrors that converter’s validated round-trip pattern (pyretis.tools.convert_settings.convert()): the conversion is verified before being trusted, here by comparing the coordinator config pyretis.simulation.setup.setup_config() builds from the ORIGINAL file against the one it builds from the CONVERTED file (both go through the identical shared second stage, MERGE_TODO.md S5.6), not by re-running a full simulation – any mismatch aborts with an error rather than silently writing a translation nobody checked.

pyretis.tools.convert_infretis_dialect._TIS_SET_HARMLESS_EXTRAS = frozenset({'high_accept', 'mirror_freq', 'rescale_energy', 'sigma_v', 'target_freq', 'target_indices'})

Coordinator-config keys the converter’s own tis_set comparison leaves out. These are keys native_to_infswap_config carries unconditionally (post-defaulting) whose value equals the coordinator’s own internal fallback default regardless – see normalize_infretis_dialect’s docstring for the full reasoning (sigma_v, rescale_energy, mirror_freq, target_freq all confirmed against their pyretis.core.moves.py / repex.py .get(key, default) reads). Comparing only the keys the OLD route’s dict actually has is what the rest of this module does instead of hardcoding this list a second time.

pyretis.tools.convert_infretis_dialect._compare_configs(old_config, new_config)

Compare two coordinator config dicts; return a list of mismatches.

Only the fields a conversion could plausibly perturb are checked (mirroring the manual validation this module formalizes, see MERGE_TODO.md S5.6 Phase 3/4): interfaces, shooting_moves, the topology flags, zeroswap, ensemble_engines, runner (minus the infinit-only files key, which normalize_infretis_dialect drops deliberately), engine/engine0 (minus run-location-specific keys), output’s delete_old family, and every tis_set key the OLD route actually sets (extra keys the NEW route carries are the documented, harmless post-defaulting additions – see _TIS_SET_HARMLESS_EXTRAS).

pyretis.tools.convert_infretis_dialect._norm(value)

Stable string form for equality comparison and diagnostics.

pyretis.tools.convert_infretis_dialect._strip_incidental(engine)

Drop keys that legitimately differ by run location, not content.

input_files (GROMACS/CP2K, pyretis/inout/formats/{gromacs, cp2k}.py) is a run-time cache of input_path resolved to absolute paths on whatever machine setup_config happens to run on – derived, not user-specified, so it is exactly as run-location-incidental as exe_path.

cp2k_format is likewise derived, not user content: the engine factory auto-detects it from input_path/initial.* (else "xyz") deterministically and idempotently (pyretis.engines.factory’s cp2k-format checker). The two dialects only differ in WHEN that detection runs – the native route resolves it at config-build time, the infretis-flavour route defers it to engine construction – so the resolved value is identical and its presence on only one side is not a translation difference.

pyretis.tools.convert_infretis_dialect._validate_conversion(infretis_path, native_path)

Compare the OLD and NEW routes’ coordinator configs; raise on mismatch.

Both files must be read relative to the SAME working directory (module files, initial.xyz, load/ all resolve relative to cwd, not the input path), so the caller is expected to already be chdir’d there – see convert().

pyretis.tools.convert_infretis_dialect.convert(infretis_path, native_path=None, *, force=False, validate=True)

Convert one infretis-flavour TOML file to native syntax in place.

Returns the path of the written TOML file.

Parameters:

• infretis_path (str) – Path to the infretis-flavour input TOML.

• native_path (str, optional) – Output path. Defaults to overwriting infretis_path (native syntax is still .toml, unlike the rst -> toml converter).

• force (bool, optional) – Overwrite native_path if it already exists and differs from infretis_path.

• validate (bool, optional) – Verify the conversion (see _validate_conversion()) before writing. Runs with the working directory changed to infretis_path’s directory, since the config’s own relative references (engine modules, load/, …) require it; restored afterwards regardless of outcome.

pyretis.tools.convert_infretis_dialect.main(argv=None)

Run the infretis-flavour -> native converter command line interface.

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:

1. run a short infinite-swapping simulation with the current interfaces;

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

3. re-select the most-decorrelated active paths from the run as the initial paths for the next iteration’s interface set;

4. 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 config (no [current] section), loading a load/ directory of re-selected paths numbered 0 .. N-1. PyRETIS’ setup_config() then starts that iteration cleanly. 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 working load_dir for the starting interfaces, exactly as the infinite-swapping examples do.

pyretis.tools.interface_optimizer.reselect_initial_paths(src_load_dir, 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_load_dir (str) – The directory holding the previous iteration’s paths (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 infinite-swapping config. Must contain a working [simulation] load_dir for its interfaces and an [infinit] section (see set_default_infinit()).

• workdir (str) – Directory in which the per-iteration step_<i> sub-directories are created (default: the current directory).

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