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.

Tip

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

Tip

More detailed documentation on building t-route for ngen is described in ngen documentation.

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). If your NetCDF is installed in a non-standard location, you may need set the path to it in the compiler.sh file, which is explained in the file.

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