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

Table 53 Description of input arguments for pyretis analyse

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 LOG_FILE. The default is pyretisanalyse.log.

-l LOG_LEVEL, –log_level LOG_LEVEL

Level of the log file, such as DEBUG, INFO (the default), WARNING or ERROR.

-skipb N, –skip-begin N

Discard the first N cycles (equilibration); a count of 0 or less discards none. Optional; without it the input’s skip_initial_cycles applies (default: none).

-skipe N, –skip-end N

Discard the last N cycles, for instance after an interrupted run; a count of 0 or less discards none. Optional; without it the input’s skip_final_cycles applies (default: none).

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.txt or energy.txt and no line to cross.txt: the part ran with [output] cross-file below 1, so cross.txt may not hold every crossing of the run. Run the simulation again from its start with cross-file = 1.

  • The crossings of cross.txt are 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 smaller skipcross.

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] restart in 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 with backup = "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,

\[\text{HA eff.} = \frac{\sum \text{weight of the accepted trials}} {\text{trials attempted}}\]

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

[3^+]

Agreement

PyRETIS 3, as reported

0.522

–

PyRETIS 3, null moves removed

0.278

–

PyRETIS 4, as reported (sh only)

0.215

–

PyRETIS 4, counted as sh + tr

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.