The Output section¶

The output section defines settings for how PyRETIS should create output files.

Example Output section:

[output]
order-file = 1
energy-file = 1
screen = 10

The following keywords can be set for the output section:

Table 42 Keywords for output to files.¶
Keyword	Description
bakcup	Determines how we deal with already existing files.
prefix	Add a prefix to output files.
energy-file	Set frequency of output to the energy file.
cross-file	Set frequency of output of crossing data.
order-file	Set frequency of output of order parameter data.
pathensemble-file	Set frequency of output of path ensemble data.
restart-file	Set frequency of restart files overwriting.
trajectory-file	Set frequency of output of trajectory data.

Table 43 Keywords for output to the screen.¶
Keyword	Description
screen	Set frequency of output to the screen.
data_dir	Re-root the per-ensemble output directories.
keep_rejected_status	Keep the trials rejected with the listed status codes.

Keywords controlling output to files¶

For the keywords controlling the frequency of the output to files, e.g. energy-file, writing of such output can be disabled by setting a frequency of 0 or less.

Note that PyRETIS will create a set of files for each path ensemble in a RETIS (or TIS) simulation.

The keywords bakcup, prefix, cross-file, pathensemble-file, restart-file and trajectory-file set the output of the in-process tasks (md, md-nve, md-flux). A path-sampling run (tis, retis, explore, pptis, repptis), and make-tis-files, refuses them: the scheduler writes its own output files, and the in-process initiation of the initial paths writes the same files whatever their values (see the keywords that take no effect).

Keyword backup¶

backup = string

Determines how we deal with already existing files. This can be set to one of the following:

backup = append: Output will be appended to already existing files.
backup = overwrite: Output will overwrite already existing files.
backup = backup: A backup of existing files will be created. Existing files will be renamed with a suffix _XXX where XXX is a number.

The keyword applies to the output files of the md, md-nve and md-flux tasks, and a path-sampling run (tis, retis, explore, pptis, repptis) refuses it: a restart appends to the ensemble output of such a run, and a new simulation started with kick or load stops with an error when that output holds sampled cycles. See the restart method for how to add cycles or start over.

Default: The default is backup = append.

Keyword prefix¶

prefix = string

The prefix can be used to add names to the output files, that is prefix = TEXT will prepend TEXT to output files created by PyRETIS. This can, for instance, be used to organize your output.

Default: The default is None, that is: no prefix is added by default.

Keyword energy-file¶

energy-file = integer

Determines how often we should write to the energy file. energy-file = N will make PyRETIS write to the energy file every Nth step.

Default: The default is energy-file = 1.

Keyword cross-file¶

cross-file = integer

Determines how often PyRETIS will try to write to the crossing file. The crossing file will only be written to if an actual crossing has been detected. Note that this only applies to simulations for determining the initial flux.

cross-file = N will make PyRETIS write to the crossing file every Nth step. Normally, this keyword should be set to 1. This does not mean that we will write to the crossing file every step, but only that we will check if we can write new crossing data every step. The file will only be written to if a crossing has been made.

Default: The default is cross-file = 1.

Keyword order-file¶

order-file = integer

Determines how often we will write out order parameters to the order file.

order-file = N will make PyRETIS write to the order file every Nth step.

Default: The default is order-file = 1.

Keyword restart-file¶

restart-file = integer

Determines how often we will write out the restart file.

restart-file = N will make PyRETIS overwrite the restart files every Nth step. The restart files are: pyretis.restart in the main folder and ensemble.restart in the ensemble’s pathfolders for path ensemble simulations.

Default: The default is restart-file = 1.

Keyword pathensemble-file¶

pathensemble-file = integer

Determines how often we will write out path data for path ensembles. This file contains the basic information about the paths (length, maximum/minimum order parameter, what kind of move we perform, was the path accepted etc.) and is the most important file for the analysis. The move type codes and path status (acceptance or rejection reason) codes recorded in this file are explained in Path types and rejection reasons.

Every row is an occupancy record – which path the ensemble held that cycle – and is what the crossing-probability analysis reads. After the canonical set come three extra trailing columns: the global PathNumber, the raw high-acceptance weight HA-weight (ha_factor) and FracInc, the ensemble’s share of that path in the cycle. The WHAM analysis reads them directly. The attempted moves, accepted or rejected, which the acceptance ratios are counted from, are written to moves.txt beside this file. Output written in the earlier layouts (a separate ha_weight.txt, attempted moves as Trial = 1 rows of this file, or a separate trials.txt) is still read. See pathensemble.txt – what each ensemble held.

Normally, the frequency of output should be set to 1, but setting pathensemble-file = N will make PyRETIS write to the order file every Nth step.

Warning

Setting a value different from 1 is not accounted for in the analysis and is not recommended.

Default: The default is pathensemble-file = 1.

Keyword trajectory-file¶

trajectory-file = integer

Determines how often we should write trajectory data to a trajectory output file.

Warning

