Skill: wangjiaocheng/cda-data-synth (version 1.0.0)

--- name: cda-data-synth author: 王教成 Wang Jiaocheng (波动几何) description: | CDA 因果数据合成器——根据领域描述自动生成 CDA 架构可消费的因果数据集。 生成 Entity-State Graph（JSON 格式）、CausalEdge 列表、带时间戳的观测轨迹、哈密顿量约束参数。 覆盖热力学、力学、流体、多域耦合等物理域，支持生成训练数据、验证数据、基准测试数据。 当用户需要为 CDA 架构生成合成数据、构造因果仿真场景、设计测试基准数据集时触发。 触发词：因果数据合成、Entity-State Graph、生成仿真数据、CDA训练数据、合成因果数据、因果图数据、物理仿真数据集、因果轨迹数据。 --- # CDA 因果数据合成器（Data Synthesizer） 为 Causal Dynamics Architecture 架构生成标准格式的合成因果数据集。 ## 核心定位 CDA 架构的输入不是 Token 序列，而是 **Entity-State Graph**（实体-状态因果图）。本技能解决从"领域描述"到"架构可消费数据"的桥梁问题。 **数据格式所有权**：本技能定义并维护 CDA 的数据序列化协议。Code Lab 技能依赖此协议生成代码。 ## 工作流程 ``` 用户描述场景 ↓ 1. 解析领域类型（热力学/力学/流体/多域耦合） ↓ 2. 设计实体拓扑（entities + edges 骨架） ↓ 3. 参数化机制函数（mechanism parameters） ↓ 4. 运行前向仿真生成轨迹（trajectory snapshots） ↓ 5. 序列化为 JSON 格式输出 ``` ## 输出格式规范 所有输出必须符合 `references/data-format-spec.md` 中定义的 JSON Schema。 核心输出文件类型： - `*.graph.json` — 静态因果图（实体 + 边 + 属性） - `*.trajectory.json` — 时序轨迹（多时刻快照序列） - `*.hamiltonian.json` — 哈密顿量参数（势能函数 + 守恒量） - `*.meta.json` — 数据集元信息（域类型、规模、物理约束摘要） ## 参考文件 | 文件 | 内容 | |------|------| | `references/data-format-spec.md` | **核心协议**：Entity-State Graph 的完整 JSON Schema 定义 | | `references/synthesis-protocols.md` | 各物理域的数据合成协议（热力学/力学/流体/耦合） | | `references/thermal-building-example.json` | 热力学示例：建筑温度仿真数据集 | ## 数据合成原则 1. **物理一致性**：合成数据必须满足能量守恒、质量守恒等物理约束 2. **因果真实性**：因果边的方向和机制函数必须反映真实物理规律 3. **可验证性**：每条因果边都附带 ground truth，便于验证因果发现算法 4. **可扩展性**：从简单场景（3-5 实体）到复杂场景（100+ 实体）渐进生成 ## 域类型与对应的物理约束 | 域 | 广义坐标 q | 共轭动量 p | 典型机制函数 | 守恒量 | |----|-----------|-----------|-------------|--------| | 热力学 | 温度 T | 热流 J_q | 傅里叶定律、牛顿冷却 | 能量 | | 力学 | 位移 x | 动量 p | 胡克定律、阻尼力 | 能量、动量 | | 流体 | 压力场 P | 质量流 J_m | Navier-Stokes 简化 | 质量、动量 | | 电路 | 电荷 Q | 电流 I | 欧姆定律、基尔霍夫定律 | 电荷、能量 | ## 与 CDA 主技能的关系 ``` CDA（主技能） ├── 理论参考：架构设计、公式、路线图 ├── CDA Data Synthesizer（本技能） │ └── 数据生成：Entity-State Graph → JSON └── CDA Code Lab └── 代码生成：读取数据 → 仿真/训练代码 ``` ## 使用指南 1. 用户描述目标场景（如"一个有三台压缩机和两个冷库的制冷系统"） 2. 读取 `references/data-format-spec.md` 获取格式规范 3. 读取 `references/synthesis-protocols.md` 获取对应域的合成协议 4. 参考示例文件了解完整数据集结构 5. 生成符合规范的 JSON 数据文件，输出到用户指定目录

path: references/data-format-spec.md
content: # CDA 数据格式规范（Data Format Specification）

> **版本**: v0.1.0
> **状态**: 初版提案
> **所有权**: CDA Data Synthesizer 技能

本文件定义 Causal Dynamics Architecture 的核心数据序列化协议。所有 CDA 组件（仿真引擎、训练管线、评估框架）必须遵守此格式。

---

## 一、总体设计原则

