# hsiwm

**Repository Path**: yt7589/hsiwm

## Basic Information

- **Project Name**: hsiwm
- **Description**: Heshu Industrial World Model
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AdaJEPA — 自适应 JEPA 智能制造预测性维护与工艺优化系统

基于自适应 Joint Embedding Predictive Architecture（JEPA）的智能制造系统，统一服务于**预测性维护**、**自适应加工**和**工艺优化**三大目标。通过构建可自适应的隐空间世界模型，实现设备退化早期检测、工况漂移下的实时工艺参数优化以及隐空间动力学的可解释性分析。

核心理念：将多传感器时序信号编码到统一隐空间，利用流匹配进行概率性未来状态预测，结合 Koopman 算子实现物理一致性约束，并通过在线自适应（AdaJEPA）持续跟踪工业系统动态变化。

---

## 系统架构

```
┌─────────────────────────────────────────────────────┐
│                   Orchestrator Agent                 │
│  (实验编排、超参数管理、训练循环)                     │
└─────┬───────┬────────┬────────┬────────┬───────────┘
      │       │        │        │        │
      ▼       ▼        ▼        ▼        ▼
┌─────────┐ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│  Data   │ │Encoder│ │Predi-│ │FlowM-│ │ AdaJEPA  │
│ Pipeline│ │Agent  │ │ctor  │ │atch  │ │  Agent   │
│  Agent  │ │       │ │Agent │ │Agent │ │          │
└─────────┘ └───────┘ └──────┘ └──────┘ └──────────┘
      │                                       │
      └───────────────┬───────────────────────┘
                      ▼
           ┌──────────────────┐
           │  Interpretability│
           │      Agent       │
           │  (Koopman + KAN) │
           └──────────────────┘
```

| 模块 | 职责 | 核心技术 |
|:---|:---|:---|
| **DataPipeline Agent** | 多传感器数据加载、清洗、帧构建、多尺度金字塔 | 滑动窗口、AvgPool降采样 |
| **Encoder Agent** | 多尺度时序编码，隐空间表示学习 | xLSTM、SigReg 协方差正则 |
| **Predictor Agent** | 基于历史隐状态预测未来隐状态 | Transformer Encoder |
| **FlowMatching Agent** | 概率性未来状态预测，不确定性量化 | 条件流匹配、ODE积分 |
| **AdaJEPA Agent** | 在线自适应学习，推理-更新闭环 | 环形缓冲区、单步梯度更新 |
| **Interpretability Agent** | 隐空间可解释性分析 | Koopman DMD、KAN 符号回归 |
| **Orchestrator Agent** | 训练编排、超参数管理、checkpoint | YAML 配置驱动 |

---

## 快速开始

### 环境要求

- Python ≥ 3.10
- PyTorch ≥ 2.0
- CUDA（可选，CPU 也可运行）

### 安装

```bash
git clone <repo-url> && cd hsimw
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

### 验证安装

```bash
# 运行单元测试
pytest adaptive_jepa/tests/ -v --tb=short

# 运行数据管道演示
python demo_pipeline.py
```

### 最小化训练示例

```bash
# 使用合成数据的快速训练（约 2 分钟，不需要 GPU）
python adaptive_jepa/experiments/examples/basic_training.py
```

### CMAPSS 完整训练

```bash
# 下载 CMAPSS 数据
python adaptive_jepa/experiments/download_cmapss.py

# 运行基线实验
python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp1_baseline
```

---

## Agent 使用示例

### DataPipeline Agent

```python
import numpy as np
from adaptive_jepa import DataPipelineAgent

# 生成合成数据
data = np.random.randn(10000, 6).astype(np.float32)

pipeline = DataPipelineAgent(window_length=256, stride=128)
frames = pipeline.build_frames(data)         # (N, 256, 6)
pyramid = pipeline.build_pyramid(frames)     # 多尺度金字塔
loader = pipeline.get_dataloader(pyramid, batch_size=32)

for s1, s2, s4 in loader:
    print(f"Scale 1: {s1.shape}, Scale 2: {s2.shape}, Scale 4: {s4.shape}")
    break
```

### Encoder Agent

```python
import torch
from adaptive_jepa import EncoderAgent

encoder = EncoderAgent(input_channels=24, use_xlstm=True, hidden_size=256)
x = torch.randn(4, 256, 24)           # (B, L, C)
z = encoder.encode(x, scale=1)        # → (4, 128)
print(f"Latent shape: {z.shape}")
```

### Predictor Agent

```python
from adaptive_jepa import PredictorAgent

predictor = PredictorAgent(history=8)
z_hist = torch.randn(4, 8, 128)       # (B, H=8, d=128)
z_next = predictor.predict(z_hist, scale=1)  # → (4, 128)
```

### FlowMatching Agent

```python
from adaptive_jepa import FlowMatchingAgent

fm = FlowMatchingAgent(d_latent=128, d_condition=1024)
z0 = torch.randn(4, 128)              # 先验采样
cond = torch.randn(4, 1024)           # 条件（8帧历史展平）
z_pred = fm.sample(z0, cond)          # 一次采样 → (4, 128)

