lujingze/SystemSimulationApp

0 Fork 0

Files

T

huojiarong 2ddaaeb56a 上传 AMESim 参考资料

2026-07-30 10:15:23 +00:00

20 KiB

Raw Blame History

组件模型建模规范 v1

状态：已在 experimental 临时组件库实施
适用对象：人工开发者、代码生成工具和 AI 编程助手
配套读取规范：组件库分类、发现与读取规范 v1

1. 文档目标

本文档规定一个 Python 仿真元件应如何创建、修改、测试和注册。完成后的模型必须同时满足四个使用方：

求解器能够实例化模型并调用方程。
System XML 能够根据稳定类型找到模型。
React Flow 能够自动显示图标、端口和参数。
结果页面能够根据结构化元数据展示变量。

本文档是模型代码的开发合同。若本文档与当前代码行为不一致，应把它视为缺陷：先核对实际实现，再在同一次修改中同步代码、测试和文档，禁止让两套规则长期并存。

2. 开始前先判断任务类型

2.1 新增公开模型

公开模型会出现在前端组件库中，也能被 System XML 创建。必须：

放入某个组件库的分类目录。
实现完整模型契约。
加入该库 library.py 的 models 清单。
添加目录、契约、方程和最小仿真测试。

2.2 修改已有公开模型

必须先判断改动是否破坏已有工程：

改动	版本建议	兼容性要求
修复数值实现但不改变契约	修订版本	旧 XML 和工程继续可用
新增有默认值的参数或结果	次版本	旧工程缺少该字段时必须有迁移或默认值
修改界面名称或图标	库修订版本	不修改机器标识
修改方程的物理语义	根据影响提高次版本或主版本	补充基准和变更说明
删除、改名端口或参数	主版本	必须设计工程和 XML 迁移
修改 `MODEL_TYPE`	视为新模型	旧类型必须保留迁移映射

2.3 新增内部模型

仅供固定算例或研究代码使用、不进入前端目录的模型，不加入 library.py。这类模型应放在对应 examples/ 或专用系统目录，不能与公开模型混放后依赖扫描规则排除。

当前示例是 app/simulation/examples/testmodel/dynamic_pipe.py。

2.4 新增物理域

仅新增模型类不足以支持新物理域。除了模型，还必须设计：

PortDefinition 和端口变量。
变量角色与连接规则。
网络兼容性检查。
代数方程和 stream/signal 传播。
XML 端口协议。
前端连线兼容规则。
最小闭合系统与求解测试。

没有完成这些基础能力时，不得仅通过修改 domain 字符串宣称支持新物理域。

3. 开发前必须读取的文件

人工或 AI 在修改模型前，应按顺序读取：

本文档。
目标库的 library.py。
同分类中物理行为最接近的现有模型。
core/base.py。
core/ports.py。
core/metadata.py。
core/catalog.py。
registry.py 中的启动校验。
与目标模型最接近的测试。

不要只根据文件名、前端图标或旧 XML 猜测模型语义。

4. 文件位置和命名

公开模型放在：

app/simulation/components/<library_id>/<category_id>/<model_module>.py

例如：

app/simulation/components/experimental/storage/cylinder.py
app/simulation/components/experimental/flow/orifice.py
app/simulation/components/experimental/junctions/tee.py

规则：

一个公开模型原则上对应一个文件和一个主要模型类。
模块名、MODEL_TYPE、端口名和参数名使用稳定机器标识。
MODEL_TYPE 使用小写 snake_case。
参数和结果变量允许保留已有热力学惯例，如 T0、T、U。
中文名称只写入 label，不能代替机器标识。
求解器、介质和网络通用逻辑不得复制到模型文件。

5. 公开模型完整契约

每个公开模型类必须在自身类体中显式声明：

MODEL_TYPE = "example_component"
MODEL_VERSION = "1.0.0"
PORTS = (...)
PARAMETERS = (...)
RESULT_VARIABLES = (...)
DISPLAY = ...

