Relationship of Catchment, Flowpath, and Waterbody

[hellkite500]

Background and reference

This is an attempt to begin formalizing the framework's handling and integration of HY_Waterbody. A more detailed relationship of HY_Waterbody can be seen here. A HY_Catchment has a one-to-one mapping to a HY_Flowpath. This flowpath is the logical conveyance mechanism for hydrologic information from the upstream HY_Nexus to the downstream HY_Nexus. So logically, a HY_Catchment produces lateral flow to a HY_Flowpath, which may then map that flow to the downstream nexus. Currently, a HY_Catchment interacts directly with the downstream Nexus, which semantically is the same as as the HY_Catchment contributing flow to the associated HY_Flowpath which then conveys water to the HY_Nexus.

Implementing these semantics opens up the integration of hydro-dynamic routing using HY_Waterbody, where the HY_Catchment contributes to a HY_Flowpath, which is linked (potentially one-to-many) to a set of waterbodies (and the waterbodies' internal cross/longitudal sections). These waterbody classes are then responsible for deciding how flow ultimately gets to the downstream nexus.

To ultimately route flow, we need several key pieces of information

• Initially, we would like to use current NWM routelink data which provides channel properties for each COMID in the NHDPlus network
• Need these waterbodies topologically consistent with refactored catchments
• Computationally friendly discretization of the channel/waterbody geometries, in the HY_Features sense, I think this would be done by describing for each waterbody a list of cross sections and longitudinal sections for each waterbody.
• Map NWM routlink properties to each waterbody/section

An example waterbody geojson might look like:

{
    "type": "FeatureCollection",
    "name": "waterbody_data",
    "crs": {"type": "name", "properties": {"name": "urn:ogc:def:crs:OGC:1.3:CRS84"}},
    "features": [
        {"type": "Feature", "id": "wb-1", "properties":
         {
              "type": "HY_River",
              "cross_sections": [
                       {"id":"id1", "width":123, "paramB":"valueB"},
                       {"id":"id2", "width":123, "paramB":"valueB1"}
                   ],
               "longitudal_sections": [
                       {"id":"id1", "cross_section":"id1", "length":123, "paramB":"valueB"},
                       {"id":"id2", "cross_section":"id2", "length":123, "paramB":"valueB1"}
                   ],
              "flowpath_id": "fp-1",  
              "realized_catchment":  "cat-1"
          }
        }
    ]
}

Note, the "realized_catchment" key and "flowpath_id" key may or may not be appropriate, still looking at the correct way to attach this to the overall topology.

This issue serves as a place to work through the definitions, format, and required information to define waterbodies in a meaningful context for the ultimate purpose of connecting them to some routing mechanic.

@dblodgett-usgs @mikejohnson51 @robertbartel @donaldwj what are your thoughts, and any next steps you can think of we need to work on on the hydrofabric or ngen support?

@jdmattern-noaa @jameshalgren I think we can extend this into the t-route ngen to better represent the t-route network using the waterbody cross/longitudal sections as the routing segments, and could use that as our initial routing test.

[hellkite500]

@fred-ogden you may be interested in following this discussion.

[hellkite500]

Here is another, somewhat simpler, diagram of the conceptual waterbody relationship in HY_Features.

[mikejohnson51]

After some follow up with @hellkite500 we are going to test two approaches. One that adds the waterbody/channel attributes to the flowpaths geojson similar to the above example, as well as one that is closer(?) to the HY_Features specification in which all water body information is stored as a separate JSON file with appropriate nexus, flowpath, and catchment references.

Maybe something like:

{
    "name": "waterbody_data",
    "features": [
        {"type": "Feature", "id": "wb-1", "properties":
         {
              "type": "HY_River",
              "cross_sections": [
                       {"nex-id":"id1", "cs-id":1, "width":123, "paramB":"valueB"},
                       {"nex-id":"id2", "cs-id":2, "width":123, "paramB":"valueB1"}
                   ],
               "longitudal_sections": [
                       {"nex-id":"id1", "cross_section":"cs-1", "length":123, "paramB":"valueB"},
                       {"nex-id":"id2", "cross_section":"cs-2", "length":123, "paramB":"valueB1"}
                   ],
              "flowpath_id": "fp-1",  
              "realized_catchment":  "cat-1"
          }
        }
    ]
}