Base Engine Utility

Base file-handler abstraction for ReaxKit.

This module defines the abstract FileHandler class, which provides the common interface and lifecycle used by all ReaxKit file handlers (e.g., XmoloutHandler, Fort7Handler, SummaryHandler).

The base class standardizes how ReaxFF output files are:

• loaded from disk
• parsed lazily into structured tabular data
• exposed via a uniform DataFrame-based API
• accompanied by lightweight metadata

All ReaxKit analysis functions rely on FileHandler subclasses to provide a consistent, predictable view of parsed ReaxFF files.

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

Bases: ABC

Abstract base class for ReaxKit file handlers.

This class defines the minimal public interface that all ReaxKit file handlers must implement. Subclasses are responsible for parsing a specific ReaxFF file format and exposing its contents as structured pandas DataFrames.

Parsed Data

Main table A pandas.DataFrame returned by dataframe(), whose columns depend on the specific file type.

Metadata A dictionary of lightweight metadata returned by metadata(), typically including global or per-file attributes.

Notes

• Parsing is performed lazily and cached after the first access.
• Parsed payloads are also cached across handler instances using: 1) an in-process memory cache 2) an on-disk cache
• Subclasses must implement the private _parse() method.

Method: parse

Parse the file contents into structured data.

Works on

FileHandler — ReaxFF output file

Returns:

Type	Description
None	Parses the file and caches the resulting DataFrame and metadata.

Examples:

>>> h = SomeHandler("file")
>>> h.parse()

Method: dataframe

Return the parsed file contents as a pandas DataFrame.

Works on

FileHandler — ReaxFF output file

Returns:

Type	Description
DataFrame	Structured table representing the parsed file contents.

Examples:

>>> h = SomeHandler("file")
>>> df = h.dataframe()

Method: metadata

Return parsed metadata associated with the file.

Works on

FileHandler — ReaxFF output file

Returns:

Type	Description
dict	Dictionary of metadata values extracted during parsing.

Examples:

>>> h = SomeHandler("file")
>>> meta = h.metadata()

Method: clear_runtime_cache

Clear runtime cache.

Returns:

Type	Description
None	Return value.

Examples:

# Example
clear_runtime_cache(...)