RETIS in a 1D triple-well: the `zero_left` shortcut¶

This example shows how a left interface for the [0:math:^-] ensemble (set with the zero_left keyword) can make a RETIS simulation a lot cheaper, and what it does to the flux of a rate calculation.

The motivation is simple. In RETIS the [0:math:^-] ensemble samples the recrossings inside the reactant state. By default, paths in [0:math:^-] can wander arbitrarily far to the left of \(\lambda_0\). In a multi-state landscape this means they can fall into a neighbouring metastable well, where they get trapped and finally rejected at maxlength. zero_left adds a hard left boundary to [0:math:^-] so that paths that would escape into the neighbouring well are rejected on the spot with the cheap 0-L status code (BWI for a trial that starts at zero_left).

Verification status: passing – see Tutorial map.

Tutorial quick start¶

Best starting point: examples/tutorials/path_sampling/internal/1D-triple-well/.
Edit first: compare retis-no-zero-left/retis.toml and retis-zero-left/retis.toml; the key setting is zero_left in the [simulation] section.
Run: execute pyretis run -i retis.toml -p in each variant directory.
Analyse: run pyretis analyse -i retis.toml in each completed variant directory, then run python compare.py from the tutorial directory.
Expected output: two comparable RETIS output trees and a short comparison of [0:math:^-] path cost.
Related checks: represented by the internal RETIS checks and the tutorial smoke runner; see Example test status.

The system¶

We use the TripleWell potential

\[V(x) = a x^6 + b x^4 + c x^2 + d x\]

with \((a, b, c, d) = (1, -3, 2, 0)\). This gives three minima

A at \(x \approx -1.256\) (well depth \(\approx -0.39\))
B at \(x = 0\) (metastable intermediate, \(V = 0\))
C at \(x \approx +1.256\) (well depth \(\approx -0.39\))

separated by two barriers of height \(\approx 0.385\) above B at \(x \approx \pm 0.65\). From the A side, the same barriers are \(\approx 0.776\) high, so a particle that drops into A spends many integration steps before escaping.

We sample only the B \(\to\) C transition. Without a left bound, [0:math:^-] paths that wander into A inflate the sampling cost; with a left bound at \(x = -0.4\) (well inside the B basin) they cannot reach A at all.

The two input files¶

The example ships two input files that differ in one line.

Baseline (retis-no-zero-left/retis.toml) – a retis run samples [0:math:^-], here without a left bound:

Simulation
----------
task = retis
steps = 250
interfaces = [0.05, 0.20, 0.40, 0.55, 0.90]
seed = 0

With zero_left (retis-zero-left/retis.toml):

Simulation
----------
task = retis
steps = 250
interfaces = [0.05, 0.20, 0.40, 0.55, 0.90]
zero_left = -0.4
seed = 0

Everything else (interfaces, engine, temperature, seeds, output) is identical. The full input files are bundled with the PyRETIS sources under examples/tutorials/path_sampling/internal/1D-triple-well/.

The triple-well potential itself is specified by:

Potential
---------
class = TripleWell
a = 1.0
b = -3.0
c = 2.0
d = 0.0

Running the example¶

Each variant runs in roughly one minute on a typical laptop. From the example directory:

cd retis-no-zero-left
pyretis run -i retis.toml -p
pyretis analyse -i retis.toml

cd ../retis-zero-left
pyretis run -i retis.toml -p
pyretis analyse -i retis.toml

A small helper script then reports the [0:math:^-] ensemble cost for both runs:

"""Compare the [0^-] cost of the two triple-well RETIS runs.

Run after both ``retis-no-zero-left`` and ``retis-zero-left`` have
been simulated and analysed. The script reads ``000/pathensemble.txt``
in each directory and reports the accepted-path statistics that show
the cost of the [0^-] ensemble.
"""
import os
import sys

Run it with python compare.py.

What to look for¶

In a typical run, the variant with zero_left shows:

zero FTX / BTX rejections in [0:math:^-] (rejections appear as the much cheaper 0-L and BWI statuses), and fewer MD steps spent in [0:math:^-] (the MD-steps column of 000/moves.txt);
the same B \(\to\) C crossing probabilities in [0:math:^+], [1:math:^+], …, within their statistical errors;
a higher flux: the [0:math:^-] of a rate calculation holds only the paths that turn back before zero_left, and the flux is computed from them, without the longer excursions it rejects. pyretis analyse warns when more than 1 % of the [0:math:^-] trials were rejected at zero_left; with zero_left = -0.4 a few percent are.

That is the take-away: zero_left keeps the [0:math:^-] out of a neighbouring long-lived basin you are not interested in sampling, and the flux leaves out the paths it stops, so place it where the [0:math:^-] paths seldom reach it.

Going further¶

Move zero_left toward the A-B barrier (e.g. -0.6) and watch the share of rejections at zero_left drop; move it toward the first interface (e.g. -0.2) and watch it grow.
Add a tilt to the potential (d parameter of TripleWell) to make A deeper and the trapping effect more dramatic.
Change [retis] swapfreq to see how the share of swaps of [0:math:^-] \(\leftrightarrow\) [0:math:^+] changes.

Tested by¶

The tutorial is included in examples/tutorials/path_sampling/internal/1D-triple-well/ and runs every time the tutorial smoke runner (examples/run-tutorials.sh) is invoked, including from the top-level ./test-heavy.sh.
A dedicated, deterministic regression fixture lives at examples/tests/test-internal/retis-zero-left/. It runs the same two input files at a much smaller size, checks that the 0-L rejections appear in [0:math:^-] (and may propagate to [0:math:^+] through a failed swap-zero) but never in [1:math:^+] or beyond, and that zero_left does not produce FTX/BTX rejections in [0:math:^-]. Run it with:
```
cd examples/tests/test-internal/retis-zero-left
./run.sh
```

RETIS in a 1D triple-well: the zero_left shortcut¶