Fortran で GWBplugin を使うには

GWB プラグインは、Fortran インターフェイス (GWBplugin.f90) と出力ライブラリ (GWBplugin.lib) をリンクさせるための DLL です。

 

プラグインの使用法

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

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

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

 

2. GWB プラグインの Fortran ラッパーインターフェイス

• 以下に GWBplugin.f90 の Fortran ラッパーインターフェイスを示します。

  // GWBplugin.f90
  MODULE GWBpluginModule
  INTEGER, PARAMETER :: ANULL = -999999 ! marker for undefined value
  INTEGER, PARAMETER :: GWB_MAX_RESPONSE = 32
  
  TYPE GWBplugin
  
  FUNCTION initialize(plugin, app_name, file_name, cmds) RESULT(retval)
  TYPE(GWBplugin), INTENT(out), TARGET :: plugin
  CHARACTER (LEN = *), INTENT(in) :: app_name
  CHARACTER (LEN = *), INTENT(in), OPTIONAL :: file_name, cmds
  INTEGER(C_INT) :: retval
  
  FUNCTION exec_cmd(plugin, uline) RESULT(retval)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin
  CHARACTER (LEN = *), INTENT(in) :: uline
  INTEGER(C_INT) :: retval
  
  FUNCTION results(plugin, f_data, f_value, f_units, ix, jy) RESULT(retval)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin
  ! f_data :
  CHARACTER(LEN = GWB_MAX_RESPONSE), INTENT(out), OPTIONAL :: f_data(:)
  !or
  REAL(8), INTENT(out), OPTIONAL :: f_data(:)
  !or
  INTEGER, INTENT(out), OPTIONAL :: f_data(:)
  CHARACTER(LEN = *), INTENT(in) :: f_value
  CHARACTER(LEN = *), INTENT(in), OPTIONAL :: f_units
  INTEGER, INTENT(in), OPTIONAL :: ix, jy
  INTEGER(C_INT) :: retval
  
  SUBROUTINE destroy(plugin)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin

 

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

まず GWBplugin オブジェクトのインスタンスを生成します。次に、アプリケーションの名前、結果を書き出すファイル、コマンドラインの引数などを渡す initialize() 関数を実行します。

• 構文

  FUNCTION initialize(plugin, app_name, file_name, cmds) RESULT(retval)
  TYPE(GWBplugin), INTENT(out), TARGET :: plugin
  CHARACTER (LEN = *), INTENT(in) :: app_name
  CHARACTER (LEN = *), INTENT(in), OPTIONAL :: file_name, cmds
  INTEGER(C_INT) :: retval

  
  
• パラメータ

  plugin	GWBplugin の type インスタンス
  app_name	使用したい GWB アプリケーションの名称が含まれる文字列。rxn, spece8, react, x1t, x2t のいずれかを選択可能。
  file_name [オプション]	GWB アプリケーションに出力させたいファイルの名称が含まれる文字列。出力結果をファイルに書き出さない場合は空白にすることも可能。
  cmds [オプション]	アプリケーションをコマンドラインから実行する際に通常渡すコマンドラインオプションが含まれる文字列。空白文字列にすることも可能。
  	コマンドライン・オプション： -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.f90"
  ...
  USE GWBpluginModule
  ...
  TYPE(GWBplugin) :: myPlugin
  INTEGER :: success
  ...
  ! plug-in SpecE8 with no output written and no options
  success = initialize(myPlugin,"spece8")
  ...
  ! plug-in React with output written to output.txt and no options
  success = initialize(myPlugin,"react","output.txt")
  ...
  ! plug-in X1t with no output written, no working directory change,
  !  and read input from pb_contam.x1t
  success = initialize(myPlugin,"x1t","",&
  '-nocd -i "c:/program files (x86)/gwb/script/pb_contam.x1t"')

 

 

4. 計算の設定と実行

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

• 構文

  FUNCTION exec_cmd(plugin, uline) RESULT(retval)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin
  CHARACTER (LEN = *), INTENT(in) :: uline
  INTEGER(C_INT) :: retval

  
  
• パラメータ

  plugin	GWBplugin の type インスタンス
  uline	GWB アプリケーションに渡したいコマンドを含む文字列。

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

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

 

5. 計算結果の入手

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

• 構文

    FUNCTION results(plugin, f_data, f_value, f_units, ix, jy) RESULT(retval)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin
  ! f_data :
  CHARACTER(LEN = GWB_MAX_RESPONSE), INTENT(out), OPTIONAL :: f_data(:)
  !or
  REAL(8), INTENT(out), OPTIONAL :: f_data(:)
  !or
  INTEGER, INTENT(out), OPTIONAL :: f_data(:)
  CHARACTER(LEN = *), INTENT(in) :: f_value
  CHARACTER(LEN = *), INTENT(in), OPTIONAL :: f_units
  INTEGER, INTENT(in), OPTIONAL :: ix, jy
  INTEGER(C_INT) :: retval

  
  
• パラメータ

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

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

  ! get aqueous species names
  INTEGER :: ndata
  CHARACTER (LEN=GWB_MAX_RESPONSE), ALLOCATABLE :: Species(:)
  ndata = results(myPlugin,"species")
  ALLOCATE(Species(ndata))
  results(myPlugin,Species,"species")
  
  ! get aqueous species concentrations in mg/kg
  REAL(8), ALLOCATABLE :: Conc(:)
  ALLOCATE(Conc(ndata))
  results(myPlugin,Conc,"concentration aqueous","mg/kg")
  
  ! get pH at node 3,5
  REAL(8) :: pH(1)
  results(myPlugin,pH,"pH","",3,5)
  

 

6. メモリの解放

destroy() 関数を使って、GWB プラグインのオブジェクトが使用していたメモリを解放します。

• 構文

  SUBROUTINE destroy(plugin)
  TYPE(GWBplugin), INTENT(in), TARGET :: plugin

  
  
• パラメータ

  plugin	GWBplugin の type インスタンス

  
  
• 戻り値
  なし
  
  
• 注意
  なし

• 例

  CALL destroy(myPlugin)

 

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

• Intel Fortran コンパイラを使ってコマンドラインから GWBplugin Example1 をコンパイルする手順
• MinGW, MSYS, gfortran を使ってコマンドラインから GWBplugin Example1 をコンパイルする手順
• Microsoft Visual Studio と Intel Fortran コンパイラを使って GWBplugin Example1 をコンパイルする手順

 

Fortran Plug-in サポート情報

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

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

 

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

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

 

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

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

 

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

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