Skip to content

I/O

mp.io mirrors molrs.io. Single-frame formats have read_<format>(source) and write_<format>(sink, frame) functions. Pass a pathlib.Path for a file, bytes or mp.io.Text(text) for in-memory input, and a bytearray for in-memory output. A bare string cannot identify whether it is a path or file contents. Multi-frame readers and writers live in their format modules, for example mp.io.lammps.LammpsDumpReader(path) and mp.io.lammps.LammpsDumpWriter(path).

Data API
Structure files read_pdb / write_pdb, read_mol2 / write_mol2, read_gro / write_gro, read_xyz / write_xyz, read_lammps_data / write_lammps_data, plus CIF, CUBE, XSF, POSCAR, SDF and AMBER readers
Force fields mp.io.lammps.LammpsForcefieldReader / LammpsForcefieldWriter; mp.io.gromacs.GromacsTopForcefieldReader / GromacsTopForcefieldWriter; corresponding classes in amber, openmm_xml and xml
Trajectories <Format>Reader / <Format>Writer in pdb, gro, xyz, lammps, dcd, trr and xtc
SMILES and CGsmiles mp.io.smiles.read_smiles(text), mp.io.cgsmiles.read_cgsmiles(text)
Scientific records mp.io.write_mrec(path, frame=..., trajectory=..., forcefield=...), mp.io.mrec.MrecFile(path), mp.io.mrec.MrecReader(path)
Wire frames mp.io.read_wire_frame / mp.io.write_wire_frame
Logs and metrics mp.io.read_lammps_log; molpy's lammps.LammpsLogMetricReader, mrec.MrecMetricReader and mlp_jsonl.MlpJsonlMetricReader

The format-specific force-field classes use read(source) and write(sink, forcefield). GROMACS and AMBER readers also expose read_system(source) for a force field and its typed frame. LAMMPS data coefficients are read with LammpsForcefieldReader().read_data_coeffs(frame).

For a record, MrecFile.sections() lists its sections and frame(), system(), meta() and forcefield() read them. MrecReader accesses its trajectory by index or iteration.

Metric readers (molpy's)

molpy publishes three readers in the molcrafts.metric_readers entry-point group, for any molcrafts viewer to find by format. Each turns a parsed file into plottable series records; none parses a format itself.

Class Format Entry point
lammps.LammpsLogMetricReader log.lammps thermo tables lammps_log
mlp_jsonl.MlpJsonlMetricReader *.mlp.jsonl metric records (tailable) mlp_jsonl
mrec.MrecMetricReader the step / time series of a *.mrec trajectory (store directory or packed *.mrec.zip) mrec

Every reader enforces a viewer's request the same way:

  • since is a raw index: the number of records of the reader's unfiltered, unstrided stream to skip (LAMMPS: row-major over thermo rows and columns; mrec: every step record, then every time record; mlp_jsonl: line order).
  • stride keeps every n-th sample of each series after since and the metric_type / keys filters; limit caps the records yielded.
  • A record's s is the simulation step where the source records one (the LAMMPS Step column, the mrec step column), else the sample's ordinal in its source; mlp_jsonl records keep the s their writer gave them.
  • MlpJsonlMetricReader skips only a torn last line (no trailing newline, not yet parseable); any other malformed line raises ValueError with its line number.

Example

from pathlib import Path
import molpy as mp

frame = mp.io.read_pdb(Path("molecule.pdb"))
mp.io.write_pdb(Path("copy.pdb"), frame)

record = Path("snapshot.mrec")
mp.io.write_mrec(record, frame=frame)
restored = mp.io.mrec.MrecFile(record).frame()

Full API

LAMMPS data files

read_lammps_data 

read_lammps_data(source, atom_style=None)

Read a LAMMPS data file. Typed blocks carry type_id and the string type; atom_style fixes the Atoms layout as LAMMPS's atom_style does.

write_lammps_data 

write_lammps_data(
    sink,
    frame,
    *,
    type_labels=None,
    atom_style=None,
    units=None,
)

LAMMPS fix bond/react

BondReactTemplate

One fix bond/react reaction: pre / post templates (Atomistic or Frame, atoms paired by an integer react_id) and the atoms the map file names (atoms of pre, or their react_id).

write_lammps_bond_react_system 

write_lammps_bond_react_system(
    workdir, frame, forcefield, templates
)

Write {stem}.data, {stem}.ff and per template {name}_pre.mol / {name}_post.mol / {name}.map into workdir, with one type numbering for system and templates. Warns for untyped template topology it leaves out.

mrec (scientific records)

mp.io.write_mrec(path, frame=..., system=..., trajectory=..., forcefield=...) writes a record. mp.io.mrec.MrecFile(path) reads its sections(), meta(), frame(), system() and forcefield(). mp.io.mrec.MrecReader(path) reads trajectory frames lazily.

Metric readers

LammpsLogMetricReader

log.lammps thermo tables, parsed by molrs.io.read_lammps_log.

Thermo rows carry no wall-clock. LAMMPS records simulation steps, not timestamps, so each record is tagged wall_time_source: "ingest" and carries its step in s (the Step column; a table without one gets the row's ordinal across every run). Synthesizing per-row times from Loop time would be fabricated data.

read 

read(path, *, source='', request=None)

Yield the thermo records request selects (see :mod:._metric_reader).

The raw stream is row-major: for each run, for each thermo row, one record per non-Step column, so since counts those records.

MlpJsonlMetricReader

*.mlp.jsonl — records that already are metric records.

It is the format molexp writes while a run is in flight, which makes it the one that grows underneath a live chart. That is why it is tailable; it is not otherwise privileged, and it is read through the same seam as every other format.

Only a torn tail is forgiven. A live writer can be caught mid-line, so a last line with no terminating newline that does not parse is not a record yet: it is skipped, and the next poll reads it whole. Any other line that is not a JSON object with a k key is corruption, and :meth:read raises :class:ValueError naming the file and line rather than skip it — a skipped line would silently shift every later record's since index. Blank lines are not records.

read 

read(path, *, source='', request=None)

Yield the records request selects (see :mod:._metric_reader).

The raw stream is the file's records in line order, so since counts records (blank lines and a torn tail excluded). Each record keeps its own s and tags; source is added unless it has one.

Raises:

Type Description
ValueError

A line other than a torn tail is not a metric record.

MrecMetricReader

*.mrec records — the per-frame series a trajectory carries.

A record is not a metrics file: what it has that a chart can draw is its simulation step and time per frame. Those are emitted and nothing else is invented. Both forms of a record are read: the *.mrec store directory a run writes, and the *.mrec.zip archive molrs packs it into once closed (pack_mrec_zip).

read 

read(path, *, source='', request=None)

Yield the step / time records request selects.

The raw stream is series-major — every frame's mrec/step, then every frame's mrec/time — so since counts those records. s is the frame's simulation step, or its index when the record has no step column (see :mod:._metric_reader).

sniff 

sniff(path)

True for a *.mrec directory or *.mrec.zip file molrs can open.