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 for ``class = lammps_steps`` with ``velocity_generation = engine``: LAMMPS draws the shooting velocities with velocity create, at the target temperature of the RETIS simulations, which 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). class = lammps, and class = lammps_steps with velocity_generation = maxwell, draw the velocities in PyRETIS, at the temperature of the engine section, with the constants of LAMMPS real units, and require units real in lammps.in (see velocity_generation).

  • Masses in the data file for ``class = lammps``, and for ``class = lammps_steps`` with ``velocity_generation = maxwell``: PyRETIS takes the masses of the atoms from the Masses section of the LAMMPS data file, so lammps.in has no mass command, which sets masses in LAMMPS in place of those of the data file. A mass command in lammps.in stops the run with an error: for class = lammps when the engine is set up, and for class = lammps_steps at the draw of a configuration held in a data file; its draw of a frame of a dump reads the data file that LAMMPS writes for the frame, with the masses of the mass commands (see atom_style).

  • Mandatory format with ``order_mode = lammps``, the default of ``class = lammps_steps``: 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 mode corresponds to order_mode = lammps in the PyRETIS engine section, the default of class = lammps_steps.

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
temperature = 300.0
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 = pyretis_distance
index = [0, 1]
periodic = True

Collective-variable
-------------------
class = pyretis_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.