Routing

Channel Routing Integration

In addition to general modeling, model engine also supports integrating with t-route for channel routing. To do this, a few additional requirements are necessary:

1. Model engine must be built with -DNGEN_WITH_PYTHON=ON and -DNGEN_WITH_ROUTING=ON.

2. t-route must be installed in either the system-wide Python packages, or a virtual environment.

3. The realization configuration file used must include the routing key in the document root, and a YAML routing configuration file is required.

   Note You can find examples of routing configuration files in the t-route repository.

With these requirements met, compiling and running ngen will automatically perform channel routing.

Important ngen will only search either the system packages, or the virtual environment packages for t-route. This means that if you have already built ngen with routing support, you can update your installed t-route version without rebuilding ngen.

Using the latest version of t-route

The git submodule of t-route in extern/t-route is based off commit 6f8033b, and since t-route is in active development, end-users may want to use the latest commit of t-route in their ngen build. In order to accomplish this, the minimal steps to take are:

1. Clone the latest version of t-route to a local directory

   git clone https://github.com/NOAA-OWP/t-route
   

2. Install t-route into your system packages OR virtual environment if activated

   cd t-route
   ./compiler.sh
   

3. Configure ngen with -DNGEN_WITH_PYTHON=ON and -DNGEN_WITH_ROUTING=ON, or run an already compiled executable of ngen.

Known Issues

NetCDF Fortran Error

If you are facing a NetCDF error that looks like

Fatal Error: Cannot read module file 'netcdf.mod' opened at (1), because it was created by a different version of GNU Fortran

Then this is due to a compiler version mismatch between netcdf.mod and the compiler version you are using to build t-route. The primary way to resolve this is to rebuild the Fortran version of NetCDF using your current Fortran compiler (i.e. gfortran).

However, if you are working on a UCS machine, then a correctly compiled version of NetCDF should be located in /usr/include. To use this version, you need to pass some environment variables to the subshell of compiler.sh:

F90=gfortran NETCDF=/usr/include ./compiler.sh

Cython 3.0.4 Error

If you are facing a Cython error that looks like

TypeError: performance_hint() missing 1 required positional argument: 'env'

Then this is due to a Cython bug in 3.0.4. See Cython#5771 for more information, and Cython#5773 for an incoming fix that should be available in Cython 3.0.5.

A workaround for now is to downgrade Cython to version 3.0.3.

Segmentation Fault

One possible issue that can cause a segmentation fault when attempting to perform channel routing in ngen is when using pyarrow >= 12.0.0. For details, see ngen#614.

A solution to this is to downgrade pyarrow to 11.0.0 or lower:

pip install -U pyarrow==11.0.0