Monitoring a running simulation¶
A path-sampling run is long, and the useful question during it is not “what is the rate” – that is the last thing to converge – but “is this run doing anything sensible?” A run that is sampling badly looks wrong within a few hundred cycles, in ways that are visible long before any rate is trustworthy.
Everything on this page can be done while the simulation is still running. PyRETIS writes its per-ensemble output incrementally and appends to it, so the output on disk is always a complete record of the cycles finished so far. Nothing here modifies the run, and nothing here needs the run to stop.
See also
Simulation outputs describes the files these commands read; Calculating the rate explains the rate itself, and Cleaning run artifacts how to reset a directory afterwards.
pyretis status: what each ensemble sampled¶
Run it in the directory the simulation is running in:
pyretis status
It reads the per-ensemble output in place, computes nothing expensive – no crossing probabilities, no matching, no rate – and prints what the sampler has actually been doing:
Per-ensemble status
Ens Cycles Trials Acc Rej Acc% Shoot Swap HA eff
----- ------------- -------- -------- -------- ------ ------ ------ -------
000 1-25 8 7 1 87.5 0.750 1.000 n/a
001 1-25 5 5 0 100.0 1.000 1.000 n/a
002 1-25 11 7 4 63.6 0.636 n/a n/a
003 1-25 5 5 0 100.0 1.000 n/a n/a
Moves attempted, per ensemble
000: s+: 4/4 (1.000) sh: 3/4 (0.750)
001: s-: 4/4 (1.000) sh: 1/1 (1.000)
002: sh: 7/11 (0.636)
003: sh: 5/5 (1.000)
* a high-acceptance move: read its HA eff., not its ratio.
Why trials were rejected
000: BTL: 1
002: NCR: 4
The codes are explained in the documentation: path types and
rejections.
Because it is cheap and read-only, it is safe to run repeatedly against
a live run – for instance under watch:
watch -n 60 pyretis status --no-moves
Reading the table¶
Column |
Meaning |
|---|---|
|
The ensemble directory ( |
|
The first and last cycle this ensemble has recorded. |
|
Monte Carlo moves attempted in this ensemble. |
|
How many of those were accepted, and how many rejected. |
|
The overall acceptance percentage over all move types. |
|
Acceptance ratio of the shooting-like moves alone, excluding the high-acceptance moves (which would drag it towards 1). |
|
Acceptance ratio of the swapping moves. |
|
For wire fencing and stone skipping: the weight collected per attempt. Those moves accept almost every trial, so their acceptance ratio is near 1 whatever the sampling is doing; the weight is what varies and what matters. |
A ratio is n/a when the move was never attempted in that ensemble.
A move that was not attempted has no acceptance ratio – it is not a
ratio of one.
What to look for¶
A very low shooting ratio in one ensemble usually means its interfaces are too far apart, or the shooting move is too aggressive for the system.
A dominant rejection code is the most useful single diagnostic on the page. Many
NCR(no crossing) means trials are not reaching the interface; the codes are listed in Path types and rejection reasons.``Swap`` at ``n/a`` in a RETIS run means the ensembles are not exchanging, which defeats the point of RETIS.
Ensembles with very different ``Cycles`` in an infinite-swapping run are expected – occupancy is spread over ensembles – but a stalled ensemble is not.
Options¶
Argument |
Description |
|---|---|
|
The directory the simulation ran in (default: the current one). |
|
Discard the first |
|
Discard the last |
|
Leave out the per-move breakdown. |
|
Leave out the rejection breakdown. |
|
Write the status as JSON, for further processing. |
The --json form is the one to build on if you are watching many runs
at once:
pyretis status --json | python -c \
"import json,sys; [print(e['ensemble'], e['rejections']) \
for e in json.load(sys.stdin)]"
Old runs are handled too. pyretis status reads the trial records
through the same reader the analysis uses, which knows every layout
PyRETIS has written – moves.txt, attempts recorded inside
pathensemble.txt, or a separate trials.txt.
Analysing a run that has not finished¶
pyretis analyse can be run against a live simulation:
pyretis analyse -i retis.toml
The analysis reads the output files as they stand and reports on the cycles completed so far. It does not touch the running simulation, and the simulation does not wait for it.
Two things are worth knowing:
The report is stamped with the cycle count (
<name>_report_cycles-NNNNNNNNN.rst), so analysing repeatedly during a run leaves a series of reports rather than overwriting one. That series is itself informative: the rate should stop moving.A rate from an unconverged run is not wrong so much as premature. Use
-skipbto drop the equilibration, and read Is it converged? before quoting anything.
The cheapest useful check during a run is whether the rate is still drifting. Analyse twice, a few hundred cycles apart, and compare – if the second is outside the first’s error bar, the run is not converged.
Visualising a run that has not finished¶
PyVisA can likewise be pointed at a running simulation:
pyretis pyvisa -i retis.toml
It reads the same output files and plots what is there. Re-loading picks up the cycles finished since. This is the fastest way to see the shape of a problem – a crossing-probability curve with a kink at one interface, or a path-length distribution with a tail that should not be there.
Resetting a directory afterwards¶
When a run is finished with, pyretis tools clean removes the
generated files and leaves the committed inputs:
pyretis tools clean --dry-run # list what would be removed
pyretis tools clean # remove it
Always use --dry-run first in a directory that holds anything you
staged by hand. The full description, including what counts as an
artifact and what is protected, is in Cleaning run artifacts.