Refactor DDt hierarchy: variable-dt BDF, auto-init, effective order

docs/api/systems_ddt.md

@@ -5,40 +5,65 @@
    :no-members:
 ```
 
-## Lagrangian Derivatives
+Time derivative operators approximate $D\phi/Dt$ or $DF/Dt$ for transient
+solvers.  All operators share a common interface: ``update_pre_solve(dt)``
+before each timestep, ``bdf()`` for the BDF approximation in the weak form,
+and ``update_post_solve(dt)`` after the solve completes.
+
+History is initialised automatically on the first solve call, and BDF order
+ramps from 1 up to the requested ``order`` over the first few timesteps.
 
-### Lagrangian_DDt
+## Base Class
+
+### Symbolic
 
 ```{eval-rst}
-.. autoclass:: underworld3.systems.ddt.Lagrangian_DDt
+.. autoclass:: underworld3.systems.ddt.Symbolic
    :members:
    :show-inheritance:
 ```
 
-### SemiLagrangian_DDt
+## Eulerian Derivatives
+
+### Eulerian
 
 ```{eval-rst}
-.. autoclass:: underworld3.systems.ddt.SemiLagrangian_DDt
+.. autoclass:: underworld3.systems.ddt.Eulerian
    :members:
    :show-inheritance:
 ```
 
-## Eulerian Derivatives
+## Lagrangian Derivatives
 
-### Eulerian_DDt
+### SemiLagrangian
 
 ```{eval-rst}
-.. autoclass:: underworld3.systems.ddt.Eulerian_DDt
+.. autoclass:: underworld3.systems.ddt.SemiLagrangian
    :members:
    :show-inheritance:
 ```
 
-## Flux History (Viscoelastic)
+### Lagrangian
 
-### Lagrangian_Flux_DDt
+```{eval-rst}
+.. autoclass:: underworld3.systems.ddt.Lagrangian
+   :members:
+   :show-inheritance:
+```
+
+### Lagrangian_Swarm
 
 ```{eval-rst}
-.. autoclass:: underworld3.systems.ddt.Lagrangian_Flux_DDt
+.. autoclass:: underworld3.systems.ddt.Lagrangian_Swarm
    :members:
    :show-inheritance:
 ```
+
+## Convenience Aliases
+
+The following aliases are available via ``underworld3.systems``:
+
+- ``Lagrangian_DDt`` → {class}`~underworld3.systems.ddt.Lagrangian`
+- ``SemiLagragian_DDt`` → {class}`~underworld3.systems.ddt.SemiLagrangian`
+- ``Lagrangian_Swarm_DDt`` → {class}`~underworld3.systems.ddt.Lagrangian_Swarm`
+- ``Eulerian_DDt`` → {class}`~underworld3.systems.ddt.Eulerian`