First implementation of the diagnostic module:

* Base classes to define diagnostics
* First batch of diagnostics useful for the model
* Multiple diagnostics classes to show them simultaneously
* Documentation (API + user guide + example)
* Example notebooks

Other important changes:

* Numerical quadrature of symbolic inner products (it is now the default
way to compute them) + timeout in the case of symbolic integration
before falling back to quadrature

And finally various minor changes and bugfixes.

README.md

@@ -15,10 +15,12 @@ a 2-layer [quasi-geostrophic](https://en.wikipedia.org/wiki/Quasi-geostrophic_eq
 atmosphere on a [beta-plane](https://en.wikipedia.org/wiki/Beta_plane), coupled to a simple land or
 [shallow-water](https://en.wikipedia.org/wiki/Shallow_water_equations) ocean component. 
 
+![](./misc/figs/readme.gif)
+
 About
 -----
 
-(c) 2020 qgs Developers and Contributors
+(c) 2020-2021 qgs Developers and Contributors
 
 Part of the code originates from the Python [MAOOAM](https://github.com/Climdyn/MAOOAM) implementation by Maxime Tondeur and Jonathan Demaeyer.
 
@@ -130,13 +132,12 @@ Forthcoming developments
 * Technical mid-term developments
     + Dimensionally robust Parameter class operation
     + Windows OS support
-    + Numerical basis of function
-    + Visualisation tools, e.g. based on the [movie-script](https://github.com/jodemaey/movie-script) package
 * Long-term development track
     + Active advection
     + True quasi-geostrophic ocean when using ocean model version
     + Salinity in the ocean 
     + Symbolic PDE equation specification
+    + Numerical basis of function
 
 Contributing to qgs
 -------------------

documentation/source/conf.py

@@ -18,11 +18,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'qgs'
-copyright = '2021, qgs Developers and Contributors'
+copyright = '2020-2021, qgs Developers and Contributors'
 author = 'Jonathan Demaeyer and Lesley De Cruz'
 
 # The full version, including alpha/beta/rc tags
-release = 'v0.2.3'  # temporary
+release = 'v0.2.4'  # temporary
 version = release
 
 
@@ -54,6 +54,15 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['files/notebooks/*', '**.ipynb_checkpoints']
 
+# -- Debugging ---------------------------------------------------------------
+
+# nitpicky = True
+#
+# nitpick_ignore = [('py:class', 'optional'),
+#                   ('py:class', 'iterable'),
+#                   ('py:class', '2-tuple'),
+#                   ('py:class', 'Sympy expression'),
+#                   ('py:class', 'callable')]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -74,7 +83,9 @@
                        'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
                        'matplotlib': ('https://matplotlib.org', None),
                        'sparse': ('https://sparse.pydata.org/en/stable/', None),
-                       'sympy': ('https://docs.sympy.org/latest/', None)}
+                       'sympy': ('https://docs.sympy.org/latest/', None),
+                       'ipython': ('https://ipython.readthedocs.io/en/stable/', None),
+                       'ipywidgets': ('https://ipywidgets.readthedocs.io/en/latest/', None)}
 
 # Napoleon settings
 napoleon_google_docstring = True

documentation/source/files/diagnostic.rst

@@ -0,0 +1,79 @@
+In addition to the plotting of the model’s variables (the coefficients
+of the spectral expansion of the fields), it is also possible to plot
+several diagnostics associated to these variables, whether they are
+fields or scalars. These diagnostics are arranged in classes (:class:`.Diagnostic` being the parent abstract base class) and must be
+instantiated to obtain objects that convert the model output to the
+corresponding diagnostics.
+
+For instance, we can define a :class:`.MiddleAtmosphericStreamfunctionDiagnostic` diagnostic that returns the
+500hPa streamfunction field:
+
+.. code:: ipython3
+
+    psi_a = MiddleAtmosphericStreamfunctionDiagnostic(model_parameters)
+
+and *feed* it with a model outputs ``time`` and ``trajectory`` previously computed
+(like in the previous section):
+
+.. code:: ipython3
+
+    psi_a.set_data(time, trajectory)
+
+It is then possible to plot the corresponding fields with the :meth:`~.FieldDiagnostic.plot` method:
+
+.. code:: ipython3
+
+    psi_a.plot(50)
+
+
+.. image:: user_guide/figures/maooam_run-Copy1_63_1.png
+
+
+or to easily create animation widget and movie of the diagnostic with
+respectively the :meth:`~.FieldDiagnostic.animate` and :meth:`~.FieldDiagnostic.movie` methods:
+
+.. code:: ipython3
+
+    psi_a.movie(figsize=(13,8), anim_kwargs={'interval': 100, 'frames':100})
+
+.. include:: user_guide/vid_diag.rst
+
+All the diagnostics classes should in principle have these 3 methods
+(``plot``, ``animate`` and ``movie``). Note that the movies can also be
+saved in mpeg 4 format.
+
+One can also define multiple diagnostics and couple them toghether with
+a :class:`.MultiDiagnostic` object. For instance, here we couple the previous ``psi_a``
+diagnostic with a dynamical scatter plot:
+
+.. code:: ipython3
+
+    variable_nondim = VariablesDiagnostic([2, 1, 0], model_parameters, False)
+    m = MultiDiagnostic(1,2)
+    m.add_diagnostic(variable_nondim, diagnostic_kwargs={'show_time':True, 'style':'2Dscatter'}, plot_kwargs={'ms': 0.2})
+    m.add_diagnostic(psi_a, diagnostic_kwargs={'show_time':False})
+    m.set_data(time, trajectory)
+
+As with the other diagnostics, the :class:`.MultiDiagnostic` object can plot
+and create movies:
+
+.. code:: ipython3
+
+    m.plot(50)
+
+
+.. image:: user_guide/figures/maooam_run-Copy1_70_0.png
+
+
+.. code:: ipython3
+
+    m.movie(figsize=(15,8), anim_kwargs={'interval': 100, 'frames':100})
+
+.. include:: user_guide/vid_multi.rst
+
+Further examples using the diagnostics can be found in the sections :ref:`files/examples/RP:Recovering the result of Reinhold and Pierrehumbert (1982)`,
+:ref:`files/examples/DDV:Recovering the result of De Cruz, Demaeyer and Vannitsem (2016)` and :ref:`files/examples/manual:Manual setting of the basis`.
+Examples are also provided in the in the ``notebooks`` folder.
+
+Moreover, the diagnostics classes methods are fully described in the section :ref:`files/technical/diagnostics:Diagnostics` of the
+:ref:`files/references:References`.

documentation/source/files/examples.rst

@@ -7,9 +7,10 @@ Some basic examples are available in this section:
 .. toctree::
    :maxdepth: 1
 
-   examples/RP
+   examples/RP.rst
    examples/DDV
    examples/Lietal
    examples/diffeq
    examples/tgls
-   examples/VSPD
+   examples/VSPD
+   examples/manual

documentation/source/files/examples/manual.rst

@@ -0,0 +1,3 @@
+
+.. include:: manual_basis.rst
+    :start-line: 13