Doc updated

Author: dalmo1991

doc/build_element.rst

@@ -1,7 +1,7 @@
 .. TODO
 .. - review the conde inserted
 
-.. note:: Last update 04/05/2021
+.. note:: Last update 21/07/2021
 
 .. .. warning:: This guide is still work in progress. New pages are being written
 ..              and existing ones modified. Once the guide will reach its final
@@ -120,11 +120,11 @@ from the Numba optimization.
 
 The last methods to implement are :code:`_fluxes_function_python` (pure Python)
 and :code:`_fluxes_function_numba` (Numba optimized), which calculate the
-reservoir fluxes.
+reservoir fluxes and their derivatives.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 90-124
+   :lines: 90-132
    :linenos:
 
 :code:`_fluxes_function_python` and :code:`_fluxes_function_numba` are both
@@ -142,11 +142,15 @@ The output is a tuple containing three elements:
   (e.g. streamflow, :code:`- k * S`);
 - lower bound for the search of the state;
 - upper bound for the search of the state;
+- tuple with the computed values of the derivatives of fluxes w.r.t. the state :code:`S`;
+  we maintain the convention of positive sign for incoming
+  fluxes (e.g. derivative of the precipitation, :code:`0`), negative sign  for outgoing fluxes
+  (e.g. derivative of the streamflow, :code:`- k`);
 
 The implementation for the Numba solver differs from the pure Python implementation in two aspects:
 
 - the usage of the Numba decorator that defines the types of input variables
-  (lines 24-25)
+  (lines 28-29)
 - the method works only for a single time step and not for the vectorized
   solution. For the vectorized solution the Python implementation (with Numpy)
   is considered sufficient, and hence a Numba implementation is not pursued.
@@ -176,22 +180,22 @@ implement only the methods needed to compute the weight array.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 2, 128, 129
+   :lines: 2, 136, 137
    :linenos:
 
 The only method requiring implementation is the private method used to
 calculate the :code:`weight` array.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 146-160
+   :lines: 154-168
    :linenos:
 
 The method :code:`_build_weight` makes use of a secondary private static method
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 162-172
+   :lines: 170-180
    :linenos:
 
 This method returns the area :math:`A_i` of the red triangle in the figure,
@@ -228,7 +232,7 @@ the new functionality.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 5, 176, 177
+   :lines: 5, 184, 185
    :linenos:
 
 First, we define two private attributes that specify the number of upstream and
@@ -237,15 +241,15 @@ constructing the model structure.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 194-195
+   :lines: 202-203
    :linenos:
 
 We then define the method that receives the inputs, and the method that calculates
 the outputs.
 
 .. literalinclude:: build_element_code.py
    :language: python
-   :lines: 197, 208-211, 227-233
+   :lines: 205, 216-219, 235-241
    :linenos:
 
 The two methods have the same structure as the ones implemented as part of the earlier

doc/build_element_code.py

@@ -106,7 +106,11 @@ def _fluxes_function_python(S, S0, ind, P, k, dt):
                     - k[ind] * S,
                 ],
                 0.0,
-                S0 + P[ind] * dt[ind]
+                S0 + P[ind] * dt[ind],
+                [
+                    0.0,
+                    - k[ind]
+                ]
             )
 
     @staticmethod
@@ -120,7 +124,11 @@ def _fluxes_function_numba(S, S0, ind, P, k, dt):
                 - k[ind] * S,
             ),
             0.0,
-            S0 + P[ind] * dt[ind]
+            S0 + P[ind] * dt[ind],
+            (
+                0.0,
+                - k[ind]
+            )
         )
 
 # Implement lag function

doc/changelog.rst

@@ -1,8 +1,39 @@
-.. note:: Last update 24/05/2021
+.. note:: Last update 29/11/2021
 
 Change log
 ==========
 
+Version 1.3.1
+-------------
+
+Minor changes
+.............
+
+- Added the classifier :code:`Topic :: Scientific/Engineering :: Hydrology`
+
+Version 1.3.0
+-------------
+
+Major changes to existing components
+....................................
+
+- :code:`ODEsElements` can now return the derivative of the fluxes together with
+  the fluxes. This enables the usage of numerical solvers that use the
+  derivatives (e.g., Newton methods).
+- Folder structure improved. The numerical approximators and the root finders
+  have been moved from the folder :code:`implementation/computation` to
+  :code:`implementation/numerical_approximators` and
+  :code:`implementation/root_finders`, respectively. Names of the files have
+  been slightly modified to be coherent with this new folder organization.
+
+New code
+........
+
+- Implemented a new numerical approximator implementing Runge Kutta 4
+- Implemented a new root finder implementing a Newton-bisection method
+- Implemented a new root finder implementing a trivial algorithm to solve
+  explicit algebraic equations.
+
 Version 1.2.1
 -------------
 

doc/contribute.rst

@@ -1,4 +1,4 @@
-.. note:: Last update 03/05/2021
+.. note:: Last update 22/07/2021
 
 .. .. warning:: This guide is still work in progress. New pages are being written
 ..              and existing ones modified. Once the guide will reach its final
@@ -42,8 +42,8 @@ GitHub and is published online in
 `Read the Docs <https://superflexpy.readthedocs.io/>`_.
 
 Examples are available on GitHub as Jupyter notebooks. These examples can be
-visualized statically or run in a sandbox environment (see :ref:`examples` for
-further details).
+visualized statically or run in a sandbox environment (Binder). Refer to :ref:`examples` for
+a list of the available examples.
 
 The scientific publication introducing SuperflexPy has been submitted to
 *Geoscientific Model Development* and is currently under review. The draft is

doc/demo_code.py

@@ -7,8 +7,8 @@
 # Import SuperflexPy
 from superflexpy.implementation.elements.hbv import PowerReservoir
 from superflexpy.implementation.elements.gr4j import UnitHydrograph1
-from superflexpy.implementation.computation.pegasus_root_finding import PegasusPython
-from superflexpy.implementation.computation.implicit_euler import ImplicitEulerPython
+from superflexpy.implementation.root_finders.pegasus import PegasusPython
+from superflexpy.implementation.numerical_approximators.implicit_euler import ImplicitEulerPython
 from superflexpy.framework.unit import Unit
 from superflexpy.framework.node import Node
 from superflexpy.framework.network import Network

doc/interfaces_code.py

@@ -1,5 +1,5 @@
-from superflexpy.implementation.computation.implicit_euler import ImplicitEulerPython
-from superflexpy.implementation.computation.pegasus_root_finding import PegasusPython
+from superflexpy.implementation.numerical_approximators.implicit_euler import ImplicitEulerPython
+from superflexpy.implementation.root_finders.pegasus import PegasusPython
 from superflexpy.implementation.elements.hbv import PowerReservoir
 from superflexpy.framework.unit import Unit
 import spotpy

doc/model_thur_hess2020.py

@@ -7,8 +7,8 @@
 from superflexpy.framework.unit import Unit
 from superflexpy.framework.node import Node
 from superflexpy.framework.network import Network
-from superflexpy.implementation.computation.pegasus_root_finding import PegasusPython
-from superflexpy.implementation.computation.implicit_euler import ImplicitEulerPython
+from superflexpy.implementation.root_finders.pegasus import PegasusPython
+from superflexpy.implementation.numerical_approximators.implicit_euler import ImplicitEulerPython
 
 solver = PegasusPython()
 approximator = ImplicitEulerPython(root_finder=solver)