Crate dsfb_robotics

Expand description

§dsfb-robotics — DSFB Structural Semiotics Engine for Robotics Health Monitoring

What this crate is, in one paragraph. A deterministic, no_std, no_alloc, zero-unsafe observer that reads residual streams — joint torque identification residuals, inverse-dynamics residuals, whole-body MPC force residuals, centroidal-momentum observer residuals, bearing envelope-spectrum residuals, health-index trajectories — which existing robot control and prognostics pipelines already compute, and structures them into a typed grammar of human-readable episodes. DSFB does not replace inverse-dynamics identification, Kalman / Luenberger observers, whole-body controllers, MPC, rainflow RUL estimators, or vibration-based FDD classifiers — it augments them by giving operators a structural view of what those systems discard. Removing DSFB leaves the upstream control and prognostics stack unchanged.

Invariant Forge LLC — Prior art under 35 U.S.C. § 102. Commercial deployment requires a separate written license. Reference implementation: Apache-2.0. licensing@invariantforge.net

§Positioning — Augmentation, not competition

DSFB does not compete with existing robotics sensing, kinematic identification, whole-body balance control, or PHM methods. Existing methods will continue to outperform DSFB at their own tasks — earlier fault detection, lower false-alarm rates, better RUL accuracy, tighter tracking control. DSFB’s role is orthogonal: it reads the residuals those methods already produce and usually discard, and structures them into a human-readable grammar (Admissible / Boundary / Violation) with typed episodes and provenance-tagged audit trails.

This makes existing methods more important, not less — DSFB is literally dependent on a functioning upstream observer chain to have anything to interpret.

§Architectural Contract

Observer-only. Public API accepts &[f64] (immutable reference only). There is no mutable write path into any upstream data structure. Enforced by type signature.
#![no_std]. Core modules link against neither the Rust standard library nor any OS runtime. Deployable on bare-metal MCUs (Cortex-M4F, RISC-V 32-bit) alongside a safety-gate companion to an industrial robot controller.
no_alloc in core. All internal structures use fixed-capacity array-backed types. The canonical observe signature takes a caller-supplied &mut [Episode] output buffer. No heap allocation in any hot path of the default build.
Zero unsafe. No unsafe blocks, no UnsafeCell, no RefCell in any observer code path. Enforced at compile time by #![forbid(unsafe_code)] below.

§Non-Claims (from companion paper §11)

This crate does not provide:

Fault classification (bearing fault type, root-cause identification)
Calibrated Pd/Pfa or F1/ROC-AUC guarantees
Earlier detection than incumbent threshold alarms, RMS monitors, or CUSUM/EWMA change-point detectors
Hard real-time latency bounds under specific controller platforms
RUL (remaining useful life) prediction
ISO 10218-1/-2:2025 or IEC 61508 certification
A replacement for any upstream observer, estimator, or controller

§Feature Flags

Feature	Description
(none)	Core engine: `no_std` + `no_alloc` + zero unsafe
`alloc`	Opt-in heap via `alloc` crate for host-side convenience wrappers
`std`	Opt-in std library for pipeline and output modules
`serde`	JSON artefact serialization (requires `std`)
`paper_lock`	Headline-metric enforcement for deterministic reproducibility
`real_figures`	Real-dataset figure bank for the companion paper (requires `std`)
`experimental`	Exploratory extensions not validated in the companion paper

§Minimal usage (bare-metal, `no_std` + `no_alloc`)

use dsfb_robotics::{Episode, observe};
let residuals: &[f64] = &[0.01, 0.02, 0.05, 0.12, 0.21];
let mut out = [Episode::empty(); 16];
let n = observe(residuals, &mut out);
for e in &out[..n] {
    // advisory only — no write-back, no upstream coupling
    let _ = (e.index, e.grammar, e.decision);
}

§Streaming engine usage (per-observation API)

use dsfb_robotics::engine::DsfbRoboticsEngine;
use dsfb_robotics::platform::RobotContext;

