Active Site Workflow

Direct command workflow for active-site analyses.

This module implements CLI workflow orchestration for its command family, including argument parsing, request construction, execution dispatch, and result presentation handoff.

Usage context

• Command routing: Resolve CLI aliases and normalized command names.
• Task execution: Build request objects and invoke registered tasks.
• Output handling: Forward results to table, plot, export, or report flows.

Command: get_active_site_structural

Compute per-atom active-site structural descriptors on a selected frame. Use this command when you need atom-resolved structural labels and geometry metrics around active sites from connectivity trajectory data. This command analyzes prepared analysis inputs and does not run a simulation.

Examples

---

  1. Baseline structural analysis on frame 0:
   reaxkit get_active_site_structural --frame 0 --bo-threshold 0.3

  2. Strict carbon-focused analysis on a later frame:
   reaxkit get_active_site_structural --frame 100 --no-include-noncarbon --strict-tract

  3. Render and save a structural plot:
   reaxkit get_active_site_structural --plot single --save active_site_structural.png

Arguments

Flag	Required	Default	Help	Choices
--frame	No	0	Frame index used for structural analysis. Example: --frame 100, which runs the descriptor extraction on frame 100.
--bo-threshold	No	0.3	Bond-order threshold used to build connectivity. Example: --bo-threshold 0.4, which requires stronger bonds to count as connected.
--bond-mode	No	bo	Bond graph source: bo (from ConnectivityData.bond_orders) or distance (TRACT geometric cutoffs)	bo, distance
--bond-scale	No	1.2	Scale factor on covalent radii for distance mode
--alpha-radius	No	0.0	Alpha-shape radius for non-periodic boundary detection
--gap-deg	No	220.0	Angular-gap threshold for boundary fallback
--carbon-element	No	C	Element symbol used for carbon network analysis
--include-noncarbon	No	True	Include non-carbon atoms in output table
--strict-tract	No	False	Raise if canonical structural output cannot satisfy strict TRACT compatibility
--soap	No	False	Compute optional SOAP descriptors (soap_pc1/2/3 and optional soap_score).
--soap-ref-path	No		Optional .npy reference SOAP vectors for soap_score.
--soap-r-cut	No	5.0	SOAP cutoff radius in angstrom.
--soap-n-max	No	9	SOAP radial basis size.
--soap-l-max	No	9	SOAP angular basis size.
--soap-zeta	No	2	SOAP kernel exponent for reference similarity.

1. A spatial x-y active-site map where atoms are colored by absolute pyramidalization |d_pyr|, with under-coordinated atoms highlighted as red stars.

Figure: Spatial map of pyramidalization with under-coordinated atoms highlighted.

1. A spatial x-y map from active_site_structural showing each atom colored by its assigned active-site label, such as basal, defect, edge_armchair, or edge_zigzag.

Figure: Spatial map of active-site labels.

1. A spatial x-y map from active_site_structural showing atoms colored by detected grain_id regions from psi6 orientation-based region growing.

Figure: Spatial map of grain IDs from psi6 region-growing.

1. A histogram from active_site_structural comparing the |d_pyr| pyramidalization distribution by site label, with the tau_opt = 0.229 Å threshold marked.

Figure: Distribution of pyramidalization by site label.

Command: get_active_site_events

Extract persistent active-site C-O and C-Si events across trajectory frames. Use this command to detect bond-forming or bond-breaking event patterns over time from connectivity-aware data. Use --diagnose first to sample C-X distance distributions and choose distance cutoffs. This command analyzes existing data and does not generate force-field input templates.

Examples

---

  0. Diagnose distance cutoffs before full extraction:
   reaxkit get_active_site_events --diagnose --r-probe 2.5 --max-diag-frames 500

  1. Automatic mode for persistent events:
   reaxkit get_active_site_events --mode auto --persist 5

  2. Bond-order mode on a sampled frame range:
   reaxkit get_active_site_events --frames 0:500:5 --mode bo --bo-threshold 0.8

  3. Distance mode with custom cutoffs:
     reaxkit get_active_site_events --input 30_1073_ams.rkf --r-co 1.65 --persist 50 --every 10     reaxkit get_active_site_events --mode dist --r-co 1.65 --r-csi 2.10 --strict-tract

Arguments

Flag	Required	Default	Help	Choices
--frames	No		Frames: "0,10,20", "0 10 20", "0:20", "0-20", or "0:20:2"
--every, --stride	No	10	Use every Nth selected frame (TRACT alias: --stride; default: 10)
--mode	No	auto	Event detection mode	auto, bo, dist
--bo-threshold, --bo_threshold	No	0.8	Bond-order threshold for bo mode
--r-co, --r_CO	No	1.65	C-O distance cutoff in angstrom for dist mode
--r-csi, --r_CSi	No	2.1	C-Si distance cutoff in angstrom for dist mode
--persist	No	50	Required consecutive analyzed frames for confirmed binding
--diagnose	No		Sample C-X distance and episode distributions to choose --r-co/--r-csi and --persist before full extraction
--r-probe	No	2.5	Generous C-X cutoff in angstrom used for diagnostic close-approach episodes
--max-diag-frames	No	500	Maximum sampled frames for --diagnose
--timestep-fs	No	10.0	Raw trajectory timestep in fs used to report diagnostic episode durations
--carbon-element	No	C	Carbon element symbol
--oxygen-element	No	O	Oxygen element symbol
--silicon-element	No	Si	Silicon element symbol
--strict-tract	No	False	Raise if canonical events output cannot satisfy strict TRACT compatibility

Common Runtime and Presentation Arguments

These are shared workflow-level CLI flags added before command-specific options, covering runtime context (engine/input/storage) and output presentation/export behavior.

Flag	Required	Default	Help	Choices
--engine	No			reaxff, ams, lammps
--input	No	.	Input file or directory for engine resolution
--run-dir, --dir	No	.	Run directory fallback for engine detection
--fort7	No	fort.7	Path to fort.7
--xmolout	No	xmolout	Path to xmolout
--summary	No		Optional summary.txt path
--log	No		Logging level	verbose, quiet
--run-id	No		Run identifier for run-scoped layout (e.g., run_91ac0e).
--project-root	No		Project root that contains inputs/, data/, analysis/, etc.
--analysis-id	No		Optional analysis artifact id; defaults to run id.
--plot	No		Render a plot	single, subplot
--show	No		Show the generated plot window
--save	No		Save the generated plot to a file path
--export	No		Write the result table to CSV
--grid	No		Subplot grid like 2x2 or 2*2
--report	No	False	Generate a report under reports///
--report-format	No	both	Report format when --report is enabled.	both, pdf, docx