TRCE — Thermodynamic Reservoir Computing Engine

用 CPU 热力学硬件做 AI 推理的物理储层计算引擎。不依赖 GPU，不引入传统 ML 框架。"计算"是硅片上的热传导，"记忆"是芯片的热惯性。

核心理念

传统 ML:  软件在 GPU 上算矩阵乘法
TRCE:    硅片的热传导完成非线性变换，软件只做 I/O + 线性 Readout

物理过程	触发方式	等效 ML 运算
CPU 死循环脉冲	inject_heat_pulse()	非线性特征投影
热传导扩散	自然发生	高维空间激活变换
热惯性衰减	自然发生	RNN/LSTM 隐藏状态
风扇耗散控制	set_fan_state()	遗忘门

硬件拓扑

组件	路径	维度	角色
热区 ×N	/sys/class/thermal/thermal_zone*	4-dim	储层状态向量
风扇 ×M	/sys/class/thermal/cooling_device*	5-dim	耗散执行器
硅晶热惯性	物理固有	—	时间记忆（遗忘门）

编号不固定，启动时运行时探测 sysfs type 字段。

项目结构

TRCE/
├── Cargo.toml                  # Workspace 根
├── pyproject.toml              # maturin 构建配置
├── crates/
│   ├── trce-core/              # Rust 核心库
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── engine.rs       # Typestate 引擎 (Uninitialized → Calibrated → Running → Released)
│   │       ├── hardware/       # sysfs I/O 层
│   │       │   ├── thermal_zone.rs
│   │       │   ├── cooling_device.rs
│   │       │   ├── cpu_affinity.rs
│   │       │   ├── governor.rs
│   │       │   └── thermald.rs
│   │       ├── inference/      # 推理管线
│   │       │   ├── pulse.rs    # 热脉冲注入 (black_box 防优化)
│   │       │   ├── readout.rs  # 线性分类器 (8-dim 点积 + sign)
│   │       │   ├── signal.rs   # 梯度、基线扣除、指数移动平均
│   │       │   └── stream.rs   # tokio MPSC 流式推理
│   │       ├── training/       # 离线训练
│   │       │   ├── fit.rs      # OLS / Ridge 回归 (手写 Gaussian elimination)
│   │       │   └── fingerprint.rs  # 多窗口物理指纹采集
│   │       ├── telemetry/      # 遥测
│   │       │   ├── metrics.rs
│   │       │   └── watchdog.rs # 独立 OS 线程超温熔断
│   │       ├── serialization/
│   │       │   └── weights.rs  # 权重序列化 (原生字节格式)
│   │       └── privilege/
│   │           └── mod.rs      # root 检测、提权策略
│   └── trce-py/                # PyO3 Python 绑定
│       └── src/lib.rs
├── python/trce/                # Python 封装层
│   ├── __init__.py
│   ├── engine.py               # ThermodynamicEngine Python 接口
│   ├── training.py             # DesignMatrix, ReadoutWeights, fit_readout
│   └── daemon.py               # 守护进程入口 (自动提权)
├── deploy/
│   └── trce.service            # systemd 服务单元
└── examples/
    └── basic_inference.py

快速开始

环境要求

• OS: Debian/Ubuntu (依赖 /sys/class/thermal/ sysfs 路径)
• 权限: root/sudo (风扇控制、governor 锁定、thermald 管理)
• Python: >= 3.8
• Rust: stable (通过 maturin 构建)

构建

# 克隆仓库
git clone <repo-url> && cd TRCE

# 创建 Python 虚拟环境
python3 -m venv .venv && source .venv/bin/activate

# 安装 maturin
pip install maturin numpy

# 构建并安装 PyO3 扩展
maturin develop --release

基本推理

from trce import ThermodynamicEngine

with ThermodynamicEngine() as engine:
    engine.calibrate_baseline(5)  # 采样 5 秒空载温度
    engine.load_weights_from_file("weights.bin")

    features = [0.5, 0.3, 0.7, 0.2]
    result = engine.inject_and_predict(features)
    print(f"Prediction: {result.prediction}, Confidence: {result.confidence:.4f}")

训练拟合

from trce.training import DesignMatrix, fit_readout

# 收集物理指纹 (需要真实硬件)
# samples: 28-dim 向量 (6 时间窗口 × 4 热区 + 4 dT/dt)
# labels: +1 或 -1
matrix = DesignMatrix(samples, labels)

# 拟合 Readout 权重
weights = fit_readout(matrix, method="ridge", alpha=0.1)

# 保存权重
weights.save("weights.bin")

架构 (4 阶段，严格顺序)

