lammpsio.DumpFile

class lammpsio.DumpFile(filename, schema=None, sort_ids=True, copy_from=None)

LAMMPS dump file.

The LAMMPS dump file is a highly flexible file format. The schema of the file is deduced from the ITEM: ATOMS header unless one is manually specified. If specificed, the schema must be a dictionary mapping pieces of data to column indexes (0-indexed). Valid keys for the schema match the names and shapes in the Snapshot. The keys requiring only 1 column index are:

  • "id"

  • "typeid"

  • "molecule"

  • "charge"

  • "mass"

The keys requiring 3 column indexes are:

  • "position"

  • "velocity"

  • "image"

LAMMPS dumps particles in an unknown order unless you have used the dump_modify sort option. If you want particles to be ordered by id in the Snapshot, use sort_ids=True (default). Note that slightly faster reading may be possible by setting this option to False.

A DumpFile is iterable, so you can use it to go through all the snapshots of a trajectory. It supports LAMMPS dump file with different compression formats such as gzip and Zstandard (pyzstd package needs to be installed separately for Zstandard support). Random access to snapshots is not currently implemented, but it may be added in future. If you want to randomly access snapshots, you should load the whole file into a list, but the memory requirements to do so may be large.

The dump file may not contain certain information about your particles, for example, topology, or you may choose not to write this information in the dump file because it does not change frame-to-frame. The copy_from option allows this information to be copied into a new snapshot from a reference one, e.g, that was read from a DataFile.

Parameters:

  • filename (str) – Path to dump file.

  • schema (dict) – Schema for the contents of the file. Defaults to None, which means to read it from the file.

  • sort_ids (bool) – If True, sort the particles by ID in each snapshot.

  • copy_from (Snapshot) – If specified, copy supported fields that are missing in the dump file but are set in a reference Snapshot.

Example

Create a dump file object:

traj = lammpsio.DumpFile(filename)

Iterate snapshots:

for snapshot in traj:
    print(snapshot.step)

You can also use multiprocessing to read snapshots in parallel:

import multiprocessing

def process_snapshot(snapshot):
    return snapshot.N

if __name__ == '__main__':
    num_workers = max(2, multiprocessing.cpu_count())
    with multiprocessing.Pool(num_workers) as p:
        num_particles = p.map(process_snapshot, traj)
    print(num_particles)

You can also get the number of snapshots in the DumpFile, but this does require reading the entire file: use with caution!

num_frames = len(traj)

Random access by creating a list:

snapshots = [snap for snap in traj]
print(snapshots[3].step)

Methods:

create(filename, schema, snapshots)

Create a LAMMPS dump file.

Attributes:

copy_from

Copy fields that are missing in a dump file.

filename

Path to the file.

schema

Data schema.
classmethod create(filename, schema, snapshots)

Create a LAMMPS dump file.

Parameters:

  • filename (str) – Path to dump file.

  • schema (dict) – Schema for the contents of the file.

  • snapshots (Snapshot or list) – One or more snapshots to write to the dump file.

Returns:

The object representing the new dump file.

Return type:

DumpFile

Example

A DumpFile can be created from a list of snapshots:

schema = {"id":0, "position":(1, 2, 3), "image": (4, 5, 6)}

lammpsio.DumpFile.create(filename, schema, snapshots)
property copy_from

Copy fields that are missing in a dump file.

The fields that can be copied are:

Type:

Snapshot

property filename

Path to the file.

Type:

str

property schema

Data schema.

Type:

dict