Improve setupPromote documentation

[d-torrance]

The setupPromote docs currently only mention setupPromote(RingMap), but there are 5 more methods to mention!

[pzinn]

Good point. For the record, most are small variations on the same functionality: the inclusion of the source/target of the map is just a convenience for coding; one can explicitly provide a degree map; and finally one can use a function rather than a ring map (this might seem weird, but there's at least one case where it's not easy to make the map explicit -- see enginering.m2 L322 -- and this is the best workaround I could find).

[d-torrance]

I'm confused -- in addition to promote(R, S), setupPromote also defines methods for:

• promote(List, R, S)
• promote(Module, R, S)
• promote(Matrix, R, S)
• promote(MutableMatrix, R, S)

What are these methods supposed to do? Only the two-argument promote is documented. And the currently installed ones don't seem to do what you'd expect:

i1 : promote({1,2,3}, ZZ, RR_53)

o1 = {1, 2, 3}

o1 : List

i2 : class \ oo

o2 = {ZZ, ZZ, ZZ}

o2 : List

[pzinn]

Excellent questions! but let me point out that the existence of such methods has nothing to do with setupPromote: this is already how promote worked before setupPromote was introduced, see e.g., commonRingInitializations in enginering.m2.
Now to answer your question, the obscure one promote(List, R, S) is actually for degrees, see e.g., line 86 of ringmap.m2.
I wish it was clearer -- maybe degrees should have their own class?

[pzinn]

Also, maybe (some of) these methods can be dispensed with -- we should probably take a closer look at where in the code they're actually used.

[d-torrance]

Ah, okay. Looking at the code, we have things like this:

promote(Matrix,RingElement) := 
promote(Matrix,Number) := Matrix => (f,S) -> (
     R := ring f;
     if R === S then return f;
     if not isFreeModule target f or not isFreeModule source f then error "promote: expected source and target to be free modules";
     promote(f, R, S))

So users almost certainly wouldn't call something like promote(f, R, S) directly, but they definitely might call promote(f, S), which (if f is a matrix over R) would call this.

[pzinn]

I wonder why we need to impose that source f and target f are free modules. Same question with promote(Module,RingElement). In the example below, if i5 works, why not i6?

i1 : R=QQ[x_1,x_2]; R'=QQ[e_1,e_2]; setupPromote map(R,R',{x_1+x_2,x_1*x_2})

i4 : M=R'^1/e_2

o4 = cokernel | e_2 |

                              1
o4 : R'-module, quotient of R'

i5 : M ** R

o5 = cokernel | x_1x_2 |

                            1
o5 : R-module, quotient of R

i6 : promote(M,R)
stdio:4:7(3): error: promote: expected module to be free

[d-torrance]

Is there a good example of when specifying the degree map in setupPromote is useful?

[pzinn]

not that I can think of. see also this comment in enginering.m2:

-- TODO improve this, or deprecate promote/lift(List,R,S)
defaultDegMap := (R,S) -> (