SOFIA ENGINE

Offline-First Industrial AI, Quantum-Inspired Emulation & Multi-Domain Signal Intelligence Runtime

Documentation | GitHub Wiki | NPM Package | REI SignalLab | Rootcastle

Executive Overview

Sofia Engine is an engineering-grade, offline-first edge intelligence and artificial intelligence runtime developed by Rootcastle Engineering & Innovation. Built for mission-critical industrial assets—power distribution grids, high-speed turbomachinery, chemical process systems, and robotics—Sofia converts complex multi-domain physical telemetry into structured, mathematically validated engineering intelligence directly at the edge.

Sofia Engine is not merely a vibration monitor. Powered by algorithms from Rootcastle REI SignalLab, it integrates:

1. Multi-Domain Industrial Signal Processing:
   • Mechanical Vibration: ISO 10816/20816 severity, Welch PSD (Parseval energy-conserving), Hilbert analytic envelope, rotating machinery kinematics (BPFO, BPFI, BSF, FTF, Gear Mesh).
   • Electrical Power Quality (IEEE 519 / IEC 61000-4-30): Active/Reactive/Apparent Power ($P, Q, S$), Power Factor ($PF$), Total Harmonic Distortion ($\text{THD}_V, \text{THD}_I$ up to 50th harmonic), Fortescue 3-Phase Symmetrical Components ($V_0, V_1, V_2, VUF$), and Sag/Swell/Interruption event detection.
   • Acoustic Emission & Ultrasound (ASTM E1316): High-frequency transient energy, counts, duration, rise time, and cavitation intensity indexing for pumps and valves.
   • Thermal & Fluid Process Telemetry: Dynamic rate of change ($dT/dt$), thermal gradient, pressure pulsations, and water hammer transients.
   • Multi-Axis Inertial Dynamics (IMU): 3-axis acceleration vector magnitude ($|\mathbf{a}|$), dynamic tilt (pitch, roll), and dynamic jerk ($d\mathbf{a}/dt$).
2. Advanced Quantum Computing Emulation (sofia_ai.quantum):
   • Complex statevector simulation in $\mathbb{C}^{2^n}$ with unitary evolution.
   • Universal gate library: Hadamard ($H$), Pauli ($X, Y, Z$), Phase ($S, T$), Parametric Rotations ($R_x, R_y, R_z$), and Entangling Gates ($CX, CZ$).
   • Quantum Feature Maps (Angle & Amplitude encoding) and Quantum Kernel Estimation ($K(x, y) = |\langle \psi(x) | \psi(y) \rangle|^2$) for quantum-enhanced machine learning.
3. AI Copilot & Technical Decision Support (sofia_ai.copilot):
   • Multi-provider AI reasoning engine supporting NVIDIA NIM (api.nvidia.com), OpenRouter (openrouter.ai), and deterministic offline fallback.
4. Deterministic Safety Gate (PolicyEngine):
   • Strict default DENY state machine. Inference and RL models cannot actuate machinery without passing allowlists, operator authorization, interlocks, and Nonce/TTL replay defense.
5. Universal Multi-Language Runtime:
   • Python Core: Zero runtime dependencies beyond NumPy (numpy>=1.24).
   • TypeScript / Node.js SDK: Published on npm as @rootcastle/sofia-engine with zero runtime dependencies.
   • Embedded C99 Runtime: Microcontroller engine (embedded/) with Q16.16 fixed-point math and Python-verified golden vectors.

The Rootcastle Engineering Pillars

+---------------------------------------------------------------------------------------+
|                                ROOTCASTLE PILLARS                                     |
+---------------------------------------------------------------------------------------+
|  1. EVIDENCE BEATS HYPE        Every metric derives from verifiable physical/spectral |
|                                evidence. No unbacked accuracy claims.                 |
|  2. MULTI-DOMAIN INTELLIGENCE  Vibration, electrical power, acoustic, thermal, and    |
|                                process signals unified in a single edge runtime.      |
|  3. QUANTUM-INSPIRED SPEED     Statevector emulation, quantum kernels, and VQC.       |
|  4. DEFAULT "DENY" SAFETY      Zero control path bypass. All control decisions pass   |
|                                through physical interlocks and operator gates.        |
|  5. AIR-GAPPED BY DESIGN       Zero network or broker dependency in the core. Runs on |
|                                bare metal, isolated gateways, and microcontrollers.   |
+---------------------------------------------------------------------------------------+

