Modelica-注释

注释

136 次浏览	1次

回想一下在关于实验条件的讨论中，我们使用注释包含了有关仿真开始和结束时间的信息。注释是一种包含与模型行为无关的信息的方式。在实验条件的情况下，我们注入了关于如何对特定模型进行仿真的信息。但在 Modelica 中，注释被广泛用于提供有关模型的各种附加信息。例如，正如我们在本书后面将会看到的，注释用于描述组件和连接器的图形外观。目前，重要的是要理解注释是除行为之外的附加数据，可以“附加”到 Modelica 中的不同元素上。

在本节中，我们将首先介绍注释在 Modelica 模型中的出现位置。接下来，我们将解释如何使用记录定义来描述注释的内容。最后，我们将介绍作为 Modelica 规范一部分的众多“标准”注释中的几个。

注释位置

注释可以在 Modelica 中的许多不同位置出现。我们将讨论每个可能的位置，并演示每种情况下的语法。

声明注解

声明注解位于声明的末尾，紧跟之前。以下是一个包含注解的简单声明示例：

parameter Real length "Rod length" annotation(...);

请注意，注释位于描述字符串之后、分号之前。此外，“...”只是用于存放注释数据的占位符，相关内容稍后会进行详细说明。

声明与方程注释

还可以将注释与方程式关联起来，例如：

T = T0 "Specify initial value for T" annotation(...);

在声明和公式中，注释总是位于最末尾，并且紧接在“；”符号之前。

继承注释

在讨论“修改与避免重复”这部分内容时，我们曾简要提及了“extends”关键字。可以将一个注解与“extends”子句进行关联，其方式如下：

extends QuiescentModelWithInheritance(gamma=0.3, delta=0.01) annotation(...);

正如我们在之前的所有案例中所观察到的那样，注释总是紧跟在“；”符号之前。

模型注释

模型注释将注释数据直接与模型定义本身关联起来。这正是我们在描述实验条件时所见到的那种注释形式，例如：

model FirstOrderExperiment "Defining experimental conditions"
  Real x "State variable";
initial equation
  x = 2 "Used before simulation to compute initial values";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
  annotation(experiment(StartTime=0,StopTime=8));
end FirstOrderExperiment;

请注意，与我们之前所描述的所有标注位置不同，此次的标注实际上并未“附着”于任何具体对象。这表明它是在对模型本身进行标注。

注释数据

通用语法

注释的语法与修改的语法相同。这意味着注释将包含对注释中变量的赋值操作，例如：

annotation(Evaluate=true);

或者它会对注释中变量内的某些内容进行修改，例如：

annotation(experiment(StartTime=0,StopTime=8));

用户注释

注释的设计目的是让模型开发者能够为他们的模型附加任意数据。例如，如果用户想要将零件编号与某个给定的模型定义相关联，他们可能会这样添加模型注释：

annotation(PartNumber="FF78-E4B879");

标注数据的一般原则是：如果一个工具读取一个模型，那么在将其重新写入时就必须保留标注信息。该工具无需（并且通常也不会）理解这些数据，但数据必须得以保留。

多重注释

假设用户想要同时指定一个零件编号和一项实验注释。那么他们可能会得到这样的注释：

annotation(PartNumber="FF78-E4B879",
           experiment(StartTime=0,StopTime=8));

请注意这两条信息是如何能够并存在一起的。思考标注的方式之一是将其想象成一棵类似这样的树状结构：


PartNumber="FF78-E4B879"
experiment
StartTime=0
StopTime=8

命名空间

这引入了注释的另一项原则，即只要名称不同，就可以有多个注解。因此，选择名称非常重要，应选择不会与其他名称产生潜在冲突的名称。例如，包含零件编号的更佳方法是将其封装在一个更有可能专属于您公司或应用的变量中，例如：

annotation(XogenyIndustries(PartNumber="FF78-E4B879"),
           experiment(StartTime=0,StopTime=8));

在这种情况下，变量“Xogeny Industries”可用于为特定的组织或目的划分一个“命名空间”。如果另一家组织出现并希望为同一型号关联不同的零件编号，他们可以通过在注释中建立自己的独立层级结构来实现，例如：

annotation(XogenyIndustries(PartNumber="FF78-E4B879"),
           AcmeEquipment(PartNumber="A23335-992"),
           experiment(StartTime=0,StopTime=8));

