Document what "coercion" is (perhaps also in contrast to promotion)

[fingolfin]

I am confused as to what the relation between "coercion" and "promotion" in AA is supposed to be. As far as I could tell, it is not defined anywhere? Yes, I can guess; yes, I am familiar with the notion of coercion from other projects; but I think it should be defined.

For now I wonder: Are they intended as synonyms? Or perhaps AA wants to avoid "promotion" to make it clear that this differs from promotions in Julia (but then shouldn't this be stated explicitly somewhere? Perhaps it is and I just overlooked it?)

As far as I can tell, the Julia manual only seems to talk about "promotion", no mention of "coerce" or "coercion" is in there. Searching the AA manual for "coercion" yields three sections (for modules and for permutation groups, but e.g. not for rings); searching for "promotion" yields a bunch of hits, including https://nemocas.github.io/AbstractAlgebra.jl/latest/rings/#Promotion-rules and the almost identical https://nemocas.github.io/AbstractAlgebra.jl/latest/ncrings/#Promotion-rules (why this duplication???) which talks about "promotion rules" for use in "coercion" but without ever really explaining

[wbhart]

It's just semantic. Julia uses the word promotion (promote_rule). We use that mechanism for coercion (taking a value which can be exactly represented in some other ring/field/etc and putting it into that ring/field/etc).

[wbhart]

I'm really not sure what to add, or where. Do you really want me to write somewhere that "coercion is to mathematical structures as promotion is to types"? It's not really any clearer is it?

Perhaps if you can be more specific about what you actually want here, or did I answer your question.

The problem is, coercion is not well-defined in general.

[wbhart]

What I could do is write a section somewhere on the AbstractAlgebra/Nemo coercion philosophy. Some years ago we put a moratorium on complex coercion (with some very limited exceptions, e.g. substitution of polynomials) until the system was sophisticated enough to warrant adding a proper coercion system.

• Simple coercion example: Z + Z[x] -> Z[x] (promotion suffices)
• Complex coercion example: Q + Z[x] -> Q[x]

Magma and Sage both have complex coercion systems, both of which have documented deficiencies.