Basic Model Interface Documentation
Release 0.3
Fedor Baart
May 24, 2014
Contents
1
Python wrapper for BMI models
1.1 Origin . . . . . . . . . . . .
1.2 Models . . . . . . . . . . .
1.3 Prerequisites . . . . . . . .
1.4 Setup . . . . . . . . . . . .
1.5 Usage . . . . . . . . . . . .
1.6 Convenience scripts . . . .
1.7 Links . . . . . . . . . . . .
.
.
.
.
.
.
.
1
1
1
1
2
2
2
3
2
bmi package
2.1 bmi.wrapper module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
5
3
Indices and tables
7
Python Module Index
9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
i
ii
CHAPTER 1
Python wrapper for BMI models
This is ctypes wrapper for BMI models.
The BMI describes a low level interface for numerical models.
1.1 Origin
This module is based on code from:
• CSMDS: https://csdms.colorado.edu/svn/bmi/trunk/python/bmi/BMI.py
• OpenEarth: http://svn.oss.deltares.nl/repos/openearthtools/trunk/python/OpenEarthTools
• 3Di: https://github.com/nens/python-subgrid
1.2 Models
Several models implement the BMI interface.
• Subgrid: https://github.com/nens/python-subgrid
• Swan: https://github.com/SiggyF/chenopis
• XBeach: http://svn.oss.deltares.nl/repos/xbeach
• DFlow-FM: https://repos.deltares.nl/repos/ds/trunk/additional/unstruc/python/dflowfm
1.3 Prerequisites
We need a compiled BMI library (dll, so, dylib). There are a couple of common locations where we look for it.:
.
~/local/lib
~/.local/lib
/opt/modelname/lib
/usr/local/lib
/usr/lib
A convention on linux is to install the library into /opt/modelname/. If you are using one of the models above,
the modelname will be 3di, dflowfm, xbeach or swan
1
Basic Model Interface Documentation, Release 0.3
In case you have an alternative location, you can set the LD_LIBRARY_PATH, (DYLD_LIBRARY_PATH in OSX,
PATH in windows) environment variable, for example for 3Di:
$ export LD_LIBRARY_PATH=/home/user/svn/3di/trunk/subgridf90/src/.libs
(On windows the command is set instead of export).
1.4 Setup
The virtualenv way (assumes virtualenvwrapper and virtualenv are installed):
mkvirtualenv main
workon main
# get the version from pypi
pip install bmi
# or if you want to add your source directory to the path
pip install -e .
Combination Windows and Anaconda:
-
Download + Install Anaconda
Download and install the :faulthandler: package, from http://www.lfd.uci.edu/~gohlke/pythonlibs/#fa
Download and install the :NetCDF4: package, from http://www.lfd.uci.edu/~gohlke/pythonlibs/#netcdf4
Open an (Anaconda) Python-terminal (Press :[Ctrl]:+:[Alt]+:A:).
pip.bat install -e ‘‘<path to your bmi-python GIT working copy>‘‘
1.5 Usage
There are two ways to use the wrapper. A handy way is as a context manager, so with a with statement:
with BMIWrapper(engine="model", configfile=’/full/path/model.ini’) as model:
# model is the actual library.
model.something()
The second way is by calling start() and stop() yourself and using the library attribute to access the Fortran
library:
wrapper = BMIWrapper(engine="model", configfile=’/full/path/model.mdu’)
wrapper.start()
wrapper.library.something()
...
wrapper.stop()
Note: Without the mdu argument, no model is loaded and you’re free to use the library as you want.
1.6 Convenience scripts
The python bmi library contains a script that can be used as a command line runner for your model:
bmi-runner <engine> <configfile>
2
Chapter 1. Python wrapper for BMI models
Basic Model Interface Documentation, Release 0.3
1.7 Links
Contents:
1.7. Links
3
Basic Model Interface Documentation, Release 0.3
4
Chapter 1. Python wrapper for BMI models
CHAPTER 2
bmi package
2.1 bmi.wrapper module
class bmi.wrapper.BMIWrapper(engine, configfile)
Wrapper around a ctypes-loaded BMI library.
There are two ways to use the wrapper. A handy way is as a context manager, so with a with statement:
with BMIWrapper(engine="model", configfile=’/full/path/model.ini’) as model:
# model is the wrapper around library.
model.update(1.0)
...
The second way is by calling start() and stop() yourself and using the library attribute to access the
Fortran library:
wrapper = BMIWrapper(engine="model", configfile=’/full/path/model.ini’)
wrapper.initalize()
wrapper.update(1.0)
...
wrapper.finalize()
Note: Without the config argument, no model is loaded and you’re free to use the library as you want.
finalize()
Shutdown the library and clean up the model.
Note that the Fortran library’s cleanup code is not up to snuff yet, so the cleanup is not perfect. Note also
that the working directory is changed back to the original one.
get_current_time()
returns current time of simulation
get_end_time()
returns end time of simulation
get_nd(name, sliced=False)
Return an nd array from model library
get_start_time()
returns start time
get_var_rank(name)
Return array rank or 0 for scalar.
5
Basic Model Interface Documentation, Release 0.3
get_var_shape(name)
Return shape of the array.
get_var_type(name)
Return type string, compatible with numpy.
initialize()
Initialize and load the Fortran library (and model, if applicable).
The Fortran library is loaded and ctypes is used to annotate functions inside the library. The Fortran
library’s initialization is called.
Normally a path to an *.ini model file is passed to the __init__(). If so, that model is loaded. Note
that _load_model() changes the working directory to that of the model.
inq_compound(name)
Return the number of fields and size (not yet) of a compound type.
inq_compound_field(name, index)
Lookup the type,rank and shape of a compound field
make_compound_ctype(varname)
Create a ctypes type that corresponds to a compound type in memory.
set_logger(logger)
subscribe to fortran log messages
update(dt=-1)
Return type string, compatible with numpy.
6
Chapter 2. bmi package
CHAPTER 3
Indices and tables
• genindex
• modindex
• search
7
Basic Model Interface Documentation, Release 0.3
8
Chapter 3. Indices and tables
Python Module Index
b
bmi.wrapper, 5
9