1. **JSON-first**：以 JSON 为主要序列化格式，人类可读、工具链友好
2. **NumPy 兼容**：所有张量/矩阵字段设计为可直接 `np.array()` 加载
3. **float64 精度**：所有数值字段在加载时必须转为 `torch.float64` / `np.float64`。物理仿真对数值精度高度敏感，JSON 本身不区分 float32/float64，但 consuming 端（Code Lab）应始终以双精度处理。`belief.covariance` 尤其需要高精度以保证正定性
4. **因果图 = 拓扑 + 动力学**：静态结构（实体+边）和动态行为（机制函数参数）分离
5. **时间序列友好**：轨迹数据按 snapshot 组织，支持稀疏/密集采样

---

## 二、核心数据结构

### 2.1 EntityState（实体状态）

对应 CDA §3.1 的 `EntityState` 类。

```json
{
  "id": 0,
  "name": "compressor_1",
  "type": "thermal_node",
  "domain": "thermodynamics",
  "position": {
    "values": [350.0, 0.0, 0.0],
    "coordinates": ["temperature_K", "x_m", "y_m"],
    "units": ["K", "m", "m"]
  },
  "momentum": {
    "values": [1500.0, 0.0, 0.0],
    "coordinates": ["heat_flux_W", "velocity_x", "velocity_y"],
    "units": ["W", "m/s", "m/s"]
  },
  "attributes": {
    "mass": 25.0,
    "specific_heat": 500.0,
    "thermal_conductivity": 50.0,
    "volume": 0.05,
    "material_type": "steel"
  },
  "belief": {
    "distribution_type": "gaussian",
    "mean": [350.0, 0.0, 0.0],
    "covariance": [
      [1.0, 0.0, 0.0],
      [0.0, 0.01, 0.0],
      [0.0, 0.0, 0.01]
    ]
  }
}
```

**字段说明**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | int | ✅ | 实体唯一标识符（全局） |
| `name` | string | ✅ | 人类可读名称 |
| `type` | string | ✅ | 实体类型（见 §2.5 类型注册表） |
| `domain` | string | ✅ | 所属物理域（thermodynamics/mechanics/fluid/circuit） |
| `position` | object | ✅ | 广义坐标 q |
| `position.values` | float[] | ✅ | 坐标值数组 |
| `position.coordinates` | string[] | ✅ | 每个维度的物理含义 |
| `position.units` | string[] | ✅ | 每个维度的单位 |
| `momentum` | object | ✅ | 共轭动量 p（结构同 position） |
| `attributes` | object | ✅ | 固有属性（质量、材料参数等，域相关） |
| `belief` | object | ✅ | 贝叶斯信念分布 |

**belief 子结构**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `distribution_type` | string | 目前仅支持 `gaussian`，预留 `mixture`, `laplace` |
| `mean` | float[] | 信念均值（维度 = position + momentum） |
| `covariance` | float[][] | 协方差矩阵（方阵，维度同 mean） |

---

### 2.2 CausalEdge（因果边）

对应 CDA §3.1 的 `CausalEdge` 类。

```json
{
  "source_id": 0,
  "target_id": 1,
  "mechanism_type": "thermal_conduction",
  "mechanism_params": {
    "conductivity": 50.0,
    "cross_section_area": 0.01,
    "distance": 2.0,
    "function_form": "fourier_law"
  },
  "strength": 0.85,
  "delay": 0.0,
  "confidence": 0.95,
  "source_knowledge": "physics_equation"
}
```

