Xmolout Analyzer Analysis

xmolout trajectory analysis utilities.

This module provides atomistic and trajectory-level analysis tools for ReaxFF xmolout files via XmoloutHandler.

It supports extraction of atom properties, trajectories, simulation box information, displacement metrics, atom-type mappings, and radial distribution functions (RDFs) using multiple backends.

Typical use cases include:

exporting per-atom coordinates or properties across frames
building atom trajectories in long or wide format
tracking box dimensions and thermodynamic scalars over time
computing mean-squared displacement (MSD)
computing total or partial RDFs and RDF-derived properties

`get_atom_trajectories(xh, *, frames=None, every=1, atoms=None, atom_types=None, dims=('x', 'y', 'z'), format='long')`

Extract atomic trajectories across frames.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed xmolout handler.	required
`frames`	`int, slice, or sequence of int`	Frame indices to include.	`None`
`every`	`int`	Subsample frames by taking every Nth frame.	`1`
`atoms`	`sequence of int or slice`	Atom indices to include.	`None`
`atom_types`	`sequence of str`	Atom types to include.	`None`
`dims`	`sequence of {"x", "y", "z"}`	Coordinate components to extract.	`("x","y","z")`
`format`	`('long', 'wide')`	Output format.	`"long"`

Returns:

Type	Description
`DataFrame`	Atom trajectories in long or wide format.

Examples:

>>> df = get_atom_trajectories(xh, atoms=[1, 2], dims=("z",))

`get_atom_type_mapping(xh, frame=0)`

Return atom-type mappings for a given frame.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed xmolout handler.	required
`frame`	`int`	Frame index to inspect.	`0`

Returns:

Type	Description
`dict`	Mapping containing: - `types`: sorted unique atom types - `type_to_indices`: atom indices per type (1-based) - `index_to_type`: per-atom type list

Examples:

>>> m = get_atom_type_mapping(xh)
>>> m["types"]

`get_mean_squared_displacement(xh, *, frames=None, every=1, atoms=None, atom_types=None, dims=('x', 'y', 'z'), origin='first')`

Compute per-atom mean-squared displacement (MSD) without PBC unwrapping.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed xmolout handler.	required
`frames`	`int, slice, or sequence of int`	Frames over which MSD is computed.	`None`
`every`	`int`	Subsample frames by taking every Nth frame.	`1`
`atoms`	`sequence of int`	Atom indices to include.	`None`
`atom_types`	`sequence of str`	Atom types to include.	`None`
`dims`	`sequence of {"x","y","z"}`	Coordinate components used for displacement.	`("x","y","z")`
`origin`	`'first'`	Reference frame for displacement.	`"first"`

Returns:

Type	Description
`DataFrame`	Long-format table with columns `frame_index`, `iter`, `atom_id`, and `msd`.

Examples:

>>> df = get_mean_squared_displacement(xh, atom_types=["O"])

`get_radial_dist_fnc(xh, *, backend='freud', frames=None, types_a=None, types_b=None, r_max=None, bins=200, property=None, average=True, return_stack=False)`

Compute radial distribution functions (RDFs) or RDF-derived properties.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed xmolout handler.	required
`backend`	`('freud', 'ovito')`	RDF backend to use.	`"freud"`
`frames`	`iterable of int`	Frame indices to include.	`None`
`types_a`	`iterable of str`	Atom types defining a partial RDF.	`None`
`types_b`	`iterable of str`	Atom types defining a partial RDF.	`None`
`r_max`	`float`	Maximum radius cutoff.	`None`
`bins`	`int`	Number of RDF bins.	`200`
`property`	`str`	RDF-derived quantity (e.g. `first_peak`, `dominant_peak`, `area`, `excess_area`).	`None`
`average`	`bool`	Average RDF curves across frames.	`True`
`return_stack`	`bool`	Return per-frame RDF curves when not averaging.	`False`

Returns:

Type	Description
`numpy.ndarray, tuple, or pandas.DataFrame`	RDF curves or per-frame RDF-derived properties.

Examples:

>>> r, g = get_radial_dist_fnc(xh, types_a=["Al"], types_b=["N"])
>>> df = get_radial_dist_fnc(xh, property="first_peak")

`get_unit_cell_dimensions_across_frames(xh, *, frames=None, every=1)`

Extract simulation box dimensions and scalar quantities per frame.

Works on

XmoloutHandler — xmolout

Parameters:

Name	Type	Description	Default
`xh`	`XmoloutHandler`	Parsed xmolout handler.	required
`frames`	`int, slice, or sequence of int`	Frame indices to include.	`None`
`every`	`int`	Subsample frames by taking every Nth frame.	`1`

Returns:

Type	Description
`DataFrame`	Table with columns such as `a`, `b`, `c`, `alpha`, `beta`, `gamma`, `E_pot`, and `num_of_atoms`.

Examples:

>>> df = get_unit_cell_dimensions_across_frames(xh)