有时，Modelica 工具供应商会自行添加一些特殊的注释（例如在 Modelica 标准库中）。按照惯例，工具供应商会使用以两个下划线开头的名称，例如

annotation(XogenyIndustries(PartNumber="FF78-E4B879"),
           __ModelicateTechnologies(enableCoolFeature10=true),
           AcmeEquipment(PartNumber="A23335-992"),
           experiment(StartTime=0,StopTime=8));

说明

请记住，注释数据是任意的。这使得可以将任意数据与模型相关联。这些数据的含义通常在 Modelica 规范中并未定义。正如我们很快将会看到的，有一些“标准”注释（它们将在本书中逐一介绍），并且它们在规范中都有详细说明。但当用户添加超出标准注释的注释时，可以假定他们有某种方法（使用某种 Modelica 工具、编译器或其他与 Modelica 有关的技术）来提取和解读其注释数据。

关键在于，虽然您可以向模型中插入（非标准的）注释数据，但工具只需保留这些数据，而无需对其进行解读。

文档说明

通常会将 Modelica 注释视为与记录定义相关联的项目进行记录。在接下来的主题中，我们将看到这种技术的几个示例。强烈建议使用这种方法来记录预期的注释数据。实际上，这种技术非常流行且实用，以至于有人提议在未来将其纳入语言本身。

引言注释

本节仅介绍了 Modelica 中的几个“标准注释”。如前所述，注释通常允许包含任意数据，这些数据会被工具保留，并且在某个时候可能会被解释。标准注释的语法和含义在 Modelica 规范中有详细描述，因此 Modelica 工具可以一致且普遍地对其进行解释。
我们将遵循一种惯例（在可能的情况下）以记录定义的方式来描述标准注释。这些记录定义并非正式存在，它们只是用来简洁表达注释中所包含数据的一种方式。

文档说明

类型：模型标注

在 Modelica 中的“文档注释”功能允许将原始文本或 HTML 格式的内容与模型关联起来作为文档内容。这种文档由两个部分组成。第一部分是关于模型的信息，第二部分是修订历史信息。文档注释的结构由以下记录定义来描述：

record Documentation
  String info "Documentation in text or HTML format";
  String revision "Revision information in text or HTML format";
end Documentation;

当将 HTML 代码嵌入到注释中时，该 HTML 代码必须用 <html> 标签包起来，例如：

model MyWidget
  // ... declarations
  annotation(
    Documentation(
      info="<html><h1 class=\"heading\">Introduction</h1><p>...</p></html>"));
  // .. equations
end MyWidget;

在此，“MyWidget”模型包含有 HTML 文档。该文档被包裹在 <html> 标签内，用于定义属性的所有引号都通过“进行转义，以避免意外地终止信息字符串。

实验

类型：模型标注

实验注释用于说明关于如何对某一模型进行模拟的相关信息。该注释数据可以以记录形式呈现如下：

record experiment
  Real StartTime "Time at which the simulation should start";
  Real StopTime "Time at which the simulation should stop";
  Real Interval(min=0) "Time interval between results";
  Real Tolerance(min=0) "Solver tolerance to use";
end experiment;

评估

类型：声明注释（适用于参数）

“Evaluate”注解向 Modelica 编译器表明，给定参数的值在编译时可以转换为常量。换句话说，它表示用户不需要能够在不同模拟中更改该参数的值。

设置这种注释的初衷在于，它能让 Modelica 编译器在模型编译过程中对参数做出许多假设，而这些假设在其他情况下是无法实现的。这些假设可能会对方程组产生限制，使得在这种情况下求解方程组要比一般情况（即参数可以取一系列值的情况）更容易。

“Evaluate”注解只是一个布尔型变量（值为“true”表示参数值可以转换为常量）。其使用方式如下：

parameter Real x annotation(Evaluate=true);

隐藏结果

类型：声明注释

“HideResult”注解用于表明对于某个特定变量的解决方案对分析人员而言并不重要。通过将“HideResult”的值设为“true”，模型开发者向 Modelica 编译器表明，它无需将带有该注解的变量存储在任何生成的模拟结果中。这样做可以节省模拟时间和磁盘空间，因为这样可以避免写入永远不会被查看的数据。

“HideResult”注解的使用方式如下：

Real z "Uninteresting variable" annotation(HideResult=true);

136 次浏览	1次

< 首页

< 下一页