**字段说明**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source_id` | int | ✅ | 因端实体 ID |
| `target_id` | int | ✅ | 果端实体 ID |
| `mechanism_type` | string | ✅ | 机制类型（见 §2.6 机制类型注册表） |
| `mechanism_params` | object | ✅ | 机制函数参数（域相关，见 §2.7） |
| `strength` | float | ✅ | 因果强度 α_ij ∈ [0, 1] |
| `delay` | float | ✅ | 传播延迟 τ_ij（秒），0 表示即时 |
| `confidence` | float | ✅ | 置信度 ∈ [0, 1] |
| `source_knowledge` | string | ✅ | 知识来源（physics_equation/topology_diagram/equipment_manual/expert/data_inferred） |

**自环边语义（source_id == target_id）**：

当 `source_id == target_id` 时，表示**外部干预或边界条件**作用在该实体自身，而非实体间的因果传播。典型场景：

| 场景 | mechanism_type | 语义 |
|------|---------------|------|
| 空调制冷 | `thermal_convection` | 外部冷源对房间的热注入/提取 |
| 散热器加热 | `thermal_convection` | 外部热源对房间的热注入 |
| 外力施加 | `spring_force` | 外部边界条件/载荷 |
| 控制器反馈 | `pinn_learned` | 自适应控制器对自身状态的修正 |

自环边的机制函数 `f(s_self, s_self)` 只接收一个实体的状态作为输入，输出该实体的状态变化量 Δs。在因果传播计算中，自环边应在普通因果边**之后**处理（先计算实体间传播，再叠加外部干预）。

---

### 2.3 WorldState（世界状态快照）

一个时刻的完整系统状态。

```json
{
  "timestamp": 0.0,
  "time_unit": "s",
  "entities": [
    { "..." : "EntityState 对象（同 §2.1）" }
  ],
  "edges": [
    { "..." : "CausalEdge 对象（同 §2.2）" }
  ],
  "hamiltonian": {
    "total_energy": 45000.0,
    "kinetic_energy": 0.0,
    "potential_energy": 45000.0,
    "energy_error": 1.2e-6,
    "conservation_violated": false
  }
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `timestamp` | float | 时刻值 |
| `time_unit` | string | 时间单位（s/min/h） |
| `entities` | EntityState[] | 当前时刻所有实体状态 |
| `edges` | CausalEdge[] | 当前时刻所有因果边（通常不变，但在线学习可变） |
| `hamiltonian` | object | 哈密顿量守恒检查（可选，用于验证） |

---

## 三、文件类型规范

### 3.1 Graph 文件（*.graph.json）

静态因果图定义。包含初始时刻的完整系统状态。

```json
{
  "version": "0.1.0",
  "format": "cda-graph",
  "metadata": {
    "name": "building_thermal_system",
    "domain": "thermodynamics",
    "description": "三房间建筑热力学系统",
    "entity_count": 5,
    "edge_count": 6,
    "created_by": "cda-data-synth",
    "creation_time": "2026-04-27T03:00:00Z"
  },
  "entities": [ "..." ],
  "edges": [ "..." ],
  "initial_state": {
    "timestamp": 0.0,
    "hamiltonian": {
      "initial_total_energy": 45000.0
    }
  },
  "hamiltonian_definition": {
    "type": "custom",
    "potential_function": {
      "type": "pairwise",
      "form": "V(q) = sum_{i<j} (alpha_ij * (q_i - q_j)^2)",
      "params": {
        "note": "alpha_ij stored in edge mechanism_params"
      }
    },
    "conservation_quantity": "total_energy",
    "tolerance": 1.0e-4
  }
}
```

### 3.2 Trajectory 文件（*.trajectory.json）

时序轨迹。由多个 WorldState 快照组成。

```json
{
  "version": "0.1.0",
  "format": "cda-trajectory",
  "metadata": {
    "graph_ref": "building_thermal_system.graph.json",
    "snapshot_count": 1000,
    "time_range": {
      "start": 0.0,
      "end": 3600.0,
      "unit": "s"
    },
    "sampling": {
      "method": "uniform",
      "dt": 3.6,
      "steps": 1000
    },
    "generator": {
      "method": "störmer-verlet",
      "noise_level": 0.01
    }
  },
  "snapshots": [
    {
      "timestamp": 0.0,
      "entities": [ "..." ],
      "hamiltonian": { "..." }
    },
    {
      "timestamp": 3.6,
      "entities": [ "..." ],
      "hamiltonian": { "..." }
    }
  ]
}
```

**优化建议**：对于大型轨迹（>100 实体 × >10000 时间步），考虑分片存储：
```
trajectory/
  ├── meta.json          （metadata）
  ├── snapshot_000.json   （t=0 ~ t=99）
  ├── snapshot_001.json   （t=100 ~ t=199）
  └── ...
```

### 3.3 Hamiltonian 文件（*.hamiltonian.json）

哈密顿量的完整定义。用于训练时的能量约束。

```json
{
  "version": "0.1.0",
  "format": "cda-hamiltonian",
  "metadata": {
    "domain": "thermodynamics",
    "entity_count": 5
  },
  "kinetic_energy": {
    "formula": "T(p) = sum_i (p_i^2 / (2 * C_i * m_i))",
    "parameters": {
      "C": [500.0, 500.0, 500.0, 500.0, 500.0],
      "m": [25.0, 25.0, 25.0, 25.0, 25.0]
    },
    "note": "C_i = specific_heat, p_i = heat_flux analogy"
  },
  "potential_energy": {
    "formula": "V(q) = sum_{edges} alpha_ij * k_ij * A_ij / d_ij * (T_i - T_j)^2 / 2",
    "parameters": {
      "note": "Edge-dependent, see mechanism_params in edges"
    },
    "note": "Thermal analogy: potential = stored thermal energy"
  },
  "total_energy": {
    "E_total": 45000.0,
    "tolerance": 1.0e-4,
    "enforcement": "hard_constraint"
  }
}
```

### 3.4 Meta 文件（*.meta.json）

数据集元信息，用于索引和管理。

```json
{
  "version": "0.1.0",
  "dataset_name": "thermal_building_3room",
  "description": "三房间建筑热力学仿真：室外→外墙→房间→内墙→房间，含空调和散热器",
  "files": {
    "graph": "thermal_building_3room.graph.json",
    "trajectory": "thermal_building_3room.trajectory.json",
    "hamiltonian": "thermal_building_3room.hamiltonian.json"
  },
  "statistics": {
    "entity_count": 5,
    "edge_count": 6,
    "trajectory_steps": 1000,
    "time_range_s": [0.0, 3600.0],
    "state_dimension": 6
  },
  "tags": ["thermodynamics", "building", "phase1", "multi-entity"]
}
```

---

## 四、类型注册表

### 4.1 实体类型（entity type）

| type | domain | 广义坐标 q | 共轭动量 p | 典型属性 |
|------|--------|-----------|-----------|---------|
| `thermal_node` | thermodynamics | 温度 T [K] | 热流 J [W] | mass, specific_heat, thermal_conductivity |
| `mechanical_body` | mechanics | 位移 x [m] | 动量 p [kg·m/s] | mass, stiffness, damping |
| `fluid_cell` | fluid | 压力 P [Pa] | 质量流 J_m [kg/s] | volume, viscosity, density |
| `circuit_node` | circuit | 电压 V [V] | 电流 I [A] | capacitance, resistance |
| `chemical_species` | chemistry | 浓度 c [mol/L] | 反应流 J_r [mol/s] | molecular_weight, activation_energy |
| `abstract_entity` | general | 任意 | 任意 | 无约束 |

### 4.2 机制类型（mechanism type）

| mechanism_type | 因果关系 | 公式 | 对应物理定律 |
|---------------|---------|------|-------------|
| `thermal_conduction` | T_hot → T_cold | Q = k·A·(T_i - T_j)/d | 傅里叶定律 |
| `thermal_convection` | T_surface → T_fluid | Q = h·A·(T_s - T_f) | 牛顿冷却定律 |
| `thermal_radiation` | T_body → T_absorber | Q = ε·σ·A·(T_i⁴ - T_j⁴) | Stefan-Boltzmann |
| `spring_force` | x_displacement → F | F = -k·(x_i - x_j) | 胡克定律 |
| `damping_force` | v_velocity → F | F = -c·v | 粘性阻尼 |
| `gravitational` | mass → mass | F = -G·m_i·m_j/r² | 万有引力 |
| `pressure_driven_flow` | P_high → P_low | Q = ΔP/R | 压力驱动流动 |
| `ohmic_resistance` | V → I | I = (V_i - V_j)/R | 欧姆定律 |
| `chemical_reaction` | c_reactant → c_product | J = k·c^n | 质量作用定律 |
| `pinn_learned` | general → general | f(q, p; θ) | 数据驱动 PINN |

---

## 五、机制参数格式（§2.7 详解）

不同 mechanism_type 的 `mechanism_params` 结构：

### 5.1 thermal_conduction

```json
{
  "conductivity": 50.0,
  "cross_section_area": 0.01,
  "distance": 2.0,
  "function_form": "fourier_law",
  "pinn_params": null
}
```

### 5.2 spring_force

```json
{
  "stiffness": 1000.0,
  "rest_length": 1.0,
  "damping_coeff": 5.0,
  "function_form": "hooke_law",
  "pinn_params": null
}
```

### 5.3 pinn_learned（数据驱动）

```json
{
  "function_form": "pinn",
  "pinn_params": {
    "network_arch": [64, 64, 32],
    "activation": "tanh",
    "trained": false,
    "param_count": 8000
  }
}
```

---

## 六、Python 加载接口

推荐的数据加载代码骨架（Code Lab 技能会基于此生成完整实现）：

```python
@dataclass
class EntityState:
    id: int
    name: str
    type: str
    domain: str
    position: np.ndarray      # (dim_q,)
    momentum: np.ndarray      # (dim_p,)
    attributes: dict
    belief_mean: np.ndarray   # (dim_q + dim_p,)
    belief_cov: np.ndarray    # (dim, dim)

@dataclass
class CausalEdge:
    source_id: int
    target_id: int
    mechanism_type: str
    mechanism_params: dict
    strength: float
    delay: float
    confidence: float

@dataclass
class WorldState:
    timestamp: float
    entities: Dict[int, EntityState]
    edges: List[CausalEdge]

def load_graph(path: str) -> Tuple[Dict[int, EntityState], List[CausalEdge]]:
    """从 .graph.json 加载静态因果图"""
    ...

def load_trajectory(path: str) -> List[WorldState]:
    """从 .trajectory.json 加载时序轨迹"""
    ...
```

---

## 七、版本策略

- **主版本号**（X.0.0）：破坏性格式变更，不兼容旧版
- **次版本号**（0.X.0）：新增可选字段，向后兼容
- **补丁号**（0.0.X）：文档修正、示例更新

当前版本 `0.1.0`：定义了热力学域的完整格式，力学和流体域的属性参数待补充。


path: references/synthesis-protocols.md
content: # CDA 因果数据合成协议（Synthesis Protocols）

> **配合**: `data-format-spec.md` v0.1.0
> **作用**: 定义各物理域的实体拓扑设计、机制参数化、仿真参数选择、噪声注入策略

---

## 一、通用合成流程

```
输入：场景描述（自然语言）
  ↓
Step 1: 域识别（thermodynamics / mechanics / fluid / coupling）
  ↓
Step 2: 实体设计（类型、数量、初始状态、属性）
  ↓
Step 3: 因果拓扑设计（边：source→target、机制类型、参数）
  ↓
Step 4: 哈密顿量定义（势能函数、守恒量）
  ↓
Step 5: 前向仿真（积分器 + 机制函数 → 轨迹）
  ↓
Step 6: 观测噪声注入（模拟真实传感器）
  ↓
Step 7: 序列化输出（按 data-format-spec.md 格式）
```

---

## 二、热力学域合成协议

### 2.1 实体设计规则

**实体类型**: `thermal_node`

**广义坐标 q**: 温度 T（标量或向量）
**共轭动量 p**: 热流 J（标量，W）
**典型属性**:

| 属性 | 符号 | 单位 | 典型范围 | 设计方法 |
|------|------|------|---------|---------|
| 质量 | m | kg | 1 ~ 10000 | 根据对象体量设定 |
| 比热容 | C | J/(kg·K) | 100 ~ 2000 | 根据材料查表 |
| 导热系数 | k | W/(m·K) | 0.01 ~ 400 | 根据材料查表 |

**初始温度分布设计**:

| 场景 | 推荐分布 | 说明 |
|------|---------|------|
| 稳态分析 | 均匀温度 + 小扰动 | 验证收敛性 |
| 瞬态分析 | 线性梯度 | 验证热传导方向 |
| 阶跃响应 | 单点高温 + 低温环境 | 验证动态响应 |
| 自然演化 | 随机初始化 [280, 370]K | 验证长期行为 |

### 2.2 因果边设计规则

**机制类型**: `thermal_conduction`（主导）、`thermal_convection`（可选）、`thermal_radiation`（高温场景）

**傅里叶定律参数化**:

```
Q_ij = (k_eff * A_ij / d_ij) * (T_i - T_j)

其中：
  k_eff = 等效导热系数（串联/并联取调和/算术平均）
  A_ij = 传热面积
  d_ij = 传热距离

因果强度 α_ij = min(1, Q_ij / Q_max)
```

**典型因果拓扑**:

```
建筑场景：
  outdoor ──→ wall ──→ room_A ──→ inner_wall ──→ room_B
    │           │                          │            │
    └───────────┘                          └────────────┘
```

### 2.3 仿真参数

| 参数 | 推荐值 | 说明 |
|------|-------|------|
| 积分器 | Störmer-Verlet | 辛积分器，能量守恒 |
| dt | 0.1 ~ 10.0 s | 根据热时间常数选择（τ = mC/kA） |
| 总时长 | 3~5 个热时间常数 | 确保接近稳态 |
| 噪声模型 | Gaussian N(0, σ²) | σ = 0.1 ~ 1.0 K（温度），0.5 ~ 5.0 W（热流） |

### 2.4 哈密顿量定义

热力学类比：

```
动能（类比）：T(p) = sum_i p_i² / (2·C_i·m_i)
  这里 p_i 是热流类比量，C_i·m_i 是热容

势能（类比）：V(q) = sum_{edges} α_ij · k_ij · A_ij / d_ij · (T_i - T_j)² / 2

总能量：E = T + V = const（热平衡时所有温度相等，势能最小化）
```

---

## 三、力学域合成协议

### 3.1 实体设计规则

**实体类型**: `mechanical_body`

**广义坐标 q**: 位移 x（1D/2D/3D）
**共轭动量 p**: 动量 p = m·v
**典型属性**:

| 属性 | 符号 | 单位 | 典型范围 |
|------|------|------|---------|
| 质量 | m | kg | 0.01 ~ 1000 |
| 刚度 | k | N/m | 10 ~ 100000 |
| 阻尼系数 | c | N·s/m | 0.01 ~ 100 |

**初始条件设计**:

| 场景 | 推荐初始条件 |
|------|-------------|
| 自由振动 | 初始位移 + 零速度 |
| 受迫振动 | 零初始 + 周期性外力 |
| 碰撞 | 两物体相向运动 |

### 3.2 因果边设计规则

**机制类型**: `spring_force`（主导）、`damping_force`、`gravitational`

**胡克定律参数化**:

```
F_ij = -k_ij · (x_i - x_j - L_0) · n_ij

其中：
  k_ij = 弹簧刚度
  L_0 = 自然长度
  n_ij = 从 j 到 i 的单位方向向量

因果强度 α_ij = k_ij / k_max
```

### 3.3 仿真参数

| 参数 | 推荐值 |
|------|-------|
| 积分器 | Störmer-Verlet 或 Yoshida 4阶 |
| dt | 0.001 ~ 0.01 s |
| 总时长 | 10~50 个振动周期（T = 2π√(m/k)) |

