pytuflow.NCGrid.flux

Contents

pytuflow.NCGrid.flux#

NCGrid.flux(locations, data_types='', time_fmt='relative', use_unit_flow=True, direction_convention='arithmetic')#

Returns the flux across a line. Tracer data type(s) can be provided to calculate the volume flux.

Does not currently support groundwater flux calculation.

Warning

The result of the flux() method should be used with care. Due to result interpolation, the resulting flux could be off by 10% or more. The error depends on variables such as result format, the hydraulic engine that created the results, whether SGS was used, and the line location.

As an example, the TUFLOW HPC tutorial model was run at a 10 m cell size (the tutorial model is usually run at 5 m) with SGS on. The peak flow from a PO line gave a result of 90 m3/s, and the equivalent flux() call gave 81 m3/s using use_unit_flow=True, and 76 m3/s if using use_unit_flow=False. That is an underprediction of 10% or more, even when using the unit flow map output. From testing, the XMDF.flux() method will not be as peaky as equivalent PO results, most likely due to some smoothing of the result surface from interpolation. This means that any error in the XMDF.flux() prediction will typically lean toward underprediction.

The same test with a 5 m cell size and with SGS turned off, resulted in XMDF.flux() predicting a much closer peak of approximately 1% difference to the PO results. The NCGrid.flux() predicted even closer with a peak less than 1% difference. Other real world tests have shown that without SGS, the XMDF.flux() is typically within 5% of the PO result given sufficient cell resolution across the flowpath.

The same test was run with TUFLOW FV using the NetCDF output format. In this case, the NCMesh.flux() method returned an estimate that was identical to the flux output from TUFLOW FV (the peak was within ~0.2%). This is due to the interpolation, or lack thereof in this instance. TUFLOW FV calculates both water level and velocity at the cell centre, and the NetCDF output writes values to the cell centre. Note, the NCMesh.flux() estimate is not guaranteed to always be identical, particularly when using spherical coordinates.

Parameters:

  • locations (LineString | list[LineString] | dict[str, LineString] | GeoDataFrame | str | PathLike) – The line(s) to extract the flux for.

  • 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 (mg/L in SI units). In these cases, the returned flux will the mass flux (g) 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.

  • direction_convention (str, optional) –

    The convention used for direction data. This should match the how the data is stored in the output file. The default out of TUFLOW for the “NC” map output is "arithmetic".

    • "arithmetic" (default) - direction is measured anticlockwise from the positive x-axis (east)

    • "nautical" - direction is measured clockwise from the positive y-axis (north)

Returns:

An array containing the extracted flux across the line.

Return type:

pd.DataFrame

Examples

Extract the flow across a line:

>>> res = ... # assume res is a Mesh or NCGrid output
>>> Q = res.flux('/path/to/line.shp')
>>> Q
      locA/flux (q)
time
0.0        0.000000
0.5        0.000000
1.0       81.115922
1.5       52.226762
2.0       17.359964
2.5        8.920063
3.0        4.825885

Extract the mass flux across a line:

>>> Q_mass = res.flux('/path/to/line', 'ad01_conc')
>>> Q_mass
         locA/flux ad01_conc (q)
time
0.0                     0.000000
0.5                     0.000000
1.0                    89.579868
1.5                   123.392674
2.0                   102.520215
2.5                   101.631599
3.0                   100.038073
Contents