同时必须实现：

@classmethod
def create(
    cls,
    *,
    name: str,
    medium: IdealGasMedium,
    parameters: Mapping[str, float],
) -> Component:
    ...

注册器要求这些字段直接存在于公开模型类中。不要依赖父类隐式提供 MODEL_TYPE、MODEL_VERSION、PORTS、PARAMETERS、RESULT_VARIABLES、 DISPLAY 或 create()。

6. 基类选择

6.1 `AlgebraicComponent`

适用于没有积分状态、由当前端口变量和参数直接决定残差的元件，例如：

孔板
阀门
阻性管段
理想三通

至少实现：

构造函数和端口注册。
create()。
pressure_flow_equation_residuals()。
需要传递 stream 变量时实现 update_stream_outflows()。

6.2 `ThermodynamicVolumeComponent`

适用于包含质量和能量状态的气体容腔，例如：

气瓶
贮箱
有容积的管段

至少实现：

get_state_vector()。
set_state_vector()。
refresh_thermodynamic_ports()。
state_derivative_from_ports()。
pressure_flow_equation_residuals()。

该基类已经提供标准热力学组件结果：

m, U, p, T, rho, u, h

除非物理含义不同，不要重新复制这组结果声明。

6.3 其他基类

如果现有基类不能表达模型，应先评估是否缺少一种通用组件能力。不要为了一个模型直接把专用判断塞入 SimulationNetwork 或求解器。

7. 端口建模规范

当前气动模型使用：

PortDefinition.pneumatic(
    "port_a",
    nominal_role="bidirectional",
)

气动端口包含：

变量	角色	连接规则	SI 单位
`p`	`effort`	`equal`	`Pa`
`m_flow`	`flow`	`sumToZero`	`kg/s`
`h_outflow`	`stream`	`streamMix`	`J/kg`

必须遵守：

m_flow > 0 表示质量流入当前组件。
nominal_role 只用于界面和默认布局，不限制实际流向。
物理连接是非因果的，连接线端点顺序不代表流向。
所有声明端口必须使用 register_declared_port() 创建。
DISPLAY.ports 必须与 PORTS 名称集合完全一致。
分支连接使用三通等连接元件，不能让一个物理端口直接连接多条边。

禁止：

在模型内部根据画布左右方向判断流向。
为了前端显示另造一套端口名。
把 port_a 固定解释为真实入口、把 port_b 固定解释为真实出口。
直接绕过端口状态读写其他组件对象。

8. 参数建模规范

所有用户可配置输入必须使用 ParameterDefinition：

ParameterDefinition(
    name="volume",
    label="容积",
    quantity="volume",
    unit="m3",
    default=0.1,
    minimum=0.0,
    minimum_exclusive=True,
)

字段含义：

字段	规则
`name`	稳定机器名，同时用于 XML、工程文件和 `create()`
`label`	前端显示名称，不能为空
`quantity`	受控物理量标识
`unit`	后端 SI 基准单位
`default`	必须能够创建有效模型
`minimum` / `maximum`	必须反映方程有效范围
`minimum_exclusive`	用于直径、容积等严格大于零的量

当前受控单位定义在 SI_UNIT_BY_QUANTITY：

quantity	SI 单位
`dimensionless`	空字符串
`density`	`kg/m³`
`flow_coefficient`	`kg/(s*Pa^0.5)`
`internal_energy`	`J`
`length`	`m`
`mass`	`kg`
`mass_flow`	`kg/s`
`pressure`	`Pa`
`specific_enthalpy`	`J/kg`
`specific_internal_energy`	`J/kg`
`temperature`	`K`
`volume`	`m3`

新增物理量时必须先扩展后端受控单位表，再评估前端是否需要单位换算选项。禁止在单个模型中私自拼写新的同义 quantity。

构造函数必须调用：

