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
backup	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	Not used by any run: leave it out of the input.
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 backup, prefix, restart-file and trajectory-file set the output files of the md, md-nve and md-flux tasks, and cross-file the crossing file of md-flux. A path-sampling run (tis, retis, explore, pptis, repptis), and make-tis-files, refuses these keywords and pathensemble-file: it records every cycle in pathensemble.txt and every attempted move in moves.txt, keeps its trajectories in the stores that archive_every thins, and records the state a restart continues from in output.toml (see the keywords that take no effect). The md, md-nve and md-flux tasks write no path ensemble file: they accept pathensemble-file, data_dir, keep_rejected_status, archive_every, keep_traj_fnames and engine_log but take no effect from them, and md and md-nve none from cross-file.

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: Existing files are renamed with a suffix _XXX, as with backup = backup: this value does not overwrite them. To write the files afresh, remove them or run in a new directory.

• 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 of an md, md-nve or md-flux run. A path-sampling run (tis, retis, explore, pptis, repptis) writes to the energy.txt of each ensemble directory the energies along each path the ensemble holds, one block for each row of its pathensemble.txt, when N is positive, and writes no such file when N is 0 or less; a value above 1 does not thin the file. Each sampled path in the accepted and archive stores keeps its own energy.txt either way.

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 of an md, md-nve or md-flux run. A path-sampling run (tis, retis, explore, pptis, repptis) writes to the order.txt of each ensemble directory the order parameter along each path the ensemble holds, one block for each row of its pathensemble.txt, when N is positive, and writes no such file when N is 0 or less; a value above 1 does not thin the file. Each path in the accepted and archive stores keeps its own order.txt either way.

Default

The default is order-file = 1.

Keyword restart-file

restart-file = integer

Determines how often we will write out the restart file of an md, md-nve or md-flux run.

restart-file = N will make PyRETIS overwrite the restart file pyretis.restart every Nth step. A path-sampling run refuses the keyword: it writes the state a restart continues from to the [current] section of output.toml every cycle, keeping the one before as output.toml.prev. The ensemble.restart file of each ensemble directory is written once, when the initial paths are made, and is not the state of the run.

Default

The default is restart-file = 1.

Keyword pathensemble-file

pathensemble-file = integer

The path ensemble file pathensemble.txt 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.

A path-sampling run writes pathensemble.txt every cycle and refuses the keyword pathensemble-file; the md, md-nve and md-flux tasks write no path ensemble file and take no effect from it. Leave the keyword out of the input.

Keyword trajectory-file

trajectory-file = integer

Determines how often an md, md-nve or md-flux run writes the configuration to its trajectory file traj.xyz: trajectory-file = N writes it every Nth step.

A path-sampling run (tis, retis, explore, pptis, repptis) refuses the keyword. It stores every path it accepts, and moves a replaced path to the long-term store: archive_every sets how many of those it keeps, which is the way to bound its disk use with an external engine.

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, keyed by the global path number. The operational store <ensemble>/accepted/<path number>/ holds the paths the ensembles hold, the initial paths of the run, which stay there, and the paths replaced most recently, as many as the run has ensembles; each later replacement moves the oldest of those to the long-term store <ensemble>/archive/<path number>/. Trial moves are generated in a transient <ensemble>/generate/ scratch directory. A restart keeps the same paths as an uninterrupted run. 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

Extensions of files that travel with a path’s trajectory when the path moves between the stores. For each trajectory file <name>.<ext> of the path, the file <name><entry> beside it is kept with it, so write each entry with its leading dot: keep_traj_fnames = [".edr", ".cpt"] keeps the traj.edr and traj.cpt of a trajectory traj.trr. An entry is not a glob pattern ("*.edr" keeps nothing), and a file of another name, such as a topology topol.tpr, is not kept.

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 a simulation reports its progress. An md, md-nve or md-flux run writes its temperature, energies and pressure to the screen every screen steps. A path-sampling run writes no progress to the screen: it writes its progress report (the moves it attempts and the paths they give) to the run log pyretis.log every screen cycles, and 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 – pathensemble.txt, moves.txt, order.txt, energy.txt and the path stores accepted/, archive/ and rejected/ – under this directory, relative to the run directory. output.toml and the run log stay in the run directory, and so does a directory per ensemble holding the ensemble.restart written when the initial paths are made.

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; a kept one is written, with its trajectory, order.txt and energy.txt, to <ensemble>/rejected/cycle<NNNNNNN>_<status>/ (for example 001/rejected/cycle0000056_NCR/) for inspection afterwards. ACC is not a rejection and is refused here. A code that is no status code, such as the typo "NRC", is accepted and keeps nothing: see Path types and rejection reasons for the codes.

Default

No default; no rejected trial is kept.