モデルの説明を記載する

Modelicaの文法シンタックスとして最重要とまではいかないものの，モデルの価値を高めるために書いておく方がよい（いえ本来なら記載しておくべきもの）がコメントです．最低限の記述として，何の目的で作られたモデルなのか，何を表現した変数なのか，また各機械特性値については記述しておく必要があります．チームで使う場合はもちろん，自分しか見ないというような場合も（3ヶ月もすれば何を書いたか忘れてしまうので）特にスクリプトを自作した場合は，忘れずに記載しておきましょう．

実行に影響しないコメント

Modelicaのコメントは大別すると2種類あります．Modelicaのコンパイラが「無視するもの」と「無視しないもの」です．まずはModelicaコンパイラに完全に無視されるコメントから．

行のコメント

行をコメントアウトするときは「//」を文頭につけます．下記のような感じです．

// この行はコメントです

C++やJavaなどと同じですね．

領域のコメント

複数行に渡って領域をコメントアウトするときは「/*   */」で囲みます．例えば下記のような要領です．

/* この行はコメントです
この行もコメントです
最後のコメント行です */

こちらもC++やJavaと同じです．

実行に影響するコメント

定義コメント（definition comments）は変数を記述するためのコメントで，1DCAEのモデリングにおいては重要です．このコメントはModelicaのトランスレーターに無視されません．定義コメントには「クラスの宣言の始め」と「変数宣言の後」に挿入するものがあります．

定義コメント１：クラス宣言の始め

下記のようにクラス（モデル）の一番始めの行でクラスの名前を宣言した後に，ダブルクォーテーションで囲みます．この定義コメントはモデルの説明ですので，ぜひ記述しておくべきです．日本語を使うこともできます．

class commentTest "コメントテスト用のモデル" 

end commentTest;

定義コメント２：変数宣言の後

もう一つの定義コメントはモデルの変数やパラメータの説明の記述を行います．下記のように変数と文末のセミコロン「 ; 」の間に記載します．この定義コメントも重要なので，出来る限り記述するようにしましょう．

Real x1 "質点1の変位";

MSLの例

標準ライブラリ（MSL: Modelica Standard Library）の定義コメントを参考に見てみましょう．例としてMechanicsのTranslationalのSpringDamper要素を見てみます．

model SpringDamper "Linear 1D translational spring and damper in parallel"
  extends Translational.Interfaces.PartialCompliantWithRelativeStates;
  parameter SI.TranslationalSpringConstant c(final min=0, start=1) "Spring constant";
  parameter SI.TranslationalDampingConstant d(final min=0, start=1) "Damping constant";
  parameter SI.Position s_rel0=0 "Unstretched spring length";
  extends
    Modelica.Thermal.HeatTransfer.Interfaces.PartialElementaryConditionalHeatPortWithoutT;
protected
  Modelica.SIunits.Force f_c "Spring force";
  Modelica.SIunits.Force f_d "Damping force";
equation
  f_c = c*(s_rel - s_rel0);
  f_d = d*v_rel;
  f = f_c + f_d;
  lossPower = f_d*v_rel;
end SpringDamper;

モデルと変数およびパラメータには，必ず定義コメントが記述されています．

マスバネダンパーモデル

それでは前回のマスバネダンパーモデル（MyUnit1）にコメントを追加したものを下記に記します．

model MyMDS "マスバネダンパー・システム"

  Real x(unit="m") "変位";
  Real v(unit="m/s") "速度";
  Real a(unit="m/s2") "加速度";

  parameter Real m(unit="kg") = 1.0 "質量";
  parameter Real c(unit="N.s/m") = 1.0 "粘性減衰係数";
  parameter Real k(unit="N/m") = 1.0 "ばね定数";

equation
  v = der(x);
  a = der(v);
  m * a + c * v + k * x = 0;

initial equation
  x = 1.0;
  v = 0.0;

end MyMDS;

このモデルを実行させると下記のようになります．

MyMDSの実行結果

変数ブラウザを見ると，「記述」の欄に各変数およびパラメータの説明が追加されているのが分かります．

以上で，マスバネダンパー・モデルのスクリプトベースは完成です．次回からはグラフィカルベースでのモデリングに進みましょう．

追記

アノテーション（注釈）

ちなみにModelicaではアノテーションという機能の一部を使って，下記のようなモデルのヘルプ（取扱説明書）を作成できます．

ドキュメントブラウザを表示させたところ

アノテーション機能を使うと，説明のための図や画像を挿入したり，改訂時のリビジョンを記載したりできますが，こちらはグラフィカルベースでのモデリングの際に説明させて頂こうと思います．

書籍「プログラミングの作法」

先日，情報工学の方に「プログラミング作法」という本を紹介していただきました．新人プログラマーにとっては必須の名著だそうです．スライドに上手くまとめている方がおられましたので，参考までにご紹介しておきます．