priority_flow.slope_calc_upwind
===============================

.. py:module:: priority_flow.slope_calc_upwind

.. autoapi-nested-parse::

   Calculate slopes from a DEM using upwinding.

   Translated line-by-line from PriorityFlow R package Slope_Calc_Upwind.R.
   This function calculates slopes using standard or upwinding options and
   applies a range of smoothing options, consistent with ParFlow OverlandFlow BC.



Functions
---------

.. autoapisummary::

   priority_flow.slope_calc_upwind.slope_calc_upwind


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

.. py:function:: slope_calc_upwind(dem: numpy.ndarray, direction: numpy.ndarray, dx: float, dy: float, mask: numpy.ndarray | None = None, borders: numpy.ndarray | None = None, borderdir: int = 1, d4: tuple[int, int, int, int] = (1, 2, 3, 4), minslope: float = 1e-05, maxslope: float = -1, secondary_th: float = -1, river_method: int = 0, river_secondary_th: float = 0, rivermask: numpy.ndarray | None = None, subbasins: numpy.ndarray | None = None, printflag: bool = False, upflag: bool = True) -> dict[str, numpy.ndarray]

   Calculate slopes from a DEM.

   This function will calculate slopes using standard or upwinding
   options and apply a range of smoothing options.

   :param dem: Digital elevation model (nx x ny) in HydroFrame layout.
   :type dem: np.ndarray
   :param direction: Flow direction (1=down, 2=left, 3=up, 4=right). May be modified in place for borders.
   :type direction: np.ndarray
   :param dx: Lateral grid cell resolution.
   :type dx: float
   :param dy: Lateral grid cell resolution.
   :type dy: float
   :param mask: Domain mask (1=active, 0=inactive). If None, full rectangular domain is used.
   :type mask: np.ndarray or None
   :param borders: Matrix with 1 for border cells default out, 2 default in, 0 for non-border. Built from mask if None.
   :type borders: np.ndarray or None
   :param borderdir: Default for border cells: 1=point out, 2=point in.
   :type borderdir: int
   :param d4: Direction codes (down, left, up, right). Default (1, 2, 3, 4).
   :type d4: tuple
   :param minslope: Minimum absolute slope for flat cells. Use -1 to disable minimum enforcement.
   :type minslope: float
   :param maxslope: Maximum absolute slope. Use -1 to disable.
   :type maxslope: float
   :param secondary_th: Max ratio |secondary|/|primary|. Use -1 to disable.
   :type secondary_th: float
   :param river_method: 0=none, 1=scale secondary along river, 2=watershed mean slope, 3=stream mean slope.
   :type river_method: int
   :param river_secondary_th: Secondary ratio for river cells when river_method 1-3.
   :type river_secondary_th: float
   :param rivermask: River mask (1=river). Required for river_method 1, 2, 3.
   :type rivermask: np.ndarray or None
   :param subbasins: Subbasin ids. Required for river_method 2, 3.
   :type subbasins: np.ndarray or None
   :param printflag: Print progress.
   :type printflag: bool
   :param upflag: If True, downwind slopes for OverlandFlow; if False, standard [i+1]-[i] (OverlandKin).
   :type upflag: bool

   .. rubric:: Notes

   **River methods**:

   - ``0``: default value, no special treatment for river cells.
   - ``1``: scale secondary slopes along the river (requires a river
     mask and a river-specific secondary threshold).
   - ``2``: apply watershed mean slope to each river reach (requires
     river mask and subbasins).
   - ``3``: apply the stream mean slope to each reach (requires river
     mask and subbasins).

   NOTE: The river mask can differ from the rivers used to create the
   subbasins (for example, using a higher threshold to define
   subbasins and a lower threshold to define river cells).

   :returns: "slopex", "slopey", "direction" (nx x ny arrays).
   :rtype: dict