# The wflow_bmi_combined 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.

The wflow_bmi_combined module implements a class that connects 2 or more python bmi modules and exports those to the outside as a single bmi model.

• A @ character is used to separate the module from the variable. For example, the variable Flow in module wflow_hbv becomes wflow_hbv@Flow in the combined model (it was Flow in the single interface)

• The individual models can run in a separate case dir or can be combined into one directory (and share maps that are identical)

The bmi2runner.py script can be used to run a set of combined models, it is documented seperately.

## wflow_bmi_combined module documentation¶

wflow_bmi_combined.configsection(config, section)

gets the list of lesy in a section

Input:
• config

• section

Output:
• list of keys in the section

wflow_bmi_combined.iniFileSetUp(configfile)

Reads .ini file and returns a config object.

class wflow_bmi_combined.wflowbmi_csdms

Bases: wflow.bmi.Bmi

csdms BMI implementation runner for combined pcraster/python and rtc models

• all variables are identified by: component_name@variable_name

• idmapping between model locations is identifief by a file with indices:component_name@variable_name@file

• this version is only tested for a one-way link

• get_component_name returns a comma separated list of components

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 model_name@section_name:attribute_name

Returns

list of attributes

get_attribute_value(attribute_name)
gets the attribute value for the name. The name should adhere to the following convention::

model_name@section_name:attribute_name

Parameters

attribute_name

Returns

attribute value

get_component_name()
Returns

identifier of the models separated by a comma (,)

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 of last model in the list. Tiem sare assumed to be identical

get_time_step()

Get the model time steps in units since the epoch

Returns

duration of one time step of the model with the largest! timestep.

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 combined model ini file

initialize_config(filename, loglevel=10)

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

Read the ini file for the comnined bmi model and initializes all the bmi models listed in the config file.

Parameters

filename

Returns

nothing

initialize_model()

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

initalises all bmi models listed in the config file. Als does the first (timestep 0) data exchange

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 model_name@section:option notation

• attribute_value – string value of the option

Returns

set_end_time(end_time)

sets the end time for all bmi models

Parameters

end_time – time in units (seconds) since the epoch

Returns

set_start_time(start_time)

Sets the start time for all bmi models

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

The function iterates over all models

update_frac(time_frac)

Not implemented. Raises a NotImplementedError

update_to_start_time(start_time)

Update the model until and including the start time in case start time of models differ.

• one or more timesteps foreward

Variables

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

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.