# The wflow_bmi interface¶

## Introduction¶

In order to simplify conversion of an existing model to a reusable, plug-and-play model component, CSDMS has developed a simple interface called the Basic Model Interface or BMI that model developers are asked to implement. Recall that in this context an interface is a named set of functions with prescribed function names, argument types and return types. The BMI functions make the model self-describing and fully controllable by a modeling framework.

This is the first implementation of the BMI for the wflow pcraster/python models

## Configuration¶

Mapping of long_var_name to model variables not yet implemented. The long_var_name should be model for names for now

## wflow_bmi module documentation¶

class wflow_bmi.BmiGridType

Bases: object

RECTILINEAR = 2
STRUCTURED = 3
UNIFORM = 1
UNKNOWN = 0
UNSTRUCTURED = 4
class wflow_bmi.LookupNames(filename)

Bases: object

wflow_bmi.configget(config, section, var, default)

Gets a string from a config file (.ini) and returns a default value if the key is not found. If the key is not found it also sets the value with the default in the config-file

Input:
• config - python ConfigParser object

• section - section in the file

• var - variable (key) to get

• default - default string

Returns:
• string - either the value from the config file or the default value

wflow_bmi.configsection(config, section)

gets the list of lesy in a section

Input:
• config

• section

Output:
• list of keys in the section

wflow_bmi.configset(config, section, var, value, overwrite=False)

Sets a string in the in memory representation of the config object Deos NOT overwrite existing values if overwrite is set to False (default)

Input:
• config - python ConfigParser object

• section - section in the file

• var - variable (key) to set

• value - the value to set

• overwrite (optional, default is False)

Returns:
• nothing

wflow_bmi.iniFileSetUp(configfile)

Reads .ini file and returns a config object.

wflow_bmi.wflow_model(name)
class wflow_bmi.wflowbmi_csdms(log=None)

Bases: wflow.bmi.Bmi

csdms BMI implementation for pcraster/python models

Todo

implement translation of units

Todo

implement translation of long_var_names

finalize()

Shutdown the library and clean up the model. Uses the default (model configured) state location to also save states.

get_attribute_names()

Get the attributes of the model return in the form of section_name:attribute_name

Returns

list of attributes

get_attribute_value(attribute_name)
Parameters

attribute_name

Returns

attribute value

get_component_name()
Returns

identifier of the model based on the name of the ini file

get_current_time()

Get the current time since the epoch of the model

Returns

current time of simulation n the units and epoch returned by the function get_time_units

get_end_time()

Get the end time of the model run in units since the epoch

Returns

end time of simulation n the units and epoch returned by the function get_time_units

get_grid_connectivity(long_var_name)

Not applicable, raises NotImplementedError Should return the ldd if present!!

get_grid_offset(long_var_name)

Not applicable raises NotImplementedError

get_grid_origin(long_var_name)

gets the origin of the model grid.

Variables

long_var_name (String) – identifier of a variable in the model.

Returns

X, Y: ,the lower left corner of the grid.

get_grid_shape(long_var_name)

Return the shape of the grid. Only return something for variables with a uniform, rectilinear or structured grid. Otherwise raise ValueError.

Variables

long_var_name – identifier of a variable in the model.

Returns

List of integers: the sizes of the dimensions of the given variable, e.g. [500, 400] for a 2D grid with 500x400 grid cells.

get_grid_spacing(long_var_name)

Only return something for variables with a uniform grid. Otherwise raise ValueError.

Variables

long_var_name – identifier of a variable in the model.

Returns

The size of a grid cell for each of the dimensions of the given variable, e.g. [width, height]: for a 2D grid cell.

get_grid_type(long_var_name)

Get the grid type according to the enumeration in BmiGridType

Variables

long_var_name (String) – identifier of a variable in the model.

Returns

BmiGridType type of the grid geometry of the given variable.

get_grid_x(long_var_name)

Give X coordinates of point in the model grid

Variables

long_var_name (String) – identifier of a variable in the model.

Returns

Numpy array of doubles: x coordinate of grid cell center for each grid cell, in the same order as the

values returned by function get_value.

get_grid_y(long_var_name)

Give Y coordinates of point in the model grid

Variables

long_var_name (String) – identifier of a variable in the model.

Returns

Numpy array of doubles: y coordinate of grid cell center for each grid cell, in the same order as the

values returned by function get_value.

get_grid_z(long_var_name)

Give Z coordinates of point in the model grid

Variables

long_var_name (String) – identifier of a variable in the model.

Returns

Numpy array of doubles: z coordinate of grid cell center for each grid cell, in the same order as the values returned by function get_value.

get_input_var_names()
Returns

List of String objects: identifiers of all input variables of the model:

get_output_var_names()

Returns the list of model output variables

Returns

List of String objects: identifiers of all output variables of the model:

get_start_time()

Gets the start time of the model.

Returns

start time in the units and epoch returned by the function get_time_units

get_time_step()

Get the model time steps in units since the epoch

Returns

duration of one time step of the model in the units returned by the function get_time_units

get_time_units()

Return the time units of the model as a string

Returns

Return a string formatted using the UDUNITS standard from Unidata.

get_value(long_var_name)

Get the value(s) of a variable as a numpy array

Variables

long_var_name – name of the variable

Returns

a np array of long_var_name

get_value_at_indices(long_var_name, inds)

Get a numpy array of the values at the given indices

Variables
• long_var_name – identifier of a variable in the model:

• inds – List of list each tuple contains one index for each dimension of the given variable, i.e. each tuple indicates one element in the multi-dimensional variable array:

Returns

