Merge pull request #18 from fenfisdi/issue/12/update_docstrings

Updated documentation - minor refactors on code

Features

* base documentation with examples and how to install the package
* refactored the predefined models into sub-packages
* renamed ``Optimize.minimize`` -> ``Optimize.optimize``

.gitignore

@@ -73,6 +73,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_build
 
 # PyBuilder
 .pybuilder/

.readthedocs.yml

@@ -3,7 +3,7 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
-version: 0.1.dev1
+version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -13,6 +13,9 @@ sphinx:
 formats:
   - pdf
 
+build:
+  image: testing
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
    version: 3.9

README.md

@@ -2,6 +2,6 @@
 
 ``DINJO Is Not Just An Optimizer`` is a Python framework designed for the optimization of initial value problems' parameters.
 
-Lets say you have some 'experimental' data of a state variable ``S`` of the initial value problem ``dS/dt = f(t, S; p), S(t_0) = f_0`` where ``p`` is a list of parameters.
+Lets say you have some 'experimental' data of a state variable ``S`` corresponding to the initial value problem ``dS/dt = f(t, S; p), S(t_0) = f_0`` where ``p`` is a list of parameters. If you want to know the optimal value of ``p`` so that the solution of the initial value problem fits your experimental data, you can use DINJO to get an approximate value of the optimal ``p``.
 