# 异常检测
score = fm.compute_anomaly_score(z_true=z_pred, condition=cond)
alert = fm.anomaly_trend_detect([0.1, 0.2, 0.35, 0.55, 0.8])
print(f"Alert: {alert}")
```

### AdaJEPA Agent（在线自适应）

```python
from adaptive_jepa import AdaJEPAAgent, EncoderAgent, PredictorAgent, FlowMatchingAgent

adajepa = AdaJEPAAgent(
    encoder=EncoderAgent(input_channels=24),
    predictor=PredictorAgent(),
    flow_matcher=FlowMatchingAgent(d_latent=128, d_condition=1024),
    buffer_capacity=1000,
    lr=1e-4,
)

# 模拟在线循环
for step in range(200):
    obs = torch.randn(256, 24)              # 新传感器帧
    z_pred = adajepa.step(obs)              # 推理 + 缓冲
    if step % 20 == 0 and step > 0:
        adajepa.adapt()                     # 单步梯度更新
```

### Interpretability Agent

```python
from adaptive_jepa import InterpretabilityAgent

interp = InterpretabilityAgent()

# Koopman 分析
z_seq = torch.randn(500, 128, dtype=torch.float64)
K, evals, evecs = interp.fit_koopman(z_seq)
cond = interp.compute_condition_number(K)
modes = interp.analyze_modes(top_k=5)
print(f"Condition number: {cond:.4f}")

# 符号回归
quality = torch.randn(500, dtype=torch.float64)
expr = interp.symbolic_regression(z_seq, quality, n_epochs=200)
print(expr[:200])
```

---

## 消融实验

8 个消融实验逐步验证各组件的贡献：

| 编号 | 配置 | 命令 |
|:---|:---|:---|
| 1 | 基线：MTS-JEPA + MLP | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp1_baseline` |
| 2 | + xLSTM 骨干网络 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp2_xlstm` |
| 3 | + SigReg 正则化 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp3_sigreg` |
| 4 | + 多尺度预测 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp4_multiscale` |
| 5 | + 流匹配 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp5_flowmatch` |
| 6 | + Koopman 约束 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp6_koopman` |
| 7 | 完整模型（冻结） | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp7_full_frozen` |
| 8 | + AdaJEPA 在线自适应 | `python -m adaptive_jepa.experiments.ablation.run_ablation --exp exp8_adajepa` |

结果自动保存到 `adaptive_jepa/experiments/ablation/results/` 目录。

### 一键运行全部消融实验

```bash
python -m adaptive_jepa.experiments.ablation.run_ablation --all
python adaptive_jepa/experiments/ablation/summarize.py
```

---

## 项目结构

```
hsimw/
├── README.md
├── AGENTS.md                        # 项目宪法与开发规范
├── pyproject.toml
├── requirements.txt
├── demo_pipeline.py                 # 数据管道演示
├── doc/
│   ├── architecture.md              # 完整研究方案（数学推导 + 架构设计）
│   └── tasks/                       # 任务列表
├── adaptive_jepa/
│   ├── agents/                      # 7 个 Agent + BaseAgent
│   ├── models/                      # xLSTM, Koopman, KAN, VectorField
│   ├── losses/                      # SigReg, JEPA, FlowMatching, Koopman 损失
│   ├── utils/                       # 环形缓冲区、评估指标、可视化
│   ├── configs/                     # YAML 配置文件（default/cmapss/ims/phm2010/xjtu）
│   ├── experiments/
│   │   ├── ablation/                # 8 个消融实验 + 结果
│   │   ├── applications/            # 3 个应用场景脚本
│   │   └── examples/                # 使用示例脚本
│   └── tests/                       # 单元测试
├── raw_data/                        # 原始数据集
└── results/                         # 实验结果输出
```

---

## 主要特性

- **多尺度时序编码**：xLSTM 骨干 + 3 层金字塔（原始/½/¼ 分辨率），同时捕捉瞬态冲击和长期趋势
- **概率性预测**：条件流匹配 + ODE 积分，支持多模态未来和不确定性量化
- **防坍塌正则**：SigReg 协方差正则化确保隐表示各维度去相关
- **物理一致性**：Koopman 算子提供线性动力学基，约束隐空间演化规律
- **在线自适应**：AdaJEPA 闭环持续学习，30 秒内完成一轮更新，跟踪工况漂移
- **可解释性**：KAN 符号回归 + Koopman 特征值分析，黑箱模型可解释化

---

## 引用

本项目的核心算法基于以下工作：

- LeCun, Y. (2022). "A Path Towards Autonomous Machine Intelligence." *arXiv preprint arXiv:2207.00607*.
- Beck, M. et al. (2024). "xLSTM: Extended Long Short-Term Memory." *arXiv preprint arXiv:2405.04517*.
- Lipman, Y. et al. (2023). "Flow Matching for Generative Modeling." *ICLR 2023*.
- Bardes, A. et al. (2022). "VICReg: Variance-Invariance-Covariance Regularization for Self-Supervised Learning." *ICLR 2022*.
- Lusch, B. et al. (2018). "Deep Learning for Universal Linear Embeddings of Nonlinear Dynamics." *Nature Communications*.

---

## 许可证

MIT License