The GWB plug-in feature is implemented as a Dynamic-Link Library (DLL). For Python we provide a GWBplugin wrapper class contained in the Python script file GWBplugin.py which handles dealing with the C data type conversion and calling the DLL. This page answers common queries about how to use the Python version of the plug-in feature. Since Python is a dynamically typed language there are some minor differences with its results function compared to statically typed languages.
Using the GWB plug-in feature:
To include GWBplugin.py in your Python script you first need to append the "src" folder of the GWB installation to sys.path in Python and then you can import the class.
import sys sys.path.append('/program files/gwb/src') from GWBplugin import *
This is a synopsis of the Python wrapper class provided in GWBplugin.py in the "src" directory of the GWB installation folder.
# GWBplugin.py ANULL = -999999 class GWBplugin: Name = "GWBplugin" def __init__(self): def initialize (self, app_name, file_name = None, cmds = None): def exec_cmd (self, uline): def results (self, value, units = None, ix = 0, jy = 0): def destroy (self):
Within your code you must first create a "GWBplugin" object. Next, use the "initialize" function to start the GWB application of interest by passing the application name, a optional file name for the GWB application to write output to, and any command-line type arguments.
def initialize (self, app_name, file_name = None, cmds = None):
Non-zero on success and zero on failure.
import sys sys.path.append('/program files/gwb/src') from GWBplugin import * ... myPlugin = GWBplugin() ... # plug-in SpecE8 with no output written and no options success = myPlugin.initialize("spece8") ... # plug-in React with output written to output.txt and no options success = myPlugin.initialize("react","output.txt") ... # plug-in X1t with no output written, no working directory change, # and read input from pb_contam.x1t success = myPlugin.initialize("x1t","","-nocd -i \"c:/program files/gwb/script/pb_contam.x1t\"")
The "exec_cmd" function can be 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.
def exec_cmd (self, uline):
Non-zero on success and zero on failure.
myPlugin.exec_cmd("3 mmol H+") myPlugin.exec_cmd("2 mmol Ca++") myPlugin.exec_cmd("5 mmolar Cl-") myPlugin.exec_cmd("go")
Retrieving the results using the GWB plug-in feature can be accomplished using the "results" function. The keywords, default units, and return types are the same as those listed in the Report Command chapter of the reference manual in the documentation. To use the results commands you provide the desired report command and keywords, optional desired units, and the node location of choice (X1t and X2t only).
# results function def results (self, value, units = None, ix = 0, jy = 0):
Array containing the requested results.
# get aqueous species names Species = myPlugin.results("species") # get aqueous species concentrations in mg/kg Conc = myPlugin.results("concentration aqueous","mg/kg") # get pH at node 3,5 pH = myPlugin.results("pH","",3,5)
The "destroy" function can be used to free up the underlying memory associated with the GWBplugin object.
define destroy (self):
For this tutorial you will need to have Python for Windows installed which can be obtained from the main Python website. GWBplugin has been tested with version 2.7.3, but most should work.
The first thing you need to do is to open the command prompt ...
Then create a working folder ...
Change to that folder ...
Copy the "src" folder from GWB installation – default install path shown ...
copy /Y "C:\Program Files\GWB\src"
Add the GWB installation folder to your path ...
set path=C:\Program Files\GWB;%path%
You are now ready to run the example with Python ...
Which should produce output similar to the following ...
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
Congratulations on plugging into the GWB!
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.
Why does it say that %1 is not a valid Win32 application?
You need to add the correct version (32-bit vs 64-bit) of GWB's installation folder to the path that corresponds with the version of Python you are using. 32-bit Python can only load 32-bit DLLs and 64-bit Python can only load 64-bit DLLs.
Where are the GWBplugin files that I need to import located?
The GWBplugin Python wrapper class file (GWBplugin.py) is installed to the "src" folder in the GWB directory.