PCRGlobWB example use case

This example shows how the PCRGlobWB model can be used within the eWaterCycle system. It is based on the example use case from https://github.com/UU-Hydro/PCR-GLOBWB_input_example.

This example use case assumes that the ewatercycle platform has been installed and configured on your system. See our system setup documentation for instructions if this is not the case.

# This cell is only used to suppress some distracting output messages
import warnings

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

import matplotlib.pyplot as plt
from cartopy import crs
from cartopy import feature as cfeature

import ewatercycle.forcing
import ewatercycle.models
import ewatercycle.parameter_sets

Loading a parameter set

A set of (example) parameter sets come pre-installed on the eWaterCycle system (see system setup if this is not the case).

ewatercycle.parameter_sets.available_parameter_sets()

('lisflood_fraser', 'pcrglobwb_rhinemeuse_30min', 'wflow_rhine_sbm_nc')

Existing parametersets can easily be loaded:

parameter_set = ewatercycle.parameter_sets.get_parameter_set(
    "pcrglobwb_rhinemeuse_30min"
)
print(parameter_set)

Parameter set
-------------
name=pcrglobwb_rhinemeuse_30min
directory=/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min
config=/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min/setup_natural_test.ini
doi=N/A
target_model=pcrglobwb
supported_model_versions={'setters'}

It is also possible to load a custom parameterset by passing in the relevant parameters directly:

custom_parameter_set = ewatercycle.parameter_sets.ParameterSet(
    name="custom_parameter_set",
    directory="/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min",
    config="/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min/setup_natural_test.ini",
    target_model="pcrglobwb",
    supported_model_versions={"setters"},
)

Load forcing data

For this example case, the forcing is already included in the parameter set and configured correctly. Therefore in principle this step can be skipped. However, for the purpose of illustration, we show how the forcing would be loaded using the ewatercycle.forcing module, as if it came from another source. To learn about forcing generation, see our preprocessing examples.

forcing = ewatercycle.forcing.load_foreign(
    target_model="pcrglobwb",
    start_time="2001-01-01T00:00:00Z",
    end_time="2010-12-31T00:00:00Z",
    directory="./parameter-sets/pcrglobwb_rhinemeuse_30min/forcing",
    shape=None,  # if available, it can be used e.g. for plotting
    forcing_info=dict(
        # model-specific options
        precipitationNC="precipitation_2001to2010.nc",
        temperatureNC="temperature_2001to2010.nc",
    ),
)
print(forcing)

Forcing data for PCRGlobWB
--------------------------
Directory: /home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min/forcing
Start time: 2001-01-01T00:00:00Z
End time: 2010-12-31T00:00:00Z
Shapefile: None
Additional information for model config:
  - temperatureNC: temperature_2001to2010.nc
  - precipitationNC: precipitation_2001to2010.nc

Setting up the model

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

ewatercycle.models.PCRGlobWB.available_versions

('setters',)

pcrglob = ewatercycle.models.PCRGlobWB(
    version="setters", parameter_set=parameter_set, forcing=forcing
)
print(pcrglob)

eWaterCycle PCRGlobWB
-------------------
Version = setters
Parameter set =
  Parameter set
  -------------
  name=pcrglobwb_rhinemeuse_30min
  directory=/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min
  config=/home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min/setup_natural_test.ini
  doi=N/A
  target_model=pcrglobwb
  supported_model_versions={'setters'}
Forcing =
  Forcing data for PCRGlobWB
  --------------------------
  Directory: /home/peter/ewatercycle/ewatercycle/docs/examples/parameter-sets/pcrglobwb_rhinemeuse_30min/forcing
  Start time: 2001-01-01T00:00:00Z
  End time: 2010-12-31T00:00:00Z
  Shapefile: None
  Additional information for model config:
    - temperatureNC: temperature_2001to2010.nc
    - precipitationNC: precipitation_2001to2010.nc

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

pcrglob.parameters

[('start_time', '2001-01-01T00:00:00Z'),
 ('end_time', '2001-01-01T00:00:00Z'),
 ('routing_method', 'accuTravelTime'),
 ('max_spinups_in_years', '20')]

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

cfg_file, cfg_dir = pcrglob.setup(
    end_time="2001-02-28T00:00:00Z", max_spinups_in_years=5
)
cfg_file, cfg_dir

Running /home/peter/ewatercycle/ewatercycle/ewatercycle-pcrg-grpc4bmi-setters.sif singularity container on port 50639

('/home/peter/ewatercycle/ewatercycle/docs/examples/pcrglobwb_20210714_141432/pcrglobwb_ewatercycle.ini',
 '/home/peter/ewatercycle/ewatercycle/docs/examples/pcrglobwb_20210714_141432')

pcrglob.parameters

[('start_time', '2001-01-01T00:00:00Z'),
 ('end_time', '2001-02-28T00:00:00Z'),
 ('routing_method', 'accuTravelTime'),
 ('max_spinups_in_years', '5')]

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

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

while pcrglob.time < pcrglob.end_time:
    print(pcrglob.time_as_isostr, end="\r")
    pcrglob.update()

2001-02-27T00:00:00Z

Interacting with the model

PCRGlobWB exposes many variables. Just a few of them are shown here:

list(pcrglob.output_var_names)[-15:-5]

('total_abstraction',
 'livestockWaterWithdrawalVolume',
 'desalination_source_abstraction',
 'discharge',
 'temperature',
 'upper_soil_transpiration',
 'snow_water_equivalent',
 'total_runoff',
 'transpiration_from_irrigation',
 'fraction_of_surface_water')

Model fields can be fetched as xarray objects (or as flat numpy arrays using get_value()):

da = pcrglob.get_value_as_xarray("discharge")
da.thin(5)  # only show every 5th value in each dim

<xarray.DataArray 'discharge' (latitude: 3, longitude: 4)>
array([[         nan,          nan,          nan,          nan],
       [         nan,  74.54685211,  10.38944435,          nan],
       [         nan, 188.07923889,          nan,          nan]])
Coordinates:
  * longitude  (longitude) float64 3.75 6.25 8.75 11.25
  * latitude   (latitude) float64 46.25 48.75 51.25
    time       object 2001-02-28 00:00:00
Attributes:
    units:    m3.s-1

Xarray makes it very easy to plot the data. In the figure below, we add three points that we will use to illustrate that we can also access individual grid cells.

fig = plt.figure(dpi=120)
ax = fig.add_subplot(111, projection=crs.PlateCarree())
da.plot(ax=ax, cmap="GnBu")

# Overlay ocean and coastines
ax.add_feature(cfeature.OCEAN)
ax.add_feature(cfeature.RIVERS, color="k")
ax.coastlines()

# Add some verification points
target_longitudes = [7.8, 10.2, 11]
target_latitudes = [50.3, 49.8, 47]
ax.scatter(target_longitudes, target_latitudes, s=250, c="r", marker="x", lw=2)

<matplotlib.collections.PathCollection at 0x7f636aa5c4f0>

We can get (or set) the values at custom points as well:

pcrglob.get_value_at_coords("discharge", lon=target_longitudes, lat=target_latitudes)

array([713.2911377 ,  84.76369476,          nan])

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.

pcrglob.finalize()