// W=8 drift window, K=4 persistence threshold
let mut eng = DsfbRoboticsEngine::<8, 4>::new(0.1);

let residual_norm: f64 = 0.045; // ‖r(k)‖ from your upstream observer
let ep = eng.observe_one(residual_norm, false, RobotContext::ArmOperating, 0);
let _ = (ep.grammar, ep.decision);
// upstream robot controller: UNCHANGED

Re-exports§

pub use crate::engine::DsfbRoboticsEngine;
pub use crate::envelope::AdmissibilityEnvelope;
pub use crate::episode::Episode;
pub use crate::grammar::GrammarState;
pub use crate::grammar::ReasonCode;
pub use crate::platform::RobotContext;
pub use crate::policy::PolicyDecision;
pub use crate::sign::SignTuple;
pub use crate::sign::SignWindow;

Modules§

balancing: Shared residual helper for balancing datasets. Shared residual helper for balancing datasets (MIT Cheetah 3 / Mini-Cheetah, IIT iCub push-recovery).
calibration: Healthy-window envelope calibration. Healthy-window calibration.
datasets: Per-dataset residual adapters across PHM (CWRU, IMS, FEMTO-ST), kinematics (KUKA LWR-IV+, Franka Panda Gaz, DLR-class Giacomuzzo, UR10 Polydoros), and balancing (MIT Mini-Cheetah, iCub push-recovery, ANYmal, Unitree G1, ergoCub Sorrentino, plus the LeRobot ALOHA / Mobile-ALOHA / SO-100 / DROID / OpenX teleoperation slates). See datasets::DatasetId for the canonical slug enumeration. Per-dataset residual adapters.
engine: Streaming DSFB engine orchestrator. See engine::DsfbRoboticsEngine and grammar::GrammarEvaluator for the canonical per-sample pipeline. DsfbRoboticsEngine — the streaming orchestrator that composes crate::sign::SignWindow, crate::grammar::GrammarEvaluator, and crate::envelope::AdmissibilityEnvelope into a no_std + no_alloc observer suitable for bare-metal MCU deployment alongside a safety-rated controller.
envelope: Admissibility envelope E(k) = {r : ‖r‖ ≤ ρ(k)}. Admissibility envelope E(k) = { r ∈ ℝⁿ : ‖r‖ ≤ ρ(k) }.
episode: Canonical Episode struct emitted by the observer. Canonical Episode struct — the DSFB observer’s advisory output.
grammar: Grammar FSM: Admissible | Boundary[ReasonCode] | Violation. Grammar FSM: Admissible | Boundary[ReasonCode] | Violation.
heuristics: Heuristics bank: typed robotics motifs. Heuristics bank — typed motif library for robotics-specific structural patterns.
kinematics: Shared residual helper for kinematic-identification datasets. Shared residual helper for kinematic-identification datasets (KUKA LWR, Franka Panda, DLR Rollin’ Justin / LWR-III, UR10).
math: libm-free f64 helpers for no_std + no_alloc core. libm-free f64 helpers for the no_std + no_alloc core.
platform: Robot operating context: commissioning, operating, stance, swing, maintenance. Robot operating context for envelope scaling and violation suppression.
policy: Advisory policy layer: grammar → decision. Advisory policy layer: map a grammar state to a PolicyDecision (Silent, Review, Escalate).
sign: Residual sign tuple σ(k) = (‖r‖, ṙ, r̈). Residual sign tuple σ(k) = (‖r(k)‖, ṙ(k), r̈(k)) and its sliding-window estimator.
stationarity: Wide-sense-stationarity check for calibration windows. Wide-sense-stationarity (WSS) check for calibration windows.
syntax: Syntax layer: classify sign tuples into named motifs (see heuristics::RoboticsMotif for the typed motif catalogue). Syntax layer — classify residual sign-tuple sequences into named structural motifs from the heuristics bank.
uncertainty: Uncertainty budget per GUM JCGM 100:2008. Uncertainty budget per GUM JCGM 100:2008.

Functions§

observe: Read-only one-shot DSFB observation of a residual slice.