Asking for advice: differential operators in the global namespace

[Eric Gourgoulhon]

Hi,

In Trac #24622, the standard differential operators gradient, divergence, curl, Laplacian and d'Alembertian are introduced on pseudo-Riemannian manifolds. A demo worksheet is here.
In particular, these operators are involved in the elementary vector calculus implemented in the subsequent ticket #24623, as illustrated in this other demo worksheet.

To cope with standard mathematical notations, these operators are introduced as functions in the global namespace, which merely invoke the corresponding method of their argument, e.g. if v is a vector field,

sage: div(v)

returns the divergence of v computed as v.divergence().

Is it OK to introduce five new names in the global namespace:
grad, div, curl, laplacian, dalembertian
and possibly a sixth one: rot as an alias of curl?

An alternative (disapproved by the reviewer) is to inject these names in the global namespace only if any pseudo-Riemannian manifold is constructed, by means of the function sage.repl.user_globals.set_global in PseudoRiemannianManifold.__init__, see line 398 of
this source file.

Thank you for your feedback.

Eric.

[Kwankyu Lee]

Is it OK to introduce five new names in the global namespace:
grad, div, curl, laplacian, dalembertian
and possibly a sixth one: rot as an alias of curl?

-1

 

An alternative (disapproved by the reviewer) is to inject these names in the global namespace only if any pseudo-Riemannian manifold is constructed, by means of the function sage.repl.user_globals.set_global in PseudoRiemannianManifold.__init__, see line 398 of
this source file.

-1

From the ticket:

Some other thoughts that come to my mind is a function like setup_manifolds_environment and/or getting people who use SageManifolds to have a specific section to their .sage/init.sage file.

+1 with the provision that the function `setup_manifolds_environment` itself is not in the global namespace but in the package `sage.manifolds`.

[Simon King]

Hi Eric,

On 2018-03-03, Eric Gourgoulhon <egourg...@gmail.com> wrote:
> To cope with standard mathematical notations, these operators are
> introduced as functions in the global namespace, which merely invoke the
> corresponding method of their argument, e.g. if v is a vector field,
>
> sage: div(v)

What's wrong with v.div(), to cope with standard notation in SageMath?

"div", as a notation for "divergence", could also easily be mistaken
with "division", "divisor", or also "dividend" (IIRC, there *is* some
mathematical finance in SageMath).

Also one should be aware that "standard mathematical notation" is
usually strongly dependent on context. Here is a little anecdote: In
some test, I gave my students the little problem "What is the definition
of the order of a group element?". Surprisingly many of them gave the
definition of an order relation. So, in the next homework, I asked them
to do a little research and find as many different mathematical notions
that are named "order". I think they found more than 10.

Conclusion: Functions in the global name space lack context, and are thus
often unsuited for mathematical notations.

And even if you absolutely want to put divergence into the global name
space (which already is too much bloated, IMHO), then I think it would
still be a bad idea to put an *abbreviated* function name into the global
name space ("div" instead of "divergence") just because in *some* branch
of mathematics that abbreviation is standard.

> Is it OK to introduce five new names in the global namespace:
> grad, div, curl, laplacian, dalembertian
> and possibly a sixth one: rot as an alias of curl?

-1

> An alternative (disapproved by the reviewer) is to inject these names in
> the global namespace only if any pseudo-Riemannian manifold is constructed,

-1

Again, what is wrong with the Python standard notation v.div(), where v
is a vector field? Since v.div is a method of a vector field, it
automatically adds the context that were missing if div() was a global
function.

Best regards,
Simon

[Vincent Delecroix]

Hi Eric,

I agree with Kwankyu and Simon:
- the global namespace is already bloated
- abbreviations should be avoided in most places in Sage

And having the namespace modified at the time an object is created is by
far the worst solution.

The following two alternatives would be fine

1) using member functions (methods): ie v.div() instead of div(v)

2) having a module containing all of your abbreviations so that
{{{
sage: from sage.manifolds.operators import *
}}}
would give access to these abbreviations in the namespace. You might
want to import this module in the namespace as "manifolds" so that the
user can do
{{{
sage: manifolds.div(v)
}}}
This is what was done to simplfy the global namespace with
sage.codings.codes_catalog.

Vincent

[Eric Gourgoulhon]

 

An alternative (disapproved by the reviewer) is to inject these names in the global namespace only if any pseudo-Riemannian manifold is constructed, by means of the function sage.repl.user_globals.set_global in PseudoRiemannianManifold.__init__, see line 398 of
this source file.