numpy array of values in the data type returned by the function get_var_type.

get_var_nbytes(long_var_name)

Gets the number of bytes occupied in memory for a given variable.

Variables

long_var_name (String) – identifier of a variable in the model:

Returns

total number of bytes contained in the given variable (number of elements * bytes per element)

get_var_rank(long_var_name)

Gets the number of dimensions for a variable

Variables

long_var_name (String) – identifier of a variable in the model:

Returns

array rank or 0 for scalar (number of dimensions):

get_var_size(long_var_name)

Gets the number of elements in a variable (rows * cols)

Variables

long_var_name (String) – identifier of a variable in the model:

Returns

total number of values contained in the given variable (number of elements in map)

get_var_type(long_var_name)

Gets the variable type as a numpy type string

Returns

variable type string, compatible with numpy:

get_var_units(long_var_name)

Supply units as defined in the API section of the ini file

Variables

long_var_name – identifier of a variable in the model.

Returns

String: unit of the values of the given variable. Return a string formatted

using the UDUNITS standard from Unidata. (only if set properly in the ini file)

initialize(filename, loglevel=10)

Initialise the model. Should be called before any other method.

Variables
• filename – full path to the wflow ini file

• loglevel – optional loglevel (default == DEBUG)

Assumptions for now:

• the configfile wih be a full path

• we define the case from the basedir of the configfile

Todo

Get name of module from ini file name

initialize_config(filename, loglevel=10)

Extended functionality, see https://github.com/eWaterCycle/bmi/blob/master/src/main/python/bmi.py

see initialize

Parameters
• filename

• loglevel

Returns

nothing

initialize_model()

Extended functionality, see https://github.com/eWaterCycle/bmi/blob/master/src/main/python/bmi.py

see initialize

Parameters

self

Returns

nothing

load_state(source_directory)

Ask the model to load its complete internal current state from one or more state files in the given directory.

Variables

source_directory – the directory from which the state files should be

save_state(destination_directory)

Ask the model to write its complete internal current state to one or more state files in the given directory. Afterwards the given directory will only contain the state files and nothing else. Sates are save in the models’ native format.

Variables

destination_directory – the directory in which the state files should be written.

set_attribute_value(attribute_name, attribute_value)
Parameters
• attribute_name – name using the section:option notation

• attribute_value – string value of the option

Returns

set_end_time(end_time)
Parameters

end_time – time in units (seconds) since the epoch

Returns

set_start_time(start_time)
Parameters

start_time – time in units (seconds) since the epoch

Returns

nothing

set_value(long_var_name, src)

Set the values(s) in a map using a numpy array as source

Variables
• long_var_name – identifier of a variable in the model.

• src – all values to set for the given variable. If only one value is present a uniform map will be set in the wflow model.

set_value_at_indices(long_var_name, inds, src)

Set the values in a variable using a numpy array of the values given indices

Variables
• long_var_name – identifier of a variable in the model:

• inds – List of Lists of integers inds each nested List contains one index for each dimension of the given variable, i.e. each nested List indicates one element in the multi-dimensional variable array, e.g. [[0, 0], [0, 1], [15, 19], [15, 20], [15, 21]] indicates 5 elements in a 2D grid.:

• src – Numpy array of values. one value to set for each of the indicated elements:

update()

Propagate the model to the next model timestep

update_frac(time_frac)

Not implemented. Raises a NotImplementedError

update_until(time)

Update the model until and including the given time.

• one or more timesteps foreward

• max one timestep backward

Variables

time (double) – time in the units and epoch returned by the function get_time_units.

class wflow_bmi.wflowbmi_light

Bases: object

Deltares specific light version of the BMI. Used for internal model linkage

finalize()

Shutdown the library and clean up the model.

get_current_time()

Get the current time since the epoch of the model

Returns

current time of simulation n the units and epoch returned by the function get_time_units

get_end_time()

Get the end time of the model run in units since the epoch

Returns

end time of simulation n the units and epoch returned by the function get_time_units

get_start_time()

Gets the start time of the model.

Returns

start time in the units and epoch returned by the function get_time_units

get_time_step()

Get the model time steps in units since the epoch

Returns

duration of one time step of the model in the units returned by the function get_time_units

get_time_units()
Returns

time units as a CF convention string

get_var(long_var_name)

Return an nd array from model library

get_var_count()

Return number of variables

get_var_name(i)

Return variable name

Parameters

i – variable number

Return name

name of variable number i

get_var_rank(long_var_name)

Gets the number of dimensions for a variable

Variables

long_var_name (String) – identifier of a variable in the model:

Returns

array rank or 0 for scalar (number of dimensions):

get_var_shape(long_var_name)

Return shape of the array.

Parameters

long_var_name – the long variable name

:return shape of the variable

get_var_type(long_var_name)

Gets the variable type as a numpy type string

Parameters

long_var_name – name of the variable

Returns

variable type string, compatible with numpy:

initialize(configfile=None, loglevel=10)

Assumptions for now: - the configfile wih be a full path - we define the case from the basedir of the configfile

inq_compound(name)

Return the number of fields of a compound type.

inq_compound_field(name, index)

Lookup the type,rank and shape of a compound field

set_var(long_var_name, src)

Set the values(s) in a map using a numpy array as source

Variables
• long_var_name – identifier of a variable in the model.

• src – all values to set for the given variable. If only one value is present a uniform map will be set in the wflow model.

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

Return type string, compatible with numpy. Propagate the model dt (in seconds)

update_as_it_should_be(dt)

Return type string, compatible with numpy. Propagate the model dt timesteps