AdvDiffusion is not a positional drop-in for AdvDiffusionSLCN, and NavierStokesSwarm is the same class as NavierStokesSLCN

[lmoresi]

Two API problems from #688, found in review and not filed before the merge.

Positional arguments diverge at argument 5

docs/advanced/eulerian-advection-diffusion.md advertises the swap as one line:

adv = uw.systems.AdvDiffusion(mesh, T, v.sym, order=1)   # was AdvDiffusionSLCN

That is safe with keywords. Positionally the two signatures part company at argument 5:

AdvDiffusion       ['mesh', 'u_Field', 'V_fn', 'order', 'theta', 'peclet_weight', 'verbose', 'DuDt']
AdvDiffusionSLCN   ['mesh', 'u_Field', 'V_fn', 'order', 'restore_points_func', 'verbose', 'DuDt', 'DFDt']

A call that passed restore_points_func positionally to AdvDiffusionSLCN gives that value to theta on AdvDiffusion. A float lands silently; a callable would probably fail somewhere well away from the call site. Argument 6 then swaps verbose and peclet_weight, which is float against bool and also silent.

Options: make everything after V_fn keyword-only on both, or align the orders. Keyword-only is the smaller change and matches how the docs already show them.

NavierStokesSwarm and NavierStokesSLCN are the same class

>>> uw.systems.NavierStokesSwarm is uw.systems.NavierStokesSLCN
True

Both are bound in systems/__init__.py:

from .solvers import SNES_NavierStokes as NavierStokesSwarm
from .solvers import SNES_NavierStokes as NavierStokesSLCN

Two public names for one class, and the names promise different transport. Someone reaching for NavierStokesSwarm because their model carries particles gets the semi-Lagrangian solver and no indication of it. Either one name is wrong and should go, or the swarm variant it names does not exist yet and the alias should not either.

Neither is urgent, and neither breaks a keyword-argument call.

Underworld development team with AI support from Claude Code