wolfhece.pyshields
==================

.. py:module:: wolfhece.pyshields

.. autoapi-nested-parse::

   Author: HECE - University of Liege, Pierre Archambeau
   Date: 2024

   Copyright (c) 2024 University of Liege. All rights reserved.

   This script and its content are protected by copyright law. Unauthorized
   copying or distribution of this file, via any medium, is strictly prohibited.







Module Contents
---------------

.. py:data:: RHO_PUREWATER
   :value: 1000.0


.. py:data:: RHO_SEAWATER
   :value: 1025.0


.. py:data:: RHO_SEDIMENT
   :value: 2650.0


.. py:data:: KIN_VISCOSITY
   :value: 1e-06


.. py:data:: GRAVITY
   :value: 9.81


.. py:data:: BED_LOAD
   :value: 1


.. py:data:: SUSPENDED_LOAD_50
   :value: 2


.. py:data:: SUSPENDED_LOAD_100
   :value: 3


.. py:data:: WASH_LOAD
   :value: 4


   Pierre Archambeau
   @date : 2022

   Chezy : u = C (RJ)**.5
   Strickler : C = K R**(1/6)

    --> u = K R**(2/3) J**.5

    en 2D : R = h

    --> u = K h**(2/3) J**.5

    J = u**2 / K**2 / h**(4/3)

    mais aussi

    J = f/D * u**2 /2 /g
        avec D = 4h

    --> J = f/(4h) *u**2 /2 /g
    --> tau = J * rho * h * g

    Shields :
      Theta = tau / ((rhom-rho) * g * d)
      Theta = tau / rho / ((s-1) * g * d)  avec s = rhom/rho

      Theta = J * h / ((s-1) * d)

    Strickler :
      J = u**2 / K**2 / h**(4/3)
      tau = J * rho * h * g

      tau = (q/K)**2 / h**(7/3) * rho  * g

   Autres :
      J = f/(4h) *u**2 /2 /g
      tau = J * rho * h * g

      tau = f/8 * (q/h)**2 * rho

    References:
         Telemac-Mascaret, https://gitlab.pam-retd.fr/otm/telemac-mascaret/-/blob/main/sources/gaia/shields.f

         Yalin, Ferraira da Silva (2001), Fluvial Processes, IAHR Monograph

         Fredsoe,  Jorgen and Deigaard Rolf. (1992). Mechanics of Coastal Sediment.
               Sediment Transport. Advanced Series on Ocean Engineering - Vol. 3.
               World Scientific. Singapure.

         Madsen, Ole S., Wood, William. (2002).  Sediment Transport Outside the
               Surf Zone. In: Vincent, L., and Demirbilek, Z. (editors),
               Coastal Engineering Manual, Part III, Combined wave and current
               bottom boundary layer flow, Chapter III-6,
               Engineer Manual 1110-2-1100, U.S. Army Corps of Engineers,
               Washington, DC.

         Nielsen, Peter. (1992). Coastal Bottom Boundary Layers and
               Sediment Transport. Advanced Series on Ocean Engineering - Vol. 4.
               World Scientific. Singapure.

   :type: @author

.. py:function:: get_sadim(d: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   s_adim = d**(3/2) * ((s-1) * g)**.5 / (4 * nu)

   [-] = [m^1.5 ] * [m^.5 s^-1] / [m^2 s^-1]


.. py:function:: get_dstar(d: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   compute d*


.. py:function:: sadim2dstar(sadim: float) -> float

.. py:function:: dstar2sadim(dstar: float) -> float

.. py:function:: get_d_from_sadim(sadim: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   s_adim = d**(3/2) * ((s-1) * g)**.5 / (4 * nu)

   [-] = [m^1.5 ] * [m^.5 s^-1] / [m^2 s^-1]


.. py:function:: get_d_from_dstar(dstar: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   d_star = d * (g * (s-1) / nu**2)**(1/3)

   [-] = [m] * ([m s^-2] / [m^4 s^-2])^(1/3)


.. py:function:: get_psi_cr(s_adim: float) -> float

   https://nl.mathworks.com/matlabcentral/fileexchange/97447-modified-shields-diagram-and-criterion?tab=reviews


.. py:function:: get_psi_cr2(dstar: float) -> float

   http://docs.opentelemac.org/doxydocs/v8p2r0/html/shields_8f_source.html


.. py:function:: get_psi_cr3(dstar: float) -> float

   Fluvial Processes, IAHR 2001, pp 6-9


.. py:function:: get_shields_cr(d, rhom=RHO_SEDIMENT, rho=RHO_PUREWATER, which=2)

   :param d: grain diameter [m]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]
   :param which: which formula to use (default 2) -- see funcs = [(get_sadim, get_psi_cr), (get_dstar, get_psi_cr2), (get_dstar, get_psi_cr3)]

   :return: [critical_shear_velocity, tau_cr, xadim_val, psicr]

    Example:
     [critical_shear_velocity, tau_cr, xadim_val, psicr] = get_shields_cr(0.2E-3, 2650)


.. py:function:: _poly(x: float) -> float

.. py:function:: _dpolydx(x: float) -> float

   derivative of _poly


.. py:function:: get_sadim_min() -> float

.. py:function:: get_tau_from_psiadim(psiadim, d: float, rhom: float = 2650, rho: float = RHO_PUREWATER) -> float

.. py:function:: get_d_min(rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

.. py:function:: _d_cr(x: float, tau_obj: float, rhom: float, rho: float, xadim: float, yadim: float) -> float

   Equation to solve to get d_cr


.. py:function:: _get_d_cr(tau_cr, rhom=RHO_SEDIMENT, rho=RHO_PUREWATER, which=2) -> float

   Critical diameter d_cr for Shields criterion

   :param tau_cr: critical shear stress [Pa]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]
   :param which: which formula to use (default 2) -- see funcs = [(get_sadim, get_psi_cr), (get_dstar, get_psi_cr2), (get_dstar, get_psi_cr3)]


.. py:function:: get_d_cr(q: float, h: float, K: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER, method='brenth', which=2, friction_law: Literal['Strickler', 'Colebrook'] = 'Strickler') -> list[float]

   Diamètre critique d'emportement par :
         - Shields
         - Izbach

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]
   :param method: method to solve the equation (default 'brenth')
   :param which: which formula to use (default 2)  -- see funcs = [(get_sadim,get_psi_cr),(get_dstar,get_psi_cr2),(get_dstar,get_psi_cr3)]


.. py:function:: get_settling_vel(d: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   Vitesse de chute

   :param d: grain diameter [m]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]


.. py:function:: get_Rouse(d: float, q: float, h: float, K: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER) -> float

   Vitesse de chute

   :param d: grain diameter [m]
   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]


.. py:function:: _get_Rouse(d: float, q: float, h: float, K: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER, frac: float = 50) -> float

   Settling velocity function -- used in root_scalar

   :param d: grain diameter [m]
   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]