1. Hardware Isolation — 锁 CPU 亲和性、锁 performance governor、停 thermald
2. Feature-to-Heat Projection — 输入特征编码为微秒级 CPU 死循环脉冲 (PWM)；风扇开关控制遗忘率
3. State Telemetry — 异步非阻塞 I/O 读取热区温度；提取位置向量 (ΔT) 和动力学向量 (dT/dt)
4. Linear Readout — 单层矩阵乘法 + 偏置 + sign 阈值分类；物理层已完成非线性化

Typestate 生命周期

Uninitialized ──init_hardware_harness()──▶ Calibrated
                                                │
                                        load_weights()
                                                │
                                                ▼
                                           Running ──release()──▶ Released

每个状态是零大小类型 (ZST)，状态转换消费 self 返回新类型。未初始化就调推理 → 编译错误。

API 一览

Rust (trce-core)

模块	关键类型/函数	说明
engine	ThermodynamicEngine<State>	Typestate 引擎主体
hardware	ThermalZone, CoolingDevice, HardwareHarness	sysfs 硬件控制
inference	inject_heat_pulse(), ReadoutWeights::classify()	脉冲注入 + 分类
training	fit_readout(), collect_physical_fingerprints()	OLS/Ridge 拟合
telemetry	WatchdogHandle, EngineMetrics	超温熔断 + 遥测
serialization	save_weights(), load_weights()	原生字节权重 I/O
privilege	is_root(), escalate_if_needed()	权限管理

Python (trce)

类/函数	说明
ThermodynamicEngine	高层 Python 接口 (context manager)
DesignMatrix	训练数据容器
ReadoutWeights	权重 (classify, save, load)
fit_readout(matrix, method)	OLS / Ridge 拟合
probe_thermal_zones()	探测热区
read_temperatures()	读取温度
probe_cooling_devices()	探测风扇
set_fan_state(id, state)	控制风扇

关键设计决策

决策	选择	原因
硬件探测	运行时扫描 sysfs type 字段	不同硬件编号不同
权重格式	原生字节 8×f64 weights + 1×f64 bias	零依赖、纳秒级加载
Watchdog	独立 OS 线程	tokio 卡死时仍能熔断
生命周期	Typestate 模式	编译期强制阶段顺序
异步 I/O	tokio + spawn_blocking	sysfs 是阻塞 I/O
矩阵运算	手写 Gaussian elimination + partial pivoting	不引入 nalgebra/ndarray
sysfs 写入	O_SYNC + sync_all()	内核要求首次写入完整值
调用风格	嵌入式 HAL 风格	不像数学库，像硬件控制
脉冲防优化	std::hint::black_box	防止 LLVM 死代码消除
GIL 释放	py.allow_threads()	Python 长操作不阻塞其他线程

部署

systemd 服务 (推荐)

sudo cp deploy/trce.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now trce

服务配置:

• 以 root 运行 (需要 CAP_SYS_ADMIN 控制风扇/governor)
• 严格沙箱: ProtectSystem=strict, ProtectHome=true
• 仅允许读写 /sys/class/thermal 和 /tmp
• 自动重启 (5 秒延迟)

手动运行

sudo .venv/bin/python -m trce.daemon

非 root 用户会自动触发 sudo 提权。

物理参数调优

热脉冲

参数	默认值	说明
pulse_duration_us	2000	脉冲持续时间 (微秒)
intensity	0.0 ~ 1.0	脉冲强度 (特征值)

多窗口采样

采样时间窗口: [0.0, 0.5, 1.0, 1.5, 2.0, 3.0] 秒

特征维度 = 6 时间窗口 × 4 热区 + 4 dT/dt = 28 维

冷却策略

• 脉冲注入期间: 风扇 关闭 (最大化 ΔT)
• 样本间隔: 5 秒 冷却时间 (消除热惯性混叠)
• 冷却完成后: 风扇恢复开启

依赖

Rust

crate	用途
tokio	异步运行时
pyo3	Python 绑定
core_affinity	CPU 亲和性
anyhow	错误处理
libc	系统调用

零 ML 框架依赖 — 不依赖 numpy (Rust 侧)、linfa、ndarray。

Python

包	用途
numpy	训练阶段矩阵运算
maturin	构建 PyO3 扩展

风险与缓解

风险	等级	缓解措施
硬件热插拔	高	运行时探测 + I/O 错误重试
Governor 路径差异	高	读 available_governors，fallback intel_pstate
tokio runtime 卡死	高	sysfs 全部 spawn_blocking + 独立线程 watchdog
PyO3 GIL 竞争	中	py.allow_threads() 释放 GIL
温度读取延迟抖动	中	CLOCK_MONOTONIC 时间戳 + 紧凑循环
非 root 无法控制风扇	中	降级为只读模式，提示提权

License

MIT © NeuronPulse