Skip to content

Geo Handler Engine Utility

ReaxFF geometry structure (geo) file handler.

This module provides a handler for parsing ReaxFF .geo structure files in XTLGRF format, which define atomic coordinates, optional periodic cell parameters, and descriptive metadata for a system.

Typical use cases include:

  • loading initial or relaxed geometries
  • extracting atomic coordinates for analysis or visualization
  • accessing unit cell parameters for periodic systems

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: GeoHandler

Bases: BaseHandler

Parser for ReaxFF geometry structure files (.geo / XTLGRF format).

This class parses .geo files and exposes atomic coordinates and associated structural metadata as structured Python objects.

Parsed Data

Atom table One row per atom, returned by dataframe(), with columns: ["atom_id", "atom_type", "x", "y", "z"]

Connectivity table One row per declared CONECT edge, returned by connectivity(), with columns: ["source_atom_id", "target_atom_id"]

Metadata Returned by metadata(), containing: { "descriptor": str | None, # from DESCRP line "remark": str | None, # concatenated REMARK lines "cell_lengths": { # from CRYSTX (a, b, c) "a": float, "b": float, "c": float, } | None, "cell_angles": { # from CRYSTX (alpha, beta, gamma) "alpha": float, "beta": float, "gamma": float, } | None, "n_atoms": int, }

Notes
  • Only ATOM and HETATM records are parsed into the atom table.
  • CONECT records (after FORMAT CONECT) are parsed into a separate connectivity table.
  • Cell parameters are optional and may be absent for non-periodic systems.
  • Non-structural lines (e.g. XTLGRF, FORMAT) are ignored.
  • This handler is not frame-based; the file represents a single structure.

Method: n_atoms

N atoms.

Returns:

Type Description
int

Return value description.

Method: cell

Return a flat dict with cell parameters:

{
    "a": ...,
    "b": ...,
    "c": ...,
    "alpha": ...,
    "beta": ...,
    "gamma": ...,
}

Values may be None if CRYSTX was missing or malformed.

Method: coordinates

Return a copy of the atom table (id, type, x, y, z).

This is just a convenience wrapper around .dataframe() to make the intent explicit.

Method: connectivity

Return a copy of the parsed CONECT edge table.

Returns:

Type Description
DataFrame

Columns: - source_atom_id - target_atom_id