System Architecture

flowchart TD
    subgraph INGEST ["1. Multi-Domain Telemetry Layer"]
        S_VIB["Vibration (Acc / Vel / Disp)"] --> TS["TelemetrySource (ABC)"]
        S_ELEC["Electrical (V, I 3-Phase)"] --> TS
        S_AC["Acoustic / Ultrasound"] --> TS
        S_PROC["Process (Temp, Press, Flow)"] --> TS
        S_IMU["3-Axis IMU (Motion, Tilt)"] --> TS
        S_BUS["MQTT / Modbus / Serial / CSV"] -.-> TS
        TS --> RB["Bounded Ring Buffer\n(Ceiling: N samples, Drop-Oldest)"]
    end

    subgraph DSP ["2. Multi-Domain Signal & Feature Pipeline (NumPy / Pure TS)"]
        RB --> WN["Sliding Window & Quality Tagging\n(GOOD, STALE, MISSING, INVALID)"]
        WN --> SIG_VIB["Vibration DSP\n- Welch PSD (Parseval)\n- Hilbert Envelope\n- Kinematics (BPFO/BPFI)"]
        WN --> SIG_ELE["Electrical Engine (IEEE 519)\n- Power (P, Q, S, PF)\n- THD (1-50 Harmonics)\n- Fortescue 3-Phase (V0, V1, V2, VUF)"]
        WN --> SIG_AC["Acoustic Engine (ASTM E1316)\n- AE Energy, Counts, Rise Time\n- Cavitation Index"]
        WN --> SIG_PROC["Process & Motion\n- dT/dt, Pressure Pulsation\n- Tilt (Pitch, Roll), Jerk"]
        SIG_VIB & SIG_ELE & SIG_AC & SIG_PROC --> FEAT["Unified FeatureVector\n(Named, Ordered, Versioned)"]
    end

    subgraph QUANTUM ["3. Quantum Emulation & Inference Layer"]
        FEAT --> Q_MAP["Quantum Feature Map\n(Angle / Amplitude Encoding)"]
        Q_MAP --> Q_CIRC["QuantumCircuit & Kernel\n(Statevector in C^(2^n), Gates, Fidelity)"]
        FEAT --> MB["Statistical & ML Backends\n- Robust MAD / EWMA / CUSUM\n- ONNX / PyTorch (Optional)"]
        Q_CIRC & MB --> IR["InferenceResult\n(Score, Confidence, Uncertainty)"]
    end

    subgraph DIAGNOSTICS ["4. Diagnostic & Health Evaluation"]
        IR --> DE["DiagnosticEngine\n(Evidence Fusion & Quality Scaling)"]
        DE --> HE["HealthEvent\n(Severity, Evidence Trail)"]
        HE --> HS["HealthScore\n(0-100 with Dynamic Uncertainty Band)"]
    end

    subgraph COPILOT ["5. AI Copilot & Safe Decision Gate"]
        HE --> AI_COP["Sofia AI Copilot\n- NVIDIA NIM (api.nvidia.com)\n- OpenRouter (openrouter.ai)\n- Offline Deterministic Renderer"]
        CMD["CommandRequest"] --> PE{"PolicyEngine\n(Default: DENY)"}
        PE -->|Passes Interlocks & Approval| ACT["CommandDecision: APPROVE"]
        PE -->|Violation / High Uncertainty| DEN["CommandDecision: DENY"]
    end

    style INGEST fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style DSP fill:#181825,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
    style QUANTUM fill:#1e1e2e,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style DIAGNOSTICS fill:#181825,stroke:#fab387,stroke-width:2px,color:#cdd6f4
    style COPILOT fill:#313244,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4

