grpc4bmi.bmi_memoized module¶

class grpc4bmi.bmi_memoized.MemoizedBmi(origin: Bmi)[source]¶

Bases: Bmi

Wrapper around Bmi object that caches the return values of almost all methods.

Most BMI methods return same value each time it is called, so the results can be cached. gRPC communication is expensive and can be sped up by caching.

The following methods are not cached:

initialize
update_*
finalize
get_current_time
get_value_*
set_value_*

The cache is cleared when initialize() is called.

Example

A gRPC BMI server is running on localhost:1234, to cache it use the following.

>>> import grpc
>>> from grpc4bmi.bmi_grpc_client import BmiClient
>>> from grpc4bmi.bmi_memoized import MemoizedBmi
>>> slow_model = BmiClient(grpc.insecure_channel("localhost:1234"))
>>> model = MemoizedBmi(slow_model)
>>> print(model.get_component_name())
Hello world
>>> # Calling second time will return cached value
>>> # and not talk to server on "localhost:1234"
>>> print(model.get_component_name())
Hello world

finalize()[source]¶

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.

Notes

/* C */
int finalize(void *self);

get_component_name()[source]¶

Name of the component.

Returns: The name of the component.
Return type: str

Notes

/* C */
int get_component_name(void * self, char * name);

get_current_time()[source]¶

Current time of the model.

Returns: The current model time.
Return type: float

See also

get_start_time

Notes

/* C */
int get_current_time(void * self, double * time);

get_end_time()[source]¶

End time of the model.

Returns: The maximum model time.
Return type: float

See also

get_start_time

Notes

/* C */
int get_end_time(void * self, double * time);

get_grid_connectivity(grid_id)[source]¶

Get connectivity array of the grid.

Parameters: grid_id (int) – A grid identifier.
Returns: The graph of connections between the grid nodes.
Return type: array_like or int

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_connectivity(void * self, int grid_id,
                          int * connectivity);

get_grid_offset(grid_id)[source]¶

Get offsets for the grid nodes.

Parameters: grid_id (int) – A grid identifier.
Returns: The offsets for the grid nodes.
Return type: array_like of int

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_offset(void * self, int grid_id, int * offset);

get_grid_origin(grid_id)[source]¶

Get coordinates for the origin of the computational grid.

Parameters: grid_id (int) – A grid identifier.
Returns: The coordinates of the lower left corner of the grid.
Return type: array_like

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_origin(void * self, int grid_id, double * origin);

get_grid_rank(grid_id)[source]¶

Get number of dimensions of the computational grid.

Parameters: grid_id (int) – A grid identifier.
Returns: Rank of the grid.
Return type: int

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_rank(void * self, int grid_id, int * rank);

get_grid_shape(grid_id)[source]¶

Get dimensions of the computational grid.

Parameters: grid_id (int) – A grid identifier.
Returns: The dimensions of the grid.
Return type: tuple of int

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_shape(void * self, const char * var_name,
                   int * shape);

get_grid_size(grid_id)[source]¶

Get the total number of elements in the computational grid.

Parameters: grid_id (int) – A grid identifier.
Returns: Size of the grid.
Return type: int

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_size(void * self, int grid_id, int * size);

get_grid_spacing(grid_id)[source]¶

Get distance between nodes of the computational grid.

Parameters: grid_id (int) – A grid identifier.
Returns: The grid spacing.
Return type: array_like

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_spacing(void * self, int grid_id, double * spacing);

get_grid_type(grid_id)[source]¶

Get the grid type as a string.

Parameters: grid_id (int) – A grid identifier.
Returns: Type of grid as a string.
Return type: str

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_type(void * self, int grid_id, char * type);

get_grid_x(grid_id)[source]¶

Get coordinates of grid nodes in the streamwise direction.

Parameters: grid_id (int) – A grid identifier.
Returns: The positions of the grid nodes.
Return type: array_like of float

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_x(void * self, const char * var_name, double * x);

get_grid_y(grid_id)[source]¶

Get coordinates of grid nodes in the transverse direction.

Parameters: grid_id (int) – A grid identifier.
Returns: The positions of the grid nodes.
Return type: array_like of float

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_y(void * self, const char * var_name, double * y);

get_grid_z(grid_id)[source]¶

Get coordinates of grid nodes in the normal direction.

Parameters: grid_id (int) – A grid identifier.
Returns: The positions of the grid nodes.
Return type: array_like of float

See also

bmi.vars.BmiVars.get_var_grid: Obtain a grid_id.

