Integrate Office of Water Prediction NextGen Hydrofabric for Source/Sink Construction of SCHISM mesh

[jduckerOWP]

The Office of Water Prediction is currently developing the Next Generation Water Resources Modeling Framework (NextGen) project using SCHISM as a coastal model. We are constructing a common hydrofabric to apply a new routing network model called T-Route, which is constrained to the NextGen hydrofabric itself. The NextGen hydrofabric encapsulates the flow path geometry information within a geopackage file. This pull request aims to accomplish the following:

1. Create a new source/sink module that will directly handle NextGen hydofabric geopackage files for finding the SCHISM hgrid.gr3 sources and sinks based on the respective flowpath geometries within the hydrofabric.
2. Streamline the NGen module to extract geo-dataframes for the SCHISM source and sink terms.
3. Create a source.nc file that is only compatible with the SCHISM Basic Model Interface (NWM_BMI=1 option in param.nml). This means that this file essentially only tells SCHISM the element identifiers for sources and sinks while bypassing any forcing data. This special source.nc file also includes a netcdf field that lists out the flow path identifiers from the NextGen hydrofabric sources and sinks. This field will be needed for further development of the SCHISM BMI in the coming months.
4. No development can be completed yet in PySCHISM to extract NextGen Hydrofabric T-Route retrospective data since the model is not yet nearing an operational phase. Once a public repository becomes available for T-Route, we will begin constructing modules to extract streamflow data for constructing .th files similar to the National Water Model.
5. An example Python module to implement this NextGen Hydrofabric source/sink method is available within the "examples" directory. Please use the conus.gpkg file located in the NextGen Hydrofabric AWS server as part of the example method.

I'll be happy to answer any questions or work with developers to merge this PySCHISM branch into the main branch of the repository.

[josephzhang8]

Thx @jduckerOWP !
@feiye-vims
I reviewed the changes, which are mostly enhancement but I don't know pySCHISM enough. Can u plz review? Thx

[feiye-vims]

Thx @jduckerOWP ! @feiye-vims I reviewed the changes, which are mostly enhancement but I don't know pySCHISM enough. Can u plz review? Thx

I don't think the new code interferes with any existing functions. In fact, it is the original element paring function that has minor problems.

Thanks @jduckerOWP

[jduckerOWP]

@feiye-vims is there an issue created on the PySCHISM page to describe the problem with the original element pairing problem? I'll be happy to take a look at it and see if our team can help fix the issues in the future. The idea here for the NextGen module was to at least mimic the process for creating the source.nc file with the original NWM vector-based routing network. However, we want to certainly fix the code if issues are introduced as well with linking the NextGen hydrofabric flow path network with the hgrid.gr3 file elements. Thanks again @josephzhang8 and @feiye-vims for both looking at this pull request quickly!

[feiye-vims]

@jduckerOWP Some other users and I identified the issue, and I briefly summarized it in issue #113. Everybody in our group is tied up with other more urgent tasks, so we haven't fixed it.