I/O¶

File readers and writers for molecular data, force fields, and trajectories.

Quick reference¶

Data files¶

Function	Format	Direction
`read_pdb` / `write_pdb`	PDB	read/write
`read_lammps_data` / `write_lammps_data`	LAMMPS data	read/write
`read_gro` / `write_gro`	GROMACS GRO	read/write
`read_mol2`	MOL2	read
`read_xyz`	XYZ	read
`XsfReader` / `XsfWriter`	XSF (crystallographic)	read/write
`read_h5` / `write_h5`	HDF5	read/write
`read_amber_inpcrd`	AMBER inpcrd	read

Force fields¶

Function	Format	Direction
`read_xml_forcefield`	OpenMM/OPLS XML	read
`XMLForceFieldWriter`	OpenMM/OPLS XML	write
`LAMMPSForceFieldWriter`	LAMMPS coefficients	write
`GromacsForceFieldWriter`	GROMACS .itp	write
`read_amber`	AMBER prmtop + inpcrd	read

Trajectories¶

Function	Format	Direction
`read_lammps_trajectory`	LAMMPS dump	read (lazy)
`read_xyz_trajectory`	XYZ trajectory	read (lazy)
`read_h5_trajectory`	HDF5 trajectory	read (lazy)

Logs¶

Function	Format	Direction
`read_LAMMPS_log`	LAMMPS log	read

Canonical examples¶

import molpy as mp

# Read/write structure
frame = mp.io.read_pdb("molecule.pdb")
mp.io.write_lammps_data("system.data", frame, atom_style="full")

# Read force field
ff = mp.io.read_xml_forcefield("oplsaa.xml")

# Write LAMMPS force field
from molpy.io.forcefield import LAMMPSForceFieldWriter
LAMMPSForceFieldWriter("system.ff").write(ff, atom_types={"CT", "HC"})

# Read trajectory (lazy)
traj = mp.io.read_lammps_trajectory("dump.lammpstrj")
for frame in traj:
    process(frame)

# Read LAMMPS run output
log = mp.io.read_LAMMPS_log("log.lammps")
thermo = log.runs[0].thermo
print(thermo.columns)

# Write full LAMMPS system (data + ff)
mp.io.write_lammps_system("output_dir", frame, ff)

Full API¶

Factory Functions¶

readers ¶

Data file reader factory functions.

This module provides convenient factory functions for creating various data file readers. All functions return Frame objects by populating an optional frame parameter.

PathLike `module-attribute` ¶

PathLike = str | Path

LAMMPSLog `dataclass` ¶

LAMMPSLog(file, style='default')

Parsed LAMMPS log.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to a LAMMPS log file.	required
`style`	`str`	Thermo style. Only `"default"` is currently parsed.	`'default'`

Notes

The class keeps the historical LAMMPSLog(path).read() workflow and log["stages"] compatibility while exposing the new dataclass-shaped result through attributes such as runs.

file `property` ¶

file

Compatibility alias for the historical file attribute.

getitem ¶

__getitem__(key)

Get a compatibility info field by key.

setitem ¶

__setitem__(key, value)

Set a compatibility info field by key.

legacy_thermo_stages ¶

legacy_thermo_stages()

Return thermo arrays using the historical stages shape.

read ¶

read()

Read and parse the log file. Returns self for chaining.

read_thermo ¶

read_thermo(text, style)

Parse thermo tables into the compatibility mapping.

read_version ¶

read_version(text)

Extract the LAMMPS version line into the compatibility mapping.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

stages and n_stages are retained for compatibility. New code should prefer runs.

_ensure_frame ¶

_ensure_frame(frame)

Ensure a Frame object exists.

read_LAMMPS_log ¶

read_LAMMPS_log(file)

Read a LAMMPS log file and return a nested dataclass result.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to LAMMPS log file	required

Returns:

Type	Description
`LAMMPSLog`	Parsed `LAMMPSLog` object.

read_amber_ac ¶

read_amber_ac(file, frame=None)

Read AC file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to AC file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_amber_frcmod ¶

read_amber_frcmod(file)

Read an AMBER FRCMOD file.

FRCMOD files contain additional force field parameters generated by parmchk2.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to FRCMOD file	required

Returns:

Type	Description
`dict[str, Any]`	Dictionary with sections: 'remark', 'mass', 'bond', 'angle', 'dihe',
`dict[str, Any]`	'improper', 'nonbon', and 'raw_text'.

read_amber_inpcrd ¶

read_amber_inpcrd(inpcrd, frame=None)

Read AMBER inpcrd file and return a Frame object.

Parameters:

Name	Type	Description	Default
`inpcrd`	`PathLike`	Path to AMBER inpcrd file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_amber_prmtop ¶

read_amber_prmtop(prmtop, inpcrd=None, frame=None)

Read AMBER prmtop and optional inpcrd files.

Parameters:

Name	Type	Description	Default
`prmtop`	`PathLike`	Path to AMBER prmtop file	required
`inpcrd`	`PathLike \| None`	Optional path to AMBER inpcrd file	`None`
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Tuple of (Frame, ForceField)

read_dcd_trajectory ¶

read_dcd_trajectory(file)

Read a DCD trajectory and return a lazy trajectory reader.

Backed by the molrs Rust lazy reader (O(1) random access by frame index).

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to a `.dcd` file.	required

Returns:

Type	Description
`Any`	molrs `TrajectoryReader` object.

read_gro ¶

read_gro(file, frame=None)

Read GROMACS gro file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to gro file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_h5 ¶

read_h5(file, frame=None)

Read HDF5 file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to HDF5 file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

Examples:

>>> frame = read_h5("structure.h5")
>>> frame["atoms"]["x"]
array([0., 1., 2.])

read_h5_trajectory ¶

read_h5_trajectory(file)

Read HDF5 trajectory file and return a trajectory reader.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to HDF5 trajectory file	required

Returns:

Type	Description
`Any`	HDF5TrajectoryReader object

Examples:

>>> reader = read_h5_trajectory("trajectory.h5")
>>> frame = reader.read_frame(0)
>>> for frame in reader:
...     process(frame)

read_lammps_data ¶

read_lammps_data(file, atom_style, frame=None)

Read LAMMPS data file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to LAMMPS data file	required
`atom_style`	`str`	LAMMPS atom style (e.g., 'full', 'atomic')	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_lammps_forcefield ¶

read_lammps_forcefield(scripts)

Read a LAMMPS force-field include (*.ff) into a ForceField.

Delegates to the native molrs reader (molrs.read_lammps_forcefield), which parses the include directly into a molrs.ForceField in molrs units (Å, kcal/mol, radians, e): LAMMPS harmonic K → molrs k = 2K, angle and dihedral-phase values stay in degrees, and dihedral_style fourier maps to the molrs periodic kernel. AMBER 1-4 scaling is recorded on the force field's special bonds. Per-atom charge and mass live in the LAMMPS data file, not this include, so they are not read here.

Parameters:

Name	Type	Description	Default
`scripts`	`PathLike \| list[PathLike]`	Path (or list of paths) to LAMMPS force-field include(s). A list is concatenated and parsed as a single document.	required

Returns:

Type	Description
`Any`	`molpy.ForceField` (which is `molrs.ForceField`).

read_lammps_molecule ¶

read_lammps_molecule(file, frame=None)

Read LAMMPS molecule file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to LAMMPS molecule file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_lammps_trajectory ¶

read_lammps_trajectory(traj, frame=None)

Read LAMMPS trajectory file and return a trajectory reader.

Backed by the molrs Rust lazy reader.

