DOC: upgrade math num section (#214)

* xx * doc upgrade minor corrections * doc upgrade minor corrections * doc * DOC: Update forward structure - Update hydrological module structure figure - Add dropdown for each module - Update .gitignore --------- Co-authored-by: Francois Colleoni <[email protected]>
DassHydro · Jun 28, 2024 · f47b00e · f47b00e
1 parent 7cae4e6
commit f47b00e
Show file tree

Hide file tree

Showing 14 changed files with 5,448 additions and 624 deletions.
diff --git a/.gitignore b/.gitignore
@@ -72,4 +72,5 @@ tmp*
 # Documentation files
 doc/source/api_reference/**/smash
 doc/*-dataset
-doc/*~
+doc/**/*~
+doc/**/*#
diff --git a/doc/source/_static/flowchart_forward_gridded.png b/doc/source/_static/flowchart_forward_gridded.png
diff --git a/doc/source/_static/forward_composition_flowchart.png b/doc/source/_static/forward_composition_flowchart.png
diff --git a/doc/source/_static/forward_flowchart_detail_input_params_states_fluxes.png b/doc/source/_static/forward_flowchart_detail_input_params_states_fluxes.png
diff --git a/doc/source/_static/forward_simple_flowchart.png b/doc/source/_static/forward_simple_flowchart.png
diff --git a/doc/source/_static/gr4_structure.svg b/doc/source/_static/gr4_structure.svg
diff --git a/doc/source/_static/gr5_structure.svg b/doc/source/_static/gr5_structure.svg
diff --git a/doc/source/_static/grd_structure.svg b/doc/source/_static/grd_structure.svg
diff --git a/doc/source/_static/loieau_structure.svg b/doc/source/_static/loieau_structure.svg
diff --git a/doc/source/_static/vic3l_structure.svg b/doc/source/_static/vic3l_structure.svg
diff --git a/doc/source/asset/eqs_smash_doc.lyx b/doc/source/asset/eqs_smash_doc.lyx
@@ -489,7 +489,7 @@ J\left(\boldsymbol{U}\left(\boldsymbol{\rho}\right),\boldsymbol{Y}^{*}\right)
 
 \begin_layout Standard
 \begin_inset Graphics
-	filename /home/pagarambois/Documents/Distant/smash/doc/source/_static/forward_simple_flowchart.png
+	filename ../_static/forward_simple_flowchart.png
 
 \end_inset
 
@@ -498,7 +498,16 @@ J\left(\boldsymbol{U}\left(\boldsymbol{\rho}\right),\boldsymbol{Y}^{*}\right)
 
 \begin_layout Standard
 \begin_inset Graphics
-	filename forward_composition_flowchart.png
+	filename ../_static/forward_composition_flowchart.png
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename ../_static/forward_flowchart_GMDv1.png
 
 \end_inset
 
@@ -514,7 +523,7 @@ J\left(\boldsymbol{U}\left(\boldsymbol{\rho}\right),\boldsymbol{Y}^{*}\right)
 
 \begin_layout Standard
 \begin_inset Graphics
-	filename Inversion_process_flowchart.png
+	filename ../_static/Inversion_process_flowchart.png
 
 \end_inset
 
@@ -530,7 +539,43 @@ J\left(\boldsymbol{U}\left(\boldsymbol{\rho}\right),\boldsymbol{Y}^{*}\right)
 
 \begin_layout Standard
 \begin_inset Graphics
-	filename /home/pagarambois/Documents/Distant/smash/doc/source/_static/flowchart_forward_gridded.png
+	filename ../_static/forward_flowchart_detail_input_params_states_fluxes.png
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Model structures :
+\end_layout
+
+\begin_layout Standard
+gr4-5
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename ../_static/gr_flowchart.png
+
+\end_inset
+
+
+\begin_inset Graphics
+	filename ../_static/gr_flowchart.png
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+grd
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename ../_static/grd_flowchart.png
 
 \end_inset
 

diff --git a/doc/source/asset/smash_graphes_structures.odp b/doc/source/asset/smash_graphes_structures.odp
diff --git a/doc/source/math_num_documentation/forward_inverse_problem.rst b/doc/source/math_num_documentation/forward_inverse_problem.rst
@@ -6,16 +6,16 @@ Forward & Inverse Problems
 
 This section explains:
 
-- The **hydrological modeling problem statement (forward/direct 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 **hydrological modeling problem (forward/direct problem)**, that consists in modeling the spatio-temporal evolution of water states-fluxes within a spatio-temporal 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.
+- The **parameter estimation problem (inverse problem)**, that aims to estimating uncertain or unknows model parameters from the available spatio-temporal observations of hydrological state-fluxes and from basin physical descriptors.
 
 Forward problem statement
 -------------------------
 
 The forward/direct hydrological modeling problem statement is formulated here.
 
-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. 
+The 2D spatial domain is denoted :math:`\Omega` with :math:`x` the vector of spatial coordinates, and :math:`t` is the time in the simulation window :math:`\left]0,T\right]`. 
 
 
 Hydrological model definition
@@ -32,7 +32,7 @@ catchment physical descriptors :math:`\boldsymbol{D}` onto surface discharge :ma
     \boldsymbol{U}(x,t)=(Q,\boldsymbol{h},\boldsymbol{q})(x,t)=\mathcal{M}\left(\left[\boldsymbol{I},\boldsymbol{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.
+with :math:`\boldsymbol{U}(x,t)` the modeled state-flux variables, :math:`\boldsymbol{\theta}` the parameters and :math:`\boldsymbol{h}_{0}=\boldsymbol{h}\left(x,t=0\right)` the initial states.
 
 
 .. figure:: ../_static/forward_simple_flowchart.png
@@ -41,7 +41,7 @@ with :math:`\boldsymbol{U}(x,t)` the modeled state-flux variables, :math:`\bolds
 
     Flowchart of the forward modeling problem: input data, forward hydrological model :math:`\mathcal{M}`, simulated quantites.
 
-.. dropdown:: Sizes of model variables
+.. dropdown:: Detail on model variables
     :animate: fade-in-slide-down
 
     The sizes of the variables in the forward/direct problem are detailed here. We denote by :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]`.
@@ -60,10 +60,14 @@ with :math:`\boldsymbol{U}(x,t)` the modeled state-flux variables, :math:`\bolds
 
     - Initial states :math:`\boldsymbol{h}_{0}=\boldsymbol{h}(x,t=0)`
 
-Operators Composition
-*********************
+
+.. _math_num_documentation.forward_inverse_problem.chaining:
+
+
+Operators Chaining Principle
+****************************
 
-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. 
+The **forward hydrological model** :math:`\mathcal{M}` is obtained by chaining through fluxes 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.
 
@@ -112,6 +116,8 @@ Consequently, replacing in :ref:`Eq. 1 <math_num_documentation.forward_inverse_p
     :name: math_num_documentation.forward_inverse_problem.forward_problem_M_2
 
     \boldsymbol{U}(x,t)=(Q,\boldsymbol{h},\boldsymbol{q})(x,t)=\mathcal{M}\left(\left[\boldsymbol{I},\boldsymbol{D}\right](x,t);\phi\left(\boldsymbol{D}(x,t),\boldsymbol{\rho}\right)\right)
+    
+The descriptors-to-parameters mappings are described in  :ref:`mapping section <math_num_documentation.mapping>`.
 
 Parameter Estimation problem statement
 --------------------------------------