Dakota BMI classes

The Basic Model Interface (BMI) defines an interface for converting a standalone model into an integrated modeling framework component.

• Background: http://dx.doi.org/10.1016/j.cageo.2012.04.002
• Documentation: http://bmi-forum.readthedocs.io/

Basic Model Interface for the Dakota iterative systems analysis toolkit.

class dakotathon.bmi.BmiDakota

Bases: bmipy.bmi.Bmi

The BMI implementation for the CSDMS Dakota interface.

__init__()

Create a BmiDakota instance.

finalize()

Perform tear-down tasks for the model.

Perform all tasks that take place after exiting the model’s time loop. This typically includes deallocating memory, closing files and printing reports.

get_component_name()

Name of the component.

str

The name of the component.

get_current_time()

Current time of the model.

float

The current model time.

get_end_time()

End time of the model.

float

The maximum model time.

get_grid_edge_count(grid)

Get the number of edges in the grid.

grid : int

A grid identifier.

int

The total number of grid edges.

get_grid_edge_nodes(grid, edge_nodes)

Get the edge-node connectivity.

grid : int

A grid identifier.

edge_nodes : ndarray of int, shape (2 x nnodes,)

A numpy array to place the edge-node connectivity. For each edge, connectivity is given as node at edge tail, followed by node at edge head.

ndarray of int

The input numpy array that holds the edge-node connectivity.

get_grid_face_count(grid)

Get the number of faces in the grid.

grid : int

A grid identifier.

int

The total number of grid faces.

get_grid_face_nodes(grid, face_nodes)

Get the face-node connectivity.

grid : int

A grid identifier.

face_nodes : ndarray of int

A numpy array to place the face-node connectivity. For each face, the nodes (listed in a counter-clockwise direction) that form the boundary of the face.

ndarray of int

The input numpy array that holds the face-node connectivity.

get_grid_node_count(grid)

Get the number of nodes in the grid.

grid : int

A grid identifier.

int

The total number of grid nodes.

get_grid_nodes_per_face(grid, nodes_per_face)

Get the number of nodes for each face.

grid : int

A grid identifier.

nodes_per_face : ndarray of int, shape (nfaces,)

A numpy array to place the number of edges per face.

ndarray of int

The input numpy array that holds the number of nodes per edge.

get_grid_origin(grid, origin)

Get coordinates for the lower-left corner of the computational grid.

grid : int

A grid identifier.

origin : ndarray of float, shape (ndim,)

A numpy array to hold the coordinates of the lower-left corner of the grid.

ndarray of float

The input numpy array that holds the coordinates of the grid’s lower-left corner.

get_grid_rank(grid)

Get number of dimensions of the computational grid.

grid : int

A grid identifier.

int

Rank of the grid.

get_grid_shape(grid, shape)

Get dimensions of the computational grid.

grid : int

A grid identifier.

shape : ndarray of int, shape (ndim,)

A numpy array into which to place the shape of the grid.

ndarray of int

The input numpy array that holds the grid’s shape.

get_grid_size(grid)

Get the total number of elements in the computational grid.

grid : int

A grid identifier.

int

Size of the grid.

get_grid_spacing(grid, spacing)

Get distance between nodes of the computational grid.

grid : int

A grid identifier.

spacing : ndarray of float, shape (ndim,)

A numpy array to hold the spacing between grid rows and columns.

ndarray of float

The input numpy array that holds the grid’s spacing.

get_grid_type(grid)

Get the grid type as a string.

grid : int

A grid identifier.

str

Type of grid as a string.

get_grid_x(grid, x)

Get coordinates of grid nodes in the x direction.

grid : int

A grid identifier.

x : ndarray of float, shape (nrows,)

A numpy array to hold the x-coordinates of the grid node columns.

ndarray of float

The input numpy array that holds the grid’s column x-coordinates.

get_grid_y(grid, y)

Get coordinates of grid nodes in the y direction.

grid : int

A grid identifier.

y : ndarray of float, shape (ncols,)

A numpy array to hold the y-coordinates of the grid node rows.

ndarray of float

The input numpy array that holds the grid’s row y-coordinates.

get_grid_z(grid, z)

Get coordinates of grid nodes in the z direction.

grid : int

A grid identifier.

z : ndarray of float, shape (nlayers,)

A numpy array to hold the z-coordinates of the grid nodes layers.

ndarray of float

The input numpy array that holds the grid’s layer z-coordinates.

get_input_var_names()

List of a model’s input variables.

Input variable names must be CSDMS Standard Names, also known as long variable names.

list of str

The input variables for the model.

Standard Names enable the CSDMS framework to determine whether an input variable in one model is equivalent to, or compatible with, an output variable in another model. This allows the framework to automatically connect components.

Standard Names do not have to be used within the model.

get_output_var_names()

List of a model’s output variables.

Output variable names must be CSDMS Standard Names, also known as long variable names.

list of str

The output variables for the model.

