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
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)

Related

• Concepts: Block and Frame
• Concepts: Force Field

---

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_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, forcefield=None)

Read LAMMPS force field file and return a ForceField object.

Parameters:

Name	Type	Description	Default
scripts	PathLike | list[PathLike]	Path or list of paths to LAMMPS force field scripts	required
forcefield	Any	Optional existing ForceField to populate	None

Returns:

Type	Description
Any	Populated ForceField object

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_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_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_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_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.

OPLSAAForceFieldReader

OPLSAAForceFieldReader(filepath)

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)

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

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)

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.

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.

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.