标注¶

回顾一下，在试验条件章节中，我们讨论了通过annotation功能定义模型仿真开始和结束的时间。通过annotation功能包含上述信息是一种方法，并且不包含与模型特性相关的信息。在试验条件下，我们可以定义特定模型如何进行仿真的信息。但是，在Modelica语言中，标注广泛应用于提供各种与模型相关的附加信息。例如，在后续的章节中，我们可以看到标注可以用来描述图形外观组件和连接器。现在，更重要是要理解标注只是额外的数据，除了描述模型的物理特性，它可以“附加”在Modelica不同的元素上。

在本节中，我们将首先讨论 annotation 在Modelica模型中可以出现的地方。接下来，我们将解释如何使用Record类型定义来描述标注所包含的内容。最后，我们将介绍一些包含在Modelica规范内的“标准”标注。

标注的位置¶

标注可以在Modelica模型的不同位置上出现。我们将讨论每个可能出现的位置，并讲述每种情况下的语法。

标注的声明¶

标注的声明紧跟在一个声明的后面，并且在标示符 ; 的前面。下面是一个包含标注的简单声明：

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

从上述程序段中可以看到，标注紧跟在描述性字符串的后面，并在标示符;的前面。另外，括号内的...只是用来放置标注数据的占位符。具体内容将在本书后面的章节中讨论。

语句标注和方程标注¶

另外，也可以将标注和方程相关联，例如：

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

标注总是紧跟在声明和方程定义的结束处，并且在标示符 ; 的前面。

标注的继承¶

在章节修改语句和避免重复中，我们已经简单的对关键词extends进行了讨论。如下所示，我们也可以将annotation和extends相关联：

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

正如我们在前面的每个例子中观察到的那样，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));

在本例里，变量XogenyIndustries可以为某个特定组织或目的创建出一个“命名空间”。如果其他组织想要一个不同的部件号与同一个模型相关联，他们就能通过在自己的标注中的层次中做到这一点，如：

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标注时常常假设标注和某个Record类型定义相关联。我们将在下个主题看到这个技巧的几个例子。强烈建议大家使用这种方法来记录预期的标注数据。其实，这种技术如此的流行而且实用，以致于有人建议，让其实际上成为语言本身的一部分。

简单标注¶

这部分介绍了Modelica的几个“标准标注”。这如前面所讨论，标注通常可以包含任意信息。这些标注不会被工具改变，而且可能会在某些时候得到解析。标准标注的语法和意义在Modelica标准都有描述。这样，这些标注就能Modelica工具得到一致以及普遍的解析。

我们将（尽可能地）按照record定义的方式去描述标准标注。这些record定义不正式存在。它们只是一种表达包含在标注中数据的简明方式。

`Documentation`¶

类型：模型标注

Modelica的Documentation标注可用纯文本或HTML表示模型相关文档。文档是由两部分组成。第一部分是有关模型的信息。第二部分则是关于模型修订历史的信息。The structure of the Documentation annotation is described by the following record definition:Documentation标注的结构可以用下列记录定义表示：

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>标记内，所有用于定义属性的引号都用\”进行转义，以避免意外地终结info字符串。

`experiment`¶

类型：模型标注

experiment标注用于指定模型仿真方式的信息。标注数据可以用record形式表示如下：

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`¶

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

Evaluate标注指示Modelica编译器，指定parameter值在编译的时候可以转化为constant。换句话说，标注表示该用户不需要在每次仿真都改变parameter的值。

这种标注背后的动机在于，它允许Modelica编译器在编译期间对parameter进行一些之前不可能的假设。这些假设可能限制方程组，让其变得更容易解。因为参数不再会像一般情况那样有一个取值范围。

Evaluate标注只是个Boolean变量（True值表示parameter值可以转化为constant）。这在标注可以使用如下：

parameter Real x annotation(Evaluate=true);

`HideResult`¶

类型：声明标注

HideResult标注用于表明，分析者并不关心该变量的解。通过把HideResult值设置为True，模型开发者告诉Modelica编译器并不需要在任何产生的结果里储存被标注的值。这可以节省模拟时间和磁盘空间。因为这样避免了写入根本不会被读取的数据。

HideResult标注使用如下：

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

Table Of Contents

标注¶