MV-1024：MotionSolveモデル内でのユーザーサブルーチンの使用

本チュートリアルでは、運動を定義する際のユーザーサブルーチンの利点について学びます。

ユーザーサブルーチンは、様々な理由で作成されます。例えば：
  • 重要な論理的条件によって決定される物理現象を描写するため
  • 複雑な式を明示的な形式で定式化することが実際困難な場合
  • C/C++やFortranのようなプログラミング言語や、Tcl、Python、Rubyなどのインタープリターを使ったよりシンプルなプログラミングを最大限に活用するため

MotionSolveで自身のサブルーチンを使用するには、下記の手順に従います：

  1. ユーザー定義のモデリングエンティティを含むC/C++、FORTRAN、TclまたはPythonソースファイルを作成します。

    サポートされているソルバーサブルーチンのリスト、および、モデル内におけるサブルーチンのセットアップと使用のガイドラインについては、MotionSolveユーザーズガイドをご参照ください。

  2. C/C++またはFortran用のユーザーサブルーチンをコンパイルおよびリンクすることによってDLLを取得します。もしくは、TclまたはPython用にソースファイルを直接使用します。
    MotionSolveは、2つの別々のレベルのユーザーDLLを提供し、アルゴリズムは、個々に指定されたライブラリから開始し、各シンボルを理解していきます。
    1. 要素レベルのDLL（most specific）

      モデリング要素定義内にDLLの名称を指定します。

    2. マシンレベルのDLL

      環境変数MS_USERSUBDLLを作成し、それをDLLファイルに設定することが可能です。この環境変数は、MotionSolveがインストールされた際に自動的に定義されるものではありません。ただし、<インストールディレクトリ>\hwsolvers\usersub\subdll\win32\フォルダー内にFortran DLLおよびC/C++ DLLが用意されています。これは、ユーザーサブルーチンDLLを使用するテストモデルの一部をユーザーが実行できるようにするためです。

    注: どのDLLを読み込むかは、"most specific"の規則、すなわち、1つ目は2つ目に優先することに基づきます。
  3. 自身のマルチボディモデル内の対応するエンティティが"ユーザー定義"のものとなり、自分のDLLを参照するように修正します。これを行うには、以下の2つの方法があります：
    1. MotionViewインターフェース内でエンティティを修正
    2. MotionSolve XMLファイルを編集する。

    上記のいずれを選択したかにかかわらず、1つまたは複数のエンティティがユーザー定義となったXMLファイルが生成されます。

    例えば、xmlファイル内のカプラーモデリング要素の場合：

     <Constraint_Coupler
id                  = "1"
type                = "TwoJoint"
i_marker_id_joint1  = "30603030"
j_marker_id_joint1  = "30602031"
body1_id_joint1     = "30603"
body2_id_joint1     = "30602"
joint_type_joint1   = " "
i_marker_id_joint2  = "30603040"
j_marker_id_joint2  = "30604040"
body1_id_joint2     = "30603"
body2_id_joint2     = "30604"
joint_type_joint2   = " "
usrsub_param_string = "USER(-8.5)"
usrsub_dll_name     = "C:/work/testsub.dll">
</Constraint_Coupler>

    usrsub_dll_name引数は、このカプラー要素について、要素レベルのDLLとしてC:/work/testsub.dllを定義します。任意の要素で異なるDLLを参照できるように定義できます。

    XMLファイル内のカプラーモデリング要素は、下記のとおり定義することも可能です：

     <Constraint_Coupler
  id                  = "1"
  type                = "TwoJoint"
  i_marker_id_joint1  = "30603030"
  j_marker_id_joint1  = "30602031"
  body1_id_joint1     = "30603"
  body2_id_joint1     = "30602"
  joint_type_joint1   = " "
  i_marker_id_joint2  = "30603040"
  j_marker_id_joint2  = "30604040"
  body1_id_joint2     = "30603"
  body2_id_joint2     = "30604"
  joint_type_joint2   = " "
  usrsub_param_string = "USER(-8.5)"
  usrsub_dll_name     = "NULL">
 </Constraint_Coupler>

    本演習の場合、MotionSolveは、MS_USERSUBDLL環境変数の値により定義されているマシンレベルのDLLを探します。

  4. MotionSolveを実行し、シミュレーション中で適切なDLLをピックアップしていることを確認します。

本演習に必要なモデルファイルPendu_model.mdlを、mbd_modeling\motionsolve自身の<作業ディレクトリ>にコピーしてください。

式を用いて運動を定義

  1. MotionViewの新しいセッションをスタートします。
  2. <作業ディレクトリ>からMDLモデルファイルPendu_model.mdlを読み込みます。
  3. Project BrowserでModelを右クリックし、Add Constraint > Motionsを選択（またはツールバーからMotions を 右クリック）します。
  4. 変位の運動をPendulum BodyとGround Bodyの間の回転ジョイントに追加します。
  5. Propertiesタブをクリックします。
  6. 変位の運動に、式3.142* TIMEを設定します。
  7. Outputs をクリックし、Outputsパネルを表示させます。
    出力リクエストを確認します。
  8. Run をクリックし、Runパネルにアクセスします。
  9. Save and run current modelをクリックし、自身の<作業ディレクトリ>に進みます。MotionSolve入力XMLファイルとして名称をPendu_model.xmlと指定します。
  10. Simulation type:がTransientに設定されていることを確認します。
  11. End Timeに1を指定します。
  12. Check をクリックし、モデリングエラーがないかをチェックします。
  13. エラーのないことが確認できたら、Runボタンをクリックします。
  14. 実行が終了すると、Animateボタンがアクティブになります。Animateをクリックし、シミュレーションのアニメーション表示を確認します。
  15. Runパネルで、Plotをクリックし、出力リクエストの時刻歴を見ます。

