GWBplugin – Getting started with Fortran

Syntax

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

Parameters

plugin

An instance of type GWBplugin.

app_name

A string containing the GWB application name you wish to use. Valid options are rxn, spece8, react, x1t, and x2t.

file_name [optional]

A string containing the name of the file you want the GWB application to write its output to. Can be an empty string if you do not want the output to be written to a file.

cmds [optional]

A string containing command-line options you could normally pass to the application when running it from the command-line. Can be an empty string.

Command-line options:

-cd

Change the working directory to the directory containing the input script specified with the -i option.

-nocd

Do not change the working directory.

-i <input_script>

Read initial input commands from the specified file.

-gtd <gtdata_dir>

Set directory to search for thermodynamic datasets.

-cond <cond_data>

Set the dataset for calculating electrical conductivity.

-d <thermo_data>

Set the thermodynamic dataset.

-s <surf_data>

Set a dataset of surface sorption reactions.

-iso <isotope_data>

Set a dataset of isotope fractionation factors.

Return value

Non-zero on success and zero on failure.

Remarks

• For this function to succeed you must have your GWB installation folder added to the PATH environment variable so all the required DLLs can be found.
• initialize must be done before trying to use any of the other functions.

Examples

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/gwb/script/pb_contam.x1t"')

Syntax

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

Parameters

plugin

An instance of type GWBplugin.

uline

A string containing the command you wish to send to the GWB application.

Return value

Non-zero on success and zero on failure.

Remarks

None.

Examples

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

Syntax

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

Parameters

plugin

An instance of type GWBplugin.

data [optional]

Address of data block to fill. Can be omitted – see remarks.

value

String containing the report command keyword and arguments.

units [optional]

String containing the units you would like the results returned in. Can be an empty string if you want default units.

ix [optional]

X node position.

jy [optional]

Y node position.

Return value

The number of values written (or to be written) to the data block.

Remarks

• To determine the size of data block you will need first call this function without the data parameter and with the rest of the parameters filled. If you know the report command you are using only returns a single value you can simply pass an array of size 1 of the correct data type. Please see the "Appendix: Report Command" section in the GWB Reference Manual for details on data types and available keywords. The Reference Manual can be found in the documentation section of the website.
• If the command fails for any reason, for example if the requested data doesn't exist or the specified unit conversion failed, the data will be filled with ANULL (-999999.0).
• ix is only used when running X1t and X2t. Otherwise it is ignored.
• jy is only used when running X2t. Otherwise it is ignored.

Examples

! 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)

Syntax

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

Parameters

plugin

An instance of type GWBplugin.

Return value

None.

Remarks

None.

Examples

CALL destroy(myPlugin)

For this tutorial you will need to have Intel's Fortran compiler installed in addition to GWB 9.0.2 (or later).

The first thing you need to do is to open Intel's Command Prompt ...

Then create a working folder ...

mkdir "%homepath%\GWBplugin"

Change to that folder ...

cd "%homepath%\GWBplugin"

Copy the "src" folder from GWB installation – default install path shown ...

copy /Y "C:\Program Files\GWB\src"

Copy the GWBplugin.lib file from GWB installation – default install path shown ...

copy /Y "C:\Program Files\GWB\gwbplugin.lib"

Add the GWB installation folder to your path ...

set path=C:\Program Files\GWB;%path%

Compile the example file and tell the compiler to use the GWBplugin library...

ifort GWBplugin_Fortran_Example1.f90 GWBplugin.lib

You are now ready to run the example ...

GWBplugin_Fortran_Example1.exe

Which should produce output similar to the following ...

 Beginning run.
 Finished run.

concentration of Cl- in molal is  0.500E-01
concentration of Cl- in mg/kg is  0.177E+04

There are 4 aqueous species

Cl-  =  0.177E+04 mg/kg
H+   =  0.114E-04 mg/kg
HCl  =  0.123E-10 mg/kg
OH-  =  0.204E-01 mg/kg

Congratulations on plugging into the GWB!

For this tutorial you will need to have MinGW with the gfortran compiler and MSYS installed in addition to GWB 9.0.2 (or later).

The first thing you need to do is to launch the MinGW Shell ...

Then create a working folder ...

mkdir -p ~/GWBplugin

Change to that folder ...

cd ~/GWBplugin

Copy the "src" folder from GWB installation – default install path shown ...

cp /c/program\ files/gwb/src/* .

Copy the GWBplugin.lib file from GWB installation – default install path shown ...

cp /c/program\ files/gwb/gwbplugin.lib .

Add the GWB installation folder to your path ...

PATH=/c/program\ files/gwb:$PATH

Compile the example file and tell the compiler to use the GWBplugin library ...

gfortran GWBplugin_Fortran_Example1.f90 GWBplugin.lib -o GWBplugin_Fortran_Example1.exe

You are now ready to run the example ...

./GWBplugin_Fortran_Example1.exe

Which should produce output similar to the following ...

Beginning run.
Finished run.

concentration of Cl- in molal is  0.500E-01
concentration of Cl- in mg/kg is  0.177E+04

There are 4 aqueous species

Cl-  =  0.177E+04 mg/kg
H+   =  0.114E-04 mg/kg
HCl  =  0.123E-10 mg/kg
OH-  =  0.204E-01 mg/kg

Congratulations on plugging into the GWB!

For this tutorial you will need to have Intel's Fortran compiler and Microsoft's Visual Studio installed in addition to GWB 9.0.2 (or later).

The first thing you need to do is to open Visual Studio ...

Then create a new project ... Ctrl+Shift+N

Expand the 'Intel Visual Fortran' project type, select 'Console Application', and use the 'Empty Project' Template. Give the project a name e.g. 'GWBplugin_example1'. Click 'OK' ...

Select the project in the 'Solution Explorer' (Ctrl+Alt+L opens it if it isn't already). Right click the project and select 'Add' then 'Existing Item...' (Shift+Alt+A)

Browse to the 'src' subfolder of your GWB installation and select the 'GWBpugin_Fortran_example1.f90' file and click 'Add'

Right click the project and open its 'Properties' ... Alt+F7

64-bit Only: If you are trying to build a 64-bit project, click on the 'Configuration Manager...' button ...

64-bit Only: Select '<New...>'

64-bit Only: Assuming you have Intel and Visual Studio 64-bit components installed, the 'New Solution Platform' should be pre-filled with 'x64' or it should be selectable from the dropdown. Select 'x64' and hit 'OK'.

Now select 'All configurations' from the Configuration selection ...

And select the correct platform : Win32 for 32-bit builds or x64 for 64-bit builds ...

Under 'Configuration Properties' – 'Fortran' – 'General' add the 'src' folder of the GWB installation to the 'Additional Include Directories' ...

Under 'Configuration Properties' – 'Linker' – 'Input' add the GWBplugin.lib library to the 'Additional Dependencies' ...
PLEASE NOTE: GWBplugin.lib is now located directly in the GWB folder and not the "src" subfolder

Under 'Configuration Properties' – 'Debugging' add the GWB install folder to the path in the 'Environment' variable. You can now click 'OK' to save the settings and close the project properties ...

You are now ready to 'Build Solution' under the 'Build' menu (or possibly 'Debug' menu) ... F7

Make sure the project builds correctly and there are no errors ...

You can now 'Start Without Debugging' ... Ctrl-F5
Note: If you need to debug your program you must attach a debugger after the 'initialize' call to GWBplugin otherwise your program will encounter a run-time error.

Assuming everything is setup correctly and built without errors your program should launch and give output like this ...

Congratulations on plugging into the GWB!