### 3.4 哈密顿量定义

```
动能：T(p) = sum_i p_i² / (2·m_i)
势能：V(q) = sum_{edges} k_ij·(x_i - x_j - L_0)² / 2 + m_i·g·h_i
总能量：E = T + V = const
```

---

## 四、流体域合成协议

### 4.1 实体设计规则

**实体类型**: `fluid_cell`

**广义坐标 q**: 压力 P（Pa）
**共轭动量 p**: 质量流率 J_m（kg/s）
**典型属性**:

| 属性 | 符号 | 单位 | 典型范围 |
|------|------|------|---------|
| 体积 | V | m³ | 0.001 ~ 10 |
| 粘度 | μ | Pa·s | 0.001 ~ 1 |
| 密度 | ρ | kg/m³ | 0.5 ~ 1500 |

### 4.2 因果边设计规则

**机制类型**: `pressure_driven_flow`

**参数化**:

```
J_m = (P_i - P_j) / R_ij

其中 R_ij = 128·μ·L / (π·D⁴)（Hagen-Poiseuille）
```

### 4.3 仿真参数

| 参数 | 推荐值 |
|------|-------|
| 积分器 | Störmer-Verlet |
| dt | 0.01 ~ 1.0 s |
| 总时长 | 压力平衡时间常数 |

