Basic Model Interface Documentation

Transcription

1 Basic Model Interface Documentation Release 0.3 Fedor Baart Aug 14, 2018

2

3 Contents 1 Python wrapper for BMI models Origin Models Prerequisites Setup Usage Convenience scripts Links bmi package 5 3 bmi wrapper 7 4 wrapper 11 5 Indices and tables 13 Python Module Index 15 i

4 ii

5 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: OpenEarth: 3Di: Models Several models implement the BMI interface. Subgrid: Swan: XBeach: DFlow-FM: Prerequisites We need a compiled BMI library (dll, so, dylib). There are a couple of common locations where we look for it.: 1

6 Basic Model Interface Documentation, Release 0.3. ~/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 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 gohlke/pythonlibs/#faulthandler - Download and install the :NetCDF4: package, from 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() (continues on next page) 2 Chapter 1. Python wrapper for BMI models

7 Basic Model Interface Documentation, Release wrapper.stop() (continued from previous page) 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> 1.7 Links Contents: 1.6. Convenience scripts 3

8 Basic Model Interface Documentation, Release Chapter 1. Python wrapper for BMI models

9 CHAPTER 2 bmi package 5

10 Basic Model Interface Documentation, Release Chapter 2. bmi package

11 CHAPTER 3 bmi wrapper This module provides a ctypes wrapper around a bmi library. class bmi.wrapper.bmiwrapper(engine, configfile=none) Bases: bmi.api.ibmi 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 7

12 Basic Model Interface Documentation, Release 0.3 get_start_time() returns start time get_time_step() returns current time step of simulation get_var(name) Return an nd array from model library get_var_count() Return number of variables get_var_name(i) Return variable name get_var_rank(name) Return array rank or 0 for scalar. get_var_shape(name) Return shape of the array. get_var_type(name) Return type string, compatible with numpy. initialize(configfile=none) 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 known_paths = ['.', '~/local/lib', '~/.local/lib', '/usr/local/lib', '/usr/lib'] library = None make_compound_ctype(varname) Create a ctypes type that corresponds to a compound type in memory. set_current_time(current_time) sets current time of simulation set_logger(logger) subscribe to fortran log messages set_structure_field(name, id, field, value) set_var(name, var) Set the variable name with the values of var set_var_index(name, index, var) Overwrite the values in variable name with data from var, at the flattened (C-contiguous style) indices. Indices is a vector of 0-based integers, of the same length as the vector var. For some implementations it can be equivalent and more efficient to do: get_var(name).flat[index] = var set_var_slice(name, start, count, var) Overwrite the values in variable name with data from var, in the range (start:start+count). Start, count 8 Chapter 3. bmi wrapper

13 Basic Model Interface Documentation, Release 0.3 can be integers for rank 1, and can be tuples of integers for higher ranks. For some implementations it can be equivalent and more efficient to do: get_var(name)[start[0]:start[0]+count[0],..., start[n]:start[n]+count[n]] = var update(dt=-1) Return type string, compatible with numpy. bmi.wrapper.c_log(level, message) python logger to be called from fortran bmi.wrapper.create_string_buffer(astring) character array create_string_buffer(aninteger) -> character array create_string_buffer(astring, aninteger) -> character array bmi.wrapper.struct2dict(struct) convert a ctypes structure to a dictionary bmi.wrapper.structs2pandas(structs) convert ctypes structure or structure array to pandas data frame bmi.wrapper.structs2records(structs) convert one or more structs and generate dictionaries bmi.wrapper.wrap(func) Return wrapped function with type conversion and sanity checks. 9

14 Basic Model Interface Documentation, Release Chapter 3. bmi wrapper

15 CHAPTER 4 wrapper Run a BMI model Usage: bmi-runner <engine> [<config>] [ disable-logger] [ info] bmi-runner -h help Positional arguments: engine model engine name, this is either name of the library (e.g. model1) or full path to the BMI library (/usr/lib/libmodel1.so.5 or C:optmodel1.dll) config model config file, used to initialize model Options: -h, --help --disable-logger --info show this help message and exit do not inject logger into the BMI library display information about the model bmi.runner.colorlogs(format= short ) Append a rainbow logging handler and a formatter to the root logger bmi.runner.get_size(start_path=. ) bmi.runner.main() main bmi runner program bmi.runner.trace(model) 11

16 Basic Model Interface Documentation, Release Chapter 4. wrapper

17 CHAPTER 5 Indices and tables genindex modindex search 13

18 Basic Model Interface Documentation, Release Chapter 5. Indices and tables

19 Python Module Index b bmi.runner, 11 bmi.wrapper, 7 15

20 Basic Model Interface Documentation, Release Python Module Index

21 Index B bmi.runner (module), 11 bmi.wrapper (module), 7 BMIWrapper (class in bmi.wrapper), 7 C c_log() (in module bmi.wrapper), 9 colorlogs() (in module bmi.runner), 11 create_string_buffer() (in module bmi.wrapper), 9 F finalize() (bmi.wrapper.bmiwrapper method), 7 G get_current_time() (bmi.wrapper.bmiwrapper method), 7 get_end_time() (bmi.wrapper.bmiwrapper method), 7 get_size() (in module bmi.runner), 11 get_start_time() (bmi.wrapper.bmiwrapper method), 7 get_time_step() (bmi.wrapper.bmiwrapper method), 8 get_var() (bmi.wrapper.bmiwrapper method), 8 get_var_count() (bmi.wrapper.bmiwrapper method), 8 get_var_name() (bmi.wrapper.bmiwrapper method), 8 get_var_rank() (bmi.wrapper.bmiwrapper method), 8 get_var_shape() (bmi.wrapper.bmiwrapper method), 8 get_var_type() (bmi.wrapper.bmiwrapper method), 8 I initialize() (bmi.wrapper.bmiwrapper method), 8 inq_compound() (bmi.wrapper.bmiwrapper method), 8 inq_compound_field() (bmi.wrapper.bmiwrapper method), 8 K known_paths (bmi.wrapper.bmiwrapper attribute), 8 L library (bmi.wrapper.bmiwrapper attribute), 8 M main() (in module bmi.runner), 11 make_compound_ctype() (bmi.wrapper.bmiwrapper method), 8 S set_current_time() (bmi.wrapper.bmiwrapper method), 8 set_logger() (bmi.wrapper.bmiwrapper method), 8 set_structure_field() (bmi.wrapper.bmiwrapper method), 8 set_var() (bmi.wrapper.bmiwrapper method), 8 set_var_index() (bmi.wrapper.bmiwrapper method), 8 set_var_slice() (bmi.wrapper.bmiwrapper method), 8 struct2dict() (in module bmi.wrapper), 9 structs2pandas() (in module bmi.wrapper), 9 structs2records() (in module bmi.wrapper), 9 T trace() (in module bmi.runner), 11 U update() (bmi.wrapper.bmiwrapper method), 9 W wrap() (in module bmi.wrapper), 9 17