Models Analysis

Define shared request/result dataclasses for active-site analyzer tasks.

This module centralizes task request and result schemas for active-site structural and event extraction analyzers. It is scoped to typed payload models and does not implement analysis computation.

Usage context

• Task contracts: Provide stable input/output shapes for active-site tasks.
• Serialization support: Keep result payloads consistent for presentation/reporting.
• Cross-module reuse: Share request/result models across structural/event modules.

Request: ActiveSiteStructuralRequest

Request payload for frame-level active-site structural analysis.

Carries frame selection and descriptor configuration for structural active- site characterization, including bonding mode and optional SOAP settings.

Fields

Field	Type	Default	Help	Choices
frame	int	0	Frame index for structural analysis.
bo_threshold	float	0.3	Bond-order threshold used to construct the connectivity graph.
bond_mode	str	bo	Bond graph mode: bo (ConnectivityData.bond_orders) or distance (TRACT-style geometric cutoffs).	bo, distance
bond_scale	float	1.2	Scale factor on covalent radii for distance-based bond detection.
alpha_radius	float	0.0	Alpha-shape radius for non-periodic boundary detection; <=0 disables alpha-shape.
gap_deg	float	220.0	Angular-gap threshold used in boundary detection fallback.
carbon_element	str	C	Element symbol used for carbon network analysis.
include_noncarbon	bool	True	Include non-carbon atoms in the output table.	True, False
strict_tract	bool	False	Raise when canonical structural fields are too incomplete for TRACT compatibility.	True, False
soap	bool	False	Compute optional SOAP descriptors for carbon atoms.	True, False
soap_ref_path	Optional[str]		Optional .npy path of reactive-site SOAP vectors used for soap_score.
soap_r_cut	float	5.0	SOAP cutoff radius in angstrom.
soap_n_max	int	9	SOAP radial basis size.
soap_l_max	int	9	SOAP angular basis size.
soap_zeta	int	2	Exponent used for SOAP kernel similarity scoring when reference vectors are provided.

Examples

req = ActiveSiteStructuralRequest(
    frame=0,
    bond_mode="bo",
    bo_threshold=0.3,
    soap=False,
)

Sample output: ActiveSiteStructuralRequest(...) Meaning: The request configures one-frame structural descriptor extraction.

Result: ActiveSiteStructuralResult

Result payload for frame-level active-site structural analysis.

Stores raw structural descriptors, TRACT-compatible projection, summary statistics, and optional SOAP descriptor matrix.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
tract_table	pd.DataFrame
summary	dict[str, Any]
request	ActiveSiteStructuralRequest
soap_descriptors	Optional[np.ndarray]

Examples

result = ActiveSiteStructuralResult(table=df, tract_table=tract_df, summary={}, request=req)

Sample output: ActiveSiteStructuralResult(...) Meaning: The result packages detailed and report-ready structural outputs.

Request: ActiveSiteEventsRequest

Request payload for trajectory-level active-site event extraction.

Configures frame sampling, detection mode, species definitions, and event persistence criteria for extracting C-O and C-Si event summaries.

Fields

Field	Type	Default	Help	Choices
frames	Optional[Sequence[int]]		Optional frame indices to evaluate.
every	int	10	Frame stride for selected frames.
mode	str	auto	Event mode: auto | bo | dist.	auto, bo, dist
bo_threshold	float	0.8	Bond-order threshold for event detection in bo mode.
r_CO	float	1.65	C-O cutoff in angstrom for distance mode.
r_CSi	float	2.1	C-Si cutoff in angstrom for distance mode.
persist	int	50	Required consecutive analyzed frames for confirmed binding.
carbon_element	str	C	Element symbol used as reactive substrate atom type.
oxygen_element	str	O	Element symbol treated as oxygen target.
silicon_element	str	Si	Element symbol treated as silicon target.
strict_tract	bool	False	Raise when canonical events fields are too incomplete for TRACT compatibility.	True, False

Examples

req = ActiveSiteEventsRequest(mode="auto", every=10, persist=50)

Sample output: ActiveSiteEventsRequest(...) Meaning: The request controls trajectory windowing and event confirmation logic.

Result: ActiveSiteEventsResult

Result payload for trajectory-level active-site event extraction.

Stores per-carbon event descriptors, TRACT-compatible table projection, and run-level event summary metadata.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
tract_table	pd.DataFrame
summary	dict[str, Any]
request	ActiveSiteEventsRequest

Examples

result = ActiveSiteEventsResult(table=df, tract_table=tract_df, summary={}, request=req)

Sample output: ActiveSiteEventsResult(...) Meaning: The result bundles event rows and summary/report metadata.

Request: ActiveSiteEventDiagnosticsRequest

Request payload for active-site event cutoff diagnostics.

Samples trajectory frames to characterize nearest C-O and C-Si distance distributions before full event extraction. The diagnostic helps choose r_CO, r_CSi, and persistence thresholds for distance-mode runs.

Fields

Field	Type	Default	Help	Choices
frames	Optional[Sequence[int]]		Optional frame indices to sample. Empty means all frames.
every	int	10	Frame stride for diagnostic sampling.
r_probe	float	2.5	Generous C-X distance cutoff used to detect close-approach episodes.
max_diag_frames	int	500	Maximum number of sampled frames to analyze.
timestep_fs	float	10.0	Raw trajectory timestep used to convert episode lengths to ps.
carbon_element	str	C	Element symbol used as reactive substrate atom type.
oxygen_element	str	O	Element symbol treated as oxygen target.
silicon_element	str	Si	Element symbol treated as silicon target.

Result: ActiveSiteEventDiagnosticsResult

Result payload for active-site event cutoff diagnostics.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
distance_table	pd.DataFrame
episode_table	pd.DataFrame
summary	dict[str, Any]
request	ActiveSiteEventDiagnosticsRequest