---

## 五、多域耦合合成协议

### 5.1 耦合方式

| 耦合对 | 耦合机制 | 因果边类型 |
|--------|---------|-----------|
| 热 ↔ 力 | 热膨胀/温度相关刚度 | `thermal_expansion` |
| 力 ↔ 流 | 压力驱动变形 | `pressure_deformation` |
| 热 ↔ 流 | 对流传热 | `thermal_convection` |
| 化 ↔ 热 | 放热/吸热反应 | `chemical_heat` |

### 5.2 设计原则

1. **先单域后耦合**：先确保每个单域能正确仿真，再加耦合边
2. **时间步统一**：取所有域中最小的 dt 作为全局步长
3. **弱耦合优先**：先用单向耦合（热→力），验证后再加双向

---

## 六、场景模板库

### 6.1 热力学模板

#### 模板 A：简单双节点热传导

```
实体：heater (T=400K) → conductor → sink (T=300K)
边：heater → sink, thermal_conduction
验证：温度趋近平衡 T_eq = (m1·C1·T1 + m2·C2·T2) / (m1·C1 + m2·C2)
用途：验证因果传播方向、能量守恒
```

#### 模板 B：建筑三房间

```
实体：outdoor, wall_north, room_A, inner_wall, room_B
边：6 条 thermal_conduction
验证：温度梯度分布、稳态热流
用途：验证多实体因果图、复杂拓扑
```