Parameters:

Name	Type	Description	Default
`traj`	`PathLike`	Path to LAMMPS trajectory file	required
`frame`	`Any`	Unused; retained for backward compatibility. molrs handles the canonical fields, so no reference Frame is needed.	`None`

Returns:

Type	Description
`Any`	molrs `TrajectoryReader` object

read_mol2 ¶

read_mol2(file, frame=None)

Read mol2 file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to mol2 file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_pdb ¶

read_pdb(file, frame=None)

Read PDB file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to PDB file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_pdb_trajectory ¶

read_pdb_trajectory(file)

Read every model of a (multi-frame) PDB file as a list of Frames.

Each MODEL/END-delimited block becomes one Frame. A single-model PDB yields a one-element list. Backed by the molrs Rust reader.

read_top ¶

read_top(file, forcefield=None)

Read GROMACS topology file and return a ForceField object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to GROMACS .top file	required
`forcefield`	`Any`	Optional existing ForceField to populate	`None`

Returns:

Type	Description
`Any`	Populated ForceField object

read_trr_trajectory ¶

read_trr_trajectory(file)

Read a GROMACS TRR trajectory and return a lazy trajectory reader.

Backed by the molrs Rust lazy reader (single/double precision, coordinates plus velocities/forces when present; O(1) random access).

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to a `.trr` file.	required

Returns:

Type	Description
`Any`	molrs `TrajectoryReader` object.

read_xml_forcefield ¶

read_xml_forcefield(file)

Read XML force field file and return a ForceField object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to XML force field file	required

Returns:

Type	Description
`Any`	ForceField object

read_xsf ¶

read_xsf(file, frame=None)

Read XSF file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to XSF file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_xtc_trajectory ¶

read_xtc_trajectory(file)

Read a GROMACS XTC (compressed) trajectory and return a lazy reader.

Backed by the molrs Rust lazy reader (lossy compression; accepts classic 1995 and 2023 magic; O(1) random access after a one-time index scan).

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to a `.xtc` file.	required

Returns:

Type	Description
`Any`	molrs `TrajectoryReader` object.

read_xyz ¶

read_xyz(file, frame=None)

Read XYZ file and return a Frame object.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to XYZ file	required
`frame`	`Any`	Optional existing Frame to populate	`None`

Returns:

Type	Description
`Any`	Populated Frame object

read_xyz_trajectory ¶

read_xyz_trajectory(file)

Read XYZ trajectory file and return a trajectory reader.

Backed by the molrs Rust lazy reader.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Path to XYZ trajectory file	required

Returns:

Type	Description
`Any`	molrs `TrajectoryReader` object

writers ¶

Data file writer factory functions.

This module provides convenient factory functions for creating various data file writers. All functions write Frame or ForceField objects to files.

PathLike `module-attribute` ¶

PathLike = str | Path

write_amber_frcmod ¶

write_amber_frcmod(
    file,
    *,
    remark="",
    mass="",
    bond="",
    angle="",
    dihe="",
    improper="",
    nonbon="",
)

Write an AMBER FRCMOD file.

FRCMOD files contain additional force field parameters. This function creates a properly formatted file with the provided sections.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`remark`	`str`	Optional comment/remark line	`''`
`mass`	`str`	MASS section content	`''`
`bond`	`str`	BOND section content	`''`
`angle`	`str`	ANGLE section content	`''`
`dihe`	`str`	DIHEDRAL section content	`''`
`improper`	`str`	IMPROPER section content	`''`
`nonbon`	`str`	NONBON section content	`''`

write_gro ¶

write_gro(file, frame)

Write a Frame object to a GROMACS GRO file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required

write_h5 ¶

write_h5(
    file, frame, compression="gzip", compression_opts=4
)

Write a Frame object to an HDF5 file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required
`compression`	`str \| None`	Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.	`'gzip'`
`compression_opts`	`int`	Compression level (for gzip: 0-9). Defaults to 4.	`4`

Examples:

>>> frame = Frame(blocks={"atoms": {"x": [0, 1, 2], "y": [0, 0, 0]}})
>>> write_h5("structure.h5", frame)

write_h5_trajectory ¶

write_h5_trajectory(
    file, frames, compression="gzip", compression_opts=4
)

Write frames to an HDF5 trajectory file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frames`	`list`	List of Frame objects to write	required
`compression`	`str \| None`	Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.	`'gzip'`
`compression_opts`	`int`	Compression level (for gzip: 0-9). Defaults to 4.	`4`

Examples:

>>> frames = [frame0, frame1, frame2]
>>> write_h5_trajectory("trajectory.h5", frames)

write_lammps_bond_react_system ¶

write_lammps_bond_react_system(
    workdir, frame, forcefield, templates
)

Write a complete LAMMPS fix bond/react system.

Produces all files needed for a reactive MD simulation:

{stem}.data — system configuration
{stem}.ff — force field coefficients
{name}_pre.mol / {name}_post.mol — reaction templates
{name}.map — atom equivalence maps

Type numbering is unified across the system and all templates so that fix bond/react can match atom types correctly.

Parameters:

Name	Type	Description	Default
`workdir`	`PathLike`	Output directory (created if missing).	required
`frame`	`Any`	Packed system Frame.	required
`forcefield`	`Any`	ForceField object.	required
`templates`	`dict[str, Any] \| Sequence[Any]`	Either a `{name: BondReactTemplate}` dict, or a sequence of templates (named `rxn1`, `rxn2`, …).	required

Example::

mp.io.write_lammps_bond_react_system(
    "output", packed_frame, ff,
    templates={"rxn1": template},
)

write_lammps_data ¶

write_lammps_data(file, frame, atom_style='full')

Write a Frame object to a LAMMPS data file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required
`atom_style`	`str`	LAMMPS atom style (default: 'full')	`'full'`

write_lammps_forcefield ¶

write_lammps_forcefield(
    file, forcefield, precision=6, skip_pair_style=False
)

Write a ForceField object to a LAMMPS force field file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`forcefield`	`Any`	ForceField object to write	required
`precision`	`int`	Number of decimal places for floating point values	`6`
`skip_pair_style`	`bool`	If True, omit the `pair_style` line so the calling LAMMPS input script can set it independently (e.g. to switch between `lj/cut/coul/cut` for minimisation and `lj/cut/coul/long` for MD).	`False`

write_lammps_molecule ¶

write_lammps_molecule(file, frame, format_type='native')

Write a Frame object to a LAMMPS molecule file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required
`format_type`	`str`	Format type (default: 'native')	`'native'`

write_lammps_system ¶

write_lammps_system(workdir, frame, forcefield)

Write a complete LAMMPS system (data + forcefield) to a directory.

Parameters:

Name	Type	Description	Default
`workdir`	`PathLike`	Output directory path	required
`frame`	`Any`	Frame object containing structure	required
`forcefield`	`Any`	ForceField object containing parameters	required

Returns:

Type	Description
`dict[str, Path]`	Dict with keys `"data"` and `"ff"` pointing to the written files.

write_lammps_trajectory ¶

write_lammps_trajectory(file, frames, atom_style='full')

Write frames to a LAMMPS trajectory file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frames`	`list`	List of Frame objects to write	required
`atom_style`	`str`	LAMMPS atom style (default: 'full')	`'full'`

write_pdb ¶

write_pdb(file, frame)

Write a Frame object to a PDB file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required

write_top ¶

write_top(file, frame)

Write a Frame object to a GROMACS topology file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required

write_trr ¶

write_trr(file, frames)

Write frames to a GROMACS TRR trajectory (single precision).

