真实的世界 · RealWorld Sim

一个"按物理规律说话"的工程沙盒：把零件、材料、液体、电机、PLC 程序放进去，软件按真实物理算它 扛不扛得住、转不转得动、热不热、做不做得出来——目标是像《我的世界》一样搭东西，但搭出来的东西在现实里真的能做。

现阶段是工程估算工具，不能替代实测和正式设计校核。每个模块都写明了哪些已验证、哪些是估算。 给 AI 代理：本仓提供 llms.txt（机器可读能力/接口/反馈入口）与 python3 diag.py（诊断摘要 JSON）；Web 版 OpenAPI 在 /openapi.json。 每个模块"干什么+一键示例+看什么"见 docs/GUIDE.md。

License: MIT（见 LICENSE）。

项目定位（用户 2026-10-13 阐述）

做淬火设备和电源的目的是能真正生产。现实中电源易出故障，要靠测试和版本升级持续优化性能，尽量缩小理论与现实的差距。本软件的作用是在设备做出之前和之后，在软件里模拟真实设备长时间运行、暴露问题，并区分是软件的问题还是设备设计的问题。两套系统——真实设备（私有设计仓）与本仿真——对照走。

项目方向（2026-10-13 用户定）：仿真阶段不计较器件成本，优先功能做满测透；功能立住后再做降本迭代。功率等级逐级爬升：先把 100 kW 级做到优秀，再研发更高等级。

现在能做什么

安装（Ubuntu 22.04 / 24.04 桌面）

./install_ubuntu.sh   # 第一次
./run.sh              # 打开软件
.venv/bin/python validate.py   # 自检

# 只装某个模块的最小依赖（打包成 pip 包后）：pip install "realworld-sim[induction|world3d|flow|mcu|web|desktop|all]"
# 各模块对应的最小安装命令见 docs/GUIDE.md；requirements.txt = 全量，等价 [all,web,desktop]

电路仿真需要 ngspice：install_ubuntu.sh 里已包含 sudo apt install ngspice。 可选的 Cortex-M 核心需要 unicorn：./install_ubuntu.sh --with-unicorn（或 .venv/bin/pip install unicorn），不装也能用其它全部功能。 可选的非圆截面涡流需要 gmsh：pip install gmsh，不装也能用其它全部功能。

Web 版（云端化，v0.16 起）

普通 Linux 云主机即可跑（无需桌面环境）：

pip install -r requirements.txt -r requirements-web.txt
python3 -m uvicorn web.server:app --host 0.0.0.0 --port 8000
# 浏览器打开 http://服务器IP:8000

已接入：感应加热淬火（参数表单 → 后台任务 → 温度场/硬度/曲线 SVG 图 + 结果摘要）、材料库查询、三维装配世界（13 个预设场景 → three.js 交互查看器：旋转/缩放/逐帧动画，零件按体检状态着色）、PLC 虚拟调试（FX 指令表可编辑 → 整段运行 → 逻辑分析仪时序图 + 节拍统计，含急停演示剧本）、流体三算例（管网泵/阀/喷淋 + 水锤 + 水箱放空射流，图同桌面版）、单片机+PLC 联合仿真（AVR+FX3U+半桥电路，过流保护演示，关键时刻波形实测）、电路仿真（5 个示例电路或自定义 SPICE 网表 → 自动测量 + 波形/频谱/频率响应图；需服务器装 ngspice，未装会明确提示）。任务表已持久化（SQLite），感应淬火任务支持断点续算：运行中周期落检查点，服务器重启/任务中断后一键从断点接着算（实测续算与连续运行终态差 <0.001°C，见 validate_ckpt.py）；感应淬火有速度档：快速模式（分阶段变步长 + EM 求解降频）实测 ×1.6–2.1，水喷常规工况 t8/5 偏差 <0.002 s、硬化层深度和 HRC 不变（见 validate_accel.py），精确档仍是验证基线。已知边界（豆包 12 点实测矩阵）：油淬等慢冷介质 t8/5 绝对偏差可达 0.1 s 级（相对偏差仍小，出精确结论用精确档）；频率偏离 20 kHz 时 HRC 可漂移 ~1，精确报告回精确档（SQLite）：重启不丢历史，中断任务标记可重提，页面带最近任务面板。物理内核与桌面版完全一致（rw 包，无 Qt 依赖），结果同样过 validate 自检。 架构约定面向中期目标——自由组合"拼设备"（电源板 + PLC + 变频器 + 机械件任意组合）+ 长时连续运行（100 h 级、加速仿真）：模块注册表的参数/结果都是纯 JSON、运行函数无状态，后续"拼设备"就是部件连接拓扑 JSON 由图执行器组合模块；长任务将换持久化任务表 + 断点续算（任务表已持久化 SQLite，感应淬火支持断点续算）。

依赖与许可证

