ESML — 能源系统建模语言

ESML 把声明式模型编译成扁平方程系统：结构分析 → 指标约简 → 因果化/撕裂 → 稳态牛顿求解或时间积分。公开面是引擎核心（solve / simulate / import / check）；常驻数字孪生会话（DTIL：session / predict / snapshot）属于商业版。

能力

• 声明式建模：变量、参数、方程、组件、连接、数组与序集。
• 编译：展平、结构分析、指标约简、因果化与撕裂。
• 求解：稳态牛顿、显式/隐式时间积分、优化族与任务调度。
• 导入/导出：多种建模与仿真格式、FMU、CSV、报告。
• 客户端：MIT Python / Julia，通过公开 JSON 协议调用引擎，不含引擎代码。

下载与安装

从 最新发布 下载学术版（Linux x86_64）：

tar -xzf esml-academic-1.8.1-linux-x86_64.tar.gz
export ESML_HOME="$PWD/esml-academic-1.8.1-linux-x86_64"
"$ESML_HOME/esml" --version

包内含引擎、物性后端 libesml_mmprops_ffi.so、模型库 library/、教程与烟测脚本。 客户端用 ESML_BIN 指向这个二进制即可，不需要编译器或引擎源码。

快速开始：IEEE 300 潮流

"$ESML_HOME/esml" solve \
  "$ESML_HOME/library/domains/power/cases/case300.comp.esml" \
  -L "$ESML_HOME/library" --json

输出 unknowns = 4604；本机实测整进程约 0.32 s。更多步骤见 IEEE 300 十分钟教程。

结果里有什么

--json 返回的不只是数值，而是一份可直接入库/后处理的结果契约：

{
  "apiVersion": "esml.solve/v1",
  "system": "Demo",
  "unknowns": 2,
  "values": [
    { "path": "tclab.T1", "value": 339.007, "unit": "K" }
  ],
  "meta": {
    "engineVersion": "1.8.1",
    "docHash": "612e8b85…",
    "durationMs": 0.423,
    "converged": true,
    "unitCoverage": { "known": 2, "total": 2, "complete": true }
  }
}

• values[].unit：一致 SI 单位下的量纲表达式；模型未声明单位时为 null，引擎不猜。
• meta.docHash：源文件 SHA-256，可作缓存/归档键。
• meta.converged：成功信封恒为 true；未收敛非零退出，不会返回半个结果。
• unitCoverage：有多少变量真正带了单位，一眼判断能否进入带单位后处理。

完整字段、失败语义与客户端映射见结果契约。

Python 与 Julia

pip install git+https://github.com/ai4energy/esml-python@v0.2.0

from esml import solve

out = solve(
    "library/domains/power/cases/case300.comp.esml",
    libraries=["library"],
)
print(out.unknowns, out.values["b1.net.Vm"])
print(out.meta["engineVersion"], out.meta["unitCoverage"])

using Pkg
Pkg.add(url = "https://github.com/ai4energy/ESML.jl", rev = "v0.2.0")

using ESML

out = solve("library/domains/power/cases/case300.comp.esml"; libraries = ["library"])
println(out.unknowns, " ", out.values["b1.net.Vm"])

客户端均为 MIT，公开面是一次性 solve / simulate；不保留状态。常驻会话请使用商业版引擎。

学术版与商业版

版本	展平未知量	能力
学术版（公开下载）	≤ 16,384	引擎核心；学术/教学/个人非商业免费
商业版	无限制	完整能力，含 DTIL 常驻会话；商业用途需授权

IEEE 300（4,604）在学术版范围内；IEEE 2869（56,920）、1354（25,672）、9241（194,664） 需要商业版。超限模型在求解前响亮报错，给出实际规模、上限与联系方式，不会静默降阶。

教程与文档

• 结果契约：solve / simulate 返回什么
• IEEE 300 十分钟教程（命令行 / Python / Julia）
• 常见问题
• 排错
• 客户端：esml-python · ESML.jl

XML 校验（XSD）

canonical XSD 已发布在站内：https://docs.ai4energy.cn/schema/。推荐用 esml-canonical-basic.xsd 做内容校验；esml-v1.xsd 做轻量入口检查。 详见 XSD 与 XML 校验（含 xmllint / lxml 示例，IEEE 300 用例实测通过）。

许可

ESML 引擎是商业软件（不是 MIT）。学术/教学/个人非商业用途免费；商业用途需取得 商业许可 —— mingtao.li@gmail.com。客户端（Python / Julia）为 MIT。 完整条款见 ai4energy/esml 的 LICENSE.md。