-If you want to know the optimal value of ``p`` so that the solution of the initial value problem fits your experimental data, you can use DINJO to get an approximate value of the optimal ``p``.
+**Visit [DINJO's official documentation](https://dinjo.readthedocs.io/)**

dinjo/model.py

@@ -36,11 +36,11 @@ class Parameter(Variable):
     """Represents a parameter of the differential equations definining
     an initial value problem.
 
-    Attributes
-    ----------
     In addition to the attributes defined in
-    :class:`dinjo.model.Variable`:
+    :py:class:`dinjo.model.Variable`
 
+    Attributes
+    ----------
     bounds : 2-tuple of floats.
         list containing the minimum and maximum values that the
         parameter can take ``(min, max)``.

dinjo/optimizer.py

@@ -142,7 +142,7 @@ def rms(solution_reference) -> float:
 
         return cost_func(solution_reference)
 
-    def minimize(
+    def optimize(
         self,
         cost_method: str = 'root_mean_square',
         algorithm: str = 'differential_evolution',

dinjo/predefined/__init__.py

@@ -1,11 +0,0 @@
-from ._seir_model import ModelSEIR
-from ._seirv_model import ModelSEIRV
-from ._seirv_fixed import ModelSimpleSEIRV
-from ._sir_model import ModelSIR
-
-__all__ = [
-    'ModelSEIR',
-    'ModelSEIRV',
-    'ModelSimpleSEIRV',
-    'ModelSIR',
-]

dinjo/predefined/epidemiology/__init__.py

@@ -0,0 +1,11 @@
+from ._seir_model import ModelSEIR
+from ._seirv_model import ModelSEIRV
+from ._seirv_fixed import ModelSimpleSEIRV
+from ._sir_model import ModelSIR
+
+__all__ = [
+    'ModelSEIR',
+    'ModelSEIRV',
+    'ModelSimpleSEIRV',
+    'ModelSIR',
+]

dinjo/predefined/_seir_model.py → dinjo/predefined/epidemiology/_seir_model.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ..model import ModelIVP
+from ...model import ModelIVP
 
 
 class ModelSEIR(ModelIVP):

dinjo/predefined/_seirv_fixed.py → dinjo/predefined/epidemiology/_seirv_fixed.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ..model import ModelIVP
+from ...model import ModelIVP
 
 
 class ModelSimpleSEIRV(ModelIVP):

dinjo/predefined/_seirv_model.py → dinjo/predefined/epidemiology/_seirv_model.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ..model import ModelIVP
+from ...model import ModelIVP
 
 
 class ModelSEIRV(ModelIVP):

dinjo/predefined/_sir_model.py → dinjo/predefined/epidemiology/_sir_model.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ..model import ModelIVP
+from ...model import ModelIVP
 
 
 class ModelSIR(ModelIVP):

dinjo/predefined/physics/__init__.py

@@ -0,0 +1,5 @@
+from ._harmonic_oscillator import ModelOscillator
+
+__all__ = [
+    'ModelOscillator',
+]

dinjo/predefined/physics/_harmonic_oscillator.py

@@ -0,0 +1,16 @@
+from ...model import ModelIVP
+
+
+class ModelOscillator(ModelIVP):
+    def build_model(self, t, y, w):
+        """Harmonic Oscillator differential equations
+        """
+        q, p = y
+
+        # Hamilton's equations
+        dydt = [
+            p,
+            - (w ** 2) * q
+        ]
+
+        return dydt

docs/source/conf.py

@@ -24,8 +24,8 @@
 copyright = '2021, Juan Esteban Aristizabal-Zuluaga and FEnFiSDi'
 author = 'Juan Esteban Aristizabal-Zuluaga and FEnFiSDi'
 
-version = '0.1.0'
-release = '0.1.0'
+version = '0.0'
+release = '0.0.dev1'
 
 # -- General configuration ---------------------------------------------------
 
@@ -50,7 +50,10 @@
 autodoc_default_options = {
     'members': True,
     'private-members':
-        '',
+        '_seir_model, '
+        '_seirv_model, '
+        '_seirv_fixed, '
+        '_sir_model',
     'special-members': '__init__',
     'inherited-members': False,
     'show-inheritance': False,

docs/source/dinjo/dinjo.model.rst

@@ -0,0 +1,10 @@
+.. _code-dinjo.model:
+
+=========================
+:mod:`dinjo.model` module
+=========================
+
+.. automodule:: dinjo.model
+   :members:
+   :undoc-members: reference_t_values
+   :show-inheritance:

docs/source/dinjo/dinjo.optimizer.rst

@@ -0,0 +1,10 @@
+.. _code-dinjo.optimizer:
+
+=============================
+:mod:`dinjo.optimizer` module
+=============================
+
+.. automodule:: dinjo.optimizer
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/dinjo/dinjo.predefined.epidemiology.rst

@@ -0,0 +1,62 @@
+.. _code-dinjo.predefined.epidemiology:
+
+===============================================
+:mod:`dinjo.predefined.epidemiology` subpackage
+===============================================
+
+For your convenience, the classes
+:py:class:`~dinjo.predefined.epidemiology._seir_model.ModelSEIR`,
+:py:class:`~dinjo.predefined.epidemiology._seirv_model.ModelSEIRV`,
+:py:class:`~dinjo.predefined.epidemiology._seirv_fixed.ModelSimpleSEIRV`,
+:py:class:`~dinjo.predefined.epidemiology._sir_model.ModelSIR`
+can be imported directly from the subpackage
+:mod:`dinjo.predefined.epidemiology`:
+
+.. code-block:: python
+
+   from dinjo.predefined.epidemiology import (
+      ModelSEIR,
+      ModelSEIRV,
+      ModelSimpleSEIRV,
+      ModelSIR
+   )
+
+
+Submodules
+==========
+
+:mod:`dinjo.predefined.epidemiology._seir_model`
+------------------------------------------------
+
+.. automodule:: dinjo.predefined.epidemiology._seir_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`dinjo.predefined.epidemiology._seirv_model`
+-------------------------------------------------
+
+.. automodule:: dinjo.predefined.epidemiology._seirv_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`dinjo.predefined.epidemiology._seirv_fixed`
+-------------------------------------------------
+
+.. automodule:: dinjo.predefined.epidemiology._seirv_fixed
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+:mod:`dinjo.predefined.epidemiology._sir_model`
+------------------------------------------------
+
+.. automodule:: dinjo.predefined.epidemiology._sir_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/source/dinjo/dinjo.predefined.rst

@@ -1,10 +1,23 @@
-dinjo.predefined package
-========================
+.. _code-dinjo.predefined:
 
-Module contents
----------------
+==================================
+:mod:`dinjo.predefined` subpackage
+==================================
+
+
+Package contents
+================
 
 .. automodule:: dinjo.predefined
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+Subpackages
+===========
+
+.. toctree::
+   :maxdepth: 4
+
+   dinjo.predefined.epidemiology

docs/source/dinjo/dinjo.rst

@@ -1,37 +1,32 @@
-dinjo
-=====
+.. _code-dinjo:
+
+====================
+:mod:`dinjo` package
+====================
+
+Package contents
+================
+
+.. automodule:: dinjo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 Subpackages
------------
+===========
 
 .. toctree::
    :maxdepth: 4
 
    dinjo.predefined
 
+
 Submodules
 ==========
 
-dinjo.model
------------
-
-.. automodule:: dinjo.model
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-dinjo.optimizer
----------------
-
-.. automodule:: dinjo.optimizer
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
-===============
+.. toctree::
+   :maxdepth: 4
 
-.. automodule:: dinjo
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   dinjo.model
+   dinjo.optimizer