Mathematical & Scientific Foundations

1. Electrical Power Quality & Fortescue Transformation (from REI SignalLab)

• Instantaneous Active, Reactive, and Apparent Power: $$P = \frac{1}{N}\sum_{n=0}^{N-1} v_n \cdot i_n, \quad S = V_{rms} \cdot I_{rms}, \quad Q = \sqrt{S^2 - P^2}, \quad PF = \frac{P}{S}$$

• Total Harmonic Distortion ($\text{THD}$) (IEEE 519 up to 50th harmonic): $$\text{THD}V = \frac{\sqrt{\sum{h=2}^{50} V_h^2}}{V_1} \times 100%$$

• Fortescue Symmetrical Components (3-Phase Unbalance): Let $a = e^{j \frac{2\pi}{3}} = -\frac{1}{2} + j \frac{\sqrt{3}}{2}$: $$\begin{bmatrix} V_0 \ V_1 \ V_2 \end{bmatrix} = \frac{1}{3} \begin{bmatrix} 1 & 1 & 1 \ 1 & a & a^2 \ 1 & a^2 & a \end{bmatrix} \begin{bmatrix} V_a \ V_b \ V_c \end{bmatrix}$$

  • $V_0$: Zero sequence (ground faults).
  • $V_1$: Positive sequence (balanced operating component).
  • $V_2$: Negative sequence (motor overheating / unbalance).
  • Voltage Unbalance Factor: $\text{VUF} = \frac{|V_2|}{|V_1|} \times 100%$.

2. Acoustic Emission & Cavitation Indexing (ASTM E1316)

• Acoustic Emission Energy ($E_{AE}$): $$E_{AE} = \int_{0}^{T} v(t)^2 , dt \approx \sum_{n=0}^{N-1} v_n^2 \Delta t$$
• Cavitation Index ($C_p$): $$C_p = \frac{\int_{5\text{ kHz}}^{20\text{ kHz}} P(f) , df}{\int_{0}^{f_s/2} P(f) , df}$$ Measures the ratio of broadband high-frequency acoustic collapse energy to overall energy.

3. Vibration DSP & Bearing Kinematics

• Welch Power Spectral Density (Parseval Energy Preserved): $$\sum_{n=0}^{N-1} |x_n|^2 = \frac{1}{N} \sum_{k=0}^{N-1} |X_k|^2$$
• Demodulated Analytic Envelope (Hilbert Transform): $$\tilde{x}(t) = x(t) + j \cdot \mathcal{H}{x(t)} = A(t)e^{j\phi(t)}, \quad A(t) = \sqrt{x(t)^2 + [\mathcal{H}{x(t)}]^2}$$
• Bearing Defect Frequencies (Outer/Inner/Ball/Cage): $$\text{BPFO} = \frac{N_b}{2} f_r \left(1 - \frac{d}{D}\cos\alpha\right), \quad \text{BPFI} = \frac{N_b}{2} f_r \left(1 + \frac{d}{D}\cos\alpha\right)$$

4. Advanced Quantum Computing Emulation

• Quantum Statevector: $$|\psi\rangle = \sum_{i=0}^{2^n-1} \alpha_i |i\rangle \in \mathbb{C}^{2^n}, \quad \sum_{i} |\alpha_i|^2 = 1$$
• Angle Encoding Feature Map: $$|x\rangle = \bigotimes_{i=1}^n \left(\cos(x_i)|0\rangle + \sin(x_i)|1\rangle\right)$$
• Quantum Kernel Estimation: $$K(x, y) = |\langle \psi(x) | \psi(y) \rangle|^2$$ Yields transition fidelity in $[0, 1]$ for quantum support vector machines and anomaly isolation.

Installation

Python (Core Engine & CLI)

# Minimal production installation (NumPy only - Zero bloat)
pip install sofia-engine

# With industrial field protocols (MQTT, Modbus, Serial)
pip install "sofia-engine[industrial]"

