Documentation on monomial orderings

[thofma]

At some point in time, Dan introduced the following important piece of information in the documentation (important for people who not want to write slow code):

!!! note
    As the above functions take an arbitrary ordering, they are much slower than
    the versions from AbstractAlgebra, which use the natural ordering in the
    parent polynomial ring: `default_ordering(parent(f))` is not necessarily
    this natural ordering. If this ordering of the parent is desired, or if the
    ordering is not important, it is recommended to use the following.
    - `AbstractAlgebra.coefficients(f)`
    - `zip(AbstractAlgebra.coefficients(f), AbstractAlgebra.exponent_vectors(f))`
    - `AbstractAlgebra.exponent_vectors(f)`
    - `AbstractAlgebra.monomials(f)`
    - `AbstractAlgebra.terms(f)`
    - `AbstractAlgebra.leading_coefficient(f)`
    - `AbstractAlgebra.leading_exponent_vector(f)`
    - `AbstractAlgebra.leading_monomial(f)`
    - `AbstractAlgebra.leading_term(f)`

It appears that this was removed in #1760. @wdecker @ederc not sure if this was on purpose? If so, do you mind if we reintroduce it? Maybe in the developer documentation part?

[wdecker]

It appears that this was removed in #1760. @wdecker @ederc not sure if this was on purpose? If so, do you mind if we reintroduce it? Maybe in the developer documentation part?

I removed this since I found it very confusing for the average user, in particular since the wording is not accurate enough. On the other hand, it might indeed be important for developers. But not every developer will read the developer documentation part if he is just interested in monomial orderings. So how about adding something like !!! note for developers to !!! note, !!! warning, and friends so that informaton like the one considered here can be entered at the right spot.

[fieker]

we try to have @wdecker deal with it

[jo-ap]

A (hopefully helpful) comment from the user side. I needed to obtain symbolic polynomials as Julia functions (for later use with numeric input), which i managed to get working like so:

julia> R, (x, y, z) = polynomial_ring(QQ, ["x", "y", "z"]);

julia> f = x*y*z - y^3;

julia> f_julia = u -> sum([c*prod(u.^a) for (c, a) in coefficients_and_exponents(f)]);

julia> f_julia([x,y,z]) 
x*y*z - y^3

This seems to do the trick. However, the difficult part was gathering the information from the documentation.
First, I looked at the section in Rings > Multivariate Polynomials, which only mentions the use of coefficients and exponent_vectors. The latter is not exported (I'm using v1.2.2), but you can of course specify the module. However, this means the orderings differ:

julia> sum([c*prod([x,y,z].^a) for (c, a) in zip(coefficients(f), AbstractAlgebra.exponent_vectors(f))])
-x*y*z + y^3

Using AbstractAlgebra.coefficients resolves this issue, but to me it seems really easy to shoot yourself in the foot if there is no note in the docs about what ordering is used.
Only by looking at the source code I found the functions exponents and coefficients_and_exponents. Their usage is demonstrated in the section Gröbner/Standard Bases Over Fields. I guess it would be nice to have all of these utility functions documented in one spot or at least to include a cross reference. Maybe some word of caution is also helpful, because I suspect not every user knows or wants to check what's going on under the hood.

[joschmitt]

The particular problem here is that we import documentation from AbstractAlgebra which mentions functions that have a different name in OSCAR. 🤦 @jo-ap Thanks for pointing this out!

Can we make exponent_vectors an alias for exponents in AbstractAlgebra or is there a deeper reason for the name change that I don't see?

[thofma]

Some breadcrumbs:

• That we have in Oscar exponents but not exponent_vectors was noticed here unify iterators for univariate and multivariates and provide an automatic zipper Nemocas/AbstractAlgebra.jl#1229
• So yes, probably we can do this exponents alias.
• Maybe we should add AbstractAlgebra.coefficients_and_exponents.