Running PyRETIS

PyRETIS is executed using the pyretisrun application and a PyRETIS input file:

pyretisrun -i INPUT

where INPUT is the input file. This will produce output files which can be analysed using the pyretisanalyse 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 organised into sections and for each section, keywords are used to define your settings. The syntax for setting keywords is keyword = setting, and sections are marked by the section title followed by an underline of dashes --------, for example:

Simulation settings
-------------------
task = md-nve
steps = 100

which sets the two keywords task and steps for the Simulation section. When specifying a section, only the first word in the section title is used to identify the title internally in PyRETIS. This means that you can just as well write the following:

Simulation
----------
task = md-nve
steps = 100

or add any text you like, e.g.:

Simulation master plan
----------------------
task = md-nve
steps = 100

Both this two examples define keywords for the Simulation section.

Formatting of keywords

The format of the input file is relatively free, you can for instance order things within sections as you prefer and the input is in general case-insensitive:

Simulation settings
-------------------
task = md-nve
units = lj

which is identical to:

Simulation settings
-------------------
UNITS = lj
tAsK = md-nve

There are some important exceptions where they keyword settings are in fact case-sensitive:

  • When using external Python modules and classes, for instance:

    Engine settings
    ---------------
    class = MyExternalClass
    module = filename.py
    

    Here, the values given for the class and the module keywords are case-sensitive.

  • When referring to external files, for instance:

    Particles settings
    ------------------
    position = {'file': 'myfile.gro'}
    

    Here, we are referring to a file named myfile.gro, and PyRETIS will expect this file to be present with exactly this file name.

  • When defining your own system of units:

    Unit-system
    -----------
    length = (1.0, 'm')
    

    Here, we are using a unit of 1 metre which is identified with a 'm' and not a 'M'.

Comments

You can also add comments to structure the input file:

Simulation settings
-------------------
task = md-nve
units = lj

# More settings:

System settings
---------------
temperature = 1.0

Comments are marked as starting with a '#' and all following text will be ignored, i.e.

task = md-nve  # set up and run a md-nve simulation not TIS this time.

is effectively the same as writing,

task = md-nve

Summary

  • The input file is organised into sections where keywords are set:

    SectionTitle
    ------------
    keyword = value
    
  • Comments are marked with a #.

  • Input is in general not case-sensitive unless you are referring to files and Python classes.

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.
  • 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):