The PyRETIS analysis application¶
The PyRETIS analysis application, pyretis analyse, is used to
analyse the results from PyRETIS simulations. It analyses the
path-sampling tasks and the md-flux task (see the analysis of an
md-flux run). An md or md-nve run has
no analysis of its own: pyretis analyse stops with a message that says
so. Such a run writes its energies to energy.txt (and thermo.txt),
its order parameter to order.txt and its configurations to
traj.xyz.
See also
Simulation outputs describes the files a run writes and how to read the report this application produces – including how to tell a converged simulation from one that has not sampled enough. Calculating the rate explains how the rate constant itself is put together, and how the routes differ between TIS, RETIS, infinite swapping and the (RE)PPTIS family.
The general syntax for executing is:
pyretis analyse [-h] [-i INPUT] [-V] [-f LOG_FILE] [-l LOG_LEVEL] [-skipb N] [-skipe N]
where INPUT is the input file of the run, as the note below
describes: the file the PyRETIS
application ran from, or the file the
run wrote from it – output.toml for a path-sampling run,
out.toml for an md-flux run. Its
analysis section sets how the analysis
is done; without one, the defaults are used. It need not hold
[particles] npart: the
energy analysis of an md-flux run reads the number of particles
from the restart file of the run, and checks a [particles] npart
the file states against the number of particles that the restart file
of a run on an internal engine records. Run pyretis analyse
in the directory of the run: it reads the run’s output files from the
directory it is run in, whatever
exe_path the file holds. Do
not add endcycle to the input
of a path-sampling run: pyretis analyse refuses it, as
pyretis run does.
Note
The analysis reads the SAME input file the simulation ran
from (pyretis analyse -i retis.toml), or the run’s own
output.toml (pyretis analyse -i output.toml), which
records that input with its defaults resolved: the analysis
takes the input sections from it and the run directory it is run
in (see Calculating the rate). The output.toml of an OpenMM
run also records the step size of its integrator as [engine]
timestep, so its analysis reads the time per step and imports
no module; an OpenMM input that states no timestep is
analysed through that output.toml.
Input arguments¶
Argument |
Description |
|---|---|
-h, –help |
Show the help message and exit. |
-i INPUT, –input INPUT |
Location of the input file containing analysis settings. |
-V, –version |
Show the version number and exit. |
-f LOG_FILE, –log_file LOG_FILE |
Write the log to |
-l LOG_LEVEL, –log_level LOG_LEVEL |
Level of the log file, such as |
-skipb N, –skip-begin N |
Discard the first |
-skipe N, –skip-end N |
Discard the last |
Choosing which cycles to analyse¶
By default every sampled cycle is analysed. Two optional arguments narrow that window:
pyretis analyse -i input.toml -skipb 500
pyretis analyse -i input.toml -skipb 500 -skipe 100
The first discards the first 500 cycles – the usual reason being that the simulation had not yet equilibrated. The second additionally discards the last 100, which is what you want when a run was cut short (a wall-time kill mid-cycle) or when you are comparing two runs over the same window.
Both are counted in cycles of the run, they can be used together or on
their own, and they override
skip_initial_cycles
and
skip_final_cycles
in the input file, so you can try several windows without editing anything.
The analysis log states how many cycles each option drops
(Discarding the first 5 cycles (-skipb).). A count of 0 or less
leaves out no cycle on its side, and the log states 0.
The cycles of the run are the cycles that the pathensemble.txt of any
ensemble records, and every skip leaves out the first or the last N of
them, the same cycles in every ensemble. The ensembles of a run can
record different cycles: with several workers, and in a PyRETIS 3 RETIS
run, whose swap and relative-shoots cycles write no row for the ensembles
they leave out ([retis] nullmoves unset or false).
The window is the one of the run: an ensemble that records no row in a
cycle of the window has no row there.
The ensembles of a make-tis-files input are separate single TIS runs,
one per ensemble: pyretis analyse of that input counts the cycles of
each ensemble’s own pathensemble.txt, and the window of an
ensemble is the first or the last N of its own cycles.
A run file written by an earlier version of PyRETIS can record
skip_initial_cycles = 0 next to a skip above 0, two numbers of
cycles to discard. pyretis analyse -i output.toml then stops with a
message that asks for the number; give it with -skipb N, or keep
one of the two keys in the input.
The chosen window applies to everything the matched analysis reports: the
crossing probabilities, the rate, and the acceptance ratios below. The
WHAM analysis ([analysis] method = "wham" or "both") applies the
same window: it leaves out the rows of the same cycles of every
ensemble, so method = "both" computes the two estimates over the same
cycles; the WHAM matrix also leaves out the paths held at the end of the
run (see below), which makes the two estimates differ. The WHAM report
states the cycles left out (Skipped initial cycles: N,
Skipped final cycles: M).
A biretis run is analysed with the matched estimator, for both
directions (see the biretis task): the analysis writes
report/biretis_report.txt with the two rates and \(K\), applies
the window of -skipb and -skipe, leaves out the initialisation
paths by the rule below, and refuses [analysis] method = "wham" and
"both". The input gives each ensemble directory its role, so the
analysis takes the layout of the run: it refuses an input whose
interfaces, interfaces_b or shared differ from those the
output.toml of the run records (analyse with the input the run ran
with, or with -i output.toml).
A run whose output.toml records the windows of the input has the
layout of the input, and the analysis checks the directory:
an ensemble directory beyond the layout is the output of an earlier run in the same directory; the analysis leaves it out and a warning names it;
an ensemble directory missing from the layout is refused, and the message says that the output of that ensemble is missing.
A run without an output.toml, or whose output.toml records no
windows, is read with the layout of the input, and a warning says so; the
analysis refuses an ensemble directory beyond that layout and one missing
from it. The message for a directory beyond the layout names both causes,
a run of another layout than the input and the output of an earlier run
in the directory, and both remedies: analyse the run with the input of the
run, with -i output.toml where the directory holds one, or move that
directory out of the run directory. The message for a missing directory
advises the input of the run, in the same way.
For every run, the analysis refuses a pathensemble.txt whose sampled
paths (the initialisation paths left out) in the cycles analysed start on
a side outside those of its role in the layout, and the message names the
file.
The tools that read the combined path-data matrix of a run (below: the
training set, the interface optimiser and the merge of several runs)
read the one ladder of a one-way run, and they refuse the directory of a
biretis run.
Independently of the window, each ensemble’s statistics start at its
first accepted, non-initialisation path. The paths an ensemble holds
before that are the ones initiation put there (ld, ki or is)
and they are not samples of the ensemble, so counting them would bias
the crossing probability towards whatever the initial path happened to
do. An ensemble that has not yet been sampled at all is reported as
having no accepted paths to analyse rather than given a number built
from its initial path – if you see that, the run was too short to
reach that ensemble.
The same holds for a path marked hc: an ensemble held it at a restart
that changed [tis] high_accept, so it was accepted under the other
acceptance rule. Its rows from the restart on are left out, and the
ensemble counts again from its first path accepted after the restart; its
rows from before the restart stay in.
The WHAM analysis, and every tool that builds the combined path-data
matrix from the per-ensemble output (the training set and the interface
optimiser read the same matrix), leaves out the rows of the
initialisation paths and of the paths marked hc by the same rule.
Its skip counts cycles of the run, as the matched analysis counts them:
the rows of the first N and of the last M cycles that the
pathensemble.txt files of the run record are left out of every
ensemble, and each path sums its rows in the cycles that remain. A path
with no row left has no row in the matrix. The paths the ensembles hold
at the end of the run are left out of the matrix, their rows in the
kept cycles included, as without a skip.
A literal infswap_data.txt or infretis_data.txt in the run
directory is read in place of the per-ensemble output. Its rows record
no move, so every row of it is kept, the rows of the initialisation
paths included. Its rows record no cycle either, so the WHAM analysis
of such a file (a run directory analysed without -i, or
method = "wham" or "both") with -skipb, -skipe, skip_initial_cycles,
skip_final_cycles or skip above 0 stops with an error that
says so; -skipb 0 and -skipe 0 skip nothing. The merge of several
runs (pyretis.analysis.combine_data)
writes <out>.txt, combo.txt by default, in this layout, and its
interfaces to <out>.toml. Copied into a directory as
infswap_data.txt, with <out>.toml as output.toml, the merge
is read in this way. The merge reads the paths of each run as the
analysis does. Its skip counts paths: it discards the first
skip paths of each run’s path list (the first skip rows of a
literal data file), by ascending path number, the initialisation paths
included.
Stone skipping without high acceptance ([tis] high_accept = false)
samples each path with weight 1. When the rows of such an ensemble carry
the crossing count of each path as HA-weight, and the counts differ from
row to row, every weighted average over them is biased, so the analysis
leaves those cycles out and its log names them. The run’s
output.toml records, as [current] ss_weight_from_cycle, the
first cycle whose rows carry the weight of the rule each path was sampled
with, and, under [current] ss_weight_before, the move list and layout
the earlier rows were written with and the paths held at that cycle. The
rows before it are checked, and so is every row of a run whose
output.toml does not record it. In a folder without a run file
(output.toml, restart.toml or infswap.toml),
rows that carry an HA-weight are checked with the settings of the input:
the count of [runner] workers is the one of the input alone.
Where no weight decides where a path goes (tis, pptis,
repptis), only an affected ensemble loses those cycles. In a
retis run the weights also decided, through the swaps, where each
path went, so every ensemble loses them, up to the last cycle in which a
path held at the boundary is still held. The cycles after that start
from the paths the earlier weights left behind, as a run starts from its
initial paths, and may need an equilibration skip of their own.
-skipb counts from the first cycle of the run and does not add
to the cycles left out: the log names how many those are, per ensemble,
of the cycles of the run
(Ensemble 002: cycles up to 400 (400 of 1000 recorded) are left out
...), and -skipb must exceed that number by the cycles to skip.
An ensemble with no cycle left is refused with an
error; continuing the run with
restart adds cycles that can
be analysed. The WHAM analysis, and every tool that reads the combined
path-data matrix, sums every cycle of a path, so it refuses such a run.
Two cases leave no trace in the run’s files: a change of
[tis] high_accept that output.toml does not record (a state
file edited by hand and resumed from), and rows appended after the
boundary by a version of PyRETIS that writes the crossing count.
Analysing an md-flux run¶
pyretis analyse of an md-flux run reads the cross.txt,
order.txt and energy.txt that the run wrote to the directory it
is run in, and writes one report with the flux analysis (the flux
through each interface, the time in the states, the efficiency), the
energy analysis and the order parameter analysis. The report is named
md_flux_report_cycles-<N>, with N the number of steps the analysis
covers: the steps of the parts it analyses, which the Total cycles of the
flux analysis gives. What the flux is, and which steps
count for it, is described with the md-flux keyword interfaces.
For a file the run did not write (order-file, energy-file or cross-file below 1), the report says so
where the results of its analysis would be, the other analyses complete
and their reports are written, and pyretis analyse exits with status
1, as it does whenever an analysis does not run. The same holds when the
flux analysis stops for one of the reasons below: the report says why it
holds no flux.
The parts of the run¶
An md-flux run is written in parts, a fresh run and each continuation
of a restart file, each with a start line and, when it ends, an end line
(see the parts of an md-flux run).
The analysis takes each part on its own, from the state of the run at its
start, and never joins two parts:
The flux of a part is counted from the state that its start line gives. A part in the state
unknown(the state of a fresh run that starts outside A and outside B, or outside A for a run with one or two interfaces, which its continuations keep until the run enters A or B) counts no time and no crossing up to the step of its first entry into A or B (into A, without B); the crossings of that step are not counted either, and from that step on the part counts. The Flux from column of the table below gives the step.The flux through an interface is the number of its effective crossings in all the parts divided by the time that all the parts spend in the overall state A. A run that is stopped and continued from its restart file has the same crossings and the same time in the overall state A as the run written in one piece, when the continuation makes the steps the run would have made, as a run with an internal engine does.
The time of each part in the overall state A is cut into windows of skipcross steps from the start of the part, the last window of a part holding the steps that remain. The windows of all the parts, in the order of the parts, each weighted by its length, give the running average and the block error of the flux. A window never holds time of two parts, so the error estimate of a run in parts can differ from that of the run in one piece, and its flux does not.
The energy and order parameter analyses take the rows of all the parts that the analysis keeps (see below), in the order of the parts: the averages, the running averages and the distributions are over all of them, as for a run in one piece. The block error takes blocks of rows of one part, and the mean square displacement of the order parameter takes its lags within a part, pooled over the parts (see maxblock and maxordermsd).
A part that starts at step S can make steps again that an earlier part
made: a run that was killed after its last restart file and continued from
it, a run continued from an older restart file, and a run started again
in the same folder with backup = "append". In each file the analysis
then leaves out of every earlier part the rows of the steps from S on
and the crossings of the steps after S, and reads those of the later
part; the crossings of step S stay with the earlier part, since the
start line of the later part gives the state after them. A fresh run
started again in the folder replaces every part before it. The report
names what it leaves out: the Left out column of its table, and a note
for each part that is replaced whole, which the log gives as a warning
too, as
cross.txt: a part that starts at step 0 replaces part 1 from step 0; its
12 crossings are not analysed.
A part ends at the step of its end line. A part without one, as a killed
part, ends at its last row of order.txt or energy.txt, the later of
the two. A part with neither a row nor an end line holds nothing to
analyse: it contributes nothing, its crossings are left out, and the
message says so (Part 1 from step 0 holds no row of order.txt or
energy.txt and no line that marks where it ended). Rows and crossings
after the end of a part are left out as well.
The report holds a table of the parts, Parts of the run, with a row for
each part kept in the files, and the notes below it. This is the table of
a run that was killed after step 3383 and continued from its restart
file at step 3000, with the flux analysis done:
+------+-------+------+-------------+-----------+-----------+------------------------------------------------+
| Part | Start | End | Ended | Flux from | Overall A | Left out |
+======+=======+======+=============+===========+===========+================================================+
| 1 | 0 | 3383 | no end line | 0 | 3000 | from step 3000: cross 2, energy 384, order 384 |
+------+-------+------+-------------+-----------+-----------+------------------------------------------------+
| 2 | 3000 | 5000 | normal end | 3000 | 1593 | none |
+------+-------+------+-------------+-----------+-----------+------------------------------------------------+
Part is its number, Start and End its first step and its end
(the step of the end line, or of the last row), Ended how it ended
(normal end, soft exit, error, no end line, no row and no
end line, or from the settings for a run without lines that ends where
its settings give), Flux from the step the flux analysis counts it from
(never when its state never becomes known, and for a part that ends
nowhere), Overall A its steps in the overall state A, and
Left out what the analyses leave out of it: the rows of the steps that a
later part made again (from which step, and how many of cross.txt,
energy.txt and order.txt), and the rows after its end. The
flux columns hold - when the flux analysis stopped.
When the analysis is given the files of one continuation, run in a folder of its own, it analyses that part: from the step it continues from, in the state its start line gives. Its report is named after the steps of that part.
When the analysis stops¶
The flux analysis stops alone, and the report says why, in these cases:
A part wrote rows to
order.txtorenergy.txtand no line tocross.txt: the part ran with [output] cross-file below 1, socross.txtmay not hold every crossing of the run. Run the simulation again from its start withcross-file = 1.The crossings of
cross.txtare not those of an md-flux run: a crossing that cannot follow the state of the run (the message names the file, the line and the crossing), or a crossing of an interface number that the settings of the analysis do not have, as when the analysis is given other interfaces than the run had. Analyse the files that the run wrote, unchanged, with the interfaces it ran with.The run spends less time in the overall state A than one window (
skipcross), or none (a run that stays in B, one that starts in B and never enters A, one whose state stays unknown). Start the run in A, run it longer, or set a smallerskipcross.
All three analyses stop, with one message, in these cases:
The files hold no start line and show more than one part: a step that repeats or goes back, a first row after step 0 that is not [simulation] startcycle (a continuation in a folder of its own), a
[simulation] restartin the settings of the run (the run continues an earlier run), or backups of the settings file,out.toml_000, … in the folder (a run started where a run ran before). The message names what it found. Run the simulation again with this version of PyRETIS, which writes the lines that mark the parts. When the files hold one run and only the backups show another (a run started again in the folder withbackup = "backup"writes its files anew and leaves the backups beside them), move the backups out of the folder.Some parts have start lines and the rows of another part have none, and no part starts at their first step or before: the rows belong to a run of a PyRETIS that writes no such lines. Analyse each run in a folder of its own. (A part that starts at the first step of such rows or before replaces them, as it replaces a part with lines, and the report says so.)
A file that no run writes: an end line of a part that is not the one open in the file, a row after the end line of its part, a row before the start step of its part, or rows whose steps go back.
Files of an earlier PyRETIS¶
The order.txt, energy.txt and cross.txt of a run of a
PyRETIS that wrote no lines that mark the parts hold one part, when
they show no sign of more than one (above): the analysis reads it from the
first row of order.txt or energy.txt (step 0, or
[simulation] startcycle) to its last row, and the table of the report
gives its number as - and no end line. The state of the run at its
first step is taken from its crossings (a first crossing of an interface in
the positive direction shows that the run started to its left) and,
without crossings, from the first row of order.txt; a run that starts
between A and B waits for its first entry into A or B, as above. When that
row has the digits of the first interface, or, with three interfaces or
more, of the last (order.txt holds six decimals), the run may have
stayed on either side of it, and the flux analysis stops: start the run
away from the interface.
When the settings of the run give a later end ([simulation] endcycle,
or steps) than its last row, the run stopped there or did not write its
last steps, and the analysis ends at the last row; the log and the report
say so. A run that wrote cross.txt alone ends where its settings give,
which no row shows: the log and the report say so, and a run that stopped
earlier is counted up to that step in the state it stopped in, so its
flux is too low when that is the overall state A.
Acceptance ratios¶
The report’s Pathensemble data table gives, per ensemble, the fraction of attempted moves that were accepted – separately for the shooting-like moves and for the swapping moves.
These are counted from moves.txt – one line per attempted
move: the cycle, the move that ran, and the status it ended in (ACC,
or a rejection code such as BWI or NCR; see
Path types and rejection reasons). It is the only record of a
rejection. pathensemble.txt beside it says which path each
ensemble holds, so every one of its lines is an accepted path by
construction – counting those would report every move as accepted. See
moves.txt – what the sampler attempted for the file’s columns.
A cycle in which two ensembles were picked together is a swap, whatever
shooting move those ensembles are configured with, and is recorded in
both partners: under the + code in the lower-index one and the -
code in the higher. The pair of codes says which swap it was –
s+/s- for the zero swap between [0^-] and [0^+],
p+/p- for the PPTIS/REPPTIS swap between adjacent ensembles.
That is what makes the swap ratio computable at all.
Two further columns report what counting acceptances cannot.
HA eff. is for the high-acceptance moves – wire fencing and stone
skipping. Those are built so that a trial is accepted almost every time;
what varies is the weight the accepted path carries, its crossing
count. A plain acceptance ratio therefore sits near 1.000000 however
the sampling is doing, and says nothing. This column reports instead the
weight collected per attempt,
which reduces to the ordinary acceptance ratio when every weight is 1.
Two ensembles that both accept every wire-fencing trial can differ by a
factor of four here, and that difference is the one that matters. The
high-acceptance moves are excluded from the shooting column for the same
reason; an ensemble that runs only wire fencing shows n/a there.
Exchange answers the question the swap column cannot on most
ensembles. Under infinite swapping only the zero swap is an
accept/reject move; every other ensemble exchanges by having its
occupancy redistributed over the live paths. A cycle in which one path
holds the whole ensemble exchanged nothing; a cycle split 0.9 / 0.1
exchanged a tenth. This column averages 1 - (largest share) over the
analysed cycles, so 0 means the ensembles are not communicating and
larger means more exchange. It is the same quantity a swap acceptance
ratio measures, on the routes where no swap is ever proposed.
A ratio is shown as n/a when it cannot be formed: the move was never
attempted in that ensemble (a per-interface TIS run attempts no swaps, so
its swap ratio is always n/a). A move that was not attempted has no
acceptance ratio – it is not a ratio of one.
Comparing these numbers with PyRETIS 3¶
The column is called Shoot acc. ratio in both versions but it does not count the same moves, so the two are not directly comparable.
PyRETIS 3 divided everything that was not a swap by its attempts. That
denominator included the time-reversal move, and it included the null
move, which is accepted by definition. PyRETIS 4 counts only the moves
that actually shoot – sh, bias and wt – so it answers “how
often does shooting succeed here?” rather than “how often did this
ensemble keep a path?”.
The difference is not cosmetic, and it is largest exactly where it
misleads most. In a 2000-cycle RETIS run of the 1D double well, the two
versions report this for the outermost ensemble [3^+]:
Counted over |
|
Agreement |
|---|---|---|
PyRETIS 3, as reported |
0.522 |
– |
PyRETIS 3, null moves removed |
0.278 |
– |
PyRETIS 4, as reported ( |
0.215 |
– |
PyRETIS 4, counted as |
0.283 |
0.006 from PyRETIS 3 |
PyRETIS 3’s 0.522 is almost twice its own shooting performance: 511 of its attempts in that ensemble were null moves, every one of them accepted. Once those are removed the two versions agree to 0.006. The same holds for the other ensembles, where null moves are rarer and the two numbers were never far apart to begin with.
So if you are reproducing a PyRETIS 3 result, expect this column to drop, most visibly in the outer ensembles – the sampling has not got worse, the ratio has stopped counting moves that could not fail.
The swap column differs for a structural reason rather than a
book-keeping one: PyRETIS 3 proposed a discrete swap between every
adjacent pair and could report a ratio for each, while under infinite
swapping only the zero swap is an accept/reject move. Every other
ensemble therefore shows n/a there and reports Exchange instead,
as described above.
Older runs are still analysed. Before moves.txt the attempted
moves were written into pathensemble.txt itself with a trailing
Trial column, and before that into a separate trials.txt;
both are read.
Only one case genuinely has no answer: output written by the scheduler
between those conventions, which holds accepted paths only. That is
reported as n/a rather than as the 1.000000 those rows would
otherwise produce.
Note
In pathensemble.txt the Mc column is a different thing:
it names how the path was originally generated, which for a path
that arrived by a swap is the move that created it in its previous
ensemble. Read moves.txt for what was attempted here.
The same counts are logged at the end of a run, per move in brackets.
The total before the brackets counts every attempted move, the
frequency moves such as tr included, so it is not the report’s
Shoot acc. ratio, which counts sh, bias and wt only:
Acceptance (attempted trials, per ensemble):
000: 10/11 = 0.9091 [s+: 5/5 sh: 1/2 tr: 4/4]
001: 11/12 = 0.9167 [s-: 5/5 sh: 0/1 tr: 6/6]
A very low ratio usually means the interfaces are placed too far apart, or the shooting move is too aggressive for the system.