\(\renewcommand{\AA}{\text{Å}}\)

fix symmetry command

Syntax

fix ID group-ID symmetry file keyword value ...

ID, group-ID are documented in fix command
file = path to a symmetry-data file describing the space group and orbit map
zero or more keyword/value pairs may be appended

keyword = tol

tol value = epsilon
  epsilon = fractional-coordinate tolerance

Examples

fix sym all symmetry symgroup.pm.json
fix sym all symmetry symgroup.fm-3m.json tol 1.0e-8

Example input scripts available: examples/PACKAGES/symmetry

Description

Added in version TBD.

This fix constrains a molecular dynamics simulation to obey a chosen crystallographic space-group symmetry at every timestep. The algorithm follows (Cox), and the LAMMPS implementation is derived from the symd reference implementation.

Atoms are organized into orbits. Each orbit has one asymmetric representative and one image atom per non-identity operator of the declared space group. Per step the fix:

averages the forces and velocities of the atoms in each orbit (mapped back to the asymmetric unit through the operator inverses) and redistributes the symmetrized values to every image, and
re-folds the image positions from the asymmetric representative using the affine operators to cancel numerical drift.

The user is responsible for setting up the data file so that the full unit cell is already present and consistent with the symmetry at the start of the run; the fix verifies this at init within tol.

Special positions (Wyckoff sites)

Atoms sitting on a special position (a mirror plane, axis, or inversion center) are invariant under one or more non-identity operators of the space group. To declare such an atom, set its orbit’s tags slot at every stabilizer-op index equal to the asymmetric tag and list those op indices in a per-orbit site_symmetry array (see the file-format section). Per step the fix then applies a Lagrange-multiplier projection that drives the asym atom’s fractional position and velocity back onto the constraint subspace defined by its stabilizer. The pseudo-inverse used for the projection is pre-computed at init from a Jacobi eigen- decomposition of \(B = \sum_k (R_k - I)^T (R_k - I)\) over the stabilizer ops.

Symmetry-data file format

The file is in JSON format with the top-level schema:

{
  "group_name": "Pm",
  "lattice":    "monoclinic",

  "ops": [
    { "R": [[1, 0, 0], [0,  1, 0], [0, 0, 1]],
      "t": [0, 0, 0] },
    { "R": [[1, 0, 0], [0, -1, 0], [0, 0, 1]],
      "t": ["0", "0", "0"] }
  ],

  "orbits": [
    { "tags": [1, 2] },
    { "tags": [3, 4] },
    { "tags": [5, 5], "site_symmetry": [2] }
  ]
}

lattice must be one of triclinic, monoclinic, orthorhombic, tetragonal, hexagonal, trigonal, cubic.
Operators act on fractional coordinates: \(s' = R \cdot s + t\). R is an integer-valued lattice operator with \(|\det R| = 1\). t components accept either JSON numbers (0.5) or rational strings ("1/2").
The first entry in ops must be the identity. The full operator list must be closed under composition modulo lattice translations; the fix verifies this at init.
Each orbit’s tags array is parallel to ops: tags[0] is the asymmetric representative and tags[k] for \(k \ge 1\) is the atom tag related to it by ops[k]. For atoms on Wyckoff special positions, set tags[k] equal to tags[0] for every op k in the stabilizer and list those op indices (1-based, excluding 1) in an optional site_symmetry array on the same orbit. The fix verifies at init that each declared Wyckoff atom actually sits on its constraint manifold to within tol.
Any JSON key not listed above (for example fields starting with _comment) is silently ignored, so the file can carry documentation inline.

LAMMPS provides a JSON schema file for symmetry files in the tools/json folder. Using the schema file the files can be validated to be conforming to the syntax requirement and conventions without running LAMMPS. Please note that the format requirement for JSON files in general are very strict and the JSON reader in LAMMPS does not accept JSON files with extensions like comments. Validating a particular JSON format symmetry file against this schema ensures that both, the JSON syntax requirement and the LAMMPS conventions. LAMMPS should be able to read and parse any JSON file that passes the schema check. This is a formal check only and thus it cannot check whether the file contents are consistent or physically meaningful.

Adapting JSON files from the symd reference engine

The JSON format used here is not the format used by the symd reference engine. symd’s space-group tables (python/symd/data/{2,3}dgroups.json) describe each group in abstract crystallographic terms. To use a symd entry in a fix symmetry file you have to convert it in three steps:

Lattice family – lowercase the symd lattice string. symd uses "Triclinic"; this fix wants "triclinic".
Operators – expand each genpos string into an explicit \((R, t)\) block. The expression "x,y,z" means the identity \(R = I, t = 0\). The expression "-x+1/2, y, -z" means
```
{ "R": [[-1, 0, 0], [0, 1, 0], [0, 0, -1]],
  "t": ["1/2", 0, 0] }
```
In general each comma-separated component is an affine combination of x, y, z (coefficients +/- 1 or 0, giving one row of \(R\)) plus an optional rational constant (one component of \(t\)). Rational strings ("1/2") are preferred over decimal approximations to preserve exactness through the parser. The first genpos entry is required to be the identity by both formats.
Orbits and Wyckoff sites – symd auto-generates image atoms from an asymmetric unit; this fix does not. You have to place the full unit cell yourself (in the LAMMPS data file or via create_atoms) and then list every orbit explicitly:
- For each general-position asymmetric atom with tag T, build a tags array of length equal to the number of operators, with tags[k] set to the tag of the atom you placed at \(R_k \cdot s_T + t_k\). The fix verifies this layout at init.
- For each atom you place on a symd specpos site, also declare the site_symmetry array on its orbit. The stabilizer ops are those \(R_k\) for which \(R_k \cdot s + t_k \equiv s\) (modulo lattice translations) at the special-position coordinates. For Wyckoff site “h” in the example above (1/2,1/2,1/2 under P-1), op 2 (inversion) fixes the site, so the orbit reads { "tags": [T, T], "site_symmetry": [2] }.

A few Python conversion scripts for generating symmetry files are available alongside the example in the examples/PACKAGES/symmetry/ folder.

Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands.

This fix can be used with run_style respa. Force symmetrization is applied at every RESPA level so each per-level force contribution is individually symmetric; position re-folding and Wyckoff projection still run once per outer step in end_of_step.

This fix is not invoked during energy minimization.

Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.

The full unit cell (asymmetric atom plus all images) must already be present in the system at the start of the run; the fix does not create atoms.

The simulation box must be compatible with the declared lattice family. When using fix npt or fix box/relax the user must select a coupling (e.g. iso, aniso, tri) that preserves the Bravais lattice type; the fix does not project box deformation onto the symmetric subspace.

Default

tol = 1.0e-6.

(Cox) Cox and White, J. Chem. Theor. Comput., 18, 4077 (2022).