bmi_topography package

Submodules

bmi_topography.api_key module

class bmi_topography.api_key.ApiKey(api_key, source='user')[source]

Bases: object

Store an API key to use when fetching topography data from OpenTopography.

Parameters:

  • api_key (str) – An API key as a (non-empty) string.

  • source (str, optional) – A string that indicates where the key came from. Possible values are: user, env, file, and demo.

Raises:

Examples

>>> from bmi_topography.api_key import ApiKey
>>> api_key = ApiKey("foobar")
>>> api_key
ApiKey('foobar', source='user')
API_KEY_ENV_VAR = 'OPENTOPOGRAPHY_API_KEY'
API_KEY_FILES = ('.opentopography.txt', '~/.opentopography.txt')
DEMO_API_KEY = 'demoapikeyot2022'
property api_key

The API key.

classmethod from_env()[source]

Get the key from and environment variables.

classmethod from_file()[source]

Read the key from a file.

classmethod from_sources(api_key=None)[source]

Get a key from the first of a series of sources.

Look for a key from the following sources, returning the first found: (1) provided by a user through the api_key keyword, (2) provided by an environment variable, (3) provided in a text file, and (4) use a demo key

is_demo_key()[source]

Check if the key is a demo key.

property source

Where the API key came from.

bmi_topography.bbox module

class bmi_topography.bbox.BoundingBox(lower_left: Tuple[float], upper_right: Tuple[float])[source]

Bases: object

Represent a simple latitude-longitude bounding box.

Examples

Create a bounding box:

>>> from bmi_topography import BoundingBox
>>> bbox = BoundingBox((33, 111), (44, 122))
>>> print(bbox)
[(33, 111), (44, 122)]
property east
property lower_left

The southwest corner of the box, given by tuple of (south, west).

property north
property south
property upper_right

The northeast corner of the box, given by tuple of (north, east).

property west

bmi_topography.bmi module

class bmi_topography.bmi.BmiGridUniformRectilinear(shape, yx_spacing, yx_of_lower_left)

Bases: tuple

shape

Alias for field number 0

yx_of_lower_left

Alias for field number 2

yx_spacing

Alias for field number 1

class bmi_topography.bmi.BmiTopography[source]

Bases: Bmi

BMI-mediated access to NASA SRTM land elevation data.

