GWBplugin – Getting started with MATLAB

The GWB plug-in feature is implemented as a Dynamic-Link Library (DLL). For MATLAB we provide a GWBplugin wrapper class contained in the MATLAB script file "GWBplugin.m" which handles dealing with the C data type conversion and calling the DLL. This page answers common queries about how to use the MATLAB version of the plug-in feature. Since MATLAB is a dynamically typed language there are some minor differences with its results function compared to statically typed languages.


Using the plug-in

Using the GWB plug-in feature:

  1. Compiling a MEX file and linking to the GWB plug-in library.
  2. GWBplugin MATLAB wrapper class overview.
  3. Initializing the GWB application you wish to use.
  4. Configure and execute your calculations.
  5. Retrieving the results.
  6. Cleaning up.

Compiling a MEX file and linking to the GWB plug-in library.

To begin, locate the directory in which the GWB software is installed on your computer. Most commonly, the installation is in directory "C:\Program Files\Gwb" for 64 bit GWB, which we'll assume here, or in "C:\Program Files (x86)\Gwb" for the 32 bit version.

Add the GWB installation directory (e.g., "C:\Program Files\Gwb") to your PATH environmental variable, either from the Windows Control Panel before starting MATLAB, or by issuing the command

setenv('PATH',[getenv('PATH'),';C:\Program Files\Gwb']);
from within MATLAB.

Next, set up a C compiler in MATLAB using the command "mex -setup", as described in the MATLAB documentation. The compiler might be cl, icl, or gcc; it should already be installed on your computer.

Now, compile within MATLAB the file "GWBpluginMex.cpp" and associated header file "class_handle.hpp", which are located in the "src" subdirectory, to produce a MATLAB library. The command to do this is

mex "C:\Program Files\Gwb\src\GWBpluginMex.cpp"
            -I"C:\Program Files\Gwb\src" -L"C:\Program Files\Gwb" -lgwbplugin

GWBplugin MATLAB wrapper class overview.

This is a synopsis of the MATLAB wrapper class provided in "GWBplugin.m", which can be found in the "src" directory of the GWB installation folder.

classdef GWBplugin < handle
    properties (SetAccess = private, Hidden = true)
        objectHandle;
    end
    methods
        function this = GWBplugin(varargin)
            this.objectHandle = GWBpluginMex('new');
            GWBpluginMex('initialize', this.objectHandle, varargin{:});
        end

        function delete(this)
            GWBpluginMex('delete', this.objectHandle);
        end

        function exec_cmd(this, varargin)
            GWBpluginMex('exec_cmd', this.objectHandle, varargin{:});
        end
        
        function result = results(this, varargin)
            result = GWBpluginMex('results', this.objectHandle, varargin{:});
        end
    end
end

Initializing the GWB application you wish to use.

Within your MATLAB script you begin by creating a "GWBplugin" object, passing the application name (e.g., 'spece8'), an optional file name for the GWB application to write output to, and any command-line type arguments.

Syntax

myGWBrun = GWBplugin(app_name, file_name, cmds):

Parameters

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. Omit or pass an empty array if you do not want to write output 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 omitted or an empty array.

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

The handle of the GWB plugin, or zero on failure.

Remark

  • 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.
  • Output to the file is not performed in MATLAB until the GWBplugin object has been cleared from memory. To do this, enter the MATLAB 'clear' command.

Examples

% plug-in SpecE8 with no output written and no options
myGWBrun = GWBplugin('spece8');
...

% plug-in React with output written to output.txt and no options
myGWBrun = GWBplugin('react','output.txt');
...

% plug-in X1t with no output written, no working directory change,
%  and read input from pb_contam.x1t
myGWBrun = GWBplugin('x1t',[],'-nocd -i \"c:/Program Files/gwb/script/pb_contam.x1t\"');

Configure and execute your calculations.

The "exec_cmd" function is used to transmit commands to the plug-in. Each application has a chapter in the reference manual of the documentation on what commands are available. You use these commands to configure the application and then send a "go" command to trigger the calculations.

Syntax

exec_cmd(myGWBrun, uline):

Parameters

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

You may include more than one GWB command in a single call.

Examples

exec_cmd(myGWBrun, '3 mmol H+')
exec_cmd(myGWBrun, '2 mmol/kg Ca++', '4 mmol/kg Cl-', 'go')