-1

I'm also -1 for this, after the argument given by Travis on the ticket: injecting silently names in the global namespace may override names already defined by the user. Initially, I naively thought this was a good way to avoid cluttering the global namespace of a generic Sage session.

[Eric Gourgoulhon]

Hi Simon,

Le dimanche 4 mars 2018 08:25:09 UTC+1, Simon King a écrit :

What's wrong with v.div(), to cope with standard notation in SageMath?

Nothing from my point of view: I also prefer object-oriented notations over functional ones and v.div() is already implemented in the ticket (as an alias for v.divergence()). However, I had in mind users who want to use Sage for elementary vector calculus. For them, div(v) is more natural than v.div(), like cos(x) instead of x.cos().
 

"div", as a notation for "divergence", could also easily be mistaken
with "division", "divisor", or also "dividend" (IIRC, there *is* some
mathematical finance in SageMath).

Also one should be aware that "standard mathematical notation" is
usually strongly dependent on context.

Yes I agree.
 

Here is a little anecdote: In
some test, I gave my students the little problem "What is the definition
of the order of a group element?". Surprisingly many of them gave the
definition of an order relation. So, in the next homework, I asked them
to do a little research and find as many different mathematical notions
that are named "order". I think they found more than 10.

Thanks for this anecdote.

Conclusion: Functions in the global name space lack context, and are thus
often unsuited for mathematical notations.

I agree.
 

And even if you absolutely want to put divergence into the global name
space (which already is too much bloated, IMHO), then I think it would
still be a bad idea to put an *abbreviated* function name into the global
name space ("div" instead of "divergence") just because in *some* branch
of mathematics that abbreviation is standard.

I already did this for the method: divergence() is the true method and div() is a mere alias.
 
Best regards,

Eric.

[Eric Gourgoulhon]

Hi Vincent,

Le dimanche 4 mars 2018 11:35:04 UTC+1, vdelecroix a écrit :

Hi Eric,

I agree with Kwankyu and Simon:
- the global namespace is already bloated
- abbreviations should be avoided in most places in Sage

Thanks for your feedback.
 

And having the namespace modified at the time an object is created is by
far the worst solution.

As I said in the reply to Kwankyu, I am also fully convinced of this.
 

The following two alternatives would be fine

1) using member functions (methods): ie v.div() instead of div(v)

2) having a module containing all of your abbreviations so that
{{{
sage: from sage.manifolds.operators import *
}}}
would give access to these abbreviations in the namespace.

This is actually the case in the ticket: all the operators as functions are in a dedicated module, so that one can do
sage: from sage.manifolds.differentiable.operators import *

You might
want to import this module in the namespace as "manifolds" so that the
user can do
{{{
sage: manifolds.div(v)
}}}
This is what was done to simplfy the global namespace with
sage.codings.codes_catalog.

Thanks for the suggestion, but from the end user who wants to perform elementary vector calculus,  manifolds.div(v) looks even more complicated than v.div(). So maybe, we should stick with the postfix notation and ofter the possibility to
import by hand the operators module.

Best regards,

Eric.

[Nils Bruin]

On Sunday, March 4, 2018 at 10:58:32 AM UTC, Eric Gourgoulhon wrote:

I'm also -1 for this, after the argument given by Travis on the ticket: injecting silently names in the global namespace may override names already defined by the user. Initially, I naively thought this was a good way to avoid cluttering the global namespace of a generic Sage session.

It's actually worse than that: At runtime, it's not even clear if there a unique "global" namespace, so (apart from the fact that clobbering a namespace is a bad idea), you'd even have a hard time getting a hold of the appropriate namespace to clobber.

I'd subscribe to the advice of guiding your users to use "from sage.manifolds.operators import *" or something similar. Defining a function to do this is tricky for the reason mentioned above (and getting access to the function would require an import anyway). 

[Eric Gourgoulhon]

Thank you all for your answers!

The conclusion is pretty clear: the differential operators will *not* be added to the global namespace at start, even less be added silently when a pseudo-Riemannian manifold is constructed. The only way to get them will be an explicit demand from the user, in the form of a Python import:
from sage.manifolds.operators import *
or even more explicitly:
from sage.manifolds.operators import grad, div, curl, laplacian
It seems pretty safe to keep the standard notations here (i.e. "grad" instead of "gradient" and "div" instead of "divergence"), because the context of the import is clearly that of differential geometry. If for some reason, the name "div" was already used, it remains possible to do
from sage.manifolds.operators import div as divergence.

Eric.