self.set_parameter_values(
    {
        "volume": volume,
        "p0": p0,
        "T0": T0,
    }
)

保存值、方程计算和结果输出都使用 SI。前端显示单位变化不能改变后端参数语义。

9. 结果变量规范

9.1 组件级结果

组件自身状态或派生量使用 ResultVariableDefinition：

ResultVariableDefinition(
    name="pressure_drop",
    label="压降",
    quantity="pressure",
    unit="Pa",
    category="derived",
    order=10,
)

声明后必须在 component_result_values() 返回同名值：

def component_result_values(self) -> Mapping[str, float]:
    return {
        "pressure_drop": self.port_a.p - self.port_b.p,
    }

声明集合和返回键必须一致。

9.2 端口结果

端口结果由 PORTS 的端口变量自动产生，不要在 RESULT_VARIABLES 中重复声明 port_a.p、port_a.m_flow 等字段。

9.3 禁止暴露的内容

以下内容默认不能作为用户结果：

非线性求解器内部未知量索引。
缩放残差和迭代缓存。
仅用于调试的临时中间值。
可以由已有结果稳定推导、但没有明确工程用途的重复字段。

10. 显示声明规范

公开模型必须声明 DISPLAY：

DISPLAY = ComponentDisplaySpec(
    label="示例阻力元件",
    library_id="experimental",
    category_id="flow",
    symbol="generic",
    ports=(
        PortDisplaySpec("port_a", "left", order=10),
        PortDisplaySpec("port_b", "right", order=20),
    ),
    order=90,
)

规则：

library_id 必须等于所属库 ID。
category_id 必须存在于所属库的 categories。
symbol 是前端图形键，不是模型类型。
未实现专用图标时使用新的稳定键，前端会回退到通用图形。
只有确实需要专用工程图标时才修改前端图标渲染器。
side 只允许 left 或 right。
旋转和镜像不能改变端口名或物理语义。

11. 标准创建入口

create() 是注册器创建模型的唯一入口：

@classmethod
def create(
    cls,
    *,
    name: str,
    medium: IdealGasMedium,
    parameters: Mapping[str, float],
) -> ExampleComponent:
    return cls(
        name=name,
        medium=medium,
        coefficient=parameters["coefficient"],
    )

注册器会在调用前：

补齐默认参数。
拒绝未知参数。
检查有限值和边界。

调用后还会检查：

返回对象类型正确。
实例 model_type 与 MODEL_TYPE 一致。
实际端口与 PORTS 完全一致。
实例保存的参数与规范化参数完全一致。

create() 不应重复实现参数默认值和边界校验，也不能静默修改传入参数。

12. 方程实现要求

模型方程必须满足：

残差形式统一为“期望等式左侧减右侧”。
每条 EquationResidual 使用稳定、可定位的 id。
variables 列出该残差实际涉及的端口量或状态。
role 与方程主要约束的物理角色一致。
对零压差、零流量和反向流动给出有限结果。
必要正则化必须有物理解释，并通过边界测试保护。
不得用画布坐标、连接线方向或组件名称决定方程。

动态模型还必须：

状态向量长度稳定。
get_state_vector() 和 set_state_vector() 互为逆操作。
状态导数满足质量和能量守恒约定。
初始化默认值能够产生有限介质状态。

13. 可复制的代数模型模板

下面是一个符合当前规范的两端口代数阻力模板。复制后必须根据真实物理模型修改类型、参数、方程、名称和测试，不能只改类名就注册。

from __future__ import annotations

from collections.abc import Mapping
from math import sqrt

from app.simulation.core.base import AlgebraicComponent
from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
from app.simulation.core.equations import EquationResidual
from app.simulation.core.metadata import ParameterDefinition
from app.simulation.core.medium import IdealGasMedium
from app.simulation.core.ports import PortDefinition