本项目没有使用 PySpice（GPLv3），电路部分是自己写的 MIT 封装。单片机部分（AVR 子集 CPU、汇编器、外设层、联合仿真）全部自写，MIT；没有使用 simavr（GPLv3）。

已验证（validate.py）

• 集肤深度：有限元 vs 理论 < 3%；能量守恒：输入 10000 J，工件吸收 9949 J

• 悬臂梁挠度 = 材料力学公式；环形板外缘挠度 vs 解析解 0.4%

• 10 m 水柱 98.07 kPa；水沸点 100.00 °C；200 °C 饱和压力 1.552 MPa（蒸汽表 1.555）

• 层流摩擦系数 64/Re；电机额定点转矩 = P/ω

• PLC 演示程序：加热/淬火时间与程序设定一致

• 电路/示波器（ngspice 44.2；Ubuntu 24.04 官方源是 42，缪斯实测 v42 下同样全部通过）：RC τ 与 63.2% 点误差 <0.01%，上升时间 2.197τ 误差 -0.02%；RLC 谐振频率误差 <0.001%； 运放振荡器频率 vs 2RC·ln3 误差 -0.43%（行为级运放压摆率有限）；FFT 方波 3/5 次谐波 = 1/3、1/5； 示波器 Vpp/Vavg/Vrms/频率/占空比 与解析值一致；整流纹波比近似公式 I/(2fC) 小 18%（公式本身偏保守）

• 电磁升级（v0.9）：非线性谐波平衡 vs 一维时域真值 <1.0%（20–700°C，5–80 kA/m）；线性极限 vs 解析 <0.3%；三维 vs 二维轴对称 −2.5%（粗网格，最低阶棱边单元）；偏心引起的周向功率差是模型结果，未经实测；

• 整机联动（ngspice 44.2）：全桥方波→串联 RLC 的功率，基波近似 vs ngspice 偏差 <0.5%；合旁路冲击电流 RK4 vs ngspice <0.01%；预充电 RC 指数 <0.2%； 电网→母线→逆变器→线圈/工件能量守恒 <0.2%；加热 3 s 工件吸收 17.89 kJ（有限元表 17.83 kJ）；缺水 → 高频关断 720 ms（预计 708 ms + 扫描）

• 三维装配世界（v0.10，MuJoCo 刚体）：自由落体 g 0.00%；钢板桥弯矩 +0.04% / 挠度 +0.04% vs 材料力学；斜面临界角 26–27°（理论 26.57°）、滑动加速度 −0.3%；橡胶块倾倒临界 17.5–19.5°（理论 18.43°）；叠积木临界外伸 0.95–1.05（理论 1.0）；台架反力 −0.21%

• 连接与破坏（v0.12）：26 种国标型材理论重量 vs GB 最大偏差 5.5%（尖角近似忽略圆角，偏轻）；方管截面 I 与解析 0.000%；工字钢梁挠度 vs 材料力学 −2.7%； 壁挂支架螺栓组：接头力/力矩 vs 静力手算 0.00%，螺栓拉/剪力 vs 弹性分配手算 <3%；轴承静态反力 vs 重量 0.00%、3000 rpm 不平衡力 vs m·e·ω² −2.4%、L10 公式复核一致； 赫兹点接触 a/p0 vs 手算 0.0%/0.0%（R10 钢球 100 N：a=0.188 mm、p0=1353 MPa）；断裂判据：玻璃板 20 kg 正常 / 80 kg 断裂（理论断裂载荷 27 kg，分布载荷略高）

• 焊缝与断裂后果（v0.13）：角焊缝群 σ_b/τ vs 手算 0.0%/0.0%；断裂后果：玻璃板断成 2 段后两段倾倒、钢块下落 206 mm（断后失去支撑）

• 非圆截面涡流（v0.14，gmsh 非结构网格，可选依赖）：同几何空心管 vs 结构网格 +2.68% / vs 二维轴对称 +0.16%；方坯 20×20 表层/心部功率密度 19.2×（集肤）、左右对称 1.003、空气假损耗 0.01%；方坯角部 = 面心 0.71（δ 尺度的「冷角」regime，如实标注）；①b 页可直接算方坯并画截面功率热图（v0.15）

• 流体（v0.11）：摩擦系数 vs fluids.friction <1e-4；单管/并联 vs 独立求根 <1e-4；环网 vs 独立 Hardy-Cross <0.01%；泵相似定律 Q∝转速；水箱放空 vs Torricelli 0.00%；水锤瞬关压升 = Joukowsky ρav 0.00%、周期 = 4L/a 0.00%、缓闭 4 s vs Michaud +4%；射流射程 = v²sin2θ/g；气管 vs fluids.compressible 一致

• 材料库：混合法则密度 vs 31 个牌号实测平均偏差 1.3%（最大 3.6%）；互溶模型 vs 二元相图结论 84% 一致

