The Output section¶
The output section defines settings for how PyRETIS should create
output files.
Output settings
---------------
backup = 'overwrite'
pathensemble-file = 1
order-file = 1
energy-file = 1
screen = 10
The following keywords can be set for the output section:
Keyword |
Description |
|---|---|
Determines how we deal with already existing files. |
|
Add a prefix to output files. |
|
Set frequency of output to the energy file. |
|
Set frequency of output of crossing data. |
|
Set frequency of output of order parameter data. |
|
Set frequency of output of path ensemble data. |
|
Set frequency of restart files overwriting. |
|
Set frequency of output of trajectory data. |
Keyword |
Description |
|---|---|
Set frequency of output to the screen. |
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.
Keyword backup¶
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_XXXwhereXXXis a number.
- Default
The default is
backup = overwrite.
Keyword prefix¶
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¶
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¶
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¶
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¶
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¶
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.
For an infinite-swapping run the file carries two extra trailing
columns after the canonical set — the global PathNumber and the
raw high-acceptance weight (ha_factor) — which the WHAM analysis
reads directly. They replace the separate ha_weight.txt sidecar of
earlier versions (still read as a fallback for a pre-fold run).
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¶
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.)
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).
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 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.rst -p
then writing of results to the screen will be disabled.
Keyword screen¶
Determines how often output from a simulation should be written to the screen during a simulation.
- Default
The default is
screen = 10.