Source code for polyphys.simulate.data

"""\
=====================================================================
LAMMPS data files --- :mod:`polyphys.simulate.data`
=====================================================================

The :mod:`~polyphys.simulate.data` module reads and writes LAMMPS data
files, the input of the ``read_data`` command, for molecular systems of
atoms, bonds, and angles. A data file built here serves two ends: a start
configuration that LAMMPS reads and runs, and a topology that analysis tools
such as MDAnalysis read with a dump.

.. versionadded:: 0.6.0

Contents
========

:class:`DataFile` holds the contents of one data file as NumPy arrays, its
box as a :class:`~polyphys.simulate.core.Box`, and checks them.
:func:`read_data` reads a file into it, raising :class:`BrokenDataError`, a
:class:`~polyphys.simulate.core.LammpsFormatError`, for a file that does not
follow the format; :func:`write_data` writes one out. :func:`with_frame`
takes the positions and the box of a dump frame
(:class:`~polyphys.simulate.dump.DumpFrame`) and the rest from a template, to
give a dump its matching topology.

Format
======

A data file is a header and a body. The first line is a title and is
skipped. The header lines give counts and the box, in any order::

    8 atoms
    1 atom types
    8 bonds
    1 bond types
    0.0 6.0 xlo xhi
    0.0 6.0 ylo yhi
    0.0 6.0 zlo zhi
    1.0 0.5 -0.5 xy xz yz

The body is a sequence of sections, each a keyword line followed by one line
per entry: ``Masses`` (``type mass``), ``Atoms`` (columns by atom style, see
:class:`DataFile`), ``Velocities`` (``atom-ID vx vy vz``), ``Bonds``
(``ID type atom1 atom2``), and ``Angles`` (``ID type atom1 atom2 atom3``).
``#`` starts a comment and blank lines are skipped. ``Atoms # bond`` names the
atom style in a comment. A file whose name ends in ``.gz`` is read through
gzip. Atom lines may end with the three image flags, on
all lines or on none; LAMMPS sets missing image flags and velocities to zero.

Supported atom styles: ``atomic``, ``bond``, ``angle``, ``molecular``, and
``full``. Sections with names ending in ``Coeffs`` (force-field coefficients)
are skipped when read and never written; the input script sets them, as
``write_data nocoeff`` assumes. Dihedrals, impropers, type labels, and
general triclinic boxes are not supported.

The module converts no units; values are in the ``units`` of the run.

Complexity
==========

:func:`read_data` and :func:`write_data` take :math:`O(n_a + n_b + n_t)`
time and memory for :math:`n_a` atoms, :math:`n_b` bonds, and :math:`n_t`
angles; :func:`with_frame` takes :math:`O(n_a \\log n_a)` time to match atom
IDs.

References
==========

The format follows the LAMMPS documentation of `read_data
<https://docs.lammps.org/read_data.html>`_ and `write_data
<https://docs.lammps.org/write_data.html>`_.

Dependencies
============
- Python standard library: `dataclasses`, `logging`, `pathlib`
- Third-party: `numpy`
- PolyPhys: :mod:`polyphys.simulate.core`, :mod:`polyphys.simulate.dump`
"""

import dataclasses
import logging
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, NamedTuple

import numpy as np
import numpy.typing as npt

from polyphys.simulate.core import (
    Box,
    FloatArray,
    IntArray,
    LammpsFormatError,
    _frozen,
    _open_text,
)
from polyphys.simulate.dump import DumpFrame

__all__ = [
    "BrokenDataError",
    "DataFile",
    "read_data",
    "with_frame",
    "write_data",
]

logger = logging.getLogger(__name__)


class _Style(NamedTuple):
    """The per-atom columns and the topology an atom style allows."""

    molecule: bool
    charge: bool
    bonds: bool
    angles: bool


