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. output.toml records most of them;
# pyretis.log reports the box, the particle mass, the zero starting
# velocities and the force-field name. The particle type 0,
# high_friction = false and [orderparameter] periodic = false are
# recorded in neither file.
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 = "pyretis_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. The output.toml the run writes records that input with most of its defaults resolved (see “What PyRETIS fills in” below), so pyretis analyse -i output.toml gives the same analysis.

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 66 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] swapfreq

0.5 – the probability that a move picked in \([0^-]\) or \([0^+]\) is the swap of the paths of the two.

[output]

Every path’s energies and order parameter are written (energy-file and order-file = 1); every replaced path is kept in the archive (archive_every = 1): raise it for a long run.

[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.

The settings of the run are written to output.toml when the run starts, under the names of the input and with most of the defaults resolved, so after a run you have a 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. Some defaults of this run are not in it. pyretis.log reports these instead: the box, non-periodic, with a warning that asks for a [box] section; the particle mass, 1.0, taken from the particle name Ar of initial.xyz; the starting velocities, zero, with the warning Velocities not created/read: Set to zero!; and the name of the force field, Generic force field. These take their default without a record in either file: the particle type, 0, of [particles] ptype; [engine] high_friction = false (see high_friction); and [orderparameter] periodic = false (see periodic).

Note

Two defaults are physical rather than cosmetic, so it is worth knowing them.

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