Notes

/* C */
int get_grid_z(void * self, const char * var_name, double * z);

get_input_var_names()[source]¶

List of a model’s input variables.

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

Returns: The input variables for the model.
Return type: list of str

Notes

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.

Notes

/* C */
int get_input_var_name_count(void * self, int * count);
int get_input_var_names(void * self, char ** names);

get_output_var_names()[source]¶

List of a model’s output variables.

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

Returns: The output variables for the model.
Return type: list of str

See also

get_input_var_names

Notes

/* C */
int get_output_var_name_count(void * self, int * count);
int get_output_var_names(void * self, char ** names);

get_start_time()[source]¶

Start time of the model.

Model times should be of type float. The default model start time is 0.

Returns: The model start time.
Return type: float

Notes

/* C */
int get_start_time(void * self, double * time);

get_time_step()[source]¶

Current time step of the model.

The model time step should be of type float. The default time step is 1.0.

Returns: The time step used in model.
Return type: float

Notes

/* C */
int get_time_step(void * self, double * dt);

get_time_units()[source]¶

Time units of the model.

Returns: The model time unit; e.g., days or s.
Return type: float

Notes

CSDMS uses the UDUNITS standard from Unidata.

Notes

/* C */
int get_time_units(void * self, char * units);

get_value(var_name)[source]¶

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.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: The value of a model variable.
Return type: array_like

Notes

/* C */
int get_value(void * self, const char * var_name, void * buffer);

get_value_at_indices(var_name, indices)[source]¶

Get values at particular indices.

Parameters

var_name (str) – An input or output variable name, a CSDMS Standard Name.
indices (array_like) – The indices into the variable array.

Returns

Value of the model variable at the given location.

Return type

array_like

Notes

/* C */
int get_value_at_indices(void * self, const char * var_name,
                         void * buffer, int * indices, int len);

get_value_ref(var_name)[source]¶

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.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: A reference to a model variable.
Return type: array_like

Notes

/* C */
int get_value_ref(void * self, const char * var_name,
                  void ** buffer);

get_var_grid(var_name)[source]¶

Get grid identifier for the given variable.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: The grid identifier.
Return type: int

See also

bmi.info.BmiInfo.get_input_var_names: Get var_name from this method or from get_output_var_names().

Notes

/* C */
int get_var_grid(void * self, const char * var_name, int * id);

get_var_itemsize(var_name)[source]¶

Get memory use for each array element in bytes.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: Item size in bytes.
Return type: int

Notes

/* C */
int get_var_itemsize(void * self, const char * var_name,
                     int * itemsize);

get_var_nbytes(var_name)[source]¶

Get size, in bytes, of the given variable.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: The size of the variable, counted in bytes.
Return type: int

Notes

/* C */
int get_var_nbytes(void * self, const char * var_name,
                   int * nbytes);

get_var_type(var_name)[source]¶

Get data type of the given variable.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: The Python variable type; e.g., str, int, float.
Return type: str

Notes

/* C */
int get_var_type(void * self, const char * var_name, char * type);

get_var_units(var_name)[source]¶

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.

Parameters: var_name (str) – An input or output variable name, a CSDMS Standard Name.
Returns: The variable units.
Return type: str

Notes

CSDMS uses the UDUNITS standard from Unidata.

/* C */
int get_var_units(void * self, const char * var_name,
                  char * units);

initialize(filename)[source]¶

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.

Parameters: filename (str, optional) – The path to the model configuration file.

Notes

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.

/* C */
int initialize(void *self, char * filename);

set_value(var_name, src)[source]¶

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.

Parameters

var_name (str) – An input or output variable name, a CSDMS Standard Name.
src (array_like) – The new value for the specified variable.

Notes

/* C */
int set_value(void * self, const char * var_name, void * src);

set_value_at_indices(var_name, indices, src)[source]¶

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

Parameters

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.

Notes

/* C */
int set_value_at_indices(void * self, const char * var_name,
                         int * indices, int len, void * src);

update()[source]¶

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.

Notes

/* C */
int update(void *self);

update_frac(time_frac)[source]¶

Advance model state by a fraction of a time step.

Parameters: time_frac (float) – A fraction of a model time step value.

See also

update

Notes

/* C */
int update_frac(void *self, double time_frac);

update_until(time)[source]¶

Advance model state until the given time.

Parameters: time (float) – A model time value.

See also

update

Notes

/* C */
int update_until(void *self, double time);