riverarchitect.shear

Regime-aware dimensionless bed shear stress (Shields stress).

Replaces the Keulegan-only expression of the original River Architect (LifespanDesign/cLifespanDesignAnalysis.analyse_taux):

ustar2 = Square(u / (5.75 * Log10(12.2 * h / (2 * 2.2 * dmean))))
taux = ustar2 / ((s - 1) * g * dmean)

That expression assumes the Keulegan-Einstein logarithmic resistance law everywhere, including shallow coarse-bed cells where the roughness layer occupies most of the water column. There the argument of the logarithm approaches one, the computed shear velocity blows up, and the resulting Shields stress is meaningless - shallow riffle margins are exactly where lifespan and recruitment analyses look. This module therefore:

  • uses the Rickenmann-Recking (2011) coarse-bed resistance relation at low relative submergence (h/ks <= 7),

  • uses the Keulegan-Einstein relation where the flow is deep (h/ks >= 20),

  • blends the shear coefficient Cf = (u*/U)**2 smoothly between the two limits, so there is no artificial seam in the output where the closure switches,

  • references the Shields stress to D84 (theta84 = ustar2 / (g * (s - 1) * D84)), consistent with Schwindt et al. (2019), rather than to the mean grain size,

  • masks NoData, dry cells, negative velocities and nonpositive grain sizes, and reports a per-cell regime code so users can see which closure applied where.

ks = 2 * D84 and D84 = 2.2 * dmean reproduce the roughness height of the original expression (2 * 2.2 * dmean); with those defaults the deep-water limit of this module is exactly the legacy ustar2, and theta84 is the legacy value divided by 2.2.

The blend is a transparent engineering interpolation between two published resistance equations; the blend itself is not a separately calibrated law. Pass a very large high_limit to use Rickenmann-Recking over the whole range instead.

This module is pure numpy: no arcpy, no GDAL, testable anywhere. NoData travels as numpy.nan, as everywhere in this package; invalid cells come back as NaN with regime code 0.

riverarchitect.shear.G_SI = 9.81

Gravitational acceleration in m/s^2.

riverarchitect.shear.RHO_RATIO = 2.68

Relative grain density (ratio of sediment and water density).

riverarchitect.shear.D84_FACTOR = 2.2

Default multiplier estimating D84 from a mean grain size raster.

riverarchitect.shear.KS_FACTOR = 2.0

Equivalent roughness height as a multiple of D84 (ks = KS_FACTOR * D84).

riverarchitect.shear.LOW_LIMIT = 7.0

Pure Rickenmann-Recking at or below this relative submergence h/ks.

riverarchitect.shear.HIGH_LIMIT = 20.0

Pure Keulegan-Einstein at or above this relative submergence h/ks.

riverarchitect.shear.REGIME_LABELS = {0: 'invalid', 1: 'Rickenmann-Recking', 2: 'blended', 3: 'Keulegan-Einstein'}

Meaning of the codes in ShearResult.regime.

class riverarchitect.shear.ShearResult(ustar2, theta84, h_over_ks, regime)[source]

Bases: NamedTuple

What calculate_taux() returns, cell by cell.

Variables:
Parameters:
ustar2: numpy.ndarray

Alias for field number 0

theta84: numpy.ndarray

Alias for field number 1

h_over_ks: numpy.ndarray

Alias for field number 2

regime: numpy.ndarray

Alias for field number 3

riverarchitect.shear.gravity_of(unit)[source]

Gravitational acceleration in the length unit of unit.

Parameters:

unit (str) – "us" (ft/s^2) or "si" (m/s^2).

Returns:

the value to pass as gravity to calculate_taux().

Return type:

float

riverarchitect.shear.rickenmann_recking_velocity_ratio(relative_depth)[source]

U/u* from Rickenmann and Recking (2011), for coarse shallow beds.

Parameters:

relative_depth (numpy.ndarray) – h / D84.

Returns:

U/u* = 4.416 * x**1.904 * (1 + (x / 1.283)**1.618)**-1.083.

Return type:

numpy.ndarray

riverarchitect.shear.keulegan_velocity_ratio(relative_submergence)[source]

U/u* from the Keulegan-Einstein fully rough logarithmic law.

Parameters:

relative_submergence (numpy.ndarray) – h / ks.

Returns:

U/u* = 5.75 * log10(12.2 * h/ks).

Return type:

numpy.ndarray

riverarchitect.shear.smoothstep_weight(relative_submergence, low_limit=7.0, high_limit=20.0)[source]

Zero-to-one smoothstep weight of the Keulegan closure between two h/ks limits.

Parameters:

  • relative_submergence (numpy.ndarray) – h / ks.

  • low_limit (float) – weight is 0 at or below this.

  • high_limit (float) – weight is 1 at or above this.

Returns:

t * t * (3 - 2 * t) with t clipped to [0, 1].

Return type:

numpy.ndarray

riverarchitect.shear.d84_of(grain, grain_kind='dmean', factor=2.2)[source]

D84 estimated from a grain-size raster.

River Architect condition folders carry a dmean raster; the analyses need D84. The published approximation D84 = 2.2 * D50 is applied to dmean for continuity with the original program, but a measured d84 raster is preferable wherever one exists.

Parameters:

  • grain (numpy.ndarray) – grain sizes in the condition’s length unit.

  • grain_kind (str) – "dmean", "d50" (multiplied by factor) or "d84" (used as is).

  • factor (float) – multiplier estimating D84 from dmean or D50.

Returns:

the D84 array.

Return type:

numpy.ndarray

riverarchitect.shear.calculate_taux(velocity, depth, d84, *, gravity=9.81, density_ratio=2.68, ks_factor=2.0, low_limit=7.0, high_limit=20.0)[source]

Squared shear velocity, D84 Shields stress, relative submergence and regime.

All inputs must share one unit system (SI with gravity=9.81, or U.S. customary with gravity in ft/s**2); the Shields stress is dimensionless either way. Arrays may contain NaN. Invalid cells (NaN anywhere, u < 0, h <= 0, d84 <= 0) come back as NaN with regime code 0.

Parameters:

  • velocity (numpy.ndarray) – depth-averaged flow velocity U.

  • depth (numpy.ndarray) – water depth h.

  • d84 (numpy.ndarray) – D84 grain size; see d84_of().

  • gravity (float) – gravitational acceleration in the rasters’ unit system.

  • density_ratio (float) – sediment-to-water density ratio s.

  • ks_factor (float) – equivalent roughness multiplier ks / D84.

  • low_limit (float) – pure Rickenmann-Recking at or below this h/ks.

  • high_limit (float) – pure Keulegan-Einstein at or above this h/ks.

Returns:

(ustar2, theta84, h_over_ks, regime).

Return type:

ShearResult

riverarchitect.shear.regime_summary(regime)[source]

Cell counts per resistance regime, for logging.

Parameters:

regime (numpy.ndarray) – the code array of a ShearResult.

Returns:

{label: count} in the order of REGIME_LABELS.

Return type:

dict