GWBplugin – Getting started with Python

Using the plug-in

Using the GWB plug-in feature:

1. Including GWBplugin.py in your Python script.
2. GWBplugin Python 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.

Including GWBplugin.py in your Python script.

To include GWBplugin.py in your Python script you just need to import the class.

from GWBplugin import *

If you didn't select "Set user PATH and PYTHONPATH environment variables" when installing GWB you will 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 *

GWBplugin Python wrapper class overview.

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

Initializing the GWB application you wish to use.

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

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\"")

Configure and execute your calculations.

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

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.

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

# 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)[0]

Cleaning up.

The "destroy" function can be used to free up the underlying memory associated with the GWBplugin object.

define destroy (self):

myPlugin.destroy()

Quickstart tutorials and examples

Step-by-step instructions for running GWBplugin Example1 on the command line with Python.

cmd.exe

python "/Program Files/GWB/src/GWBplugin_Python_Example1.py"

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

Python plug-in support

Why does it say "FileNotFoundError: Could not find module 'gwbplugin' (or one of its dependencies)" when I try to run my program?
In order to locate the GWB DLLs the GWBplugin class uses the GWB_BIN_PATH environment variable that is set during the GWB installation. If the variable is not set correctly you can either manually set it or re-run the GWB installer.

Why does it say "ModuleNotFoundError: No module named 'GWBplugin'" when I try to run my program?
In order for Python to locate the GWBplugin.py wrapper it uses the PYTHONPATH environment variable. If the variable is not set correctly you can either manually set it or re-run the GWB installer being sure to select "Set user PATH and PYTHONPATH environment variables".

How can I check if my PATH Environment variables are set correctly?
You can check by entering the following commands in Python's Command line:

import os,sys
print(sys.path)

print(os.listdir('C:\\Program Files\\Gwb\\Src')) 

print(os.environ['GWB_BIN_PATH'])

print(os.listdir(os.environ['GWB_BIN_PATH'])) 

Why does my Activation Utility keep coming up when I try to call the GWB Plugin?
Please check that you are using the full Windows Python installer instead of the Microsoft Store version or the embeddable or ARM version from Python.org. See note at the top of page regarding the supported Python installation.

Why does it say that %1 is not a valid Win32 application?
You need to be using the same bit version for both Python and GWB. 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.

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.