finalize() → None[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.

get_component_name() → str[source]

Name of the component.

Returns:

The name of the component.

Return type:

str

get_current_time() → float[source]

Current time of the model.

Returns:

The current model time.

Return type:

float

get_end_time() → float[source]

End time of the model.

Returns:

The maximum model time.

Return type:

float

get_grid_edge_count(grid: int) → int[source]

Get the number of edges in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid edges.

Return type:

int

get_grid_edge_nodes(grid: int, edge_nodes: ndarray) → ndarray[source]

Get the edge-node connectivity.

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of int

get_grid_face_count(grid: int) → int[source]

Get the number of faces in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid faces.

Return type:

int

get_grid_face_edges(grid: int, face_edges: ndarray) → ndarray[source]

Get the face-edge connectivity.

Parameters:

  • grid (int) – A grid identifier.

  • face_edges (ndarray of int) – A numpy array to place the face-edge connectivity.

Returns:

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

Return type:

ndarray of int

get_grid_face_nodes(grid: int, face_nodes: ndarray) → ndarray[source]

Get the face-node connectivity.

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of int

get_grid_node_count(grid: int) → int[source]

Get the number of nodes in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid nodes.

Return type:

int

get_grid_nodes_per_face(grid: int, nodes_per_face: ndarray) → ndarray[source]

Get the number of nodes for each face.

Parameters:

  • grid (int) – A grid identifier.

  • nodes_per_face (ndarray of int, shape (nfaces,)) – A numpy array to place the number of edges per face.

Returns:

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

Return type:

ndarray of int

get_grid_origin(grid: int, origin: ndarray) → ndarray[source]

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

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of float

get_grid_rank(grid: int) → int[source]

Get number of dimensions of the computational grid.

Parameters:

grid (int) – A grid identifier.

Returns:

Rank of the grid.

Return type:

int

get_grid_shape(grid: int, shape: ndarray) → ndarray[source]

Get dimensions of the computational grid.

Parameters:

  • grid (int) – A grid identifier.

  • shape (ndarray of int, shape (ndim,)) – A numpy array into which to place the shape of the grid.

Returns:

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

Return type:

ndarray of int

get_grid_size(grid: int) → int[source]

Get the total number of elements in the computational grid.

Parameters:

grid (int) – A grid identifier.

Returns:

Size of the grid.

Return type:

int

get_grid_spacing(grid: int, spacing: ndarray) → ndarray[source]

Get distance between nodes of the computational grid.

Parameters:

  • grid (int) – A grid identifier.

  • spacing (ndarray of float, shape (ndim,)) – A numpy array to hold the spacing between grid rows and columns.

Returns:

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

Return type:

ndarray of float

get_grid_type(grid: int) → str[source]

Get the grid type as a string.

Parameters:

grid (int) – A grid identifier.

Returns:

Type of grid as a string.

Return type:

str

get_grid_x(grid: int, x: ndarray) → ndarray[source]

Get coordinates of grid nodes in the x direction.

Parameters:

  • grid (int) – A grid identifier.

  • x (ndarray of float, shape (nrows,)) – A numpy array to hold the x-coordinates of the grid node columns.

Returns:

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

Return type:

ndarray of float

get_grid_y(grid: int, y: ndarray) → ndarray[source]

Get coordinates of grid nodes in the y direction.

Parameters:

  • grid (int) – A grid identifier.

  • y (ndarray of float, shape (ncols,)) – A numpy array to hold the y-coordinates of the grid node rows.

Returns:

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

Return type:

ndarray of float

get_grid_z(grid: int, z: ndarray) → ndarray[source]

Get coordinates of grid nodes in the z direction.

Parameters:

  • grid (int) – A grid identifier.

  • z (ndarray of float, shape (nlayers,)) – A numpy array to hold the z-coordinates of the grid nodes layers.

Returns:

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

Return type:

ndarray of float

get_input_item_count() → int[source]

Count of a model’s input variables.

Returns:

The number of input variables.

Return type:

int

get_input_var_names() → Tuple[str][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.

get_output_item_count() → int[source]

Count of a model’s output variables.

Returns:

The number of output variables.

Return type:

int

get_output_var_names() → Tuple[str][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

get_start_time() → float[source]

Start time of the model.

Model times should be of type float.

Returns:

The model start time.

Return type:

float

get_time_step() → float[source]

Current time step of the model.

The model time step should be of type float.

Returns:

The time step used in model.

Return type:

float

get_time_units() → str[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.

get_value(name: str, dest: ndarray) → ndarray[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:

  • name (str) – An input or output variable name, a CSDMS Standard Name.

  • dest (ndarray) – A numpy array into which to place the values.

Returns:

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

Return type:

ndarray

get_value_at_indices(name: str, dest: ndarray, inds: ndarray) → ndarray[source]

Get values at particular indices.

Parameters:

  • 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.

Returns:

Value of the model variable at the given location.

Return type:

array_like

get_value_ptr(name: str) → ndarray[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:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

A reference to a model variable.

Return type:

array_like

get_var_grid(name: str) → int[source]

Get grid identifier for the given variable.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

The grid identifier.

Return type:

int

get_var_itemsize(name: str) → int[source]

Get memory use for each array element in bytes.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

Item size in bytes.

Return type:

int

get_var_location(name: str) → str[source]

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.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

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

Return type:

str

Notes

CSDMS uses the ugrid conventions to define unstructured grids.

get_var_nbytes(name: str) → int[source]

Get size, in bytes, of the given variable.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

The size of the variable, counted in bytes.

Return type:

int

get_var_type(name: str) → str[source]

Get data type of the given variable.

Parameters:

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

get_var_units(name: str) → str[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:

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.

initialize(config_file: str) → None[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:

config_file (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.

set_value(name: str, values: ndarray) → None[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.

set_value_at_indices(name: str, inds: ndarray, src: ndarray) → None[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.

update() → None[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.

update_until(time: float) → None[source]

Advance model state until the given time.

Parameters:

time (float) – A model time later than the current model time.

class bmi_topography.bmi.BmiVar(dtype, itemsize, nbytes, units, location, grid)

Bases: tuple

dtype

Alias for field number 0

grid

Alias for field number 5

itemsize

Alias for field number 1

location

Alias for field number 4

nbytes

Alias for field number 2

units

Alias for field number 3

bmi_topography.cli module

Command-line interface for bmi-topography

bmi_topography.errors module

exception bmi_topography.errors.BadApiKeySource[source]

Bases: BmiTopographyError

Raise for an invalid API key source.

exception bmi_topography.errors.BadKeyError[source]

Bases: BmiTopographyError

Raise for an invalid key.

exception bmi_topography.errors.BmiTopographyError[source]

Bases: Exception

Base exception for all bmi_topography errors.

exception bmi_topography.errors.MissingKeyError[source]

Bases: BmiTopographyError

Raise if an API key cannot be found.

bmi_topography.topography module

Base class to access elevation data

class bmi_topography.topography.Topography(dem_type=None, south=None, north=None, west=None, east=None, output_format=None, cache_dir=None, api_key=None)[source]

Bases: object

Fetch and cache land elevation data from OpenTopography.

DEFAULT = {'cache_dir': '~/.bmi_topography', 'dem_type': 'SRTMGL3', 'east': -118.465576, 'north': 38.091337, 'output_format': 'GTiff', 'south': 36.738884, 'west': -120.168457}
NETLOC = 'portal.opentopography.org'
PATH = '/API/globaldem'
SCHEME = 'https'
VALID_DEM_TYPES = ('SRTMGL3', 'SRTMGL1', 'SRTMGL1_E', 'AW3D30', 'AW3D30_E', 'SRTM15Plus', 'NASADEM', 'COP30', 'COP90')
VALID_OUTPUT_FORMATS = {'AAIGrid': 'asc', 'GTiff': 'tif', 'HFA': 'img'}
property bbox
property cache_dir
property da
static data_url()[source]
property dem_type
fetch()[source]

Download and locally store topography data.

Returns:

The path to the downloaded file

Return type:

pathlib.Path

property file_extension
load()[source]

Load a cached topography data file into an xarray DataArray.

Returns:

A container for the data

Return type:

xarray.DataArray

property output_format

Module contents

class bmi_topography.BmiTopography[source]

Bases: Bmi

BMI-mediated access to NASA SRTM land elevation data.

finalize() → None[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.

get_component_name() → str[source]

Name of the component.

Returns:

The name of the component.

Return type:

str

get_current_time() → float[source]

Current time of the model.

Returns:

The current model time.

Return type:

float

get_end_time() → float[source]

End time of the model.

Returns:

The maximum model time.

Return type:

float

get_grid_edge_count(grid: int) → int[source]

Get the number of edges in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid edges.

Return type:

int

get_grid_edge_nodes(grid: int, edge_nodes: ndarray) → ndarray[source]

Get the edge-node connectivity.

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of int

get_grid_face_count(grid: int) → int[source]

Get the number of faces in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid faces.

Return type:

int

get_grid_face_edges(grid: int, face_edges: ndarray) → ndarray[source]

Get the face-edge connectivity.

Parameters:

  • grid (int) – A grid identifier.

  • face_edges (ndarray of int) – A numpy array to place the face-edge connectivity.

Returns:

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

Return type:

ndarray of int

get_grid_face_nodes(grid: int, face_nodes: ndarray) → ndarray[source]

Get the face-node connectivity.

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of int

get_grid_node_count(grid: int) → int[source]

Get the number of nodes in the grid.

Parameters:

grid (int) – A grid identifier.

Returns:

The total number of grid nodes.

Return type:

int

get_grid_nodes_per_face(grid: int, nodes_per_face: ndarray) → ndarray[source]

Get the number of nodes for each face.

Parameters:

  • grid (int) – A grid identifier.

  • nodes_per_face (ndarray of int, shape (nfaces,)) – A numpy array to place the number of edges per face.

Returns:

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

Return type:

ndarray of int

get_grid_origin(grid: int, origin: ndarray) → ndarray[source]

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

Parameters:

  • 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.

Returns:

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

Return type:

ndarray of float

get_grid_rank(grid: int) → int[source]

Get number of dimensions of the computational grid.

Parameters:

grid (int) – A grid identifier.

Returns:

Rank of the grid.

Return type:

int

get_grid_shape(grid: int, shape: ndarray) → ndarray[source]

Get dimensions of the computational grid.

Parameters:

  • grid (int) – A grid identifier.

  • shape (ndarray of int, shape (ndim,)) – A numpy array into which to place the shape of the grid.

Returns:

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

Return type:

ndarray of int

get_grid_size(grid: int) → int[source]

Get the total number of elements in the computational grid.

Parameters:

grid (int) – A grid identifier.

Returns:

Size of the grid.

Return type:

int

get_grid_spacing(grid: int, spacing: ndarray) → ndarray[source]

Get distance between nodes of the computational grid.

Parameters:

  • grid (int) – A grid identifier.

  • spacing (ndarray of float, shape (ndim,)) – A numpy array to hold the spacing between grid rows and columns.

Returns:

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

Return type:

ndarray of float

get_grid_type(grid: int) → str[source]

Get the grid type as a string.

Parameters:

grid (int) – A grid identifier.

Returns:

Type of grid as a string.

Return type:

str

get_grid_x(grid: int, x: ndarray) → ndarray[source]

Get coordinates of grid nodes in the x direction.

Parameters:

  • grid (int) – A grid identifier.

  • x (ndarray of float, shape (nrows,)) – A numpy array to hold the x-coordinates of the grid node columns.

Returns:

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

Return type:

ndarray of float

get_grid_y(grid: int, y: ndarray) → ndarray[source]

Get coordinates of grid nodes in the y direction.

Parameters:

  • grid (int) – A grid identifier.

  • y (ndarray of float, shape (ncols,)) – A numpy array to hold the y-coordinates of the grid node rows.

Returns:

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

Return type:

ndarray of float

get_grid_z(grid: int, z: ndarray) → ndarray[source]

Get coordinates of grid nodes in the z direction.

Parameters:

  • grid (int) – A grid identifier.

  • z (ndarray of float, shape (nlayers,)) – A numpy array to hold the z-coordinates of the grid nodes layers.

Returns:

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

Return type:

ndarray of float

get_input_item_count() → int[source]

Count of a model’s input variables.

Returns:

The number of input variables.

Return type:

int

get_input_var_names() → Tuple[str][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.

get_output_item_count() → int[source]

Count of a model’s output variables.

Returns:

The number of output variables.

Return type:

int

get_output_var_names() → Tuple[str][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

get_start_time() → float[source]

Start time of the model.

Model times should be of type float.

Returns:

The model start time.

Return type:

float

get_time_step() → float[source]

Current time step of the model.

The model time step should be of type float.

Returns:

The time step used in model.

Return type:

float

get_time_units() → str[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.

get_value(name: str, dest: ndarray) → ndarray[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:

  • name (str) – An input or output variable name, a CSDMS Standard Name.

  • dest (ndarray) – A numpy array into which to place the values.

Returns:

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

Return type:

ndarray

get_value_at_indices(name: str, dest: ndarray, inds: ndarray) → ndarray[source]

Get values at particular indices.

Parameters:

  • 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.

Returns:

Value of the model variable at the given location.

Return type:

array_like

get_value_ptr(name: str) → ndarray[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:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

A reference to a model variable.

Return type:

array_like

get_var_grid(name: str) → int[source]

Get grid identifier for the given variable.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

The grid identifier.

Return type:

int

get_var_itemsize(name: str) → int[source]

Get memory use for each array element in bytes.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

Item size in bytes.

Return type:

int

get_var_location(name: str) → str[source]

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.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

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

Return type:

str

Notes

CSDMS uses the ugrid conventions to define unstructured grids.

get_var_nbytes(name: str) → int[source]

Get size, in bytes, of the given variable.

Parameters:

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns:

The size of the variable, counted in bytes.

Return type:

int

get_var_type(name: str) → str[source]

Get data type of the given variable.

Parameters:

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

get_var_units(name: str) → str[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:

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.

initialize(config_file: str) → None[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:

config_file (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.

set_value(name: str, values: ndarray) → None[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.

set_value_at_indices(name: str, inds: ndarray, src: ndarray) → None[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.

update() → None[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.

update_until(time: float) → None[source]

Advance model state until the given time.

Parameters:

time (float) – A model time later than the current model time.

class bmi_topography.BoundingBox(lower_left: Tuple[float], upper_right: Tuple[float])[source]

Bases: object

Represent a simple latitude-longitude bounding box.

Examples

Create a bounding box:

>>> from bmi_topography import BoundingBox
>>> bbox = BoundingBox((33, 111), (44, 122))
>>> print(bbox)
[(33, 111), (44, 122)]
property east
property lower_left

The southwest corner of the box, given by tuple of (south, west).

property north
property south
property upper_right

The northeast corner of the box, given by tuple of (north, east).

property west
class bmi_topography.Topography(dem_type=None, south=None, north=None, west=None, east=None, output_format=None, cache_dir=None, api_key=None)[source]

Bases: object

Fetch and cache land elevation data from OpenTopography.

DEFAULT = {'cache_dir': '~/.bmi_topography', 'dem_type': 'SRTMGL3', 'east': -118.465576, 'north': 38.091337, 'output_format': 'GTiff', 'south': 36.738884, 'west': -120.168457}
NETLOC = 'portal.opentopography.org'
PATH = '/API/globaldem'
SCHEME = 'https'
VALID_DEM_TYPES = ('SRTMGL3', 'SRTMGL1', 'SRTMGL1_E', 'AW3D30', 'AW3D30_E', 'SRTM15Plus', 'NASADEM', 'COP30', 'COP90')
VALID_OUTPUT_FORMATS = {'AAIGrid': 'asc', 'GTiff': 'tif', 'HFA': 'img'}
property bbox
property cache_dir
property da
static data_url()[source]
property dem_type
fetch()[source]

Download and locally store topography data.

Returns:

The path to the downloaded file

Return type:

pathlib.Path

property file_extension
load()[source]

Load a cached topography data file into an xarray DataArray.

Returns:

A container for the data

Return type:

xarray.DataArray

property output_format