pytuflow.NCMesh.flux

Contents

pytuflow.NCMesh.flux#

NCMesh.flux(locations, data_types='', time_fmt='relative', use_unit_flow=True)#

Returns the flux across a line. Tracer data type(s) can be provided to calculate the mass flux of a constituent. By default, the routine will preference the use of unit flow, otherwise depth and velocity is used.

Multiple flux calls on the same result can potentially be sped up by pre-loading the relevant results into memory. For example, loading vector unit flow into memory, or if unit flow does not exist in the result, then loading vector velocity and depth into memory (just velocity is required for NCMesh results).

Note

The flux calculation requires vector results. For HPC/Classic .xmdf results, these will be labelled vector unit flow and vector velocity (not unit flow and velocity, these are scalar results). Make sure to choose the correct result types if loading results into memory.

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 the 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 when using use_unit_flow=False. That is an underprediction of 10% or more.

The same test with a 5 m cell size, and with SGS turned off, resulted in XMDF.flux() predicting a much closer peak. The estimate peak was within 1% of the PO line. The NCGrid.flux() predicted even closer with a peak less than 1% different. Other real world tests have shown that XMDF.flux() is typically within 5% of the PO result given sufficient cell resolution across the flowpath and SGS is off. It is recommended to use the unit flow result if SGS is turned on, rather than use depth and velocity. Note, it is recommended to use unit flow whether SGS is on or off, however it is especially important to use when SGS is on.

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 almost 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 this close, particularly when using spherical coordinates.

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 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.shp', 'conc tracer1')
>>> Q_mass
      locA/flux conc tracer1 (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