• 单片机（按 AVR 指令手册周期数 / ATmega328P 手册公式，没有和真芯片逐周期对照）：一次延时循环 4613 周期与手工计数一致；中断响应 11 周期； 定时器溢出 976.5625 Hz、CTC 2000 Hz、Fast PWM 20 kHz/30%、62.5 kHz/25%、反相 25%、OCR=0 → 1/256，全部与公式一致； ADC 量化误差最大 0.96 LSB、平均 -0.479 LSB（理论 -0.5）、标准差 0.289 LSB（理论 0.2887）；UART 9615.38 波特，TX 波形独立解码正确

• 联合仿真：按钮 → PLC 输出 12.0 ms（窗口 12–14 ms）；PLC 输出 → 单片机动作 0.2 ms + 21 周期；ADC 超限 → 关驱动 24.562 µs（与理论一致）； 电流越线 → 关驱动 69.3 µs（窗口 24.6–74.6 µs）

• 电路导入回归（v0.11.1，validate_circuit.py）：.options 导入结果与直接 ngspice 一致；IEC/DIN 位号（V=半导体、D=IC）的 .net 按 Sim.Device/库符号/型号/引脚名判型；3/4 脚器件按实际引脚； 热模型烧毁截止与窗口/保持段拼接连续（恒定功率与解析解误差 <1e-6 K）；无激励网表报“无激励源，结果全零”；波形名大小写不敏感

主要近似（未实测校准）

• 磁导率用随温度变化的有效 μr，不是完整 B-H 曲线；淬火换热系数为典型曲线

• 硬度按 45 钢 CCT/回火规律估算，不是金相计算

• 机架接点按刚接；焊缝强度、振动、疲劳未算

• 管路局部阻力系数取手册典型值；电机特性由铭牌推算（Kloss 公式修正）

• 示例里的二极管/三极管/功率 MOSFET/运放是通用模型（典型参数），不是具体厂家型号；要和真板子对比请换成厂家 SPICE 模型

• 示波器的 AC 耦合用“减去整段记录平均值”近似，不是真机的 ~10 Hz 高通；上升时间按屏幕内 Vmin/Vmax 定 10%/90%

• 任意配比合金的熔化范围、电阻率、强度只是粗估范围；浓合金电阻率（镍铬、钛合金）会超出估算上限

• 单片机是 AVR 指令子集，汇编器输出内部指令表（不生成 .hex，不能直接跑 avr-gcc 固件）；没有 Timer1/SPI/I²C/看门狗/EEPROM；引脚输入无同步器延时

• PLC 输入滤波 10 ms、输出延时 0.2 ms、扫描 2 ms 是假设值；行为级固件、ngspice 回放、unicorn 计时都是估算

• 整机联动：主回路是基波平均模型（微秒级开关波形看 ⑥/⑦）；变频器固件是 Python 行为级；工件加热按“能量等效时间”查恒功率有限元表（变功率时表面/心部温度分布与恒功率不同，近似）； 机器参数（10 kW 级、30 kHz、母线 2 mF、预充电阻 100 Ω、线圈热容、保护阈值、线圈 150°C 损坏线、淬火液 45°C 线）都是假设值，不是某台设备实测

• 三维装配世界：摩擦系数是典型值、取两种材料较小者（估算）；接触是 MuJoCo 软接触，冲击峰值力不可信，落重冲击用材料力学公式给保守上界；梁校核是沿长轴一维、接触点分布决定载荷分布（超静定时是近似）；焊成一组的零件当刚体；不含浮力动力学/空气阻力/破坏后碎裂/疲劳；渲染是软件画家算法，穿插很多的复杂场景会有锯齿

• v0.12：型材按尖角分解，质量/惯量比 GB 理论值偏轻 1–5%（忽略圆角）；槽钢/角钢非对称截面只算竖向力绕水平形心轴的弯曲，不算扭转/双力矩与剪切中心； 螺栓组是 bearing 型弹性分配（直接剪+偏心转动剪+轴向拉+弯矩），不含撬力放大、预紧力、被连接件变形与承压板校核；螺栓只算拉不算压（压由被连接件接触传）； 轴承只有深沟球径向载荷（P=Fr），额定为典型样本值，不含寿命修正 a_ISO；赫兹接触是静态弹性解，p0 超屈服不一定失效；断裂判据只看最大应力 vs 抗拉强度，不含应力集中系数、裂纹与疲劳

• 流体：水锤不模拟汽穴（负压到蒸气压后的撞击更大，只报警）；管网准稳态（忽略管内惯性）；泵曲线二次拟合；射流不计空气阻力；阀 K 随开度按 K/开度² 简化；示例管路参数是假设值

路线图

