Skip to content

README.md

Latest commit

 

History

History
271 lines (208 loc) · 9.43 KB

README.md

File metadata and controls

271 lines (208 loc) · 9.43 KB
Raw

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