class ExampleRestriction(AlgebraicComponent):
    MODEL_TYPE = "example_restriction"
    MODEL_VERSION = "1.0.0"
    PORTS = (
        PortDefinition.pneumatic("port_a", nominal_role="bidirectional"),
        PortDefinition.pneumatic("port_b", nominal_role="bidirectional"),
    )
    PARAMETERS = (
        ParameterDefinition(
            name="K",
            label="流量系数",
            quantity="flow_coefficient",
            unit="kg/(s*Pa^0.5)",
            default=1e-5,
            minimum=0.0,
        ),
    )
    RESULT_VARIABLES = ()
    DISPLAY = ComponentDisplaySpec(
        label="示例阻力元件",
        library_id="experimental",
        category_id="flow",
        symbol="generic",
        ports=(
            PortDisplaySpec("port_a", "left", order=10),
            PortDisplaySpec("port_b", "right", order=20),
        ),
        order=90,
    )

    def __init__(self, name: str, K: float = 1e-5) -> None:
        super().__init__(name)
        self.set_parameter_values({"K": K})
        self.K = K
        self.port_a = self.register_declared_port("port_a")
        self.port_b = self.register_declared_port("port_b")

    @classmethod
    def create(
        cls,
        *,
        name: str,
        medium: IdealGasMedium,
        parameters: Mapping[str, float],
    ) -> ExampleRestriction:
        return cls(name=name, K=parameters["K"])

    def pressure_flow_equation_residuals(
        self,
    ) -> tuple[EquationResidual, ...]:
        pressure_difference = self.port_a.p - self.port_b.p
        expected_flow = (
            self.K
            * sqrt(abs(pressure_difference))
            * (1.0 if pressure_difference > 0.0 else -1.0)
            if pressure_difference != 0.0
            else 0.0
        )
        return (
            EquationResidual(
                id=f"{self.name}:mass_flow_balance",
                owner="component",
                owner_id=self.name,
                relation="sumToZero",
                variables=(
                    f"{self.name}.port_a.m_flow",
                    f"{self.name}.port_b.m_flow",
                ),
                role="flow",
                value=self.port_a.m_flow + self.port_b.m_flow,
            ),
            EquationResidual(
                id=f"{self.name}:pressure_flow_relation",
                owner="component",
                owner_id=self.name,
                relation="constitutive",
                variables=(
                    f"{self.name}.port_a.p",
                    f"{self.name}.port_b.p",
                    f"{self.name}.port_a.m_flow",
                ),
                role="flow",
                value=self.port_a.m_flow - expected_flow,
            ),
        )

    def update_stream_outflows(
        self,
        connected_h: Mapping[str, float],
    ) -> None:
        self.port_a.h_outflow = connected_h["port_b"]
        self.port_b.h_outflow = connected_h["port_a"]

真实现有模型可参考：

储能元件： cylinder.py
阻性元件： orifice.py
多端口连接元件： tee.py

14. 注册模型

模型文件完成后，只修改所属库的 library.py：

models=(
    # 已有模型
    "app.simulation.components.experimental.flow.example_restriction:ExampleRestriction",
)

禁止：

直接修改 COMPONENT_MODEL_REGISTRY。
在前端复制参数和端口定义作为正式来源。
递归扫描组件目录自动导入所有 .py。
同时注册两个相同 MODEL_TYPE。
把测试类、抽象基类或内部算例模型加入公开清单。

15. 测试要求

每个公开模型至少添加：

静态契约测试。
默认参数创建测试。
参数边界测试。
端口与显示布局一致性测试。
关键方程残差测试。
零流量或反向流动测试。
目录输出测试。
最小 XML 编译测试。
能进入通用求解器的模型，再添加短时仿真测试。

推荐先运行：

