Loaders Dynamics Engine Utility

Dynamic-trajectory and geometry loaders for the ReaxFF adapter.

This module groups load routines that operate on trajectory-like time evolution and geometry/connectivity assembly for ReaxFF outputs.

Usage context

• Trajectory ingest: Load xmolout-driven trajectory/simulation data.
• Geometry ingest: Load initial/final geometry records and metadata.
• Connectivity ingest: Load fort.7 connectivity and merged trajectory bundles.

Function: load_trajectory

Load trajectory data for ReaxFF runs.

Resolves the trajectory source (typically xmolout), builds the corresponding handler, and normalizes it into TrajectoryData. Simulation metadata from summary.txt is merged when available.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance used to resolve paths and construct handlers.	required
args	dict	Loader arguments, including optional path overrides.	required
reporter	Any	Optional reporter passed to handler constructors.	None

Returns:

Type	Description
TrajectoryData	Normalized trajectory data with merged simulation metadata when present.

Examples:

>>> data = adapter.load_trajectory({"xmolout": "run/xmolout"})

Function: load_geometry

Load initial geometry data for ReaxFF runs.

Resolves an initial-geometry source and parses it through GeoHandler. When geometry_role="final" or a final-geometry file is provided, this delegates to load_final_geometry.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance used for path resolution and handler lifecycle.	required
args	dict	Loader arguments with optional geo, geometry, or input.	required
reporter	Any	Optional reporter passed to handler constructors.	None

Returns:

Type	Description
GeometryData	Normalized initial-geometry record (or final geometry when delegated).

Examples:

>>> geom = adapter.load_geometry({"geo": "run/geo"})

Function: load_final_geometry

Load final (optimized) geometry data for ReaxFF runs.

Resolves a final-geometry source and parses it through GeoHandler. If the ReaxFF engine is used, then this file would usually be fort.90.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance used for path resolution and handler lifecycle.	required
args	dict	Loader arguments with optional final_geometry, fort90, or input.	required
reporter	Any	Optional reporter passed to handler constructors.	None

Returns:

Type	Description
GeometryData	Normalized final-geometry record.

Examples:

>>> final_geom = adapter.load_final_geometry({"final_geometry": "run/fort.90"})

Function: load_simulation

Load merged simulation metadata for ReaxFF runs.

Attempts to load simulation metadata from trajectory and summary sources, then merges both records. Raises when neither source is available.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance that provides simulation sub-loaders.	required
args	dict	Loader arguments containing optional trajectory/summary paths.	required
reporter	Any	Optional reporter passed to underlying handlers.	None

Returns:

Type	Description
SimulationData	Merged simulation metadata.

Examples:

>>> sim = adapter.load_simulation({"run_dir": "run"})

Function: load_connectivity

Load connectivity matrices and merged simulation metadata.

Resolves connectivity input and parses it via Fort7Handler, then merges simulation metadata from trajectory/summary sources into the returned model. If the ReaxFF engine is used, then the connectivity file would usually be fort.7.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance used to resolve paths and build handlers.	required
args	dict	Loader arguments with optional fort7, connectivity, or input.	required
reporter	Any	Optional reporter passed to handler constructors.	None

Returns:

Type	Description
ConnectivityData	Connectivity record with simulation-derived atom metadata when present.

Examples:

>>> conn = adapter.load_connectivity({"fort7": "run/fort.7"})

Function: load_coordination_status_bundle

Load a coordination-status bundle from connectivity and force-field data.

Composes a bundle by invoking connectivity and force-field loaders and packaging their normalized outputs into one data model.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance that exposes dependent load methods.	required
args	dict	Loader arguments forwarded to dependent loaders.	required
reporter	Any	Optional reporter forwarded to dependent loaders.	None

Returns:

Type	Description
CoordinationStatusBundleData	Bundle containing connectivity and force-field parameter records.

Examples:

>>> bundle = adapter.load_coordination_status_bundle({"run_dir": "run"})

Function: load_connectivity_trajectory

Load combined connectivity and trajectory data.

Builds connectivity and trajectory handlers, optionally includes summary simulation metadata and force-field parameters, then constructs a unified ConnectivityTrajectoryData object. If the ReaxFF engine is used, then the inputs would usually be fort.7 and xmolout.

Parameters:

Name	Type	Description	Default
adapter	ReaxFFAdapter	Adapter instance used for path resolution and handler construction.	required
args	dict	Loader arguments with optional connectivity/trajectory path overrides.	required
reporter	Any	Optional reporter passed to handler constructors.	None

Returns:

Type	Description
ConnectivityTrajectoryData	Combined connectivity and trajectory dataset with optional supplements.

Examples:

>>> ctd = adapter.load_connectivity_trajectory({"run_dir": "run"})