A ring element can often be coerced into a ring other than its parent. The need for this occurs for example when one wants to perform a binary ring operation on elements of different structures, or when an intrinsic function is invoked on elements for which it has not been defined.
The basic principle is that such an operation may be performed whenever it makes sense mathematically. Before the operation can be performed however, an element may need to be coerced into some structure in which the operation can legally be performed. There are two types of coercion: automatic and forced coercion. Automatic coercion occurs when Magma can figure out for itself what the target structure should be, and how elements of the originating structure can be coerced into that structure. In other cases Magma may still be able to perform the coercion, provided the target structure has been specified; for this type of coercion R ! x instructs Magma to execute the coercion of element x into ring R.
The precise rules for automatic and forced coercion between rings are explained in the next two subsections. It is good to keep an important general distinction between automatic and forced coercion in mind: whether or not automatic coercion will succeed depends on the originating and the target structure alone, while for forced coercion success may depend on the particular element as well. Thus, integers can be lifted automatically to the rationals if necessary, but conversely, only the integer elements of Q can be coerced into Z by using !.
The subsections below will describe for specific rings R and S in Magma whether or not an element r of R can be lifted automatically or by force into S. Suppose that the unary Magma function Function takes elements of the type of S as argument and one is interested in the result of that function when applied to r. If R can be coerced automatically into a unique structure S of the desired type, then Function(r) will produce the required result. If R cannot be coerced automatically into such S, but forced coercion on r is possible, then Function(S ! r) will yield the desired effect. If, finally, neither automatic nor forced coercion is possible, it may be possible to define a map m from R to S, and then Function( m(r) ) will give the answer.
For example, the function Order is defined for elements of residue class rings (among others). But Order(3) has no obvious interpretation (and an error will arise) because there is not a unique residue class ring in which this should be evaluated.
If a binary operation : C x C -> C on members C of a category of rings (C) is applied to elements r and s of members R and S from (C), the same rules for coercion will be used to determine the legality of r s. If s can be coerced automatically into R, then this will take place and r s will be evaluated in R; otherwise, if r can be coerced automatically into S, then r s will be evaluated in S. If neither succeeds, then, in certain cases, Magma will try to find an existing common overstructure T for R and S, that is, an object T from (C) such that ⊂T⊃S; then both r and s will be coerced into T and the result t=r s will be returned as an element of T. If none of these cases apply, an error results. It may still be possible to evaluate by forced coercion of r into S or s into R, using (S ! r) o s or using r o (R ! s).
We will first deal with the easier of the two cases: automatic coercion. A simple demonstration of the desirability of automatic coercion is given by the following example:
1 + (1/2);
It is obvious that one wants the result to be 3/2: we want to identify the integer 1 with the rational number 1 and perform the addition in Q, that is, we clearly wish to have automatic coercion from Z to Q.
The basic rule for automatic coercion is: automatic coercion will only take place when there exists a unique target structure and an obvious homomorphism from the parent structure to the target structure In particular, if one structure is naturally contained in the other (and Magma knows about it!), automatic coercion will take place. (The provision that Magma must know about the embedding is in particular relevant for finite fields and number fields; in these cases it is possible to create subrings, or even isomorphic rings/fields, for which the embedding is not known.)
Also, for any ring R there is a natural ring homomorphism Z -> R, hence any integer can be coerced automatically into any ring.
See the (pdf) Handbook for a table detailing the rules for automatic coercion. It is appropriate here to make some general remarks only.
Integers will be automatically coerced into any ring, and rationals into any ring except a finite field or a residue class ring.
Operations involving elements of real or complex fields of different precisions automatically coerce the numbers into the field with the higher precision.
Elements of different finite field elements can be operated upon with automatic coercion only if one field is a subset of the other or both fields have been created inside another finite field.
In addition to these rules, general rules apply to polynomial and matrix algebras. The rules for polynomial rings are as follows. An element s from a ring S can be automatically coerced into R[X1, ..., Xn] if either S equals R[X1, ..., Xi] for some 1≤i≤n, or S=R. Note that in the latter case the element s must be an element of the coefficient ring R, and that it is not sufficient for it to be coercible into R.
So, for example, we can add an integer and a polynomial over the integers, we can add an element f of Z[X] and g of Z[X, Y], but not an integer and a polynomial over the rationals.
An element s can be coerced automatically in the matrix ring Mn, n(R) if it is coercible automatically into the coefficient ring R, in which case s will be identified with the diagonal matrix that has each diagonal entry equal to s.
So we can add an integer and a matrix ring element over the rationals, but we cannot automatically add elements of Mn, n(Z) and Mn, n(Q), nor elements from M2, 2(Z) and M3, 3(Z).
In certain cases where automatic coercion will not take place, one can cast an element into the ring in which the operation should take place.
If, for example, one is working in a ring Z/pZ, and p happens to be prime, it may occur that one wishes to perform some finite field operations on an element in the ring; if F is a finite field of characteristic p an element x of Z/pZ can be cast into an element of F using F ! x;
See the (pdf) Handbook for a table detailing the rules for non-automatic coercion. It is appropriate here to make some general remarks only.
Non-automatic coercion may only apply to certain elements of the domain; thus only those elements of Q can be coerced into Z that are in fact integers. Similarly, if an element of a quadratic field with a negative discriminant is to be coerced into a real field then it must correspond to a complex number with no imaginary part.
An element from Fps can only be coerced into Z/mZ if s=1 and m=p.
Any element from Fps can be coerced into Fpr if s divides r, and otherwise only a subset of the field is coercible. Similarly for cyclotomic fields.
The rules for coercion from and to polynomial rings and matrix rings are as follows.
If an attempt is made to forcibly coerce s into P=R[X1, ..., Xn], the following steps are executed successively:
The ring element s can be coerced into Mn, n(R) if either it can be coerced into R (in which case s will be identified with the diagonal matrix with s on the diagonal), or s∈S=Mn, n(R'), where R' can be coerced into R. Also a sequence of n2 elements coercible into R can be coerced into the matrix ring Mn, n(R).
Elements from a matrix ring Mn, n(R) can only be coerced into rings other than a matrix ring if n=1; in that case the usual rules for the coefficient ring R apply.
Note that in some cases it is possible to go from (a subset of) some structure to another in two steps, but not directly: it is possible to go
> y := L ! (Q ! x)
to coerce a rational element of one number field into another via the rationals.
Finally we note that the binary Boolean operator in returns true if and only if forced coercion will be successful.