.\.venv-win\Scripts\python.exe -m unittest `
  tests.test_component_registry `
  tests.test_component_catalog `
  tests.test_component_metadata

然后运行完整回归：

.\.venv-win\Scripts\python.exe -m unittest discover -s tests

目录契约影响前端时还要运行：

cd frontend
$env:Path = 'F:\Master\SystemSimulationApp\.tools\node-v24.18.0-win-x64;' + $env:Path
npm.cmd run build

16. 修改已有模型的安全步骤

找到 MODEL_TYPE 的所有 XML、工程和测试引用。
记录修改前的端口、参数、结果和默认行为。
判断版本级别和是否需要迁移。
先增加或修改测试，明确预期物理行为。
修改模型类，不在注册器和前端复制规则。
检查默认实例和旧参数是否仍能创建。
检查最小系统是否仍然闭合。
运行针对性测试和完整回归。
同步本文档或模型专属说明中的物理假设。

17. 人工或 AI 的任务输入卡

为了减少猜测，新增模型前建议先填写：

模型中文名称：
MODEL_TYPE：
所属 library_id：
所属 category_id：
物理域：
模型用途和边界：
端口列表及含义：
参数列表、SI 单位、默认值和范围：
状态变量：
代数方程或微分方程：
正流量约定：
需要显示的组件结果：
已知参考模型或工程公式：
最小测试系统：
允许的近似：
明确不实现的能力：

如果关键物理信息缺失，AI 应先通过现有模型、测试或用户提供的参考补齐；不能仅凭组件名称自行创造方程。

18. AI 修改协议

AI 创建或修改模型时必须遵守：

修改前

读取第 3 节列出的文件。
检查工作区已有改动，不能覆盖无关修改。
明确模型是公开模型还是内部模型。
明确端口物理域、状态、参数、方程和结果。
找到最接近的现有模型并沿用代码风格。

修改中

将物理契约保存在模型类中。
只在库清单中登记公开模型。
不修改集中注册表来加入单个模型。
不为了让测试通过而放宽全局校验。
不改变现有模型标识，除非任务明确要求迁移。
不把前端拖拽方向当作物理流向。
不把求解器失败简单隐藏为默认结果。

修改后

展示涉及的模型、清单和测试文件。
报告版本变化和兼容性影响。
运行针对性测试、完整后端测试和必要的前端构建。
检查 GET /api/components/catalog 中的模型、分类、端口和参数。
告知用户需要重启 FastAPI 才能加载新的 Python 模块。
未执行的校验必须明确说明原因。

19. 常见失败与处理

现象	常见原因	处理
FastAPI 启动时报模型缺少声明	字段继承自父类或漏写	在公开模型类中显式声明
模型未出现在前端	未加入 `library.py` 或后端未重启	检查清单并重启 FastAPI
前端显示“内置兜底”	`/api/components/catalog` 不可用	检查 8000 端口和接口响应
显示端口校验失败	`DISPLAY.ports` 与 `PORTS` 不一致	使用相同端口名和完整集合
单位校验失败	`quantity` 与 SI 单位不匹配	使用受控单位表或先扩展规范
默认模型无法注册	默认参数越界或构造函数未保存参数	修复默认值和 `set_parameter_values()`
XML 报不支持模型	XML `type` 与 `MODEL_TYPE` 不一致	修正类型或提供迁移
模型可显示但无法仿真	只完成目录元数据，方程或物理域求解未实现	补齐方程、网络和求解测试

20. 完成定义

一个模型只有同时满足以下条件才算完成：

模型契约完整且启动校验通过。
默认参数和边界有效。
端口、参数和结果具有稳定物理含义。
方程覆盖零流量、正常流动和必要的反向流动。
模型已加入正确库清单。
目录接口能自动输出模型。
前端无需复制参数和端口定义即可使用。
XML 能映射到正确模型。
最小系统能够编译；声称可仿真的模型必须产生有限结果。
针对性测试、完整回归和必要的前端构建通过。
文档记录了模型假设、适用范围和已知限制。

20 KiB Raw Blame History Unescape Escape