Adding solvers for quick experiments

[tlunet]

This PR intends to bring qmat to version 1.0.0, including many new features, in particular :

• vectorized Dahlquist solver (single $\lambda$, IMEX)
• generic Runge-Kutta and SDC solvers for non-linear problem
• introduction of the DiffOp class for non-linear problem to implement some toy problems
• implementation of the $\phi$-SDC, allowing to define SDC sweeps without any $Q_\Delta$ coefficient
• finalization of the notebook tutorials, with advanced tutorials on the generic solvers implementation
• addition of a playground system, where contributors can add their own code, or a link to a playground in their fork

All implemented solver classes (and associated tutorials) make use of the $Q$ and $Q_\Delta$ coefficients of qmat, and allows to easily test different time-schemes on different problems.

📣 To review the documentation, it's highly recommended to generate it locally, cf docs on docs.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (43dd0b6) to head (5441d06).

Additional details and impacted files

@@            Coverage Diff             @@
##              main       #21    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           15        19     +4     
  Lines         1505      2088   +583     
==========================================
+ Hits          1505      2088   +583     

Flag	Coverage Δ
smart-tests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[brownbaerchen]

Looks really nice. Lot's of new stuff. I have a few concerns about naming, which I put in the comments.
Of course I wasn't able to check very closely that the code is as clean and correct as possible with such a large PR, but overall cleanliness appears to be really good and the testing comprehensive, so that seems fine to me.

I am wondering a bit about the direction qmat overall evolves in. Its scope is expanding from a repository of quadrature coefficients to a playground for SDC. This is not necessarily bad. But I feel like most of your issues with pySDC stem from the code trying to be really flexible, really easy to understand and to support everything and invariably failing to excel at all of it. Of course the eierlegende Wollmilchsau doesn't exist. It's not pySDC and it will not be qmat. Already, I am confused why there is a specialized Dahlquist solver and an implementation of a "differential operator" for the Dahlquist problem...
Does it make sense to split the generation of $Q$ and $Q_\Delta$ coefficients and the SDC research playground that qmat is becoming with this PR into two separate repositories? This would ensure the separation of concerns and decoupling of the building blocks. Just consider: If you tell people to add pySDC as a dependency to their code in order to get the coefficients, they will laugh at you because it sounds too complicated and qmat is the solution to this problem. For now.

[brownbaerchen]

I think this template is not entirely sufficient explanation. In particular because of some mixing of stuff.
If I understand correctly, the "differential operator" implements the $f$ in an equation $u_t=f$. But then this class defines initial conditions for the associated initial value problem and has a function evalF when to me it should be called only eval because the differential operator is already $f$.
I have not yet read the code this documents, but that is also the intended order for new contributers and I am pretty sure I would not be the only one to be confused.

[tlunet]

Agree on solving the confusion, I'll improve the template. But eval is already a built-in python function, and the name should echo with the fSolve method. We could change to fEval maybe ... but it feels a bit weird

[brownbaerchen]

Well, how set are you on the "differential operator" name? I would personally change that and then the other names are fine.

[tlunet]

I didn't find anything better at the moment. Problem is too generic and looks too close to pySDC. And at the end, we do need a class representing

$$ f(u,t) $$

a.k.a

$$ \frac{du}{dt} $$

which I imagined can be named a (time) "differential operator". I also thought about ODERightHandSide, but it didn't felt as simple and concise as DiffOp

[brownbaerchen]

I don't think problem is too generic. Yes pySDC has problems (pun intended) but so does the rest of the world. I think differential operator is also very generic, but I personally don't expect it to have properties like $f$.
I don't know what the perfect name here is, but maybe this is another sign that this belongs in a separate repository, not in the one that computes quadrature coefficients.

[tlunet]

Thanks for the review, I really appreciate. I've left (for now) the main issue to solve, which is how to name a class allowing to evaluate $f(u,t)$, store the initial solution $u_0$, and solve $u-\alpha f(u,t)=rhs$. For now, it's the DiffOp class, with the evalF method for $f(u,t)$ and fSolve for $u-\alpha f(u,t)=rhs$.

Note that it echoes with the evalPhi and phiSolve of the PhiSolver class (generic time-integrator).

I'm still not sure about the Problem name tho ... after all, we are talking about differential equations here, which are a given type of problems

[tlunet]