v0.5 材料库 → v0.6 电路板仿真 + 虚拟示波器 → v0.7 单片机仿真接 PLC（已完成）→ v0.8 整机联动（已完成）→ v0.9 电磁升级：非线性 B-H、导磁体、三维涡流（已完成）→ v0.10 三维装配世界：零件摆放 + 刚体物理 + 受力体检（已完成）→ v0.11 流体：管网/泵/水锤/射流（已完成）→ v0.12 连接与破坏：型材库、螺栓组、轴承寿命、赫兹接触、断裂判据（已完成）→ v0.13 焊缝校核 + 断裂后果演示（已完成）→ v0.14 非圆截面涡流（gmsh 非结构网格，已完成）→ v0.15 方坯涡流 GUI 接入（已完成）→ v0.16 云端化第一阶段：Web 版（FastAPI + 感应淬火/材料库，已完成）→ v0.17 实测反馈修复（已完成）→ v0.18 三维装配世界上 Web（three.js 交互查看器 + 型材接触对修复，已完成）→ v0.19 PLC 虚拟调试上 Web（指令表 + 设备模型 + 逻辑分析仪时序，已完成）→ v0.20 流体三算例上 Web（管网/水锤/放空射流，已完成）→ v0.21 单片机+PLC 联合仿真上 Web（已完成）→ v0.22 任务持久化（SQLite 任务表 + 历史面板 + 重启清理，已完成）→ v0.23 实测反馈修复第二批（已完成）→ v0.24 电路仿真上 Web（5 示例 + 自定义网表，需服务器装 ngspice，已完成）→ v0.25 断点续算（感应淬火检查点落盘 + 中断续算 + 参数指纹防误续，已完成）→ v0.26 加速仿真第一档（变步长 + EM 降频 ×1.8，已完成）→ v0.27 事件触发 EM 重解（温度变化 >25K 立即重解，居里区非线性自动收紧 10K：15kW 激进工况峰值温度误差 9.9→4.6°C，常规工况零回归，已完成）→ v0.28 符号组装热步（sparsity pattern 一次构建 + P1 几何张量预计算，热步提速 ~50%、整机 ~20%，结果与通用 asm 偏差 ~1e-12 浮点噪声，构建时自校验失败自动回退，已完成）→ v0.29 本地主分支合入（Hark 材料：电路器件库/应力校核/拓扑告警、整机 100kW 通用机+满功率考核、电磁辅助体/导磁体温度反馈/辐射、流体 NPSHa+100kW 冷却、材料 mix 边界、GUI 截图校验，已完成）→ v0.30 问题单复验修复批（卡布逐张复验 12 项：①三相电网 LL 浪涌极性接反——正浪涌曾被反向注入 -643 V 尖峰，已修正并加方向回归；②母线预充/泄放改指数精确 RC 更新——显式 Euler 在 dt>τ 时过冲到 1295 V 非物理值，新格式全 dt 误差 ~1e-4 V，R_pc/R_bleed/C_bus 非法值明确 ValueError；③事件历史改有界（2×EV_MAX 批量修剪，内存不再无限增长）；④材料 mix 拒绝 NaN/Inf/非数值（曾静默丢弃或 KeyError）；⑤ngspice 一切非零退出码拒绝解析（普通非零曾当成功）；⑥圆管惯量改圆环公式显式 ——曾按实心圆柱几何+环形质量致惯量全非物理，非法尺寸建模层拒绝；⑦KiCad 值统一提取——fields Value/位置式 property 曾读不出或崩溃；⑧负载短路加谐振电容过压硬件比较器默认检测延时 2 µs（旧文20 µs为笔误；关断还有离散步边界），电感储能续灌使本模型电容峰值约 3130 V 仍超额定峰值 11%，verdict 如实 WARN。20 µs敏感性对照约3711 V；这不是器件选型或实机保护延时认证，须核实全链延时、吸收/回馈与器件条件，详见 短路瞬态能量账。4 项复验未复现：1946/1954/1822/1825，已完成）→ v0.30.2 PLC 畸形输入装载期校验（豆包 P2-2/P3-1 复测 5 项全部复现成立：LD 缺操作数/ANB·MPP 空栈/MOV 非法 K·H 常数裸异常、MOV 可写输入 X、非法八进制地址（Y80）静默通过，另连带 OUT T 缺设定值运行期才崩同批修掉：现一律装载期抛带原程序行号的业务异常，新增 MPS/MRD/MPP 配平与 ANB/ORB 块结构静态检查、ZRST 起止类型不一致改业务异常（原裸 assert）；web 回归新增 6 条断言，全套件绿，已完成）→ 下一步：矩阵分解复用/BDF2（等调研）、断点续算推广、网格划分与 3D 零件库再扩充、1945 全回归（R/C/L/D/源/变压器）、1821 吸收回路建模

更新记录见 CHANGELOG.md。欢迎提 Issue 和 PR。

许可

MIT