MaTX\TMD 実装の約束のメモ

• マクロ/スイッチ(トグル)

  トグル TMD_ANSI

  ANSI 対応のコンパイルスイッチ

  • tmdXXXXX.h で #define (デフォルト)もしくは #undef
  • tmdXXXXX() の実装で利用
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。

  トグル _TMDXXXXX_H

  ヘッダファイル tmdXXXXX.h の重複読み込み回避のため

  • tmdXXXXX.h で #define

  トークン TMD_USER_H

  ユーザのヘッダファイルの名前

  • ユーザの main ファイル(simXXXXX.mm)で、"simXXXXX.h" のように #define
  • tmdXXXXX.h の内部でユーザのヘッダファイルを #include するため
  • 複数のファイルがある場合は TMDXXXXX_USER_H を用いる。

  トークン TMDXXXXX_USER_H

  ユーザのヘッダファイルの名前

  • ユーザの main ファイル(simXXXXX.mm)で、"simXXXXX.h" のように #define
  • tmdXXXXX.h の内部でユーザのヘッダファイルを #include するため
  • ファイルがひとつの場合は TMD_USER_H でもよい。

  トークン TMDXXXXX_MM

  TMDXXXXX の main ファイルの名前

  • tmdXXXXX.h で "tmdXXXXX.mm" のように #define
  • ヘッダファイル内での使用の簡便のため

  トグル TMD_ENABLE_PACKAGE

  TMDXXXXX の各パッケージの名前空間を分けるかどうかのスイッチ

  • 必要ならばユーザが(ヘッダファイル等で) #define する。
  • tmdXXXXX.h で tmdXXXXX() の定義に関与
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。

  モデルパラメータ p の型 tmdXXXXX(p) モデルパラメータ(トークン) p;

  モデルパラメータアクセスメソッド

  • tmdXXXXX.h で定義される。
  • TMD_ENABLE_PACKAGE と TMD_ANSI によって実際の定義は異なる。

  トークン TMD_EXTERN

  TMDXXXXX の大域変数や関数の宣言で extern が必要かどうかのスイッチ

  • tmdXXXXX.mm で extern に #define
  • tmdXXXXX.h で大域変数や関数の宣言の際に使用
  • tmdXXXXX.h の最後で必ず #undef する。

  トークン TMDXXXXX_DIM_STATE

  TMDXXXXX のモデルの状態の次元

  • tmdXXXXX.h で適当な数(Integer)に #define
  • MaTX の Ode* 等の状態ベクトルで、TMDXXXXX のモデルの状態とユーザのそれとの切り分けに使用

  トークン TMDXXXXX_DIM_INPUT, TMDXXXXX_DIM_INPUT_W, TMDXXXXX_DIM_INPUT_Y

  TMDXXXXX のモデルの入力の次元

  • tmdXXXXX.h で適当な数(Integer)に #define
  • MaTX の Ode* 等の入力ベクトルで、TMDXXXXX のモデルへの入力とユーザがログの保存などで利用するデータとの切り分けに使用

  トークン TMDXXXXX_DIM_OUTPUT, TMDXXXXX_DIM_OUTPUT_Z, TMDXXXXX_DIM_OUTPUT_Y

  TMDXXXXX のモデルの出力の次元

  • tmdXXXXX.h で適当な数(Integer)に #define
  • MaTX の Ode* 等の入力ベクトルで、TMDXXXXX のモデルへの入力とユーザが(出力などの)ログの保存などで利用するデータとの切り分けに使用

  トークン TMDXXXXX_DIM_ALL_IOS

  TMDXXXXX のモデルの入力と出力の次元の和

  • tmdXXXXX.h で、モデルの入力と出力の次元の和(Integer)に #define
  • ユーザが MaTX の Ode* 等の入力ベクトルを初期化する際の簡単のため

  Matrix chop_state_tmdXXXXX(x) Matrix x;

  MaTX の Ode* 等の状態ベクトル x から、TMDXXXXX のモデルの状態を切り分ける関数

  • tmdXXXXX.h で、x の先頭から TMDXXXXX_DIM_STATE 個だけの数を切り出すように #define
  • マクロによる実装

  Matrix chop_other_state_tmdXXXXX(x) Matrix x;

  MaTX の Ode* 等の状態ベクトル x から、TMDXXXXX のモデル以外の状態を切り分ける関数

  • tmdXXXXX.h で、x の TMDXXXXX_DIM_STATE+1 個目以降の数を切り出すように #define
  • マクロによる実装

  Matrix chop_input_tmdXXXXX(u), chop_input_w_tmdXXXXX(u), chop_input_u_tmdXXXXX(u) Matrix u;

  MaTX の Ode* 等の入力ベクトル u から、TMDXXXXX のモデルの入力を切り分ける関数

  • tmdXXXXX.h で、u の先頭から TMDXXXXX_DIM_INPUT 個(あるいは TMDXXXXX_DIM_INPUT_W 個(とあるいは更にそれ以降の TMDXXXXX_DIM_INPUT_U 個))だけの数を切り出すように #define
  • マクロによる実装

  トークン TMD_USER_MM

  ユーザの main ファイルの名前

  • ユーザの main ファイル(simXXXXX.mm)で、"simXXXXX.mm" のように #define
  • tmdXXXXX.h の内部で TMDXXXXX の関数などの宣言の種類の判別に使用
  • 複数のファイルがある場合は TMDXXXXX_USER_MM を用いる。

  トークン TMDXXXXX_USER_MM

  ユーザの main ファイルの名前

  • ユーザの main ファイル(simXXXXX.mm)で、"simXXXXX.mm" のように #define
  • tmdXXXXX.h の内部で TMDXXXXX の関数などの宣言の種類の判別に使用
  • ファイルがひとつの場合は TMD_USER_MM でもよい。

  トグル TMD_DIVIDED_COMPILE

  分割コンパイルするかどうかを知らせるスイッチ

  • 必要ならばユーザが(ヘッダファイル等で) #define する。
  • tmdXXXXX.h で TMDXXXXX の大域変数や関数の宣言の種類の判別に使用
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。
  • コンパイルの種類が混在する場合などは TMDXXXXX_DIVIDED_COMPILE を用いる。

  トグル TMDXXXXX_DIVIDED_COMPILE

  分割コンパイルするかどうかを知らせるスイッチ

  • 必要ならばユーザが(ヘッダファイル等で) #define する。
  • tmdXXXXX.h で TMDXXXXX の大域変数や関数の宣言の種類の判別に使用
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。
  • コンパイルの種類が混在しない場合では TMD_DIVIDED_COMPILE でもよい。

  トグル _TMDXXXXX_MM

  TMDXXXXX の関数定義ファイル tmdXXXXX.mm の重複読み込みの回避のため

  • tmdXXXXX.mm で #define

  トークン TMDXXXXX_USER_DIFF

  MaTX の Ode* 等でユーザが定義する微分方程式

  • 必要ならばユーザが(ヘッダファイル等で) user_diff_tmdXXXXX のように #define する。
  • プロトタイプは Matrix TMDXXXXX_USER_DIFF(t, x, u) Real t; Matrix x, u;
  • 時刻 t, Ode* 等の状態ベクトル x, 同じく入力ベクトル u に対して x の微分値を返す。ただし、TMDXXXXX のモデルの状態や入力がそれらの先頭に入っているので適当に切り分けてユーザ定義のものに対してだけ返す。

  トグル NOPLOT

  デモ(simXXXXX.mm)の最後に結果をグラフで出力しない指示

  • ユーザの必要に応じて #define
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。

  トグル MULTIPLOT

  デモ(simXXXXX.mm)の最後にグラフを出力する際に hplot.mm パッケージの hmultiplot() を使用するかどうかのスイッチ

  • ユーザの必要に応じて #define
  • Makefile 等で、コンパイラオプションとして一括管理/指定した方がよい。

  トグル TMD_DISABLE_HALIST

  TMD の各モデルの内部状態(フラグ)の保存に halist.mm パッケージを使わないように指示するスイッチ

  • 必要ならばユーザが(ヘッダファイル等で) #define する。
  • #define された場合は、これまでどおり大域変数 tmdXXXXX_flag が用いられる。
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。
  • フラグの実装法が混在する場合などは TMDXXXXX_DISABLE_HALIST を用いる。

  トグル TMDXXXXX_DISABLE_HALIST

  TMDXXXXX の内部状態(フラグ)の保存に halist.mm パッケージを使わないように指示するスイッチ

  • 必要ならばユーザが(ヘッダファイル等で) #define する。
  • #define された場合は、これまでどおり大域変数 tmdXXXXX_flag が用いられる。
  • Makefile 等で、コンパイラオプションとして一括して管理/指定した方がよい。
  • フラグの実装法が混在しない場合では TMD_DISABLE_HALIST でもよい。

