Generic Element Functions

Parent and Category

Parent(r): RngElt -> Rng

The (default) parent ring of ring element \(r\). Usually the parent of \(r\) has been created explicitly before, but in certain cases, such as literal integers, rationals, reals, and values returned by certain functions a default parent is created in the background.

Category(r): RngElt -> Cat

Type(r): RngElt -> Cat

The ‘type’ of \(r\), that is, the Magma category to which the ring element \(r\) belongs. The procedure call ListCategories() gives a list of all the categories, as does the Appendix.

Creation of Elements

Zero(R): Rng -> RngElt

The zero element of ring \(R\); this is equivalent to R ! 0.

One(R): Rng -> RngElt

Id(R): Rng -> RngElt

The multiplicative identity \(1\) of ring \(R\); this is equivalent to R ! 1.

R ! a: Rng, RngElt -> RngElt

Coerce the element \(a\) of some ring into the ring \(R\). (The rules on coercion are explained earlier in this Chapter.) If \(a\) is an integer, the coercion will always succeed: the element \(a\cdot 1_R\) will be returned, where \(1_R\) is the unit element of \(R\).

Random(R): Rng -> RngElt

A random element of the finite ring \(R\) (every element of \(R\) has the same probability of being returned).

Representative(R): Rng -> RngElt

Rep(R): Rng -> RngElt

A representative element of the finite ring \(R\).

Arithmetic Operations

+ a: RngElt -> RngElt

Element \(a\).

- a: RngElt -> RngElt

The negation (additive inverse) of element \(a\).

a + b: RngElt, RngElt -> RngElt

The sum of the ring elements \(a\) and \(b\); if \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the sum can be taken.

a - b: RngElt, RngElt -> RngElt

The difference of the ring elements \(a\) and \(b\); if \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the difference can be taken.

a * b: RngElt, RngElt -> RngElt

The product of the ring elements \(a\) and \(b\); if \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the product can be taken.

a ^ k: RngElt, RngIntElt -> RngElt

Form the \(k\)-th power of the ring element \(a\), for small \(k\). If \(k = 0\), then \(a^k\) returns \(1\), even when \(a = 0\). If \(k\) is negative, \(a\) must have a multiplicative inverse and the result is \((a^{-1})^{-k}\).

a / b: RngElt, RngElt -> RngElt

Given an element \(a\) of \(R\) and a unit \(b\) of \(R\), form the quotient of the elements \(a\) and \(b\). If \(b\) is not invertible in \(R\), an error results, unless both \(a\) and \(b\) are integers, in which case a / b returns the rational number \(a/b\). If \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the quotient can be taken.

a +:= b: RngElt, RngElt -> RngElt

Mutation assignment: change \(a\) into the sum of \(a\) and \(b\).

a -:= b: RngElt, RngElt -> RngElt

Mutation assignment: change \(a\) into the difference of \(a\) and \(b\).

a *:= b: RngElt, RngElt -> RngElt

Mutation assignment: change \(a\) into the product of \(a\) and \(b\).

a /:= b: RngElt, RngElt -> RngElt

Mutation assignment: change \(a\) into the quotient of \(a\) and \(b\).

a ^:= k: RngElt, RngIntElt -> RngElt

Mutation assignment: change \(a\) into the power \(a^k\).

Equality and Membership

a eq b: RngElt, RngElt -> BoolElt

Returns true if the elements \(a\) and \(b\) of \(R\) are the same, otherwise false.

a ne b: RngElt, RngElt -> BoolElt

Returns true if the elements \(a\) and \(b\) of \(R\) are distinct, otherwise false.

R eq S: Rng, Rng -> BoolElt

Returns true if the rings \(R\) and \(S\) are the same, otherwise false.

R ne S: Rng, Rng -> BoolElt

Returns true if the rings \(R\) and \(S\) are distinct, otherwise false.

a in R: RngElt, Rng -> BoolElt

Returns true if and only if \(a\) is an element of \(R\).

a notin R: RngElt, Rng -> BoolElt

Returns true if and only if \(a\) is not an element of \(R\).

Predicates on Ring Elements

IsZero(a): RngElt -> BoolElt

Returns true if and only if the element \(a\) of \(R\) equals \(0_R\).

IsOne(a): RngElt -> BoolElt

Returns true if and only if the element \(a\) of \(R\) equals \(1_R\).

IsMinusOne(a): RngElt -> BoolElt

Returns true if and only if the element \(a\) of \(R\) equals the element \(-1\) of \(R\).

IsUnit(a): RngElt -> BoolElt

Returns true if \(a\) is a unit in its parent \(R\), false otherwise.

IsIdempotent(x): RngElt -> BoolElt

Returns true if and only if \(x^2\) equals \(x\).

IsNilpotent(x): RngElt -> BoolElt

Returns true if and only if some integer power \(x^i\) of \(x\) is zero.

IsZeroDivisor(x): RngElt -> BoolElt

Returns true if and only if \(x\) is a zero-divisor, that is, there exists an element \(y\) in the parent \(R\) of \(x\) such that \(xy=0\).

IsIrreducible(x): RngElt -> BoolElt

Returns true if and only if the parent \(R\) of the element \(x\) is a domain and \(x\) is irreducible in \(R\), that is, \(x\) is a non-unit of \(R\) and whenever a product \(ab\) of elements of \(R\) divides \(x\) then \(a\) or \(b\) is a unit of \(R\).

IsPrime(x): RngElt -> BoolElt

Returns true if and only if the parent \(R\) of the element \(x\) is a domain and \(x\) is a prime element of \(R\), that is, \(x\) is neither \(0\) nor a unit and whenever \(x\) divides the product \(ab\) of two elements of \(R\) it divides \(a\) or \(b\).

Comparison of Ring Elements

The comparison operations are only defined on types of ring that are ordered.

a gt b: RngElt, RngElt -> BoolElt

Returns true if the ring element \(a\) is greater than the ring element \(b\), otherwise false.

a ge b: RngElt, RngElt -> BoolElt

Returns true if the ring element \(a\) is greater than or equal to the ring element \(b\), otherwise false.

a lt b: RngElt, RngElt -> BoolElt

Returns true if the ring element \(a\) is less than the ring element \(b\), otherwise false.

a le b: RngElt, RngElt -> BoolElt

Returns true if the ring element \(a\) is less than or equal to the ring element \(b\), otherwise false.

Maximum(a, b): RngElt, RngElt -> RngElt

The maximum of the ring elements \(a\) and \(b\); if \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the maximum can be taken.

Maximum(Q): [RngIntElt] -> RngElt

The maximum of the sequence \(Q\) of ring elements.

Minimum(a, b): RngElt, RngElt -> RngElt

The minimum of the ring elements \(a\) and \(b\); if \(a\) and \(b\) do not belong to the same ring \(R\), an attempt will be made to find a common overstructure in which the minimum can be taken.

Minimum(Q): [RngIntElt] -> RngElt

The minimum of the sequence \(Q\) of ring elements.