Adapter Engine Utility

Adapt AMS KF/RKF content into ReaxKit canonical data models.

This adapter implements AMS-specific extraction from History and molecule sections and maps those arrays/tables into engine-agnostic domain models. It focuses on data loading/writing concerns and delegates analysis behavior to downstream tasks and workflows.

Usage context

• Engine resolution: Registered under "ams" for adapter auto-detection.
• Data ingestion: Produces trajectory/connectivity/simulation and related models.
• Export workflow: Writes canonical trajectory data to XYZ output.

Class: AMSAdapter

Bases: EngineAdapter

Adapter scaffold for AMS KF/RKF-based loading.

Method: detect

Score whether a path appears to be an AMS run input/output location.

Parameters:

Name	Type	Description	Default
path	str | Path	Candidate file or directory path.	required

Returns:

Type	Description
float	Detection score in [0.0, 1.0] where higher means more likely AMS.

Examples:

score = AMSAdapter().detect("reaxout.kf")

Method: clear_runtime_cache

Clear AMS runtime caches used by RKF handler instances.

Returns:

Type	Description
None

Examples:

AMSAdapter.clear_runtime_cache()

Method: required_input_files

Return expected AMS file names for supported domain data types.

Parameters:

Name	Type	Description	Default
data_type	type	Requested canonical data-model class.	required
args	dict	Adapter runtime arguments (unused for this decision).	required

Returns:

Type	Description
tuple[str, ...] | None	Candidate AMS file names, or None when not constrained.

Examples:

files = adapter.required_input_files(TrajectoryData, {})

Method: load_kf

Return a cached AMS KFFile handle for downstream loaders.

Parameters:

Name	Type	Description	Default
args	dict	Adapter arguments containing optional KF/RKF path selectors.	required

Returns:

Type	Description
Any	AMS KFFile object from RKFHandler.

Examples:

kf = adapter.load_kf({"rkf": "reaxout.rkf"})

Method: load_trajectory

Load canonical trajectory data from AMS History%Coordinates.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
TrajectoryData	Frame-major positions, inferred elements, atom IDs, and iterations.

Examples:

traj = AMSAdapter().load_trajectory({"rkf": "reaxout.rkf"})

Method: load_connectivity

Load connectivity and bond-order arrays from AMS history records.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
ConnectivityData	Canonical connectivity payload with per-frame neighbor and bond data.

Examples:

conn = AMSAdapter().load_connectivity({"kf": "reaxout.kf"})

Method: load_simulation

Load simulation-level scalar series from AMS History sections.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
SimulationData	Iterations, energies, thermodynamic series, and cell geometry.

Examples:

sim = AMSAdapter().load_simulation({"rkf": "reaxout.rkf"})

Method: load_partial_energy

Load per-frame AMS partial-energy components from History.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
PartialEnergyData	Matrix of component energies and associated iteration axis.

Examples:

pe = AMSAdapter().load_partial_energy({"rkf": "reaxout.rkf"})

Method: load_charges

Load per-atom charges and framewise total charge from AMS History.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
ChargeData	Charge matrix, summed charge series, and iteration indices.

Examples:

charges = AMSAdapter().load_charges({"kf": "reaxout.kf"})

Method: load_atomic_kinematics

Load latest-frame coordinate/velocity/acceleration tables from AMS.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
AtomicKinematicsData	Snapshot data tables for coordinates, velocities, and accelerations.

Examples:

kin = AMSAdapter().load_atomic_kinematics({"rkf": "reaxout.rkf"})

Method: load_atom_temperature

Load per-atom temperature series from AMS History entries.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
AtomTemperatureData	Temperature matrix indexed by frame and atom.

Examples:

t = AMSAdapter().load_atom_temperature({"rkf": "reaxout.rkf"})

Method: load_atom_strain_energy

Load per-atom strain-energy series from AMS History entries.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
AtomStrainEnergyData	Strain-energy matrix indexed by frame and atom.

Examples:

se = AMSAdapter().load_atom_strain_energy({"kf": "reaxout.kf"})

Method: load_molecular_analysis

Load molecule counts/species tables from AMS molecule sections.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
MolecularAnalysisData	Iteration-indexed totals and molecular species frequency table.

Examples:

mol = AMSAdapter().load_molecular_analysis({"rkf": "reaxout.rkf"})

Method: load_stress

Load per-atom stress tensor series and derived stress variants.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback (phase, done, total, message).	None

Returns:

Type	Description
StressData	Stress tensor arrays and optional averaged/isotropic series.

Examples:

stress = AMSAdapter().load_stress({"rkf": "reaxout.rkf"})

Method: load_connectivity_trajectory

Load connectivity and trajectory together as a composite payload.

Parameters:

Name	Type	Description	Default
args	dict	Adapter options including optional KF/RKF path hints.	required
reporter	callable | None	Progress callback passed through to both loaders.	None

Returns:

Type	Description
ConnectivityTrajectoryData	Combined connectivity and trajectory canonical models.

Examples:

combo = AMSAdapter().load_connectivity_trajectory({"kf": "reaxout.kf"})

Method: write_trajectory

Write canonical trajectory data to an XYZ trajectory file.

Parameters:

Name	Type	Description	Default
data	TrajectoryData	Canonical trajectory payload to serialize.	required
out_path	str | Path	Destination file path for XYZ output.	required
args	dict | None	Optional writer settings. Supports precision (default 6).	None

Returns:

Type	Description
Any	Return value from write_xyz_trajectory.

Examples:

adapter.write_trajectory(traj, "traj.xyz", {"precision": 8})