kira-energetics

Deterministic, explainable energy-landscape analysis for cellular states in the Kira pipeline.

kira-energetics does not parse expression matrices directly. It consumes upstream Kira outputs, aligns cells, computes energetic coordinates (E_state, P_exit), assigns regimes, estimates escape barriers, and evaluates perturbation response (built-in A2AR plus config-driven scenarios).

Build requirements

• Rust >= 1.95
• Upstream outputs under --deps from:
  • kira-mitoqc
  • kira-riboqc (optional; if absent, ribosome load is treated as neutral 0.0)
  • kira-autolys

Install

Install from crates.io:

cargo install kira-energetics

From source:

cargo build --release

Usage examples

Full deterministic pipeline (stages 0-7):

kira-energetics run \
  --deps ./out \
  --out ./out

Validation only (dependency discovery + schema/alignment checks):

kira-energetics run \
  --deps ./out \
  --out ./out \
  --validate-only

Strict mode (hard-fail on schema/non-finite/alignment issues):

kira-energetics run \
  --deps ./out \
  --out ./out \
  --strict

Custom perturbation config:

kira-energetics run \
  --deps ./out \
  --out ./out \
  --perturb ./perturbations.yaml

Selected perturbations in independent compose mode:

kira-energetics run \
  --deps ./out \
  --out ./out \
  --perturb ./perturbations.yaml \
  --perturb-select a2ar,generic_boost \
  --perturb-compose independent

CLI options

kira-energetics run supports:

• --deps <PATH>: directory with upstream kira-* outputs
• --out <PATH>: output root
• --validate-only: run only stage 0
• --strict: strict validation mode
• --perturb <PATH>: JSON/YAML perturbation config for stage 6
• --perturb-select <name[,name...]>: subset of enabled perturbations
• --perturb-compose <sequential|independent>: perturbation composition mode (default sequential)

Pipeline outputs

Outputs are written to:

• <out>/kira-energetics/

Key artifacts:

• stage0_validate/manifest.json
• stage1_axes/axes.tsv
• stage2_energetics/energetics.tsv
• stage3_regimes/regimes.tsv
• stage4_barriers/barriers.tsv
• stage5_perturb/a2ar.tsv
• stage6_perturb_multi/*.tsv
• stage7_report/baseline_summary.json
• summary.json
• pipeline_step.json

Determinism and contract guarantees

• Stable cell_id alignment across all stages
• Fixed constants and thresholds
• No randomization or ML components
• SIMD backends (AVX2/NEON) with scalar-equivalent formulas
• Fixed TSV float formatting (%.6f)