# stirling_engine_sim

**Repository Path**: seaoftranquility/stirling_engine_sim

## Basic Information

- **Project Name**: stirling_engine_sim
- **Description**: simulations, analysis and optimizations on a stirling engine with matlab and ansys
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 斯特林发动机数字孪生（stirling-sim）

> 课程设计：基于 STEP 几何的微型斯特林发动机数字孪生（M1–M5） | 最后更新：2026-10-22 11:06 CST
> 工作目录 `E:\Design Engineering\stirling-sim\` | MATLAB R2025b + ANSYS Student 2026R1 + Python 3.13

## Viewer v3（2026-10-28）

`viewer/stirling_step_viewer.html` 升级为 v3：**模型树 UI（Ansys 式）+ KaTeX 公式卡**；
热端缸温度场升级为 **10×8 扇区解析热网络**（热点随火焰三维移动、置换器→轴→导套导热链可见、
T_amb=22 °C）；气体粒子改为 **布朗运动**（Langevin/OU，V_rms∝√T）；新增 **M3 动力学移植**
（δ/飞轮/启动，与 MATLAB S12 对口径验证）与 **二阶损失模型**（再生缺失/泄漏/机械，
本机无再生器 → η 从 57.8% 崩塌到 ~1% 是诚实结论）；**MAPDL 连杆 FEA 叠层**（12,277 节点）。
验证全绿：`verify_viewer.py` + `validate_viewer.cjs` 42/42 + 三个 node 自检套件。
详见 `viewer/VIEWER_MANUAL.md` §0.5。

## 1. 项目概述

以 `stirling engine.step` 为**唯一结构真源**（D0 STEP-first 铁律），建立从热力学（M1）到
两档优化（M5）的完整数字孪生链，全部结论可复现、全部数值有溯源。

**双档结论**（任务书口径：0.1 W 保底 / 0.5 W 目标，双口径 P_i 与 P_shaft=0.3·P_i）：

| 档 | 结论 | 条件 |
|---|---|---|
| 档 1（0.1 W） | **P_shaft_min = 0.2519 W（2.52× 门限）** | v1 几何 + p=2 atm + T_h=700 K + N=1200 rpm |
| 档 2（0.5 W） | **可达（v2-c = 0.5000 W 最小改动；域内最大 3.58 W）** | 缸径×1.122、行程×1.104、死区×0.595、p×1.13 + 配套（飞轮 J×21.2、轴承 624、密封实封） |

## 2. 目录结构

```
stirling-sim/
├── config/            # 单源参数链 (engine_params.json/m, sha256 溯源, DO NOT EDIT)
├── core/
│   ├── M1_thermo/     # Schmidt (gamma_exact) + 泄漏敏感性 + Phase1 出口
│   ├── M2_kinematics/ # 曲柄滑块闭式解 + λ 扫描
│   ├── M3_dynamics/   # 气体力→转矩、飞轮 sizing、转速波动、发电机负载(T5.5)
│   ├── M4_stress/     # 手算、梁模型、PDE 三源、轴承 L10、BOM
│   └── M5_opt/        # 向量化内核、扫描、灵敏度、两档优化、改动清单
├── tests/             # 8 个测试文件 (test_*.m, run_all_tests 自动发现)
├── tools/             # STEP 提取、config 生成、MAPDL/PDE 工具、反标定
├── viewer/            # WebGL 数字孪生 (stirling_step_viewer.html + VIEWER_MANUAL.md)
├── serve_viewer.ps1   # 一键起本地 HTTP 服务 (viewer 必须走 HTTP，file:// 会被拦截)
├── ansys/             # MAPDL 批处理 (M4) + Motion/Fluent 指南 (T5.3/T5.4)
├── figs/              # 全部图表 (≥150 dpi, 中文图注)
├── logs/              # 每步日志 + 摘要 JSON (数值溯源)
└── report/            # 出口报告 + master_report.pdf + 测量协议 + 创造性应用
```

## 3. 如何复现

> ⚠️ 运行环境说明：本机默认是 **Windows PowerShell 5.1**，它**不支持 `&&`**（那是 PowerShell 7+ 才有的运算符）。
> 因此下面「手动分步」给出 PowerShell 5.1 可直接粘贴的命令；若改用 **Git Bash** 或 **PowerShell 7 (`pwsh`)**，
> 原 `&&` 写法可直接用（仅需把 `cmd //c` 改为 `cmd /c`、路径改为 `E:\...` / `E:/...` 风格）。

### 3.1 一键脚本（推荐）

项目根目录已提供 `stirling_run.ps1`，按 ①测试 → ②参数链 → ③M4 FEA → ④报告 PDF 顺序执行，
任一步失败即停（`$LASTEXITCODE` 检查）。先把脚本顶部 `$ProjectRoot` 改成你机器上的真实路径，再运行：

```powershell
powershell -ExecutionPolicy Bypass -File 'E:\Design Engineering\stirling-sim\stirling_run.ps1'
```

### 3.2 手动分步（Windows PowerShell 5.1）

