# LAMMPS dump local file reader

User interface of the LAMMPS dump local reader, when attached to a Load trajectory modifier.

For loading per-bond data from files written by the dump command of the LAMMPS simulation code.

## Supported format variants

This reader specifically handles files written by the `local` dump style of LAMMPS – in contrast to regular atom and custom dump files. The latter store only atomistic data and are handled by OVITO’s regular LAMMPS dump file reader.

Since dump local files don’t contain per-particle data but rather information related to interactions (bonds, angles, dihedrals, etc.), the file reader is typically used in conjunction with the Load trajectory modifier to amend an already loaded structure, with particle coordinates coming from another file. A common use case of the LAMMPS dump local file reader is to load dynamically changing bond topologies from a reactive MD simulation run.

The file reader detects the kind of data items (bonds, angles, dihedrals, impropers, or neighbors) in a dump local file by analyzing the file’s header. For example

    ITEM: NUMBER OF BONDS

tells OVITO that the dump file contains a list of bonds and their properties. Instead of “BONDS” and “ENTRIES” (the default label), the reader also understands the labels:

> - “ANGLES” for angular data

> - “DIHEDRALS” for dihedral data

> - “IMPROPERS” for improper data

> - “NEIGHBORS” for neighbor lists

You must set the correct label using the dump_modify label command in your LAMMPS simulation script. For example, to dump the current list of bonds in regular time intervals, you would use the following command sequence:

    compute      bond all property/local batom1 batom2 btype
    dump         bond_dump all local 100 bonds.dump c_bond[1] c_bond[2] c_bond[3]
    dump_modify  bond_dump label BONDS

Furthermore, to make it easier for OVITO to automatically recognize the meaning of the file’s columns, you should give them names using the LAMMPS dump_modify colname command:

    dump_modify  bond_dump colname 1 batom1 colname 2 batom2 colname 3 btype

The reader can parse gzipped files (“.gz” suffix) and zstd compressed files (“.zst” suffix) directly. Binary files (“.bin” suffix) are not supported.

## Automatic column mapping

OVITO uses the names of the columns in the dump local file to automatically map them to the right bond/angle/dihedral/improper properties in OVITO. It therefore is important to give the columns in your dump file meaningful names using the LAMMPS dump_modify colname command already at simulation time.

Bonds

  For BONDS dump files, the following column names are recognized by OVITO:

  > - batom1 and batom2 for the two atom IDs of the bond

  > - btype for the bond type (optional)

  > - dist for the bond length computed by the compute bond/local command (optional)

  Use the following LAMMPS commands to generate such a dump file:

      compute     bond all property/local batom1 batom2 btype
      compute     dist all bond/local dist
      dump        bond_dump all local 100 bonds.dump c_bond[1] c_bond[2] c_bond[3] c_dist
      dump_modify bond_dump &
                    label BONDS &
                    colname 1 batom1 &
                    colname 2 batom2 &
                    colname 3 btype &
                    colname 4 dist

Angles

  For ANGLES dump files, the following column names are recognized by OVITO:

  > - aatom1, aatom2, and aatom3 for the three atom IDs defining the angular interaction

  > - atype for the angle type (optional)

  > - theta for the angle value computed by the compute angle/local command (optional)

  Use the following LAMMPS commands to generate such a dump file:

      compute     angle all property/local aatom1 aatom2 aatom3 atype
      compute     theta all angle/local theta
      dump        angle_dump all local 100 angles.dump c_angle[1] c_angle[2] c_angle[3] c_angle[4] c_theta
      dump_modify angle_dump &
                    label ANGLES &
                    colname 1 aatom1 &
                    colname 2 aatom2 &
                    colname 3 aatom3 &
                    colname 4 atype &
                    colname 5 theta

Dihedrals

  For DIHEDRALS dump files, the following column names are recognized by OVITO:

  > - datom1, datom2, datom3, and datom4 for the four atom IDs defining the dihedral interaction

  > - dtype for the dihedral type (optional)

  > - phi for the dihedral angle computed by the compute dihedral/local command (optional)

  Use the following LAMMPS commands to generate such a dump file:

      compute     dihedral all property/local datom1 datom2 datom3 datom4 dtype
      compute     phi all dihedral/local phi
      dump        dihedral_dump all local 100 dihedrals.dump c_dihedral[1] c_dihedral[2] c_dihedral[3] c_dihedral[4] c_dihedral[5] c_phi
      dump_modify dihedral_dump &
                    label DIHEDRALS &
                    colname 1 datom1 &
                    colname 2 datom2 &
                    colname 3 datom3 &
                    colname 4 datom4 &
                    colname 5 dtype &
                    colname 6 phi

Impropers

  For IMPROPERS dump files, the following column names are recognized by OVITO:

  > - iatom1, iatom2, iatom3, and iatom4 for the four atom IDs defining the improper interaction

  > - itype for the improper type (optional)

  > - chi for the improper angle computed by the compute improper/local command (optional)

  Use the following LAMMPS commands to generate such a dump file:

      compute     improper all property/local iatom1 iatom2 iatom3 iatom4 itype
      compute     chi all improper/local chi
      dump        improper_dump all local 100 impropers.dump c_improper[1] c_improper[2] c_improper[3] c_improper[4] c_improper[5] c_chi
      dump_modify improper_dump &
                    label IMPROPERS &
                    colname 1 iatom1 &
                    colname 2 iatom2 &
                    colname 3 iatom3 &
                    colname 4 iatom4 &
                    colname 5 itype &
                    colname 6 chi

## Manual column mapping

In case OVITO is unable to guess the correct mapping automatically, e.g., when the file’s columns have user-defined names, you may need to specify the correct mapping by hand in the following dialog displayed by the file reader:

File columns get automatically mapped to corresponding standard properties in OVITO if their names match one of the predefined standard bond properties (case insensitive). Spaces that are part of a standard property name must be left out, because LAMMPS dump files do not support column names containing spaces. For example, a dump file column named `BondType` will be mapped to the standard property Bond Type.

For standard properties with multiple components, a component name must be appended with a dot. For example, a dump file column named `ParticleIdentifiers.A` will automatically be mapped to the second component of the Particle Identifiers standard bond property in OVITO. Note that you can use the LAMMPS dump_modify colname command to give the columns in your dump file specific names.

For further information on how to set up the bond property mapping correctly, see the Load trajectory modifier.

## Python parameters

The file reader accepts the following keyword parameters in a call to the `load()` Python function:

load(location, columns=None)
  Parameters:

    columns (list[str|None]) – A list of OVITO bond/angle/dihedral/improper property names, one for each data column in the dump local file. List entries may be set to `None` to skip individual file columns during parsing.