Implementation of the toolbox module computing the Lyapunov vectors and

exponents

documentation/source/conf.py

@@ -22,7 +22,7 @@
 author = 'Jonathan Demaeyer and Lesley De Cruz'
 
 # The full version, including alpha/beta/rc tags
-release = 'v0.2.4'  # temporary
+release = 'v0.2.5'  # temporary
 version = release
 
 

documentation/source/files/model/ref.bib

@@ -438,3 +438,57 @@ @article{OB1989
   publisher = {Taylor & Francis},
   url = {https://doi.org/10.3402/tellusa.v41i4.11842}
 }
+
+@article{BGGS1980,
+  title={Lyapunov characteristic exponents for smooth dynamical systems and for Hamiltonian systems; a method for computing all of them. Part 1: Theory},
+  author={Benettin, Giancarlo and Galgani, Luigi and Giorgilli, Antonio and Strelcyn, Jean-Marie},
+  journal={Meccanica},
+  volume={15},
+  number={1},
+  pages={9--20},
+  year={1980},
+  publisher={Springer},
+  url={https://link.springer.com/article/10.1007/BF02128236}
+}
+
+@article{KP2012,
+  title={Theory and computation of covariant Lyapunov vectors},
+  author={Kuptsov, Pavel V and Parlitz, Ulrich},
+  journal={Journal of nonlinear science},
+  volume={22},
+  number={5},
+  pages={727--762},
+  year={2012},
+  publisher={Springer},
+  url={https://link.springer.com/article/10.1007/s00332-012-9126-5}
+}
+
+@article{GPTCLP2007,
+  title={Characterizing dynamics with covariant Lyapunov vectors},
+  author={Ginelli, Francesco and Poggi, Pietro and Turchi, Alessio and Chat{\'e}, Hugues and Livi, Roberto and Politi, Antonio},
+  journal={Physical review letters},
+  volume={99},
+  number={13},
+  pages={130601},
+  year={2007},
+  publisher={APS},
+  url={https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.99.130601}
+}
+
+@article{ER1985,
+  title={Ergodic theory of chaos and strange attractors},
+  author={Eckmann, J-P and Ruelle, David},
+  journal={The theory of chaotic attractors},
+  pages={273--312},
+  year={1985},
+  publisher={Springer},
+  url={https://link.springer.com/chapter/10.1007/978-0-387-21830-4_17}
+}
+
+@article{DPV2021,
+  title={Identifying efficient ensemble perturbations for initializing subseasonal-to-seasonal prediction},
+  author={Demaeyer, Jonathan and Penny, Stephen G and Vannitsem, St{\'e}phane},
+  journal={arXiv preprint arXiv:2109.07979},
+  year={2021},
+  url={https://arxiv.org/abs/2109.07979}
+}

documentation/source/files/references.rst

@@ -14,3 +14,4 @@ Documentation of the classes and functions of the models.
    technical/diagnostics
    technical/integrators
    technical/misc
+   technical/toolbox

documentation/source/files/technical/toolbox.rst

@@ -0,0 +1,9 @@
+
+Toolbox module
+==============
+
+Module holding model's tools (analysis, Lyapunov vectos, ...).
+
+.. automodule:: qgs.toolbox.lyapunov
+    :show-inheritance:
+    :members:

documentation/source/files/technical_description.rst

@@ -74,7 +74,7 @@ Additional technical information
 --------------------------------
 
 * qgs is optimized to run ensembles of initial conditions on multiple cores, using `Numba`_ jit-compilation and
-  `multiprocessing`_ workers. As such, qgs does not work on Windows presently.
+  `multiprocessing`_ workers.
 
 * qgs has a `tangent linear model`_ optimized to run ensembles of initial conditions as well, with a broadcast
   integration of the tangent model thanks to `Numpy`_.

documentation/source/files/user_guide.rst

@@ -502,6 +502,37 @@ Note that it is also possible to use other ordinary differential equations integ
 
 More diagnostics will be implemented soon.
 
+4.2 Toolbox
+^^^^^^^^^^^
+
+The toolbox regroups submodules to make specific analysis with the model and are available in the :mod:`qgs.toolbox` module.
+For the references of these submodules, see :ref:`files/technical/toolbox:Toolbox module`.
+
+Presently, the list of submodules available is the following:
+
+* ``lyapunov``: A module to compute Lyapunov exponents and vectors.
+
+More submodules will be implemented soon.
+
+4.2.1 Lyapunov toolbox
+""""""""""""""""""""""
+
+This module allows you to integrate the model and simultaneously obtain the *local* `Lyapunov vectors`_ and `exponents`_.
+The methods included are:
+
+1. The Benettin algorithm to compute the *Forward* and *Backward* Lyapunov vectors :cite:`user-BGGS1980`.
+   This method is implemented in the :class:`~.lyapunov.LyapunovsEstimator` class.
+2. The method of the intersection between the subspaces spanned by the Forward and Backward vectors to find the
+   *Covariant* Lyapunov vectors :cite:`user-ER1985` (see also :cite:`user-DPV2021`). Suitable for long trajectories.
+   This method is implemented in the :class:`~.lyapunov.CovariantLyapunovsEstimator` class.
+3. The Ginelli method :cite:`user-GPTCLP2007` to compute also the *Covariant* Lyapunov vectors.
+   Suitable for a trajectory not too long (depends on the memory available).
+   This method is also implemented in the :class:`~.lyapunov.CovariantLyapunovsEstimator` class.
+
+See also :cite:`user-KP2012` for a description of these methods.
+
+Some example notebooks on how to use this module are available in the `notebooks/lyapunov <../../../../notebooks/lyapunov>`_ folder.
+
 5. Developers information
 -------------------------
 
@@ -544,3 +575,5 @@ References
 .. _basis functions: https://en.wikipedia.org/wiki/Basis_function
 .. _basis: https://en.wikipedia.org/wiki/Basis_(linear_algebra)
 .. _Fourier modes: https://en.wikipedia.org/wiki/Fourier_series
+.. _Lyapunov vectors: https://en.wikipedia.org/wiki/Lyapunov_vector
+.. _exponents: https://en.wikipedia.org/wiki/Lyapunov_exponent