A minimal input file

This is the shortest complete PyRETIS simulation: a RETIS run of a single particle in a double well, written with no optional settings at all. Every line of the input describes the physics of the problem. Everything else – the move set, how the first paths are made, the output frequencies, the path-length cap, the simulation box – is filled in by PyRETIS.

Start here if you want to see what PyRETIS genuinely needs to be told before you meet the full input description.

Verification status: passing – see Tutorial map.

Tutorial quick start

  • Best starting point: examples/tutorials/path_sampling/internal/1D-double-well/minimal/.

  • Edit first: minimal.toml.

  • Run: pyretis run -i minimal.toml -p (about a minute).

  • Analyse: pyretis analyse -i minimal.toml.

  • Expected output: numbered ensemble folders (000, 001, …), pyretis.log, output.toml, and a report/ folder after the analysis.

The whole input file

# The smallest input that runs a RETIS simulation. Every setting here
# describes the physics of the problem; everything else -- the move set,
# the initiation, the output frequencies, the path-length cap, the box --
# PyRETIS fills in with defaults (they are echoed to output.toml).
potential = [
    { class = "DoubleWell", a = 1.0, b = 2.0, c = 0.0 },
]

[simulation]
task = "retis"
steps = 100
interfaces = [-0.9, -0.8, -0.5, 1.0]

[system]
dimensions = 1
temperature = 0.07

[engine]
class = "Langevin"
timestep = 0.002
gamma = 0.3

[particles.position]
input_file = "initial.xyz"

[orderparameter]
class = "Position"
dim = "x"
index = 0

That is the complete input. The only other file the run needs is the starting configuration it points at, initial.xyz, which holds one particle at \(x = -1\), the bottom of the left-hand well:

1

Ar -1.0 0.0 0.0

Run it with:

pyretis run -i minimal.toml -p
pyretis analyse -i minimal.toml

Note that the analysis reads the same input file as the run, not the output.toml the run writes.

What each section is for

Only a handful of things cannot be guessed, because each one is the problem you are posing:

potential

The energy landscape: here the double well \(V(x) = a x^4 - b x^2 + c\), which has two stable states near \(x = \pm 1\) separated by a barrier at \(x = 0\).

[simulation]

What to run – the retis task, how many Monte Carlo steps, and the interfaces defining the path ensembles. The first and last interface mark the two states; the ones between them slice up the barrier region.

[system]

That the system is one-dimensional, and the temperature it is sampled at. The temperature decides how rare the transition is, so it is a physical choice rather than a technical one.

[engine]

How trajectories are propagated: Langevin dynamics with the given timestep and friction gamma.

[particles.position]

Where the system starts, read from initial.xyz.

[orderparameter]

How progress along the reaction is measured – here simply the position of the particle, which is what the interfaces are placed on.

What PyRETIS fills in

Everything a longer input would spell out is defaulted. The ones that matter most for this run:

Table 59 Settings this input leaves to PyRETIS.

Setting

Default used here

[initial-path] method

kick – the first paths are generated by kicking off the configuration you supply.

[tis] maxlength

20000 steps: a deliberately generous cap on how long a trajectory may become.

[tis] shooting_move

sh – ordinary one-point shooting.

[retis]

The standard swap and null-move frequencies.

[output]

Sensible file-writing frequencies.

[box]

A non-periodic box around the 1D system.

The keyword pages linked above ([tis], [retis], [output], [box], [initial-path]) document each default and when you would want to override it.

Every setting a run actually used is written to output.toml when the run starts, so after a run you have the fully resolved version of the file you wrote. That is where to look when you want to know what a default resolved to, and what to copy from when you start pinning settings down explicitly.

Note

Two of these defaults are physical rather than cosmetic, so it is worth knowing they are there.

maxlength caps how long a trajectory may become; paths that reach the cap are rejected, and a cap that is too small biases the sampling. That is why the default is generous rather than tight – but for a system with genuinely long paths you should still set it deliberately.

temperature defaults to 1.0 when it is left out. For a rare-event simulation that is almost never what you want, which is why this tutorial sets it explicitly.

This run is deliberately short (100 steps) so it finishes in about a minute. The rate constant it produces is therefore only indicative; raise steps for statistics you would report.

Where to go next