Command-Line Interface

symmetrix version [--json] [--probe] [--metadata-only] reports the imported frontend location and the source commit, source-content SHA-256, native-source SHA-256, and dirty state recorded in every installed backend descriptor. It reads descriptors without loading a native extension, so it can identify a stale virtual environment even when the backend cannot initialize on the current host. An unknown identity means that artifact was built without the provenance metadata; it is not evidence that the artifact matches the current worktree. The command probes the selected native backend by default, including its compiled code identity, extension path, linked runtime/BLAS libraries, and Kokkos/device runtime details. If probing fails, it reports the error and falls back to metadata-only inspection. Use --metadata-only to skip native loading; --probe is retained as an explicit spelling of the default behavior.

symmetrix backend list [--json] reports installed descriptors and their usability without loading an extension. symmetrix backend show [selector] [--json] [--probe] resolves the automatic or explicit selection; an incompatible accelerator selector is an error rather than a usability report. With --probe, the selected extension is loaded and CPU backends report the same OpenBLAS configuration and threading fields as symmetrix doctor. symmetrix backend install --arch SELECTOR downloads and installs a published backend wheel into the current Python environment. --arch defaults to auto, which requires exactly one visible GPU architecture and infers the CUDA or ROCm major version. If uv is available it is used; otherwise the command invokes python -m pip. Use an explicit selector such as cuda13-sm120 on headless or multi-GPU systems. The command prints the resolution details, including detected architecture, toolkit version and source, selected package, and Python environment. When the detected CUDA-major wheel is unavailable, automatic mode probes and falls back to the CUDA 12 wheel for the same architecture. Explicit selectors remain strict. On CPU-only hosts, automatic mode reports that the bundled CPU backend needs no download. If no pre-compiled wheel resolves, it reports the attempted selectors and a source-build command. symmetrix doctor [--json] [--advisory] prints runtime diagnostics; --json provides the machine-readable variant for deployment checks.

symmetrix bench runs the maintained SrTiO3 MACE-OMAT-0 benchmark and reports steady-state performance in microseconds per atom. Its options select the model, backend, precision, execution profile, system size, neighbor skin, thread count, sampling protocol, and optional MACE-Torch correctness check. On Apple silicon, --metal runs the GPU stages on the Metal backend and reports the device and the stages it executes.

Artifact preparation commands are exposed as symmetrix_prepare_jit_host_artifact and symmetrix_prepare_jit_device_artifact. The converter is symmetrix_extract_mace --model MODEL [--output PATH]; it accepts species, head, compact/pair-spline format, and device-artifact preparation options and requires the optional symmetrix-xl[mace] dependencies. Omitting the species options creates the preferred universal compact export. Explicit species selection is limited to restricted format-v2 exports or the original Symmetrix pair-spline format (named v1 here); format-v3 nonlinear models always retain the complete checkpoint domain. symmetrix_calibrate_kernel_launch explicitly calibrates bounded GPU launch profiles for a model and structure; normal kernel_launch_policy="automatic" execution consumes a compatible calibration record but does not benchmark.