Running PyRETIS

PyRETIS is executed using the pyretis run application and a PyRETIS input file:

pyretis run -i INPUT

where INPUT is the input file. This will produce output files which can be analysed using the pyretis analyse application.

In the following, we describe the syntax for the PyRETIS input file.

The PyRETIS input file

PyRETIS simulations can be set up and run with a simple input file. The input file defines a simulation by setting values for keywords which are organised into sections. Here we will discuss the following:

Structure of the input file

The input file is written in TOML. It is organised into sections, written as a name in square brackets, and each section sets keywords with keyword = value:

[simulation]
task = "md-nve"
steps = 100

This sets the two keywords task and steps of the simulation section. A section runs until the next section name, so the order of the keywords inside it is free, and the order of the sections themselves is free as well.

Some sections are nested, written as a dotted name:

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

Formatting of keywords

Section names and keywords are lower case, and the file is case-sensitive: [Simulation] and TASK are refused, with a message naming the section or keyword it could not place.

Each value carries its type. Text is quoted, numbers are written plainly, booleans are true and false, and a list is written in square brackets:

[tis]
maxlength = 20000
sigma_v = -1
high_accept = true
shooting_moves = [
    "sh",
    "sh",
    "wf",
]

A value that is itself a set of named settings is written as a table, either inline or as its own section:

potential = [
    { class = "DoubleWell", a = 1.0, b = 2.0, c = 0.0 },
]

Because a quoted value is taken exactly as written, the names of external Python modules and classes, and the names of files, keep their case:

[engine]
class = "MyExternalClass"
module = "filename.py"

PyRETIS expects the file filename.py under exactly that name. The same holds for a unit you define yourself, where "m" and "M" are different units:

[unit-system]
length = [1.0, "m"]

Comments

A # starts a comment, and the rest of the line is ignored. A comment can stand on its own line or follow a value:

# The settings that define the simulation.
[simulation]
task = "md-nve"  # not TIS this time
steps = 100

[system]
temperature = 1.0

Summary

  • The input file is TOML. It is organised into [sections] whose keywords are set with keyword = value.

  • Section names and keywords are lower case, and the file is case-sensitive.

  • Text is quoted, booleans are true and false, and lists are written in square brackets.

  • Comments are marked with a #.

How much you actually have to write

Most of the sections below are optional. PyRETIS only needs to be told the things that define your problem – the potential, what to run, the system, how it is propagated, where it starts, and how progress is measured – and supplies defaults for the rest, including the move set, the initiation, the output frequencies, the path-length cap and the simulation box.

Twelve keywords, across five sections, plus the potential, are enough to run a complete RETIS simulation. This is the whole input 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

Each of the twelve states something only you can state:

  • simulation – task what to run, steps for how long, and interfaces where the interfaces that define the path ensembles lie.

  • system – dimensions and temperature.

  • engine – class how the dynamics are propagated, with the settings that engine needs, here timestep and the Langevin friction gamma.

  • particles – input_file, the configuration the run starts from.

  • orderparameter – class, dim and index: what progress is measured along.

The potential above it is the energy landscape. Everything else has a default: the move set, the initiation, the output frequencies, the path-length cap and the box.

A minimal input file walks through this same file and lists what gets defaulted. When a run starts it writes out the fully resolved settings, so you can always see what every default resolved to for that run.

The sections in the input file

The following sections are recognised by PyRETIS:

  • simulation: For defining the simulation we are going to run.

  • system: For defining system properties.

  • box: For defining a simulation box.

  • particles: For defining the initial state of particles.

  • forcefield: For defining a forcefield.

  • potential: For defining potential functions to use in the force field.

  • engine: For defining the simulation engine.

  • orderparameter: For defining the order parameter.

  • retis: For defining settings for a RETIS simulation.

  • repptis: For defining settings for a PPTIS or REPPTIS simulation.

  • initial-path: For defining settings to initialize a RETIS simulation.

  • tis: For defining settings for a TIS simulation.

  • output: For defining output settings.

  • unit-system: For defining custom unit systems.

In addition, there are analysis specific settings which can be set by making use of the following section(s):