Now on the concern of qmat loosing its simplicity : I fear that too. The main motivation behind adding those solvers, is that Martin Schreiber wanted to experiment with SDC, but wouldn't use pySDC because of its complexity for newcomers. So I quickly implemented some first solvers as example, in particular on how to do that for non-linear ODE's, so he could use it as a framework. Then came the $\phi$-solver approach out of this, which is something that would have been more complicated to do in pySDC. And I needed a few example problems to test everything, which led to the DiffOp classes.

So it did degenerated a bit, but I believe qmat is still not too big yet. And I would describe its two main goals as :

1. providing an easy way to generate quadrature coefficients, butcher tables and $Q_\Delta$ matrices
2. allowing to understand how SDC works and how to implement this on your own operational code

And the tutorials show how to do it in a naive (not efficient) way, while the provided implementation gives a generic & memory efficient approach (very similar to what was done in SWEET or for Dedalus). The solvers and DiffOp classes contribute then to point 2, and the potential experiments with it (hence the playgrounds) came naturally.

Maybe we could write in the contributing guide some development conditions for the future, as :

• keeping qmat as small and simple as possible
• add new DiffOp classes only if necessary to implement new time-integration approaches (like SL)
• add your playground in the main code only if it's useful for learning or later developments, else simply add a link to your fork in qmat.playgrounds.__init__.py.
• do not add more dependencies than the existing one (numpy and scipy)

Ideally, pySDC would serve as this easy access playground, but it will need some major rework before that. qmat can serve as temporary small playground to see what works and what does not, and then we could use the experience on a major rework of pySDC to make it more accessible, and leave qmat to the small stuff ...

[pancetta]

Just my 2 cents here: beware of scope creep. It happens and always starts like "yeah, just added this here and there, might be removed later anyway, what's the harm", you name it. Listen to the old man, been there, done that. There is no point having another pySDC beast around.

I have no problem (hahaha) with a pySDC competitor, also because its future is not bright. yet, don't reinvent the wheel, learn from the mistakes I have done. And don't try do distinguish yourself at all cost, not everything is bad there.

[tlunet]

I fully agree with the wise man 😉 ... hence I don't think qmat should compete with pySDC. But its idea is to start from RK then go to SDC, while pySDC started from PFASST to go to SDC, even arriving to RK at some point.

So I hope we'll find a better ground when those two directions intersect, and maybe make a better version of pySDC out of it ...

[pancetta]

Looks like we should talk in Dresden about it. Maybe @brownbaerchen would like to give a talk about the future pf pySDC to set the stage?

[brownbaerchen]

I fully understand why Martin does not want to use pySDC for easy tests. I agree that a code that is simpler than pySDC is not a bad idea. Generally, I think the contents of this PR are good. However, I really think the two goals for qmat you mention above are kind of unrelated and therefore would benefit from having their own repositories. In particular, the new playgrounds are not part of either goal. They are part of a third goal, which is new SDC research.

qmat should be the repository that every SDC code uses to get the coefficients for $Q$ and the latest $Q_\Delta$ and a separate repository can be used to teach newcomers about SDC and to do experiments like the $\phi$ stuff. Yes, pySDC currently promises to do the latter, but its position in the market could shift to being the bigger code that you use for PDE experiments and PFASST and so on. Because that's what it is, no matter what we claim. Proof by example of Martin not wanting to use it :D

[tlunet]

Ok, argument heard (and accepted 😉). So I could create an additional repository qmat-playground, where would be moved : (or qplay, qmatplay, qmatapp, qmatexp, ...)

• all base tutorials on how to use the $Q$ and $Q_\Delta$ coefficients for time-integration (3 at the moment)
• all potential scripts using qmat for quick investigation of stability, accuracy, etc ... (in scripts)
• all advanced tutorials on node-to-node, non-linear problem, $\phi$-SDC, etc ...
• the qmat.playgrounds an qmat.solvers module

In qmat would stay :

• qmat.qcoeff, qmat.qdelta, qmat.nodes, qmat.lagrange, qmat.mathutils and qmat.utils
• the original qmat.sdc module used to test the $Q_\Delta$ coefficients and to store the theoretical SDC orders

If this looks good on your side, I would suggest the following steps :

1. merge this PR once it's finalized
2. merge Martin's PR once it's finalized
3. create the new qmat-playground repo, setup it's documentation / CI testing and coverage / Pypi packaging
4. move all selected content from qmat to qmat-playground, through 1 PR on each repo
5. bump qmat and qmat-playground to version 1.0.0

Of course, step 1 and 2 could be done quickly, while 3, 4, and 5 would need a bit more time (and I would focus on it during my next train travel). What do you think ?