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)

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)

# 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

_ensure_frame

_ensure_frame(frame)

Ensure a Frame object exists.

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.

Parameters:

Name	Type	Description	Default
traj	PathLike	Path to LAMMPS trajectory file	required
frame	Any	Optional reference Frame for topology	None

Returns:

Type	Description
Any	LammpsTrajectoryReader 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_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.

Parameters:

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

Returns:

Type	Description
Any	XYZTrajectoryReader 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)

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

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)

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)

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

Returns:

Type	Description
AtomisticForcefield	Populated AtomisticForcefield object

Example

Load built-in OPLS-AA force field

ff = read_xml_forcefield("oplsaa.xml")

Load custom force field from path

from pathlib import Path ff = read_xml_forcefield(Path("/path/to/custom.xml"))

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

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

GroFieldFormatter

Bases: FieldFormatter

GROMACS .gro field name translation.

GroReader

GroReader(file)

Bases: DataReader

Robust GROMACS GRO file reader.

Features: - Parses GRO format atoms with proper field extraction - Handles box information (orthogonal and triclinic) - Robust error handling for malformed files - Proper coordinate precision preservation

assign_numbers

assign_numbers(atoms)

Assign atomic numbers based on atom names.

read

read(frame=None)

Read GRO file and populate frame.

sanitizer staticmethod

sanitizer(line)

Clean line while preserving GRO format.

GroWriter

GroWriter(path)

Bases: DataWriter

GROMACS GRO file writer.

Features: - Writes properly formatted GRO files - Handles orthogonal and triclinic boxes - Supports velocity information - Maintains precision for coordinates

write

write(frame)

Write frame to GRO file.

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

XYZReader

XYZReader(path, **open_kwargs)

Bases: DataReader

Parse an XYZ file (single model) into an :class:Frame.

Supports both standard XYZ and extended XYZ (extxyz) formats.

Standard XYZ Format

1. integer `N`  - number of atoms
2. comment line - stored in frame.metadata
3. N lines: `symbol  x  y  z`

Extended XYZ Format

1. integer `N`  - number of atoms
2. comment line with key=value pairs (e.g., Properties=species:S:1:pos:R:3)
3. N lines with columns defined by Properties specification

read

read(frame=None)

Parameters

frame Optional frame to populate; if None, a new one is created.

Returns

Frame Frame with: * block "atoms": - element -> (N,) x -> (N,) float array - y -> (N,) float array - z -> (N,) float array - number -> (N,) int array (atomic numbers) - additional columns from Properties if extxyz * metadata from comment line

Trajectory Modules

Base

base

BaseTrajectoryReader

BaseTrajectoryReader(fpath)

Bases: ABC, Iterable['Frame']

Base class for trajectory file readers that act as lazy-loading iterators.

This class provides memory-mapped file reading and directly returns Frame objects without loading everything into memory. Supports reading from multiple files.

Implements Iterable[Frame] for lazy iteration over frames.

Initialize the trajectory reader.

Parameters:

Name	Type	Description	Default
fpath	PathLike | list[PathLike]	Path to trajectory file or list of paths to multiple trajectory files	required

fpath property

fpath

For backward compatibility - returns the first file path.

n_frames property

n_frames

Number of frames in the trajectory.

close

close()

Close all memory-mapped files.

read_all

read_all()

Read all frames from the trajectory file.

read_frame

read_frame(index)

Read a specific frame from the trajectory file(s).

Parameters:

Name	Type	Description	Default
index	int	Global frame index to read	required

Returns:

Type	Description
Frame	The Frame object

read_frames

read_frames(indices)

Read multiple frames from the trajectory file.

Parameters:

Name	Type	Description	Default
indices	list[int]	list of frame indices to read	required

Returns:

Type	Description
list[Frame]	list of Frame objects

read_range

read_range(start, stop, step=1)

Read a range of frames from the trajectory file.

Parameters:

Name	Type	Description	Default
start	int	Starting frame index	required
stop	int	Stopping frame index (exclusive)	required
step	int	Step size	1

Returns:

Type	Description
list[Frame]	list of Frame objects

FrameLocation

Bases: NamedTuple

Location information for a frame.

MappedFile

MappedFile(fd, mm)

Thin wrapper around mmap.mmap that keeps the file descriptor alive.

The stdlib mmap object does not own the fd, so if the caller closes it the mapping becomes invalid. MappedFile holds both the open file object and the memory-mapped buffer.

close

close()

Close the memory-mapped buffer and the underlying file descriptor.

open_readonly classmethod

open_readonly(path)

Open path as a read-only memory-mapped file.

Gzip-compressed files (.gz) are transparently decompressed into a temporary file before memory-mapping.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to file.	required

Returns:

Type	Description
MappedFile	MappedFile instance.

Raises:

Type	Description
FileNotFoundError	if the file does not exist.
ValueError	if the file is empty.

TrajectoryWriter

TrajectoryWriter(fpath)

Bases: ABC

Base class for all trajectory file writers.

write_frame abstractmethod

write_frame(frame)

Write a single frame to the file.

LAMMPS

lammps

LammpsTrajectoryReader

LammpsTrajectoryReader(fpath, frame=None, extra_type_mappings=None)

Bases: BaseTrajectoryReader

Reader for LAMMPS trajectory files, supporting multiple files.

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)

Read Trajectory objects from HDF5 files.

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.

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

XYZTrajectoryReader

XYZTrajectoryReader(fpath)

Bases: BaseTrajectoryReader

Reader for XYZ trajectory files.

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.