• 大域変数

  Integer tmdXXXXX_flag

  各モデル依存の汎用フラグ(原則的には obsolete 。代わりに連想配列パッケージ halist.mm を使用する。)

  • tmdXXXXX.h で宣言
  • init_tmdXXXXX() で適当な値に設定して、diff_tmdXXXXX() などで利用する。

  モデルパラメータたち

  TMD_ENABLE_PACKAGE で、TMDXXXXX 毎に名前空間は分けられる。
  必ず tmdXXXXX() でアクセスする。

• 関数

  void init_tmdXXXXX(f1, f2, ...) Integer f1, f2;

  TMDXXXXX のモデルの初期化を行なう。

  • フラグ(f1, f2 など)の個数や意味は各々のモデルに依存。

  Matrix diff_tmdXXXXX(t, x, u) Real t; Matrix x, u;

  TMDXXXXX のモデルの微分方程式

  • 時刻 t, 状態 x, 入力 u に対する x の微分値を返す。
  • x, u はユーザによって拡張されている可能性があり、それにあった次元のベクトル(行列)を返す。

  Matrix output_tmdXXXXX(t, x, u) Real t; Matrix x, u;

  TMDXXXXX のモデルの出力値

  • 時刻 t, 状態 x, 入力 u に対する出力値を返す。
  • x, u はユーザによって拡張されている可能性がある。

• ユーザプログラム(の基本的な流れ)

  準備

  • TMDXXXXX_USER_H と TMDXXXXX_USER_MM を #define する。
  • そして、tmdXXXXX.h を #include する。このとき自動的に TMDXXXXX_USER_H が #include される。

  モデルの初期化

  • init_tmdXXXXX() を適当な引数で呼ぶ。
  • すると、モデルパラメータが設定される。(引数によっては物理パラメータは変更されずに、線形モデルの行列パラメータだけが更新されるようなこともある。)

  制御系の設計

  init_tmdXXXX() で設定されたモデルの物理パラメータや設計モデルなどを用いて制御系を設計する。

  制御器(プログラム)の定義

  MaTX の Ode* 等で用いる link_eqs() を書く。このとき、動的なパートがある場合は TMDXXXXX_USER_DIFF を用いる。

  シミュレーション

  diff_tmdXXXXX() と link_eqs() で、適当な初期値から、MaTX の Ode* 等を用いてシミュレーション(積分等)を行なう。時刻、状態、入力の系列が返される。

  結果の表示/保存

  必要ならば、シミュレーション結果をグラフなどで表示したり保存したりする。