The PyRETIS analysis application¶

The PyRETIS analysis application, pyretis analyse, is used to analyse the results from PyRETIS simulations.

Input arguments¶

Table 49 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.
-skipb N, –skip-begin N	Discard the first `N` cycles (equilibration). Optional; without it nothing is discarded.
-skipe N, –skip-end N	Discard the last `N` cycles, for instance after an interrupted run. Optional; without it nothing is discarded.

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, 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 which cycles it dropped.

The chosen window applies to everything the analysis reports: the crossing probabilities, the rate, and the acceptance ratios below.

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 as s+ in the lower-index partner and s- in the higher one. 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.

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 numbers are logged at the end of a run, broken down per move:

Acceptance (attempted trials, per ensemble):
  000: 34/50 = 0.6800   [sh: 34/50]
  001: 25/50 = 0.5000   [sh: 21/40 tr: 4/10]

A very low ratio usually means the interfaces are placed too far apart, or the shooting move is too aggressive for the system.