C++ で GWBplugin を使うには

GWB plug-in の機能は、ダイナミックリンク・ライブラリ (DLL) として実装されます。C++ ではヘッダファイル GWBplugin.h に含まれる GWBplugin ラッパークラスと、GWBplugin.dll への出力ライブラリ GWBplugin.lib が提供されます。

このページでは、本プラグインの C++ バージョンの使用に関する一般的な質問にお答えします。なお、ここで紹介する内容を実行するには、GWB バージョン 9.0.2 以降が必要となります。

 

プラグインの使用法

1. プログラムのコンパイルとプラグインへのリンク
2. GWB プラグインの C++ ラッパークラスの概要
3. GWB アプリケーションの初期化
4. 計算の設定と実行
5. 計算結果の入手
6. メモリの解放

1. プログラムのコンパイルとプラグインへのリンク

GWB プラグインは、Micorosoft、Intel および GCC の C++ コンパイラで動作確認がとられています。プログラムにリンクさせるライブラリとヘッダファイルは、c:¥Program Files¥GWB¥src ディレクトリにインストールされます。ヘッダファイルは GWBplugin.h、リンクするライブラリは GWBplugin.lib です。チュートリアルとサンプルにしたがって、コンパイル環境とサンプルプログラムを実行して下さい (Visual Studio コマンドライン、Visual Studio、MinGW/MSYS/g++ のチュートリアルがあります) 。

 

2. GWB プラグインの C++ ラッパークラスの概要

• 以下は GWB のインストールフォルダの "src" ディレクトリにある GWBplugin.h で提供される C++ ラッパークラスの概要です。

  // GWBplugin.h
  
  #define ANULL  -999999.0       // marker for an undefined value
  
  class GWBplugin {
  public:
  GWBplugin();
  ~GWBplugin();
  int initialize(const char* app_name, const char* file_name = NULL, const char* cmds = NULL);
  int exec_cmd(char* uline);
  int results(void* data, const char* value, const char* units  = NULL , int ix  = 0 , int jy  = 0);
  };

 

3. GWB アプリケーションの初期化

まずはじめに "GWBplugin" オブジェクトのインスタンスを作成する必要があります。次に、 "initialize" 関数を使用して、アプリケーションの名称、出力データを書き出すオプションのファイル名、その他のコマンドラインタイプの引数を渡して関心のある GWB アプリケーションをスタートします。

• 構文

  int initialize(
  const char* app_name,
  const char* file_name = NULL,
  const char* cmds = NULL
  );

  
  
• パラメータ

  app_name	使用したい GWB アプリケーションの名称が含まれる文字列。rxn, spece8, react, x1t, x2t のいずれかを選択可能。
  file_name [オプション]	GWB アプリケーションに出力させたいファイルの名称が含まれる文字列。出力結果をファイルに書き出さない場合は、NULL 又は空白にすることも可能。
  cmds [オプション]	アプリケーションをコマンドラインから実行する際に通常渡すコマンドラインオプションが含まれる文字列。NULL 又は空白文字列にすることも可能。
  	コマンドライン・オプション： -nocd GWB アプリケーションの作業フォルダを前回使用したフォルダ、または、-i オプションで指定したインプット・スクリプトのフォルダに変更しない。 -cd 作業ディレクトリを i オプションで指定したインプット・スクリプトのあるディレクトリに変更する。 -i <input script> <input script>で指定したファイルから初期インプット・コマンドを読み込む。 -d <thermo data> <thermo data>で指定した熱力学データを使用する。 -s <surface data> <surface data> で指定した表面吸着反応ファイルを使用する。

  
  
• 戻り値
  成功したらゼロ以外、失敗したらゼロ
  
  
• 注意
  • この関数を実行させるには、PATH 環境変数に GWB インストールフォルダを追加し、必要なすべての DLL を見つけられるようにする必要があります。
  • 他の関数の実行を試みるには、必ず初期化を実行する必要があります。
    
    

