MotionSolveのカスタム要素の記述

以下の手順で、MotionSolve入力デックのカスタム要素の記述方法について説明します。付録Aに、PIDコントロールを実装するために開発されたカスタム要素の例が含まれています。

カスタムマッピングファイルの作成

次のXML要素をコピーしてファイル（C:/test/my_custom_mapping.xmlなど）に貼り付けます。

  <?xml version="1.0"?>
  <!-- MotionSolve custom mapping definition file -->
  <MSolve_Custom_Mapping>
  <CustomElement
       symbol             = "MyCustomElement">
      <Attribute
         id               = "integer"
         name             = "attribute_name"
         type             = "INTEGER | REAL | AUTO_ID"      
         default          = "default_value"
      />
      <Attribute
         ...
      />    
      <Component
         id               = "integer"
         ctype            = "usrsub_name"                     
         par_list         = "(comma separated list of integers)"
         usrsub_dll_name  = "valid_path_name"
         usrsub_fnc_name  = "valid_fnc_name" 
      />
      <Component
         ...
      />
    </CustomElement>
  </MSolve_Custom_Mapping>

パラメータsymbolで定義された名前は、MotionSolveによってカスタム要素名として使用されます。MotionSolveは、パラメータsymbolで定義された名前（この場合は"MyCustomElement"）の内部での解釈が、上の<CustomElement/>タグ内で定義されたコンポーネントのリストと一致することを保証します。カスタム要素には、複数の属性と複数のコンポーネントを含めることができます。詳細については、後述する付録Aをご参照ください。

属性要素は、カスタム要素でパラメータとして出現するものです。属性要素は次のように記述されます：

<Attribute
       id               = "integer"
       name             = "attribute_name"
       type             = "INTEGER | REAL | BOOL | AUTO_ID"      
       default          = "default_value"
    />

パラメータidは、整数型で、属性の値を参照するために<Component>タグで使用されます。これは、定義されたすべての属性の中で一意にする必要があります。
パラメータnameは、カスタム要素内でユーザーが指定する必要のあるパラメータとして出現する文字列を定義します。
パラメータtypeは、integer、real、Booleanのいずれかにすることができます。"AUTO_ID"の値を取ることもでき、その場合は自動的に整数値が割り当てられます。"AUTO_ID"に設定した場合、他のコンポーネントは属性idを参照することによってそれらのID値を自動的に設定できます。
パラメータdefaultは、カスタム要素で指定されなかった属性のデフォルト値を設定します。このパラメータは、typeが"AUTO_ID"に設定されていない場合にのみ使用します。

コンポーネント要素は、カスタム要素の同等の解釈を定義します。これは、次のように記述されます：

