Xmolout Generator

XMOL trajectory file generators.

This module provides utilities for generating new ReaxFF xmolout files from in-memory trajectory data or from an existing XmoloutHandler. Generated files are fully compatible with downstream ReaxKit analyses (e.g., coordination, connectivity, and visualization workflows).

Typical use cases include:

writing a filtered or reduced xmolout from an existing trajectory
exporting selected frames or atoms for focused analysis
generating synthetic or post-processed trajectories with extra per-atom fields

`write_xmolout_from_frames(frames, out_path, *, simulation_name='MD', precision=6, defaults=None)`

Write an xmolout file from explicit per-frame dictionaries.

Works on

In-memory frame dictionaries → xmolout

Parameters:

Name	Type	Description	Default
`frames`	`iterable of dict`	Frame dictionaries with required keys: `iter`, `coords`, `atom_types`. Optional keys include: `E_pot`, `a`, `b`, `c`, `alpha`, `beta`, `gamma`, and `extras` for per-atom additional columns.	required
`out_path`	`str or Path`	Output path for the generated xmolout file.	required
`simulation_name`	`str`	Simulation name written to the xmolout header line.	`'MD'`
`precision`	`int`	Decimal precision for floating-point values.	`6`
`defaults`	`dict or None`	Default header values used when missing from a frame.	`None`

Returns:

Type	Description
`Path`	Path to the written xmolout file.

Examples:

>>> frames = [{
...     "iter": 0,
...     "coords": [[0,0,0], [1,0,0]],
...     "atom_types": ["H", "H"],
... }]
>>> write_xmolout_from_frames(frames, "xmolout_test")

`write_xmolout_from_handler(xh, out_path, *, frames=None, atoms=None, atom_types=None, simulation_name=None, precision=6, include_extras=False)`

Write a filtered xmolout file from an existing XmoloutHandler.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed trajectory handler providing frame and metadata access.	required
`out_path`	`str or Path`	Output path for the generated xmolout file.	required
`frames`	`sequence of int, range, slice, or None`	Frame indices to include. If None, all frames are written.	`None`
`atoms`	`sequence of int, slice, or None`	Atom indices to include per frame.	`None`
`atom_types`	`sequence of str or None`	Atom types to include per frame (alternative to `atoms`).	`None`
`simulation_name`	`str or None`	Simulation name written to the xmolout header line.	`None`
`precision`	`int`	Decimal precision for floating-point values.	`6`
`include_extras`	`bool, str, or sequence of str`	Control writing of extra per-atom columns: - False: write only atom type and coordinates - True or "all": write all extra columns - sequence: write only the specified columns	`False`

Returns:

Type	Description
`Path`	Path to the written xmolout file.

Examples:

>>> xh = XmoloutHandler("xmolout")
>>> write_xmolout_from_handler(
...     xh,
...     "xmolout_filtered",
...     frames=range(0, 100),
...     atom_types=["Al", "N"],
... )