"diffeq" package structure

[pnkraemer]

Tagging @nathanaelbosch @schmidtjonathan @JonathanWenger, but if others have something to share, please don't hesitate to do so.

Hi! Last week, @JonathanWenger and had a chat about changing the package structure in diffeq a little bit. The goal woud be to unify the diffeq API with the structure in the remaining packages (linalg and quad had a few fairly drastic refactorings recently).
Since the diffeq functionality has been growing quite a lot, I think it is a good idea to restructure and organise a bit.

The main advantages would be roughly threefold:

• Communicate more clearly, what a PertubedSomethingSolver is, and distinguish it from the filtering-based solvers.
• Improve clarity of which components belong together by using more "aggressive" namespaces
• Let functions such as probsolve_ivp stand out more, by leaving it as one of the very few items in top-level (in terms of telling a user "you are probably looking for this one").

I think this is a good idea. @schmidtjonathan, we discussed something like these with @NinaEffenberger recently.

My ad-hoc proposal would be something along the lines of:

from probnum import diffeq

diffeq.probsolve_ivp()
diffeq.perturbsolve_ivp()  # new (Nina)

diffeq.odefiltsmooth.ProbabilisticODESolver()  # name debatable
diffeq.odefiltsmooth.ProbabilisticODESolution()  # name debatable
diffeq.odefiltsmooth.initialize.RungeKuttaInitialization()
diffeq.odefiltsmooth.initialize.TaylorModeInitialization()
diffeq.odefiltsmooth.information_operators.EK0() # new
diffeq.odefiltsmooth.information_operators.EK1()  # new


diffeq.perturbed.step.PerturbedStepSolver()
diffeq.perturbed.step.PerturbedStepSolution()
diffeq.perturbed.step.PerturbedStepRule()
diffeq.perturbed.step.perturb_uniform()
diffeq.perturbed.step.perturb_lognormal()

diffeq.perturbed.state.PerturbedStateSolver()  # new (Nina)
diffeq.perturbed.state.PerturbedStateSolution()  # new (Nina)

diffeq.steprule.ConstantSteps()
diffeq.steprule.AdaptiveSteps()

diffeq.interface.ODESolver()
diffeq.interface.ODESolution()
diffeq.interface.scipy.WrappedScipyODESolver()
diffeq.interface.scipy.WrappedScipyODESolution()

Random side notes:

• The main difference to the current state would be that the import path

diffeq.perturbed.state

communicates where in the world of PN methods the Conrad et al. algorithm can be placed

• It is not absolutely clear to me how to treat e.g. BVP solvers (but this can be sorted out I think). One solution would be to introduce even deeper packages such as diffeq.odefiltsmooth.ivp.andsoon, as well as diffeq.odefiltsmooth.bvp.etcetera and move from there. This may be too deep a structure, but some solution will exist, surely.

[JonathanWenger]

I would suggest to not necessarily have initialization classes but rather make them (part of) classmethods (i.e. constructors) for ProbabilisticODESolver.

[pnkraemer]

The way this is currently handled is that the initialisation strategy is passed to the constructor as a callable (with appropriate input). Shortcuts to specific choices of initialisation (i.e. Runge-Kutta init, or Taylor-mode init) are provided via classmethods. I like this approach and would keep it, unless there is a clear advantage to the only-classmethod approach.

The debatable thing here is (IMO) whether it needs to be a class. In principle, a callable would suffice (I guess), but a class would make it easier to force an interface (e.g. with an abstract base class).

[pnkraemer]

See #477 which implements some of these things. :)

[pnkraemer]

There is also #486, which implements information operators and approximations thereof.

[pnkraemer]

#490 Unifies initialization routines (and tests thereof).