Running LAMMPS with PyRETIS¶

This page describes how to use the LAMMPS Molecular Dynamics Simulator with PyRETIS.

Standard LAMMPS input¶

The LAMMPS-PyRETIS interface is designed to use LAMMPS’s internal ability to perform on-the-fly calculations. PyRETIS expects a LAMMPS input file to be present in the folder from which it is executed. This input file should contain all the information LAMMPS needs to run a simulation on your system, including but not limited to:

Initial coordinates and molecular topology, with force field coefficients if needed, in a LAMMPS data file. This file can be read into LAMMPS using the read_data command.
Information about units, bonded and non-bonded force field coefficients, and long-range electrostatics methods, if applicable.
A LAMMPS fix that will integrate the motion of the atoms in the system.

The LAMMPS input file should contain everything that is needed to run a normal MD simulation except for the run command.

PyRETIS requirements for LAMMPS input¶

In addition to the standard input requirements for a LAMMPS simulation, there are additional requirements for running LAMMPS with PyRETIS.

Mandatory format: The target temperature for the RETIS simulations must be set to a LAMMPS equal-style variable called SET_TEMP. An example is shown below:
```
variable SET_TEMP equal 300.0
```

In the above example, the system temperature is set to 300.0 K (assuming real LAMMPS units).

Mandatory format in the default ``order_mode = lammps`` mode: The order parameter(s) that PyRETIS tracks should be declared as LAMMPS equal-style variable(s). Multiple order parameters can be defined, but the first order parameter, op_1, will be used by PyRETIS to determine interface crossings.
```
variable op_1 equal c_1
variable op_2 equal c_2
```
In the above example, two order parameters will be tracked and output by LAMMPS to a file called order.txt. The first column of order.txt is the LAMMPS step, the second column is op_1, and the third column is op_2. Only op_1 is used by LAMMPS to determine crossing of the first or last interface and stop the simulation.

The above example refers to LAMMPS compute commands, referenced by c_1 and c_2, that return scalar values. By combining LAMMPS compute and LAMMPS variable commands, many calculations can be performed internally by LAMMPS. LAMMPS can also call Python scripts for more calculations. For clearer input files, order parameter calculations can be scripted in a separate file, order.in, and included in the main LAMMPS input script as follows:
```
include order.in
```
This is the default mode and corresponds to order_mode = lammps in the PyRETIS engine section.

Order parameters evaluated by PyRETIS¶

The LAMMPS engine can also evaluate order parameters and collective variables with the normal PyRETIS orderparameter and collective-variable sections. Select this behavior with:

Engine
------
class = lammps
lmp = lmp
input_path = lammps_input
subcycles = 1
order_mode = pyretis

In this mode, LAMMPS is used to propagate the dynamics and write trajectory frames. PyRETIS then reads those frames, reconstructs positions and velocities, and calls the configured PyRETIS order-parameter object. The first returned value is still the main order parameter used for interface decisions; any additional returned values or configured collective variables are stored as extra order/CV columns.

For example:

Orderparameter
--------------
class = Distance
index = [0, 1]
periodic = True

Collective-variable
-------------------
class = Position
index = 0
dim = x

When order_mode = pyretis is used, the LAMMPS input no longer needs to define op_1 in order.in. If your lammps.in still contains include order.in, the file must still exist or be listed as an extra_files dependency, because LAMMPS itself will try to read it.

The tradeoff is that LAMMPS cannot stop internally on v_op_1 in this mode. PyRETIS therefore runs LAMMPS up to the requested path length and truncates the resulting path after evaluating the Python order parameter. The traditional order_mode = lammps mode can stop inside LAMMPS as soon as v_op_1 crosses an interface.

Restrictions¶

There are some restrictions for the LAMMPS-PyRETIS interface.

Motion should be propagated using NVE dynamics, as NVT/NPT dynamics have not been shown to be accurately time-reversible in practice.
We recommend that the SHAKE algorithm not be used, because in practice it produces non-time reversible results due to the iterative nature of the algorithm.
Order parameters must not depend on the direction of velocity components.

Notes¶

The subcycle length, defined in the PyRETIS input file, refers to how often LAMMPS will print to the log file and the order.txt file.