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 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_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_dialect module

Convert a legacy-runner TOML config to canonical syntax.

Usage:

python -m pyretis.tools.convert_legacy_dialect path/to/infswap.toml
python -m pyretis.tools.convert_legacy_dialect 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).

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_legacy_dialect._INCIDENTAL_PATHS = frozenset({'engine.cp2k_format', 'engine.exe_path', 'engine.input_files', 'engine.rgen', 'engine.type', 'engine0.cp2k_format', 'engine0.exe_path', 'engine0.input_files', 'engine0.rgen', 'engine0.type', 'output.delete_old', 'output.delete_old_all', 'output.keep_maxop_trajs', 'output.native_compat', 'output.pattern', 'particles.type', 'runner.files', 'system.temperature', 'system.units'})

Dotted coordinator-config paths the comparison deliberately IGNORES. Every entry names a key whose OLD-vs-NEW difference is a documented, intentional property of the conversion – NOT sampling-relevant user content. Anything not listed here is compared in full, so a key a future translator change silently drops FAILS the conversion instead of shipping (the keep_traj_fnames lesson).

pyretis.tools.convert_legacy_dialect._ONE_SIDED_DEFAULTS = {'output.data_dir': './', 'output.energy_file': 1, 'output.order_file': 1, 'output.screen': 1, 'simulation.load_dir': 'accepted', 'simulation.tis_set.allowmaxlength': False, 'simulation.tis_set.high_accept': False, 'simulation.tis_set.maxlength': 20000, 'simulation.tis_set.mirror_freq': 0, 'simulation.tis_set.rescale_energy': False, 'simulation.tis_set.sigma_v': -1, 'simulation.tis_set.target_freq': 0, 'simulation.tis_set.target_indices': [], 'simulation.tis_set.zero_momentum': False, 'system.dimensions': 3, 'system.rgen': 'pcg64'}

Dotted path -> the coordinator’s own no-op default for that key. A key present on only ONE side is tolerated if and only if its value equals this default: presence-at-default and absence are equivalent (the coordinator’s scattered .get(key, default) reads and apply_config_defaults supply exactly these values when absent, and add_default_settings injects the SECTIONS entries into every parsed canonical config). A one-sided key holding any OTHER value is a real translation difference and fails the conversion.

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

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

The FULL dicts are compared, minus the explicit, documented exceptions in _INCIDENTAL_PATHS / _ONE_SIDED_DEFAULTS – so a key the conversion newly drops (or invents) fails the validation instead of shipping silently. Two structural normalizations are applied first: the OLD side’s shooting_moves is truncated to one entry per ensemble (the dialect ignores extras, and normalize_legacy_dialect truncates the same way – see its docstring), and the hyphenated order-file/energy-file spellings are folded onto the coordinator’s underscore names.

pyretis.tools.convert_legacy_dialect._diff_configs(old, new, path, mismatches)

Recursively diff two config (sub-)dicts into mismatches.

Walks the UNION of both key sets so a key present on either side is accounted for: skipped when its dotted path is a documented incidental (_INCIDENTAL_PATHS), tolerated one-sided only at its documented no-op default (_ONE_SIDED_DEFAULTS), and a mismatch otherwise.

pyretis.tools.convert_legacy_dialect._norm(value)

Stable string form for equality comparison and diagnostics.

pyretis.tools.convert_legacy_dialect._validate_conversion(legacy_path, output_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_legacy_dialect.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) – Verify the conversion (see _validate_conversion()) 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.

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

Run the legacy-runner -> canonical converter CLI.

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). The starting config may be written in EITHER dialect: it is routed through the same normalize / parse / translate pipeline the pyretis run CLI uses, so a canonical-shaped config (task = "retis", [tis]) and a legacy-runner one behave identically. 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 dialect. 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).

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