pytuflow.NCGrid.flux_integral

pytuflow.NCGrid.flux_integral#

NCGrid.flux_integral(locations, data_types=None, time_fmt='relative', use_unit_flow=False)#

A convenience function that integrates the curve returned from the flux() method. This method is basically a wrapper around flux().cumsum() and will rename the returned DataFrame columns.

The parameters are passed directly into the flux() method. More information can be found within the flux() documentation.

Warning

The results of the flux_integral method should be used withe care. Similar caveats apply as in the flux() method. Read the flux() documentation for more information.

Parameters:

  • locations (LineString | list[LineString] | dict[str, LineString] | GeoDataFrame | str | PathLike) –

    The line(s) to extract the flux for. The location can be:

    • LineString represented by a list of tuple[x, y] coordinates.

    • LineString represented by a WKT string

    • shapely.LineString object

    • list[LineStrings]

    • dict[str, LineString] where the str will be used as the ID in the resulting pd.DataFrame

    • geopandas.GeoDataFrame

    • path to a GIS file containing lines

  • data_types (str | list[str], optional) – The result type(s) to extract the flux for. If left blank, the returned flux will be the flow across the line. If data_types are provided, this should typically be a tracer concentration (e.g. mg/L). In these cases, the returned flux will the mass flux (g/s) across the line.

  • time_fmt (str, optional) – The format for the time values. Options are "relative" or "absolute".

  • use_unit_flow (bool, optional) – Use unit flow if it is available. Otherwise, the fallback is depth x velocity. The resulting data frame column name will have either (q) if unit flow was used, or (d.v) if depth x velocity was used.

Returns:

An array containing the integrated flux across the line.

Return type:

pd.DataFrame

Examples

Estimate the cumulative volume of water passing over a line.

>>> res = ... # assume res is a Mesh or Grid instance
>>> vol = res.flux_integral('/path/to/line.shp')
>>> vol
      line/flux integral (d.v)
time
0.0                   0.000000
0.5                   0.000000
1.0                  80.615680
1.5                 132.488715
2.0                 149.876389
2.5                 158.860493
3.0                 163.762476

Estimate the cumulative mass of a constituent passing over a line.

>>> res = ... # assume res is a Mesh or Grid instance
>>> mass = res.flux_integral('/path/to/line.shp', 'conc tracer1')
>>> mass
      line/flux integral conc tracer1 (d.v)
time
0.0                                0.000000
0.5                                0.000000
1.0                               82.259233
1.5                              198.207042
2.0                              301.399413
2.5                              396.370227
3.0                              496.216145