Running Hype model using eWaterCycle package

This notebook shows how to run Hype model using a demo use-case.

import warnings

warnings.filterwarnings("ignore", category=UserWarning)

import pandas as pd

import ewatercycle.models
import ewatercycle.parameter_sets

Load parameter set

The parameter set demo.zip should be downloaded from https://sourceforge.net/projects/hype/files/release_hype_5_6_2/ and unzipped.

parameter_set_dir = "<path where demo.zip was extracted to>"
parameter_set = ewatercycle.parameter_sets.ParameterSet(
    name="hype_demo",
    directory=parameter_set_dir,
    config=parameter_set_dir + "/info.txt",
    target_model="hype",
)

Setting up the model

Note that the model version and the parameterset versions should be compatible.

ewatercycle.models.Hype.available_versions

('feb2021',)

model = ewatercycle.models.Hype(version="feb2021", parameter_set=parameter_set)

eWaterCycle exposes a selected set of configurable parameters. These can be modified in the setup() method.

model.parameters

[('start_time', '1961-01-01T00:00:00Z'),
 ('end_time', '1963-12-31T00:00:00Z'),
 ('crit_time', '1962-01-01T00:00:00Z')]

Calling setup() will start up a docker or singularity container. Be careful with calling it multiple times!

cfg_file, cfg_dir = model.setup(end_time="1962-06-30T00:00:00Z")
cfg_file, cfg_dir

('/tmp/hype_20220607_121055/info.txt', '/tmp/hype_20220607_121055')

model.parameters

[('start_time', '1961-01-01T00:00:00Z'),
 ('end_time', '1962-06-30T00:00:00Z'),
 ('crit_time', '1962-01-01T00:00:00Z')]

Note that the parameters have been changed. A new config file which incorporates these updated parameters has been generated as well. If you want to see or modify any additional model settings, you can acces this file directly. When you’re ready, pass the path to the config file to initialize().

model.initialize(cfg_file)

Running the model

Simply running the model from start to end is straightforward. At each time step we can retrieve information from the model.

discharge = []
time_range = []
end_time = model.end_time

while model.time < end_time:
    model.update()
    # The demo parameter set has a single sub catchment so store first value of array
    discharge.append(model.get_value("comp outflow olake")[0])
    time_range.append(model.time_as_datetime.date())
    print(model.time_as_isostr, end="\r")

1962-06-30T00:00:00Z

Interacting with the model

Hype model exposes many variables.

model.output_var_names

('comp outflow olake',
 'rec outflow olake',
 'air temperature',
 'corrected air temper',
 'precipitation',
 'corr precipitation',
 'subbasin evaporation',
 'computed runoff',
 'computed soil water')

Hype is a lumped sub-basin model so there are values per subbasin. The outflow of all sub-basins can be requested with:

da = model.get_value("comp outflow olake")
da

array([6.71861417e-05])

The model has some info about the sub-basins:

[
    model.bmi.get_grid_size(1),
    model.bmi.get_grid_rank(1),
    model.bmi.get_grid_type(1),
    model.bmi.get_grid_shape(1),
    model.bmi.get_grid_x(1),
    model.bmi.get_grid_y(1),
]

[1, 1, 'unstructured', (1,), array([0.]), array([0.])]

Inspect the results

simulated_discharge = pd.DataFrame(
    {"simulation": discharge}, index=pd.to_datetime(time_range)
)

simulated_discharge.plot(figsize=(12, 8))

<AxesSubplot:>

Cleaning up

Models usually perform some “wrap up tasks” at the end of a model run, such as writing the last outputs to disk and releasing memory. In the case of eWaterCycle, another important teardown task is destroying the docker or singularity container in which the model was running. This can free up a lot of resources on your system. Therefore it is good practice to always call finalize() when you’re done with an experiment.

model.finalize()