.. py:function:: get_transport_mode(d: float, q: float, h: float, K: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER)

   Transport mode

   return in [BED_LOAD, SUSPENDED_LOAD_50, SUSPENDED_LOAD_100, WASH_LOAD]

   :param d: grain diameter [m]
   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]



.. py:function:: get_d_cr_susp(q: float, h: float, K: float, rhom: float = RHO_SEDIMENT, rho: float = RHO_PUREWATER, method='brenth', which=50) -> float

   Diamètre critique d'emportement par suspension à 50% --> cf Rouse 1.2

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]



.. py:function:: shieldsdia_sadim(s_psicr=None, dstar_psicr=None, figax=None) -> tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

   Plot Shields diagram with sadim as x-axis

   :param s_psicr: tuple (S, psicr) for a specific point to plot on the diagram
   :param dstar_psicr: tuple (dstar, psicr) for a specific point to plot on the diagram
   :param figax: tuple (fig, ax) to plot on a specific figure and axes


.. py:function:: shieldsdia_dstar(s_psicr=None, dstar_psicr=None, figax=None) -> tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

   Plot Shields diagram with dstar as x-axis

   :param s_psicr: tuple (S, psicr) for a specific point to plot on the diagram
   :param dstar_psicr: tuple (dstar, psicr) for a specific point to plot on the diagram
   :param figax: tuple (fig, ax) to plot on a specific figure and axes


.. py:function:: shieldsdia_dim(figax=None) -> tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

   Plot Shields diagram with dimensional values


.. py:function:: get_friction_slope_2D_Manning(q: float, h: float, n: float) -> float

   Compute friction slope j for 2D flow with Manning/Strickler friction law

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param n: Manning friction coefficient [m^{-1/3}.s]


.. py:function:: get_friction_slope_2D_Strickler(q: float, h: float, K: float) -> float

   Compute friction slope j for 2D flow with Strickler friction law

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m^{1/3}/s]


.. py:function:: get_friction_slope_2D_Colebrook(q: float, h: float, K: float) -> float

   Compute friction slope j for 2D flow with Colebrook-White friction law

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: height of roughness [m] - will be used to compute k/D or k/(4h) in 2D flow


.. py:function:: get_shear_velocity_2D_Manning(q: float, h: float, n: float) -> float

   Compute shear velocity u_* for 2D flow with Manning/Strickler friction law

   :param j: friction slope [-]
   :param h: water depth [m]
   :param q: discharge [m3/s]
   :param n: Manning friction coefficient [m-1/3.s]


.. py:function:: get_shear_velocity_2D_Colebrook(q: float, h: float, K: float) -> float

   Compute shear velocity u_* for 2D flow with Colebrook-White friction law

   :param j: friction slope [-]
   :param h: water depth [m]
   :param q: discharge [m3/s]
   :param K: Colebrook-White friction coefficient [m]


.. py:function:: get_Shields_2D_Manning(s: float, d: float, q: float, h: float, n: float) -> float

   Compute Shields dimensionless parameter for 2D flow with Manning/Strickler friction law

   :param s: sediment density / water density [-]
   :param d: sediment diameter [m]
   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param n: Manning friction coefficient [m-1/3.s]

   See also get_Shields_2D_Strickler


.. py:function:: get_Shields_2D_Strickler(s: float, d: float, q: float, h: float, K: float) -> float

   Compute Shields dimensionless parameter for 2D flow with Manning/Strickler friction law

   :param s: sediment density / water density [-]
   :param d: sediment diameter [m]
   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param K: Strickler friction coefficient [m1/3/s]

   See also get_Shields_2D_Manning


.. py:function:: izbach_d_cr(q: float, h: float, rhom: float = 2650, rho: float = RHO_PUREWATER, method='ridder') -> float

   https://en.wikipedia.org/wiki/Izbash_formula

   u_c/ ((s-1) * g * d)**.5 = 1.7

   avec  :
         (s-1) = (rho_m - rho) / rho
         u_c = 85% u_moyen)

   --> d = u_c**2 / ((s-1) * g) / 1.7**2

   --> d = (0.85 * q/h)**2 / ((s-1) * g) / 1.7**2

   :param q: discharge [m3/s]
   :param h: water depth [m]
   :param rhom: sediment density [kg/m3]
   :param rho: water density [kg/m3]
   :param method: method to solve the equation (default 'ridder')