The Analysis section

The analysis section defines parameters for the analysis.

Example Analysis section:

[analysis]
method = "matched"
skip_initial_cycles = 0
maxblock = 1000
blockskip = 1
bins = 100
ngrid = 1001
report = [
    "latex",
    "rst",
    "html",
]
maxordermsd = 100
txt-output = "txt.gz"
skipcross = 1000

[analysis.plot]
plotter = "mpl"
output = "png"
style = "pyretis"

A shorter example, a WHAM analysis that leaves out the first 100 paths of the run:

[analysis]
method = "wham"
skip_initial_cycles = 100
ngrid = 1001
bins = 100

Choosing the rate-estimation method

PyRETIS can estimate the crossing probability and the rate constant with two complementary methods, selected with the method keyword. Both read the sampled paths from the same simulation; they differ in how those paths are combined:

• matched (the default; crossing is accepted as the historical spelling) – the matched / point-matching analysis. It reads the per-ensemble pathensemble.txt files and matches the per-ensemble crossing-probability curves at the interfaces. This is the classic PyRETIS analysis and is available for every path-sampling task (tis, retis, pptis, repptis); the PPTIS/REPPTIS memory-kernel analyses build on its per-ensemble local probabilities. A biretis run is analysed this way only, for the two directions (see the biretis task): it refuses wham and both.

• wham – the weighted-histogram (WHAM) analysis. It reweights the shared paths across all ensembles in a single histogram, built from the same per-ensemble output every scheduler run writes (a literal infswap_data.txt, if one is present – from an older run, or from merging several runs’ path data – is read directly instead). Use it when you have an infinite-swapping run.

• both – run the two analyses and report each. When the run holds no path data for the WHAM analysis (an md-flux run), the matched analysis is run and the WHAM analysis is skipped with a warning (method = "wham" instead fails loudly if no usable path data is found). When the matched analysis fails, the analysis stops with an error and the WHAM analysis is not run.

The two methods are different estimators of the same physical rate, so on a converged simulation they agree within their statistical error. Comparing them with method = "both" is a useful cross-check.

The skip_initial_cycles and skip_final_cycles keywords leave the start and the end of the sampling out of the statistics; on the command line, pyretis analyse -skipb N -skipe M sets them and overrides the input file. The two methods do not leave out the same sampling:

• the matched analysis leaves out the first N and the last M cycles of the run;

• the WHAM analysis leaves out the first N paths of the run, counted by path number with the initialisation paths included (its report says Skipped initial paths: N), and keeps the last cycles: skip_final_cycles and -skipe do not change it.

So with a skip set, method = "both" does not compute the two estimates over the same production window. With neither the keywords nor the options, both methods use the whole run.

Keywords for the Analysis section

For the analysis section the following keywords can be set:

Table 45 Supported keywords for the analysis section.

Keyword	Description
method	Select the rate-estimation method.
skip_initial_cycles	Initial cycles to skip; the wham method skips as many initial paths instead.
skip_final_cycles	Final cycles to skip (matched method only).
bins	Set the number of bins to use when creating histograms.
blockskip	Selects certain block lengths to skip in the in the block error analysis
maxblock	Set maximum length of blocks to consider in the block error analysis.
maxordermsd	Set the maximum number of time origins to consider when calculating a mean square displacement.
ngrid	Number of points used for calculating the crossing probability.
plot	Settings related to plotting of results.
report	Define output format(s) for the report.
report-dir	Not read: the report goes to the folder report where pyretis analyse is run.
skipcross	Set time window for initial flux calculation.
txt-output	Select format for text-based output.
skip	Initial cycles to skip, in an older input; set skip_initial_cycles instead.
tau_ref_bin	Set the reference region of the permeability analysis.

Keyword method

method = string

The method keyword selects which rate-estimation method pyretis analyse runs. See Choosing the rate-estimation method for guidance. Valid choices are:

• matched – the matched (point-matching) analysis of the per-ensemble pathensemble.txt files (the classic PyRETIS analysis; crossing is accepted as the historical spelling).

• wham – the weighted-histogram (WHAM) analysis of an infinite-swapping run’s shared-path data (built from the per-ensemble output, or a literal infswap_data.txt if one is present).

• both – run both analyses and report each.

Default

The default value is: method = matched

Keyword skip_initial_cycles

skip_initial_cycles = integer

The skip_initial_cycles keyword sets the number of initial (equilibration) cycles to discard before the statistics are accumulated. The matched method leaves out the first skip_initial_cycles cycles of the run. The wham method leaves out the first skip_initial_cycles paths of the run instead, counted by path number with the initialisation paths included, so the two estimates of method = "both" are not computed over the same production window. When it is 0, the matched method uses the skip keyword of an older input instead; the wham method does not read skip.

Default

The default value is: skip_initial_cycles = 0

Note

pyretis analyse -skipb N sets this on the command line, overriding the input file. That is usually what you want: how much equilibration to drop is a question you answer after looking at the run, without editing (and re-saving) the input.

Keyword skip_final_cycles

skip_final_cycles = integer

The counterpart of skip_initial_cycles: the number of cycles to discard at the end of the sampling. This is what you reach for when a run was stopped part-way – a wall-time kill, a crashed node – and its final cycles are not to be trusted, or when you want to compare two runs over the same number of cycles.

pyretis analyse -skipe N sets it on the command line, overriding the input file.

