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, lammps.in, in the folder that the input_path keyword of the engine section names. 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 in a LAMMPS data file. This file can be read into LAMMPS using the read_data command. Give the force field coefficients, if needed, with commands of the input file, as pair_coeff and bond_coeff after read_data: class = lammps_steps hands the configurations between LAMMPS runs in data files that it writes without coefficients and reads through that read_data command, so coefficients that only the data file holds are lost once a run continues from a configuration LAMMPS wrote, and LAMMPS stops with ERROR: All pair coeffs are not set.
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.

The temperature is stated in ``lammps.in``: PyRETIS reads the temperature of the run from lammps.in when the engine is created:
- the LAMMPS equal-style variable called SET_TEMP;
- the Tstart, equal to Tstop, of each thermostat fix: nvt and npt with their variants, bocs, gld, langevin, langevin/eff, temp/berendsen, temp/csvr, temp/csld, temp/rescale, temp/rescale/eff and the thermostats of the rigid-body fixes, and the temp of qtb;
- the Tstart, equal to Tstop, of the pair styles dpd/tstat and dpd/ext/tstat of the last pair_style command, also with the suffix of an accelerator package, as dpd/tstat/omp, and as a sub-style of hybrid or hybrid/overlay;
- the temperature of each velocity create and velocity scale command.
They must all be one temperature, equal to four machine epsilons relative to the larger, and a lammps.in that states none stops the run. A thermostat fix or pair style whose Tstart and Tstop are two temperatures, as fix 2 all gld 300 310 ..., stops the run, and so do the other fixes and pair styles that set or change the temperature, the pair styles dpd and dpd/ext among them, and a fix style that PyRETIS does not know; the error names the command. For example,
```
pair_style dpd/tstat 300.0 300.0 2.5 ${pyretis_seed}
```
states the temperature 300.0. With class = lammps_steps and velocity_generation = engine (the default), LAMMPS draws the shooting velocities with velocity create at SET_TEMP, which lammps.in must then set: a lammps.in without SET_TEMP stops such a run when it is set up, also when a thermostat fix, a thermostat pair style or a velocity command states the temperature. An example is shown below:
```
variable SET_TEMP equal 300.0
```
In the above example, the temperature of the run is 300.0 K (in real LAMMPS units; in units lj it is a reduced temperature, and [system] units must then be "lj"). [system] temperature and the temperature of the engine section are optional; when one is set, it must equal the temperature of lammps.in within a relative $10^{-9}$, and neither sets the temperature of the run (see the temperature keyword). class = lammps, and class = lammps_steps with velocity_generation = maxwell, draw the velocities in PyRETIS, at the temperature of lammps.in, 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).
The seed of a stochastic fix or pair style is ``${pyretis_seed}``: For each LAMMPS run, both LAMMPS engines draw a seed on their random generator and define it as the LAMMPS variable pyretis_seed on the command line. A fix or pair style that draws random numbers, such as fix langevin, takes it as its seed, so that every run draws other random numbers and a run with the same PyRETIS seed draws the same ones:
```
fix 2 all langevin 300.0 300.0 100.0 ${pyretis_seed}
```
An immediate expression of the variable, as $(v_pyretis_seed+1) or $(v_pyretis_seed + 1), gives a second fix its own seed. A run of an md task draws the seed on the random generator of the task. The restart file of the task stores the state of that generator, so that an md task restarted with [simulation] restart draws the seeds that follow those of its first runs; a restart file without it, written by an earlier version, stops the restart with an error, and a new md task from the last configuration of the run continues it. A run that integrates no time step (one that writes a configuration, generates velocities or reads a frame of a dump) defines pyretis_seed as 1. Before LAMMPS runs, PyRETIS reads the fix and pair_style commands of lammps.in and of the files it includes, and stops with an error at a seed that is a number, a LAMMPS variable other than pyretis_seed, or left out where the style then takes a seed fixed in LAMMPS. The styles are those of LAMMPS 22 Jul 2025 that seed a random generator from their command, among them the langevin styles, temp/csvr, temp/csld, gld, gle, gjf, ffl, the brownian styles, the langevin keyword of the fix rigid styles, the Monte Carlo fixes as gcmc and atom/swap, and the pair styles dpd, dpd/tstat and the other DPD styles; the full list is LAMMPS_FIX_SEED_ARGUMENTS, LAMMPS_FIX_SEED_KEYWORDS, LAMMPS_FIX_DEFAULT_SEED_KEYWORDS and LAMMPS_PAIR_SEED_ARGUMENTS of pyretis.engines.lammps_steps.
A path-sampling run integrates with velocities at the time of the positions: it reverses and draws velocities at a frame and integrates on from its positions. Integrate with fix nve, alone or with fix langevin (without gjf, or with gjf no), fix temp/csvr or fix temp/csld. Before it starts, and before any message about the temperature of lammps.in, a path-sampling run refuses fix langevin with gjf vhalf, which stores the velocities half a time step away from the positions (see the integrator of a path-sampling run); the md, md-nve and md-flux tasks accept it when PyRETIS reads the temperature of lammps.in. fix gjf and the Brownian dynamics of fix brownian, brownian/sphere, brownian/asphere and brownian/poly set the temperature of the atoms in a way PyRETIS does not read, and every task refuses them (above); path sampling of Brownian dynamics runs with the internal Langevin engine with high_friction = true.
Each piece of a path is a LAMMPS run of its own: every piece of trajectory a path-sampling run generates (the backward and the forward piece of a shooting move, the extension of a path in a swap move) starts LAMMPS from a stored frame, with the positions, the velocities, the image flags and the box of the frame, at time step 0. The variables a fix keeps of its own start again with each piece. Before it starts, a path-sampling run therefore refuses the fixes that carry such variables deterministically or that change the velocities or the box without time reversibility: fix nvt, npt, nph and their variants, the fix rigid styles rigid/nvt, rigid/npt and rigid/nph, bocs, the Drude tgnvt and tgnpt fixes, nphug, pimd, pimd/nvt, msst, qbmsst, pimd/langevin with ensemble nve or nph, temp/berendsen, temp/rescale, press/berendsen, heat, ehex, nve/limit, viscosity, thermal/conductivity, oneway and deform/pressure with a pressure control. It warns, and runs, for fix gld and qtb, for fix langevin with gjf vfull, for fix deform and the other deform/pressure styles, and for fix momentum every N > 1 time steps. Every task refuses the fixes that set the temperature in a way PyRETIS does not read (above), among them fix gle, ffl, nvk, press/langevin, the ttm fixes, pimd/langevin, fix viscous and damping/cundall, and a thermostat whose Tstart differs from its Tstop or whose target is a v_ variable. For a constant pressure, equilibrate the volume with a barostat in an md task and run the path sampling at that volume. The full lists and the reasons are in the thermostats and barostats of a path-sampling run.
The LAMMPS run starts at time step 0: PyRETIS names frame k of the dump of a LAMMPS run by the time step k * subcycles, and stops with an error after a run whose dump has a frame with another time step. read_data sets the time step to 0, and PyRETIS sets it to 0 after it reads a frame of a dump. A read_restart of lammps.in keeps the time step of the restart file, so follow it with reset_timestep 0 (see A LAMMPS restart file read by lammps.in), and leave out of lammps.in the run and minimize commands and a reset_timestep to another step.
The units come before the time step: LAMMPS sets the time step to the default of the unit system at a units command, and a clear command restores the default settings of LAMMPS, the time step among them. Set the units before the timestep command, and write no clear command after it. A units command after a timestep command, with no clear command between them, in lammps.in or in a file it includes, stops the run with an error that names both lines, when the engine is created and when pyretis analyse or the set-up of a path-sampling run reads the time step of lammps.in (see The time step).
The commands are read as LAMMPS reads them: PyRETIS reads the commands of lammps.in, of the files it includes and, with order_mode = lammps, of order.in as LAMMPS does: a line that ends with & continues on the next line, a text in triple quotes (""") can run over several lines and belongs to its command, as the text of a print command does, and a comment starts at the first # outside quotes. These files must be UTF-8 text, comments included, and each command, without its comment, must be ASCII; a UTF-8 byte order mark at the start of a file is a character that is not ASCII. Otherwise the run stops with an error that names the file and the line. The engines also stop the run, when they are created, at the commands that change which commands LAMMPS runs, if, jump, label, next, partition, python and run ... every, and at the fix styles python, python/invoke and python/move: write lammps.in without them.
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 with class = lammps_steps; class = lammps determines them with the orderparameter section (see order_mode).
```
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, for each LAMMPS run, to a file order_<run name>.txt in the directory LAMMPS runs in. The first column of the file 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. Each variable of order.in must read the positions of the atoms and the box only, as compute 1 all com or x[1]: LAMMPS evaluates the variables on the velocities of the LAMMPS run, which on a backward leg are those of the path reversed, and the engine stops at set-up with an error that names a variable that reads a velocity, a fix, or a compute or keyword that PyRETIS cannot tell to be independent of the velocities (order_mode lists what a variable may read). Such an order parameter needs order_mode = pyretis. 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. When the input also has an orderparameter section, as a load of frames without order.txt needs, the variables of order.in and the orderparameter and collective-variable sections must give each frame the same columns: the run stops with an error at the first frame they disagree on (order_mode).

A LAMMPS restart file read by `lammps.in`¶

lammps.in can start from a LAMMPS restart file with the read_restart command. LAMMPS then runs with the unit system, the time step and the pair style of the restart file: they replace those of the units and timestep commands before read_restart, and the pair style of a pair_style command before it. PyRETIS reads the unit system and the time step of the restart file, not its pair style, and lammps.in states what the run runs with, as in:

units real
atom_style atomic
read_restart equil.restart
reset_timestep 0
pair_style lj/cut 8.0
pair_coeff 1 1 0.238 3.405
variable SET_TEMP equal 300.0
fix 1 all nve

with equil.restart in input_path and extra_files = ["equil.restart"] in the engine section. This run has the unit system real, the time step of equil.restart and the temperature 300.0 K. When the engine is created, the run stops with an error for the first of these rules that lammps.in breaks, in this order, and when pyretis analyse or the set-up of a path-sampling run reads the time step of lammps.in (see The time step), for the first of the rules 1 to 3:

Units. A units command before read_restart, in lammps.in or in a file it includes, states the unit system of the restart file. A lammps.in without a units command stops the run: PyRETIS does not take the LAMMPS default units lj for it. A units command of another unit system than the one of the restart file stops the run, and the error names both; a units command after read_restart stops it too, as LAMMPS stops at it.
Time step. The run has the time step of the last timestep command after read_restart, and without one the time step of the restart file. A timestep command before read_restart gives the time step of the restart file, within a relative $10^{-9}$; another value stops the run, and the error names both values and the file. A timestep in the engine section, when it is set, must equal the time step of the run.
Pair style. A pair_style command, with its pair_coeff commands, follows read_restart, in lammps.in or in a file it includes. A pair_style command before read_restart does not count: the pair style of the restart file replaces it.
Temperature. SET_TEMP, before or after read_restart, a thermostat fix, or a dpd/tstat or dpd/ext/tstat pair style after read_restart states the temperature. A velocity command does not count, and neither does a thermostat pair style before read_restart.

read_restart names one file, by its absolute path or by a relative name. LAMMPS opens a file of a relative name in the directory it runs in, where the engine copies the files of extra_files from input_path: put the file in input_path and name it in extra_files. A relative name that is not a file of input_path stops the run when the engine is created, and a restart file that is not in the directory LAMMPS runs in, as one left out of extra_files, stops it before LAMMPS runs. Before each LAMMPS run, the engine checks the units and the time step of the restart file in that directory in the same way. A name with a LAMMPS variable, a * or a % stops the run: write the name of the file. PyRETIS reads restart files of the format revision 3, which LAMMPS 22 Jul 2025 writes, in the byte order of the machine it runs on; a restart file of another revision or byte order stops the run with an error that names the file.

Configurations held in LAMMPS restart files¶

PyRETIS does not start a LAMMPS run from a configuration held in a LAMMPS restart file: the input of the run would read it with read_restart after lammps.in, and LAMMPS accepts no fix command before the box that read_restart reads, so no fix would integrate the motion of the atoms. A configuration is held in a restart file when its file is a LAMMPS restart file, whatever its name, or when the name of its file ends with .restart and it names frame 0 or no frame. Such a configuration stops the run with an error before LAMMPS runs: as the initial configuration of the run, in a path that a run with a LAMMPS engine loads, and wherever a LAMMPS engine is asked to start from it. In a load folder without traj.txt, a trajectory file that is a LAMMPS restart file stops the load before any frame is read, whatever the engine (see Load folder layouts). Store the configuration as a LAMMPS data file, with write_data, or as a frame of a LAMMPS dump, and start from that.

The time step¶

The time step of a LAMMPS engine is the one that LAMMPS runs lammps.in with. With read_restart, it is the time step of the restart rules. Without read_restart, it is the one of the timestep command of lammps.in: write one timestep command, with a number, in lammps.in itself, after the units command. A timestep in the engine section, when it is set, must equal it.

pyretis analyse converts the path lengths of a run to time with the time per step of [engine], and a path-sampling run checks, when it is set up, that its engine sections have one time per step (see the initial flux). Both read the time step of a LAMMPS section that leaves timestep out from its lammps.in: for a lammps.in that reads a restart file, the time step of the run given above, which needs the restart file in input_path or at its absolute path; for another lammps.in, its timestep command. To tell whether lammps.in reads a restart file, PyRETIS reads the commands of lammps.in, of the files that its include and jump commands name, and the commands that if, run ... every, partition and mdi plugin run. It stops with an error that names the command at:

a units command after a timestep command, also with a clear command between them;
an include, a jump or a read_restart that another command runs;
an include or jump whose file does not exist, or is named by a LAMMPS variable that has no single value in the script, and a command whose name is such a variable;
Python in any form: the python command, the fix styles python, python/invoke and python/move, the pair style python and a variable of style python;
plugin load, mdi engine, the kim commands, and the shell commands other than mkdir, rmdir, rm and putenv;
a loop, a jump back to a label or to the start of a file, that runs again a command whose name, file or quoted commands are written with a LAMMPS variable, and a jump from an included file back to a file that includes it.

A LAMMPS section that sets timestep is not read this way.

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 order_mode = "pyretis", the default of class = lammps:

[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 = "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.

LAMMPS cannot stop internally on v_op_1 in this mode. With class = lammps, PyRETIS reads the frames as LAMMPS writes them and stops LAMMPS once the path is complete. With class = lammps_steps, PyRETIS runs LAMMPS up to the requested path length and truncates the resulting path after evaluating the Python order parameter; there, order_mode = lammps can stop inside LAMMPS as soon as v_op_1 crosses an interface.

Restrictions¶

There are some restrictions for the LAMMPS-PyRETIS interface.

A path-sampling run integrates with the fixes of the requirement above on velocities at the time of the positions; the thermostat and barostat fixes it refuses or warns for are listed in the thermostats and barostats of a path-sampling run.
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. With class = lammps_steps and velocity_generation = engine, a fix shake stops the run with an error at the first velocity draw; fix rattle and the fix rigid styles are drawn with their constraints (see velocity_generation).
Order parameters must not depend on the direction of velocity components.

Notes¶

The subcycles keyword of the engine section sets how often, in LAMMPS steps, LAMMPS writes a frame of the trajectory that PyRETIS reads, prints to the log file and, with order_mode = lammps, prints the order parameters to order_<run name>.txt.