# -*- coding: utf-8 -*-
"""Landlab component for overland flow using the linearized diffusion-wave approximation.

Created on Fri May 27 14:26:13 2016

@author: gtucker
"""


import numpy as np

from landlab import Component

_FOUR_THIRDS = 4.0 / 3.0
_SEVEN_THIRDS = 7.0 / 3.0
_MICRO_DEPTH = 1.0e-6  # tiny water depth to avoid blowup in time-step estimator


class LinearDiffusionOverlandFlowRouter(Component):
    r"""Calculate water flow over topography.

    Landlab component that implements a two-dimensional, linearized
    diffusion-wave model. The diffusion-wave approximation is a simplification
    of the shallow-water equations that omits the momentum terms. The flow
    velocity is calculated using the local water-surface slope as an
    approximation of the energy slope. With this linearized form, flow velocity
    is calculated using a linearized Manning equation, with the water-surface
    slope being used as the slope factor. There are two governing equations, one
    that represents conservation of water mass:

    ..math::

        \frac{\partial H}{\partial t} = (P - I) - \nabla\cdot\mathbf{q}

    where :math:`H(x,y,t)` is local water depth, :math:`t` is time, :math:`P`
    is precipitation rate, :math:`I` is infiltration rate, and :math:`\mathbf{q}`
    is specific water discharge, which equals depth times depth-averaged
    velocity. The other governing equation represents specific discharge as a
    function of gravity, pressure, and friction:

    ..math::

        \mathbf{q} = \frac{H^{4/3}}{n^2 U_c} \nabla w

    where :math:`n` is the friction factor ("Manning's n"), :math:`U_c` is a
    characteristic flow velocity, and :math:`w` is water-surface height, which
    is the sum of topographic elevation plus water depth.

    Infiltration rate should decline smoothly to zero as surface water depth
    approaches zero. To ensure this, infiltration rate is calculated as

    ..math::

        I = I_c \left( 1 - e^{-H / H_i} ) \right)

    where :math:`H_i` is a characteristic water depth. The concept here is that
    when :math:`H \le H_i`, small spatial variations in water depth will leave
    parts of the ground un-ponded and therefore not subject to any infiltration.
    Mathematically, :math:`I \approx 0.95 I_c` when :math:`H = 3H_i`.

    Examples
    --------