Kinematics Workflow

Direct command workflow for atomic-kinematics 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_kinematics

Extract kinematics datasets from atomic kinematics files. This command can return metadata, coordinates, velocities, accelerations, or previous accelerations, optionally filtered to selected atoms.

Examples

---

  1. Export selected-atom velocities:
   reaxkit get_kinematics --key velocities --atoms 1 3 7 --export velocities.csv

  2. Read metadata from a specific kinematics file:
   reaxkit get_kinematics --key metadata --vels moldyn.vel

  3. Plot accelerations using subplot layout:
   reaxkit get_kinematics --key accelerations --plot subplot --save accelerations.png

Arguments

Flag	Required	Default	Help	Choices
--plot	No		Render a plot. Example: --plot subplot, which creates one panel per value column.	single, subplot
--show	No		Show the generated plot window. Example: --show, which opens the figure interactively.
--save	No		Save the generated plot to a file path. Example: --save accelerations.png, which writes the figure image.
--export	No		Write the result table to CSV. Example: --export velocities.csv, which saves tabular output.
--grid	No		Subplot grid like 2x2 or 2*2. Example: --grid 2x2, which arranges subplot panels in a 2-by-2 layout.
--xaxis	No	atom_index	Quantity on x-axis. Example: --xaxis atom_index, which uses atom index for horizontal axis.	atom_index
--key	Yes		Requested kinematics dataset. Example: --key velocities, which returns velocity components by atom.
--atoms	No		1-based atom ids. Example: --atoms 1 3 7, which limits output rows to those atoms.

Command: kinematics_plot3d

Arguments

No command-specific arguments found.

Command: kinematics_heatmap2d

Arguments

No command-specific arguments found.

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		Engine override. Example: --engine reaxff, which forces ReaxFF parsing behavior.	reaxff, ams, lammps
--input	No	.	Input file or directory for engine resolution. Example: --input runs/job1, which sets lookup context for required files.
--run-dir, --dir	No	.	Run directory fallback for engine detection. Example: --run-dir runs/job1, which serves as backup path context.
--vels, --file	No	vels	Atomic kinematics file path. Example: --vels moldyn.vel, which reads kinematics data from that file.
--log	No		Logging level. Example: --log verbose, which prints more runtime details.	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.