Extra documentation

langevinmodel · Jun 3, 2024 · b6fa469 · b6fa469
1 parent 15f62c3
commit b6fa469
Show file tree

Hide file tree

Showing 6 changed files with 88 additions and 45 deletions.
diff --git a/docs/api/functions.rst b/docs/api/functions.rst
@@ -27,6 +27,8 @@ Parameteric Functions
     sklearnTransformer
 
     FiniteElement
+
+    ModelOverlay
 
 Non Parametric Functions
 =========================

diff --git a/docs/for_developper.rst b/docs/for_developper.rst
@@ -57,21 +57,25 @@ A model in folie represent a model of Langevin evolution. As such, it is mainly
 
 Most of the time, the  spatial dependencies of the model are described by folie functions and can simply be set as model attributes.
 
-When more complicated behavior are necessary (for exemple the mean displacement of a Langevin model is the sum of its force and its friction times the velocity), the is a mecanism of ModelOverlay.
+When more complicated behavior are necessary (for exemple the mean displacement of a Langevin model is the sum of its force and its friction times the velocity), the is a mecanism of :py:class:`~folie.functions.ModelOverlay`.
 
-ModelOverlay is a particular type of functions. This is an interface for model methods adn as such it allow for easy composition of functions.
+:py:class:`~folie.functions.ModelOverlay` is a particular type of functions. This is an interface for model methods adn as such it allow for easy composition of functions.
 
-model.mycomponent = ModelOverlay("_mycomponent")
+.. code-block:: python
+
+	model.mycomponent = ModelOverlay("_mycomponent")
 
-allow to access to the method of the models as if there was function attributes.
+allow to access to the method of the models as if there was function attributes. This means that we can use
 
-then using ModelOverlay, we can use
+.. code-block:: python
 
-model.mycomponent.grad_coeffs() 
+	model.mycomponent.grad_coeffs() 
 
 as a call to
 
-model._mycomponent_coeffs()
+.. code-block:: python
+
+	model._mycomponent_coeffs()
 
 This allows to have an unified interface to components of a model, irrespective of theirs definitions as model methods or as folie functions.
 
@@ -158,4 +162,4 @@ folie use sphinx gallery to automatically generate plot of the examples. To be i
 
 The tutorials folder contain more complex examples on the form of Jupyter notebooks, anything in the tutorials folder will be inclued into the corresponding documentation section. The name of the snippset will be the title of the jupyter notebook.
 
-The statistical_performances folder aims to contains Jupyter notebook that explore more systematically the peformance of the estimation with respect to number of data, choice of the estimator and so forth.
+The statistical_performances folder aims to contains Jupyter notebook that explore more systematically the peformance of the estimation with respect to number of data, choice of the estimator and so forth.
diff --git a/docs/notebooks/estimation.ipynb b/docs/notebooks/estimation.ipynb
@@ -193,7 +193,7 @@
    "id": "24ed7493",
    "metadata": {},
    "source": [
-    "# Parallel execution\n",
+    "## Parallel execution\n",
     "\n",
     "\n",
     "See https://scikit-learn.org/stable/computing/parallelism.html for an overview of available options.\n",

diff --git a/docs/notebooks/simulations.ipynb b/docs/notebooks/simulations.ipynb
diff --git a/folie/functions/base.py b/folie/functions/base.py
@@ -201,7 +201,30 @@ def coefficients(self, vals):
 
 class ModelOverlay(Function):
     """
-    A class that allow to overlay a model and make it be used as a function
+    A class that allow to overlay a model and make it be used as a function.
+
+    For example, if a model contain
+        model.mean_force =  ModelOverlay(model, "_force", output_shape=output_shape_force)
+    then we have the following mapping:
+
+        - model.mean_force(x) -> model._force(x)
+        - model.mean_force.grad_x(x) -> model._force_dx(x)
+        - model.mean_force.hessian_x(x) -> model._force_d2x(x)
+        - model.mean_force.grad_coeffs(x) -> model._force_dcoeffs(x)
+        - model.mean_force.coefficients -> model._force_coefficients
+
+    If any of the [function_name]_d* function is not implemented, it would be replaced by a numerical derivative
+
+    Parameters
+    ----------
+        model: a python class
+            This is the class to to overlay
+
+        function_name: str
+            The common part of the function name. The model should contain at least the function [function_name]
+
+        output_shape: tuple or array
+            The output shape of the term
     """
 
     def __init__(self, model, function_name, output_shape=None, **kwargs):

diff --git a/tests/test_simulation.py b/tests/test_simulation.py
@@ -19,6 +19,22 @@ def test_simple_simulation(steppercls):
     assert trj_data[0]["x"].shape == (50, 1)
 
 
+@pytest.mark.parametrize("steppercls", [fl.simulations.EulerStepper])
+def test_simple_simulation2d(steppercls):
+
+    data = np.linspace(-1, 1, 24).reshape(-1, 2)
+    fun = fl.functions.Polynomial(deg=3, domain=fl.Domain.Rd(2))  # .fit(data, y=data)
+    model = fl.models.Overdamped(fun)
+
+    simu_engine = fl.Simulator(steppercls(model), 1e-3)
+
+    trj_data = simu_engine.run(50, np.zeros((5, 2)))
+
+    assert len(trj_data) == 5
+
+    assert trj_data[0]["x"].shape == (50, 2)
+
+
 @pytest.mark.parametrize("steppercls", [fl.simulations.VECStepper])
 def test_underdamped_simulation(steppercls):