get_start_time()

Start time of the model.

Model times should be of type float.

float

The model start time.

get_time_step()

Current time step of the model.

The model time step should be of type float.

float

The time step used in model.

get_time_units()

Time units of the model.

float

The model time unit; e.g., days or s.

CSDMS uses the UDUNITS standard from Unidata.

get_value(name, dest)

Get a copy of values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a copy of a model variable, with the return type, size and rank dependent on the variable.

name : str

An input or output variable name, a CSDMS Standard Name.

dest : ndarray

A numpy array into which to place the values.

ndarray

The same numpy array that was passed as an input buffer.

get_value_at_indices(name, dest, inds)

Get values at particular indices.

name : str

An input or output variable name, a CSDMS Standard Name.

dest : ndarray

A numpy array into which to place the values.

indices : array_like

The indices into the variable array.

array_like

Value of the model variable at the given location.

get_value_ptr(name)

Get a reference to values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a reference to a model variable, with the return type, size and rank dependent on the variable.

name : str

An input or output variable name, a CSDMS Standard Name.

array_like

A reference to a model variable.

get_var_grid(name)

Get grid identifier for the given variable.

name : str

An input or output variable name, a CSDMS Standard Name.

int

The grid identifier.

get_var_itemsize(name)

Get memory use for each array element in bytes.

name : str

An input or output variable name, a CSDMS Standard Name.

int

Item size in bytes.

get_var_location(name)

Get the grid element type that the a given variable is defined on.

The grid topology can be composed of nodes, edges, and faces.

node

A point that has a coordinate pair or triplet: the most basic element of the topology.

edge

A line or curve bounded by two nodes.

face

A plane or surface enclosed by a set of edges. In a 2D horizontal application one may consider the word “polygon”, but in the hierarchy of elements the word “face” is most common.

name : str

An input or output variable name, a CSDMS Standard Name.

str

The grid location on which the variable is defined. Must be one of “node”, “edge”, or “face”.

CSDMS uses the ugrid conventions to define unstructured grids.

get_var_nbytes(name)

Get size, in bytes, of the given variable.

name : str

An input or output variable name, a CSDMS Standard Name.

int

The size of the variable, counted in bytes.

get_var_type(name)

Get data type of the given variable.

name : str

An input or output variable name, a CSDMS Standard Name.

str

The Python variable type; e.g., str, int, float.

get_var_units(name)

Get units of the given variable.

Standard unit names, in lower case, should be used, such as meters or seconds. Standard abbreviations, like m for meters, are also supported. For variables with compound units, each unit name is separated by a single space, with exponents other than 1 placed immediately after the name, as in m s-1 for velocity, W m-2 for an energy flux, or km2 for an area.

name : str

An input or output variable name, a CSDMS Standard Name.

str

The variable units.

CSDMS uses the UDUNITS standard from Unidata.

initialize(config_file)

Perform startup tasks for the model.

Perform all tasks that take place before entering the model’s time loop, including opening files and initializing the model state. Model inputs are read from a text-based configuration file, specified by filename.

config_file : str, optional

The path to the model configuration file.

Models should be refactored, if necessary, to use a configuration file. CSDMS does not impose any constraint on how configuration files are formatted, although YAML is recommended. A template of a model’s configuration file with placeholder values is used by the BMI.

set_value(name, values)

Specify a new value for a model variable.

This is the setter for the model, used to change the model’s current state. It accepts, through src, a new value for a model variable, with the type, size and rank of src dependent on the variable.

var_name : str

An input or output variable name, a CSDMS Standard Name.

src : array_like

The new value for the specified variable.

set_value_at_indices(name, inds, src)

Specify a new value for a model variable at particular indices.

var_name : str

An input or output variable name, a CSDMS Standard Name.

indices : array_like

The indices into the variable array.

src : array_like

The new value for the specified variable.

update()

Advance model state by one time step.

Perform all tasks that take place within one pass through the model’s time loop. This typically includes incrementing all of the model’s state variables. If the model’s state variables don’t change in time, then they can be computed by the initialize() method and this method can return with no action.

class dakotathon.bmi.CenteredParameterStudy

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota centered parameter study.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.

class dakotathon.bmi.MultidimParameterStudy

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota multidim parameter study.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.

class dakotathon.bmi.PolynomialChaos

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota study with the polynomial chaos method.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.

class dakotathon.bmi.PsuadeMoat

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota study with the PSUADE MOAT method.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional Path to a Dakota configuration file.

class dakotathon.bmi.Sampling

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota sampling study.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.

class dakotathon.bmi.StochasticCollocation

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota study with the stochastic collocation method.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.

class dakotathon.bmi.VectorParameterStudy

Bases: dakotathon.bmi.BmiDakota

BMI implementation of a Dakota vector parameter study.

initialize(filename=None)

Create a Dakota instance and input file.

filename : str, optional

Path to a Dakota configuration file.