• 例

  #include "GWBplugin.h"
  ...
  GWBplugin myPlugin;
  ...
  // plug-in SpecE8 with no output written and no options
  int success = myPlugin.initialize("spece8");
  ...
  // plug-in React with output written to output.txt and no options
  int success = myPlugin.initialize("react","output.txt");
  ...
  // plug-in X1t with no output written, no working directory change,
  //  and read input from pb_contam.x1t
  int success = myPlugin.initialize("x1t",NULL,
  "-nocd -i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"");

 

 

4. 計算の設定と実行

プラグインにコマンドを渡すには、"exec_cmd" 関数を使用します。どのようなコマンドが使用できるかは、マニュアルに記載されていますので、それを参照して下さい。実行するコマンドを設定したら、最後に go コマンドを渡します。

• 構文

  int exec_cmd(
  char* uline
  );

  
  
• パラメータ

  uline	GWB アプリケーションに渡したいコマンドを含む文字列。

  
  
• 戻り値
  成功したらゼロ以外、失敗したらゼロ
  
  
• 注意
  • なし
    
    
• 例

  myPlugin.exec_cmd("3 mmol H+");
  myPlugin.exec_cmd("2 mmol Ca++");
  myPlugin.exec_cmd("5 mmolar Cl-");
  myPlugin.exec_cmd("go");

 

5. 計算結果の入手

GWB プラグインで実行した計算結果は、"results" 関数で得ることができます。キーワードや単位、戻り値のタイプは、マニュアルの Report Command に書かれているのと同じです。"results" 関数では、レポートコマンドやキーワード、単位、ノードの位置 (X1t、X2t プログラムのみ) といっしょにデータブロックのアドレスを指定します。

 

• 構文

  int results(
  void* data,
  const char* value,
  const char* units = NULL,
  int ix = 0,
  int jy = 0
  );

  
  
• パラメータ

  data [オプション]	計算結果を埋めるデータブロックのアドレス。NULL にすることも可能。
  value	レポートコマンドのキーワードと引数を含む文字列。
  units [オプション]	返される結果の単位を指定する文字列。デフォルトの単位を使用する場合は NULL 又は空白文字列にすることも可能。
  ix [オプション]	X ノード位置
  jy [オプション]	Y ノード位置

  
  
• 戻り値
  データブロックに書き込まれた (書き込まれる) 値の数。
  
  
• 注意
  • データブロックのサイズを決定するには、まずはじめに、data パラメータを NULL に、data 以外の全てのパラメータを指定してこの関数を呼び出す必要があります。使用するレポートコマンドが単一の値しか返さないことが分かれば、適切なデータタイプを指すポインタを渡すことができます。データタイプと利用できるキーワードの詳細については、GWB Reference Manual の "Appendix: Report Command" セクションをご覧ください。Reference Manual は、開発元の documentation セクションで入手可能です。
  • 要求されたデータが存在しない場合や指定した単位変換に失敗した場合など、コマンドが何らかの理由で失敗した場合は、データに ANULL (-999999.0) が入ります。
  • ix は、X1t と X2t の実行時のみ使用されます。それ以外は無視されます。
  • jy は、X2t の実行時のみ使用されます。それ以外は無視されます。
    
    
• 例

  // get aqueous species names
  int ndata = myPlugin.results(NULL,"species");
  char** Species = new char*[ndata];
  myPlugin.results(Species,"species");
  
  // get aqueous species concentrations in mg/kg
  double* Conc = new double[ndata];
  myPlugin.results(Conc,"concentration aqueous","mg/kg");
  
  // get pH at node 3,5
  double pH = ANULL;
  myPlugin.results(&pH,"pH",NULL,3,5);

 

 

チュートリアルとサンプル

• Microsoft または Intel コンパイラを使ってコマンドラインから GWBplugin Example1 をコンパイルする手順
• MinGW, MSYS, g++ を使ってコマンドラインから GWBplugin Example1 をコンパイルする手順
• Microsoft Visual Studio を使って GWBplugin Example1 をコンパイルする手順

 

Fortran Plug-in サポート情報

GWB plug-in でサポートされる C++ コンパイラは何ですか？

GWB plug-in で現在動作確認されているのは、Micorosoft、Intel および GCC コンパイラです。

 

自分で作成したプログラムを実行しようとすると GWBplugin.dll が見つからないと言われますがどうすればよいでしょう？

GWBplugin クラスが使用する GWB の DLL の場所を指定するためには、GWB インストールディレクトリを PATH 環境変数に追加する必要があります。

 

リンク対象となる GWBplugin ファイルの場所はどこですか？

GWBplugin の export library (GWBplugin.lib) と ヘッダファイル (GWBplugin.h) は、GWB ディレクトリの "src" フォルダにインストールされます。

 

GWBplugin library のフルパスを指定しているにもかかわらず、コンパイラで GWBplugin library のリンク先が見つからないといわれますが、どうすればよいでしょうか？

32-bit コンパイラを使って 64-bit ライブラリにリンクしたり、または、64-bit コンパイラで 32-bit ライブラリにリンクを指定するような場合にこうした問題が発生します。ご使用のコンパイラのバージョンが、インストールしている GWB のバージョンと一致しているかご確認ください。