4. 模型接口的元数据描述与自描述机制

在多学科联合仿真中，模型接口能否被正确识别、匹配和调用，往往不取决于模型本身算得多准，而取决于“别人能不能看懂它”。元数据描述与自描述机制解决的正是这个问题：让模型在脱离原始开发环境、脱离文档、脱离作者的情况下，仍然能够说明自己是什么、需要什么、能提供什么、适用于哪个版本。本节围绕元数据标准、模型封装、接口契约、版本管理与可发现性五个方面展开。

一、元数据：接口的“身份证”与“说明书”

元数据是描述模型接口的数据，它不参与求解计算，却决定了模型能否被工具链正确装配。以 FMI（Functional Mock-up Interface）标准为例，一个 FMU（Functional Mock-up Unit）内部包含 modelDescription.xml，其中记录了模型名称、FMI 版本、支持的接口类型（Model Exchange 或 Co-Simulation）、求解器步长建议、以及每个变量的名称、类型、因果关系、可变性和单位。这些字段就是典型的接口元数据。

元数据通常分为三类：标识类（模型名、GUID、作者、版本）、结构类（输入/输出/参数变量、类型、维度、因果关系）、语义类（单位、物理量、取值范围、默认值）。结构类元数据决定“能不能连”，语义类元数据决定“连得对不对”。例如两个模型都输出名为 speed 的变量，一个单位是 m/s，另一个是 km/h，若元数据中未声明单位，装配时就会产生 3.6 倍的隐性错误。

二、模型封装：把接口和实现一起打包

模型封装的目标是让模型以“黑盒”形式交付：调用方只依赖接口，不依赖内部实现。封装过程一般包括：编译为动态库或可执行体、生成接口描述文件、附带资源文件（参数表、查找表、许可证说明）、以及定义调用入口。以 FMU 为例，其目录结构如下：

MyModel.fmu
├── modelDescription.xml      # 接口元数据
├── binaries/
│   └── linux64/MyModel.so    # 编译后的实现
├── resources/                # 参数表、查找表
└── documentation/            # 可选说明

封装的关键约束是：接口描述文件必须与二进制实现严格对应。若 modelDescription.xml 中声明了 5 个输入，而实际库只导出 4 个，调用方在初始化阶段就会失败。因此封装后应做一次“接口一致性校验”，逐项比对元数据声明与实现导出符号。

三、接口契约：调用顺序与状态约定

接口契约规定的不只是“有哪些函数”，还包括“按什么顺序调用、每个阶段允许做什么”。FMI 的 Co-Simulation 接口定义了明确的调用序列：fmi2Instantiate → fmi2SetupExperiment → fmi2EnterInitializationMode → fmi2ExitInitializationMode → 循环 fmi2DoStep → fmi2Terminate → fmi2FreeInstance。在初始化模式内可以设置参数，但不应推进时间；进入步进模式后才能调用 fmi2DoStep。违反契约的调用通常不会立即报错，而是产生难以定位的数值异常。

契约还约定了状态语义：输入变量在 fmi2DoStep 前设置，输出变量在步进完成后读取；参数在初始化阶段设置后一般不再改变。这些约定构成了多模型协同仿真的时序基础。

四、版本管理：接口兼容性的底线

模型接口一旦发布，就可能被多个仿真工程引用。版本管理的核心是区分“兼容变更”与“破坏性变更”。兼容变更包括：新增可选输入、修正文档、调整内部算法但不改变输出语义。破坏性变更包括：删除或重命名变量、改变变量单位、改变因果关系、修改 GUID。FMI 通过 GUID 强制校验：若 FMU 的 GUID 与装配工程中记录的不一致，工具会拒绝加载，从而避免“同名不同版”的静默错误。

实践中建议采用语义化版本 主版本.次版本.修订号：主版本变更表示接口不兼容，次版本表示向后兼容的功能新增，修订号表示文档或内部修正。同时，在 modelDescription.xml 中保留 version 与 generationTool 字段，便于追溯生成工具链。

五、可发现性：让模型被“找到”和“选对”

可发现性指在模型库或联合仿真平台中，用户能否通过关键词、物理域、单位、版本等条件快速定位到合适模型。实现可发现性的基础是元数据字段的规范化和可检索化。例如，为每个模型建立索引条目：

当元数据字段完整且单位统一时，平台可以自动完成“输入-输出”匹配：将上游模型的输出变量与下游模型的输入变量按名称、类型、单位进行配对，并给出匹配度评分。若单位不一致，平台可提示需要插入单位转换模块，而不是直接连接。

综上，元数据描述与自描述机制的本质，是让模型接口从“口头约定”变为“机器可读的契约”。元数据标准提供字段规范，模型封装把接口与实现绑定，接口契约约束调用时序，版本管理控制兼容性边界，可发现性则让模型在库中可被检索和自动匹配。五者共同构成多学科模型互操作的基础设施。