Only the matched method applies it. The wham method keeps the final cycles whatever skip_final_cycles or -skipe say, although -skipe still logs Discarding the last N cycles (-skipe). To leave the final cycles of a run out of the rate, use method = "matched".

Default

Nothing is discarded.

Keyword bins

bins = integer

The bins keyword defines the number of bins to use when histograms are created.

Default

The default value is: bins = 100

Keyword blockskip

blockskip = integer

The blockskip keyword can be used to skip certain block lengths in the block error analysis. That is:

• blockskip = 1 will consider all blocks up to the value given in the keyword maxblock

• blockskip = n will consider every n’th block up to the value given in the keyword maxblock, That is, it will use block lengths equal to 1, 1 + n, 1 + 2*n and so on.

Default

The default value is: blockskip = 1

Keyword maxblock

maxblock = integer

The maxblock keyword defines the maximum length of the blocks to consider for the block error analysis. If a negative number is set, PyRETIS will set maxblock equal to (1/2) * length of the data we are analysing. This is also the maximum length that PyRETIS will consider, even if the input maxblock is set higher.

Default

The default value is: maxblock = 1000

Keyword maxordermsd

maxordermsd = integer

The maxordermsd keyword defines the maximum number of time origins to consider when calculating a mean square displacement. If this is set to a value < 0, PyRETIS will internally set maxordermsd to (1/5) * length of the data for which the mean square displacement will be obtained.

Default

The default value is: maxordermsd = -1

Keyword ngrid

ngrid = integer

The ngrid keyword defines the number of points used for the order parameter when PyRETIS is calculating the crossing probability as a function of the order parameter.

Default

The default value is: ngrid = 1001

Keyword plot

plot = dictionary

The plot keyword defines how plotting should be carried out. It is given as a dictionary, where the following keys can be used:

• 'plotter': Which selects the kind of plotter to use. Currently, PyRETIS only implements a plotter using matplotlib which is selected by setting plot = {'plotter': 'mpl'}.

• 'output': Which selects the output format for plots. This can be set to any of the supported output formats by the plotter. Often this will depend on your specific system, but common choices are 'png', 'pdf' and 'svg'.

• 'style': Selects a style for creating plots. Here you can, for instance, create your own matplotlib style or use one of the built-in styles. Please see http://matplotlib.org/users/style_sheets.html for more information.

Default

The default value is: plot = {'plotter': 'mpl', 'style': 'pyretis', 'output': 'png'}

Keyword report

report = list of strings

The report keyword defines the output format for the report. This is provided as a list of strings, where each item in the list correspond to a specific format:

• 'latex' selects latex output.

• 'rst' selects output in reStructuredText.

• 'html' selects html output.

Default

The default value is: report = ['latex', 'rst', 'html']

Keyword report-dir

report-dir = string

pyretis analyse writes the report, its figures and its text files to the folder report in the directory it is run from, and does not read this keyword: a report-dir in the input is accepted without a message and the report still goes to report. To keep a report apart from the next analysis, copy or rename the report folder.

Default

The folder report in the directory pyretis analyse is run from.

Keyword skipcross

skipcross = integer

The length, in simulation steps, of the time window the initial flux is averaged over in an md-flux analysis.

Note

The name is historical and misleading: nothing is skipped. The keyword is a window length.

The flux is the number of effective crossings of an interface per unit time. Measuring it once over the whole run would give a single number with no way to put an error on it, so the time the system spends in the overall \(A\) state is instead cut into windows of skipcross steps, and the flux is computed in each. That series is what the running-average plot and the block-error estimate are built from.

It does not change the flux itself. The mean over the windows is the total crossing count divided by the total time however the windows are drawn; only the spread of the series changes, and with it the error estimate:

skipcross	windows	mean flux	spread
500	200	0.50000	0.313
1000	100	0.50000	0.215
5000	20	0.50000	0.067
20000	5	0.50000	0.039

(the same 500 synthetic crossings over 100000 steps, binned four ways.)

So choose it for the statistics, not for the answer. Too small and each window holds a handful of crossings, so the series is noisy; too large and there are too few windows for a meaningful block analysis. A useful target is enough windows to block over – a few tens – with several crossings in each.

If the run does not contain even one full window, the analysis stops with an explicit error rather than producing an empty flux array: reduce skipcross or run longer.

Only the analysis of an md-flux run reads skipcross. A tis or retis run takes its flux from the [0^-] and [0^+] path lengths instead (see Where each factor comes from in a run); the analysis of a path-sampling run accepts skipcross without a message and does not use it.

Default

The default value is: skipcross = 1000

Keyword txt-output

txt-output = string

The txt-output keyword defines the format for how text-based output should be written. Valid choices are:

• txt for writing plain text files.

• txt.gz for creating gzipped files.

Default

The default value is: txt-output = txt.gz

Keyword skip

skip = integer

The number of initial cycles left out of the analysis, as an input of PyRETIS 3 sets it; set skip_initial_cycles instead. The matched method uses skip whenever skip_initial_cycles is 0: also when the input sets skip_initial_cycles to 0, and when pyretis analyse -skipb 0 is given (the analysis then prints Discarding the first 0 cycles (-skipb). and still leaves out skip cycles). The wham method does not read skip.

Default

The default value is 0.

Keyword tau_ref_bin

tau_ref_bin = list of floats

The order-parameter bin the permeability analysis takes as its reference region when it computes \(\tau\), given as the two edges of the bin. See Studying permeability with PyRETIS for a worked example.

Default

The default value is [].