MOTSUBユーザーサブルーチンを用いた運動の定義

本ステップでは、ユーザーサブルーチンMOTSUBを使用します。このユーザーサブルーチンは、DLL ms_csubdll.dll内でコンパイル、リンクされています。マシンレベルのこのDLLは、インストレーションに用意されています。Windows 64-bitプラットフォームの場合は、DLLは以下の場所にあります：<installation_directory>\hwsolvers\motionsolve\usersub\subdll\win64\.

マシンレベルのDLLとして、ms_csubdll.dllを使用します。

  1. 環境変数MS_USERSUBDLLを作成し、値をDLLファイルにセットします。
    1. windows 64-bitプラットフォームユーザーの場合は、これは<installation_directory>\hwsolvers\motionsolve\usersub\subdll\win64\ms_csubdll.dllとなります。
    2. My Computerアイコンを右クリックします。Advancedタブで、Environment variables > New（User variablesの下）を選択します。
    3. Variable name:をMS_USERSUBDLLに設定します。
    4. Variable value:を<installation_directory>\hwsolvers\motionsolve\usersub\subdll\win64\ms_csubdll.dllに設定します。
      図 1.


  2. MotionViewモデルウィンドウ内で、これより前のステップからのPendu_model.mdlが開いたまま、Motionsパネルに進みます。
  3. ConnectivityタブでUser-defined propertiesチェックボックスにチェックマークを入れます。
  4. User-Definedタブをクリックし、テキストボックスに`USER(100001,5,2)`と入力します。
    図 2.


    注: 要素レベル（specific）のDLL/Interpreter関数を使用するには、Use local dll and function nameチェックボックスにマークを入れ、フォルダーアイコンを使ってDLLを指します。

    文字列`USER(100001,5,2)`は、MOTSUBユーザーサブルーチンに引数を渡すために使用されます。MOTSUBユーザーサブルーチンは下記のとおりUSER(branch_id, par1, par2)内でパラメータpar1およびpar2を使って運動を計算します：

    motion_val= par1*TIME^par2
  5. FileメニューからExport > Modelを選択します。
    Export Modelパネルが表示されます。
  6. ファイル名をPendu_model_usersub.mdlと指定します。
  7. MotionViewの現在のセッションを閉じ、新しいセッションを開始します。保存されているモデルPendu_model_usersub.mdlを開きます。
  8. Run をクリックし、Runパネルにアクセスします。
  9. Save and run current modelをクリックし、自身の作業ディレクトリに進みます。MotionSolve入力XMLファイルとして名称をPendu_model_usersub.xmlと指定します。
  10. Simulation type:がTransientに設定されていることを確認します。
  11. End Timeに1を指定します。
  12. MainタブでCheckボタンをクリックし、モデリングのエラーをチェックします。
  13. エラーのないことが確認できたら、Runボタンをクリックします。
  14. プロットウィンドウ内で、ABFファイルPendu_model_usersub.abfからの結果をプロットし、Pendu_model.abfファイルからの結果を上書きします。
  15. アニメーションウィンドウ内で、Load ModelパネルのOverlayオプションにチェックマークを入れます。
  16. Load model folderアイコンを使って、ファイルPendu_model_usersub.h3dを選択します。
  17. Applyをクリックします。
    これで、既存のアニメーションが新しいアニメーションで上書きされます。
    図 3.


    注: usrsub_param_stringの値が“USER(3.142, 1)”に設定されている場合、step 2からの結果はstep 1からの結果と同じになります。
  18. 作業ディレクトリから、MotionSolve XMLファイルPendu_model.xml（step 1で保存されたもの）を開きます。
  19. XMLファイルをブラウズし、Motion_Jointブロックを探します。 
    <Motion_Joint
id                  = "301001"
label               = "Motion 0"
type                = "EXPRESSION"
val_type            = "D"
expr                = "3.142*TIME"
joint_id            = "301001"
joint_type          = "R"
/>
  20. 作業ディレクトリからMotionSolve XMLファイルPendu_model_usersub.xmlを開きます。
  21. XMLファイルをブラウズし、Motion_Jointブロックを探します。 
    <Motion_Joint
id                  = "301001"
label               = "Motion 0"
type                = "USERSUB"
val_type            = "D"
usrsub_param_string = "USER(100001,5,2)"
usrsub_dll_name     = "NULL"
usrsub_fnc_name     = "MOTSUB"
joint_id            = "301001"
joint_type          = "R"
/>
    注: 上記ブロック内のusrsub_dll_nameパラメータの値がNULLにセットされている場合、MotionSolveはマシンレベルDLL内のサブルーチンを探します。このDLLは、MS_USERSUBDLL環境変数によってMotionSolveに渡されます。
  22. 要素レベルのDLLを使用するには、usrsub_dll_nameパラメータの値をDLLを指すよう設定します。
    usrsub_param_stringパラメータは、ユーザーサブルーチンに引数を渡すために使用されます。
    たとえば、MOTSUBユーザーサブルーチンは下記のとおりUSER(branch_id, par1, par2)内でパラメータpar1およびpar2を使って運動を計算します：
    motion_val= par1*TIME^par2
    MotionSolveはユーザーサブルーチンから戻された値を使用して運動を計算します。