Quickstart

After installing PyRETIS, you can run simulations by using a text based input file or by using the PyRETIS library explicitly.

The former approach is perhaps the simplest, but you will first have to learn how to create input files and this is explained in the input description.

The latter option is more involved, but you are then given more freedom in defining, running and interacting with a simulation. In order to make use of the library, you will have to read about the structure of the PyRETIS library in the introduction to the library and in the detailed reference section.

A more extensive overview can be found in the full user guide. Since version 2.4, PyVisA is automatically installed with PyRETIS. Here, we report some examples showing the use of PyRETIS and PyVisA.

Quickstart workflow

Your first run takes one input file and two commands. The file below is a complete RETIS simulation of a single particle in a double well – it is the minimal input file tutorial, and it is short because PyRETIS only needs to be told the physics and fills in everything else.

1. Install PyRETIS in a Python 3.11+ environment:

   python -m pip install pyretis
   

2. Check that the command-line tools are available:

   pyretis run --version
   pyretis analyse --version
   

3. Create a directory with two files. The first is the input, minimal.toml:

   # 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 = "pyretis_position"
   dim = "x"
   index = 0
   

   The second is the starting configuration it points at, initial.xyz – one particle at \(x = -1\):

   1
   
   Ar -1.0 0.0 0.0
   

   Both ship with PyRETIS under examples/tutorials/path_sampling/internal/1D-double-well/minimal/, so you can copy that folder instead of typing them.

4. Run the simulation (about a minute):

   pyretis run -i minimal.toml -p
   

5. Analyse it. The analysis reads the same input file as the run:

   pyretis analyse -i minimal.toml
   

After a successful run you have a pyretis.log, one numbered folder per path ensemble (000, 001, …), an output.toml recording the settings the run actually used – including every default it filled in – and, after the analysis, a report/ folder with the crossing probabilities and the rate.

What that run actually does

A path-sampling run has two phases, and the log shows them in order.

1. Initiation. Before anything can be sampled, every path ensemble needs one trajectory that already belongs to it – a path that starts and ends in the right places and crosses that ensemble’s interface. The run generates these from the starting configuration you supplied (method = "kick", the default): it gives the system a random kick, integrates forwards and backwards until the trajectory terminates, and keeps it if it satisfies the ensemble. You will see one Found initial path for [0^-], [0^+], [1^+] … line per ensemble. This phase produces no statistics; it only gets each ensemble a valid starting point.

2. Sampling. Then the actual Monte Carlo begins, and it is what steps counts. Each step picks an ensemble, proposes a new trajectory for it – usually by shooting: pick a point on the current path, draw new velocities there, and integrate outwards to get a fresh trajectory – and accepts or rejects it. RETIS additionally swaps trajectories between neighbouring ensembles, which is what lets the outer ensembles be reached at all. The ensemble’s pathensemble.txt records both sides of this: every trial that was attempted, accepted or rejected, and the paths the ensemble ends up holding. The log line for each step names the move, the ensemble and the outcome (ACC, or a rejection code with its reason).

The point of the whole procedure is the rare event: each ensemble measures how often a trajectory that reached its interface goes on to reach the next one. Those conditional probabilities multiply into the crossing probability of the full transition, which – combined with the flux out of the initial state – gives the rate constant that pyretis analyse reports. Calculating the rate works that identity through, and says where each factor comes from in a run.

Because sampling is a Monte Carlo procedure, its numbers are only as good as the number of steps: the 100-step run above is enough to see the machinery work end to end, not to quote a rate.

Continuing a run

To sample further, restart from the output.toml the run wrote:

pyretis run -i output.toml -p

One thing to know before you do: ``steps`` is the total number of cycles for the run, not the number to add. A run that has completed 100 steps and is restarted with steps = 100 still has nothing to do, and stops immediately – so raise steps to the new total (steps = 500 continues to cycle 500, adding 400). The log states which case you are in, either

Restarting from step 100; sampling continues up to the total of 500
steps set in [simulation] steps (400 cycles to go).

or, when the target has already been reached, a warning naming the number of completed steps and telling you to raise it.

From here, the minimal-input tutorial explains what each section of that file is for and what got defaulted, and RETIS in a 1D potential builds the same simulation the long way, one setting at a time.