Reorg of the code into a general qgs folder

See
openjournals/joss-reviews#2597 (comment)
for more details.
Solve the related issue #7, see #7
.

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.2'  # temporary
+release = 'v0.2.3'  # temporary
 version = release
 
 

documentation/source/files/examples/DDV2016.ipynb

@@ -100,9 +100,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from integrators.integrator import RungeKuttaIntegrator\n",
-    "from functions.tendencies import create_tendencies"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies"
    ]
   },
   {

documentation/source/files/examples/Lietal2017.ipynb

@@ -103,10 +103,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
-    "from functions.tendencies import create_tendencies\n",
-    "from plotting.util import std_plot"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies\n",
+    "from qgs.plotting.util import std_plot"
    ]
   },
   {

documentation/source/files/examples/RP1982.ipynb

@@ -100,10 +100,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
-    "from functions.tendencies import create_tendencies\n",
-    "from plotting.util import std_plot"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies\n",
+    "from qgs.plotting.util import std_plot"
    ]
   },
   {

documentation/source/files/examples/VSPD2019.ipynb

@@ -100,10 +100,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from basis.fourier import contiguous_channel_basis\n",
-    "from integrators.integrator import RungeKuttaIntegrator\n",
-    "from functions.tendencies import create_tendencies"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.basis.fourier import contiguous_channel_basis\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies"
    ]
   },
   {

documentation/source/files/examples/diffeq_example.ipynb

@@ -122,10 +122,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from integrators.integrator import RungeKuttaIntegrator\n",
-    "from functions.tendencies import create_tendencies\n",
-    "from plotting.util import std_plot"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies\n",
+    "from qgs.plotting.util import std_plot"
    ]
   },
   {

documentation/source/files/examples/tgls_example.ipynb

@@ -122,10 +122,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from params.params import QgParams\n",
-    "from integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
-    "from functions.tendencies import create_tendencies\n",
-    "from plotting.util import std_plot"
+    "from qgs.params.params import QgParams\n",
+    "from qgs.integrators.integrator import RungeKuttaIntegrator, RungeKuttaTglsIntegrator\n",
+    "from qgs.functions.tendencies import create_tendencies\n",
+    "from qgs.plotting.util import std_plot"
    ]
   },
   {

documentation/source/files/model/maooam_model.rst

@@ -288,6 +288,8 @@ that are implemented by means of a tensorial contraction:
 with :math:`\boldsymbol{\eta} = (1, \psi_{{\rm a},1}, \ldots, \psi_{{\rm a},n_\mathrm{a}}, \theta_{{\rm a},1}, \ldots, \theta_{{\rm a},n_\mathrm{a}}, \psi_{{\rm o},1}, \ldots, \psi_{{\rm o},n_\mathrm{o}}, \delta T_{{\rm o},1}, \ldots, \delta T_{{\rm o},n_\mathrm{o}})`, as described in the :ref:`files/technical_description:Code Description`. Note that :math:`\eta_0 \equiv 1`.
 The tensor :math:`\mathcal{T}`, which fully encodes the bilinear system of ODEs above, is computed and stored in the :class:`~tensors.qgtensor.QgsTensor`.
 
+.. TODO: section about MAOSOAM
+
 Example
 -------
 

documentation/source/files/technical/configuration.rst

@@ -4,18 +4,18 @@ Model configuration
 
 We describe here the modules used to configure the model. Please read the :ref:`files/user_guide:User guide` to learn how to use them.
 
-.. automodule:: params.params
+.. automodule:: qgs.params.params
     :show-inheritance:
     :members:
 
-.. automodule:: basis.base
+.. automodule:: qgs.basis.base
     :show-inheritance:
     :members:
 
-.. automodule:: basis.fourier
+.. automodule:: qgs.basis.fourier
     :show-inheritance:
     :members:
 
-.. automodule:: params.parameter
+.. automodule:: qgs.params.parameter
     :show-inheritance:
     :members:

documentation/source/files/technical/functions.rst

@@ -4,11 +4,11 @@ Functions module
 
 The functions module contains utility functions used by the model, as well as some high-level functions to handle it.
 
-.. automodule:: functions.sparse_mul
+.. automodule:: qgs.functions.sparse_mul
     :members:
 
-.. automodule:: functions.tendencies
+.. automodule:: qgs.functions.tendencies
     :members:
 
-.. automodule:: functions.util
+.. automodule:: qgs.functions.util
     :members:

documentation/source/files/technical/inner_products.rst

@@ -5,18 +5,18 @@ Inner Products
 The inner products modules contain or produce the inner products needed for the projection of
 the model's equations on basis of functions defined on its spatial domain.
 
-.. automodule:: inner_products.base
+.. automodule:: qgs.inner_products.base
     :show-inheritance:
     :members:
 
-.. automodule:: inner_products.definition
+.. automodule:: qgs.inner_products.definition
     :show-inheritance:
     :members:
 
-.. automodule:: inner_products.analytic
+.. automodule:: qgs.inner_products.analytic
     :show-inheritance:
     :members:
 
-.. automodule:: inner_products.symbolic
+.. automodule:: qgs.inner_products.symbolic
     :show-inheritance:
     :members:

documentation/source/files/technical/integrators.rst

@@ -5,9 +5,9 @@ Integration modules
 The modules used to numerically integrate the model forward in time.
 Users may add their own recipes here.
 
-.. automodule:: integrators.integrate
+.. automodule:: qgs.integrators.integrate
     :members:
 
-.. automodule:: integrators.integrator
+.. automodule:: qgs.integrators.integrator
     :show-inheritance:
     :members:

documentation/source/files/technical/misc.rst

@@ -4,5 +4,5 @@ Miscellaneous modules
 
 `Fourre-tout` place of the model code.
 
-.. automodule:: plotting.util
+.. automodule:: qgs.plotting.util
     :members:

documentation/source/files/technical/tensors.rst

@@ -4,6 +4,6 @@ Tensors module
 
 Module holding the model's tendencies tensor encoding each of their additive terms.
 
-.. automodule:: tensors.qgtensor
+.. automodule:: qgs.tensors.qgtensor
     :show-inheritance:
     :members:

documentation/source/files/technical_description.rst

@@ -21,7 +21,7 @@ merge :math:`c_i`, :math:`m_{i,j}`, and :math:`t_{i,j,k}` into the tensor
 
     \frac{\text{d}\eta_i}{\text{d}t} = \sum_{j,k=0}^{\mathrm{ndim}} \mathcal{T}_{i,j,k} \, \eta_j \, \eta_k
 
-The tensor :math:`\mathcal{T}` is computed and stored in the :class:`~tensors.qgtensor.QgsTensor`.
+The tensor :math:`\mathcal{T}` is computed and stored in the :class:`~.tensors.qgtensor.QgsTensor`.
 Recasting the system of ordinary differential
 equations for :math:`\eta_i` in the form of a tensor contraction has certain
 advantages. Indeed, the symmetry of the tensor contraction allows for a unique representation
@@ -59,10 +59,10 @@ Computational flow
 The computational flow is as follows:
 
 1. The parameters are specified by instantiating a :class:`~.params.QgParams` .
-2. The inner products are computed and stored in :class:`~inner_products.analytic.AtmosphericInnerProducts` and :class:`~inner_products.analytic.OceanicInnerProducts` objects.
-3. The tensor of the tendencies terms are computed in a :class:`~tensors.qgtensor.QgsTensor` object.
-4. The functions :obj:`~functions.tendencies.create_tendencies` create Numba optimized functions that return the tendencies and the Jacobian matrix.
-5. These functions are passed to the numerical integrator in the module :mod:`~integrators.integrator` .
+2. The inner products are computed and stored in :class:`~.inner_products.base.AtmosphericInnerProducts` and :class:`~.inner_products.base.OceanicInnerProducts` objects.
+3. The tensor of the tendencies terms are computed in a :class:`~.tensors.qgtensor.QgsTensor` object.
+4. The functions :obj:`~.functions.tendencies.create_tendencies` create Numba optimized functions that return the tendencies and the Jacobian matrix.
+5. These functions are passed to the numerical integrator in the module :mod:`~.integrators.integrator` .
 
 .. figure:: figures/compuflow.png
     :scale: 70%

documentation/source/files/user_guide.rst

@@ -34,7 +34,7 @@ The computational flow to compute the function :math:`\boldsymbol{f}` of the mod
 
     Sketch of the computational flow.
 
-This flow can be implemented step by step by the user, or can be automatically performed by the functions :meth:`~.tendencies.create_tendencies`.
+This flow can be implemented step by step by the user, or can be automatically performed by the functions :meth:`~qgs.functions.tendencies.create_tendencies`.
 This function takes a :class:`~.params.QgParams` parameters object and return the function :math:`\boldsymbol{f}` and its Jacobian matrix.
 Optionally, it can also return the byproducts of the tendencies generation process, i.e. the objects containing the inner products
 between the model's spatial modes and the tensors of the model's tendencies terms.
@@ -66,7 +66,7 @@ The model initialization first step requires the creation of a :class:`~.params.
 
 .. code:: ipython3
 
-    from params.params import QgParams
+    from qgs.params.params import QgParams
     model_parameters = QgParams()
 
 This object contains basically all the information needed by qgs to construct the inner products and the tendencies tensor of the model, which are in turn needed to produces finally the model's function :math:`\boldsymbol{f}`.
@@ -78,24 +78,24 @@ the partial differential equations of qgs. As said before, two methods are avail
 """"""""""""""""""""""""""
 
 With this method, the user has to provide directly the basis of functions of each component. These functions have to be symbolic function expressions, and should be provided using `Sympy`_.
-This has to be done using a :class:`~basis.base.SymbolicBasis` object, which is basically a list of Sympy functions.
+This has to be done using a :class:`~.basis.base.SymbolicBasis` object, which is basically a list of Sympy functions.
 
-The user can construct his own basis (see below) or use the various built-in Fourier basis provided with qgs: :class:`~basis.fourier.ChannelFourierBasis` or :class:`~basis.fourier.BasinFourierBasis`.
-In the latter case, convenient constructor functions have been defined to help the user get the Fourier basis: :meth:`~basis.fourier.contiguous_basin_basis` and :meth:`~basis.fourier.contiguous_channel_basis`.
+The user can construct his own basis (see below) or use the various built-in Fourier basis provided with qgs: :class:`~.basis.fourier.ChannelFourierBasis` or :class:`~.basis.fourier.BasinFourierBasis`.
+In the latter case, convenient constructor functions have been defined to help the user get the Fourier basis: :meth:`~qgs.basis.fourier.contiguous_basin_basis` and :meth:`~qgs.basis.fourier.contiguous_channel_basis`.
 These functions create `contiguous` Fourier basis for two different kind of boundary conditions (a zonal channel or a closed basin) shown on the first figure in :ref:`files/model/maooam_model:Coupled ocean-atmosphere model (MAOOAM)`.
 
 .. note::
 
     A `contiguous` Fourier basis means here that the Fourier modes are all present in the model up to a given maximum wavenumber in each direction (`zonal and meridional`_).
     Hence one has only to specify the maximum wavenumbers (and the model's domain aspect ratio) to these constructor functions. One can also create non-`contiguous` Fourier basis by specifying wavenumbers explicitly at
-    the :class:`~basis.fourier.ChannelFourierBasis` or :class:`~basis.fourier.BasinFourierBasis` instantiation (see the section :ref:`files/user_guide:3.1 A simple example` for an example).
+    the :class:`~.basis.fourier.ChannelFourierBasis` or :class:`~.basis.fourier.BasinFourierBasis` instantiation (see the section :ref:`files/user_guide:3.1 A simple example` for an example).
 
-Once constructed, the basis has to be provided to the :class:`~.params.QgParams` object by using dedicated methods: :meth:`~.params.QgParams.set_atmospheric_modes`, :meth:`~.params.QgParams.set_oceanic_modes` and :meth:`~.params.QgParams.set_ground_modes`.
+Once constructed, the basis has to be provided to the :class:`~.params.QgParams` object by using dedicated methods: :meth:`~qgs.params.QgParams.set_atmospheric_modes`, :meth:`~qgs.params.QgParams.set_oceanic_modes` and :meth:`~qgs.params.QgParams.set_ground_modes`.
 With the constructor functions, one can activate the mandatory atmospheric layer by typing
 
 .. code:: ipython3
 
-    from basis.fourier import contiguous_channel_basis
+    from qgs.basis.fourier import contiguous_channel_basis
     basis = contiguous_channel_basis(2, 2, 1.5)
     model_parameters.set_atmospheric_modes(basis)
 
@@ -105,11 +105,11 @@ where we have defined a channel Fourier basis up to wavenumber 2 in both directi
 
     Please note that the aspect ratio of the basis object provided to qgs is not very important, because it is superseded by the aspect ratio sets in the :class:`~.params.QgParams` object.
 
-To activate the ocean or the ground components, the user has simply to use the method :meth:`~.params.QgParams.set_oceanic_modes` and :meth:`~.params.QgParams.set_ground_modes`.
+To activate the ocean or the ground components, the user has simply to use the method :meth:`~qgs.params.QgParams.set_oceanic_modes` and :meth:`~qgs.params.QgParams.set_ground_modes`.
 Note that providing a oceanic basis of functions automatically deactivate the ground component, and vice-versa.
 
 Finally, since the `MAOOAM`_ Fourier basis are used frequently in qgs, convenient methods of the :class:`~.params.QgParams` object allow one to create easily these basis inside this object
-(without the need to create them externally and then pass them to the qgs parameters object). These are the methods :meth:`~.params.QgParams.set_atmospheric_channel_fourier_modes`, :meth:`~.params.QgParams.set_oceanic_basin_fourier_modes` and :meth:`~.params.QgParams.set_ground_channel_fourier_modes`.
+(without the need to create them externally and then pass them to the qgs parameters object). These are the methods :meth:`~qgs.params.QgParams.set_atmospheric_channel_fourier_modes`, :meth:`~qgs.params.QgParams.set_oceanic_basin_fourier_modes` and :meth:`~qgs.params.QgParams.set_ground_channel_fourier_modes`.
 For instance, the effect obtained with the 3 previous lines of code (activating the atmosphere) can also be obtained by typing:
 
 .. code:: ipython3
@@ -128,7 +128,7 @@ These convenient methods can also initialize qgs with another method (called `an
 Computing the inner products of the symbolic functions defined with `Sympy`_ **can be very resources consuming**, therefore if the basis
 of functions that you intend to use are the ones described in :ref:`files/model/maooam_model:Coupled ocean-atmosphere model (MAOOAM)`, you might be interested to use
 the analytic method, which uses the analytic formula for the inner products given in :cite:`user-DDV2016`. This initialization mode is put in action by using the
-convenient methods of the :class:`~.params.QgParams` object: :meth:`~.params.QgParams.set_atmospheric_channel_fourier_modes`, :meth:`~.params.QgParams.set_oceanic_basin_fourier_modes` and :meth:`~.params.QgParams.set_ground_channel_fourier_modes`.
+convenient methods of the :class:`~.params.QgParams` object: :meth:`~qgs.params.QgParams.set_atmospheric_channel_fourier_modes`, :meth:`~qgs.params.QgParams.set_oceanic_basin_fourier_modes` and :meth:`~qgs.params.QgParams.set_ground_channel_fourier_modes`.
 
 For instance, to initialize a channel atmosphere with up to wavenumber 2 in both directions, one can simply write:
 
@@ -166,7 +166,7 @@ These parameters classes are regrouped into the global structure :class:`~.param
 * :attr:`~.params.QgParams.ground_params` for :class:`~.params.GroundParams`.
 * :attr:`~.params.QgParams.otemperature_params` for :class:`~.params.GroundTemperatureParams`.
 
-The parameters inside these structures can be changed by passing a dictionary of the new values to the :meth:`~.params.QgParams.set_params` method. For example, if one wants to change the
+The parameters inside these structures can be changed by passing a dictionary of the new values to the :meth:`~qgs.params.QgParams.set_params` method. For example, if one wants to change the
 Coriolis parameter :math:`f_0` and the static stability of the atmosphere :math:`\sigma`, one has to write:
 
 .. code:: ipython3
@@ -222,7 +222,7 @@ Jacobian matrix :math:`\boldsymbol{\mathrm{Df}}`. Just pass it to the function :
 
 .. code:: ipython3
 
-    from functions.tendencies import create_tendencies
+    from qgs.functions.tendencies import create_tendencies
 
     f, Df = create_tendencies(model_parameters)
 
@@ -249,7 +249,7 @@ and it can be loaded again by typing
 
 .. code:: ipython3
 
-    from params.params import QgParams
+    from qgs.params.params import QgParams
 
     # loading the model
     with open('model.pickle', "rb") as file:
@@ -297,14 +297,14 @@ First, we create the parameters object:
 
 .. code:: ipython3
 
-    from params.params import QgParams
+    from qgs.params.params import QgParams
     model_parameters = QgParams({'n': 1.5})
 
 and we create a :class:`.ChannelFourierBasis` with all the modes up to wavenumber 2 in both directions, except the one with wavenumbers 1 and 2 in respectively the :math:`x` and :math:`y` direction:
 
 .. code:: ipython3
 
-    from basis.fourier import ChannelFourierBasis
+    from qgs.basis.fourier import ChannelFourierBasis
     atm_basis = ChannelFourierBasis(np.array([[1,1],
                                               [2,1],
                                               [2,2]]),1.5)
@@ -342,15 +342,15 @@ First we create the parameters object and the atmosphere:
 
 .. code:: ipython3
 
-    from params.params import QgParams
+    from qgs.params.params import QgParams
     model_parameters = QgParams({'n': 1.5})
     model_parameters.set_atmospheric_channel_fourier_modes(2, 2, mode="symbolic")
 
 Then we create a :class:`.SymbolicBasis` object:
 
 .. code:: ipython3
 
-    from basis.base import SymbolicBasis
+    from qgs.basis.base import SymbolicBasis
     ocean_basis = SymbolicBasis()
 
 We must then specify the function of the basis using `Sympy`_:
@@ -420,7 +420,7 @@ and passing it to a :class:`.OceanicSymbolicInnerProducts` object:
 
     ip = UserInnerProductDefinition()
 
-    from inner_products.symbolic import AtmosphericSymbolicInnerProducts, OceanicSymbolicInnerProducts
+    from qgs.inner_products.symbolic import AtmosphericSymbolicInnerProducts, OceanicSymbolicInnerProducts
 
     aip = AtmosphericSymbolicInnerProducts(model_parameters)
     oip = OceanicSymbolicInnerProducts(model_parameters, inner_product_definition=ip)
@@ -431,7 +431,7 @@ Once computed, the corresponding tendencies must then be created manually, first
 
 .. code:: ipython3
 
-    from tensors.qgtensor import QgsTensor
+    from qgs.tensors.qgtensor import QgsTensor
 
     aotensor = QgsTensor(model_parameters, aip, oip)
 
@@ -461,7 +461,7 @@ the qgs built-in integrator to obtain the model's trajectories:
 
 .. code:: python3
 
-    from integrators.integrator import RungeKuttaIntegrator
+    from qgs.integrators.integrator import RungeKuttaIntegrator
     import numpy as np
 
     integrator = RungeKuttaIntegrator()

documentation/source/index.rst

@@ -33,7 +33,6 @@ About
 =====
 
 Part of the code comes from the Python `MAOOAM`_ implementation by Maxime Tondeur and Jonathan Demaeyer.
-qgs is licensed under the `MIT`_ license:
 
 **Please cite the code description article if you use (a part of) this software for a publication:**
 
@@ -42,6 +41,8 @@ qgs is licensed under the `MIT`_ license:
 
 Please consult the qgs `code repository <http://www.github.com/Climdyn/qgs>`_ for updates.
 
+qgs is licensed under the `MIT`_ license:
+
 .. code-block:: none
 
    The MIT License (MIT)