Adding solvers for quick experiments

.github/workflows/ci_pipeline.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
     defaults:
       run:
         shell: bash -l {0}
@@ -35,7 +35,7 @@ jobs:
         ./test.sh
     - name: Upload coverage reports to Codecov
       uses: codecov/codecov-action@v4
-      if: github.repository_owner == 'Parallel-in-Time' && matrix.python == '3.11'
+      if: github.repository_owner == 'Parallel-in-Time' && matrix.python == '3.13'
       with:
         flags: smart-tests
         verbose: true
@@ -47,10 +47,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.11
+    - name: Set up Python 3.13
       uses: actions/setup-python@v3
       with:
-        python-version: "3.11"
+        python-version: "3.13"
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

README.md

@@ -31,6 +31,8 @@ $$
 
 and many different **lower-triangular** approximations of the $Q$ matrix, named $Q_\Delta$,
 which are key elements for Spectral Deferred Correction (SDC), or more general Iterated Runge-Kutta Methods.
+It also contains **generic time-integration solvers** based on $Q$ and $Q_\Delta$ coefficients,
+that can be used for quick testing and experiments.
 
 [![DOI](https://zenodo.org/badge/804826743.svg)](https://zenodo.org/doi/10.5281/zenodo.11956478)
 
@@ -78,3 +80,8 @@ and the current [Development Roadmap](https://qmat.readthedocs.io/en/latest/devd
 - Issues Tracker : https://github.com/Parallel-in-Time/qmat/issues
 - Q&A : https://github.com/Parallel-in-Time/qmat/discussions/categories/q-a
 - Project Proposals : https://github.com/Parallel-in-Time/qmat/discussions/categories/project-proposals
+
+## Developers
+
+- [Thibaut Lunet](https://github.com/tlunet)
+- [Thomas Saupe (né Baumann)](https://github.com/brownbaerchen)

docs/SECURITY.md

@@ -12,6 +12,6 @@ While we recommend the use of the latest version, below is the list of the curre
 
 ## Reporting a Vulnerability
 
-If you see any vulnerability with this package, please open an 
+If you see any vulnerability with this package, please open an
 [issue on the Github interface ...](https://github.com/Parallel-in-Time/qmat/issues),
-so that is can be solved as quickly as possible by the developing community.
+so that is can be solved as quickly as possible by our developing community.

docs/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'QMat Package'
-copyright = '2024 PinT Community'
+copyright = '2025 PinT Community'
 author = 'PinT Community'
 
 # The short X.Y version
@@ -72,7 +72,7 @@
 autoapi_dirs = ['../qmat']
 autoapi_file_patterns = ['*.py']
 autoapi_options = [
-    'members', 'undoc-members', 
+    'members', 'undoc-members',
     'show-inheritance-diagram',
     'show-module-summary',
     ]
@@ -162,5 +162,5 @@
 # -- Options for nbsphinx galleries
 # Using _images/ is a hack to get relocated images which have been included in the pages
 nbsphinx_thumbnails = {
-    
+
 }

docs/contributing.md

@@ -26,16 +26,19 @@ Current coverage is at 100%, so no untested line will be accepted 😇.
 
 Chosen merge strategy is to squash commits $\Rightarrow$ you don't have to care about the number of commit included in your PR, so don't be scare of making mistakes before your PR is accepted 😉
 
-> 🔔 Once your PR is accepted, please delete this branch from your fork and synchronize your `main` branch. When creating a new development branch later, ensure that you start from an up-to-date `main` branch of your fork. 
+> 🔔 Once your PR is accepted, please delete this branch from your fork and synchronize your `main` branch. When creating a new development branch later, ensure that you start from an up-to-date `main` branch of your fork.
 
 In case you are interested in contributing but don't have any idea on what, checkout out current [development roadmap 🎯](./devdoc/roadmap.md) and [project proposals 🎓](https://github.com/Parallel-in-Time/qmat/discussions/categories/project-proposals)
 
 ## Base recipes
 
-_A few base memo on how to develop this package ..._
+_Some memos on how to develop this package ..._
 
-- [General code structure](./devdoc/structure.md)
+- [Code structure](./devdoc/structure.md)
 - [Add a Runge-Kutta scheme](./devdoc/addRK.md)
+- [Add a playground](./devdoc/addPlayground.md)
+- [Add a differential operator](./devdoc/addDiffOp.md)
+- [Add a $\phi$-based time-integrator](./devdoc/addPhiIntegrator.md)
 - [Testing your changes](./devdoc/testing.md)
 - [Update this documentation](./devdoc/updateDoc.md)
 - [Version update pipeline](./devdoc/versionUpdate.md)
@@ -47,6 +50,9 @@ _A few base memo on how to develop this package ..._
 
     devdoc/structure
     devdoc/addRK
+    devdoc/addPlayground
+    devdoc/addDiffOp
+    devdoc/addPhiIntegrator
     devdoc/testing
     devdoc/updateDoc
     devdoc/versionUpdate

docs/devdoc/addDiffOp.md

@@ -0,0 +1,95 @@
+# Add a differential operator
+
+📜 _Solvers implemented in {py:mod}`qmat.solvers.generic` can be used_
+_with other {py:class}`DiffOp <qmat.solvers.generic.DiffOp>` classes_
+_than those implemented in {py:mod}`qmat.solvers.generic.diffops`._
+
+To add a new one, implement it at the end of the `diffops.py` module,
+using the following template :
+
+```python
+@registerDiffOp
+class Yoodlidoo(DiffOp):
+    r"""
+    Base description, in particular its equation :
+
+    .. math::
+
+        \frac{du}{dt} = ...
+
+    And some parameters description ...
+    """
+    def __init__(self, params="value"):
+        # use some initialization parameters
+        u0 = ... # define your initial vector
+        super().__init__(u0)
+
+    def evalF(self, u, t, out:np.ndarray):
+        r"""
+        Evaluate :math:`f(u,t)` and store the result into `out`.
+
+        Parameters
+        ----------
+        u : np.ndarray
+            Input solution for the evaluation.
+        t : float
+            Time for the evaluation.
+        out : np.ndarray
+            Output array in which is stored the evaluation.
+        """
+        out[:] = ... # put the result into out
+```
+
+And that's all ! The `registerDiffOp` operator will automatically
+- add your class in the `DIFFOPS` dictionary to make it generically available
+- check if your class properly overrides the `evalF` function (import error if not)
+- add your class to the [CI tests](./testing.md)
+
+> 📣 Per default, all `DiffOp` classes must be instantiable with default parameters
+> in order to run the tests (see the {py:func}`DiffOp.test <qmat.solvers.generic.DiffOp.test>`
+> class method). But you can change that by overriding the `test` class method and put your own
+> preset parameters for the test (checkout the
+> {py:func}`ProtheroRobinson <qmat.solvers.generic.diffops.ProtheroRobinson>` class for an example).
+
+Finally, the `DiffOp` class implements a default `fSolve` method, that solves :
+
+$$
+u - \alpha f(u, t) = rhs
+$$
+
+for any given $\alpha, t, rhs$.
+It relies on generic non-linear root-finding solvers, namely `scipy.optimize.fsolve` for small problems 
+and `scipy.optimize.newton_krylov` for large scale problems.
+You can also implement a more efficient approach tailored to your problem like this :
+
+```python
+@registerDiffOp
+class Yoodlidoo(DiffOp):
+    # ...
+
+    def fSolve(self, a:float, rhs:np.ndarray, t:float, out:np.ndarray):
+        r"""
+        Solve :math:`u-\alpha f(u,t)=rhs` for given :math:`u,t,rhs`,
+        using `out` as initial guess and storing the final result into it.
+
+        Parameters
+        ----------
+        a : float
+            The :math:`\alpha` coefficient.
+        rhs : np.ndarray
+            The right hand side.
+        t : float
+            Time for the evaluation.
+        out : np.ndarray
+            Input-output array used as initial guess,
+            in which is stored the solution.
+        """
+        # TODO : your ultra-efficient implementation that will be
+        #        way better than a generic call of scipy.optimize.fsolve
+        #        or scipy.optimize.newton_krylov.
+        out[:] = ...
+```
+
+> 🔔 Note that `out` will be used as output for the solution, 
+> but its input value can also be used as initial guess for any
+> iterative solver you may want to use.

docs/devdoc/addPhiIntegrator.md

@@ -0,0 +1,44 @@
+# Add a $\phi$-based time-integrator
+
+📜 _Additional time schemes can be added using the [$\phi$ formulation](../notebooks/14_phiIntegrator.ipynb)_
+_to test other variants of $Q_\Delta$-coefficients free Spectral Deferred Correction._
+_For that, you can implement a new {py:mod}`PhiSolver <qmat.solvers.generic.PhiSolver>` class in the {py:mod}`qmat.solvers.generic.integrators` module_.
+
+Add your class at the end of the `qmat.solvers.generic.integrators.py` module using the following template :
+
+```python
+class Phidlidoo(PhiSolver):
+    r"""
+    Base description, in particular its definition :
+
+    .. math::
+
+        \phi(u_0, u_1, ..., u_{m}, u_{m+1}) =
+            ...
+
+    And eventual parameters description ...
+    """
+
+    def evalPhi(self, uVals, fEvals, out, t0=0):
+        m = len(uVals) - 1
+        assert m > 0
+        assert len(fEvals) in [m, m+1]
+
+        # TODO : integrators implementation
+```
+
+The first assertions are not mandatory, but ensure that the `evalPhi` is properly evaluated.
+
+> 📣 New `PhiSolver` classes are not automatically tested, so you'll have to write
+> some dedicated test for your new class in `tests.test_solvers.test_integrators.py`.
+> Checkout those already implemented for `ForwardEuler` and `BackwardEuler`.
+
+As for the {py:class}`DiffOp <qmat.solvers.generic.DiffOp>` class,
+the {py:class}`PhiSolver <qmat.solvers.generic.PhiSolver>` implements a generic default
+`phiSolve` method, that you can override by a more efficient specialized approach.
+
+> 💡 Note that the model above inherits the `__init__` constructor of the `PhiSolver` class,
+> so it can take any `DiffOp` class as parameter.
+> If your time-integrator is specialized for some kind of differential operators
+> (_e.g_ a semi-Lagrangian scheme for an advective problem),
+> then you probably need to override the `__init__` method in your class too.

docs/devdoc/addPlayground.md

@@ -0,0 +1,42 @@
+# Add a playground
+
+📜 _To add experimental scripts or usage examples, without testing everything : simply add your own **playground** in {py:mod}`qmat.playgrounds`._
+
+1. create a folder with a _short & representative_ name, _e.g_ `yoodlidoo` (can also be your name for a personal playground),
+2. put your script(s) in it, and document them as much as necessary so **anyone else can understand and use your code**,
+3. create a `__init__.py` file in your playground folder with a short summary of your scripts in its docstring, _e.g_
+    ```python
+    """
+    - :class:`script1` : trying some stuff.
+    - :class:`script2` : yet another idea.
+    """
+    ```
+4. add the item line corresponding to your playground in `qmat.playgrounds.__init__.py`, _e.g_
+    ```python
+    """
+    ...
+
+    Current playgrounds
+    -------------------
+
+    - ...
+    - :class:`yoodlidoo` : some ideas to do stuff
+    """
+    ```
+5. open a pull request against the `main` branch of `qmat`.
+
+> 💡 If you don't want your playground to be integrated into the main branch of`qmat` (no proper documentation, code always evolving, ...),
+> you can still add a **soft link to a playground in your fork** by modifying `qmat.playgrounds.__init__.py` :
+> ```python
+> """
+> ...
+>
+> Current playgrounds
+> -------------------
+>
+> - ...
+> - `{name} <https://github.com/{userName}/qmat/tree/{branch}/qmat/playgrounds/{name}>`_ : some ideas ...
+> """
+> ```
+> where `name` is your playground name, `userName` your GitHub username and `branch` the branch name on your fork you are working on
+> (**do not use the `main` branch of your fork** ⚠️)