ewatercycle.base.model

Base classes for eWaterCycle models.

Module Contents

ewatercycle.base.model.logger
ewatercycle.base.model.ISO_TIMEFMT = '%Y-%m-%dT%H:%M:%SZ'
class ewatercycle.base.model.eWaterCycleModel

Bases: pydantic.BaseModel, abc.ABC

Base functionality for eWaterCycle models.

Children need to specify how to make their BMI instance: in a container or local python environment.

forcing: ewatercycle.base.forcing.DefaultForcing | None = None
parameter_set: ewatercycle.base.parameter_set.ParameterSet | None = None
property version: str

Version of the model.

property parameters: collections.abc.ItemsView[str, Any]

Display the model’s parameters and their values.

setup(*, cfg_dir: str | None = None, **kwargs) → tuple[str, str]

Perform model setup.

  1. Creates config file and config directory

  2. Start bmi instance and store as self._bmi

Parameters:

  • cfg_dir – Optionally specify path to use as config dir. Will be created if it doesn’t exist yet. Behaviour follows PyMT documentation (https://pymt.readthedocs.io/en/latest/usage.html#model-setup). Only difference is that we don’t create a temporary directory, but rather a time-stamped folder inside ewatercycle.CFG[‘output_dir’].

  • *args – Positional arguments. Sub class should specify each arg.

  • **kwargs – Named arguments. Sub class should specify each arg.

Returns:

Path to config file and path to config directory

initialize(config_file: str) → None

Initialize the model.

Parameters:

config_file – Name of initialization file.

finalize() → None

Perform tear-down tasks for the model.

After finalization, the model should not be used anymore.

update() → None

Advance model state by one time step.

get_value(name: str) → numpy.ndarray

Get a copy of values of the given variable.

Parameters:

name – Name of variable

get_value_at_coords(name, lat: collections.abc.Iterable[float], lon: collections.abc.Iterable[float]) → numpy.ndarray

Get a copy of values of the given variable at lat/lon coordinates.

Parameters:

  • name – Name of variable

  • lat – Latitudinal value

  • lon – Longitudinal value

set_value(name: str, value: numpy.ndarray) → None

Specify a new value for a model variable.

Parameters:

  • name – Name of variable

  • value – The new value for the specified variable.

set_value_at_coords(name: str, lat: collections.abc.Iterable[float], lon: collections.abc.Iterable[float], values: numpy.ndarray) → None

Specify a new value for a model variable at at lat/lon coordinates.

Parameters:

  • name – Name of variable

  • lat – Latitudinal value

  • lon – Longitudinal value

  • values – The new value for the specified variable.

get_value_as_xarray(name: str) → xarray.DataArray

Get a copy values of the given variable as xarray DataArray.

The xarray object also contains time, coordinate information and additional attributes such as the units.

Parameters:

name – Name of the variable

Returns:

Dataarray of the variable.

property bmi: bmipy.Bmi

Bmi class wrapped by the model.

property start_time: float

Start time of the model.

property end_time: float

End time of the model.

property time: float

Current time of the model.

property time_units: str

Time units of the model.

Formatted using UDUNITS standard from Unidata.

property time_step: float

Current time step of the model.

property output_var_names: collections.abc.Iterable[str]

List of a model’s output variables.

property input_var_names: collections.abc.Iterable[str]

List of a model’s input variables.

var_units(name: str) → str

Return the given variable’s units.

property start_time_as_isostr: str

Start time of the model.

In UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

property end_time_as_isostr: str

End time of the model.

In UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

property time_as_isostr: str

Current time of the model.

In UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

property start_time_as_datetime: datetime.datetime

Start time of the model as a datetime object.

property end_time_as_datetime: datetime.datetime

End time of the model as a datetime object’.

property time_as_datetime: datetime.datetime

Current time of the model as a datetime object’.

get_latlon_grid(name) → tuple[Any, Any, Any]

Grid latitude, longitude and shape for variable.

The default implementation takes Bmi’s x as longitude and y as latitude. See bmi.readthedocs.io/en/stable/model_grids.html#structured-grids.

Some models may deviate from this default. They can provide their own implementation or use a BMI wrapper as in the wflow and pcrglob examples.

Parameters:

name – Name of the variable

class ewatercycle.base.model.LocalModel

Bases: eWaterCycleModel

eWaterCycle model running in a local Python environment.

Mostly intended for development purposes.

bmi_class: type[bmipy.Bmi]
property version: str

Version of the model package.

class ewatercycle.base.model.ContainerizedModel

Bases: eWaterCycleModel

eWaterCycle model running inside a container.

This is the recommended method for sharing eWaterCycle models.

bmi_image: Annotated[ewatercycle.container.ContainerImage, BeforeValidator(_parse_containerimage)]
protocol: Literal['grpc', 'openapi'] = 'grpc'
model_config
property version: str

Version of the container image.

property logs: str

Return the container logs.