Retrieving the results.

You use the "results" function to retrieve results calculated by the plug-in. The keywords, default units, and return types are the same as those listed in the Report Command chapter of the GWB Reference Manual in the documentation. To use the results command, you provide a keyword identifying the value or values needed, and optionally the units desired. In X1t and X2t, you specify as well the node of interest.

Syntax

results(myGWBrun, value, units, ix, jy):

Parameters

value
String containing the report command keyword and arguments.
units [optional]
String containing the units you would like the results returned in. Omit or pass an empty array if you want default units.
ix [optional]
X node position.
jy [optional]
Y node position.

Return value

Array containing the requested results.

Remarks

  • If you request a single value, it is returned as an array of length one.
  • If the command fails for any reason, for example if the requested data doesn't exist or the specified unit conversion failed, an empty array is returned.
  • Parameter ix is used when running X1t and X2t; otherwise it is ignored.
  • Paramter jy is similarly used only when running X2t.

Examples

Cl = results(myGWBrun,'concentration Cl-'); % in default units
fprintf('concentration of Cl- in molal is %10.4g\n',Cl);

Cl = results(myGWBrun,'concentration Cl-','mg/kg'); % in different units
fprintf('concentration of Cl- in mg/kg is %10.4g\n',Cl);

Name = results(myGWBrun,'species');
Spec = results(myGWBrun,'concentration aqueous','mg/kg');

fprintf('\n There are %i aqueous species\n\n',length(Name));
for i = 1:length(Name)
    fprintf('%-4s = %10.4g mg/kg\n',Name{i},Spec(i));
end

Cleaning up.

The "delete" function is designed to free up the underlying memory associated with the GWBplugin object. Due to a known issue in MATLAB, we recommend you reuse existing plugin instances, rather than destroy and recreate them.

To reuse an instance, issue the command

exec_cmd(myGWBrun, 'reset');

Quickstart tutorials and examples

Step-by-step instructions for running GWBplugin_Matlab_example1 in MATLAB.

For this tutorial you need to have MATLAB installed on your computer. We've tested MATLAB versions 7.9 and 8.0.

After opening MATLAB, create a working folder and change to that folder

mkdir 'GWBplugin'
cd 'GWBplugin'

Copy the files 'GWBplugin.m' and 'GWBplugin_Matlab_example1.m' from the 'src' folder of GWB installation into the new folder

copyfile ('C:\Program Files\GWB\src\GWBplugin.m', pwd)
copyfile ('C:\Program Files\GWB\src\GWBplugin_Matlab_example1.m', pwd)

Compile the MATLAB wrapper with the 'mex' command

mex "C:\Program Files\Gwb\src\GWBpluginMex.cpp"
             -I"C:\Program Files\Gwb\src" -L"C:\Program Files\Gwb" -lgwbplugin

You are now ready to run the example script

GWBplugin_Matlab_example1

which should produce output similar to the following:

>>GWBplugin_Matlab_example1

Beginning run.
Finished run.

concentration of Cl- in molal is       0.05
concentration of Cl- in mg/kg is       1770

There are 4 aqueous species.

Cl-  =       1770 mg/kg
H+   =  1.139e-05 mg/kg
HCl  =  1.234e-11 mg/kg
OH-  =    0.02039 mg/kg

Follow the same procedure to run the second example scripts, 'GWBplugin_Matlab_example2.m'.

Congratulations on plugging into the GWB!


MATLAB plug-in support

Why does it say the specified module could not be found when I try to run my program?
In order to locate the GWB DLLs the GWBplugin class uses you must add the GWB installation directory to the PATH environment variable.

Do I install the 32-bit or 64-bit version of the GWB?
The 32-bit version of MATLAB can work only with an installation of 32-bit GWB, and 64-bit MATLAB requires 64-bit GWB be in your PATH. The library you produce with the "mex" command must similarly match the MATLAB and GWB installation types.

Where are the GWBplugin files that I need to import located?
The GWBplugin MATLAB wrapper class files ("GWBplugin.m", "GWBpluginMex.cpp") as well as the example scripts ("GWBplugin_Matlab_example1.m" and "GWBplugin_Matlab_example2.m") are installed to the "src" folder in the GWB directory.

For answers to additional questions please check the plug-in section of the reference manual in the documentation, our main support FAQ, or contact us.