Operator interface

[thomasgibson]

@alexfikl brought up a great point about the current operator interface: #172 (comment)

As already pointed out, grudge operators typically have a function signature like: operator(dcoll, *args), such as:

grudge/grudge/op.py

Line 437 in 2af3528

def weak_local_div(dcoll: DiscretizationCollection, *args):

The issue here is that we're not quite enforcing anything on *args. So, for example, if a user passes in (vec, dd) (instead of the expected (dd, vec) ordering), the code will break without actually catching this problem. Currently, we have the docstrings elaborate on *args, such as:

grudge/grudge/op.py

Lines 438 to 441 in 2af3528

	r"""Return the element-local weak divergence of the vector volume function
	represented by *vecs*.
	May be called with ``(vecs)`` or ``(dd, vecs)``.

We could strengthen the checks inside each function. However, I can see this becoming a bit unwieldy. We could also revamp the interface and impose a fixed signature for each function (meaning we always require args: dcoll, dd, vec --- no more *args).

I thought I'd raise this issue so we can discuss this. I don't think this is a huge problem right now, but definitely worth noting.

[inducer]

I think I'm OK with deprecating the version without the dd. The one downside I see is that grad(dcoll, "vol", vec) is a wee bit noisier than without, but I think it's not too bad. And given @majosm's multi-domain support coming down the pike, being more picky about the intended domain being specified is probably a good thing overall.

[inducer]

Quoting @alexfikl:

Even now it will fail in an unexpected way if it gets (vec, dd_in) by mistake.

How come as_dofdesc doesn't complain? (And can we fix that centrally by improving the checks there?)

[alexfikl]

How come as_dofdesc doesn't complain? (And can we fix that centrally by improving the checks there?)

It should, yeah. My point was that "domain tag not understood: DOFArray(...)" is a sligtly weird error to get if the arguments in the call are swapped.

In general, the complaint was just that parsing *args is a bit opaque vs having some nice explicit function arguments. My preference would have been for grad(dcoll, vec, dd=dofdesc), but maybe that's just from working with pytential too much.

[inducer]

In general, the complaint was just that parsing *args is a bit opaque vs having some nice explicit function arguments. My preference would have been for grad(dcoll, vec, dd=dofdesc), but maybe that's just from working with pytential too much.

The interface in grudge is actually a direct reaction to the one in pytential. For things like operators, the thing being operated on (the "what") is typically another expression, which means that it can validly be long and fairly deeply nested. So I find it easier if all the "how" arguments come before the "what" and not "some 'how' before, then the 'what', and then some more 'how' keyword args after".