<Component
   id               = "integer"
   ctype            = "usrsub_name"                     
   par_list         = "(comma separated list of integers)"
   usrsub_dll_name  = "valid_path_name"
   usrsub_fnc_name  = "valid_fnc_name" 
 [ 
/>

パラメータidは整数型です。その値は、既存の<Attribute/>要素のIDを参照します。その属性要素のtypeが"AUTO_ID"に設定されていない場合は、コンポーネントのIDがカスタム要素内のパラメータattribute_nameに割り当てられた値を取ります。typeが"AUTO_ID"に設定されている場合は、コンポーネントのIDに自動的に整数値が割り当てられます。
ctypeパラメータは、このコンポーネントで使用するユーザーサブルーチンのタイプを指定します。使用されるユーザーサブルーチンに応じて、このコンポーネントは、その特定のユーザーサブルーチンを使用するモデリング要素に変換されます。
par_listパラメータは、属性ID（整数）のコンマ区切りリストを指定します。このリスト内の各エントリは、そのIDを持つ属性によって表される値に拡張されます。このリストはユーザーサブルーチンに渡されます。
パラメータusrsub_dll_nameおよびusrsub_fnc_nameは、名前がusrsub_fnc_nameで指定されたユーザー作成サブルーチンを含むDLLのパスと名前を表します。

環境変数MS_CUSTOM_MAPPING_FILEを定義して設定します。

上記手順が完了すると、<Body_Rigid/>などの適切なMotionSolve要素のように、カスタム要素<MyCustomElement/>を使用できるようになります。

付録A

この例では、PIDコントロールを実装するカスタム要素を作成します。

<!-- Custom Function Mapping section-->
<CustomElement
     symbol             = "Control_PID">
    <Attribute
       id               = "1"
       name             = "input_var_id"
       type             = "INTEGER"      
       default          = "0"
    />
    <Attribute
       id               = "2"
       name             = "output_var_id"
       type             = "INTEGER"      
       default          = "0"
    />    
    <Attribute
       id               = "3"
       name             = "k"
       type             = "REAL"      
       default          = "0.0"
    />
    <Attribute
       id               = "4"
       name             = "c"
       type             = "REAL"      
       default          = "0.0"
    />
    <Attribute
       id               = "8"
       name             = "implicit"
       type             = "BOOL"      
       default          = "TRUE"
    />    
    <Attribute
       id               = "5"
       name             = "dif_1_id"
       type             = "AUTO_ID"      
    />
    <Attribute
       id               = "6"
       name             = "dif_2_id"
       type             = "AUTO_ID"      
    />
    <Attribute
       id               = "7"
       name             = "dif_3_id"
       type             = "AUTO_ID"      
    />
<Component
       id               = "2"
       ctype            = "VARSUB"                     
       par_list         = "(5,6,1,3)"
       usrsub_dll_name  = "ms_csubdll"
       usrsub_fnc_name  = "VAR_PID" 
    />
    <Component
       id               = "5"
       ctype            = "DIFSUB"                     
       par_list         = "(1)"
       usrsub_dll_name  = "ms_csubdll"
       usrsub_fnc_name  = "DIF_PID1" 
    />
    <Component
       id               = "6"
       is_implicit      = "8"
       ctype            = "DIFSUB"                     
       par_list         = "(6,7)"
       usrsub_dll_name  = "ms_csubdll"
       usrsub_fnc_name  = "DIF_PID2" 
    />    
    <Component
       id               = "7"
       is_implicit      = "8"       
       ctype            = "DIFSUB"                     
       par_list         = "(1,7,4)"
       usrsub_dll_name  = "ms_csubdll"
       usrsub_fnc_name  = "DIF_PID3" 
    />        
</CustomElement>

パラメータsymbolは、カスタム要素の名前を定義します（<Control_PID/>など）。

IDが1、2、3、4、および8の属性は、カスタム要素<Control_PID/>内に出現するパラメータを定義します。以下に例を挙げます：

<Control_PID
   input_var_id        =   "INTEGER"
   output_var_id       =   "INTEGER"
   k                   =   "REAL"
   c                   =   "REAL"
   implict             =   "BOOLEAN"
/>

IDが5、6、および7の属性は、AUTO_IDタイプを定義します。これは、これらの属性に値が自動的に割り当てられることを意味します。
コンポーネントは、<Control_PID/>要素の同等の表現を定義します。
- idは、同じIDの属性を参照します。この属性が"AUTO_ID"のタイプでない場合、コンポーネントのIDは、属性で表される値を取ります。属性がこのタイプの場合、このIDには自動的に値が割り当てられます。
- ctypeは、コンポーネントを変換する必要のあるモデル要素を識別するために使用されるキーワードです。例えば、DIFSUBコンポーネントは<Control_Diff/>に、VARSUBは<Reference_Variable/>にという具合に変換されます。
- par_listは、ユーザーサブルーチンに渡される整数の値のリストです。これらは、本質的には属性要素のIDであり、それぞれの値（整数、実数、またはブール値）に拡張されます。
- usrsub_fnc_nameとusrsub_dll_nameは、関数名と、ユーザーサブルーチンが定義されるDLLの名前 / パスを指定します。
- 使用されるctypeのタイプによっては、<Component/>要素で追加のパラメータが使用される場合があります（is_implicitなど）。

最後に、以下のカスタム要素は、

<Control_PID
  id                  = "1"
  input_var_id        = "101"
  output_var_id       = "200"
  k                   = "0.1"
  c                   = "0.02"
/>

MotionSolveによって以下の同等の解釈に変換されます：

<Reference_Variable
   id                  = "200"
   type                = "USERSUB"
   usrsub_param_string = "USER(1,2,101,0.1)"
   usrsub_dll_name     = "ms_csubdll"
   usrsub_fnc_name     = "VAR_PID"       
/>
<Control_Diff
   id                  = "1"
   type                = "USERSUB"
   usrsub_param_string = "USER(101)"
   usrsub_dll_name     = "ms_csubdll"
   usrsub_fnc_name     = "DIF_PID1"      
/>
<Control_Diff
   id                  = "2"
   is_implicit         = "TRUE"
   type                = "USERSUB"
   usrsub_param_string = "USER(2,3)"
   usrsub_dll_name     = "ms_csubdll"
   usrsub_fnc_name     = "DIF_PID2"     
/>
<Control_Diff
   id                  = "3"
   is_implicit         = "TRUE"
   type                = "USERSUB"
   usrsub_param_string = "USER(101,3,0.02)"
   usrsub_dll_name     = "ms_csubdll"
   usrsub_fnc_name     = "DIF_PID3"      
/>