ngen cal usage guide

This guide will walk through calibrating a homogeneous set of model formulations on a set of five catchments on the Oyster River near Durham, New Hampshire over the time period of [2015-12-01 - 2015-12-30]. More information about the site and contributing area can be found on the USGS's real-time monitoring page for the most downstream USGS gauge within the study area, 01073000 - Oyster River Near Durham, NH.

Much of the required data to support this exercise has been created to support this activity. Several software and data components must be installed / downloaded prior to conducting the calibration exercise. See the below Prerequisites section before proceeding.

Prerequisites

Software

• Local installation of ngen.cal. See Installing ngen cal for guidance.
• Local installation of t-route. Refer to the Usage and testing section of the t-route readme for guidance.
• Local installation of the NextGen model engine. See the NextGen Wiki for guidance.
• Local installation of SLOTH, PET, Noah-OWP modular, and CFE modules. To install these modules, see the setting up the external components section of the Next Gen wiki.

Data

• Hydrofabric, atmospheric forcing, routing configuration, NextGen realization configuration, and BMI module configuration are all required to configure and run NextGen. For the sake of demonstration, these data have been created a priori to support this guide. These data can be found on the NextGen repository. Follow this link to download an archive of the required data.

Calibration Exercise

The following sections will walk through creating a ngen.cal configuration file and running a calibration exercise. An example configuration file is available on the ngen.cal repository. See comment blocks in the aforementioned example file for explanation of configuration options. Options are also described in the Configuration Options wiki page.

Configuring ngen.cal

# file: calibration_config.yaml
general:
  strategy: 
      # Type of strategy, currently supported is estimation
      type: estimation
      # defaults to dds (currently, the only supported algorithm)
      algorithm: "dds"

  # Enable model runtime logging (captures standard out and error and writes to file)
  # logs will be written to <model.type>.log when enabled
  # defaults to False, which sends all output to /dev/null
  log: True

  start_iteration: 0
  # The total number of search iterations to run
  iterations: 100

# Define parameters to calibrate, their bounds, and initial values.
cfe_params: &cfe_params
  - 
      name: maxsmc
      min: 0.2
      max: 1.0
      init: 0.439
  - 
      name: satdk
      min: 0.0
      max: 0.000726
      init: 3.38e-06
  - 
      name: slope
      min: 0.0
      max: 1.0
      init: 0.01
  - 
      name: expon
      min: 1.0
      max: 8.0
      init: 6.0

# Model specific configuration
model:
    type: ngen
    # NOTE: you may need to adjust this to the location of your NextGen installation
    # A binary in $PATH or a qualified path to the binary to run
    binary: "ngen"
    realization: ./example_bmi_multi_realization_config_w_routing.json
    # Required path to catchment hydrofabirc file
    catchments: ./hydrofabric/catchments.geojson
    # Required path to nexus hydrofabric file
    nexus: ./hydrofabric/nexus.geojson
    # Required path to hydrofabric crosswalk file
    crosswalk: ./hydrofabric/crosswalk.json
    # Each catchment upstream of observable nexus gets its own permuted parameter space, evaluates at one observable nexus 
    strategy: independent
    params: 
        CFE: *cfe_params
    
    eval_params:
      # choices are "kling_gupta", "nnse", "custom", "single_peak", "volume"
      objective: "kling_gupta"

In the above configuration file, ngen.cal will run NextGen 100 times and use dynamically dimensioned search algorithm (DDS) to search and adjust each catchment scale CFE formulation's parameter values. After each calibration iteration, ngen.cal will use the Kling-Gupta efficiency to evaluate model performance vs streamflow observations from the Oyster River Near Durham, NH - 01073000 gauge. This performance metric will be used to adjust formulation parameters for the next iteration.

Create a new file named, calibration_config.yaml in the same directory as the provided NextGen formulation configuration and copy and paste the above configuration.

ngen.cal CLI Usage

python -m ngen.cal --help

usage: __main__.py [-h] config_file

Calibrate catchments in NGEN NWM architecture.

positional arguments:
  config_file  The configuration yaml file for catchments to be operated on

optional arguments:
  -h, --help   show this help message and exit

To begin the calibration, run the following:

python -m ngen.cal calibration_config.yaml