`trj2fig`¶

Overview¶

Summary: Extract energies from XYZ trajectory comment lines (or recompute with the MLIP backend), compute relative or absolute energy profiles, and export Plotly figures and CSV tables.

Quick reference¶

Input: An XYZ trajectory whose second line stores Hartree energies, or recompute energies with -q/--charge and/or -m/--multiplicity.
Reference modes: first frame (init), no reference (None), or an explicit 0-based frame index.
Output formats: PNG (default), JPEG, HTML, SVG, PDF, CSV.
Units: kcal/mol (default) or Hartree.
X-axis flip: --reverse-x reverses the axis so the last frame appears on the left.

mlmm trj2fig reads the Hartree energies encoded in each frame’s comment line of an XYZ trajectory, converts them to kcal/mol or Hartree, optionally references all values to a chosen frame, and exports the resulting series as static/interactive figures and CSV tables. The figure uses bold ticks, consistent fonts, markers, and a smoothed spline curve (no title).

Usage¶

mlmm trj2fig -i TRAJECTORY.xyz [-o OUTPUTS...] [-r REFERENCE] [--unit {kcal|hartree}] \
 [-q CHARGE] [-m MULTIPLICITY] [--reverse-x]

Examples¶

# Default PNG, relative energy with respect to the first frame
mlmm trj2fig -i traj.xyz

# CSV + SVG with reference frame #5, reported in Hartree
mlmm trj2fig -i traj.xyz -o energy.csv energy.svg -r 5 --unit hartree

# Multiple outputs in one run with x-axis reversed
mlmm trj2fig -i traj.xyz -o energy.png energy.html energy.pdf --reverse-x

Workflow¶

Parse the XYZ trajectory. By default, Hartree energies are extracted from each frame’s comment line. If -q/--charge or -m/--multiplicity is provided, energies are recomputed with the MLIP backend (default: uma-s-1p1) instead.
Normalize the reference specification:

init – frame 0 (or the last frame when --reverse-x is active).
None/none/null – absolute energies (no referencing).
Integer literal – the corresponding 0-based frame index.

Convert energies to either kcal/mol (default) or Hartree and, when a reference is active, subtract the reference value to produce delta-E.
Build the Plotly figure (strong ticks, spline interpolation, markers, no title) and export it to every requested extension.
Optionally emit a CSV table with columns frame, energy_hartree, and the appropriate delta-E or absolute-E column in the requested unit.

CLI options¶

Option	Description	Default
`-i, --input PATH`	XYZ trajectory whose second line stores energies.	Required
`-o, --out PATH`	Repeatable output filenames; supports `.png`, `.jpg`/`.jpeg`, `.html`, `.svg`, `.pdf`, `.csv`.	`energy.png`
extra arguments	Positional filenames listed after options; merged with the `-o` list.	None
`--unit {kcal,hartree}`	Target unit for the plotted/exported values.	`kcal`
`-r, --reference TEXT`	Reference specification (`init`, `None`, or 0-based integer).	`init`
`-q, --charge INT`	Total charge used for MLIP recomputation. Triggers recomputation when supplied.	None
`-m, --multiplicity INT`	Spin multiplicity (2S+1) used for MLIP recomputation. Triggers recomputation when supplied.	None
`--reverse-x/--no-reverse-x`	Reverse the x-axis so the last frame appears on the left (and `init` becomes the last frame).	`False`

Outputs¶

<output>.[png|jpg|jpeg|html|svg|pdf] # Plotly export for every requested extension (defaults to energy.png)
<output>.csv # Optional energy table when CSV is requested

When no -o or positional outputs are provided, a single energy.png is written to the current directory.
CSV exports include frame, energy_hartree, and either a delta-E column (delta_kcal/delta_hartree) or absolute column (energy_kcal/energy_hartree when no reference is applied).
PNG uses Plotly’s PNG export with scale=2 for higher resolution.

trj2fig¶