doc: graphe and eqs upgrades

doc/source/_static/eqs_smash_doc.lyx

@@ -0,0 +1,273 @@
+#LyX 2.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 544
+\begin_document
+\begin_header
+\save_transient_properties true
+\origin unavailable
+\textclass article
+\begin_preamble
+\usepackage{amsmath}
+\usepackage{amsfonts}
+\end_preamble
+\use_default_options true
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman "default" "default"
+\font_sans "default" "default"
+\font_typewriter "default" "default"
+\font_math "auto" "auto"
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100 100
+\font_tt_scale 100 100
+\use_microtype false
+\use_dash_ligatures true
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry false
+\use_package amsmath 1
+\use_package amssymb 1
+\use_package cancel 1
+\use_package esint 1
+\use_package mathdots 1
+\use_package mathtools 1
+\use_package mhchem 1
+\use_package stackrel 1
+\use_package stmaryrd 1
+\use_package undertilde 1
+\cite_engine basic
+\cite_engine_type default
+\biblio_style plain
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\justification true
+\use_refstyle 1
+\use_minted 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\is_math_indent 0
+\math_numbering_side default
+\quotes_style english
+\dynamic_quotes 0
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\mathcal{M}
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\boldsymbol{\theta}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\boldsymbol{h}_{0}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\boldsymbol{D}(x,t)
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\boldsymbol{I}(x,t)
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\boldsymbol{U}(x,t)=\left[Q,\boldsymbol{h},\boldsymbol{q}\right](x,t)
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\left[S,T_{e}\right](x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\mathcal{M}_{snw}
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $m_{lt}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\left[P,E\right](x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\mathcal{M}_{rr}
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\boldsymbol{h}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\boldsymbol{q}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $q_{t}(x,t)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $\mathcal{D}_{\Omega}(x)$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\[
+\mathcal{M}_{hy}
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $Q(x,t)$
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Formula 
+\[
+\mathcal{M}=\mathcal{M}_{hy}\left(\,.\,,\mathcal{M}_{rr}\left(\,.\,,\mathcal{M}_{snw}\left(.\right)\right)\right)
+\]
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename ../../smash/doc/source/_static/forward_simple_flowchart.png
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset VSpace defskip
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename ../../smash/doc/source/_static/flowchart_forward_gridded.png
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

doc/source/index.rst

@@ -11,9 +11,9 @@ smash documentation
 `smash` is a computational software framework dedicated to **S**\patially distributed **M**\odelling and
 **AS**\similation for **H**\ydrology, enabling to tackle spatially distributed differentiable hydrological
 modeling, with learnable parameterization-regionalization. This platform enables to combine vertical and
-lateral flow operators, either physically based or hydrid  with neural networks, and perform high dimensional
-non linear optimization from multi-source data. It is designed to simulate discharge hydrographs and
-hydrological states at any spatial location within a basin and reproduce the hydrological response of
+lateral flow operators, either process-based conceptual or hydrid  with neural networks, and perform high 
+dimensional non linear optimization from multi-source data. It is designed to simulate discharge hydrographs 
+and hydrological states at any spatial location within a basin and reproduce the hydrological response of
 contrasted catchments, both for operational forecasting of floods and low flows, by taking advantage of
 spatially distributed meteorological forcings, physiographic data and hydrometric observations.
 

doc/source/math_num_documentation/forward_inverse_problem.rst

@@ -4,31 +4,43 @@
 Forward & Inverse Problems
 ==========================
 
-This section explains :
+This section explains:
 
-- The **forward hydrologic problem statement**, consisting in modeling the spatio-temporal evolution of water states-fluxes within a basin given atmospheric forcings and basin physical descriptors. 
-
-- The **inverse problem statement**, aiming to use spatio-temporal observations of hydrological state-fluxes to estimate uncertain or unknows model parameters.
+- The **hydrological modeling problem statement (forward problem)**, that consists in modeling the spatio-temporal evolution of water states-fluxes within a basin/domain given atmospheric forcings and basin physical descriptors. 
 
+- The **parameter estimation problem statement (inverse problem)**, that pertains to estimating uncertain or unknows model parameters from the available spatio-temporal observations of hydrological state-fluxes and from basin physical descriptors.
 
-Forward problem
----------------
+Forward problem statement
+-------------------------
 
-Let :math:`\Omega\subset\mathbb{R}^{2}` denote a 2D spatial domain, :math:`x\in\Omega` the spatial coordinate, and :math:`t\in\left]0,T\right]` the physical time.
+Let :math:`\Omega\subset\mathbb{R}^{2}` denote a 2D spatial domain, :math:`x\in\Omega` the spatial coordinates, and :math:`t\in\left]0,T\right]` the physical time.
 
-Hydrological model
-******************
+Hydrological model definition
+*****************************
 
 The spatially distributed hydrological model is a dynamic operator :math:`\mathcal{M}` projecting fields of atmospheric forcings :math:`\mathcal{\boldsymbol{I}}`,
-catchment physiographic descriptors :math:`\boldsymbol{\mathcal{D}}` onto surface discharge :math:`Q`, model states :math:`\boldsymbol{h}`, and internal fluxes  :math:`\boldsymbol{q}` such that:
+catchment physical descriptors :math:`\boldsymbol{\mathcal{D}}` onto surface discharge :math:`Q`, model states :math:`\boldsymbol{h}`, and internal fluxes  :math:`\boldsymbol{q}` such that:
+
+
 
 .. math::
     :name: math_num_documentation.forward_inverse_problem.forward_problem_M_1
-
+    
+    \boxed{
     \boldsymbol{U}(x,t)=(Q,\boldsymbol{h},\boldsymbol{q})(x,t)=\mathcal{M}\left(\left[\mathcal{\boldsymbol{I}},\boldsymbol{\mathcal{D}}\right](x,t);\left[\boldsymbol{\theta},\boldsymbol{h}_{0}\right](x)\right)
+    }
 
 with :math:`\boldsymbol{U}(x,t)` the modeled state-flux variables, :math:`\boldsymbol{\theta}` the parameters and :math:`\boldsymbol{h}_{0}` the initial states.
 
+
+.. figure:: ../_static/forward_simple_flowchart.png
+    :align: center
+    :width: 800
+
+    Flowchart of the forward modeling problem: input data, forward hydrological model :math:`\mathcal{M}`, simulated quantites.
+
+
+
 .. note:: The dimensions of model arrays, by denoting :math:`N=N_{x} \times N_{t}` with :math:`N_{x}` the number of  cells in :math:`\Omega` and :math:`N_t` the number of simulation time steps in :math:`\left]0,T\right]`, are as follows:
 
     - Surface discharge :math:`Q(x,t)\in\mathbb{R}^{N}` 
@@ -48,21 +60,28 @@ with :math:`\boldsymbol{U}(x,t)` the modeled state-flux variables, :math:`\bolds
 Operators composition
 *********************
 
-Note that the operator :math:`\mathcal{M}` can be a composite function containing, at least differentiable operators for vertical and lateral transfert processes within each cell :math:`x\in\Omega`, and routing operator from cells to cells following a flow direction map, plus (optionally) deep neural networks enabling learnable process parameterization and learnable conceptual parameters regionalization as described later.
+The forward hydrological model :math:`\mathcal{M}` is obtained by combining at least two operators: the hydrological operator :math:`\mathcal{M}_{rr}` to simulate runoff from atmospheric forcings and use this runoff to feed a routing operator :math:`\mathcal{M}_{hy}` for cell to cell flow routing. 
+
+A snow module :math:`\mathcal{M}_{snw}` can also be added.
+
+Neural networks ca also be included into this forward model to predict parameters and/or fluxes corrections from data. 
+
+The various model structures proposed in `smash` are differentiable and detailed in :ref:`model strucures section <math_num_documentation.forward_structure>`.
 
 
 Snow, Production and Routing Operators
 ======================================
 
-The hydrological model writes 
+The forward hydrological model is obtained by partial composition (each operator taking various other inputs data and paramters) of the flow operators writes:
 
 .. math:: 
       :name: math_num_documentation.forward_inverse_problem.forward_problem_Mhy_circ_Mrr
       
-      \mathcal{M}=\mathcal{M}_{hy}\circ\mathcal{M}_{rr}\circ\mathcal{M}_{snw}
+      \mathcal{M}=\mathcal{M}_{hy}\left(\,.\,,\mathcal{M}_{rr}\left(\,.\,,\mathcal{M}_{snw}\left(.\right)\right)\right)
       
-and is composed of the snow module :math:`\mathcal{M}_{snw}` producing a melt flux :math:`m_{lt}(x,t)` inflowing the production module :math:`\mathcal{M}_{rr}` that produces elemental discharge  :math:`q_t(x,t)` inflowing a routing module :math:`\mathcal{M}_{hy}`.
+with the snow module :math:`\mathcal{M}_{snw}` producing a melt flux :math:`m_{lt}(x,t)` inflowing the production module :math:`\mathcal{M}_{rr}` that produces elemental discharge  :math:`q_t(x,t)` inflowing a routing module :math:`\mathcal{M}_{hy}`. 
 
+Models structures are detailed in :ref:`model strucures section <math_num_documentation.forward_structure>`.
 
 .. _math_num_documentation.forward_inverse_problem.mapping:
 
@@ -85,16 +104,18 @@ Consequently, replacing in :ref:`Eq. 1 <math_num_documentation.forward_inverse_p
 
     \boldsymbol{U}(x,t)=(Q,\boldsymbol{h},\boldsymbol{q})(x,t)=\mathcal{M}\left(\left[\mathcal{\boldsymbol{I}},\mathcal{\boldsymbol{D}}\right](x,t);\phi\left(\boldsymbol{\mathcal{D}}(x,t),\boldsymbol{\rho}\right)\right)
 
-Inverse problem
----------------
+Inverse problem statement
+-------------------------
+
+**ADD general optim flowchart here**
 
 .. _math_num_documentation.forward_inverse_problem.cost_function:
 
 Cost function
 *************
 
 
-Consider the following generic cost function composed of an observation term :math:`J_{obs}` and a regularization term :math:`J_{reg}` weighted by :math:`\alpha\geq0`:
+Consider the following generic differentiable cost function composed of an observation term :math:`J_{obs}` and a regularization term :math:`J_{reg}` weighted by :math:`\alpha\geq0`:
 
 
 .. math::