Thin delegation to the native molrs writer. Each frame needs x/y/ z (nm); optional vx/vy/vz and fx/fy/fz are written when present.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path.	required
`frames`	`list`	List of Frame objects to write.	required

write_xsf ¶

write_xsf(file, frame)

Write a Frame object to an XSF file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frame`	`Any`	Frame object to write	required

write_xtc ¶

write_xtc(file, frames)

Write frames to a GROMACS XTC (compressed) trajectory.

Thin delegation to the native molrs writer. Each frame needs x/y/ z (nm); quantization precision comes from frame.metadata['precision'] when present, else 1000 (0.001 nm).

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path.	required
`frames`	`list`	List of Frame objects to write.	required

write_xyz_trajectory ¶

write_xyz_trajectory(file, frames)

Write frames to an XYZ trajectory file.

Parameters:

Name	Type	Description	Default
`file`	`PathLike`	Output file path	required
`frames`	`list`	List of Frame objects to write	required

ForceField Modules¶

Base¶

base ¶

Abstract base classes for force field readers and writers.

ForceFieldReader ¶

ForceFieldReader(path)

Bases: ABC

Base class for force field file readers.

read `abstractmethod` ¶

read(forcefield=None)

Read force field data from file.

Parameters:

Name	Type	Description	Default
`forcefield`	`ForceField \| None`	Optional existing ForceField to populate.	`None`

Returns:

Type	Description
`ForceField`	Populated ForceField object.

ForceFieldWriter ¶

ForceFieldWriter(path)

Bases: ABC

Base class for force field file writers.

write `abstractmethod` ¶

write(forcefield)

Write force field data to file.

Parameters:

Name	Type	Description	Default
`forcefield`	`ForceField`	ForceField object to serialize.	required

LAMMPS¶

lammps ¶

LAMMPSForceFieldReader ¶

LAMMPSForceFieldReader(scripts, data)

read_angle_coeff ¶

read_angle_coeff(style, line)

Read angle_coeff line and create AngleType.

Format: angle_coeff [style_name] Example: angle_coeff CT-CT-OS 50.0 109.5

read_bondcoeff ¶

read_bondcoeff(style, line)

Read bond_coeff line and create BondType.

Format: bond_coeff [style_name] Example: bond_coeff CT-CT 268.0 1.529

read_dihedral_coeff ¶

read_dihedral_coeff(style, line)

Read dihedral_coeff line and create DihedralType.

Format: dihedral_coeff [style_name] Example: dihedral_coeff CT-CT-CT-CT 1.3 -0.05 0.2 0.0

read_improper_coeff ¶

read_improper_coeff(style, line)

Read improper_coeff line and create ImproperType.

Format: improper_coeff [style_name] Example: improper_coeff CA-CA-CA-HA 1.1 180.0

read_pair_coeff ¶

read_pair_coeff(style, line)

Read pair_coeff line and create PairType.

Format can be: - pair_coeff (self-interaction) - pair_coeff (cross-interaction) - pair_coeff [style_name] (hybrid)

Example: pair_coeff opls_135 0.066 3.5

LAMMPSForceFieldWriter ¶

LAMMPSForceFieldWriter(fpath, precision=6)

Writer for LAMMPS force field files.

Converts ForceField objects to LAMMPS input format with support for: - Multiple style types (bond, angle, dihedral, improper, pair) - Hybrid styles - Type filtering - Specialized Style and Type classes

Parameters:

Name Type Description Default

fpath str | Path | TextIO

Output file path or file-like object

required

precision int

Number of decimal places for floating point values

6

write ¶

write( forcefield, atom_types=None, bond_types=None, angle_types=None, dihedral_types=None, improper_types=None, skip_pair_style=False, )

Write forcefield to LAMMPS format.

Parameters:

Name Type Description Default

forcefield ForceField

ForceField object to write

required

atom_types set[str] | None

Set of atom type names to include (for pair coeffs). If None, include all.

None

bond_types set[str] | None

Set of bond type names to include. If None, include all.

None

angle_types set[str] | None

Set of angle type names to include. If None, include all.

None

dihedral_types set[str] | None

Set of dihedral type names to include. If None, include all.

None

improper_types set[str] | None

Set of improper type names to include. If None, include all.

None

skip_pair_style bool

If True, omit the pair_style header line so the calling input script can set pair_style independently.

False

LammpsForceFieldFormatter ¶

Bases: LammpsFieldFormatter, ForceFieldFormatter

LAMMPS force-field formatter.

Inherits LAMMPS field-name mapping (q ↔ charge, mol ↔ mol_id) from :class:LammpsFieldFormatter and adds parameter formatters for serializing Style/Type objects to LAMMPS coefficient lines.

TypeFilter ¶

TypeFilter(whitelist=None, blacklist=None, custom=None)

Filter for selecting which types to include in LAMMPS output.

Supports multiple filtering modes: - whitelist: Only include types whose names are in the set - blacklist: Exclude types whose names are in the set - custom: Use a custom function to determine inclusion

Parameters:

Name Type Description Default

whitelist set[str] | None

Set of type names to include. If None, all types pass.

None

blacklist set[str] | None

Set of type names to exclude. Applied after whitelist.

None

custom Callable | None

Custom filter function that takes (type_obj) -> bool. Applied after whitelist and blacklist.

None

from_whitelist classmethod ¶

from_whitelist(whitelist)

Create a filter from a whitelist (backward compatibility).

includes ¶

includes(type_obj)

Check if a type should be included.

Parameters:

Name Type Description Default

type_obj Type

Type object to check.

required

Returns:

Type Description

bool

True if type should be included, False otherwise

XML¶

xml ¶

XML force field parser for atomistic force fields.

AngleUnitWarning ¶

Bases: UserWarning

An angle value looks inconsistent with its declared angle_unit.

OPLSAAForceFieldReader ¶

OPLSAAForceFieldReader(filepath, *, angle_unit='radian')

Bases: XMLForceFieldReader

Specialized reader for OPLS-AA force field with LAMMPS unit conversions.

This reader extends XMLForceFieldReader to: 1. Use lj/cut/coul/long pair style instead of lj/cut/coul/cut 2. Convert epsilon: kJ/mol → kcal/mol (÷4.184) 3. Convert sigma: nm → Å (×10) 4. Convert bond K: kJ/mol/nm² → kcal/mol/Å² (÷(4.184×100), both use 0.5 factor in formula) 5. Convert angle K: kJ/mol/rad² → kcal/mol/deg² (direct to LAMMPS format) Formula: k_lammps = (0.5 * k_opls / 4.184) * (π/180)² Stored internally in LAMMPS format, so no conversion needed when writing 6. Convert dihedral K: kJ/mol → kcal/mol (÷4.184)

XMLForceFieldReader ¶

XMLForceFieldReader(filepath, *, angle_unit='radian')

XML force field parser for atomistic force fields.

Parses XML-formatted force field files (e.g., OPLS-AA) and populates an AtomisticForcefield object with atom types, bond parameters, angle parameters, dihedral parameters, and nonbonded interactions.

The parser handles: - AtomTypes section: atom type definitions - HarmonicBondForce: harmonic bond parameters - HarmonicAngleForce: harmonic angle parameters - RBTorsionForce: Ryckaert-Bellemans dihedral parameters - NonbondedForce: LJ and Coulomb parameters

Initialize the XML force field reader.

Parameters:

Name Type Description Default

filepath str | Path

Path to the XML force field file, or filename for built-in files (e.g., "oplsaa.xml" will load from molpy/data/forcefield/)

required

angle_unit str

Unit of angle equilibria ("angle"/phase) in the input file — "radian" (default, the OpenMM/OPLS XML convention) or "degree". Values are converted to the internal degrees representation on read, so the rest of the pipeline is unit-consistent.

'radian'

read ¶

read(forcefield=None, layer=0)

Read and parse the XML force field file.

Parameters:

Name Type Description Default

forcefield AtomisticForcefield | None

Optional existing force field to populate. If None, creates new one.

None

layer int

Overlay level for this read. 0 (default) is the base force field; a positive value marks every atom type parsed here as an overlay that overrides the base during SMARTS typing (higher layer wins). Used to stack oplsaa.xml (layer 0) → clp.xml (layer 1) → clpol.xml (layer 2).

0

Returns:

Type Description

AtomisticForcefield

Populated AtomisticForcefield object

XMLForceFieldWriter ¶

XMLForceFieldWriter( filepath, precision=6, *, angle_unit="radian" )

Write a ForceField to OpenMM-style XML.

The output is roundtrip-compatible with :class:XMLForceFieldReader.

Parameters:

Name Type Description Default

filepath str | Path

Destination path.

required

precision int

Number of decimal digits for floating-point values.

6

write ¶

write(forcefield)

Serialize forcefield to XML.

read_oplsaa_forcefield ¶

read_oplsaa_forcefield(filepath, forcefield=None, layer=0)

Read OPLS-AA force field with proper unit conversions for LAMMPS.

This function uses OPLSAAForceFieldReader which: - Uses lj/cut/coul/long pair style - Converts epsilon: epsilon_lammps = epsilon_opls / 4.184 (kJ/mol to kcal/mol) - Converts sigma: sigma_lammps = sigma_opls * 10.0 (nm to Angstrom)

Parameters:

Name Type Description Default

filepath str | Path

Path to the OPLS-AA XML file, or "oplsaa.xml" for built-in

required

forcefield AtomisticForcefield | None

Optional existing force field to populate

None

Returns:

Type Description

AtomisticForcefield

Populated AtomisticForcefield object with LAMMPS-compatible units

Example

ff = read_oplsaa_forcefield("oplsaa.xml")

read_xml_forcefield ¶

read_xml_forcefield(filepath, forcefield=None, layer=0)

Convenience function to read an XML force field file.

Parameters:

Name Type Description Default

filepath str | Path

Path to the XML force field file, or filename for built-in files (e.g., "oplsaa.xml" will load from molpy/data/forcefield/)

required

forcefield AtomisticForcefield | None

Optional existing force field to populate

None

layer int

Overlay level (0 = base, >0 = overlay that overrides the base during SMARTS typing). Pass layer=1 when stacking clp.xml onto an already-loaded oplsaa.xml so CL&P types win conflicts.

0

Returns:

Type Description

AtomisticForcefield

Populated AtomisticForcefield object

Example

Load built-in OPLS-AA force field¶

ff = read_xml_forcefield("oplsaa.xml")

Overlay CL&P on top of OPLS-AA (CL&P overrides where it matches)¶

ff = read_xml_forcefield("clp.xml", ff, layer=1)

write_xml_forcefield ¶

write_xml_forcefield(filepath, forcefield)

Convenience function to write a force field to XML.

Parameters:

Name Type Description Default

filepath str | Path

Output path.

required

forcefield AtomisticForcefield

Force field to serialize.

required

GROMACS Topology¶

top ¶

GromacsForceFieldWriter ¶

GromacsForceFieldWriter(filepath, precision=6)

Write a ForceField to GROMACS .top / .itp format.

The output is roundtrip-compatible with :class:GromacsTopReader.

Parameters:

Name Type Description Default

filepath str | Path

Destination path.

required

precision int

Number of decimal digits for floating-point values.

6

write ¶

write(forcefield)

Serialize forcefield to GROMACS topology format.

GromacsTopReader ¶

GromacsTopReader(file, include=False)

Utility to read a Gromacs .top/.itp topology file into a dictionary.

The returned mapping contains a key for every section header encountered (e.g. atomtypes, moleculetype), mapping to the raw content lines (with inline comments stripped) that appear under that section in the order they occur.

read ¶

read(forcefield, *, strip_comments=True, recursive=True)

Parse the topology file.

Parameters¶

forcefield: Optional object providing a base_dir or path attribute used to resolve relative #include statements that point inside the force-field directory (e.g. ff/amber14sb.ff/ions.itp). strip_comments: Whether to remove text following a ; (Gromacs comment delimiter). Leading/trailing whitespace is always removed. recursive: If True (default) #included files are parsed recursively. The content of an included file is merged into the dictionary being built; if the same section appears multiple times its content is extended in occurrence order.

Returns¶

dict[str, list[str]] Mapping from lower‑case section name to list of raw content lines.

AMBER¶

amber ¶

AmberPrmtopReader ¶

AmberPrmtopReader(file)

get_bond_with_H ¶

get_bond_with_H()

Return list of bonded atom pairs, K, and Rmin for each bond with a hydrogen

get_bond_without_H ¶

get_bond_without_H()

Return list of bonded atom pairs, K, and Rmin for each bond with no hydrogen

parse_angle_params ¶

parse_angle_params()

Return list of atom triplets, K, and ThetaMin for each bond angle

parse_dihedral_params ¶

parse_dihedral_params()

Return list of atom quads, K, phase and periodicity for each dihedral angle

parse_nonbond_params ¶

parse_nonbond_params(atoms)

Return list of all rVdw, epsilon pairs for each atom. If off-diagonal elements of the Lennard-Jones A and B coefficient matrices are found, NbfixPresent exception is raised

Data Modules¶

LAMMPS¶

lammps ¶

Modern LAMMPS data file I/O using Block.from_csv.

This module provides a clean, imperative approach to reading and writing LAMMPS data files using the Block.from_csv functionality.

LammpsDataReader ¶

LammpsDataReader(path, atom_style='full')

Bases: DataReader

Modern LAMMPS data file reader using Block.from_csv.

read ¶

read(frame=None)

Read LAMMPS data file into a Frame.

LammpsDataWriter ¶

LammpsDataWriter(path, atom_style='full')

Bases: DataWriter

Modern LAMMPS data file writer using Block.to_csv approach.

Important Requirements: - Atoms in the frame must have an 'id' field. This field is required to map atom indices to atom IDs for LAMMPS output. - Connectivity data (bonds, angles, dihedrals) in the frame uses atom indices (0-based from to_frame()). The writer automatically converts these indices to atom IDs using the index->ID mapping from the atoms 'id' field.

Frame Structure: - Atoms: Must include 'id' field. Other required fields depend on atom_style. - Bonds/Angles/Dihedrals: Use atom indices in 'atomi', 'atomj', 'atomk', 'atoml' (from to_frame()). These are 0-based indices that will be converted to 1-based atom IDs.

write ¶

write(frame)

Write Frame to LAMMPS data file.

Parameters:

Name Type Description Default

frame Frame

Frame containing atoms and optionally bonds/angles/dihedrals. Atoms must have 'id' field.

required

Raises:

Type Description

ValueError

If atoms are missing 'id' field.

LammpsFieldFormatter ¶

Bases: FieldFormatter

LAMMPS-specific field name translation.

Maps LAMMPS atom_style column names to canonical field names::

"q" → "charge" "mol" → "mol_id"

lammps_molecule ¶

LAMMPS molecule file I/O.

This module provides readers and writers for LAMMPS molecule template files, supporting both native format and JSON format as described in the LAMMPS documentation.

LammpsMoleculeReader ¶

LammpsMoleculeReader(path)

Bases: DataReader

LAMMPS molecule file reader supporting both native and JSON formats.

read ¶

read(frame=None)

Read LAMMPS molecule file into a Frame.

LammpsMoleculeWriter ¶

LammpsMoleculeWriter(path, format_type='native')

Bases: DataWriter

LAMMPS molecule file writer supporting both native and JSON formats.

write ¶

write(frame)

Write Frame to LAMMPS molecule file.

lammps_bond_react ¶

LAMMPS fix bond/react template serialization.

Writers and helpers for the files consumed by the LAMMPS fix bond/react command: the .map atom-mapping file and the unified string-type → numeric-ID mappings shared between the system data file and the pre/post molecule templates.

The single user-facing entry point for a complete reactive system is :func:molpy.io.write_lammps_bond_react_system; this module holds the serialization building blocks it delegates to.

File format references

LAMMPS fix bond/react: https://docs.lammps.org/fix_bond_react.html

REACTER methodology: https://www.reacter.org (Gissinger, Jensen & Wise, Polymer 128, 211-217 (2017); Macromolecules 53, 9953-9961 (2020))

apply_type_maps ¶

apply_type_maps(frame, type_maps, template_name='')

Convert string type columns to unified numeric IDs in place.

Rows whose type is not present in the mapping (e.g. boundary topology with None types) are dropped with a warning, matching the historical behavior of :func:molpy.io.write_lammps_bond_react_system. The numeric IDs must match the system data file for fix bond/react template matching (see https://docs.lammps.org/fix_bond_react.html).

Parameters:

Name Type Description Default

frame Frame

Template frame to rewrite (mutated in place).

required

type_maps dict[str, dict[str, int]]

Section → {type_name: id} mapping from :func:collect_type_maps.

required

template_name str

Template name used in the warning message.

''

collect_type_maps ¶

collect_type_maps(frames)

Build unified string-type → 1-based ID mappings across frames.

Scans the type column of every topology section in every frame, keeps named types (skipping empty strings, "None" placeholders, and purely numeric labels that are already IDs), sorts them, and assigns 1-based integer IDs. Using one mapping for the system frame and all template frames is what lets fix bond/react match template atoms against the system data file (see https://docs.lammps.org/fix_bond_react.html).

Parameters:

Name Type Description Default

frames Sequence[Frame]

Frames to scan (system frame plus pre/post template frames).

required

Returns:

Type Description

dict[str, list[str]]

A (labels, type_maps) pair. labels maps data-writer

dict[str, dict[str, int]]

label keys ("atom_types", "bond_types", …) to sorted

tuple[dict[str, list[str]], dict[str, dict[str, int]]]

type-name lists; type_maps maps section names ("atoms",

tuple[dict[str, list[str]], dict[str, dict[str, int]]]

"bonds", …) to {type_name: 1-based id} dicts.

write_bond_react_map ¶

write_bond_react_map(template, base_path)

Write the .map file for LAMMPS fix bond/react.

The .map file is purely topological and independent of type numbering. It contains a header with section counts followed by the InitiatorIDs, EdgeIDs, DeleteIDs, and Equivalences sections; atom IDs are 1-based template-local indices (see https://docs.lammps.org/fix_bond_react.html).

Parameters:

Name Type Description Default

template BondReactTemplate

Bond/react template carrying pre/post subgraphs and the initiator/edge/delete atom lists.

required

base_path str | Path

Stem path; produces {base_path}.map.

required

Raises:

Type Description

ValueError

If the pre and post subgraphs do not contain the same set of react_id atoms.

PDB¶

pdb ¶

PDBReader ¶

PDBReader(file, **kwargs)

Bases: DataReader

Minimal-yet-robust PDB reader.

ATOM / HETATM parsed per PDB v3.3 fixed columns

CRYST1 -> frame.box

CONECT -> bond list

read ¶

read(frame=None)

Read a single PDB model via the molrs Rust backend.

Multi-MODEL / multi-frame PDBs are read one model at a time; use :func:molpy.io.read_pdb_trajectory for all models.

PDBWriter ¶

PDBWriter(path)

Bases: DataWriter

Robust PDB file writer that creates properly formatted PDB files.

Features: - Writes ATOM/HETATM records with proper formatting - Handles missing fields with sensible defaults - Writes CRYST1 records from box information - Writes CONECT records for bonds - Ensures PDB format compliance

write ¶

write(frame)

Write frame to PDB file.

Required fields in frame["atoms"]: - x, y, z: coordinates (float, required) - id: atom ID (int, optional, defaults to index+1)

Optional fields in frame["atoms"]: - name: atom name (str) - resName: residue name (str) - element: element symbol (str) - resSeq: residue sequence number (int) - chainID: chain identifier (str) - occupancy: occupancy (float) - tempFactor: temperature factor (float)

Optional metadata: - elements: space-separated string of element symbols (one per atom) - name: frame name (str) - box: Box object for CRYST1 record

Raises:

Type Description

ValueError

If required fields (x, y, z) are missing or contain None

GRO¶

gro ¶

GROMACS .gro file I/O — molrs (Rust) backend.

Reader/writer delegate to :mod:molrs.io (parsing + field canonicalization in Rust). :class:GroFieldFormatter is retained for the formatter hierarchy.

GroFieldFormatter ¶

Bases: FieldFormatter

GROMACS .gro field name translation.

GroReader ¶

GroReader(path, **kwargs)

Bases: DataReader

Read GRO files via the molrs Rust backend.

GroWriter ¶

GroWriter(path, **kwargs)

Bases: DataWriter

Write GRO files via the molrs Rust backend.

Mol2¶

mol2 ¶

Mol2Reader ¶

Mol2Reader(file)

Bases: DataReader

Robust MOL2 file reader following TRIPOS MOL2 format specification.

Features: - Parses MOLECULE, ATOM, BOND, and SUBSTRUCTURE sections - Handles various atom types and bond types - Robust error handling for malformed files - Supports partial files with missing sections - Assigns atomic numbers from atom names/types

read ¶

read(frame)

Read MOL2 file and populate frame.

sanitizer staticmethod ¶

sanitizer(line)

Clean up line by stripping whitespace.

H5¶

h5 ¶

HDF5 file format support for Frame objects.

This module provides reading and writing of Frame objects to/from HDF5 format using h5py. The HDF5 format is efficient for storing large molecular datasets and supports compression and chunking.

HDF5 Structure:¶

/ # Root group ├── blocks/ # Group containing all data blocks │ ├── atoms/ # Block group (e.g., "atoms") │ │ ├── x # Dataset (variable) │ │ ├── y # Dataset │ │ └── z # Dataset │ └── bonds/ # Another block group │ ├── i # Dataset │ └── j # Dataset └── metadata/ # Group containing metadata ├── timestep # Attribute or dataset └── ... # Other metadata

HDF5Reader ¶

HDF5Reader(path, **open_kwargs)

Read Frame objects from HDF5 files.

The HDF5 file structure should follow the format: - /blocks/{block_name}/{variable_name} for data arrays - /metadata/ for frame metadata

Examples:

>>> reader = HDF5Reader("frame.h5") >>> frame = reader.read() >>> frame["atoms"]["x"] array([0., 1., 2.])

Initialize HDF5 reader.

Parameters:

Name Type Description Default

path PathLike

Path to HDF5 file

required

**open_kwargs Any

Additional arguments passed to h5py.File

{}

read ¶

read(frame=None)

Read Frame from HDF5 file.

Parameters:

Name Type Description Default

frame Frame | None

Optional existing Frame to populate. If None, creates a new one.

None

Returns:

Name Type Description

Frame Frame

Populated Frame object with blocks and metadata from HDF5 file.

HDF5Writer ¶

HDF5Writer( path, compression="gzip", compression_opts=4, **open_kwargs, )

Write Frame objects to HDF5 files.

The HDF5 file structure follows: - /blocks/{block_name}/{variable_name} for data arrays - /metadata/ for frame metadata

Examples:

>>> frame = Frame(blocks={"atoms": {"x": [0, 1, 2], "y": [0, 0, 0]}}) >>> writer = HDF5Writer("frame.h5") >>> writer.write(frame)

Initialize HDF5 writer.

Parameters:

Name Type Description Default

path PathLike

Path to output HDF5 file

required

compression str | None

Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.

'gzip'

compression_opts int

Compression level (for gzip: 0-9). Defaults to 4.

4

**open_kwargs Any

Additional arguments passed to h5py.File

{}

write ¶

write(frame)

Write Frame to HDF5 file.

Parameters:

Name Type Description Default

frame Frame

Frame object to write.

required

Raises:

Type Description

ValueError

If frame is empty (no blocks).

frame_to_h5_group ¶

frame_to_h5_group( frame, h5_group, compression="gzip", compression_opts=4 )

Write a Frame to an HDF5 group.

This function can be used to write a Frame to any HDF5 group, making it reusable for both single Frame files and trajectory files.

Parameters:

Name Type Description Default

frame Frame

Frame object to write

required

h5_group 'h5py.Group'

HDF5 group to write to

required

compression str | None

Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.

'gzip'

compression_opts int

Compression level (for gzip: 0-9). Defaults to 4.

4

Raises:

Type Description

ValueError

If frame is empty (no blocks).

h5_group_to_frame ¶

h5_group_to_frame(h5_group, frame=None)

Read a Frame from an HDF5 group.

This function can be used to read a Frame from any HDF5 group, making it reusable for both single Frame files and trajectory files.

Parameters:

Name Type Description Default

h5_group 'h5py.Group'

HDF5 group to read from

required

frame Frame | None

Optional existing Frame to populate. If None, creates a new one.

None

Returns:

Name Type Description

Frame Frame

Populated Frame object with blocks and metadata from HDF5 group.

Amber¶

amber ¶

AmberInpcrdReader ¶

AmberInpcrdReader(file, **kwargs)

Bases: DataReader

Reader for AMBER ASCII *.inpcrd (old-style) coordinate files.

Coordinates: 12.7/12.8 format, 6 numbers per line

Optional velocities section (same length as coordinates)

Optional final box line (3-6 floats)

AC¶

ac ¶

Antechamber (AC) file format reader.

Reads Antechamber .ac files containing atom and bond information with force field types and charges.

AcFieldFormatter ¶

Bases: FieldFormatter

Antechamber .ac field name translation.

AcReader ¶

AcReader(file)

Bases: DataReader

Reader for Antechamber .ac format files.

Parses ATOM and BOND sections from Antechamber output files, extracting coordinates, charges, atom types, and connectivity.

Parameters:

Name Type Description Default

file str | Path

Path to .ac file

required

assign_atomic_numbers ¶

assign_atomic_numbers(atoms)

Assign atomic numbers by guessing from atom names/types.

read ¶

read(frame)

Read .ac file and populate Frame with atoms and bonds.

Parameters:

Name Type Description Default

frame Frame

Frame to populate

required

Returns:

Type Description

Frame

Frame with atoms and bonds data

Top¶

top ¶

GROMACS topology file reader for Frame objects.

This module provides a reader for GROMACS topology files that extracts structural information (atoms, bonds, angles, dihedrals, pairs) and creates Frame objects with Block containers.

TopReader ¶

TopReader(file, **open_kwargs)

Bases: DataReader

Read GROMACS topology files and create Frame objects.

This reader parses GROMACS .top files and extracts structural information from sections like [atoms], [bonds], [angles], [dihedrals], and [pairs].

Examples:

>>> reader = TopReader("molecule.top") >>> frame = reader.read() >>> frame["atoms"] # Block with atom data >>> frame["bonds"] # Block with bond data

Initialize GROMACS topology reader.

Parameters:

Name Type Description Default

file PathLike

Path to GROMACS .top file

required

**open_kwargs Any

Additional arguments passed to file open.

{}

read ¶

read(frame=None)

Read GROMACS topology file and populate Frame.

Parameters:

Name Type Description Default

frame Frame | None

Optional existing Frame to populate. If None, creates a new one.

None

Returns:

Type Description

Frame

Frame object with atoms, bonds, angles, dihedrals, and pairs blocks.

TopWriter ¶

TopWriter(file, **open_kwargs)

Bases: DataWriter

Write GROMACS topology files from Frame objects.

Produces a minimal .top file with [ moleculetype ], [ atoms ], [ bonds ], and optional [ pairs ], [ angles ], [ dihedrals ] sections, followed by [ system ] and [ molecules ].

Examples:

>>> writer = TopWriter("molecule.top") >>> writer.write(frame)

write ¶

write(frame)

Write Frame to GROMACS topology file.

Parameters:

Name Type Description Default

frame Frame

Frame object containing "atoms" and optionally "bonds", "pairs", "angles", "dihedrals" blocks.

required

XYZ¶

xyz ¶

XYZ file I/O — molrs (Rust) backend.

Reader/writer delegate to :mod:molrs.io. The reader normalizes molrs output to molpy conventions (merge split multi-columns, species→element, atomic numbers); the writer ensures separate x/y/z coordinate columns.

XYZReader ¶

XYZReader(path, **kwargs)

Bases: DataReader

Read XYZ files via the molrs Rust backend.

XYZWriter ¶

XYZWriter(path, **kwargs)

Bases: DataWriter

Write XYZ files via the molrs Rust backend.

XSF¶

xsf ¶

XSF (XCrySDen Structure File) format reader and writer.

XSF is a format for crystal structure visualization, supporting both periodic and non-periodic structures. It can contain atomic coordinates, unit cell parameters, and other structural information.

XsfReader ¶

XsfReader(file)

Bases: DataReader

Parse an XSF file into a Frame.

XSF format supports both crystal structures (with unit cell) and molecular structures. The format can contain: - CRYSTAL or MOLECULE keyword - PRIMVEC or CONVVEC for unit cell vectors - PRIMCOORD for atomic coordinates - Optional comment lines starting with #

read ¶

read(frame=None)

Read XSF file and return Frame.

Returns¶

Frame Frame with: - frame containing atomic data - box: unit cell for CRYSTAL, Free Box for MOLECULE

XsfWriter ¶

XsfWriter(file)

Bases: DataWriter

Write Frame to XSF format.

Features: - Supports both CRYSTAL and MOLECULE structures - Writes PRIMVEC for unit cell vectors - Writes PRIMCOORD for atomic coordinates - Automatically determines structure type based on presence of box

write ¶

write(frame)

Write Frame to XSF file.

Parameters¶

frame : Frame Frame containing atomic data and optional box information

Trajectory Modules¶

Base¶

base ¶

BaseTrajectoryReader ¶

BaseTrajectoryReader(fpath, *, must_exist=True)

Bases: BaseReader, Iterable['Frame']

Pure, storage-agnostic trajectory reader: a lazy Iterable[Frame].

Subclasses implement only read_frame(index) and the n_frames property; the random-access and iteration API (__iter__, __getitem__, slicing, read_frames / read_range / read_all, __len__) is derived entirely from those two and involves no files.

n_frames abstractmethod property ¶

n_frames

Total number of frames in the trajectory.

read_all ¶

read_all()

Read every frame in the trajectory.

read_frame abstractmethod ¶

read_frame(index)

Read and return the frame at index (negative indices allowed).

read_frames ¶

read_frames(indices)

Read the frames at indices.

Parameters:

Name Type Description Default

indices list[int]

Frame indices to read.

required

Returns:

Type Description

list[Frame]

The frames, in the order requested.

read_range ¶

read_range(start, stop, step=1)

Read frames start (inclusive) to stop (exclusive) by step.

TrajectoryWriter ¶

TrajectoryWriter(fpath)

Bases: BaseReader

Base class for all trajectory file writers.

write_frame abstractmethod ¶

write_frame(frame)

Write a single frame to the file.

LAMMPS¶

lammps ¶

LammpsTrajectoryWriter ¶

LammpsTrajectoryWriter(fpath, atom_style='full')

Bases: TrajectoryWriter

Writer for LAMMPS trajectory files.

write_frame ¶

write_frame(frame, timestep=None)

Write a single frame to the file.

H5¶

h5 ¶

HDF5 trajectory file format support.

This module provides reading and writing of Trajectory objects to/from HDF5 format using h5py. The HDF5 format is efficient for storing large trajectory datasets and supports compression and chunking.

HDF5 Trajectory Structure:¶

/ # Root group ├── frames/ # Group containing all frames │ ├── 0/ # Frame 0 │ │ ├── blocks/ # Data blocks (same structure as single Frame) │ │ └── metadata/ # Frame metadata │ ├── 1/ # Frame 1 │ │ ├── blocks/ │ │ └── metadata/ │ └── ... ├── n_frames # Attribute: total number of frames └── metadata/ # Optional trajectory-level metadata

HDF5TrajectoryReader ¶

HDF5TrajectoryReader(path, **open_kwargs)

Bases: BaseTrajectoryReader

Read Trajectory objects from HDF5 files.

A binary, random-access :class:BaseTrajectoryReader: it implements only read_frame + n_frames and inherits __iter__ / __getitem__ / slicing / __len__ from the pure base (no mmap).

The HDF5 file structure should follow: - /frames/{frame_index}/blocks/ for data blocks - /frames/{frame_index}/metadata/ for frame metadata - /n_frames attribute for total frame count

Examples:

>>> reader = HDF5TrajectoryReader("trajectory.h5") >>> frame = reader.read_frame(0) >>> for frame in reader: ... process(frame)

Initialize HDF5 trajectory reader.

Parameters:

Name Type Description Default

path PathLike

Path to HDF5 trajectory file.

required

**open_kwargs Any

Additional arguments passed to h5py.File.

{}

n_frames property ¶

n_frames

Number of frames in the trajectory.

close ¶

close()

Close the HDF5 file if open.

read_frame ¶

read_frame(index)

Read a specific frame from the trajectory.

Parameters:

Name Type Description Default

index int

Frame index (0-based)

required

Returns:

Type Description

Frame

Frame object

Raises:

Type Description

IndexError

If index is out of range

HDF5TrajectoryWriter ¶

HDF5TrajectoryWriter( path, compression="gzip", compression_opts=4, **open_kwargs, )

Bases: TrajectoryWriter

Write Trajectory objects to HDF5 files.

The HDF5 file structure follows: - /frames/{frame_index}/blocks/ for data blocks - /frames/{frame_index}/metadata/ for frame metadata - /n_frames attribute for total frame count

Examples:

>>> writer = HDF5TrajectoryWriter("trajectory.h5") >>> writer.write_frame(frame0) >>> writer.write_frame(frame1) >>> writer.close()

Initialize HDF5 trajectory writer.

Parameters:

Name Type Description Default

path PathLike

Path to output HDF5 file

required

compression str | None

Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.

'gzip'

compression_opts int

Compression level (for gzip: 0-9). Defaults to 4.

4

**open_kwargs Any

Additional arguments passed to h5py.File.

{}

close ¶

close()

Close the HDF5 file.

write_frame ¶

write_frame(frame)

Write a single frame to the trajectory file.

Parameters:

Name Type Description Default

frame Frame

Frame object to write

required

XYZ¶

xyz ¶

XYZTrajectoryWriter ¶

XYZTrajectoryWriter(fpath)

Bases: TrajectoryWriter

Writer for XYZ trajectory files.

close ¶

close()

Close the file.

write_frame ¶

write_frame(frame)

Write a single frame to the XYZ file.

write_traj ¶

write_traj(trajectory)

Write multiple frames to the XYZ file.

Log Modules¶

LAMMPS¶

lammps ¶

LAMMPS log file parser.

This module parses the standard LAMMPS run output structure documented in Run_output.html: thermo tables, loop timing, performance summaries, CPU/MPI timing, load-balance statistics, neighbor statistics, and warnings. Unrecognized lines are preserved so callers can still inspect information that does not yet have a structured representation.

LAMMPSCPUUse dataclass ¶

LAMMPSCPUUse(percent, MPI_tasks, OMP_threads, raw_line)

% CPU use summary line.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSLoadBalance dataclass ¶

LAMMPSLoadBalance( name, average, maximum, minimum, histogram, raw_lines )

LAMMPS load-balance statistic plus optional histogram.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSLog dataclass ¶

LAMMPSLog(file, style='default')

Parsed LAMMPS log.

Parameters:

Name Type Description Default

file PathLike

Path to a LAMMPS log file.

required

style str

Thermo style. Only "default" is currently parsed.

'default'

Notes

The class keeps the historical LAMMPSLog(path).read() workflow and log["stages"] compatibility while exposing the new dataclass-shaped result through attributes such as runs.

file property ¶

file

Compatibility alias for the historical file attribute.

legacy_thermo_stages ¶

legacy_thermo_stages()

Return thermo arrays using the historical stages shape.

read ¶

read()

Read and parse the log file. Returns self for chaining.

read_thermo ¶

read_thermo(text, style)

Parse thermo tables into the compatibility mapping.

read_version ¶

read_version(text)

Extract the LAMMPS version line into the compatibility mapping.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

stages and n_stages are retained for compatibility. New code should prefer runs.

LAMMPSLogHeader dataclass ¶

LAMMPSLogHeader(lines)

Header text before the first parsed LAMMPS run block.

raw_text property ¶

raw_text

Header lines joined by newlines.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSLoopTime dataclass ¶

LAMMPSLoopTime(seconds, procs, steps, atoms, raw_line)

Loop time summary line.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSMemoryUsage dataclass ¶

LAMMPSMemoryUsage( minimum, average, maximum, units, raw_line )

Per MPI rank memory allocation line.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSNeighborStatistics dataclass ¶

LAMMPSNeighborStatistics( total_neighbors, ave_neighs_per_atom, ave_special_neighs_per_atom, neighbor_list_builds, dangerous_builds, raw_lines, )

Neighbor-list statistics emitted after a run.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSPerformance dataclass ¶

LAMMPSPerformance( ns_per_day, hours_per_ns, timesteps_per_second, atom_steps_per_second, atom_steps_units, raw_line, )

LAMMPS Performance summary line.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSRun dataclass ¶

LAMMPSRun( index, setup_log, memory, thermo, loop_time, performance, CPU_use, MPI_task_timing, thread_timing, load_balance, neighbor_statistics, warnings, unparsed_log, raw_text, )

One LAMMPS run output block.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSThermo dataclass ¶

LAMMPSThermo(columns, data, raw_lines)

LAMMPS thermo table with dynamic columns.

n_rows property ¶

n_rows

Number of thermo rows.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSTimingBreakdown dataclass ¶

LAMMPSTimingBreakdown(title, rows, raw_lines)

MPI task timing breakdown or thread timing table.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSTimingRow dataclass ¶

LAMMPSTimingRow( section, min_time, avg_time, max_time, percent_varavg, percent_total, raw_line, )

One row from a LAMMPS timing breakdown table.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

LAMMPSWarning dataclass ¶

LAMMPSWarning( message, raw_line, line_number=None, run_index=None )

A warning line from the LAMMPS log.

to_dict ¶

to_dict()

Return a JSON-friendly representation.

read_LAMMPS_log ¶

read_LAMMPS_log(file)

Read a LAMMPS log file into a nested dataclass result.

Parameters:

Name Type Description Default

file PathLike

Path to the LAMMPS log file.

required

Returns:

Type Description

LAMMPSLog

Parsed LAMMPSLog object.

Name	Type	Description	Default
`fpath`	`str \| Path \| TextIO`	Output file path or file-like object	required
`precision`	`int`	Number of decimal places for floating point values	`6`

Name	Type	Description	Default
`whitelist`	`set[str] \| None`	Set of type names to include. If None, all types pass.	`None`
`blacklist`	`set[str] \| None`	Set of type names to exclude. Applied after whitelist.	`None`
`custom`	`Callable \| None`	Custom filter function that takes (type_obj) -> bool. Applied after whitelist and blacklist.	`None`

Name	Type	Description	Default
`filepath`	`str \| Path`	Path to the XML force field file, or filename for built-in files (e.g., "oplsaa.xml" will load from molpy/data/forcefield/)	required
`angle_unit`	`str`	Unit of angle equilibria (`"angle"`/phase) in the input file — `"radian"` (default, the OpenMM/OPLS XML convention) or `"degree"`. Values are converted to the internal degrees representation on read, so the rest of the pipeline is unit-consistent.	`'radian'`

Name	Type	Description	Default
`forcefield`	`AtomisticForcefield \| None`	Optional existing force field to populate. If None, creates new one.	`None`
`layer`	`int`	Overlay level for this read. `0` (default) is the base force field; a positive value marks every atom type parsed here as an overlay that overrides the base during SMARTS typing (higher layer wins). Used to stack `oplsaa.xml` (layer 0) → `clp.xml` (layer 1) → `clpol.xml` (layer 2).	`0`

Name	Type	Description	Default
`filepath`	`str \| Path`	Destination path.	required
`precision`	`int`	Number of decimal digits for floating-point values.	`6`

Name	Type	Description	Default
`filepath`	`str \| Path`	Path to the OPLS-AA XML file, or "oplsaa.xml" for built-in	required
`forcefield`	`AtomisticForcefield \| None`	Optional existing force field to populate	`None`

Name	Type	Description	Default
`filepath`	`str \| Path`	Output path.	required
`forcefield`	`AtomisticForcefield`	Force field to serialize.	required

Name	Type	Description	Default
`frame`	`Frame`	Template frame to rewrite (mutated in place).	required
`type_maps`	`dict[str, dict[str, int]]`	Section → `{type_name: id}` mapping from :func:`collect_type_maps`.	required
`template_name`	`str`	Template name used in the warning message.	`''`

Type	Description
`dict[str, list[str]]`	A `(labels, type_maps)` pair. `labels` maps data-writer
`dict[str, dict[str, int]]`	label keys (`"atom_types"`, `"bond_types"`, …) to sorted
`tuple[dict[str, list[str]], dict[str, dict[str, int]]]`	type-name lists; `type_maps` maps section names (`"atoms"`,
`tuple[dict[str, list[str]], dict[str, dict[str, int]]]`	`"bonds"`, …) to `{type_name: 1-based id}` dicts.

Name	Type	Description	Default
`template`	`BondReactTemplate`	Bond/react template carrying pre/post subgraphs and the initiator/edge/delete atom lists.	required
`base_path`	`str \| Path`	Stem path; produces `{base_path}.map`.	required

Name	Type	Description	Default
`path`	`PathLike`	Path to HDF5 file	required
`**open_kwargs`	`Any`	Additional arguments passed to h5py.File	`{}`

Name	Type	Description	Default
`path`	`PathLike`	Path to output HDF5 file	required
`compression`	`str \| None`	Compression algorithm (None, 'gzip', 'lzf', 'szip'). Defaults to 'gzip'.	`'gzip'`
`compression_opts`	`int`	Compression level (for gzip: 0-9). Defaults to 4.	`4`
`**open_kwargs`	`Any`	Additional arguments passed to h5py.File	`{}`

Name	Type	Description	Default
`h5_group`	`'h5py.Group'`	HDF5 group to read from	required
`frame`	`Frame \| None`	Optional existing Frame to populate. If None, creates a new one.	`None`

Name	Type	Description	Default
`path`	`PathLike`	Path to HDF5 trajectory file.	required
`**open_kwargs`	`Any`	Additional arguments passed to h5py.File.	`{}`

I/O¶

Quick reference¶

Data files¶

Force fields¶

Trajectories¶

Logs¶

Canonical examples¶

Related¶

Full API¶

Factory Functions¶

readers ¶

PathLike module-attribute ¶

LAMMPSLog dataclass ¶

file property ¶

__getitem__ ¶

__setitem__ ¶

legacy_thermo_stages ¶

read ¶

read_thermo ¶

read_version ¶

to_dict ¶

_ensure_frame ¶

read_LAMMPS_log ¶

read_amber_ac ¶

read_amber_frcmod ¶

read_amber_inpcrd ¶

read_amber_prmtop ¶

read_dcd_trajectory ¶

read_gro ¶

read_h5 ¶

read_h5_trajectory ¶

read_lammps_data ¶

read_lammps_forcefield ¶

read_lammps_molecule ¶

read_lammps_trajectory ¶

read_mol2 ¶

read_pdb ¶

read_pdb_trajectory ¶

read_top ¶

read_trr_trajectory ¶

read_xml_forcefield ¶

read_xsf ¶

read_xtc_trajectory ¶

read_xyz ¶

read_xyz_trajectory ¶

writers ¶

PathLike module-attribute ¶

write_amber_frcmod ¶

write_gro ¶

write_h5 ¶

write_h5_trajectory ¶

write_lammps_bond_react_system ¶

write_lammps_data ¶

write_lammps_forcefield ¶

write_lammps_molecule ¶

write_lammps_system ¶

write_lammps_trajectory ¶

write_pdb ¶

write_top ¶

write_trr ¶

write_xsf ¶

write_xtc ¶

write_xyz_trajectory ¶

ForceField Modules¶

Base¶

base ¶

ForceFieldReader ¶

read abstractmethod ¶

ForceFieldWriter ¶

write abstractmethod ¶

LAMMPS¶

lammps ¶

LAMMPSForceFieldReader ¶

read_angle_coeff ¶

read_bondcoeff ¶

read_dihedral_coeff ¶

read_improper_coeff ¶

read_pair_coeff ¶

LAMMPSForceFieldWriter ¶

write ¶

PathLike `module-attribute` ¶

LAMMPSLog `dataclass` ¶

file `property` ¶

getitem ¶

setitem ¶

PathLike `module-attribute` ¶

read `abstractmethod` ¶

write `abstractmethod` ¶

from_whitelist `classmethod` ¶

sanitizer `staticmethod` ¶