#### 模板 C：制冷循环

```
实体：compressor, condenser, expansion_valve, evaporator, cold_room
边：热传导 + 压缩功 + 节流
验证：制冷系数 COP
用途：验证循环因果、能量输入/输出
```

### 6.2 力学模板

#### 模板 D：弹簧-质量系统

```
实体：mass_1, mass_2, wall (固定)
边：wall→m1 (spring), m1→m2 (spring), m1→ground (damping)
验证：固有频率 ω = √(k/m)
用途：验证振动响应、能量守恒
```

### 6.3 复合模板

#### 模板 E：热力耦合

```
实体：heated_rod (热), mass_on_spring (力)
边：thermal_conduction + thermal_expansion
验证：温度升高 → 热膨胀 → 弹簧力变化
用途：验证跨域因果传播
```

---

## 七、因果边的知识来源与置信度标注

> 对应 CDA §6.1.1 KnowledgeDrivenBootstrapper 的置信度层级。

合成数据中的每条因果边必须标注 `source_knowledge` 和 `confidence`，以便 NOTEARS 因果发现算法正确使用先验。

### 7.1 知识来源层级

| `source_knowledge` 值 | 对应 CDA 置信度 | 说明 | 合成数据中的使用场景 |
|-----------------------|----------------|------|-------------------|
| `physics_equation` | 0.95 | 物理方程直接推导（傅里叶定律、牛顿运动方程等） | 基于物理公式生成的因果边 |
| `topology_diagram` | 0.90 | 工程拓扑图（P&ID、电气接线图） | 基于系统拓扑设计的连接关系 |
| `equipment_manual` | 0.80 | 设备手册（型号参数、连接关系） | 空调/散热器等设备参数 |
| `expert_annotation` | 0.60 | 专家标注（因果关系的自然语言描述） | 用户描述的非精确因果关系 |
| `maintenance_log` | 0.40 | 运维日志（异常事件与修复记录） | 历史数据推断的因果关系 |
| `data_inferred` | 0.20 | 从观测数据中自动推断 | 因果发现算法的输出 |

### 7.2 标注规则

**规则 1：物理公式生成的边 → `physics_equation` + confidence 0.95**

```json
{
  "source_id": 0, "target_id": 1,
  "mechanism_type": "thermal_conduction",
  "strength": 0.85,
  "confidence": 0.95,
  "source_knowledge": "physics_equation"
}
```

**规则 2：系统拓扑定义的连接 → `topology_diagram` + confidence 0.90**

```json
{
  "source_id": 1, "target_id": 2,
  "mechanism_type": "thermal_conduction",
  "confidence": 0.90,
  "source_knowledge": "topology_diagram"
}
```

