Fort7 Handler Engine Utility
ReaxFF connectivity (fort.7) file handler.
This module provides a handler for parsing ReaxFF fort.7 files,
which store per-iteration atom connectivity, bond-order information,
and system-wide totals.
Typical use cases include:
- extracting per-atom bond-order features
- computing coordination statistics
- building molecule- and structure-level descriptors
Usage context
- ReaxFF parsing: Read ReaxFF text outputs into normalized tabular structures.
- Workflow ingestion: Provide canonical handler interfaces used by adapters/workflows.
- Diagnostics/export: Preserve parsed metadata for reporting and downstream conversion.
Class: Fort7Handler
Bases: BaseHandler
Parser for ReaxFF connectivity output files (fort.7).
This class parses ReaxFF fort.7 files and exposes both
iteration-level summaries and per-iteration atom connectivity
tables as structured tabular data.
Parsed Data
Summary table
One row per iteration, returned by dataframe(), with columns:
["iter", "num_of_atoms", "num_of_bonds",
"total_BO", "total_LP", "total_BO_uncorrected", "total_charge"]
Per-frame atom tables
Stored in self._frames, one table per iteration, where each
frame is a pandas.DataFrame with columns:
["atom_num", "atom_type_num", "atom_cnn1..nb", "molecule_num",
"BO1..nb", "sum_BOs", "num_LPs", "partial_charge", ...]
Here, ``nb`` denotes the number of bonded neighbors in that frame,
leading to variable-length connectivity and bond-order columns.
Metadata
Returned by metadata(), containing:
["n_frames", "n_records", "simulation_name"]
Notes
- Duplicate iterations are resolved by keeping the last occurrence.
- Connectivity and bond-order columns are inferred from the header.
- Extra, file-dependent columns are preserved as
unknown*fields.
Method: stream_file_frames
Yield fort.7 frames without materializing the trajectory.
The generator retains only the rows and totals for the current iteration. It intentionally bypasses the handler parse/cache path so streaming analysis does not create a second full in-memory copy.
When charges_only is true, rows whose large fixed-width neighbor
ids have fused together are recovered without connectivity: atom id,
atom type, bond-order values, and partial charge remain aligned, while
unavailable neighbor ids are represented by zeros. Total dipole,
polarization, and charge analyses do not consume connectivity.
charge_arrays_only is the low-overhead total-electrostatics path:
it extracts the atom id and partial-charge field from each atom row
without converting the unused connectivity/bond-order fields or
constructing a pandas table.
include_atom_types=False makes that path skip atom-type conversion
as well. Total dipole and polarization calculations need only atom ids,
coordinates, and charges, and skipping the field also avoids ambiguity
when fixed-width neighbor ids above 9999 are concatenated to it.
Method: n_frames
Method: n_atoms
Method: frame
Return a single frame as an atom-level connectivity table.
Works on
Fort7Handler — fort.7
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
i
|
int
|
Frame index to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
Atom-level table for the selected frame, including connectivity and bond-order columns. |
Examples:
>>> h = Fort7Handler("fort.7")
>>> df = h.frame(0)
Method: iter_frames
Iterate over atom-level frames with optional subsampling.
Works on
Fort7Handler — fort.7
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
step
|
int
|
Step size for subsampling frames (default: 1). |
1
|
Yields:
| Type | Description |
|---|---|
DataFrame
|
Atom-level connectivity table for each yielded frame. |
Examples:
>>> h = Fort7Handler("fort.7")
>>> for frame in h.iter_frames(step=10):
... print(len(frame))