Fort7 Analyzer Analysis

fort.7 analysis utilities.

This module provides functions for extracting atom-level and iteration-level features from a parsed ReaxFF fort.7 file, as well as higher-level coordination analysis when combined with xmolout.

Typical use cases include:

extracting per-atom quantities such as partial charges or bond-order sums
extracting per-iteration (summary) quantities from the simulation table
classifying atomic coordination (under / proper / over) across frames

`get_all_atoms_cnn_conv_fnc(handler, frames=None, iterations=None)`

Convenience function to extract all atom_cnn* connectivity columns across selected frames.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
`handler`	`Fort7Handler`	Parsed `fort.7` handler.	required
`frames`	`Indexish`	Frame indices or iteration numbers to include.	`None`
`iterations`	`Indexish`	Frame indices or iteration numbers to include.	`None`

Returns:

Type	Description
`DataFrame`	Per-atom connectivity values with frame and atom indices.

Examples:

>>> df = get_all_atoms_cnn_conv_fnc(f7)

`get_fort7_data_per_atom(handler, columns, frames=None, iterations=None, regex=False, add_index_cols=True)`

Extract per-atom feature columns across selected frames.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
`handler`	`Fort7Handler`	Parsed `fort.7` handler.	required
`columns`	`str or sequence of str`	Atom-level column name(s) to extract (e.g. `partial_charge`, `sum_BOs`). Regex patterns are allowed if `regex=True`.	required
`frames`	`int or iterable of int`	Frame indices to include.	`None`
`iterations`	`int or iterable of int`	Iteration numbers to include.	`None`
`regex`	`bool`	Whether `columns` should be interpreted as regular expressions.	`False`
`add_index_cols`	`bool`	If True, include `frame_idx`, `iter`, and `atom_idx` columns.	`True`

Returns:

Type	Description
`DataFrame`	Tidy table with one row per atom per frame, including requested feature columns and index metadata.

Examples:

>>> df = get_fort7_data_per_atom(f7, "partial_charge", frames=0)
>>> df = get_fort7_data_per_atom(f7, r"^atom_cnn\d+$", regex=True)

`get_fort7_data_summaries(handler, columns, frames=None, iterations=None, regex=False, add_index_cols=True)`

Extract per-iteration (summary) feature columns from a fort.7 file.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
`handler`	`Fort7Handler`	Parsed `fort.7` handler.	required
`columns`	`str or sequence of str`	Summary-level column name(s) to extract.	required
`frames`	`int or iterable of int`	Frame indices to include.	`None`
`iterations`	`int or iterable of int`	Iteration numbers to include.	`None`
`regex`	`bool`	Whether `columns` should be interpreted as regular expressions.	`False`
`add_index_cols`	`bool`	If True, include `frame_idx` and `iter` columns.	`True`

Returns:

Type	Description
`DataFrame`	Table with one row per selected frame containing summary quantities.

Examples:

>>> df = get_fort7_data_summaries(f7, ["num_bonds", "total_BO"])
>>> df = get_fort7_data_summaries(f7, r"^total_.*$", regex=True)

`get_partial_charges_conv_fnc(handler, frames=None, iterations=None)`

Convenience function to extract per-atom partial charges across selected frames.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
`handler`	`Fort7Handler`	Parsed `fort.7` handler.	required
`frames`	`Indexish`	Frame indices or iteration numbers to include.	`None`
`iterations`	`Indexish`	Frame indices or iteration numbers to include.	`None`

Returns:

Type	Description
`DataFrame`	Per-atom partial charges with frame and atom indices.

Examples:

>>> df = get_partial_charges_conv_fnc(f7, frames=0)

`get_sum_bos_conv_fnc(handler, frames=None, iterations=None)`

Convenience function to extract per-atom total bond order (sum_BOs) across selected frames.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
`handler`	`Fort7Handler`	Parsed `fort.7` handler.	required
`frames`	`Indexish`	Frame indices or iteration numbers to include.	`None`
`iterations`	`Indexish`	Frame indices or iteration numbers to include.	`None`

Returns:

Type	Description
`DataFrame`	Tidy table with columns: `frame_idx`, `iter`, `atom_idx`, and `sum_BOs`.

Examples:

>>> df = get_sum_bos_conv_fnc(f7)

`per_atom_coordination_status_over_frames(f7_handler, xh, *, valences, threshold=0.9, frames=None, iterations=None, require_all_valences=True)`

Classify atomic coordination status across frames using bond-order sums.

Works on

Fort7Handler + XmoloutHandler — fort.7 + xmolout

Parameters:

Name	Type	Description	Default
`f7_handler`	`Fort7Handler`	Parsed `fort.7` handler providing bond-order information.	required
`xh`	`XmoloutHandler`	Parsed `xmolout` handler providing atom types per frame.	required
`valences`	`mapping of str to float`	Reference valence values for each atom type.	required
`threshold`	`float`	Tolerance window for under/over-coordination classification.	`0.9`
`frames`	`Indexish`	Frame indices or iteration numbers to include.	`None`
`iterations`	`Indexish`	Frame indices or iteration numbers to include.	`None`
`require_all_valences`	`bool`	If True, raise an error when a valence is missing for any atom type.	`True`

Returns:

Type	Description
`DataFrame`	One row per atom per frame with columns including: `frame_index`, `iter`, `atom_id`, `atom_type`, `sum_BOs`, `valence`, `delta`, `status`, `status_label`.

Examples:

>>> df = per_atom_coordination_status_over_frames(
...     f7, xh, valences={"C": 4.0, "H": 1.0}
... )