**规则 3：设备控制行为 → `equipment_manual` + confidence 0.80**

```json
{
  "source_id": 2, "target_id": 2,
  "mechanism_type": "thermal_convection",
  "confidence": 0.80,
  "source_knowledge": "equipment_manual"
}
```

**规则 4：不确定性递减**：当同一因果边有多个知识来源时，取最高的置信度。

---

## 八、噪声与不完整性模拟

### 7.1 传感器噪声模型

```python
def add_sensor_noise(trajectory, config):
    """
    config:
      temperature_noise_std: float  # K
      heat_flux_noise_std: float    # W
      missing_probability: float    # 0~1, 每个时间步的缺失概率
      outlier_probability: float    # 0~1, 异常值概率
    """
```

### 7.2 推荐噪声配置

| 场景 | 温度噪声 | 热流噪声 | 缺失率 | 异常率 |
|------|---------|---------|--------|--------|
| 理想验证 | 0.01 K | 0.1 W | 0% | 0% |
| 实验室传感器 | 0.1 K | 1.0 W | 1% | 0.1% |
| 工业传感器 | 0.5 K | 5.0 W | 5% | 1% |
| 恶劣环境 | 1.0 K | 10.0 W | 10% | 5% |

### 7.3 因果边缺失模拟（用于验证因果发现）

故意从 ground truth 图中删除部分边，生成"不完整图"，用于验证 NOTEARS 等因果发现算法能否恢复缺失的边。

```json
{
  "generation_config": {
    "ground_truth_graph": "full.graph.json",
    "edge_removal_rate": 0.3,
    "removed_edges": [
      {"source_id": 0, "target_id": 2},
      {"source_id": 1, "target_id": 3}
    ],
    "purpose": "test_causal_discovery"
  }
}
```


