ModelicaのスタイルガイドをReferenceに記載の資料を参考に記述する。
あくまで個人的な見解であるためこの通りに書かないといけないというものではない。
一部でも何かの参考になれば幸いである。
goodとbadの例はまた後ほど。
命名規則 Naming conventions
長いので折り畳んでいます
使用できる文字
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 _
- 頭文字には数字、アンダーバーを使用しない
変数やクラスの名前
- クラスや変数名はキャメルケースで記述する
- キャメルケースは単語の先頭を大文字にする命名規則
- クラス名の頭文字は大文字
- 例. バネダンパーのクラス名
SpringDamper - Functionクラスの頭文字は小文字とする
- インスタンス名、変数名の頭文字は小文字
- 例. 断面積のパラメータ名
crossArea - 一般的に大文字で示される値は頭文字は大文字とする
- 例. 温度
Tなど - Constant prefixの場合は頭文字は大文字とする
-
UniformGravity,SteadyState
-
アンダースコア(アンダーバー)の使用方法
- アンダースコアは名前の最後でのみ使用する
- アンダースコアは変数の性質などを表す時に使用する
- 相対距離 Relative distance(s)
s_rel - 最大垂直力
fn_max - 同じ物理ポートが2つ使用されている場合、「_a」、「_b」または「_p」、「_n」で区別する。
Flange_a / Flange_b、HeatPort_a、HeatPort_b
パラメータや変数の宣言
-
ユーザーが参照しない、他のモデルから参照されないパラメータや変数はPrivateにする
-
public変数を宣言した後にprotectedセクションを宣言する
model test
public Real x;
public Real y;
protected
Real a;
Real b;
end test;
model test
protected
Real a;
Real b;
public Real x;
public Real y;
end test;
- Public, Privateに関わらず、単位がある変数には単位を定義する
- 可能ならば単位の定義はModelica.SIUnitパッケージを使用する
- パラメータの説明文とannotationのHTMLドキュメントの頭文字は大文字とする
- 例.
parameter Real a = 1 "Arbitrary factor";. - ブーリアン変数の説明は"=true: 説明"とする
- 例.
parameter Boolean useHeatPort = false "= true, if heatPort is enabled";.
デフォルト値
- パラメータの範囲が広い場合はデフォルト値を入力しない
- 例. nominal mass flow rates.など
Equation, Algorithmセクション
グラフィック関係
長いので折り畳んでいます
- ポートのインスタンス名はアイコンビューではなくダイアグラムビューに記述する
good
-
コンポーネントのインスタンス名は、ダイアグラムビューで青色で表示されることが好ましい
-
抵抗、質量、ギア比などのパラメータ値は、インスタンス名として小さいフォントサイズで黒色でアイコンに表示する
-
例. 熱コンダクタンスの値 G
-
定数を除く他の各クラスにはアイコンを付与することが好ましい
-
自作のアイコンが無いときはModelica.Iconsパッケージを使用する
ダイアグラムビュー
ここでモデル同士の接続線を結線と呼ぶ
適切な階層構造を持たせ、結線が煩雑にならず十分な可読性を持たせるように努める
-
第一階層（システム全体が閲覧できる階層）のモデルは適度に少なくする
-
数百個もモデルがあるようならば機能ごとに一つのクラスにする
-
結線はできるだけ交わらないようにする
-
結線はモデルの上を通さない
-
複数の同じ種類の結線がある場合、配列としてまとめる
-
コントロールモデルは左から右へ制御信号が流れるように記述する
good
bad
-
入力はモデルの左から、出力はモデルの右から、フィードバックはモデルの下からとする
ライブラリ構成
長いので折り畳んでいます
ここでパッケージはModelicaのpackageクラスのこととする。また、ライブラリは様々なパッケージを一つのパッケージにした包括的なモデル群のこととする。
ライブラリには次のサブパッケージを含める。
-
UsersGuideパッケージ
ライブラリの全体的な説明とその使用方法
UsersGuideパッケージに以下のパッケージが含まれること -
Implementationパッケージ
実装についての情報 -
Contactパッケージ
ライブラリ管理者と共同制作者の情報 -
Referencesパッケージ
参考資料のまとめ -
RevisionHistoryパッケージ
更新履歴 -
Examplesパッケージ
ライブラリの使用法を示すモデル -
Interfacesパッケージ
コネクタとPartialモデル -
Typeパッケージ
type, enumerationの定義 -
ユーザーが閲覧しないPartialクラスと基本的なクラスは、 BaseClassesというパッケージに保存する
プラントモデル
-
Sourcesパッケージ
境界条件を定義するモデル -
Componentsパッケージ
物理量を貯蔵、変換するモデル
複雑なモデルはより詳細にパッケージを分けること
貯蔵、変換は私のイメージなので詳しくは以下を参照
https://github.com/UedaShigenori/OpenModelica_Tutorials_Ja -
Sensorsパッケージ
特定の物理値を信号として出力するモデル
ドキュメント
- annotationセクションに記述するhtmlには、ヘッダー「h1、h2、h3」は使用しない
- annotationセクションのHTMLはドキュメントの自動生成に使用される。その際に不具合とならないようHTMLドキュメントの見出しは、「h4」で始まる必要がある。
コーディング規約
- 重複するコードはコピー&ペーストしない。オブジェクトの継承を使用する
- クラスをインスタンス化するときは相対参照は使用せず、フルパスを使用する
- 物理量を受け渡すポートにはアクロス変数とフロー変数を最低１つずつ定義する
コメントと説明
-
変数やパラメータには説明書きを記述する
-
Real T_max "Max temperature": -
上記のようにちゃんと記述しておくと、ツールによってはコードからドキュメントを自動生成してくれるのでドキュメント作成が楽になる
-
説明書きの頭文字は大文字で、文末にピリオドは含めない
-
ブーリアンパラメータに対して、説明書きは"= true: .."というように記述する
-
parameter Boolean useHeatPort = false "= true, if heatPort is enabled";.
一般的に用いられる変数
| 変数 | 物理量 |
|---|---|
| a | acceleration |
| A | Area |
| d | damping, density, diameter |
| dp | pressureDrop |
Reference
Modelica Standard LibraryのConvections
https://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_UsersGuide.html#Buildings.UsersGuide.Conventions
buildingsライブラリのConvections
https://build.openmodelica.org/Documentation/Modelica.UsersGuide.Conventions.html
MATLAB モデリング ガイドライン
https://jp.mathworks.com/help/simulink/modeling-guidelines.html