# Full development suite
pip install "sofia-engine[dev]"

TypeScript / Node.js (Edge & Cloud SDK)

npm install @rootcastle/sofia-engine

Quickstart

1. Multi-Domain Signal Processing (Python)

import numpy as np
from sofia_ai.features import (
    extract_electrical_features,
    extract_acoustic_features,
    extract_process_features,
    extract_motion_features
)

# 1. Electrical Power Quality (from 230V / 10A 50Hz signals)
t = np.arange(2000) / 2000.0
v = 230.0 * np.sqrt(2) * np.sin(2 * np.pi * 50.0 * t)
i = 10.0 * np.sqrt(2) * np.sin(2 * np.pi * 50.0 * t)
elec_fv = extract_electrical_features(v, i, fs=2000.0)
print(f"Power: {elec_fv['active_power_w']} W | PF: {elec_fv['power_factor']} | THD_V: {elec_fv['thd_v_percent']}%")

# 2. Acoustic Emission & Cavitation
sound = np.sin(2 * np.pi * 12000.0 * t)
ac_fv = extract_acoustic_features(sound, fs=50000.0)
print(f"AE Energy: {ac_fv['energy']:.4f} | Cavitation Index: {ac_fv['cavitation_index']:.2f}")

# 3. 3-Axis IMU Motion & Tilt
ax, ay, az = np.zeros(200), np.zeros(200), np.ones(200)
motion_fv = extract_motion_features(ax, ay, az, fs=100.0)
print(f"Accel Mag: {motion_fv['accel_mag_mean']:.2f} g | Roll: {motion_fv['roll_mean_deg']:.1f}°")

2. Quantum Circuit & Kernel Estimation (Python)

from sofia_ai.quantum import QuantumCircuit, QuantumKernel

# 1. Create 2-qubit Bell state (|00> + |11>) / sqrt(2)
qc = QuantumCircuit(num_qubits=2)
qc.h(0).cx(0, 1)
print("Measurement counts (1000 shots):", qc.measure(shots=1000))

# 2. Compute Quantum Kernel between two sensor feature vectors
kernel = QuantumKernel(num_qubits=3)
fidelity = kernel.evaluate([0.1, 0.5, 0.9], [0.1, 0.5, 0.9])
print(f"Quantum Kernel Fidelity: {fidelity:.4f}") # 1.0000

3. AI Copilot (CLI & Python)

# Ask with auto-detected NVIDIA NIM or OpenRouter key:
sofia ask "Explain voltage unbalance factor (VUF) exceeding 2% in a 3-phase induction motor" --device motor-01

from sofia_ai.copilot import AIEngine

ai = AIEngine(provider="auto") # Auto-detects NVIDIA_API_KEY or OPENROUTER_API_KEY
explanation = ai.explain(
    question="Why is THD_I 8.5% critical under IEEE 519?",
    device_id="substation-04",
    evidence=[{"metric": "thd_i", "observed": 8.5, "reference": 5.0}]
)
print(explanation)

Specification Traceability

| Requirement Area | Specification IDs | Key Capabilities | |---|---|---| | Multi-Domain Signals | SOFIA-SIG-001 - 012 | Vibration, Electrical (IEEE 519), Acoustic (ASTM E1316), Thermal, Fluid, IMU. | | Quantum Emulation | SOFIA-QEXP-001 - 005 | Complex statevectors in $\mathbb{C}^{2^n}$, universal gates, quantum kernels. | | AI Copilot | SOFIA-COP-001 - 004 | NVIDIA NIM & OpenRouter integrations with offline deterministic fallback. | | Safety Gate | SOFIA-SAFE-001 - 006 | Default DENY, operator approval gate, physical interlocks, Nonce/TTL protection. | | Edge Resilience | SOFIA-EDGE-001 - 007 | Ring buffers, store-and-forward (64 MiB ceiling), reconnect backoff. |

License & Governance

• License: Open-source under Apache License 2.0. See LICENSE and NOTICE.
• Developed by: Rootcastle Engineering & Innovation.