# Atoms-section columns per atom style (LAMMPS read_data, "Atoms section").
_STYLES = {
    "atomic": _Style(molecule=False, charge=False, bonds=False, angles=False),
    "bond": _Style(molecule=True, charge=False, bonds=True, angles=False),
    "angle": _Style(molecule=True, charge=False, bonds=True, angles=True),
    "molecular": _Style(molecule=True, charge=False, bonds=True, angles=True),
    "full": _Style(molecule=True, charge=True, bonds=True, angles=True),
}
_COUNTS = {
    "atoms": "atoms", "bonds": "bonds", "angles": "angles",
    "atom types": "atom_types", "bond types": "bond_types",
    "angle types": "angle_types",
}
_UNSUPPORTED_COUNTS = (
    "dihedrals", "impropers", "dihedral types", "improper types",
    "ellipsoids", "lines", "triangles", "bodies",
)
_AXES = (("xlo", "xhi"), ("ylo", "yhi"), ("zlo", "zhi"))
_DEFAULT_TITLE = "LAMMPS data file written by polyphys.simulate.data"


[docs] class BrokenDataError(LammpsFormatError): """A LAMMPS data file does not follow the data-file format. .. versionadded:: 0.6.0 Examples -------- >>> import tempfile >>> with tempfile.TemporaryDirectory() as tmp: ... path = Path(tmp) / "empty.data" ... _ = path.write_text("title\\n\\n2 atoms\\n") ... try: ... read_data(path) ... except BrokenDataError as err: ... print(str(err).split(": ", 1)[1]) the file has a header but no body """
def _empty(width: int) -> IntArray: """Return an empty ``(0, width)`` int64 array.""" return np.empty((0, width), dtype=np.int64)
[docs] @dataclass(frozen=True, eq=False) class DataFile: """The contents of one LAMMPS data file. The arrays are copied, made read-only, and checked on construction; use :func:`dataclasses.replace` to change a field. .. versionadded:: 0.6.0 Attributes ---------- atom_style : {'atomic', 'bond', 'angle', 'molecular', 'full'} The LAMMPS atom style. It sets the Atoms columns: ``atom-ID atom-type x y z`` for ``atomic``; ``atom-ID molecule-ID atom-type x y z`` for ``bond``, ``angle``, and ``molecular``; and ``atom-ID molecule-ID atom-type q x y z`` for ``full``. ``atomic`` has no bonds, ``bond`` no angles. box : :class:`~polyphys.simulate.core.Box` The simulation box. A triclinic box writes its ``xy xz yz`` line; the boundary flags are not part of a data file. ids : numpy.ndarray Shape ``(n_atoms,)``, int64: unique atom IDs, from 1. types : numpy.ndarray Shape ``(n_atoms,)``, int64: atom types, from 1 to `n_atom_types`. positions : numpy.ndarray Shape ``(n_atoms, 3)``, float64: coordinates in the length unit of the run. The writer does not check that they lie in the box: LAMMPS remaps an atom outside it across a periodic boundary and loses one outside a non-periodic boundary. n_atom_types : int Number of atom types, 1 or more; a type may be unused. masses : numpy.ndarray or None Shape ``(n_atom_types,)``: the mass of type :math:`k` at index :math:`k - 1`, or None to write no ``Masses`` section and leave the masses to the input script. mol_ids : numpy.ndarray or None Shape ``(n_atoms,)``, int64: molecule IDs, required by every style but ``atomic`` and None for it. charges : numpy.ndarray or None Shape ``(n_atoms,)``: charges, required by ``full`` and None for the others. image_flags : numpy.ndarray or None Shape ``(n_atoms, 3)``, int64: image flags, or None to write none (LAMMPS then sets them to zero). velocities : numpy.ndarray or None Shape ``(n_atoms, 3)``: velocities, or None to write no ``Velocities`` section (LAMMPS then sets them to zero). bonds : numpy.ndarray Shape ``(n_bonds, 3)``, int64: ``type, atom1, atom2`` per bond, the atoms by ID. Bond IDs are not kept: the writer numbers bonds from 1 in row order. A ring is a chain with one more bond. angles : numpy.ndarray Shape ``(n_angles, 4)``, int64: ``type, atom1, atom2, atom3`` per angle, with ``atom2`` the vertex. n_bond_types, n_angle_types : int Numbers of bond and angle types; 1 or more when there are bonds or angles. Raises ------ TypeError If `box` is not a :class:`~polyphys.simulate.core.Box`. ValueError If the atom style is unknown, an array has the wrong shape or non-integer values where integers are needed, an atom ID repeats or is below 1, a type is out of range, a bond or angle names an atom ID that does not exist, or a field is given that the style does not allow or omitted where it needs one. Examples -------- A ring of three beads with a closing bond: >>> ring = DataFile( ... atom_style="bond", box=Box(lo=np.zeros(3), hi=np.full(3, 10.0)), ... ids=np.arange(1, 4), types=np.ones(3, dtype=int), ... positions=np.array([[5.0, 5.0, 5.0], [6.0, 5.0, 5.0], ... [5.5, 5.9, 5.0]]), ... n_atom_types=1, mol_ids=np.ones(3, dtype=int), ... bonds=np.array([[1, 1, 2], [1, 2, 3], [1, 3, 1]]), n_bond_types=1) >>> ring.n_atoms, ring.n_bonds, ring.n_angles (3, 3, 0) """ atom_style: str box: Box ids: IntArray types: IntArray positions: FloatArray n_atom_types: int masses: FloatArray | None = None mol_ids: IntArray | None = None charges: FloatArray | None = None image_flags: IntArray | None = None velocities: FloatArray | None = None bonds: IntArray = field(default_factory=lambda: _empty(3)) angles: IntArray = field(default_factory=lambda: _empty(4)) n_bond_types: int = 0 n_angle_types: int = 0 def __post_init__(self) -> None: if self.atom_style not in _STYLES: raise ValueError( f"'atom_style' must be one of {tuple(_STYLES)}, " f"got {self.atom_style!r}" ) if not isinstance(self.box, Box): raise TypeError(f"'box' must be a Box, got {type(self.box)}") style = _STYLES[self.atom_style] ids = self._set_int("ids", (-1,)) n_atoms = ids.shape[0] self._set_float("positions", (n_atoms, 3)) types = self._set_int("types", (n_atoms,)) self._set_optional_float("velocities", (n_atoms, 3)) self._set_optional_int("image_flags", (n_atoms, 3)) self._set_needed("mol_ids", style.molecule, (n_atoms,), integer=True) self._set_needed("charges", style.charge, (n_atoms,), integer=False) bonds = self._set_int("bonds", (-1, 3)) angles = self._set_int("angles", (-1, 4)) if np.unique(ids).size != n_atoms or np.any(ids < 1): raise ValueError("atom IDs must be unique and 1 or more") _check_types("atom", types, self.n_atom_types, minimum=1) self._set_optional_float("masses", (self.n_atom_types,)) if bonds.shape[0] and not style.bonds: raise ValueError(f"atom style {self.atom_style!r} has no bonds") if angles.shape[0] and not style.angles: raise ValueError(f"atom style {self.atom_style!r} has no angles") _check_types("bond", bonds[:, 0], self.n_bond_types, minimum=1 if bonds.shape[0] else 0) _check_types("angle", angles[:, 0], self.n_angle_types, minimum=1 if angles.shape[0] else 0) for name, members in (("bond", bonds), ("angle", angles)): missing = np.setdiff1d(members[:, 1:], ids) if missing.size: raise ValueError( f"a {name} names atom IDs that do not exist: " f"{missing.tolist()}" ) @property def n_atoms(self) -> int: """The number of atoms.""" return int(self.ids.shape[0]) @property def n_bonds(self) -> int: """The number of bonds.""" return int(self.bonds.shape[0]) @property def n_angles(self) -> int: """The number of angles.""" return int(self.angles.shape[0])
[docs] def unwrapped_positions(self) -> FloatArray: """Return the positions unwrapped by the image flags. Returns ------- numpy.ndarray Shape ``(n_atoms, 3)``, float64: the positions moved by the image flags along the box edge vectors, by :meth:`~polyphys.simulate.core.Box.unwrap`; a copy of the positions when there are no image flags, which LAMMPS reads as zero. Time and memory are :math:`O(n_a)`. Examples -------- >>> pair = DataFile( ... atom_style="atomic", ... box=Box(lo=np.zeros(3), hi=np.full(3, 10.0)), ... ids=np.array([1, 2]), types=np.array([1, 1]), ... positions=np.array([[9.5, 5.0, 5.0], [0.5, 5.0, 5.0]]), ... n_atom_types=1, image_flags=np.array([[-1, 0, 0], [0, 0, 0]])) >>> pair.unwrapped_positions() array([[-0.5, 5. , 5. ], [ 0.5, 5. , 5. ]]) """ if self.image_flags is None: return self.positions.copy() return self.box.unwrap(self.positions, self.image_flags)
def _set_float(self, name: str, shape: tuple[int, ...]) -> FloatArray: value = _frozen(getattr(self, name), np.float64) _check_shape(name, value, shape) object.__setattr__(self, name, value) return value def _set_int(self, name: str, shape: tuple[int, ...]) -> IntArray: value = _integers(name, getattr(self, name)) if value.size == 0 and len(shape) == 2 and shape[1] > 0: value = value.reshape(0, shape[1]) # no bonds or no angles _check_shape(name, value, shape) value = _frozen(value, np.int64) object.__setattr__(self, name, value) return value def _set_optional_float(self, name: str, shape: tuple[int, ...]) -> None: if getattr(self, name) is not None: self._set_float(name, shape) def _set_optional_int(self, name: str, shape: tuple[int, ...]) -> None: if getattr(self, name) is not None: self._set_int(name, shape) def _set_needed( self, name: str, needed: bool, shape: tuple[int, ...], integer: bool ) -> None: given = getattr(self, name) is not None if needed and not given: raise ValueError(f"atom style {self.atom_style!r} needs '{name}'") if given and not needed: raise ValueError( f"atom style {self.atom_style!r} has no '{name}'" ) if given and integer: self._set_int(name, shape) elif given: self._set_float(name, shape)
def _integers(name: str, value: Any) -> IntArray: """Return `value` as an int64 array, refusing non-integer values.""" array = np.array(value) if array.size and not np.issubdtype(array.dtype, np.integer): if not np.issubdtype(array.dtype, np.number) or not np.all( array == np.round(array) ): raise ValueError(f"'{name}' must hold integers") return array.astype(np.int64) def _check_shape( name: str, value: npt.NDArray[Any], shape: tuple[int, ...] ) -> None: """Check `value` against `shape`, where -1 matches any length.""" if value.ndim != len(shape) or any( want not in (-1, got) for want, got in zip(shape, value.shape) ): raise ValueError( f"'{name}' must have shape {shape}, got {value.shape}" ) def _check_types( kind: str, types: IntArray, n_types: int, minimum: int ) -> None: """Check that every type lies from 1 to `n_types`.""" if n_types < minimum: raise ValueError(f"'n_{kind}_types' must be {minimum} or more, " f"got {n_types}") if types.size and (types.min() < 1 or types.max() > n_types): raise ValueError(f"{kind} types must be from 1 to {n_types}")
[docs] def write_data( data: DataFile, path: str | Path, *, title: str | None = None ) -> Path: """Write a LAMMPS data file. .. versionadded:: 0.6.0 Parameters ---------- data : DataFile The contents to write. path : str or pathlib.Path The file to write; an existing file is overwritten. title : str, optional The first line, which LAMMPS skips; one line, defaulting to a line that names this module. Returns ------- pathlib.Path `path`. Raises ------ ValueError If `title` has a line break. Notes ----- The header gives ``atoms`` and ``atom types``; ``bonds`` and ``bond types`` for every style with bonds; ``angles`` and ``angle types`` for every style with angles; the box; and ``xy xz yz`` when its box is triclinic. Then come ``Masses`` if given, ``Atoms # <style>`` with image flags if given, ``Velocities`` if given, and ``Bonds`` and ``Angles`` if there are any, numbered from 1. Floats are written as the shortest decimal that reads back to the same float64, so ``read_data(write_data(data, path))`` returns `data` unchanged. No coefficient section is written. Time and memory are :math:`O(n_a + n_b + n_t)`. Examples -------- >>> import tempfile >>> pair = DataFile( ... atom_style="atomic", box=Box(lo=np.zeros(3), hi=np.full(3, 5.0)), ... ids=np.array([1, 2]), types=np.array([1, 2]), ... positions=np.array([[2.0, 2.5, 2.5], [3.1, 2.5, 2.5]]), ... n_atom_types=2) >>> with tempfile.TemporaryDirectory() as tmp: ... path = write_data(pair, Path(tmp) / "pair.data", title="Two beads") ... print(path.read_text()) Two beads <BLANKLINE> 2 atoms 2 atom types <BLANKLINE> 0.0 5.0 xlo xhi 0.0 5.0 ylo yhi 0.0 5.0 zlo zhi <BLANKLINE> Atoms # atomic <BLANKLINE> 1 1 2.0 2.5 2.5 2 2 3.1 2.5 2.5 <BLANKLINE> """ title = _DEFAULT_TITLE if title is None else title if "\n" in title or "\r" in title: raise ValueError("'title' must be one line") style = _STYLES[data.atom_style] lines = [title, "", f"{data.n_atoms} atoms", f"{data.n_atom_types} atom types"] if style.bonds: lines += [f"{data.n_bonds} bonds", f"{data.n_bond_types} bond types"] if style.angles: lines += [f"{data.n_angles} angles", f"{data.n_angle_types} angle types"] lines.append("") for (lo_name, hi_name), lo, hi in zip(_AXES, data.box.lo.tolist(), data.box.hi.tolist()): lines.append(f"{lo!r} {hi!r} {lo_name} {hi_name}") if data.box.triclinic: lines.append(" ".join(map(repr, data.box.tilt.tolist())) + " xy xz yz") if data.masses is not None: lines += ["", "Masses", ""] lines += [f"{k} {mass!r}" for k, mass in enumerate(data.masses.tolist(), start=1)] lines += ["", f"Atoms # {data.atom_style}", ""] lines += _atom_lines(data) if data.velocities is not None: lines += ["", "Velocities", ""] lines += [f"{atom} " + " ".join(map(repr, v)) for atom, v in zip(data.ids.tolist(), data.velocities.tolist())] for name, rows in (("Bonds", data.bonds), ("Angles", data.angles)): if rows.shape[0]: lines += ["", name, ""] lines += [f"{k} " + " ".join(map(str, row)) for k, row in enumerate(rows.tolist(), start=1)] path = Path(path) path.write_text("\n".join(lines) + "\n", encoding="utf-8") return path
def _atom_lines(data: DataFile) -> list[str]: """Return the Atoms-section lines in the column order of the style.""" columns: list[list[str]] = [[str(atom)] for atom in data.ids.tolist()] if data.mol_ids is not None: for row, mol in zip(columns, data.mol_ids.tolist()): row.append(str(mol)) for row, atom_type in zip(columns, data.types.tolist()): row.append(str(atom_type)) if data.charges is not None: for row, charge in zip(columns, data.charges.tolist()): row.append(repr(charge)) for row, xyz in zip(columns, data.positions.tolist()): row.extend(map(repr, xyz)) if data.image_flags is not None: for row, image in zip(columns, data.image_flags.tolist()): row.extend(map(str, image)) return [" ".join(row) for row in columns] class _Section(NamedTuple): """One body section: its name, its comment, and its numbered rows.""" name: str comment: str line: int rows: list[tuple[int, list[str]]]
[docs] def read_data(path: str | Path, atom_style: str | None = None) -> DataFile: """Read a LAMMPS data file. .. versionadded:: 0.6.0 Parameters ---------- path : str or pathlib.Path The data file, read as UTF-8; a name ending in ``.gz`` is read through gzip. atom_style : str, optional The atom style, one of those of :class:`DataFile`. Needed when the ``Atoms`` line has no style comment such as ``Atoms # bond``; when both are given they must agree. Returns ------- DataFile Atoms sorted by ID; bonds and angles sorted by their IDs, which are then dropped. Raises ------ BrokenDataError If the file does not follow the format, uses a feature this module does not support (see the module documentation), or gives no atom style, or two that disagree. The message names the file and, where it can, the line, from 1. Notes ----- Sections whose names end in ``Coeffs`` are skipped and logged at level DEBUG. Time and memory are :math:`O(L)` in the length :math:`L` of the file. Examples -------- >>> import tempfile >>> text = '''Two beads and one bond ... ... 2 atoms ... 1 atom types ... 1 bonds ... 1 bond types ... 0 5 xlo xhi ... 0 5 ylo yhi ... 0 5 zlo zhi ... ... Bond Coeffs # fene ... ... 1 30.0 1.5 1.0 1.0 ... ... Atoms # bond ... ... 2 1 1 3.0 2.5 2.5 0 0 0 ... 1 1 1 2.0 2.5 2.5 0 0 0 ... ... Bonds ... ... 1 1 1 2 ... ''' >>> with tempfile.TemporaryDirectory() as tmp: ... path = Path(tmp) / "pair.data" ... _ = path.write_text(text) ... data = read_data(path) >>> data.atom_style, data.ids, data.bonds ('bond', array([1, 2]), array([[1, 1, 2]])) >>> data.positions[:, 0] array([2., 3.]) """ path = Path(path) with _open_text(path) as stream: lines = stream.read().splitlines() header, body = _read_header(lines, path) sections = _read_sections(lines, body, path) atoms = next((s for s in sections if s.name == "Atoms"), None) if atoms is None: raise _broken(path, None, "no Atoms section") style = _atom_style(atoms, atom_style, path) try: fields = _read_body(sections, style, header, path) return DataFile( box=header["box"], n_atom_types=header["atom_types"], n_bond_types=header["bond_types"], n_angle_types=header["angle_types"], **fields, ) except BrokenDataError: raise except ValueError as err: raise _broken(path, None, str(err)) from None
def _broken(path: Path, line: int | None, message: str) -> BrokenDataError: """Return an error naming the file and, when known, the line.""" where = f"{path}" if line is None else f"{path}, line {line}" return BrokenDataError(f"{where}: {message}") def _read_body( sections: list["_Section"], style: str, header: dict[str, Any], path: Path, ) -> dict[str, Any]: """Read the sections into the fields of :class:`DataFile`.""" fields: dict[str, Any] = {"atom_style": style} for section in sections: if section.name == "Atoms": fields.update(_read_atoms(section, style, header, path)) elif section.name == "Velocities": fields["velocities"] = _read_velocities(section, header, path) elif section.name == "Masses": fields["masses"] = _read_masses(section, header, path) elif section.name in ("Bonds", "Angles"): width = 4 if section.name == "Bonds" else 5 count = header["bonds" if width == 4 else "angles"] rows = _table(section, width, count, path) order = np.argsort(rows[:, 0], kind="stable") fields[section.name.lower()] = _integers( section.name, rows[order, 1:] ) elif section.name.endswith("Coeffs"): logger.debug("%s: skipped section %r (line %d)", path, section.name, section.line) else: raise _broken(path, section.line, f"section {section.name!r} is not supported") if "velocities" in fields: fields["velocities"] = _by_atom(fields.pop("velocities"), fields["ids"], "Velocities", path) if header["bonds"] and "bonds" not in fields: raise _broken(path, None, f"{header['bonds']} bonds but no Bonds") if header["angles"] and "angles" not in fields: raise _broken(path, None, f"{header['angles']} angles but no Angles") return fields def _content(line: str) -> tuple[str, str]: """Split a line into its content and its comment, both stripped.""" content, _, comment = line.partition("#") return content.strip(), comment.strip() def _read_header(lines: list[str], path: Path) -> tuple[dict[str, Any], int]: """Read the header; return its values and the index of the body.""" header: dict[str, Any] = {key: 0 for key in _COUNTS.values()} lo, hi = np.zeros(3), np.zeros(3) tilt: FloatArray | None = None seen: set[str] = set() for index in range(1, len(lines)): content, _ = _content(lines[index]) if not content: continue words = content.split() keyword = " ".join(words[1:]) try: if words[-3:] == ["xy", "xz", "yz"] and len(words) == 6: tilt = np.array(words[:3], dtype=np.float64) elif len(words) == 4 and tuple(words[2:]) in _AXES: axis = _AXES.index((words[2], words[3])) lo[axis] = float(words[0]) hi[axis] = float(words[1]) seen.add(words[2]) elif keyword in _COUNTS: header[_COUNTS[keyword]] = int(words[0]) elif keyword in _UNSUPPORTED_COUNTS: if int(words[0]): raise ValueError(f"{keyword} are not supported") elif len(words) > 2 and words[1] == "extra": logger.debug("%s: skipped header line %r", path, content) elif words[-2:] == ["abc", "origin"] or words[-1] in ( "avec", "bvec", "cvec" ): raise ValueError("general triclinic boxes are not supported") else: break except ValueError as err: raise _broken(path, index + 1, str(err)) from None else: raise _broken(path, None, "the file has a header but no body") missing = [name for name, _ in _AXES if name not in seen] if missing: raise _broken(path, None, f"the header gives no {missing} bounds") try: header["box"] = Box(lo=lo, hi=hi, tilt=np.zeros(3) if tilt is None else tilt, triclinic=tilt is not None) except ValueError as err: raise _broken(path, None, str(err)) from None return header, index def _is_number(word: str) -> bool: """Return True if `word` reads as a number.""" try: float(word) except ValueError: return False return True def _read_sections( lines: list[str], start: int, path: Path ) -> list[_Section]: """Split the body into sections; a line that starts with a number is an entry of the section above it.""" sections: list[_Section] = [] names: set[str] = set() for index in range(start, len(lines)): content, comment = _content(lines[index]) if not content: continue words = content.split() if _is_number(words[0]): if not sections: raise _broken(path, index + 1, "an entry before any section keyword") sections[-1].rows.append((index + 1, words)) continue if content in names: raise _broken(path, index + 1, f"section {content!r} repeats") names.add(content) sections.append(_Section(content, comment, index + 1, [])) return sections def _atom_style(atoms: _Section, given: str | None, path: Path) -> str: """Return the atom style from the argument and the Atoms comment.""" named = atoms.comment.split()[0] if atoms.comment else None if given is not None: if named is not None and given != named: raise _broken(path, atoms.line, f"'atom_style' is {given!r} but " f"the file says {named!r}") style = given elif named is not None: style = named else: raise _broken(path, atoms.line, "the Atoms line names no atom style; pass 'atom_style'") if style not in _STYLES: raise _broken(path, atoms.line, f"atom style {style!r} is not " f"supported; use one of {tuple(_STYLES)}") return style def _table( section: _Section, width: int | tuple[int, ...], count: int, path: Path ) -> FloatArray: """Return a section's rows as a float64 array, checking their number and width.""" widths = (width,) if isinstance(width, int) else width if len(section.rows) != count: raise _broken(path, section.line, f"{section.name} has " f"{len(section.rows)} entries, the header says {count}") if not section.rows: return np.empty((0, widths[0])) found = len(section.rows[0][1]) for line, words in section.rows: if len(words) != found or found not in widths: raise _broken(path, line, f"a {section.name} entry needs " f"{' or '.join(map(str, widths))} fields, the same " f"on every line") try: return np.array([words for _, words in section.rows], dtype=np.float64) except ValueError: raise _broken(path, section.line, f"a {section.name} entry holds a " f"value that is not a number") from None def _read_atoms( section: _Section, style: str, header: dict[str, Any], path: Path ) -> dict[str, Any]: """Read the Atoms section into the fields of :class:`DataFile`.""" spec = _STYLES[style] names = ["ids"] + (["mol_ids"] if spec.molecule else []) + ["types"] names += (["charges"] if spec.charge else []) + ["x", "y", "z"] rows = _table(section, (len(names), len(names) + 3), header["atoms"], path) rows = rows[np.argsort(rows[:, 0], kind="stable")] fields: dict[str, Any] = {} for column, name in enumerate(names[:-3]): values = rows[:, column] fields[name] = values if name == "charges" else _integers( name, values) fields["positions"] = rows[:, len(names) - 3:len(names)] if rows.shape[1] > len(names): fields["image_flags"] = _integers("image flags", rows[:, len(names):]) return fields def _read_velocities( section: _Section, header: dict[str, Any], path: Path ) -> FloatArray: """Read the Velocities section as ``atom-ID vx vy vz`` rows.""" return _table(section, 4, header["atoms"], path) def _by_atom( rows: FloatArray, ids: IntArray, name: str, path: Path ) -> FloatArray: """Order ``atom-ID value...`` rows like `ids`, which are sorted.""" keys = _integers(name, rows[:, 0]) order = np.argsort(keys, kind="stable") if not np.array_equal(keys[order], ids): raise _broken(path, None, f"the {name} atom IDs differ from the Atoms atom IDs") ordered: FloatArray = rows[order, 1:] return ordered def _read_masses( section: _Section, header: dict[str, Any], path: Path ) -> FloatArray: """Read the Masses section, one ``type mass`` line per atom type.""" rows = _table(section, 2, header["atom_types"], path) types = _integers("Masses", rows[:, 0]) order = np.argsort(types, kind="stable") expected = np.arange(1, header["atom_types"] + 1) if not np.array_equal(types[order], expected): raise _broken(path, section.line, f"Masses must give each atom type " f"from 1 to {header['atom_types']} once") masses: FloatArray = rows[order, 1] return masses
[docs] def with_frame(template: DataFile, frame: DumpFrame) -> DataFile: """Return `template` with the positions and the box of a dump frame. Use it to write the topology that goes with a dump, for analysis: the atoms, types, masses, bonds, and angles come from `template`, and the positions and box from `frame`. .. versionadded:: 0.6.0 Parameters ---------- template : DataFile A data file of the same system, such as the one the run started from. frame : DumpFrame A frame with an ``id`` column and wrapped coordinate columns, ``x y z`` or the scaled ``xs ys zs``. Unwrapped columns alone, ``xu yu zu`` or ``xsu ysu zsu``, are not accepted. Returns ------- DataFile `template` with, matched by atom ID: the frame's wrapped positions; its image flags if it has ``ix iy iz``, else none; its velocities if it has ``vx vy vz``, else none; and its box. Raises ------ ValueError If the frame has no ``id`` column, its atom IDs differ from those of `template`, or its ``type`` column, when present, disagrees with the template's types. KeyError If the frame has no wrapped coordinate columns, as in a dump of unwrapped coordinates only. Notes ----- The template's image flags and velocities belong to its own positions, so they are never carried over. Time is :math:`O(n_a \\log n_a)`, memory :math:`O(n_a)`. Examples -------- >>> template = DataFile( ... atom_style="bond", box=Box(lo=np.zeros(3), hi=np.full(3, 10.0)), ... ids=np.array([1, 2]), types=np.array([1, 1]), ... positions=np.array([[1.0, 5.0, 5.0], [2.0, 5.0, 5.0]]), ... n_atom_types=1, mol_ids=np.array([1, 1]), ... bonds=np.array([[1, 1, 2]]), n_bond_types=1) >>> frame = DumpFrame(timestep=1000, ... box=Box(lo=np.zeros(3), hi=np.full(3, 8.0)), ... columns=("id", "type", "xs", "ys", "zs"), ... data=np.array([[2, 1, 0.5, 0.5, 0.5], ... [1, 1, 0.375, 0.5, 0.5]])) >>> moved = with_frame(template, frame) >>> moved.positions array([[3., 4., 4.], [4., 4., 4.]]) >>> moved.box.hi, moved.bonds (array([8., 8., 8.]), array([[1, 1, 2]])) """ if "id" not in frame.columns: raise ValueError("the frame has no 'id' column") frame_ids = frame.column("id") frame_order = np.argsort(frame_ids, kind="stable") template_order = np.argsort(template.ids, kind="stable") if not np.array_equal(frame_ids[frame_order], template.ids[template_order]): raise ValueError("the frame's atom IDs differ from the template's") # Row k of the template takes the frame row with the same atom ID. rows = np.empty_like(frame_order) rows[template_order] = frame_order if "type" in frame.columns and not np.array_equal( frame.column("type")[rows], template.types ): raise ValueError("the frame's atom types differ from the template's") try: positions = frame.positions() except KeyError: raise KeyError( "with_frame needs wrapped coordinates, x y z or xs ys zs; a frame " "with unwrapped coordinates only, or none, has no positions " f"inside the box: {frame.columns}" ) from None columns = set(frame.columns) image: IntArray | None = None if {"ix", "iy", "iz"} <= columns: image = np.column_stack( [frame.column(n) for n in ("ix", "iy", "iz")] ).astype(np.int64)[rows] velocities: FloatArray | None = None if {"vx", "vy", "vz"} <= columns: velocities = np.column_stack( [frame.column(n) for n in ("vx", "vy", "vz")] ).astype(np.float64)[rows] return dataclasses.replace( template, positions=positions[rows], box=frame.box, image_flags=image, velocities=velocities, )