```powershell
# 0) 进入项目根（改成你机器上的真实路径）
$root = 'E:\Design Engineering\stirling-sim'
Set-Location $root

# 1) 全套件测试（8/8, 68 断言）
& '.\tools\matlab_utf8.bat' "cd('$root'); addpath(genpath(pwd)); run_all_tests"

# 2) 参数链复现（config 生成）
python tools/step_extract.py
python tools/section_record.py
python tools/gen_engine_params_m.py

# 3) M4 FEA（MAPDL 批处理；run_mapdl.bat 可从任意 CWD 调用，自动经 %TEMP% 中转）
#    输出落在 .dat 同目录: <model>_out.txt + dat 内 *CFOPEN 指定的 csv
#    conrod_model.dat 是 ESIZE=0.40 fine 档: 刷新 conrod_res_fine.csv,
#    不会覆盖 coarse 档 conrod_res.csv — 两档证据互不毁坏
& '.\ansys\M4_mapdl\run_mapdl.bat' conrod_model.dat

# 4) 总报告 PDF（publish）
matlab -batch "cd('$root'); addpath(genpath(pwd)); publish(fullfile(pwd,'report','master_report.m'), struct('format','pdf','outputDir',fullfile(pwd,'report')))"
```

### 3.3 若使用 Git Bash / PowerShell 7（`&&` 可用）

```bash
# 全套件测试（内层引号用 \" 转义，整体包在双引号里传给 cmd /c）
cmd /c "tools\\matlab_utf8.bat \"cd('E:/Design Engineering/stirling-sim'); addpath(genpath(pwd)); run_all_tests)\""

# 参数链复现（config 生成）
python tools/step_extract.py && python tools/section_record.py && python tools/gen_engine_params_m.py

# M4 FEA（MAPDL 批处理）
cd ansys/M4_mapdl && cmd /c run_mapdl.bat conrod_model.dat

# 总报告 PDF（publish）
matlab -batch "cd('E:/Design Engineering/stirling-sim'); addpath(genpath(pwd)); publish(fullfile(pwd,'report','master_report.m'), struct('format','pdf','outputDir',fullfile(pwd,'report')))"
```

## 4. 测试状态（run_all_tests 8/8 = 68 断言）

| 测试 | 断言 | 覆盖 |
|---|---|---|
| test_M1 | 19 | fixture 1e-12、物理极限、p-V 顺时针、卡诺断言 |
| test_leakage | 12 | δ³ 标度、单调性、持压诊断、独立交叉核对 |
| test_kinematics | 6 | 闭式 vs 数值微分、λ→0 退化、双活塞 |
| test_dynamics | 4 | 能量法 vs ode45、飞轮 J-δ、启动阈值 |
| test_stress | 14 | 手算 n≥1.2、梁平衡/解析、MAPDL 两档 <5%、三源 <15%、L10、BOM |
| test_m5opt | 7 | 向量化内核一致性、可行性筛、确定性、OAT 符号、两档、证书、v1 复现 |
| test_meas_backcalc | 3 | η_m 合成数据恢复 ±3%、V²/R 口径一致、输入校验 |
| test_gen_load | 3 | 空载线性、工作点残差、选型自洽 |

## 5. 报告索引

| 文档 | 内容 |
|---|---|
| `report/master_report.pdf` | **总报告**（任务书要求逐条映射） |
| `report/phase1_exit.md` | M1 热力学 + 密封/间隙敏感性 |
| `report/phase2_kinematics_dynamics.md` | M2 运动学 + M3 动力学 |
| `report/phase3_stress_bearing.md` | M4 强度/FEA/轴承/BOM + 三源验证 |
| `report/phase4_optimization.md` | M5 两档优化 + v2 改动清单 |
| `report/measurement_protocol.md` | T5.1 测量协议（样机未造 ⇒ 设计文档） |
| `report/creative_application.md` | T5.5 创造性应用（发电机方案 + 工作点选型） |
| `ansys/motion_guide.md` / `fluent_guide.md` | 加分终验指南（GUI 执行） |

## 6. WebGL 数字孪生 viewer

浏览器里的交互式 twin：`viewer/stirling_step_viewer.html`（42 个 STEP 实体面片 + Schmidt 循环实时解算）。

```powershell
Set-Location 'E:\Design Engineering\stirling-sim'
python -m http.server 8765 --bind 127.0.0.1     # 或 .\serve_viewer.ps1
# 打开 http://127.0.0.1:8765/viewer/stirling_step_viewer.html
```

细节（三档设计模式 / guards 干涉判定 / Beale·West 诊断 / 设计空间探索 / 部件清单 /
导出 PNG·WebM / 重建 scene.json / 故障排查）见 **`viewer/VIEWER_MANUAL.md`**。
优化变量的分层与边界推导见 **`report/optimization_scope_v2.md`**（脚本 `tools/opt_scope_sweep.py`）。
一致性自测：`python tools/verify_viewer.py` → `ALL CHECKS PASSED`（浏览器 vs MATLAB port，rel err ~1e-14）。

> ⚠️ 服务根目录必须是**项目根**，不能是 `viewer/`（HTML 里 fetch 的是 `../tools/scene.json`）。

## 7. 工程约定（铁律）

- **D0 STEP-first**：结构参数一律取 STEP 提取值；歧义标 `step_ambiguous` 不兜底；
  assumed/textbook 仅限 [T]/[M] 区块。
- **周期积分全权重** `sum(f)*h`（endpoint=False, Nθ=720），禁用 trapz 接缝半权重。
- **死区三档鲁棒**：central/lower/upper 同时可行，达标用三档最小值。
- **诚实报告**：不可达/降级/偏差一律显式记录，不静默通过（测试缺失项 SKIP 并计数）。
- SI 单位制（m, Pa, K, kg, s, rad）；MATLAB 批处理全闭环（无 GUI）。