Update of the documentation (#20)

* Changed the description of lambda parameter
* Update of the documentation
* Update to sphinxcontrib-bibtex > 2.0.0
* Small changes in the description of the thermodynamic equation

documentation/source/conf.py

@@ -115,6 +115,10 @@
 
 autosectionlabel_prefix_document = True
 
+# bibtex config
+
+bibtex_bibfiles = ['files/model/ref.bib']
+
 # ----- conversion script
 
 

documentation/source/files/model/maooam_model.rst

@@ -71,7 +71,7 @@ It results in these evolution equations for the temperature anomalies:
 
 .. math::
 
-    \gamma_{\rm a} \Big( \frac{\partial \delta T_{\rm a}}{\partial t} + J(\psi_{\rm a}, \delta T_{\rm a} )- \sigma \omega \frac{\delta p}{R}\Big) &= -\lambda (\delta T_{\rm a}- \delta T_{\rm o}) +4 \sigma_B T_{{\rm o},0}^3 \delta T_{\rm o} - 8 \epsilon_{\rm a} \sigma_B T_{{\rm a},0}^3 \delta T_{\rm a} + \delta R_{\rm a} \nonumber \\
+    \gamma_{\rm a} \Big( \frac{\partial \delta T_{\rm a}}{\partial t} + J(\psi_{\rm a}, \delta T_{\rm a} )- \sigma \omega \frac{p}{R}\Big) &= -\lambda (\delta T_{\rm a}- \delta T_{\rm o}) +4 \sigma_B T_{{\rm o},0}^3 \delta T_{\rm o} - 8 \epsilon_{\rm a} \sigma_B T_{{\rm a},0}^3 \delta T_{\rm a} + \delta R_{\rm a} \nonumber \\
     \gamma_{\rm o} \Big( \frac{\partial \delta T_{\rm o}}{\partial t} + J(\psi_{\rm o}, \delta T_{\rm o})\Big) &= -\lambda (\delta T_{\rm o}- \delta T_{\rm a}) -4 \sigma_B T_{{\rm o},0}^3 \delta T_{\rm o} + 4 \epsilon_{\rm a} \sigma_B T_{{\rm a},0}^3 \delta T_{\rm a} + \delta R_{\rm o}. \nonumber
 
 The hydrostatic relation in pressure coordinates is :math:`(\partial \Phi/\partial p)

documentation/source/files/model/oro_model.rst

@@ -46,19 +46,16 @@ On the other hand, the thermodynamic equation governing the mean `potential temp
 
 .. math::
 
-    2 \, \frac{\partial}{\partial t} T_{\rm a} + J(\psi_{\rm a}, 2 T_{\rm a}) = - \frac{\sigma}{H_{\rm a}} \,\omega + 2 h_d \, (T^\ast - T_{\rm a})
+    \frac{\partial}{\partial t} T_{\rm a} + J(\psi_{\rm a}, T_{\rm a}) = \frac{\sigma \, \Delta p}{R} \,\omega + h_d \, (T^\ast - T_{\rm a})
 
 where :math:`h_d` (:attr:`~.params.AtmosphericTemperatureParams.hd`) is the `Newtonian cooling`_ coefficient indicating the tendency to return to the equilibrium temperature profile :math:`T^\ast`.
 :math:`\sigma` (:attr:`~.params.AtmosphericParams.sigma`) is the static stability of the atmosphere, taken to be constant.
-The thermal wind relation
 
-.. math::
-
-    \nabla^2 T_{\rm a} = A \, \nabla^2 \theta_{\rm a}
-
-where :math:`A` is a constant, relates the baroclinic streamfunction and the temperature fields.
-Upon `nondimensionalization`_, both fields are identified with each other: :math:`\theta_{\rm a} \equiv T_{\rm a}` and
-:math:`\theta^\star \equiv T^\star`, and the equations above fully describe the system.
+The hydrostatic relation in pressure coordinates is :math:`(\partial \Phi/\partial p)
+= -1/\rho_\text{a}` with the geopotential height :math:`\Phi = f_0\;\psi_\text{a}` and :math:`\rho_\text{a}` the dry air density. The ideal gas relation :math:`p=\rho_\text{a} R T_\text{a}`
+and the vertical discretization of the hydrostatic relation at 500 hPa allows to write the spatially dependent atmospheric temperature anomaly :math:`\delta T_\text{a} = 2f_0\;\theta_\text{a} /R` where :math:`R` (:attr:`~.QgParams.rr`) is
+the ideal gas constant. Therefore, upon `nondimensionalization`_, both fields are identified with each other: :math:`2 \theta_{\rm a} \equiv T_{\rm a}` and
+:math:`2 \theta^\star \equiv T^\star`, and the equations above fully describe the system.
 
 The mean streamfunction :math:`\psi_{\rm a}` and temperature :math:`\theta_{\rm a}` can be considered to be the value of these fields at the 500 hPa level.
 

environment.yml

@@ -1,4 +1,4 @@
-name: qgs 
+name: qgs
 channels:
   - conda-forge
   - numba
@@ -13,13 +13,13 @@ dependencies:
   - scipy
   - sympy
   - sphinx
-  - sphinx_rtd_theme
+  - sphinx_rtd_theme>0.5.1
   - pytest
   - sparse
   - ffmpeg
   - pebble
   - pip
   - pip:
-      - sphinxcontrib-bibtex<2.0.0
+      - sphinxcontrib-bibtex
       - diffeqpy
 

qgs/diagnostics/base.py

@@ -509,7 +509,7 @@ def animate(self, output='animate',  style="image", ax=None, figsize=(16, 9),
         output: str, optional
             Define the kind of animation being created. Can be:
 
-            * `animate`: Create and show a :class:`ipywidgets.widgets.interactive` widget. Works only in Jupyter notebooks.
+            * `animate`: Create and show a :class:`ipywidgets.widgets.interaction.interactive` widget. Works only in Jupyter notebooks.
             * `show`: Create and show an animation with the :mod:`matplotlib.animation` module. Works only in IPython or Python.
 
         style: str, optional
@@ -545,7 +545,7 @@ def animate(self, output='animate',  style="image", ax=None, figsize=(16, 9),
 
         Returns
         -------
-        ~matplotlib.animation.FuncAnimation or ~IPython.core.display.DisplayHandle or callable
+        ~matplotlib.animation.FuncAnimation or ~IPython.display.DisplayHandle or callable
             The animation object or the callable to update the widget, depending on the value of the `output` and `show` parameters.
         """
 
@@ -859,7 +859,7 @@ def animate(self, output='animate', ax=None, figsize=(16, 9), show_time=True, st
         output: str, optional
             Define the kind of animation being created. Can be:
 
-            * `animate`: Create and show a :class:`ipywidgets.widgets.interactive` widget. Works only in Jupyter notebooks.
+            * `animate`: Create and show a :class:`ipywidgets.widgets.interaction.interactive` widget. Works only in Jupyter notebooks.
             * `show`: Create and show an animation with the :mod:`matplotlib.animation` module. Works only in IPython or Python.
 
         ax: ~matplotlib.axes.Axes, optional
@@ -881,7 +881,7 @@ def animate(self, output='animate', ax=None, figsize=(16, 9), show_time=True, st
 
         Returns
         -------
-        ~matplotlib.animation.FuncAnimation or ~IPython.core.display.DisplayHandle or callable
+        ~matplotlib.animation.FuncAnimation or ~IPython.display.DisplayHandle or callable
             The animation object or the callable to update the widget, depending on the value of the `output` and `show` parameters.
         """
 

qgs/diagnostics/multi.py

@@ -216,7 +216,7 @@ def animate(self, output='animate', figure=None, figsize=(16, 9), stride=1, anim
         output: str, optional
             Define the kind of animation being created. Can be:
 
-            * `animate`: Create and show a :class:`ipywidgets.widgets.interactive` widget. Works only in Jupyter notebooks.
+            * `animate`: Create and show a :class:`ipywidgets.widgets.interaction.interactive` widget. Works only in Jupyter notebooks.
             * `show`: Create and show an animation with the :mod:`matplotlib.animation` module. Works only in IPython or Python.
 
         figure: ~matplotlib.figure.Figure, optional
@@ -232,7 +232,7 @@ def animate(self, output='animate', figure=None, figsize=(16, 9), stride=1, anim
 
         Returns
         -------
-        ~matplotlib.animation.FuncAnimation or ~IPython.core.display.DisplayHandle
+        ~matplotlib.animation.FuncAnimation or ~IPython.display.DisplayHandle
             The animation object.
         """
 
@@ -738,7 +738,7 @@ def animate(self, output='animate',  style="image", ax=None, figsize=(16, 9),
         output: str, optional
             Define the kind of animation being created. Can be:
 
-            * `animate`: Create and show a :class:`ipywidgets.widgets.interactive` widget. Works only in Jupyter notebooks.
+            * `animate`: Create and show a :class:`ipywidgets.widgets.interaction.interactive` widget. Works only in Jupyter notebooks.
             * `show`: Create and show an animation with the :mod:`matplotlib.animation` module. Works only in IPython or Python.
 
         style: list(str), optional
@@ -774,7 +774,7 @@ def animate(self, output='animate',  style="image", ax=None, figsize=(16, 9),
 
         Returns
         -------
-        ~matplotlib.animation.FuncAnimation or ~IPython.core.display.DisplayHandle or callable
+        ~matplotlib.animation.FuncAnimation or ~IPython.display.DisplayHandle or callable
             The animation object or the callable to update the widget, depending on the value of the `output` and `show` parameters.
         """
 

qgs/diagnostics/variables.py

@@ -311,7 +311,7 @@ def animate(self, variables='all', output='animate', style="2Dscatter", backgrou
         output: str, optional
             Define the kind of animation being created. Can be:
 
-            * `animate`: Create and show a :class:`ipywidgets.widgets.interactive` widget. Works only in Jupyter notebooks.
+            * `animate`: Create and show a :class:`ipywidgets.widgets.interaction.interactive` widget. Works only in Jupyter notebooks.
             * `show`: Create and show an animation with the :mod:`matplotlib.animation` module. Works only in IPython or Python.
 
         style: str, optional
@@ -345,7 +345,7 @@ def animate(self, variables='all', output='animate', style="2Dscatter", backgrou
 
         Returns
         -------
-        ~matplotlib.animation.FuncAnimation or ~IPython.core.display.DisplayHandle or callable
+        ~matplotlib.animation.FuncAnimation or ~IPython.display.DisplayHandle or callable
             The animation object or the callable to update the widget, depending on the value of the `output` and `show` parameters.
         """
 

qgs/integrators/integrator.py

@@ -567,7 +567,7 @@ class RungeKuttaTglsIntegrator(object):
     n_traj: int
         The number of trajectories (initial conditions) of the non-linear ODEs computed at the last integration
         performed by the integrator.
-    n_tgtraj: int
+    n_tg_traj: int
         The number of trajectories (initial conditions) the linear ODEs computed at the last integration
         performed by the integrator.
     n_records: int
@@ -607,7 +607,7 @@ def __init__(self, num_threads=None, b=None, c=None, a=None, number_of_dimension
         self._recorded_traj = None
         self._recorded_fmatrix = None
         self.n_traj = 0
-        self.n_tgtraj = 0
+        self.n_tg_traj = 0
         self.n_dim = number_of_dimensions
         self.n_records = 0
         self._write_steps = 0
@@ -927,6 +927,7 @@ def integrate(self, t0, t, dt, ic=None, tg_ic=None, forward=True, adjoint=False,
 
         self.n_traj = self.ic.shape[0]
         self.n_dim = self.ic.shape[1]
+        self.n_tg_traj = self.tg_ic.shape[1]
         self._time = np.concatenate((np.arange(t0, t, dt), np.full((1,), t)))
         self._write_steps = write_steps
 

qgs/params/params.py

@@ -378,7 +378,7 @@ class AtmosphericTemperatureParams(Params):
         Ratio of surface to atmosphere temperature
         Heat exchange scheme is disabled if `None`.
     hlambda: None or Parameter
-        Sensible + turbulent heat exchange between ocean and atmosphere [:math:`W m^{-2} K^{-1}`].
+        Sensible + turbulent heat exchange between ocean/ground and atmosphere [:math:`W m^{-2} K^{-1}`].
         Heat exchange scheme is disabled if `None`.
     """
     _name = "Atmospheric Temperature"
@@ -1369,7 +1369,7 @@ def oceanic_basis(self, basis):
                                                     description="ratio of surface to atmosphere temperature")
             self.atemperature_params.hlambda = Parameter(20.00, units='[W][m^-2][K^-1]', scale_object=self.scale_params,
                                                          return_dimensional=True,
-                                                         description="sensible+turbulent heat exchange between ocean and atmosphere")
+                                                         description="sensible+turbulent heat exchange between ocean/ground and atmosphere")
 
         if self.gotemperature_params is not None:
             if self.dynamic_T:
@@ -1426,7 +1426,7 @@ def ground_basis(self, basis):
                                                     description="ratio of surface to atmosphere temperature")
             self.atemperature_params.hlambda = Parameter(20.00, units='[W][m^-2][K^-1]', scale_object=self.scale_params,
                                                          return_dimensional=True,
-                                                         description="sensible+turbulent heat exchange between ocean and atmosphere")
+                                                         description="sensible+turbulent heat exchange between ocean/ground and atmosphere")
 
         if self.gotemperature_params is not None:
             # if orography is disabled, enable it!
@@ -1797,7 +1797,7 @@ def oblocks(self, value):
                                                     description="ratio of surface to atmosphere temperature")
             self.atemperature_params.hlambda = Parameter(20.00, units='[W][m^-2][K^-1]', scale_object=self.scale_params,
                                                          return_dimensional=True,
-                                                         description="sensible+turbulent heat exchange between ocean and atmosphere")
+                                                         description="sensible+turbulent heat exchange between ocean/ground and atmosphere")
 
         if self.gotemperature_params is not None:
             self._number_of_ground_modes = 0
@@ -1845,7 +1845,7 @@ def gblocks(self, value):
             self.atemperature_params.hlambda = Parameter(20.00, units='[W][m^-2][K^-1]',
                                                          scale_object=self.scale_params,
                                                          return_dimensional=True,
-                                                         description="sensible+turbulent heat exchange between ocean and atmosphere")
+                                                         description="sensible+turbulent heat exchange between ocean/ground and atmosphere")
 
         if self.gotemperature_params is not None:
             gmod = 0

qgs/tensors/qgtensor.py

@@ -703,7 +703,7 @@ def jacobian_from_tensor(tensor):
 
         Parameters
         ----------
-        tensor: ~sparse.C00
+        tensor: ~sparse.COO
             The qgs tensor.
 
         Returns

qgs/toolbox/lyapunov.py

@@ -36,6 +36,8 @@
 import multiprocessing
 
 
+# TODO: change the usage of np.squeeze in the return of the estimators. Use specific shape descriptors instead.
+
 class LyapunovsEstimator(object):
     """Class to compute the Forward and Backward `Lyapunov vectors`_ and `exponents`_ along a trajectory of a dynamical system