path: references/thermal-building-example.json
content: {
  "version": "0.1.0",
  "format": "cda-graph",
  "metadata": {
    "name": "building_thermal_system",
    "domain": "thermodynamics",
    "description": "三房间建筑热力学系统：outdoor → wall_north → room_A → inner_wall → room_B，含空调（room_A）和散热器（room_B）",
    "entity_count": 5,
    "edge_count": 6,
    "created_by": "cda-data-synth",
    "creation_time": "2026-04-27T03:00:00Z",
    "scenario": "phase1_verification"
  },
  "entities": [
    {
      "id": 0,
      "name": "outdoor",
      "type": "thermal_node",
      "domain": "thermodynamics",
      "position": {
        "values": [305.0],
        "coordinates": ["temperature_K"],
        "units": ["K"]
      },
      "momentum": {
        "values": [0.0],
        "coordinates": ["heat_flux_W"],
        "units": ["W"]
      },
      "attributes": {
        "mass": 1e10,
        "specific_heat": 1005.0,
        "thermal_conductivity": 0.026,
        "volume": 1e7,
        "material_type": "air",
        "is_boundary": true
      },
      "belief": {
        "distribution_type": "gaussian",
        "mean": [305.0, 0.0],
        "covariance": [[0.01, 0.0], [0.0, 0.1]]
      }
    },
    {
      "id": 1,
      "name": "wall_north",
      "type": "thermal_node",
      "domain": "thermodynamics",
      "position": {
        "values": [300.0],
        "coordinates": ["temperature_K"],
        "units": ["K"]
      },
      "momentum": {
        "values": [50.0],
        "coordinates": ["heat_flux_W"],
        "units": ["W"]
      },
      "attributes": {
        "mass": 500.0,
        "specific_heat": 840.0,
        "thermal_conductivity": 0.8,
        "volume": 0.2,
        "material_type": "brick",
        "thickness": 0.3
      },
      "belief": {
        "distribution_type": "gaussian",
        "mean": [300.0, 50.0],
        "covariance": [[1.0, 0.0], [0.0, 5.0]]
      }
    },
    {
      "id": 2,
      "name": "room_A",
      "type": "thermal_node",
      "domain": "thermodynamics",
      "position": {
        "values": [295.0],
        "coordinates": ["temperature_K"],
        "units": ["K"]
      },
      "momentum": {
        "values": [0.0],
        "coordinates": ["heat_flux_W"],
        "units": ["W"]
      },
      "attributes": {
        "mass": 200.0,
        "specific_heat": 1005.0,
        "thermal_conductivity": 0.026,
        "volume": 160.0,
        "material_type": "air",
        "has_ac": true,
        "ac_power": -1500.0,
        "ac_setpoint": 293.0
      },
      "belief": {
        "distribution_type": "gaussian",
        "mean": [295.0, 0.0],
        "covariance": [[0.5, 0.0], [0.0, 10.0]]
      }
    },
    {
      "id": 3,
      "name": "inner_wall",
      "type": "thermal_node",
      "domain": "thermodynamics",
      "position": {
        "values": [293.0],
        "coordinates": ["temperature_K"],
        "units": ["K"]
      },
      "momentum": {
        "values": [20.0],
        "coordinates": ["heat_flux_W"],
        "units": ["W"]
      },
      "attributes": {
        "mass": 300.0,
        "specific_heat": 840.0,
        "thermal_conductivity": 0.6,
        "volume": 0.15,
        "material_type": "concrete",
        "thickness": 0.2
      },
      "belief": {
        "distribution_type": "gaussian",
        "mean": [293.0, 20.0],
        "covariance": [[0.5, 0.0], [0.0, 2.0]]
      }
    },
    {
      "id": 4,
      "name": "room_B",
      "type": "thermal_node",
      "domain": "thermodynamics",
      "position": {
        "values": [290.0],
        "coordinates": ["temperature_K"],
        "units": ["K"]
      },
      "momentum": {
        "values": [0.0],
        "coordinates": ["heat_flux_W"],
        "units": ["W"]
      },
      "attributes": {
        "mass": 180.0,
        "specific_heat": 1005.0,
        "thermal_conductivity": 0.026,
        "volume": 140.0,
        "material_type": "air",
        "has_heater": true,
        "heater_power": 800.0
      },
      "belief": {
        "distribution_type": "gaussian",
        "mean": [290.0, 0.0],
        "covariance": [[0.5, 0.0], [0.0, 5.0]]
      }
    }
  ],
  "edges": [
    {
      "source_id": 0,
      "target_id": 1,
      "mechanism_type": "thermal_conduction",
      "mechanism_params": {
        "conductivity": 0.8,
        "cross_section_area": 20.0,
        "distance": 0.3,
        "function_form": "fourier_law",
        "effective_coefficient": 53.33
      },
      "strength": 0.85,
      "delay": 0.0,
      "confidence": 0.95,
      "source_knowledge": "physics_equation"
    },
    {
      "source_id": 1,
      "target_id": 2,
      "mechanism_type": "thermal_conduction",
      "mechanism_params": {
        "conductivity": 0.8,
        "cross_section_area": 20.0,
        "distance": 0.3,
        "function_form": "fourier_law",
        "effective_coefficient": 53.33
      },
      "strength": 0.80,
      "delay": 0.0,
      "confidence": 0.95,
      "source_knowledge": "physics_equation"
    },
    {
      "source_id": 2,
      "target_id": 3,
      "mechanism_type": "thermal_conduction",
      "mechanism_params": {
        "conductivity": 0.6,
        "cross_section_area": 15.0,
        "distance": 0.2,
        "function_form": "fourier_law",
        "effective_coefficient": 45.0
      },
      "strength": 0.75,
      "delay": 0.0,
      "confidence": 0.90,
      "source_knowledge": "physics_equation"
    },
    {
      "source_id": 3,
      "target_id": 4,
      "mechanism_type": "thermal_conduction",
      "mechanism_params": {
        "conductivity": 0.6,
        "cross_section_area": 15.0,
        "distance": 0.2,
        "function_form": "fourier_law",
        "effective_coefficient": 45.0
      },
      "strength": 0.75,
      "delay": 0.0,
      "confidence": 0.90,
      "source_knowledge": "physics_equation"
    },
    {
      "source_id": 2,
      "target_id": 2,
      "mechanism_type": "thermal_convection",
      "mechanism_params": {
        "h_convection": 10.0,
        "area": 5.0,
        "function_form": "ac_cooling",
        "controlled": true,
        "setpoint": 293.0,
        "max_power": 1500.0,
        "control_law": "proportional",
        "kp": 50.0
      },
      "strength": 0.60,
      "delay": 0.0,
      "confidence": 0.80,
      "source_knowledge": "equipment_manual"
    },
    {
      "source_id": 4,
      "target_id": 4,
      "mechanism_type": "thermal_convection",
      "mechanism_params": {
        "h_convection": 8.0,
        "area": 3.0,
        "function_form": "heater",
        "controlled": true,
        "power": 800.0,
        "control_law": "on_off",
        "threshold_temp": 288.0
      },
      "strength": 0.55,
      "delay": 0.0,
      "confidence": 0.80,
      "source_knowledge": "equipment_manual"
    }
  ],
  "initial_state": {
    "timestamp": 0.0,
    "hamiltonian": {
      "initial_total_energy": 55270.0,
      "note": "Sum of thermal energy across all entities: E_i = m_i * C_i * T_i"
    }
  },
  "hamiltonian_definition": {
    "type": "thermal_analogy",
    "kinetic_energy": {
      "formula": "T = sum_i p_i^2 / (2 * C_i * m_i)",
      "note": "p_i is heat flux (thermal momentum analogy)"
    },
    "potential_energy": {
      "formula": "V = sum_edges (k_eff * A / d) * (T_i - T_j)^2 / 2",
      "note": "Pairwise thermal interaction energy"
    },
    "conservation_quantity": "total_thermal_energy",
    "tolerance": 1.0e-4,
    "note": "Not strictly conserved due to AC and heater (energy sources/sinks)"
  }
}

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)