Setting this to a small value (say 1) is not recommended when using external engines as this may quickly use up all the space on your hard drive. Setting trajectory-file = N means that PyRETIS will store a trajectory every Nth step for each path ensemble in a RETIS/TIS simulation. You are advised to investigate typical sizes for the trajectories before setting this frequency output.

Default: The default is trajectory-file = 100.

Keywords controlling on-disk trajectory storage¶

A path-ensemble run keeps its trajectories in a two-tier, per-ensemble store: the operational store <ensemble>/accepted/<path number>/ holds the live accepted paths, and the long-term store <ensemble>/archive/<path number>/ holds paths that have since been replaced. Trial moves are generated in a transient <ensemble>/generate/ scratch directory. Paths are keyed by their global path number and evicted in first-in-first-out order (the eviction queue is persisted, so a restart prunes identically). The following [output] keys control what happens to a superseded path and how much disk the run uses.

A replaced path always moves from the operational store <ensemble>/accepted/<pn> to the long-term store <ensemble>/archive/<pn> (a cheap same-parent rename). By default every replaced path is kept there, so a long run accumulates one trajectory per accepted move and can use a lot of disk. Use archive_every to keep only a periodic sample of them – this is the way to bound disk usage. (The former delete_old / delete_old_all / keep_maxop_trajs deletion keys are retired; a config still setting them is rejected.)

archive_every = integer

How often a replaced path is kept in the long-term store, restoring the classic PyRETIS trajectory-saving cadence for the two-tier store. archive_every = N keeps only every N-th replaced path in <ensemble>/archive/ (those whose global path number is a multiple of N) and removes the rest, so the archive holds roughly one trajectory per N accepted moves instead of every one. The operational store (the live paths) is unaffected, so sampling and restart are unchanged — only the retained trajectory history is thinned. This is the way to bound disk usage while keeping a representative sample.

Default: The default is archive_every = 1 (keep every replaced path).

keep_traj_fnames = list

Extra trajectory file-name patterns the archiver carries along when a path moves between the stores (for example a topology or restart file that must survive with the trajectory).

Default: The default is an empty list.

Keywords controlling the log files¶

A run writes two kinds of logs, on two different file structures:

The run log (pyretis.log): one file for the whole simulation, written by PyRETIS itself. It keeps growing with the simulation — by default a restart appends to it, so one file tells the whole story of the run.
The engine logs: the external engine’s own output (the engine.log / engine.err command capture, the streaming engines’ stdout.txt / stderr.txt, and per-run files such as a LAMMPS .log / .screen pair). These are per trajectory: the live log is zeroed every time a new trajectory is generated, and each finished trajectory’s logs are stored in a numbered folder <ensemble>/engine_logs/<seq>/ next to the ensemble’s generate/ scratch. The engine_log keyword decides how many of those per-trajectory folders are kept. When a trajectory generation fails, its logs are left in the scratch directory for inspection.

log_file = string

The name of the run log. The name is also carried to the worker processes of a parallel run, so all of them append to the same file. An explicit pyretis run -f <name> overrides this keyword for the main process only — in a parallel run, set the keyword (not just -f) so the workers follow the same name.

Default: The default is log_file = 'pyretis.log'.

log_mode = string

What happens to an existing run log when a run starts:

'append': keep the existing log and append to it — the log grows with the simulation and a restart continues the same file.
'backup': rotate the existing log aside first (to pyretis.log_000, _001, …), the historical behaviour.
'overwrite': truncate the existing log.

Default: The default is log_mode = 'append'.

engine_log = string

How many per-trajectory engine-log folders (<ensemble>/engine_logs/<seq>/) are kept per ensemble:

'last': keep only the most recent trajectory’s logs.
'all': keep every trajectory’s logs (mind the disk usage of a long run).
a positive integer N: keep the N most recent.

The retention never affects the sampled paths — the logs are a purely human-inspectable record. The scratch directories are per ensemble (they replaced the old per-worker directories), so the engine-log store is per ensemble too.

Default: The default is engine_log = 'last'.

Keywords controlling output to the screen¶

Note that if you run the PyRETIS application and choose to use the progress bar, that is:

pyretis run -i input.toml -p

then writing of results to the screen will be disabled.

Keyword screen¶

screen = integer

Determines how often output from a simulation should be written to the screen during a simulation. The scheduler of a path-sampling run writes its progress report (the moves it submits and the paths they give) to the log every screen cycles, and writes none with screen = 0; the run file output.toml records the value the run takes.

Default: The default is screen = 10.

Keyword data_dir¶

data_dir = string

Places the per-ensemble output directories under this directory. The per-path archive follows them, since it lives inside those directories.

Default: No default; the ensembles are written in the run directory.

Keyword keep_rejected_status¶

keep_rejected_status = list of strings

The rejection status codes whose trials are kept. A rejected trial is otherwise discarded, and keeping the interesting ones makes the rejected trajectory available for inspection afterwards. ACC is not a rejection and is refused here. See Path types and rejection reasons for the codes.

Default: No default; no rejected trial is kept.