---
title: "Handbook of Magma Functions, Part III: Basic Rings"
version: "2.30-1"
canonical: "https://docs.magma-maths.org/BasicRings/index-basic-rings.html"
---

# Basic Rings

- [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md): The ring/field world, coercion, and generic ring functionality.
- [Ring of Integers](https://docs.magma-maths.org/BasicRings/Integers/index-integers.md): Integer arithmetic, divisibility, primes, and number-theoretic functions.
- [Integer Residue Class Rings](https://docs.magma-maths.org/BasicRings/ResidueClassRings/index-residue-class-rings.md): Rings Z/nZ, Chinese remainder theorem, and Hensel lifting.
- [Rational Field](https://docs.magma-maths.org/BasicRings/Rationals/index-rationals.md): Rational number arithmetic and conversion.
- [Finite Fields](https://docs.magma-maths.org/BasicRings/FiniteFields/index-finite-fields.md): Construction, arithmetic, and extensions of finite fields.
- [Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/index-nearfields.md): Nearfield construction, properties, and element operations.
- [Univariate Polynomial Rings](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/index-univariate-polynomial-rings.md): Univariate polynomial ring creation, operations, and elements.
- [Multivariate Polynomial Rings](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/index-multivariate-polynomial-rings.md): Multivariate polynomial ring creation, operations, and elements.
- [Real and Complex Fields](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/index-real-and-complex-fields.md): Real and complex field creation, structure, and element operations.

<a id="detail"></a>
<a id="rngintro"></a>
## Introduction to Rings

- [Overview](https://docs.magma-maths.org/BasicRings/IntroductionToRings/overview.md)
- [The World of Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/world.md)
  - [New Rings from Existing Ones](https://docs.magma-maths.org/BasicRings/IntroductionToRings/world.md#new-rings-from-existing-ones)
- [Coercion](https://docs.magma-maths.org/BasicRings/IntroductionToRings/coercion.md)
  - [Automatic Coercion](https://docs.magma-maths.org/BasicRings/IntroductionToRings/coercion.md#automatic-coercion)
  - [Forced Coercion](https://docs.magma-maths.org/BasicRings/IntroductionToRings/coercion.md#forced-coercion)
- [Generic Ring Functions](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#related-structures)
    - [`Parent(R): Rng → Pow`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-parent-rng)
    - [`Category(R): Rng → Cat`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-category-rng)
    - [`Type(R): Rng → Cat`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-type-rng)
    - [`PrimeField(F): Fld → Fld`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-primefield-fld)
    - [`PrimeRing(R): Rng → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-primering-rng)
    - [`Centre(R): Rng → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-centre-rng)
    - [`Center(R): Rng → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-center-rng)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#numerical-invariants)
    - [`Characteristic(R): Rng → RngIntElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-characteristic-rng)
    - [`# R: Rng → RngIntElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#operation-operation-rng-rngintelt)
  - [Predicates and Boolean Operations](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#predicates-and-boolean-operations)
    - [`IsCommutative(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-iscommutative-rng)
    - [`IsUnitary(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isunitary-rng)
    - [`IsFinite(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isfinite-rng)
    - [`IsOrdered(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isordered-rng)
    - [`IsField(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isfield-rng)
    - [`IsDivisionRing(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isdivisionring-rng)
    - [`IsEuclideanDomain(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-iseuclideandomain-rng)
    - [`IsEuclideanRing(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-iseuclideanring-rng)
    - [`IsMagmaEuclideanRing(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-ismagmaeuclideanring-rng)
    - [`IsPID(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-ispid-rng)
    - [`IsPrincipalIdealDomain(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isprincipalidealdomain-rng)
    - [`IsPIR(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-ispir-rng)
    - [`IsPrincipalIdealRing(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isprincipalidealring-rng)
    - [`IsUFD(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isufd-rng)
    - [`IsUniqueFactorizationDomain(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isuniquefactorizationdomain-rng)
    - [`IsDomain(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isdomain-rng)
    - [`IsIntegralDomain(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-isintegraldomain-rng)
    - [`HasGCD(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#function-hasgcd-rng)
    - [`R eq S: Rng, Rng → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#operation-op-eq-rng-rng)
    - [`R ne S: Rng, Rng → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/generic.md#operation-op-ne-rng-rng)
- [Generic Element Functions](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#parent-and-category)
    - [`Parent(r): RngElt → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-parent-rngelt)
    - [`Category(r): RngElt → Cat`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-category-rngelt)
    - [`Type(r): RngElt → Cat`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-type-rngelt)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#creation-of-elements)
    - [`Zero(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-zero-rng)
    - [`One(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-one-rng)
    - [`Id(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-id-rng)
    - [`R ! a: Rng, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-rng-rngelt)
    - [`Random(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-random-rng)
    - [`Representative(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-representative-rng)
    - [`Rep(R): Rng → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-rep-rng)
  - [Arithmetic Operations](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#arithmetic-operations)
    - [`+ a: RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt)
    - [`- a: RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt-2)
    - [`a + b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-plus-rngelt-rngelt)
    - [`a - b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-minus-rngelt-rngelt)
    - [`a * b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-times-rngelt-rngelt)
    - [`a ^ k: RngElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-pow-rngelt-rngintelt)
    - [`a / b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-div-rngelt-rngelt)
    - [`a +:= b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt-rngelt)
    - [`a -:= b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt-rngelt-2)
    - [`a *:= b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt-rngelt-3)
    - [`a /:= b: RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngelt-rngelt-4)
    - [`a ^:= k: RngElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-operation-rngelt-rngintelt-rngelt)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#equality-and-membership)
    - [`a eq b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-eq-rngelt-rngelt)
    - [`a ne b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-ne-rngelt-rngelt)
    - [`R eq S: Rng, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-eq-rng-rng-2)
    - [`R ne S: Rng, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-ne-rng-rng-2)
    - [`a in R: RngElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-in-rngelt-rng)
    - [`a notin R: RngElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-notin-rngelt-rng)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#predicates-on-ring-elements)
    - [`IsZero(a): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-iszero-rngelt)
    - [`IsOne(a): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isone-rngelt)
    - [`IsMinusOne(a): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isminusone-rngelt)
    - [`IsUnit(a): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isunit-rngelt)
    - [`IsIdempotent(x): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isidempotent-rngelt)
    - [`IsNilpotent(x): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isnilpotent-rngelt)
    - [`IsZeroDivisor(x): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-iszerodivisor-rngelt)
    - [`IsIrreducible(x): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isirreducible-rngelt)
    - [`IsPrime(x): RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-isprime-rngelt)
  - [Comparison of Ring Elements](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#comparison-of-ring-elements)
    - [`a gt b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-gt-rngelt-rngelt)
    - [`a ge b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-ge-rngelt-rngelt)
    - [`a lt b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-lt-rngelt-rngelt)
    - [`a le b: RngElt, RngElt → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#operation-op-le-rngelt-rngelt)
    - [`Maximum(a, b): RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-maximum-rngelt-rngelt)
    - [`Maximum(Q): [RngIntElt] → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-maximum-rngintelt)
    - [`Minimum(a, b): RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-minimum-rngelt-rngelt)
    - [`Minimum(Q): [RngIntElt] → RngElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#function-minimum-rngintelt)
- [Ideals and Quotient Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md)
  - [Defining Ideals and Quotient Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#defining-ideals-and-quotient-rings)
    - [`ideal< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt → RngIdl`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#constructor-constructor-ideal-rng-rngelt-rngelt-rngidl)
    - [`quo< R | aᵣ, ..., aᵣ >: Rng, RngElt, ..., RngElt → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#constructor-constructor-quo-rng-rngelt-rngelt-rng)
    - [`R / I: Rng, RngIdl → Rng`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-div-rng-rngidl)
    - [`PowerIdeal(R): Rng → PowIdl`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#function-powerideal-rng)
  - [Arithmetic Operations on Ideals](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#arithmetic-operations-on-ideals)
    - [`I + J: RngIdl, RngIdl → RngIdl`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-plus-rngidl-rngidl)
    - [`I * J: RngIdl, RngIdl → RngIdl`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-times-rngidl-rngidl)
    - [`I meet J: RngIdl, RngIdl → RngIdl`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-meet-rngidl-rngidl)
  - [Boolean Operators on Ideals](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#boolean-operators-on-ideals)
    - [`a in I: RngElt, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-in-rngelt-rngidl)
    - [`a notin I: RngElt, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-notin-rngelt-rngidl)
    - [`I eq J: RngIdl, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-eq-rngidl-rngidl)
    - [`I ne J: RngIdl, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-ne-rngidl-rngidl)
    - [`I subset J: RngIdl, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-op-subset-rngidl-rngidl)
    - [`I notsubset J: RngIdl, RngIdl → BoolElt`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/ideal-quotient.md#operation-operation-notsubset-rngidl-rngidl-boolelt)
- [Other Ring Constructions](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md)
  - [Residue Class Fields](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#residue-class-fields)
    - [`ResidueClassField(I): Rng → Fld, Map`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#function-residueclassfield-rng)
  - [Localization](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#localization)
    - [`loc< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt → Rng, Map`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#constructor-constructor-loc-rng-rngelt-rngelt-rng-map)
    - [`Localization(R, P): Rng, Rng → Rng, Map`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#function-localization-rng-rng)
  - [Completion](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#completion)
    - [`comp< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt → Rng, Map`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#constructor-constructor-comp-rng-rngelt-rngelt-rng-map)
    - [`Completion(R, P): Rng, Rng → Rng, Map`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#function-completion-rng-rng)
  - [Transcendental Extension](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#transcendental-extension)
    - [`ext< R | >: Rng → RngUPol`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#constructor-constructor-ext-rng-rngupol)
    - [`ext< R, n | >: Rng, RngIntElt → RngMPol`](https://docs.magma-maths.org/BasicRings/IntroductionToRings/creation-other.md#constructor-constructor-ext-rng-rngintelt-rngmpol)

### Overview

Rings of various kinds form the richest source of algebraic structures in Magma. Tables 1 and 2 list the most important types.

```
Symbol         Description               Category
--------------------------------------------------
Z              ring of integers          RngInt
Z/mZ           ring of residue classes   RngRes
R[x]           univariate poly. ring     RngUPol
F[x]/f(x)      univ. poly. factor ring   RngUPolRes
R[x_1,...,x_m] multivariate poly. ring   RngMPol
R[[x]]         power series ring         RngSer
O              order in a number field   RngOrd
\Z_p           p-adic ring               RngPad
R_m            local ring                RngLoc
V              valuation ring            RngVal
--------------------------------------------------
Q              rational field            FldRat
F_q            finite field              FldFin
F(x_1,...,x_m) rational function field   FldFun
F((x))         field of Laurent series   FldPow
Q(sqrt(D))     quadratic number field    FldQuad
Q(zeta_n)      cyclotomic number field   FldCyc
Q(alpha)       number field              FldNum
Q_p            p-adic field              FldPad
Q_p(alpha)     local field               FldLoc
R              real field                FldRe
C              complex field             FldCom
--------------------------------------------------
```

The list of rings in Table 1 is not exhaustive, for two reasons. In the first place, some rings have been categorized differently, because their module structure or algebra structure seems pre-eminent; thus matrix rings and finitely presented algebras appear (more or less arbitrarily) in the Part on Algebras, and vector spaces and their generalizations appear in the Module Part. (Also, rings of class functions appear in the Part on Groups.) Furthermore, certain general constructions (such as `sub`) allow the user to define rings that do not appear in the above list, most notably subrings of ${\mathbb{Z}}$. Looking at the table it may seem that all rings in Magma are commutative and unital. This is not the case (even though it would have made life much easier); since polynomial rings and the like can be defined over any coefficient ring, the matrix rings and finitely presented algebras not listed here that are not generally commutative, allow the construction of non-commutative rings. Furthermore, the `sub` constructor allows the creation of rings without 1; certain functions for the construction of new rings from old ones do not allow such non-unital coefficient rings. In this Chapter we give an overview of the various types and the relations between them. Moreover, we describe the important principles underlying the rules for coercion of elements of one ring into another. This Chapter also describes the common functions for all types of rings (and their elements), and subsequent Chapters deal with particular categories of rings, as indicated by the table.

### The World of Rings

There are various ways in which to order the families of rings appearing in Table 1. We look at some in this section.

#### New Rings from Existing Ones

It is important to realize at the outset that to work comfortably with a ring, it should be finitely generated (over some subring); indeed, the only violations of this rule occur for real and complex fields, and $p$-adic and power series type structures, in which we necessarily have to cope with approximations. All other rings we will label as *exact*. All rings in Table 1 can be obtained from the ring of rational integers ${\mathbb{Z}}$ by repeated application of a handful of fundamental mathematical constructions. The first such construction is *forming fractions*: the rational field ${\mathbb{Q}}$ can be obtained as the field of fractions of ${\mathbb{Z}}$. The second construction is that of forming quotients: in this way the rings ${\mathbb{Z}}/m{\mathbb{Z}}$ are obtained from ${\mathbb{Z}}$. The third important construction is that of *transcendental extension*: by adjoining an element that satisfies no relation over the coefficient ring, a polynomial ring is obtained. An *algebraic extension* can be obtained by a combination of a transcendental extension and a quotient. Finally, *completion* of a ring at a prime leads in general to the rings that were labelled above as not exact. Some other constructions are: tensoring, taking direct products (leading to tuple modules), and taking valuation rings (an operation inverse to taking fields of fractions). Most of these constructions are supported by Magma. In many situations the `quo` and `ext` constructors will perform the quotient and algebraic extension operations, just like `sub` creates sub-structures. Note an important distinction: usually `sub` creates structures of exactly the same type as the original structure—this is precisely why the construction of sub-object does not appear as an important construction for creating new objects in the previous paragraph. Care should be taken not to confuse the mathematical properties of rings (or objects in Magma in general) and the properties of the object that Magma is aware of. For example, if one creates the ring of residue classes ${\mathbb{Z}}/p{\mathbb{Z}}$ for a prime number $p$, using the command `IntegerRing(p)`, the Magma object created is a residue class ring (whose modulus happens to be prime) and *not* a finite field; the functions applicable are the residue class ring functions, and it is, for instance, not possible to create a field extension over this object. If the intention was to create a finite field, the `FiniteField(p)` command should have been used, and for that object it is possible to create a field extension. Similarly, a convenient way of thinking about a number field $K={\mathbb{Q}}(\alpha)$ is to regard it as a quotient of the polynomial ring ${\mathbb{Q}}[X]$ and the ideal generated by the minimal polynomial $f$ of the primitive element $\alpha$:

$$
K={\mathbb{Q}}(\alpha)\cong{\mathbb{Q}}[X]/(f).
$$

This is, however, not the way to create number fields in Magma. The quotient ring of a polynomial ring will be an object to which only the generic ring functions apply, whereas to obtain the number field with all the machinery to manipulate it one has to use a command like `NumberField(f)`.

### Coercion

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 ${\mathbb{Q}}$ can be coerced into ${\mathbb{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 $\circ: C\times C\rightarrow C$ on members $C$ of a category of rings ${\cal C}$ is applied to elements $r$ and $s$ of members $R$ and $S$ from ${\cal C}$, the same rules for coercion will be used to determine the legality of $r\circ s$. If $s$ can be coerced automatically into $R$, then this will take place and $r\circ s$ will be evaluated in $R$; otherwise, if $r$ can be coerced automatically into $S$, then $r\circ 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 ${\cal C}$ such that $\subset T\supset S$; then both $r$ and $s$ will be coerced into $T$ and the result $t=r\circ 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)`.

#### Automatic Coercion

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 ${\mathbb{Q}}$, that is, we clearly wish to have automatic coercion from ${\mathbb{Z}}$ to ${\mathbb{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 ${\mathbb{Z}}\rightarrow 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[X_1, \ldots, X_n]$ if either $S$ equals $R[X_1,\ldots, X_i]$ for some $1\leq i\leq 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 ${\mathbb{Z}}[X]$ and $g$ of ${\mathbb{Z}}[X, Y]$, but *not* an integer and a polynomial over the rationals. An element $s$ can be coerced automatically in the matrix ring $M_{n, 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 $M_{n, n}({\mathbb{Z}})$ and $M_{n, n}({\mathbb{Q}})$, nor elements from $M_{2, 2}({\mathbb{Z}})$ and $M_{3, 3}({\mathbb{Z}})$.

#### Forced Coercion

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 ${\mathbb{Z}}/p{\mathbb{Z}}$, 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 ${\mathbb{Z}}/p{\mathbb{Z}}$ 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 ${\mathbb{Q}}$ can be coerced into ${\mathbb{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 ${\mathbb{F}}_{p^s}$ can only be coerced into ${\mathbb{Z}}/m{\mathbb{Z}}$ if $s=1$ and $m=p$. Any element from ${\mathbb{F}}_{p^s}$ can be coerced into ${\mathbb{F}}_{p^r}$ 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[X_1, \ldots, X_n]$, the following steps are executed successively:

**(a)**
if $s$ is an element of $P$ it remains unchanged;

**(b)**
if $s$ is a sequence, then the zero element of $P$ is returned if $s$ is empty, and if it is non-empty but the elements of the sequence can be coerced into $P[X_1, \ldots, X_{n-1}]$ then the polynomial $\sum_j s[j]X_n^{j-1}$ is returned;

**(c)**
if $s$ can be coerced into the coefficient ring $R$, then the constant polynomial $s$ is returned;

**(d)**
if $s$ is a polynomial in $R[X_1, \ldots, X_k]$ for some $1\leq k\leq n$, then it is lifted in the obvious way into $P$;

**(e)**
if $s$ is a polynomial in $R[X_1, \ldots, X_k]$ for some $k > n$, but constant in the indeterminates $X_{n+1}, \ldots, X_{k}$, then $s$ is projected down in the obvious way to $P$.

If none of these steps successfully coerces $s$ into $P$, an error occurs. The ring element $s$ can be coerced into $M_{n, 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\in S=M_{n, n}(R')$, where $R'$ can be coerced into $R$. Also a sequence of $n^2$ elements coercible into $R$ can be coerced into the matrix ring $M_{n, n}(R)$. Elements from a matrix ring $M_{n, 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.

### Generic Ring Functions

The generic functions described in this Chapter apply in principle to every type of ring. For certain rings these are the only applicable functions. The qualification ‘in principle’ in the first sentence is made because for some classes of rings an algorithm to compute certain of these functions does not exist, or has not been implemented. In that case an error will result.

This general list is provided primarily to avoid duplication of common descriptions. In the following Chapters the generic functions will be listed merely without further description, and the emphasis can be on the functions specific to a particular type of ring.

#### Related Structures

<a id="function-parent-rng"></a>
##### `Parent(R): Rng -> Pow`

The parent of ring $R$. Currently this returns the *power structure* of the ring.

<a id="function-category-rng"></a>
##### `Category(R): Rng -> Cat`

<a id="function-type-rng"></a>
##### `Type(R): Rng -> Cat`

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

<a id="function-primefield-fld"></a>
##### `PrimeField(F): Fld -> Fld`

For a field $F$, this returns either ${\mathbb{F}}_p$, if the characteristic $p$ of $F$ is positive, or ${\mathbb{Q}}$, if the characteristic of $F$ is $0$. If $F$ is an extension field then it will return the field at the bottom of the extension tower.

<a id="function-primering-rng"></a>
##### `PrimeRing(R): Rng -> Rng`

For a unitary ring $R$, this returns either ${\mathbb{Z}}/n{\mathbb{Z}}$, if the characteristic $n$ of $R$ is positive, or ${\mathbb{Z}}$, if the characteristic of $R$ is $0$. If $R$ is an extension ring then it will return the ring at the bottom of the extension tower.

<a id="function-centre-rng"></a>
##### `Centre(R): Rng -> Rng`

<a id="function-center-rng"></a>
##### `Center(R): Rng -> Rng`

Given a ring $R$, return its centre, consisting of the subring of elements commuting with all other elements of $R$.

#### Numerical Invariants

<a id="function-characteristic-rng"></a>
##### `Characteristic(R): Rng -> RngIntElt`

The characteristic of the ring $R$, which is the smallest positive integer $m$ such that $m\cdot r=0$ for every $r\in R$, or zero if such $m$ does not exist.

<a id="operation-operation-rng-rngintelt"></a>
##### `# R: Rng -> RngIntElt`

The cardinality of the ring $R$; here $R$ must be finite.

<a id="predicate"></a>
<a id="rngintro-predb"></a>
#### Predicates and Boolean Operations

<a id="function-iscommutative-rng"></a>
##### `IsCommutative(R): Rng -> BoolElt`

Returns `true` if it is known that the ring $R$ is commutative, `false` if it is known that $R$ is not commutative. An error results if the answer is not known.

<a id="function-isunitary-rng"></a>
##### `IsUnitary(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be unitary (that is, if $R$ has a multiplicative identity), `false` if $R$ has no $1$.

<a id="function-isfinite-rng"></a>
##### `IsFinite(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a finite ring, `false` if it is known to be infinite. An error results if the answer is not known.

<a id="function-isordered-rng"></a>
##### `IsOrdered(R): Rng -> BoolElt`

Returns `true` if the ring $R$ has a total ordering defined on the set of its elements, `false` otherwise.

<a id="function-isfield-rng"></a>
##### `IsField(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a field, `false` if it is known to not be a field. An error results if the answer is not known.

<a id="function-isdivisionring-rng"></a>
##### `IsDivisionRing(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a division ring (that is, every non-zero element is invertible), `false` if it is known that $R$ is not a division ring. An error results if the answer is not known.

<a id="function-iseuclideandomain-rng"></a>
##### `IsEuclideanDomain(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a euclidean domain, `false` if it is known that $R$ is not a euclidean domain. An error results if the answer is not known.

<a id="function-iseuclideanring-rng"></a>
##### `IsEuclideanRing(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be euclidean, `false` if it is known that $R$ is not euclidean. An error results if the answer is not known.

<a id="function-ismagmaeuclideanring-rng"></a>
##### `IsMagmaEuclideanRing(R): Rng -> BoolElt`

Returns `true` iff the ring $R$ is a computable euclidean ring within Magma (i.e., iff the necessary euclidean operations are defined for $R$ so algorithms requiring a euclidean ring will work).

<a id="function-ispid-rng"></a>
##### `IsPID(R): Rng -> BoolElt`

<a id="function-isprincipalidealdomain-rng"></a>
##### `IsPrincipalIdealDomain(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a principal ideal domain, `false` if it is known that $R$ is not a principal ideal domain. An error results if the answer is not known.

<a id="function-ispir-rng"></a>
##### `IsPIR(R): Rng -> BoolElt`

<a id="function-isprincipalidealring-rng"></a>
##### `IsPrincipalIdealRing(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a principal ideal ring, `false` if it is known that $R$ has non-principal ideals. An error results if the answer is not known.

<a id="function-isufd-rng"></a>
##### `IsUFD(R): Rng -> BoolElt`

<a id="function-isuniquefactorizationdomain-rng"></a>
##### `IsUniqueFactorizationDomain(R): Rng -> BoolElt`

Returns `true` if the ring $R$ is known to be a unique factorization domain, `false` if it is known that $R$ is not a unique factorization domain. An error results if the answer is not known.

<a id="function-isdomain-rng"></a>
##### `IsDomain(R): Rng -> BoolElt`

<a id="function-isintegraldomain-rng"></a>
##### `IsIntegralDomain(R): Rng -> BoolElt`

Returns `true` if it is known that $R$ is an integral domain (i.e., $R$ has no zero divisors), `false` if $R$ is known to have zero divisors. An error results if the answer is not known.

<a id="function-hasgcd-rng"></a>
##### `HasGCD(R): Rng -> BoolElt`

Returns `true` iff there is a GCD algorithm for elements of ring $R$ in Magma.

<a id="operation-op-eq-rng-rng"></a>
##### `R eq S: Rng, Rng -> Rng`

For certain pairs $R, S$ of rings, this returns `true` if $R$ and $S$ refer to the same ring, and `false` otherwise. However, if $R$ and $S$ belong to different categories an error may result.

<a id="operation-op-ne-rng-rng"></a>
##### `R ne S: Rng, Rng -> Rng`

For certain pairs $R, S$ of rings, this returns `true` if $R$ and $S$ refer to different rings, and `false` otherwise. However, if $R$ and $S$ belong to different categories an error may result.

<a id="element"></a>
<a id="rngintro-elt-funcs"></a>
### Generic Element Functions

#### Parent and Category

<a id="function-parent-rngelt"></a>
##### `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.

<a id="function-category-rngelt"></a>
##### `Category(r): RngElt -> Cat`

<a id="function-type-rngelt"></a>
##### `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

<a id="function-zero-rng"></a>
##### `Zero(R): Rng -> RngElt`

The zero element of ring $R$; this is equivalent to `R ! 0`.

<a id="function-one-rng"></a>
##### `One(R): Rng -> RngElt`

<a id="function-id-rng"></a>
##### `Id(R): Rng -> RngElt`

The multiplicative identity $1$ of ring $R$; this is equivalent to `R ! 1`.

<a id="operation-op-rng-rngelt"></a>
##### `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$.

<a id="function-random-rng"></a>
##### `Random(R): Rng -> RngElt`

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

<a id="function-representative-rng"></a>
##### `Representative(R): Rng -> RngElt`

<a id="function-rep-rng"></a>
##### `Rep(R): Rng -> RngElt`

A representative element of the finite ring $R$.

#### Arithmetic Operations

<a id="operation-operation-rngelt-rngelt"></a>
##### `+ a: RngElt -> RngElt`

Element $a$.

<a id="operation-operation-rngelt-rngelt-2"></a>
##### `- a: RngElt -> RngElt`

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

<a id="operation-op-plus-rngelt-rngelt"></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 id="operation-op-minus-rngelt-rngelt"></a>
##### `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 id="operation-op-times-rngelt-rngelt"></a>
##### `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 id="operation-op-pow-rngelt-rngintelt"></a>
##### `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 id="operation-op-div-rngelt-rngelt"></a>
##### `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 id="operation-operation-rngelt-rngelt-rngelt"></a>
##### `a +:= b: RngElt, RngElt -> RngElt`

Mutation assignment: change $a$ into the sum of $a$ and $b$.

<a id="operation-operation-rngelt-rngelt-rngelt-2"></a>
##### `a -:= b: RngElt, RngElt -> RngElt`

Mutation assignment: change $a$ into the difference of $a$ and $b$.

<a id="operation-operation-rngelt-rngelt-rngelt-3"></a>
##### `a *:= b: RngElt, RngElt -> RngElt`

Mutation assignment: change $a$ into the product of $a$ and $b$.

<a id="operation-operation-rngelt-rngelt-rngelt-4"></a>
##### `a /:= b: RngElt, RngElt -> RngElt`

Mutation assignment: change $a$ into the quotient of $a$ and $b$.

<a id="operation-operation-rngelt-rngintelt-rngelt"></a>
##### `a ^:= k: RngElt, RngIntElt -> RngElt`

Mutation assignment: change $a$ into the power $a^k$.

#### Equality and Membership

<a id="operation-op-eq-rngelt-rngelt"></a>
##### `a eq b: RngElt, RngElt -> BoolElt`

Returns `true` if the elements $a$ and $b$ of $R$ are the same, otherwise `false`.

<a id="operation-op-ne-rngelt-rngelt"></a>
##### `a ne b: RngElt, RngElt -> BoolElt`

Returns `true` if the elements $a$ and $b$ of $R$ are distinct, otherwise `false`.

<a id="operation-op-eq-rng-rng-2"></a>
##### `R eq S: Rng, Rng -> BoolElt`

Returns `true` if the rings $R$ and $S$ are the same, otherwise `false`.

<a id="operation-op-ne-rng-rng-2"></a>
##### `R ne S: Rng, Rng -> BoolElt`

Returns `true` if the rings $R$ and $S$ are distinct, otherwise `false`.

<a id="operation-op-in-rngelt-rng"></a>
##### `a in R: RngElt, Rng -> BoolElt`

Returns `true` if and only if $a$ is an element of $R$.

<a id="operation-op-notin-rngelt-rng"></a>
##### `a notin R: RngElt, Rng -> BoolElt`

Returns `true` if and only if $a$ is not an element of $R$.

#### Predicates on Ring Elements

<a id="function-iszero-rngelt"></a>
##### `IsZero(a): RngElt -> BoolElt`

Returns `true` if and only if the element $a$ of $R$ equals $0_R$.

<a id="function-isone-rngelt"></a>
##### `IsOne(a): RngElt -> BoolElt`

Returns `true` if and only if the element $a$ of $R$ equals $1_R$.

<a id="function-isminusone-rngelt"></a>
##### `IsMinusOne(a): RngElt -> BoolElt`

Returns `true` if and only if the element $a$ of $R$ equals the element $-1$ of $R$.

<a id="function-isunit-rngelt"></a>
##### `IsUnit(a): RngElt -> BoolElt`

Returns `true` if $a$ is a unit in its parent $R$, `false` otherwise.

<a id="function-isidempotent-rngelt"></a>
##### `IsIdempotent(x): RngElt -> BoolElt`

Returns `true` if and only if $x^2$ equals $x$.

<a id="function-isnilpotent-rngelt"></a>
##### `IsNilpotent(x): RngElt -> BoolElt`

Returns `true` if and only if some integer power $x^i$ of $x$ is zero.

<a id="function-iszerodivisor-rngelt"></a>
##### `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$.

<a id="function-isirreducible-rngelt"></a>
##### `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$.

<a id="function-isprime-rngelt"></a>
##### `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 id="operation-op-gt-rngelt-rngelt"></a>
##### `a gt b: RngElt, RngElt -> BoolElt`

Returns `true` if the ring element $a$ is greater than the ring element $b$, otherwise `false`.

<a id="operation-op-ge-rngelt-rngelt"></a>
##### `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 id="operation-op-lt-rngelt-rngelt"></a>
##### `a lt b: RngElt, RngElt -> BoolElt`

Returns `true` if the ring element $a$ is less than the ring element $b$, otherwise `false`.

<a id="operation-op-le-rngelt-rngelt"></a>
##### `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`.

<a id="function-maximum-rngelt-rngelt"></a>
##### `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.

<a id="function-maximum-rngintelt"></a>
##### `Maximum(Q): [RngIntElt] -> RngElt`

The maximum of the sequence $Q$ of ring elements.

<a id="function-minimum-rngelt-rngelt"></a>
##### `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.

<a id="function-minimum-rngintelt"></a>
##### `Minimum(Q): [RngIntElt] -> RngElt`

The minimum of the sequence $Q$ of ring elements.

### Ideals and Quotient Rings

The following entries describe the operations on ideals in a *commutative ring* $R$. Certain operations on left and right ideals in non-commutative rings will be described in the Chapters for the corresponding rings.

<a id="creation"></a>
<a id="rngintro-ideal"></a>
#### Defining Ideals and Quotient Rings

<a id="constructor-constructor-ideal-rng-rngelt-rngelt-rngidl"></a>
##### `ideal< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt -> RngIdl`

Given a ring $R$ and elements $a_1, \ldots, a_r$ of $R$, create the ideal $I$ of $R$ generated by $a_1, \ldots, a_r$.

<a id="constructor-constructor-quo-rng-rngelt-rngelt-rng"></a>
##### `quo< R | aᵣ, ..., aᵣ >: Rng, RngElt, ..., RngElt -> Rng`

Given a ring $R$ and elements $a_1, \ldots, a_r$ of $R$, construct the quotient ring $Q = R/I$, where $I$ is the ideal of $R$ generated by $a_1, \ldots, a_r$.

<a id="operation-op-div-rng-rngidl"></a>
##### `R / I: Rng, RngIdl -> Rng`

Given a ring $R$ and an ideal $I$ of $R$, construct the quotient ring $Q = R/I$, as well as the canonical map $R\rightarrow R/I$.

Note, however, that there can be pitfalls with this, particularly if the first argument is itself interpreted as an ideal, when instead the result could be interpreted as something like the `ColonIdeal`.

For instance:

```magma
> Z := Integers();
> I := ideal<Z|1>; // ideal of Z
> Z/I; // ideal quotient, similar to ColonIdeal
Integer Ring
> quo<Z|I>; // quotient of ring by ideal
Residue class ring of integers modulo 1
```

In fact, ${\mathbb{Z}}/I$ is computing the (fractional) ideal $J$ such that $JI={\mathbb{Z}}$. The technical reason for this is that both ${\mathbb{Z}}$ and $I$ are of type `RngInt`, and there is no specific `RngIntIdl` type as with order of number fields (where there are `RngOrd` and `RngOrdIdl`).

On the other hand, for instance for univariate polynomial rings where again there is no specific type for ideals, the `/` operator acts as the ring/ideal quotient (while `ColonIdeal` does not exist for this type, though it does for the multivariate polynomial ring type `RngMPol`).

```magma
> Zx<x> := PolynomialRing(Rationals());
> I := ideal<Zx|x>;
> Type(Zx),Type(I);
RngUPol RngUPol
> Zx/I; // same as quo<Zx|I>
Univariate Quotient Polynomial Algebra in over Rational Field
> Type(Zx/I);
RngUPolRes
```

<a id="function-powerideal-rng"></a>
##### `PowerIdeal(R): Rng -> PowIdl`

The set of ideals of $R$. This is the parent of all ideals of $R$.

#### Arithmetic Operations on Ideals

<a id="operation-op-plus-rngidl-rngidl"></a>
##### `I + J: RngIdl, RngIdl -> RngIdl`

The sum of the ideals $I$ and $J$ of the ring $R$. This ideal consists of elements $a+b$, with $a\in I$ and $b\in J$. If $I$ is generated by $\{a_1, \ldots, a_k\}$ and $J$ is generated by $\{b_1, \ldots, b_m\}$, then $I+J$ is generated by $\{a_1, \ldots, a_k, b_1, \ldots, b_m\}$.

<a id="operation-op-times-rngidl-rngidl"></a>
##### `I * J: RngIdl, RngIdl -> RngIdl`

The product of the ideals $I$ and $J$ of the ring $R$. This is the ideal generated by elements $a\cdot b$, with $a\in I$ and $b\in J$, and it consists of elements $a_1b_1+\cdots+a_nb_n$, with $a_i\in I$ and $b_j\in J$.

<a id="operation-op-meet-rngidl-rngidl"></a>
##### `I meet J: RngIdl, RngIdl -> RngIdl`

The intersection of the ideals $I$ and $J$ of the ring $R$.

#### Boolean Operators on Ideals

Throughout this subsection $I$ and $J$ are ideals belonging to the same integer ring $R$, while $a$ is an element of $R$.

<a id="operation-op-in-rngelt-rngidl"></a>
##### `a in I: RngElt, RngIdl -> BoolElt`

Returns `true` if and only if the element $a$ is a member of the ideal $I$.

<a id="operation-op-notin-rngelt-rngidl"></a>
##### `a notin I: RngElt, RngIdl -> BoolElt`

Returns `true` if and only if the element $a$ is not a member of the ideal $I$.

<a id="operation-op-eq-rngidl-rngidl"></a>
##### `I eq J: RngIdl, RngIdl -> BoolElt`

Returns `true` if and only if the ideals $I$ and $J$ are equal.

<a id="operation-op-ne-rngidl-rngidl"></a>
##### `I ne J: RngIdl, RngIdl -> BoolElt`

Returns `true` if and only if the ideals $I$ and $J$ are distinct.

<a id="operation-op-subset-rngidl-rngidl"></a>
##### `I subset J: RngIdl, RngIdl -> BoolElt`

Returns `true` if and only if the ideal $I$ is contained in the ideal $J$.

<a id="operation-operation-notsubset-rngidl-rngidl-boolelt"></a>
##### `I notsubset J: RngIdl, RngIdl -> BoolElt`

Returns `true` if and only if the ideal $I$ is not contained in the ideal $J$.

### Other Ring Constructions

Magma allows the construction of residue fields, localization of rings, and completion of rings. These constructions really just create appropriate rings of different categories within Magma.

#### Residue Class Fields

<a id="function-residueclassfield-rng"></a>
##### `ResidueClassField(I): Rng -> Fld, Map`

Given a maximal ideal $I$ of a ring $R$, create the residue class field $K$ of the quotient ring $R/I$, together with a map sending an element of $R$ to the corresponding element of $K$.

#### Localization

<a id="constructor-constructor-loc-rng-rngelt-rngelt-rng-map"></a>
##### `loc< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt -> Rng, Map`

Given a ring $R$ and elements $a_1, \ldots, a_r$ of $R$, which generate a prime ideal $P$ of $R$, create the localization $L$ of $R$ at $P$, together with a map sending an element of $R$ to the corresponding element of $L$.

<a id="function-localization-rng-rng"></a>
##### `Localization(R, P): Rng, Rng -> Rng, Map`

Given a ring $R$ and a prime ideal $P$ of $R$, create the localization $L$ of $R$ at $P$, together with a map sending an element of $R$ to the corresponding element of $L$.

#### Completion

<a id="constructor-constructor-comp-rng-rngelt-rngelt-rng-map"></a>
##### `comp< R | a₁, ..., aᵣ >: Rng, RngElt, ..., RngElt -> Rng, Map`

Given a ring $R$ and elements $a_1, \ldots, a_r$ of $R$, which generate a prime ideal or zero ideal $P$ of $R$, create the completion $C$ of $R$ at $P$, together with a map sending an element of $R$ to the corresponding element of $C$.

<a id="function-completion-rng-rng"></a>
##### `Completion(R, P): Rng, Rng -> Rng, Map`

Given a ring $R$ and a prime ideal or zero ideal $P$ of $R$, create the completion $C$ of $R$ at $P$, together with a map sending an element of $R$ to the corresponding element of $C$.

#### Transcendental Extension

<a id="constructor-constructor-ext-rng-rngupol"></a>
##### `ext< R | >: Rng -> RngUPol`

Given a ring $R$ create the univariate transcendental extension $R[x]$ of $R$. This is equivalent to `PolynomialRing(R)`.

<a id="constructor-constructor-ext-rng-rngintelt-rngmpol"></a>
##### `ext< R, n | >: Rng, RngIntElt -> RngMPol`

Given a ring $R$ and an integer $n \geq 1$, create the multivariate transcendental extension $R[x_1, \ldots, x_n]$ of $R$. This is equivalent to `PolynomialRing(R, n)`.

<a id="integer"></a>
<a id="rngint"></a>
## Ring of Integers

- [Introduction](https://docs.magma-maths.org/BasicRings/Integers/introduction.md)
  - [Representation](https://docs.magma-maths.org/BasicRings/Integers/introduction.md#representation)
  - [Coercion](https://docs.magma-maths.org/BasicRings/Integers/introduction.md#coercion)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/Integers/introduction.md#homomorphisms)
    - [`hom< Z -> R | >: RngInt, Rng → Map`](https://docs.magma-maths.org/BasicRings/Integers/introduction.md#constructor-constructor-hom-rngint-rng-map)
    - [Example: Homomorphism from the Integers to a Matrix Ring](https://docs.magma-maths.org/BasicRings/Integers/introduction.md#example-ex-a58966)
- [Creation Functions](https://docs.magma-maths.org/BasicRings/Integers/creation.md)
  - [Creation of Structures](https://docs.magma-maths.org/BasicRings/Integers/creation.md#creation-of-structures)
    - [`IntegerRing() → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integerring)
    - [`Integers() → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integers)
    - [`RingOfIntegers() → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-ringofintegers)
    - [`IntegerRing(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integerring-fldrat)
    - [`Integers(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integers-fldrat)
    - [`RingOfIntegers(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-ringofintegers-fldrat)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/Integers/creation.md#creation-of-elements)
    - [`a₁a₂...aᵣ`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#literal-literal-integer-literal-a1a2-ar)
    - [`0xa₁a₂...aᵣ`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#literal-literal-integer-literal-hexadecimal-0xa1a2-ar)
    - [`0ba₁a₂...aᵣ`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#literal-literal-integer-literal-binary-0ba1a2-ar)
    - [`elt< Z | a₁a₂...aᵣ >: RngInt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#constructor-constructor-elt-rngint-rngintelt-rngintelt)
    - [`elt< Z | 0xa₁a₂...aᵣ >: RngInt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#constructor-constructor-elt-rngint-rngintelt-rngintelt-2)
    - [`elt< Z | 0ba₁a₂...aᵣ >: RngInt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#constructor-constructor-elt-rngint-rngintelt-rngintelt-3)
    - [`Z ! a: RngInt, RngElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#operation-op-rngint-rngelt)
    - [`Z ! [a]: RngInt, [RngElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#operation-op-rngint-rngelt-2)
    - [Example: Creating Integers](https://docs.magma-maths.org/BasicRings/Integers/creation.md#example-ex-2fa3b0)
    - [`One(Z): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-one-rngint)
    - [`Identity(Z): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-identity-rngint)
    - [`Zero(Z): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-zero-rngint)
    - [`Representative(Z): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-representative-rngint)
  - [Printing of Elements](https://docs.magma-maths.org/BasicRings/Integers/creation.md#printing-of-elements)
    - [Example: Printing in Hexadecimal](https://docs.magma-maths.org/BasicRings/Integers/creation.md#example-ex-47136f)
  - [Element Conversions](https://docs.magma-maths.org/BasicRings/Integers/creation.md#element-conversions)
    - [`FactorizationToInteger(s): [ <RngIntElt, RngIntElt> ] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-factorizationtointeger-rngintelt-rngintelt)
    - [`FactorisationToInteger(s): [ <RngIntElt, RngIntElt> ] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-factorisationtointeger-rngintelt-rngintelt)
    - [`Facint(s): [ <RngIntElt, RngIntElt> ] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-facint-rngintelt-rngintelt)
    - [`IntegerToSequence(n, b): RngIntElt, RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integertosequence-rngintelt-rngintelt)
    - [`Intseq(n, b): RngIntElt, RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-intseq-rngintelt-rngintelt)
    - [`SequenceToInteger(s, b): [RngIntElt], RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-sequencetointeger-rngintelt-rngintelt)
    - [`Seqint(s, b): [RngIntElt], RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-seqint-rngintelt-rngintelt)
    - [`IntegerToString(n): RngIntElt → ModStgElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integertostring-rngintelt)
    - [`IntegerToString(n, b): RngIntElt, RngIntElt → ModStgElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-integertostring-rngintelt-rngintelt)
    - [`Eltseq(n): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-eltseq-rngintelt)
    - [`Denominator(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/creation.md#function-denominator-rngintelt)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/Integers/operation.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/Integers/operation.md#related-structures)
    - [`Category(Z): RngInt → Cat`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-category-rngint)
    - [`Parent(Z): RngInt → PowerStructure`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-parent-rngint)
    - [`PrimeRing(Z): RngInt → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-primering-rngint)
    - [`Center(Z): RngInt → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-center-rngint)
    - [`AdditiveGroup(Z): RngInt → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-additivegroup-rngint)
    - [`MultiplicativeGroup(Z): RngInt → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-multiplicativegroup-rngint)
    - [`UnitGroup(Z): RngInt → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-unitgroup-rngint)
    - [`ClassGroup(Z): RngInt → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-classgroup-rngint)
    - [`FieldOfFractions(Z): RngInt → FldRat`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-fieldoffractions-rngint)
    - [`sub< Z | n >: RngInt, RngIntElt → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#constructor-constructor-sub-rngint-rngintelt-rngint)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/Integers/operation.md#numerical-invariants)
    - [`Characteristic(Z): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-characteristic-rngint)
    - [`Signature(Z): RngInt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-signature-rngint)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/Integers/operation.md#ring-predicates-and-booleans)
    - [`IsCommutative(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-iscommutative-rngint)
    - [`IsUnitary(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isunitary-rngint)
    - [`IsFinite(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isfinite-rngint)
    - [`IsOrdered(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isordered-rngint)
    - [`IsField(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isfield-rngint)
    - [`IsEuclideanDomain(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-iseuclideandomain-rngint)
    - [`IsPID(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-ispid-rngint)
    - [`IsUFD(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isufd-rngint)
    - [`IsDivisionRing(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isdivisionring-rngint)
    - [`IsEuclideanRing(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-iseuclideanring-rngint)
    - [`IsPrincipalIdealRing(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isprincipalidealring-rngint)
    - [`IsDomain(Z): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#function-isdomain-rngint)
    - [`Z eq R: RngInt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#operation-op-eq-rngint-rng)
    - [`Z ne R: RngInt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation.md#operation-op-ne-rngint-rng)
- [Element Operations](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md)
  - [Arithmetic Operations](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#arithmetic-operations)
    - [`+ n: RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt)
    - [`- n: RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-2)
    - [`m + n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-plus-rngintelt-rngintelt)
    - [`m - n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-minus-rngintelt-rngintelt)
    - [`m * n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-times-rngintelt-rngintelt)
    - [`n ^ k: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-pow-rngintelt-rngintelt)
    - [`m / n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-div-rngintelt-rngintelt)
    - [`m +:= n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-rngintelt)
    - [`m -:= n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-rngintelt-2)
    - [`m *:= n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-rngintelt-3)
    - [`m /:= n: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-rngintelt-4)
    - [`m ^:= k: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-rngintelt-rngintelt-rngintelt-5)
    - [`n div m: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-div-rngintelt-rngintelt-rngintelt)
    - [`n mod m: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-mod-rngintelt-rngintelt-rngintelt)
    - [`ExactQuotient(n, d): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-exactquotient-rngintelt-rngintelt)
    - [`n div:= m: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-div-rngintelt-rngintelt-rngintelt-2)
    - [`n mod:= m: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-operation-mod-rngintelt-rngintelt-rngintelt-2)
  - [Bit Operations](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#bit-operations)
    - [`ShiftLeft(n, b): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-shiftleft-rngintelt-rngintelt)
    - [`ShiftRight(n, b): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-shiftright-rngintelt-rngintelt)
    - [`ModByPowerOf2(n, b): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-modbypowerof2-rngintelt-rngintelt)
  - [Bitwise Operations](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#bitwise-operations)
    - [`BitwiseNot(x): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-bitwisenot-rngintelt)
    - [`BitwiseAnd(x, y): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-bitwiseand-rngintelt-rngintelt)
    - [`BitwiseOr(x, y): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-bitwiseor-rngintelt-rngintelt)
    - [`BitwiseXor(x, y): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-bitwisexor-rngintelt-rngintelt)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#equality-and-membership)
    - [`m eq n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-eq-rngintelt-rngintelt)
    - [`m ne n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-ne-rngintelt-rngintelt)
    - [`n in R: RngIntElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-in-rngintelt-rng)
    - [`n notin R: RngIntElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-notin-rngintelt-rng)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#parent-and-category)
    - [`Parent(n): RngIntElt → RngInt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-parent-rngintelt)
    - [`Category(n): RngIntElt → Cat`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-category-rngintelt)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#predicates-on-ring-elements)
    - [`IsEven(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-iseven-rngintelt)
    - [`IsOdd(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isodd-rngintelt)
    - [`IsDivisibleBy(n, d): RngIntElt, RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isdivisibleby-rngintelt-rngintelt)
    - [`IsSquare(n): RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-issquare-rngintelt)
    - [`IsSquarefree(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-issquarefree-rngintelt)
    - [`IsPower(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-ispower-rngintelt)
    - [`IsPower(n, k): RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-ispower-rngintelt-rngintelt)
    - [`IsPrime(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isprime-rngintelt)
    - [Example: Primes Congruent to 3 Modulo 4](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#example-ex-687a13)
    - [`IsIntegral(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isintegral-rngintelt)
    - [`IsSinglePrecision(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-issingleprecision-rngintelt)
    - [`IsZero(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-iszero-rngintelt)
    - [`IsOne(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isone-rngintelt)
    - [`IsMinusOne(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isminusone-rngintelt)
    - [`IsNilpotent(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isnilpotent-rngintelt)
    - [`IsIdempotent(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isidempotent-rngintelt)
    - [`IsUnit(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isunit-rngintelt)
    - [`IsZeroDivisor(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-iszerodivisor-rngintelt)
    - [`IsRegular(n): RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isregular-rngint)
    - [`IsIrreducible(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isirreducible-rngintelt)
    - [`IsPrime(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isprime-rngintelt-2)
  - [Comparison of Ring Elements](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#comparison-of-ring-elements)
    - [`m gt n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-gt-rngintelt-rngintelt)
    - [`m ge n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-ge-rngintelt-rngintelt)
    - [`m lt n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-lt-rngintelt-rngintelt)
    - [`m le n: RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#operation-op-le-rngintelt-rngintelt)
    - [`Maximum(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-maximum-rngintelt-rngintelt)
    - [`Maximum(Q): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-maximum-rngintelt)
    - [`Minimum(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-minimum-rngintelt-rngintelt)
    - [`Minimum(Q): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-minimum-rngintelt)
  - [Conjugates, Norm, and Trace](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#conjugates-norm-and-trace)
    - [`ComplexConjugate(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-complexconjugate-rngintelt)
    - [`Conjugate(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-conjugate-rngintelt)
    - [`Norm(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-norm-rngintelt)
    - [`EuclideanNorm(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-euclideannorm-rngintelt)
    - [`Trace(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-trace-rngintelt)
    - [`MinimalPolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-minimalpolynomial-rngintelt)
  - [Other Elementary Functions](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#other-elementary-functions)
    - [`AbsoluteValue(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-absolutevalue-rngintelt)
    - [`Abs(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-abs-rngintelt)
    - [`Ilog2(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-ilog2-rngintelt)
    - [`Ilog(b, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-ilog-rngintelt-rngintelt)
    - [`Quotrem(m, n): RngIntElt, RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-quotrem-rngintelt-rngintelt)
    - [`Valuation(x, p): RngIntElt, RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-valuation-rngintelt-rngintelt)
    - [`Iroot(a, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-iroot-rngintelt-rngintelt)
    - [`Sign(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-sign-rngintelt)
    - [`Ceiling(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-ceiling-rngintelt)
    - [`Floor(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-floor-rngintelt)
    - [`Round(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-round-rngintelt)
    - [`Truncate(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-truncate-rngintelt)
    - [`SquarefreeFactorization(n): RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-squarefreefactorization-rngintelt)
    - [`Isqrt(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/operation-element.md#function-isqrt-rngintelt)
- [Random Numbers](https://docs.magma-maths.org/BasicRings/Integers/random.md)
  - [`Random(a, b): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-random-rngintelt-rngintelt)
  - [`Random(b): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-random-rngintelt)
  - [`RandomBits(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-randombits-rngintelt)
  - [`RandomPrime(n: parameter): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-randomprime-rngintelt)
  - [`RandomPrime(n, a, b, x: parameter): RngIntElt, RngIntElt, RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-randomprime-rngintelt-rngintelt-rngintelt)
  - [`RandomConsecutiveBits(n, a, b): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/random.md#function-randomconsecutivebits-rngintelt-rngintelt)
- [GCD and LCM](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md)
  - [`GreatestCommonDivisor(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-greatestcommondivisor-rngintelt-rngintelt)
  - [`Gcd(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-gcd-rngintelt-rngintelt)
  - [`GCD(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-gcd-rngintelt-rngintelt-2)
  - [`GreatestCommonDivisor(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-greatestcommondivisor-rngintelt)
  - [`Gcd(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-gcd-rngintelt)
  - [`GCD(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-gcd-rngintelt-2)
  - [`ExtendedGreatestCommonDivisor(m, n): RngIntElt, RngIntElt → RngIntElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-extendedgreatestcommondivisor-rngintelt-rngintelt)
  - [`Xgcd(m, n): RngIntElt, RngIntElt → RngIntElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-xgcd-rngintelt-rngintelt)
  - [`XGCD(m, n): RngIntElt, RngIntElt → RngIntElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-xgcd-rngintelt-rngintelt-2)
  - [`ExtendedGreatestCommonDivisor(s): [RngIntElt] → RngIntElt, [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-extendedgreatestcommondivisor-rngintelt)
  - [`Xgcd(s): [RngIntElt] → RngIntElt, [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-xgcd-rngintelt)
  - [`XGCD(s): [RngIntElt] → RngIntElt, [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-xgcd-rngintelt-2)
  - [`LeastCommonMultiple(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-leastcommonmultiple-rngintelt-rngintelt)
  - [`Lcm(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-lcm-rngintelt-rngintelt)
  - [`LCM(m, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-lcm-rngintelt-rngintelt-2)
  - [`LeastCommonMultiple(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-leastcommonmultiple-rngintelt)
  - [`Lcm(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-lcm-rngintelt)
  - [`LCM(s): [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/gcd-lcm.md#function-lcm-rngintelt-2)
- [Arithmetic Functions](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md)
  - [`CarmichaelLambda(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-carmichaellambda-rngintelt)
  - [`CarmichaelLambda(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-carmichaellambda-rnginteltfact)
  - [`CarmichaelLambda(Q): [Tup] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-carmichaellambda-tup)
  - [`DickmanRho(u): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-dickmanrho-fldreelt)
  - [`FactoredCarmichaelLambda(n): RngIntElt → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredcarmichaellambda-rngintelt)
  - [`FactoredCarmichaelLambda(Q): RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredcarmichaellambda-rnginteltfact)
  - [`FactoredCarmichaelLambda(Q): [Tup] → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredcarmichaellambda-tup)
  - [`DivisorSigma(i, n): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-divisorsigma-rngintelt-rngintelt)
  - [`DivisorSigma(i, Q): RngIntElt, RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-divisorsigma-rngintelt-rnginteltfact)
  - [`NumberOfDivisors(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-numberofdivisors-rngintelt)
  - [`NumberOfDivisors(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-numberofdivisors-rnginteltfact)
  - [`SumOfDivisors(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-sumofdivisors-rngintelt)
  - [`SumOfDivisors(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-sumofdivisors-rnginteltfact)
  - [`EulerPhi(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-eulerphi-rngintelt)
  - [`EulerPhi(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-eulerphi-rnginteltfact)
  - [`EulerPhi(Q): [Tup] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-eulerphi-tup)
  - [`FactoredEulerPhi(n): RngIntElt → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredeulerphi-rngintelt)
  - [`FactoredEulerPhi(Q): RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredeulerphi-rnginteltfact)
  - [`FactoredEulerPhi(Q): [Tup] → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredeulerphi-tup)
  - [`EulerPhiInverse(m): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-eulerphiinverse-rngintelt)
  - [`EulerPhiInverse(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-eulerphiinverse-rnginteltfact)
  - [`FactoredEulerPhiInverse(n): RngIntElt → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredeulerphiinverse-rngintelt)
  - [`FactoredEulerPhiInverse(Q): RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-factoredeulerphiinverse-rnginteltfact)
  - [`LegendreSymbol(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-legendresymbol-rngintelt-rngintelt)
  - [`JacobiSymbol(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-jacobisymbol-rngintelt-rngintelt)
  - [`KroneckerSymbol(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-kroneckersymbol-rngintelt-rngintelt)
  - [`MoebiusMu(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-moebiusmu-rngintelt)
  - [`MoebiusMu(Q): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#function-moebiusmu-rnginteltfact)
  - [Example: Amicable Pairs of Integers](https://docs.magma-maths.org/BasicRings/Integers/arithmetic-function.md#example-ex-233f46)
- [Combinatorial Functions](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md)
  - [`Binomial(n, r): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-binomial-rngintelt-rngintelt)
  - [`Multinomial(n, [r₁, ... rₙ]): RngIntElt, [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-multinomial-rngintelt-rngintelt)
  - [`Factorial(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-factorial-rngintelt)
  - [`IsFactorial(n): RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-isfactorial-rngintelt)
  - [`Partitions(n): RngIntElt → [ [ RngIntElt ] ]`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-partitions-rngintelt)
  - [`NumberOfPartitions(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-numberofpartitions-rngintelt)
  - [`RestrictedPartitions(n, M): RngIntElt, SetEnum → [ [ RngIntElt ] ]`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-restrictedpartitions-rngintelt-setenum)
  - [`RestrictedPartitions(n, k, M): RngIntElt, RngIntElt, SetEnum → [ [ RngIntElt ] ]`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-restrictedpartitions-rngintelt-rngintelt-setenum)
  - [`StirlingFirst(n, k): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-stirlingfirst-rngintelt-rngintelt)
  - [`StirlingSecond(n, k): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-stirlingsecond-rngintelt-rngintelt)
  - [`Bell(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-bell-rngintelt)
  - [`Fibonacci(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-fibonacci-rngintelt)
  - [`Lucas(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-lucas-rngintelt)
  - [`GeneralizedFibonacciNumber(g0, g1, n): RngIntElt, RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/combinatorics.md#function-generalizedfibonaccinumber-rngintelt-rngintelt-rngintelt)
- [Primes and Primality Testing](https://docs.magma-maths.org/BasicRings/Integers/prime.md)
  - [Primality](https://docs.magma-maths.org/BasicRings/Integers/prime.md#primality)
    - [`IsPrime(n): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-isprime-rngintelt-3)
    - [`IsPrime(n: parameter): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-isprime-rngintelt-4)
    - [`SetVerbose("ECPP", v): MonStgElt, Elt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#procedure-setverbose-monstgelt-elt-ecpp)
    - [`PrimalityCertificate(n): RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-primalitycertificate-rngintelt)
    - [`CheckCertificate(cert): SeqEnum → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-checkcertificate-seqenum)
    - [`OldCertificate(cert): SeqEnum → List`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-oldcertificate-seqenum)
    - [`IsProbablePrime(n: parameter): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-isprobableprime-rngintelt)
    - [`IsProbablyPrime(n: parameter): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-isprobablyprime-rngintelt)
    - [`IsPrimePower(n): RngIntElt → BoolElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-isprimepower-rngintelt)
    - [Example: Probable Repunit Primes](https://docs.magma-maths.org/BasicRings/Integers/prime.md#example-ex-ca5938)
  - [Other Functions Relating to Primes](https://docs.magma-maths.org/BasicRings/Integers/prime.md#other-functions-relating-to-primes)
    - [`NextPrime(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-nextprime-rngintelt)
    - [`NextPrime(n: parameter): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-nextprime-rngintelt-2)
    - [`PreviousPrime(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-previousprime-rngintelt)
    - [`PreviousPrime(n: parameter): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-previousprime-rngintelt-2)
    - [`PrimesUpTo(B): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-primesupto-rngintelt)
    - [`PrimesInInterval(b, e): RngIntElt, RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-primesininterval-rngintelt-rngintelt)
    - [`NthPrime(n): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-nthprime-rngintelt)
    - [`RandomPrime(n: parameter): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-randomprime-rngintelt-2)
    - [`RandomPrime(n, a, b, x: parameter): RngIntElt, RngIntElt, RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-randomprime-rngintelt-rngintelt-rngintelt-2)
    - [`PrimeBasis(n): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-primebasis-rngintelt)
    - [`PrimeDivisors(n): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/prime.md#function-primedivisors-rngintelt)
- [Factorization](https://docs.magma-maths.org/BasicRings/Integers/factor.md)
  - [General Factorization](https://docs.magma-maths.org/BasicRings/Integers/factor.md#general-factorization)
    - [`SetVerbose("Factorization", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-setverbose-monstgelt-rngintelt-factorization)
    - [`Factorization(n): RngIntElt → RngIntEltFact, RngIntElt, SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-factorization-rngintelt)
    - [`Factorisation(n): RngIntElt → RngIntEltFact, RngIntElt, SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-factorisation-rngintelt)
    - [`Factorization(n: parameters): RngIntElt → RngIntEltFact, RngIntElt, SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-factorization-rngintelt-2)
    - [`Factorisation(n: parameters): RngIntElt → RngIntEltFact, RngIntElt, SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-factorisation-rngintelt-2)
  - [Storing Potential Factors](https://docs.magma-maths.org/BasicRings/Integers/factor.md#storing-potential-factors)
    - [`StoreFactor(n): RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-storefactor-rngintelt)
    - [`StoreFactor(S): [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-storefactor-rngintelt-2)
    - [`GetStoredFactors() → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-getstoredfactors)
    - [`ClearStoredFactors()`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-clearstoredfactors)
  - [Specific Factorization Algorithms](https://docs.magma-maths.org/BasicRings/Integers/factor.md#specific-factorization-algorithms)
    - [`SetVerbose("Cunningham", b): MonStgElt, BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-setverbose-monstgelt-boolelt-cunningham)
    - [`SetVerbose("ECM", b): MonStgElt, Elt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-setverbose-monstgelt-elt-ecm)
    - [`SetVerbose("MPQS", b): MonStgElt, Elt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-setverbose-monstgelt-elt-mpqs)
    - [`Cunningham(b, k, c): RngIntElt, RngIntElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-cunningham-rngintelt-rngintelt-rngintelt)
    - [`AssertAttribute(RngInt, "CunninghamStorageLimit", l): Cat, MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#procedure-assertattribute-cat-monstgelt-rngintelt-cunninghamstoragelimit)
    - [`TrialDivision(n): RngIntElt → RngIntEltFact, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-trialdivision-rngintelt)
    - [`TrialDivision(n, B): RngIntElt, RngIntElt → RngIntEltFact, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-trialdivision-rngintelt-rngintelt)
    - [`PollardRho(n): RngIntElt → RngIntEltFact, [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-pollardrho-rngintelt)
    - [`PollardRho(n, c, s, k): RngIntElt, RngIntElt, RngIntElt, RngIntElt → RngIntEltFact, [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-pollardrho-rngintelt-rngintelt-rngintelt-rngintelt)
    - [`pMinus1(n, B1): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-pminus1-rngintelt-rngintelt)
    - [`pPlus1(n, B1): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-pplus1-rngintelt-rngintelt)
    - [`SQUFOF(n): RngIntElt → RngIntEltFact, [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-squfof-rngintelt)
    - [`SQUFOF(n, k): RngIntElt, RngIntElt → RngIntEltFact, [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-squfof-rngintelt-rngintelt)
    - [`ECM(n, B1): RngIntElt, RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-ecm-rngintelt-rngintelt)
    - [`ECMSteps(n, L, U): RngIntElt, RngIntElt, RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-ecmsteps-rngintelt-rngintelt-rngintelt)
    - [`MPQS(n): RngIntElt → RngIntEltFact, [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-rngint-mpqs)
  - [Factorization Related Functions](https://docs.magma-maths.org/BasicRings/Integers/factor.md#factorization-related-functions)
    - [`ECMOrder(p, s): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-ecmorder-rngintelt-rngintelt)
    - [`ECMFactoredOrder(p, s): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-ecmfactoredorder-rngintelt-rngintelt)
    - [`PrimeBasis(n): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-primebasis-rngintelt-2)
    - [`PrimeDivisors(n): RngIntElt → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-primedivisors-rngintelt-2)
    - [`Divisors(n): RngIntElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-divisors-rngintelt)
    - [`Divisors(f): RngIntEltFact → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-divisors-rnginteltfact)
    - [`CoprimeBasis(S): [ RngIntElt ] → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-coprimebasis-rngintelt)
    - [`CoprimeBasis(S): { RngIntElt } → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-coprimebasis-rngintelt-2)
    - [Example: Perfect Numbers](https://docs.magma-maths.org/BasicRings/Integers/factor.md#example-ex-07a3e8)
    - [`PartialFactorization(S): [ RngIntElt ] → [ RngIntEltFact ]`](https://docs.magma-maths.org/BasicRings/Integers/factor.md#function-partialfactorization-rngintelt)
    - [Example: Partial Factorization](https://docs.magma-maths.org/BasicRings/Integers/factor.md#example-ex-15e5a0)
- [Factorization Sequences](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md)
  - [Creation and Conversion](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#creation-and-conversion)
    - [`Facint(f): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-facint-rnginteltfact)
    - [`FactorizationToInteger(f): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-factorizationtointeger-rnginteltfact)
    - [`SeqFact(s): SeqEnum → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-seqfact-seqenum)
    - [`SequenceToFactorization(s): SeqEnum → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-sequencetofactorization-seqenum)
    - [`Eltseq(f): RngIntEltFact → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-eltseq-rnginteltfact)
    - [`ElementToSequence(f): RngIntEltFact → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-elementtosequence-rnginteltfact)
  - [Arithmetic](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#arithmetic)
    - [`s + t: RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#operation-op-plus-rnginteltfact-rnginteltfact)
    - [`s - t: RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#operation-op-minus-rnginteltfact-rnginteltfact)
    - [`s * t: RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#operation-op-times-rnginteltfact-rnginteltfact)
    - [`s / t: RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#operation-op-div-rnginteltfact-rnginteltfact)
    - [`s ^ k: RngIntEltFact, RngIntElt → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#operation-op-pow-rnginteltfact-rngintelt)
  - [Divisors](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#divisors)
    - [`Lcm(s, t): RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-lcm-rnginteltfact-rnginteltfact)
    - [`Gcd(s, t): RngIntEltFact, RngIntEltFact → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-gcd-rnginteltfact-rnginteltfact)
    - [`SquarefreeFactorization(f): RngIntEltFact → RngIntEltFact, RngIntEltFact`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-squarefreefactorization-rnginteltfact)
    - [`MoebiusMu(f): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-moebiusmu-rnginteltfact-2)
    - [`Divisors(f): RngIntEltFact → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-divisors-rnginteltfact-2)
    - [`PrimeDivisors(f): RngIntEltFact → SeqEnum`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-primedivisors-rnginteltfact)
    - [`NumberOfDivisors(f): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-numberofdivisors-rnginteltfact-2)
    - [`SumOfDivisors(f): RngIntEltFact → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-sumofdivisors-rnginteltfact-2)
  - [Predicates](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#predicates)
    - [`IsOne(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-isone-rnginteltfact)
    - [`IsOdd(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-isodd-rnginteltfact)
    - [`IsEven(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-iseven-rnginteltfact)
    - [`IsUnit(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-isunit-rnginteltfact)
    - [`IsPrime(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-isprime-rnginteltfact)
    - [`IsPrimePower(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-isprimepower-rnginteltfact)
    - [`IsSquare(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-issquare-rnginteltfact)
    - [`IsSquarefree(s): RngIntEltFact → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/factorization-sequence.md#function-issquarefree-rnginteltfact)
- [Modular Arithmetic](https://docs.magma-maths.org/BasicRings/Integers/modular.md)
  - [Arithmetic Operations](https://docs.magma-maths.org/BasicRings/Integers/modular.md#arithmetic-operations)
    - [`Modexp(n, k, m): RngIntElt, RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-modexp-rngintelt-rngintelt-rngintelt)
    - [`n mod m: RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#operation-operation-mod-rngintelt-rngintelt-rngintelt)
    - [`Modinv(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-modinv-rngintelt-rngintelt)
    - [`InverseMod(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-inversemod-rngintelt-rngintelt)
    - [`Modsqrt(n, m): RngIntElt, RngIntElt → BoolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-modsqrt-rngintelt-rngintelt)
    - [`Modorder(n, m): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-modorder-rngintelt-rngintelt)
    - [`IsPrimitive(n, m): RngIntElt, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-isprimitive-rngintelt-rngintelt)
    - [`PrimitiveRoot(m): RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-primitiveroot-rngintelt)
  - [The Solution of Modular Equations](https://docs.magma-maths.org/BasicRings/Integers/modular.md#the-solution-of-modular-equations)
    - [`Solution(a, b, m): RngIntElt, RngIntElt, RngIntElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-solution-rngintelt-rngintelt-rngintelt)
    - [`ChineseRemainderTheorem(X, N): [RngIntElt], [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-chineseremaindertheorem-rngintelt-rngintelt)
    - [`CRT(X, N): [RngIntElt], [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-crt-rngintelt-rngintelt)
    - [`Solution(A, B, N): [RngIntElt], [RngIntElt], [RngIntElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-solution-rngintelt-rngintelt-rngintelt-2)
    - [`NormEquation(d, m): RngIntElt, RngIntElt → BoolElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-normequation-rngintelt-rngintelt)
    - [`NormEquation(d, m: parameters)): RngIntElt, RngIntElt → BoolElt, RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/modular.md#function-normequation-rngintelt-rngintelt-2)
    - [Example: Norm Equation](https://docs.magma-maths.org/BasicRings/Integers/modular.md#example-ex-a39523)
- [Infinities](https://docs.magma-maths.org/BasicRings/Integers/infinity.md)
  - [Creation](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#creation)
    - [`Infinity() → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-infinity)
    - [`MinusInfinity() → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-minusinfinity)
  - [Arithmetic](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#arithmetic)
    - [`- x: Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-operation-infty-infty)
    - [`x + y: Infty, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-plus-infty-infty)
    - [`x + y: Infty, RngIntElt → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-plus-infty-rngintelt)
    - [`x + y: RngIntElt, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-plus-rngintelt-infty)
    - [`x - y: Infty, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-minus-infty-infty)
    - [`x - y: Infty, RngIntElt → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-minus-infty-rngintelt)
    - [`x - y: RngIntElt, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-minus-rngintelt-infty)
    - [`x * y: Infty, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-times-infty-infty)
    - [`x * y: Infty, RngIntElt → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-times-infty-rngintelt)
    - [`x * y: RngIntElt, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-times-rngintelt-infty)
    - [`x / y: RngIntElt, Infty → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-div-rngintelt-infty)
    - [`x / y: Infty, RngIntElt → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-div-infty-rngintelt)
    - [`x ^ n: Infty, Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-pow-infty-infty)
    - [`x ^ n: Infty, RngIntElt → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-pow-infty-rngintelt)
  - [Comparison](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#comparison)
    - [`x eq y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-eq-infty-infty)
    - [`x eq y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-eq-infty-rngintelt)
    - [`x eq y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-eq-rngintelt-infty)
    - [`x ne y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ne-infty-infty)
    - [`x ne y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ne-infty-rngintelt)
    - [`x ne y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ne-rngintelt-infty)
    - [`x lt y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-lt-infty-infty)
    - [`x lt y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-lt-infty-rngintelt)
    - [`x lt y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-lt-rngintelt-infty)
    - [`x le y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-le-infty-infty)
    - [`x le y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-le-infty-rngintelt)
    - [`x le y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-le-rngintelt-infty)
    - [`x gt y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-gt-infty-infty)
    - [`x gt y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-gt-infty-rngintelt)
    - [`x gt y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-gt-rngintelt-infty)
    - [`x ge y: Infty, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ge-infty-infty)
    - [`x ge y: Infty, RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ge-infty-rngintelt)
    - [`x ge y: RngIntElt, Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#operation-op-ge-rngintelt-infty)
    - [`Maximum(x, y): Infty, Infty → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-maximum-infty-infty)
    - [`Maximum(x, y): Infty, RngIntElt → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-maximum-infty-rngintelt)
    - [`Maximum(x, y): RngIntElt, Infty → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-maximum-rngintelt-infty)
    - [`Minimum(x, y): Infty, Infty → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-minimum-infty-infty)
    - [`Minimum(x, y): Infty, RngIntElt → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-minimum-infty-rngintelt)
    - [`Minimum(x, y): RngIntElt, Infty → .`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-minimum-rngintelt-infty)
  - [Miscellaneous](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#miscellaneous)
    - [`Sign(x): Infty → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-sign-infty)
    - [`Abs(x): Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-abs-infty)
    - [`AbsoluteValue(x): Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-absolutevalue-infty)
    - [`Round(x): Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-round-infty)
    - [`Floor(x): Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-floor-infty)
    - [`Ceiling(x): Infty → Infty`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-ceiling-infty)
    - [`IsFinite(x): Infty → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-isfinite-infty)
    - [`IsFinite(x): RngIntElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Integers/infinity.md#function-isfinite-rngintelt)
- [Advanced Factorization Techniques: The Number Field Sieve](https://docs.magma-maths.org/BasicRings/Integers/nfs.md)
  - [The Magma Number Field Sieve Implementation](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#the-magma-number-field-sieve-implementation)
    - [`SetVerbose("NFS", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#procedure-setverbose-monstgelt-rngintelt-nfs)
  - [Naive NFS](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#naive-nfs)
    - [`NumberFieldSieve(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-numberfieldsieve-rngintelt-rngmpolelt-rngintelt-rngintelt)
    - [`NFS(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-nfs-rngintelt-rngmpolelt-rngintelt-rngintelt)
  - [Factoring with NFS Processes](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#factoring-with-nfs-processes)
    - [`NFSProcess(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt → NFSProc`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-nfsprocess-rngintelt-rngmpolelt-rngintelt-rngintelt)
    - [Example: NFS Process Attributes](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-53bcfa)
    - [Attribute Selection](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#attribute-selection)
      - [Example: NFS Attributes for a 70-Digit Number](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-25ef84)
      - [Example: NFS Attributes for an 80-Digit Number](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-9e7234)
      - [Example: NFS Attributes for an 87-Digit Number](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-7d7073)
    - [The Sieving Stage](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#the-sieving-stage)
      - [`NumberOfRelationsRequired(P): NFSProc → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-numberofrelationsrequired-nfsproc)
      - [`FindRelations(P): NFSProc → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-findrelations-nfsproc)
    - [The Auxiliary Data Stage](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#the-auxiliary-data-stage)
      - [`CreateCycleFile(P): NFSProc → .`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-createcyclefile-nfsproc)
      - [`CycleCount(P): NFSProc → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-cyclecount-nfsproc)
      - [`CycleCount(fn): MonStgElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-cyclecount-monstgelt)
      - [`CreateCharacterFile(P): NFSProc → .`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-createcharacterfile-nfsproc)
      - [`CreateCharacterFile(P, cc): NFSProc, RngIntElt → .`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-createcharacterfile-nfsproc-rngintelt)
    - [Finding Dependencies: the Linear Algebra Stage](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#finding-dependencies-the-linear-algebra-stage)
      - [`FindDependencies(P): NFSProc → .`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-finddependencies-nfsproc)
    - [The Factorization Stage](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#the-factorization-stage)
      - [`Factor(P): NFSProc → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-factor-nfsproc)
      - [`Factor(P,k): NFSProc, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-factor-nfsproc-rngintelt)
  - [Data Files](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#data-files)
    - [`RemoveFiles(P): NFSProc → .`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-removefiles-nfsproc)
    - [`MergeFiles(S, fn): [MonStgElt], MonStgElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-mergefiles-monstgelt-monstgelt)
    - [Magma Native NFS Data Files](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#magma-native-nfs-data-files)
  - [Distributing NFS Factorizations](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#distributing-nfs-factorizations)
    - [Example: Distributed NFS Factorization](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-dc02d5)
  - [Magma and CWI NFS Interoperability](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#magma-and-cwi-nfs-interoperability)
    - [`FindRelationsInCWIFormat(P): NFSProc → RngIntElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-findrelationsincwiformat-nfsproc)
    - [`ConvertToCWIFormat(P, pb): NFSProc, RngIntElt → .;`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-converttocwiformat-nfsproc-rngintelt)
  - [Tools for Finding a Suitable Polynomial](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#tools-for-finding-a-suitable-polynomial)
    - [`BaseMPolynomial(n, m, d): RngIntElt, RngIntElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-basempolynomial-rngintelt-rngintelt-rngintelt)
    - [`MurphyAlphaApproximation(F, b): RngMPolElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-murphyalphaapproximation-rngmpolelt-rngintelt)
    - [`OptimalSkewness(F): RngMPolElt → FldReElt, FldReElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-optimalskewness-rngmpolelt)
    - [Example: Finding a Good NFS Polynomial](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#example-ex-112b3b)
    - [`BestTranslation(F, m, a): RngMPolElt, RngIntElt, FldReElt, FldReElt → RngMPolElt, RngIntElt, FldReElt, FldReElt`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-besttranslation-rngmpolelt-rngintelt-fldreelt-fldreelt)
    - [`PolynomialSieve(F, m, J0, J1, MaxAlpha): RngMPolElt, RngIntElt, RngIntElt, RngIntElt, FldReElt → List`](https://docs.magma-maths.org/BasicRings/Integers/nfs.md#function-polynomialsieve-rngmpolelt-rngintelt-rngintelt-rngintelt-fldreelt)
- [Bibliography](https://docs.magma-maths.org/BasicRings/Integers/bibliography.md)

### Introduction

This Chapter describes the operators and functions for working with the ring of rational integers ${\mathbb{Z}}$. Integers are the most commonly used objects in Magma. They can be created by just typing in the literal (decimal) digits. Integers thus created are elements of the ring of integers which is automatically created when Magma is started up. There is just one single object ‘integer ring’ around, but references to it (new ‘names’ for it) can be created using the `IntegerRing` function.

#### Representation

Since large integers occur so frequently, the first requirement for a computer algebra system is to support fast arithmetic for integers of arbitrary size. Indeed, within the bounds set by the available memory, it is possible to operate reasonably efficiently with integers of any number of decimal digits. Although it is well possible to use the integer facilities without being aware of the internal representation of (large) integers, it is sometimes useful to know how integers are stored. The most important fact is that integers smaller than $2^{30}=1073741824$ in absolute value are ‘single precision’, and in many circumstances such ‘small integers’ allow considerably faster arithmetic (they are treated slightly differently internally and escape the overhead of memory management used to deal with multi-precision integers).

#### Coercion

Integers will be automatically coerced into almost every unitary ring $R$ using the identification of $1$ and $1_R$. This means that integer arguments are allowed for almost any ring element function, and that it is not necessary to convert an integer before applying binary operators (such as $+$) on a combination of arguments consisting of an integer and another ring element. For more on coercion we refer to Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro).

#### Homomorphisms

Ring homomorphisms are required to be unitary. Therefore, to specify a homomorphism with the integers as its domain requires merely the specification of the codomain.

<a id="constructor-constructor-hom-rngint-rng-map"></a>
##### `hom< Z -> R | >: RngInt, Rng -> Map`

The natural homomorphism from ${\mathbb{Z}}$ to the ring $R$.

<a id="example-ex-a58966"></a>
##### `Example: Homomorphism from the Integers to a Matrix Ring (ex-a58966)`

```magma
> h := hom< Integers() -> MatrixRing(RealField(12), 3) | >;
> h(2)^-1;
[0.5   0   0]
[  0 0.5   0]
[  0   0 0.5]
```

### Creation Functions

#### Creation of Structures

The ring of integers is automatically created when Magma is first loaded. The ring may be formally created (and, if desired, assigned to a variable) using the function `IntegerRing()`. Subrings of ${\mathbb{Z}}$ are always ideals; see the section on ideals for details.

<a id="function-integerring"></a>
##### `IntegerRing() -> RngInt`

<a id="function-integers"></a>
##### `Integers() -> RngInt`

<a id="function-ringofintegers"></a>
##### `RingOfIntegers() -> RngInt`

<a id="function-integerring-fldrat"></a>
##### `IntegerRing(Q): FldRat -> RngInt`

<a id="function-integers-fldrat"></a>
##### `Integers(Q): FldRat -> RngInt`

<a id="function-ringofintegers-fldrat"></a>
##### `RingOfIntegers(Q): FldRat -> RngInt`

Create the ring of integers ${\mathbb{Z}}$.

#### Creation of Elements

Since the ring of integers is present when Magma is started up, integers typed into Magma without any explicit context will be regarded as elements of the ring of integers. Integers can be specified using decimal, hexadecimal, and binary notation.

<a id="literal-literal-integer-literal-a1a2-ar"></a>
##### `a₁a₂...aᵣ`

Given a succession of decimal digits $a_1, \ldots, a_r$, create the corresponding integer. Leading zeros will be ignored.

<a id="literal-literal-integer-literal-hexadecimal-0xa1a2-ar"></a>
##### `0xa₁a₂...aᵣ`

Given a succession of hexadecimal digits $a_1, \ldots, a_r$, create the corresponding integer. Leading zeros will be ignored.

<a id="literal-literal-integer-literal-binary-0ba1a2-ar"></a>
##### `0ba₁a₂...aᵣ`

Given a succession of binary digits $a_1, \ldots, a_r$, create the corresponding integer. Leading zeros will be ignored.

<a id="constructor-constructor-elt-rngint-rngintelt-rngintelt"></a>
##### `elt< Z | a₁a₂...aᵣ >: RngInt, RngIntElt -> RngIntElt`

Given a succession of decimal digits $a_1, \ldots, a_r$, create the corresponding integer as an element of $Z$.

<a id="constructor-constructor-elt-rngint-rngintelt-rngintelt-2"></a>
##### `elt< Z | 0xa₁a₂...aᵣ >: RngInt, RngIntElt -> RngIntElt`

Given a succession of hexadecimal digits $a_1, \ldots, a_r$, create the corresponding integer as an element of $Z$.

<a id="constructor-constructor-elt-rngint-rngintelt-rngintelt-3"></a>
##### `elt< Z | 0ba₁a₂...aᵣ >: RngInt, RngIntElt -> RngIntElt`

Given a succession of binary digits $a_1, \ldots, a_r$, create the corresponding integer as an element of $Z$.

<a id="operation-op-rngint-rngelt"></a>
##### `Z ! a: RngInt, RngElt -> RngIntElt`

<a id="operation-op-rngint-rngelt-2"></a>
##### `Z ! [a]: RngInt, [RngElt] -> RngIntElt`

Coerce the ring element $a$ into the ring of integers $Z$. The element $a$ is allowed to be an element of the ring of integers modulo $m$ (in which case the result $r$ satisfies $0 \leq r < m$), or an element of a finite field (in which case the result $r$ satisfies $0 \leq r < p$ if $a$ is in the prime field, of characteristic $p$, and an error otherwise), or an element of the integers, rationals, a quadratic field, a cyclotomic field, or a number field (in which cases the result is the obvious integer if $a$ is integral and an error otherwise).

<a id="example-ex-2fa3b0"></a>
##### `Example: Creating Integers (ex-2fa3b0)`

```magma
> Z := IntegerRing();
> n := 1234567890;
> n in Z;
true
> m := elt< Z | 1234567890 >;
> m eq n;
true
> l := Z ! elt< QuadraticField(3) | 1234567890, 0>;
> l;
1234567890
> k := elt< Z | 0x499602D2 >;
1234567890
> b := 0b1001001100101100000001011010010;
> b eq n;
true
> c := elt< Z | 0b1001001100101100000001011010010 >;
> c eq n;
true
```

<a id="function-one-rngint"></a>
##### `One(Z): RngInt -> RngIntElt`

<a id="function-identity-rngint"></a>
##### `Identity(Z): RngInt -> RngIntElt`

<a id="function-zero-rngint"></a>
##### `Zero(Z): RngInt -> RngIntElt`

<a id="function-representative-rngint"></a>
##### `Representative(Z): RngInt -> RngIntElt`

These generic functions (cf. Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro)) create $1$, $1$, $0$, and $0$ respectively, in the integer ring ${\mathbb{Z}}$.

#### Printing of Elements

Magma supports the printing of integers in both decimal and hexadecimal form. The default print method is to print integers in base 10; base 16 printing is performed using the `Hex` print level.

<a id="example-ex-47136f"></a>
##### `Example: Printing in Hexadecimal (ex-47136f)`

```magma
> n := 1234567890;
> n;
1234567890
> n:Hex;
0x499602D2
```

#### Element Conversions

<a id="function-factorizationtointeger-rngintelt-rngintelt"></a>
##### `FactorizationToInteger(s): [ <RngIntElt, RngIntElt> ] -> RngIntElt`

<a id="function-factorisationtointeger-rngintelt-rngintelt"></a>
##### `FactorisationToInteger(s): [ <RngIntElt, RngIntElt> ] -> RngIntElt`

<a id="function-facint-rngintelt-rngintelt"></a>
##### `Facint(s): [ <RngIntElt, RngIntElt> ] -> RngIntElt`

Given a sequence of two-element tuples $s=[ <p_1, k_1>, ..., <p_r, k_r> ]$ containing pairs of integers $<p_i, k_i>$, $1 \leq i \leq r$, with $k_i$ non-negative, this function returns the integer $p_1^{k_1} \cdots p_r^{k_r}$. It is normally used for converting a factorization sequence to the corresponding integer.

<a id="function-integertosequence-rngintelt-rngintelt"></a>
##### `IntegerToSequence(n, b): RngIntElt, RngIntElt -> [RngIntElt]`

<a id="function-intseq-rngintelt-rngintelt"></a>
##### `Intseq(n, b): RngIntElt, RngIntElt -> [RngIntElt]`

Given a non-negative integer $n$ and a positive integer $b\geq 2$, return the unique base $b$ representation of $n$ in the form of a sequence $Q$. That is, if $n = a_0b^0 + a_1b^1 + \ldots + a_{k-1}b^{k-1}$ with $0\leq a_i<b$ and $a_{k-1}> 0$, then $Q = [ a_0, a_1, \ldots, a_{k-1} ]$. (If $n=0$, then $Q=[\,]$.)

<a id="function-sequencetointeger-rngintelt-rngintelt"></a>
##### `SequenceToInteger(s, b): [RngIntElt], RngIntElt -> RngIntElt`

<a id="function-seqint-rngintelt-rngintelt"></a>
##### `Seqint(s, b): [RngIntElt], RngIntElt -> RngIntElt`

Given a positive integer $b\geq 2$ and a sequence $Q = [ a_0, \ldots, a_{k-1} ]$ of non-negative integers such that $0 \leq a_i < b$, return the integer $n = a_0b^0 + a_1b^1 + \ldots + a_{k-1}b^{k-1}$. If $Q$ is the empty sequence, the integer zero is returned. This function performs the inverse operation of the base $b$ representation.

<a id="function-integertostring-rngintelt"></a>
##### `IntegerToString(n): RngIntElt -> ModStgElt`

Create the string consisting of the decimal digits of the integer $n$. In the case in which $n$ is negative the first character will be the minus sign.

<a id="function-integertostring-rngintelt-rngintelt"></a>
##### `IntegerToString(n, b): RngIntElt, RngIntElt -> ModStgElt`

Create the string consisting of the digits of the integer $n$ in base $b$. In the case in which $n$ is negative the first character will be the minus sign. The base $b$ can be between 2 and 36. For $b \le 10$, the digits are represented numerically. For $b > 10$, the digits are represented both numerically and alphabetically, so that, 10 is ‘A’, 11 is ‘B’, et cetera.

<a id="function-eltseq-rngintelt"></a>
##### `Eltseq(n): RngIntElt -> [RngIntElt]`

The sequence $[n]$ which can be coerced back into ${\mathbb{Z}}$.

<a id="function-denominator-rngintelt"></a>
##### `Denominator(n): RngIntElt -> RngIntElt`

The denominator of $n$, i.e., $1$.

### Structure Operations

The following generic ring functions are applicable to the ring of integers and its elements.

#### Related Structures

<a id="function-category-rngint"></a>
##### `Category(Z): RngInt -> Cat`

<a id="function-parent-rngint"></a>
##### `Parent(Z): RngInt -> PowerStructure`

<a id="function-primering-rngint"></a>
##### `PrimeRing(Z): RngInt -> RngInt`

<a id="function-center-rngint"></a>
##### `Center(Z): RngInt -> RngInt`

<a id="function-additivegroup-rngint"></a>
##### `AdditiveGroup(Z): RngInt -> GrpAb, Map`

Create the abelian group of integers under addition. This returns an infinite (additive) abelian group $A$ of rank 1 together with a map from $A$ to the ring of integers $Z$, sending $A.1$ to $1$.

<a id="function-multiplicativegroup-rngint"></a>
##### `MultiplicativeGroup(Z): RngInt -> GrpAb, Map`

<a id="function-unitgroup-rngint"></a>
##### `UnitGroup(Z): RngInt -> GrpAb, Map`

Create the abelian group of invertible integers, that is, an abelian group isomorphic to the multiplicative subgroup $\langle -1\rangle$. This returns an (additive) abelian group $A$ of order $2$ together with a map from $A$ to the ring of integers $Z$, sending $A.1$ to $-1$.

<a id="function-classgroup-rngint"></a>
##### `ClassGroup(Z): RngInt -> GrpAb, Map`

The class group of the ring of ${\mathbb{Z}}$ (which is trivial).

<a id="function-fieldoffractions-rngint"></a>
##### `FieldOfFractions(Z): RngInt -> FldRat`

Create the field of fractions ${\mathbb{Q}}$ of the ring of rational integers.

<a id="constructor-constructor-sub-rngint-rngintelt-rngint"></a>
##### `sub< Z | n >: RngInt, RngIntElt -> RngInt`

Given $Z$, the ring of integers or an ideal of it, and an element $n$ of $Z$, create the ideal $aZ\cap Z$ of the ring of integers. Note that this creates an ideal, not just a subring.

#### Numerical Invariants

<a id="function-characteristic-rngint"></a>
##### `Characteristic(Z): RngInt -> RngIntElt`

<a id="function-signature-rngint"></a>
##### `Signature(Z): RngInt -> RngIntElt, RngIntElt`

The signature of ${\mathbb{Z}}$ as an order of ${\mathbb{Q}}$, i.e. `1, 0`.

#### Ring Predicates and Booleans

<a id="function-iscommutative-rngint"></a>
##### `IsCommutative(Z): RngInt -> BoolElt`

<a id="function-isunitary-rngint"></a>
##### `IsUnitary(Z): RngInt -> BoolElt`

<a id="function-isfinite-rngint"></a>
##### `IsFinite(Z): RngInt -> BoolElt`

<a id="function-isordered-rngint"></a>
##### `IsOrdered(Z): RngInt -> BoolElt`

<a id="function-isfield-rngint"></a>
##### `IsField(Z): RngInt -> BoolElt`

<a id="function-iseuclideandomain-rngint"></a>
##### `IsEuclideanDomain(Z): RngInt -> BoolElt`

<a id="function-ispid-rngint"></a>
##### `IsPID(Z): RngInt -> BoolElt`

<a id="function-isufd-rngint"></a>
##### `IsUFD(Z): RngInt -> BoolElt`

<a id="function-isdivisionring-rngint"></a>
##### `IsDivisionRing(Z): RngInt -> BoolElt`

<a id="function-iseuclideanring-rngint"></a>
##### `IsEuclideanRing(Z): RngInt -> BoolElt`

<a id="function-isprincipalidealring-rngint"></a>
##### `IsPrincipalIdealRing(Z): RngInt -> BoolElt`

<a id="function-isdomain-rngint"></a>
##### `IsDomain(Z): RngInt -> BoolElt`

<a id="operation-op-eq-rngint-rng"></a>
##### `Z eq R: RngInt, Rng -> BoolElt`

<a id="operation-op-ne-rngint-rng"></a>
##### `Z ne R: RngInt, Rng -> BoolElt`

### Element Operations

#### Arithmetic Operations

Magma includes both the Karatsuba algorithm and the Schönhage-Strassen FFT-based algorithm for the multiplication of integers ([[AHU74](https://docs.magma-maths.org/references.md#cite-ahohopcroftullman), Chap. 7], [[vzGG99](https://docs.magma-maths.org/references.md#cite-gathengerhard), Sec. 8.3]). The crossover point (where the FFT method beats the Karatsuba method) is currently $2^{15}$ bits (approx. 10000 decimal digits) on Sun SPARC workstations and $2^{17}$ bits (approx. 40000 decimal digits) on Digital Alpha workstations. Assembler macros are used for critical operations and 64-bit operations are used on DEC-Alpha machines.

Magma also contains an asymptotically-fast integer (and polynomial) division algorithm which reduces division to multiplication with a constant scale factor that is in the practical range. Thus division of integers and polynomials are based on the Karatsuba and Schönhage-Strassen (FFT) methods when applicable. The crossover point for integer division (when the new method outperforms the classical method) is currently at the point of dividing a $2^{12}$ bit (approx. 1200 decimal digit) integer by a $2^{11}$ (approx. 600 decimal digit) integer on Sun SPARC workstations.

<a id="operation-operation-rngintelt-rngintelt"></a>
##### `+ n: RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-2"></a>
##### `- n: RngIntElt -> RngIntElt`

<a id="operation-op-plus-rngintelt-rngintelt"></a>
##### `m + n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-op-minus-rngintelt-rngintelt"></a>
##### `m - n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-op-times-rngintelt-rngintelt"></a>
##### `m * n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-op-pow-rngintelt-rngintelt"></a>
##### `n ^ k: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-op-div-rngintelt-rngintelt"></a>
##### `m / n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt"></a>
##### `m +:= n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-2"></a>
##### `m -:= n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-3"></a>
##### `m *:= n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-4"></a>
##### `m /:= n: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-5"></a>
##### `m ^:= k: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-div-rngintelt-rngintelt-rngintelt"></a>
##### `n div m: RngIntElt, RngIntElt -> RngIntElt`

The quotient $q$ of the division with remainder $n=qm+r$, where $0\leq r<m$ or $m<r\leq 0$ (depending on the sign of $m$), for integers $n$ and $m\neq 0$.

<a id="operation-operation-mod-rngintelt-rngintelt-rngintelt"></a>
##### `n mod m: RngIntElt, RngIntElt -> RngIntElt`

The remainder $r$ of the division with remainder $n=qm+r$, where $0\leq r<m$ or $m<r\leq 0$ (depending on the sign of $m$), for integers $n$ and $m\neq 0$.

<a id="function-exactquotient-rngintelt-rngintelt"></a>
##### `ExactQuotient(n, d): RngIntElt, RngIntElt -> RngIntElt`

Assuming that the integer $n$ is exactly divisible by the integer $d$, return the exact quotient of $n$ by $d$ (as an integer). An error results if $d$ does not divide $n$ exactly.

<a id="operation-operation-div-rngintelt-rngintelt-rngintelt-2"></a>
##### `n div:= m: RngIntElt, RngIntElt -> RngIntElt`

<a id="operation-operation-mod-rngintelt-rngintelt-rngintelt-2"></a>
##### `n mod:= m: RngIntElt, RngIntElt -> RngIntElt`

#### Bit Operations

The following functions use bit operations on the internal representation, so are in general quicker than using the usual arithmetic operators.

<a id="function-shiftleft-rngintelt-rngintelt"></a>
##### `ShiftLeft(n, b): RngIntElt, RngIntElt -> RngIntElt`

Given integers $n$ and $b$, with $b\ge 0$, return $n \times 2^b$.

<a id="function-shiftright-rngintelt-rngintelt"></a>
##### `ShiftRight(n, b): RngIntElt, RngIntElt -> RngIntElt`

Given integers $n$ and $b$, with $b\ge 0$, return $n$ `div` $2^b$.

<a id="function-modbypowerof2-rngintelt-rngintelt"></a>
##### `ModByPowerOf2(n, b): RngIntElt, RngIntElt -> RngIntElt`

Given integers $n$ and $b$, with $b\ge 0$, return $n \bmod 2^b$ (so the result is always non-negative).

#### Bitwise Operations

The following functions apply logical operators to integers by interpreting them as sequences of bits. Note that the (implicitly infinite) 2-adic expansion of these integers is used, which enables consistent handling of negative integers. In particular, the `BitwiseNot` of a non-negative integer will be negative, and vice versa.

<a id="function-bitwisenot-rngintelt"></a>
##### `BitwiseNot(x): RngIntElt -> RngIntElt`

The integer whose 2-adic representation is the bitwise ‘not’ of the 2-adic representation of $x$.

<a id="function-bitwiseand-rngintelt-rngintelt"></a>
##### `BitwiseAnd(x, y): RngIntElt, RngIntElt -> RngIntElt`

The integer whose 2-adic representation is the bitwise ‘and’ of the 2-adic representations of $x$ and $y$.

<a id="function-bitwiseor-rngintelt-rngintelt"></a>
##### `BitwiseOr(x, y): RngIntElt, RngIntElt -> RngIntElt`

The integer whose 2-adic representation is the bitwise ‘or’ of the 2-adic representations of $x$ and $y$.

<a id="function-bitwisexor-rngintelt-rngintelt"></a>
##### `BitwiseXor(x, y): RngIntElt, RngIntElt -> RngIntElt`

The integer whose 2-adic representation is the bitwise ‘xor’ of the 2-adic representations of $x$ and $y$.

#### Equality and Membership

<a id="operation-op-eq-rngintelt-rngintelt"></a>
##### `m eq n: RngIntElt, RngIntElt -> BoolElt`

<a id="operation-op-ne-rngintelt-rngintelt"></a>
##### `m ne n: RngIntElt, RngIntElt -> BoolElt`

<a id="operation-op-in-rngintelt-rng"></a>
##### `n in R: RngIntElt, Rng -> BoolElt`

<a id="operation-op-notin-rngintelt-rng"></a>
##### `n notin R: RngIntElt, Rng -> BoolElt`

#### Parent and Category

<a id="function-parent-rngintelt"></a>
##### `Parent(n): RngIntElt -> RngInt`

<a id="function-category-rngintelt"></a>
##### `Category(n): RngIntElt -> Cat`

#### Predicates on Ring Elements

<a id="function-iseven-rngintelt"></a>
##### `IsEven(n): RngIntElt -> BoolElt`

Returns `true` if the integer $n$ is even, otherwise `false`.

<a id="function-isodd-rngintelt"></a>
##### `IsOdd(n): RngIntElt -> BoolElt`

Returns `true` if the integer $n$ is odd, otherwise `false`.

<a id="function-isdivisibleby-rngintelt-rngintelt"></a>
##### `IsDivisibleBy(n, d): RngIntElt, RngIntElt -> BoolElt, RngIntElt`

Returns `true` if and only if the integer $n$ is divisible by the integer $d$; if `true`, the quotient of $n$ by $d$ is also returned.

<a id="function-issquare-rngintelt"></a>
##### `IsSquare(n): RngIntElt -> BoolElt, RngIntElt`

Returns `true` if the non-negative integer $n$ is the square of an integer, `false` otherwise. If $n$ is a square, its positive square root is also returned.

<a id="function-issquarefree-rngintelt"></a>
##### `IsSquarefree(n): RngIntElt -> BoolElt`

Returns `true` if the non-zero integer $n$ is not divisible by the square of any prime, `false` otherwise.

<a id="function-ispower-rngintelt"></a>
##### `IsPower(n): RngIntElt -> BoolElt`

If the integer $n>1$ is a power $n=b^k$ of an integer $b$, with $k>1$, this function returns true, the minimal positive $b$ and its associated $k$; if it is not such integer power the function returns false.

<a id="function-ispower-rngintelt-rngintelt"></a>
##### `IsPower(n, k): RngIntElt, RngIntElt -> BoolElt`

If the integer $n>1$ is $k$-th power, with $k>1$, of some integer $b$, so that $n=b^k$, this function returns true, and $b$; if it is not a $k$-th integer power the function returns false.

<a id="function-isprime-rngintelt"></a>
##### `IsPrime(n): RngIntElt -> BoolElt`

```magma
Proof: BoolElt                    Default: true
```

Returns `true` if and only if the integer $n$ is a prime. A rigorous primality test which returns a proven result will be used unless the parameter `Proof` is `false`. The reader is referred to Section [Primes and Primality Testing](https://docs.magma-maths.org/BasicRings/Integers/prime.md#rngint-primesfact) for a complete description of this function.

<a id="example-ex-687a13"></a>
##### `Example: Primes Congruent to 3 Modulo 4 (ex-687a13)`

In this example we find some 10-digit primes that are congruent to 3 modulo 4 such that $(p-1)/2$ is also prime.

```magma
> { p : p in [10^10+3..10^10+1000 by 4] |
>        IsPrime(p) and IsPrime((p-1) div 2)};
{ 10000000259, 10000000643 }
```

<a id="function-isintegral-rngintelt"></a>
##### `IsIntegral(n): RngIntElt -> BoolElt`

Returns `true` if and only if $a$ is integral, which is of course true for every integer $n$.

<a id="function-issingleprecision-rngintelt"></a>
##### `IsSinglePrecision(n): RngIntElt -> BoolElt`

Returns `true` if $n$ fits in a single word in the internal representation of integers in Magma, that is, if $\vert n\vert<2^{30}$, `false` otherwise.

<a id="function-iszero-rngintelt"></a>
##### `IsZero(n): RngIntElt -> BoolElt`

<a id="function-isone-rngintelt"></a>
##### `IsOne(n): RngIntElt -> BoolElt`

<a id="function-isminusone-rngintelt"></a>
##### `IsMinusOne(n): RngIntElt -> BoolElt`

<a id="function-isnilpotent-rngintelt"></a>
##### `IsNilpotent(n): RngIntElt -> BoolElt`

<a id="function-isidempotent-rngintelt"></a>
##### `IsIdempotent(n): RngIntElt -> BoolElt`

<a id="function-isunit-rngintelt"></a>
##### `IsUnit(n): RngIntElt -> BoolElt`

<a id="function-iszerodivisor-rngintelt"></a>
##### `IsZeroDivisor(n): RngIntElt -> BoolElt`

<a id="function-isregular-rngint"></a>
##### `IsRegular(n): RngInt -> BoolElt`

<a id="function-isirreducible-rngintelt"></a>
##### `IsIrreducible(n): RngIntElt -> BoolElt`

<a id="function-isprime-rngintelt-2"></a>
##### `IsPrime(n): RngIntElt -> BoolElt`

#### Comparison of Ring Elements

<a id="operation-op-gt-rngintelt-rngintelt"></a>
##### `m gt n: RngIntElt, RngIntElt -> BoolElt`

<a id="operation-op-ge-rngintelt-rngintelt"></a>
##### `m ge n: RngIntElt, RngIntElt -> BoolElt`

<a id="operation-op-lt-rngintelt-rngintelt"></a>
##### `m lt n: RngIntElt, RngIntElt -> BoolElt`

<a id="operation-op-le-rngintelt-rngintelt"></a>
##### `m le n: RngIntElt, RngIntElt -> BoolElt`

<a id="function-maximum-rngintelt-rngintelt"></a>
##### `Maximum(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-maximum-rngintelt"></a>
##### `Maximum(Q): [RngIntElt] -> RngIntElt`

<a id="function-minimum-rngintelt-rngintelt"></a>
##### `Minimum(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-minimum-rngintelt"></a>
##### `Minimum(Q): [RngIntElt] -> RngIntElt`

#### Conjugates, Norm, and Trace

<a id="function-complexconjugate-rngintelt"></a>
##### `ComplexConjugate(n): RngIntElt -> RngIntElt`

The complex conjugate of $n$, which will be the integer $n$ itself.

<a id="function-conjugate-rngintelt"></a>
##### `Conjugate(n): RngIntElt -> RngIntElt`

The conjugate of $n$, which will be the integer $n$ itself.

<a id="function-norm-rngintelt"></a>
##### `Norm(n): RngIntElt -> RngIntElt`

The norm in ${\mathbb{Q}}$ of $n$, which will be the integer $n$ itself.

<a id="function-euclideannorm-rngintelt"></a>
##### `EuclideanNorm(n): RngIntElt -> RngIntElt`

The Euclidean norm (length) of $n$, which will equal the absolute value of $n$.

<a id="function-trace-rngintelt"></a>
##### `Trace(n): RngIntElt -> RngIntElt`

The trace (in ${\mathbb{Q}}$) of $n$, which will be the integer $n$ itself.

<a id="function-minimalpolynomial-rngintelt"></a>
##### `MinimalPolynomial(n): RngIntElt -> RngUPolElt`

Returns the minimal polynomial of the integer $n$, which is the monic linear polynomial with constant coefficient $n$ in a univariate polynomial ring $R$ over the integers.

#### Other Elementary Functions

<a id="function-absolutevalue-rngintelt"></a>
##### `AbsoluteValue(n): RngIntElt -> RngIntElt`

<a id="function-abs-rngintelt"></a>
##### `Abs(n): RngIntElt -> RngIntElt`

Absolute value of the integer $n$.

<a id="function-ilog2-rngintelt"></a>
##### `Ilog2(n): RngIntElt -> RngIntElt`

The integral part of the logarithm to the base two of the positive integer $n$.

<a id="function-ilog-rngintelt-rngintelt"></a>
##### `Ilog(b, n): RngIntElt, RngIntElt -> RngIntElt`

The integral part of the logarithm to the base $b$ of the positive integer $n$ i.e., the largest integer $k$ such that $b^k \leq n$. The integer $b$ must be greater than or equal to two.

<a id="function-quotrem-rngintelt-rngintelt"></a>
##### `Quotrem(m, n): RngIntElt, RngIntElt -> RngIntElt, RngIntElt`

Returns both the quotient $q$ and remainder $r$ obtained upon dividing the integer $m$ by the integer $n$, that is, $m = q\cdot n+r$, where $0 \leq r < n$ if $n>0$ and $n<r\leq 0$ if $n<0$.

<a id="function-valuation-rngintelt-rngintelt"></a>
##### `Valuation(x, p): RngIntElt, RngIntElt -> RngIntElt, RngIntElt`

The valuation of the integer $x$ at the prime $p$. This is the largest integer $v$ for which $p^v$ divides $x$. If $x = 0$ then $v = \infty$. The optional second return value is the integer $u$ such that $x = p^v u$.

<a id="function-iroot-rngintelt-rngintelt"></a>
##### `Iroot(a, n): RngIntElt, RngIntElt -> RngIntElt`

Given a positive integer $a$, return the integer $b= \lfloor\root n \of a\rfloor$, i.e. the integral part of the $n$-th root of $a$. To obtain the actual root (as a real number), $a$ must e coerced into a real field and the function `Root` applied.

<a id="function-sign-rngintelt"></a>
##### `Sign(n): RngIntElt -> RngIntElt`

Returns $-1$, $0$, or $1$ depending upon whether the integer $n$ is negative, zero, or positive, respectively.

<a id="function-ceiling-rngintelt"></a>
##### `Ceiling(n): RngIntElt -> RngIntElt`

The ceiling of the integer $n$, that is, $n$ itself.

<a id="function-floor-rngintelt"></a>
##### `Floor(n): RngIntElt -> RngIntElt`

The floor of the integer $n$, that is, $n$ itself.

<a id="function-round-rngintelt"></a>
##### `Round(n): RngIntElt -> RngIntElt`

This function rounds the integer $n$ to itself.

<a id="function-truncate-rngintelt"></a>
##### `Truncate(n): RngIntElt -> RngIntElt`

This function returns the integer truncation of the integer $n$, that is, $n$ itself.

<a id="function-squarefreefactorization-rngintelt"></a>
##### `SquarefreeFactorization(n): RngIntElt -> RngIntElt, RngIntElt`

Given a non-negative integer $n$, return a squarefree integer $x$ as well as a positive integer $y$, such that $n=xy^2$.

<a id="function-isqrt-rngintelt"></a>
##### `Isqrt(n): RngIntElt -> RngIntElt`

Given a positive integer $n$, return the integer $\lfloor\sqrt n\rfloor$, i.e., the integral part of the square root of the integer $n$.

### Random Numbers

Pseudo-random integers in Magma are generated using the *Monster* random number generator of G. Marsaglia [[Mar00](https://docs.magma-maths.org/references.md#cite-marsaglia)] (see also [[MZ91](https://docs.magma-maths.org/references.md#cite-marsagliazaman)] and [[Mar92](https://docs.magma-maths.org/references.md#cite-marsaglia92)]). The period of the Monster generator is $2^{29430} - 2^{27382}$ (approximately $10^{8859}$), and the generator passes all of the stringent tests in Marsaglia’s *Diehard* test suite [[Mar95](https://docs.magma-maths.org/references.md#cite-marsagliadiehard)]. Throughout the following text, the word ‘random’ is used to mean ‘pseudo-random’.

<a id="function-random-rngintelt-rngintelt"></a>
#### `Random(a, b): RngIntElt, RngIntElt -> RngIntElt`

A random integer lying in the interval $[a, b]$, where $a\leq b$.

<a id="function-random-rngintelt"></a>
#### `Random(b): RngIntElt -> RngIntElt`

A random integer lying in the interval $[0, b]$, where $b$ is a non-negative integer. Because of the good properties of the underlying Monster generator, calling `Random(1)` is a good safe way of producing a sequence of random bits.

<a id="function-randombits-rngintelt"></a>
#### `RandomBits(n): RngIntElt -> RngIntElt`

A random integer $m$ such that $0 \leq m < 2^n$, where $n$ is a small non-negative integer. Thus, $m$ has $n$ random bits with a probability of 1/2 for each bit. The function always returns $0$ when $n=0$.

<a id="function-randomprime-rngintelt"></a>
#### `RandomPrime(n: parameter): RngIntElt -> RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

A random prime integer $m$ such that $0 < m < 2^n$, where $n$ is a small non-negative integer. The function always returns $0$ for $n=0$ or $n=1$. A rigorous method will be used to check primality, unless $m > 3317044064679887385961981$ and the optional parameter `Proof` is set to `Proof := false`, in which case the result indicates that $m$ is a probable prime (of order 20).

<a id="function-randomprime-rngintelt-rngintelt-rngintelt"></a>
#### `RandomPrime(n, a, b, x: parameter): RngIntElt, RngIntElt, RngIntElt -> BoolElt, RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

Tries up to $x$ iterations to find a random prime integer $m$ congruent to $a$ modulo $b$ such that $0 < m < 2^n$. If successful, the function returns true and the integer $m$, otherwise false. The integer $n$ must be larger than 0, $a$ must lie between 0 and $b-1$ and $b$ must be larger than $0$. A rigorous method will be used to establish primality, unless $m > 3317044064679887385961981$ and the optional parameter `Proof` is set to `Proof := false`, in which case the result indicates that $m$ is a probable prime (of order 20).

<a id="function-randomconsecutivebits-rngintelt-rngintelt"></a>
#### `RandomConsecutiveBits(n, a, b): RngIntElt, RngIntElt -> RngIntElt`

A integer $m$ such that $0 \leq m < 2^n$, and the binary expansion of $n$ consists of consecutive strings of zeros or ones each of random length in the range $[a \ldots b]$.

### GCD and LCM

Within the classical range, Magma uses the fast classical Accelerated GCD algorithm of Kenneth Weber [[Web95](https://docs.magma-maths.org/references.md#cite-weber-gcd)] to compute the GCD of two integers, and the fast classical Lehmer extended GCD (‘XGCD’) algorithm [[Knu97](https://docs.magma-maths.org/references.md#cite-knuth2), pp. 345--348] (which is about 5 times faster than the Euclidean XGCD algorithm) to compute the extended GCD of two integers.

For larger integers, Magma uses the asymptotically fast Schönhage recursive (“half-GCD”) algorithm ([[Sch71](https://docs.magma-maths.org/references.md#cite-schoenhage-gcd)]; see also [[Mon92](https://docs.magma-maths.org/references.md#cite-montgomery-thesis), Sec. 3.8] for the basic idea, applied to polynomials). On a Sun SPARC workstation, the crossover point for the Schönhage GCD algorithm (where it beats the classical Accelerated GCD algorithm) is 32768 bits (about 10000 decimal digits), while the crossover point for the Schönhage XGCD algorithm (when it beats the Lehmer XGCD algorithm) is 6000 bits (about 2000 decimal digits).

<a id="function-greatestcommondivisor-rngintelt-rngintelt"></a>
#### `GreatestCommonDivisor(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-gcd-rngintelt-rngintelt"></a>
#### `Gcd(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-gcd-rngintelt-rngintelt-2"></a>
#### `GCD(m, n): RngIntElt, RngIntElt -> RngIntElt`

The greatest common divisor of $m$ and $n$, normalized to be non-negative. If either of the inputs is zero, then the result is the absolute value of the other input, while if $m$ and $n$ are both zero the result is zero.

<a id="function-greatestcommondivisor-rngintelt"></a>
#### `GreatestCommonDivisor(s): [RngIntElt] -> RngIntElt`

<a id="function-gcd-rngintelt"></a>
#### `Gcd(s): [RngIntElt] -> RngIntElt`

<a id="function-gcd-rngintelt-2"></a>
#### `GCD(s): [RngIntElt] -> RngIntElt`

The GCD of the entries of the sequence $s$. If all entries of the sequence are zero, the result is zero. An error results if the sequence is the null sequence.

<a id="function-extendedgreatestcommondivisor-rngintelt-rngintelt"></a>
#### `ExtendedGreatestCommonDivisor(m, n): RngIntElt, RngIntElt -> RngIntElt, RngIntElt, RngIntElt`

<a id="function-xgcd-rngintelt-rngintelt"></a>
#### `Xgcd(m, n): RngIntElt, RngIntElt -> RngIntElt, RngIntElt, RngIntElt`

<a id="function-xgcd-rngintelt-rngintelt-2"></a>
#### `XGCD(m, n): RngIntElt, RngIntElt -> RngIntElt, RngIntElt, RngIntElt`

The extended GCD of $m$ and $n$; returns integers $g$, $x$, and $y$ such that $g$ is the greatest common divisor of the integers $m$ and $n$, and $g = x\cdot m + y\cdot n$. If $m$ and $n$ are both zero, $g$ is zero; otherwise $g$ is always positive. If $m$ and $n$ are both non-zero, the multipliers $x$ and $y$ are unique.

<a id="function-extendedgreatestcommondivisor-rngintelt"></a>
#### `ExtendedGreatestCommonDivisor(s): [RngIntElt] -> RngIntElt, [RngIntElt]`

<a id="function-xgcd-rngintelt"></a>
#### `Xgcd(s): [RngIntElt] -> RngIntElt, [RngIntElt]`

<a id="function-xgcd-rngintelt-2"></a>
#### `XGCD(s): [RngIntElt] -> RngIntElt, [RngIntElt]`

Given a sequence of integers $s = [s_1, \ldots, s_r]$, return the non-negative integer $g$ and a sequence $X=(x_1, \ldots, x_r)$ such that $g$ is the greatest common divisor of the integers $s_i$ and $g=\sum_{i=1}^r x_i\cdot s_i$.

<a id="function-leastcommonmultiple-rngintelt-rngintelt"></a>
#### `LeastCommonMultiple(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-lcm-rngintelt-rngintelt"></a>
#### `Lcm(m, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-lcm-rngintelt-rngintelt-2"></a>
#### `LCM(m, n): RngIntElt, RngIntElt -> RngIntElt`

The smallest non-negative integer divisible by both $m$ and $n$. If $m$ or $n$ equals zero, the result is zero; this ensures that ${\operatorname{lcm}}(m, n)\gcd(m, n) = m\cdot n$.

<a id="function-leastcommonmultiple-rngintelt"></a>
#### `LeastCommonMultiple(s): [RngIntElt] -> RngIntElt`

<a id="function-lcm-rngintelt"></a>
#### `Lcm(s): [RngIntElt] -> RngIntElt`

<a id="function-lcm-rngintelt-2"></a>
#### `LCM(s): [RngIntElt] -> RngIntElt`

Least common multiple of the sequence of integers $s$.

### Arithmetic Functions

Each of the functions in this section may take an integer or the factorization of that integer.

<a id="function-carmichaellambda-rngintelt"></a>
#### `CarmichaelLambda(n): RngIntElt -> RngIntElt`

<a id="function-carmichaellambda-rnginteltfact"></a>
#### `CarmichaelLambda(Q): RngIntEltFact -> RngIntElt`

<a id="function-carmichaellambda-tup"></a>
#### `CarmichaelLambda(Q): [Tup] -> RngIntElt`

The Carmichael function $\lambda(n)$; its value equals the exponent of ${({{\mathbb{Z}}/n{\mathbb{Z}}})^*}$.

<a id="function-dickmanrho-fldreelt"></a>
#### `DickmanRho(u): FldReElt -> FldReElt`

Computes $\rho(u)$ where $\rho$ is Dickman’s rho function.

<a id="function-factoredcarmichaellambda-rngintelt"></a>
#### `FactoredCarmichaelLambda(n): RngIntElt -> RngIntEltFact`

<a id="function-factoredcarmichaellambda-rnginteltfact"></a>
#### `FactoredCarmichaelLambda(Q): RngIntEltFact -> RngIntEltFact`

<a id="function-factoredcarmichaellambda-tup"></a>
#### `FactoredCarmichaelLambda(Q): [Tup] -> RngIntEltFact`

The Carmichael function $\lambda(n)$, returned as a factorization sequence.

<a id="function-divisorsigma-rngintelt-rngintelt"></a>
#### `DivisorSigma(i, n): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-divisorsigma-rngintelt-rnginteltfact"></a>
#### `DivisorSigma(i, Q): RngIntElt, RngIntEltFact -> RngIntElt`

The divisor function $\sigma_i(n)=\sum_{d\vert n}d^i$ for integer $n$ and small non-negative integer $i$.

<a id="function-numberofdivisors-rngintelt"></a>
#### `NumberOfDivisors(n): RngIntElt -> RngIntElt`

<a id="function-numberofdivisors-rnginteltfact"></a>
#### `NumberOfDivisors(Q): RngIntEltFact -> RngIntElt`

The number of divisors of the positive integer $n$. This is a special case of `DivisorSigma`.

<a id="function-sumofdivisors-rngintelt"></a>
#### `SumOfDivisors(n): RngIntElt -> RngIntElt`

<a id="function-sumofdivisors-rnginteltfact"></a>
#### `SumOfDivisors(Q): RngIntEltFact -> RngIntElt`

The sum of the divisors of the positive integer $n$. This is a special case of `DivisorSigma`.

<a id="function-eulerphi-rngintelt"></a>
#### `EulerPhi(n): RngIntElt -> RngIntElt`

<a id="function-eulerphi-rnginteltfact"></a>
#### `EulerPhi(Q): RngIntEltFact -> RngIntElt`

<a id="function-eulerphi-tup"></a>
#### `EulerPhi(Q): [Tup] -> RngIntElt`

The Euler totient function $\phi(n)$; its value equals the order of ${({{\mathbb{Z}}/n{\mathbb{Z}}})^*}$.

<a id="function-factoredeulerphi-rngintelt"></a>
#### `FactoredEulerPhi(n): RngIntElt -> RngIntEltFact`

<a id="function-factoredeulerphi-rnginteltfact"></a>
#### `FactoredEulerPhi(Q): RngIntEltFact -> RngIntEltFact`

<a id="function-factoredeulerphi-tup"></a>
#### `FactoredEulerPhi(Q): [Tup] -> RngIntEltFact`

The Euler totient function $\phi(n)$, returned as a factorization sequence.

<a id="function-eulerphiinverse-rngintelt"></a>
#### `EulerPhiInverse(m): RngIntElt -> RngIntElt`

<a id="function-eulerphiinverse-rnginteltfact"></a>
#### `EulerPhiInverse(Q): RngIntEltFact -> RngIntElt`

The inverse of the Euler totient function $\phi(n)$; that is, the sorted sequence of all integers $n$ such that $\phi(n)=m$.

<a id="function-factoredeulerphiinverse-rngintelt"></a>
#### `FactoredEulerPhiInverse(n): RngIntElt -> RngIntEltFact`

<a id="function-factoredeulerphiinverse-rnginteltfact"></a>
#### `FactoredEulerPhiInverse(Q): RngIntEltFact -> RngIntEltFact`

The factored inverse of the Euler totient function $\phi(n)$; that is, the sorted sequence of the factorizations of all integers $n$ such that $\phi(n)=m$.

<a id="function-legendresymbol-rngintelt-rngintelt"></a>
#### `LegendreSymbol(n, m): RngIntElt, RngIntElt -> RngIntElt`

The Legendre symbol $\left({n\over m}\right)$: for prime $m$ this checks whether or not $n$ is a quadratic residue modulo $m$. The function returns $0$ if $m$ divides $n$, $-1$ if $n$ is not a quadratic residue, and $1$ if $n$ is a quadratic residue modulo $m$. A fast probabilistic primality test is performed on $m$. If $m$ fails the test (and is therefore composite), an error results; if it passes the test the Jacobi symbol is computed.

<a id="function-jacobisymbol-rngintelt-rngintelt"></a>
#### `JacobiSymbol(n, m): RngIntElt, RngIntElt -> RngIntElt`

The Jacobi symbol $\left({n\over m}\right)$. For odd $m > 1$ this is defined (but not calculated!) as the product of the Legendre symbols $\left({n\over p_i}\right)$, where the product is taken over all primes $p_i$ dividing $m$ including multiplicities. Quadratic reciprocity is used to calculate this symbol, which has the values $-1$, $0$, or $1$.

<a id="function-kroneckersymbol-rngintelt-rngintelt"></a>
#### `KroneckerSymbol(n, m): RngIntElt, RngIntElt -> RngIntElt`

The Kronecker symbol $\left({n\over m}\right)$. This is the extension of the Jacobi symbol to all integers $m$, by multiplicativity, and by defining $\left({n\over 2}\right)=(-1)^{(n^2-1)/8}$ for odd $n$ (and $0$ for even $n$) and $\left({n\over -1}\right)=\pm1$ according to the sign of $n$ for $n\neq 0$ (and $1$ for $n = 0$).

<a id="function-moebiusmu-rngintelt"></a>
#### `MoebiusMu(n): RngIntElt -> RngIntElt`

<a id="function-moebiusmu-rnginteltfact"></a>
#### `MoebiusMu(Q): RngIntEltFact -> RngIntElt`

The Möbius function $\mu(n)$. This is a multiplicative function characterized by $\mu(1)=1$, $\mu(p)=-1$, and $\mu(p^k)=0$ for $k \geq 2$, where $p$ is a prime number.

<a id="example-ex-233f46"></a>
#### `Example: Amicable Pairs of Integers (ex-233f46)`

A pair of positive integers $(m, n)$ is called *amicable* if the sum of the proper divisors (that is: excluding $m$ itself) of $m$ equals $n$, and vice versa. The following function finds such pairs. Note that it also finds perfect numbers: amicable pairs of the form $(m, m)$.

```magma
> d := func< m | DivisorSigma(1, m)-m >;
> z := func< m | d(d(m)) eq m >;
> for m := 2 to 10000 do
>     if z(m) then
>         m, d(m);
>     end if;
> end for;
6 6
28 28
220 284
284 220
496 496
1184 1210
1210 1184
2620 2924
2924 2620
5020 5564
5564 5020
6232 6368
6368 6232
8128 8128
```

### Combinatorial Functions

<a id="function-binomial-rngintelt-rngintelt"></a>
#### `Binomial(n, r): RngIntElt, RngIntElt -> RngIntElt`

The binomial coefficient $n\choose r$.

<a id="function-multinomial-rngintelt-rngintelt"></a>
#### `Multinomial(n, [r₁, ... rₙ]): RngIntElt, [RngIntElt] -> RngIntElt`

Given a sequence $Q = [r_1, \ldots, r_k]$ of positive integers such that $n = r_1 + ... + r_k$, return the multinomial coefficient $n\choose r_1, \ldots, r_k$.

<a id="function-factorial-rngintelt"></a>
#### `Factorial(n): RngIntElt -> RngIntElt`

The factorial $n!$ for positive small integer $n$.

<a id="function-isfactorial-rngintelt"></a>
#### `IsFactorial(n): RngIntElt -> BoolElt, RngIntElt`

Tests if $n = k!$ for some $k$. If so, return `true` and $k$, `false` otherwise.

<a id="function-partitions-rngintelt"></a>
#### `Partitions(n): RngIntElt -> [ [ RngIntElt ] ]`

The unrestricted partitions of the positive integer $n$. This function returns a sequence of integer sequences, each of which is a different sequence of positive integers (in descending order) adding up to $n$. The integer $n$ must be small.

<a id="function-numberofpartitions-rngintelt"></a>
#### `NumberOfPartitions(n): RngIntElt -> RngIntElt`

The number of unrestricted partitions of the non-negative integer $n$. The integer $n$ must be small.

<a id="function-restrictedpartitions-rngintelt-setenum"></a>
#### `RestrictedPartitions(n, M): RngIntElt, SetEnum -> [ [ RngIntElt ] ]`

The partitions of the positive integer $n$, restricted to elements of the positive integer sequence $M$.

<a id="function-restrictedpartitions-rngintelt-rngintelt-setenum"></a>
#### `RestrictedPartitions(n, k, M): RngIntElt, RngIntElt, SetEnum -> [ [ RngIntElt ] ]`

The partitions of the positive integer $n$ into $k$ parts, restricted to elements of the positive integer sequence $M$.

<a id="function-stirlingfirst-rngintelt-rngintelt"></a>
#### `StirlingFirst(n, k): RngIntElt, RngIntElt -> RngIntElt`

The Stirling number of the first type, $s(n, k) = [{n\atop k}]$, where $n$ and $k$ are non-negative integers.

<a id="function-stirlingsecond-rngintelt-rngintelt"></a>
#### `StirlingSecond(n, k): RngIntElt, RngIntElt -> RngIntElt`

The Stirling number of the second type, $S(n,k)=\{{n\atop k}\}$, where $n$ and $k$ are non-negative integers.

<a id="function-bell-rngintelt"></a>
#### `Bell(n): RngIntElt -> RngIntElt`

The $n$th Bell number, giving the number of partitions of a set of size $n$. (Not to be confused with `NumberOfPartitions(n)`, which gives the number of partitions of the *integer* $n$.) This is equal to the sum of `StirlingSecond(n,k)` for $k$ between 0 and $n$ (inclusive).

<a id="function-fibonacci-rngintelt"></a>
#### `Fibonacci(n): RngIntElt -> RngIntElt`

Given an integer $n$, this function returns the $n$-th Fibonacci number $F_n$, which can be defined via the recursion $F_0 = 0$, $F_1 = 1$, and $F_n = F_{n-1} + F_{n-2}$ for all integers $n$. Note that $n$ is allowed to be negative, and that $F_{-n} = (-1)^{n+1} F_n$.

<a id="function-lucas-rngintelt"></a>
#### `Lucas(n): RngIntElt -> RngIntElt`

Given an integer $n$, this function returns the $n$-th Lucas number $L_n$, which can be defined via the recursion $L_0 = 2$, $L_1 = 1$, and $L_n = L_{n-1} + L_{n-2}$ for all integers $n$. Note that $n$ is allowed to be negative, and that $L_{-n} = (-1)^{n}L_n$.

<a id="function-generalizedfibonaccinumber-rngintelt-rngintelt-rngintelt"></a>
#### `GeneralizedFibonacciNumber(g0, g1, n): RngIntElt, RngIntElt, RngIntElt -> RngIntElt`

The $n$th member of the generalized Fibonacci sequence defined by $G_0 = g_0$, $G_1 = g_1$, and $G_n = G_{n-1} + G_{n-2}$ for all integers $n$. Note that $n$ is allowed to be negative. The Fibonacci and Lucas numbers are special cases where $(g_0, g_1) = (0, 1)$ or $(2, 1)$ respectively.

<a id="prime"></a>
<a id="rngint-primesfact"></a>
### Primes and Primality Testing

Primality testing algorithms enable the user to certify the primality of prime integers. Proving the primality of very big integers can be time consuming and therefore in some of the algorithms using primes and factorization of integers the user can speed up the algorithm by explicitly allowing Magma to use probable primes rather than certified primes. A *probable prime* is an integer that has failed some compositeness test; if an integer passes a compositeness test it will be composite, but there is a (small) probability that a composite number will fail the test and is hence called a probable prime. Each Miller-Rabin test for instance, has a probability of less than $1/4$ of declaring a composite number probably prime; in practice that means that numbers that fail several such cheap independent Miller-Rabin compositeness tests will be prime. Unless specifically asked otherwise, Magma will use rigorous primality proofs.

#### Primality

If a positive integer $n$ is composite, this can be shown quickly by exhibiting a *witness* to this fact. A witness for the compositeness of $n$ is an integer $1<a<n$ with the property that

$$
a^r\not\equiv1\bmod n\quad \hbox{and}\quad a^{r2^i}\not\equiv-1\bmod n\text{  for }i=0,1,\ldots, k-1
$$

where $r$ odd, and $k$ are such that $n-1=r\cdot 2^k$. A witness never falsely claims that $n$ is composite, because for prime $n$ it must hold that $a^{n-1}\equiv 1\bmod n$ and only $\pm1$ are square roots of $1$ modulo prime $n$. Moreover, it has been shown that a fraction of at least $3/4$ of all $a$ in the range $2\ldots n-1$ will witness the compositeness of $n$. Thus randomly choosing $a$ will usually quickly expose compositeness. Unless more than $1/4$ of all possibilities for $a$ are checked though (which in practice will be impossible for reasonable $n$) the procedure of checking $k$ bases $a$ at random for being a witness (often referred to as ‘Miller-Rabin’) will not suffice to prove the primality of $n$; it does however lend credibility to the claim that $n$ is most likely prime if among $k$ (say 20) random choices for $a$ no witness for compositeness has been found. In such cases $n$ is called *probably prime of order* $k$, and in some sense the probability that $n$ is composite is less than $4^{-k}$. A slight adaptation of this compositeness test can be used for primality proofs in a bounded range. There are no composites smaller than the Sorenson/Webster bound $B=3317044064679887385961981$ (approx $3.3\times 10^{24}$) for which a witness does not exist among $a=2,3,5,7,11,13,17,19,23,29,31,37$ ([[SW17](https://docs.magma-maths.org/references.md#cite-sorenson2017strong)]). Using these values of $a$ for candidate witnesses it is certain that for any number $n$ less than $B$, the test will either find a witness or correctly declare $n$ prime. Since V2.29, Magma uses this test to prove primality (deterministically) of any prime $n<B$.

But even for large integers it is thus usually easy to identify composites without finding a factor; to be certain that a large probable prime is truly prime, a primality proving algorithm is invoked. Magma uses the ECPP (Elliptic Curve Primality Proving) method. Since V2.29, Magma uses a new implementation, that can handle 1000 digit numbers in a few minutes.

This ECPP method is both fast and rigorous, but for large integers (of say more than 100 decimal digits) it will be still be much slower than the Miller-Rabin compositeness test. The method is too involved to be explained here; we refer the reader to the literature ([[AM93](https://docs.magma-maths.org/references.md#cite-atkinmorain)], [[FKMW04](https://docs.magma-maths.org/references.md#cite-frankeetalt)]). The `IsPrime` function invokes ECPP, unless a Boolean flag is used to indicate that only ‘probable primality’ is required. The latter is equivalent to a call to `IsProbablePrime`.

<a id="function-isprime-rngintelt-3"></a>
##### `IsPrime(n): RngIntElt -> BoolElt`

<a id="function-isprime-rngintelt-4"></a>
##### `IsPrime(n: parameter): RngIntElt -> BoolElt`

```magma
Proof: BoolElt                    Default: true
```

Returns `true` iff the integer $n$ is prime. A rigorous deterministic method will be used, unless $n > B$, where $B=3317044064679887385961981$ (approx $3.3\times 10^{24}$), and optional parameter `Proof` is set to `Proof := false`, in which case the result indicates that $n$ is a probable prime (a strong pseudoprime to 20 bases).

<a id="procedure-setverbose-monstgelt-elt-ecpp"></a>
##### `SetVerbose("ECPP", v): MonStgElt, Elt`

Sets the verbose level for output when the ECPP algorithm is used in the above primality tests. The legal values are `true`, `false`, 0, 1, and 2 (`false` and `true` are the same as 0 and 1 respectively). Level 1 outputs only basic information about the times for the top-level stages (downrun and uprun). Level 2 outputs full information about every step : this level is very verbose!

<a id="function-primalitycertificate-rngintelt"></a>
##### `PrimalityCertificate(n): RngIntElt -> SeqEnum`

<a id="function-checkcertificate-seqenum"></a>
##### `CheckCertificate(cert): SeqEnum -> BoolElt`

```magma
Print: BoolElt                    Default: false
Full : BoolElt                    Default: true
```

`PrimalityCertificate` is a variant on `IsPrime` which uses ECPP and outputs a certificate of primality at the conclusion. If the number $n$ is actually proven to be composite or the test fails, then a runtime error occurs. The certificate is a `Magma` sequence of lists. Each list represents one step of the proof.

The first entry in each list $L$ indicates the method used. If the first enty is `E`, the elliptic curve `E := EllipticCurve(L[6])` is used. Its reduction modulo `n := L[2]` has the point $P$ with coordinates `L[7]`. The step assumes that `p := L[5]` is a prime. In this case $P$ has order $p$. As the prime `p` is sufficiently large, the primality of `n` follows. The next entry in the certificate will contain a proof that `p` is in fact prime. The elliptic curve was found via the CM approach with discriminant `L[3]` and the number of points on its reduction modulo `n` is given by `L[4]`.

If the first enty is `N-1`, the multiplicative group modulo `n := L[2]` has the element `g := L[4]`. The step assmes that `p := L[3]` is a prime. The `p`-th power of `g` is one modulo `n`. As the prime `p` is sufficiently large, the primality of `n` follows. The next entry in the certificate will contain a proof that `p` is in fact prime.

If the first enty is `Det`, `L[2]` is small enough to be covered by a deterministic Miller-Rabin test.

To confirm that a primality certiciate is correct, the function `CheckCertificate` can be used. It returns `true` if the certificate is corret and `false` otherwise. Setting `Print` to `true` displays the proof in a human readable format. Further, setting `full` to `true` results in an independet check of the result obtained by the deterministic Miller-Rabin test. A skeptical user is advised to check every certificate with this function, as it uses an independent implementation of elliptic curve arithmetic and also replaces the deterministic Miller-Rabin test with an independent test.

<a id="function-oldcertificate-seqenum"></a>
##### `OldCertificate(cert): SeqEnum -> List`

The function `OldCertificate` converts the currenly used primality certificate and returns it in the format used by Magma V 2.28 and earlier. It can be used for an independet check of the certificate by a program that supports that format.

<a id="function-isprobableprime-rngintelt"></a>
##### `IsProbablePrime(n: parameter): RngIntElt -> BoolElt`

<a id="function-isprobablyprime-rngintelt"></a>
##### `IsProbablyPrime(n: parameter): RngIntElt -> BoolElt`

```magma
Bases: RngIntElt                    Default: 20
```

Returns `true` if and only if the integer $n$ is a probable prime. More precisely, the function returns `true` if and only if either $n$ is prime for $n < 3317044064679887385961981$, or $n$ is a strong pseudoprime for 20 random bases $b$ with $1 < b < n$. By setting the optional parameter `Bases` to some value $B$, the number of random bases used is $B$ instead of $20$.

<a id="function-isprimepower-rngintelt"></a>
##### `IsPrimePower(n): RngIntElt -> BoolElt, RngIntElt, RngIntElt`

Returns `true` if and only if the integer $n$ is a prime power; that is, if $n$ equals $p^k$ for some prime $p$ and exponent $k\geq 1$. If this is the case, the prime $p$ and the exponent $k$ are also returned, Note that the primality of $p$ is rigorously proven.

<a id="example-ex-ca5938"></a>
##### `Example: Probable Repunit Primes (ex-ca5938)`

This piece of code uses $5$ Miller-Rabin tests to find the next probable *repunit*-prime (consisting of all $1$’s as decimal digits), using the fact that primes of this form consist of a prime number of digits:

```magma
> NextPPRepunit := function(nn)
>    n := nn;
>    repeat
>       n := NextPrime(n);
>    until IsProbablePrime( (10^n-1) div 9 : Bases := 5);
>    return n;
> end function;
```

The first few cases are easy:

```magma
> NextPPRepunit(1);
2
> NextPPRepunit(2);
19
> NextPPRepunit(19);
23
> NextPPRepunit(23);
317
```

So we found a 317 digit prime (although we should check genuine primality, using `IsPrime`)! We leave it to the reader to find the next (it has more than $1000$ decimal digits).

#### Other Functions Relating to Primes

The functions `NextPrime` and `PreviousPrime` can be used to find primes in the neighbourhood of a given integer. After sieving out only multiples of very small primes, the remaining integers are tested for primality in order. Again, a rigorous method is used unless the user flags that probable primes suffice. The `PrimeDivisors` function is different from all other functions in this section since it requires the factorization of its argument.

<a id="function-nextprime-rngintelt"></a>
##### `NextPrime(n): RngIntElt -> RngIntElt`

<a id="function-nextprime-rngintelt-2"></a>
##### `NextPrime(n: parameter): RngIntElt -> RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

The least prime number greater than $n$, where $n$ is a non-negative integer. The primality is proved. The optional boolean parameter ‘Proof’ (`Proof := true` by default) can be set to `Proof := false`, to indicate that the next probable prime (of order $20$) may be returned.

<a id="function-previousprime-rngintelt"></a>
##### `PreviousPrime(n): RngIntElt -> RngIntElt`

<a id="function-previousprime-rngintelt-2"></a>
##### `PreviousPrime(n: parameter): RngIntElt -> RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

The greatest prime number less than $n$, where $n\geq 3$ is an integer. The primality is proved. The optional boolean parameter ‘Proof’ (`Proof := true` by default) can be set to `Proof := false`, to indicate that the previous probable prime (of order $20$) may be returned.

<a id="function-primesupto-rngintelt"></a>
##### `PrimesUpTo(B): RngIntElt -> [RngIntElt]`

This function lists the primes up to (and including) the (positive) bound $B$. The algorithm is not super-optimised, but is reasonable. The limit on $B$ is $2^{30}-1$ for practical reasons, as otherwise the memory requirements can become too large with non-small integers (see below).

<a id="function-primesininterval-rngintelt-rngintelt"></a>
##### `PrimesInInterval(b, e): RngIntElt, RngIntElt -> [RngIntElt]`

This function lists the primes in the interval from $b$ to $e$, including the endpoints. The algorithm is not very optimised. The interval must be smaller than $2^{30}$ in size, but if there are non-small integers ($>2^{30}$) involved then these will create a large memory overhead in any case. For instance, the `PrimesUpTo` intrinsic for $2^{30}-1$ returns 54400028 primes in 650 megabytes, while the `PrimesInInterval` intrinsic for $(2^{30}+1,2^{31}-1)$ takes over 5 gigabytes for its array of 50697537 primes.

<a id="function-nthprime-rngintelt"></a>
##### `NthPrime(n): RngIntElt -> RngIntElt`

Given a number $n$, this function returns the $n$th prime. This is implemented for primes up to $10^{10}$, or $n\le 455052511$.

<a id="function-randomprime-rngintelt-2"></a>
##### `RandomPrime(n: parameter): RngIntElt -> RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

A random prime integer $m$ such that $0 < m < 2^n$, where $n$ is a small non-negative integer. The function always returns $0$ for $n=0$ or $n=1$. A rigorous method will be used to check primality, unless $m > 3317044064679887385961981$ and the optional parameter ‘Proof’ is set to `Proof := false`, in which case the result indicates that $m$ is a probable prime (of order 20).

<a id="function-randomprime-rngintelt-rngintelt-rngintelt-2"></a>
##### `RandomPrime(n, a, b, x: parameter): RngIntElt, RngIntElt, RngIntElt -> BoolElt, RngIntElt`

```magma
Proof: BoolElt                    Default: true
```

Tries up to $x$ iterations to find a random prime integer $m$ congruent to $a$ modulo $b$ such that $0 < m < 2^n$. Returns true, $m$ if found, or false if not found. $n$ must be larger than 0. $a$ must be between 0 and $b-1$ and $b$ must be larger than $0$. A rigorous method will be used to check primality, unless $m > 3317044064679887385961981$ and the optional parameter ‘Proof’ is set to `Proof := false`, in which case the result indicates that $m$ is a probable prime (of order 20).

<a id="function-primebasis-rngintelt"></a>
##### `PrimeBasis(n): RngIntElt -> [RngIntElt]`

<a id="function-primedivisors-rngintelt"></a>
##### `PrimeDivisors(n): RngIntElt -> [RngIntElt]`

A sequence containing the distinct prime divisors of the positive integer $|n|$.

### Factorization

This section contains a description of most of the machinery provided in Magma for the factorization of integers. An account of the Number Field Sieve is deferred until later in the chapter. In the first subsection the general-purpose `Factorization` function is described. It employs a combination of methods in an attempt to find the complete prime factorization of a given integer. Some control is possible over each of the methods, but in general default choices for the parameters would give good results for a wide range of arguments. In the second subsection we describe functions that enable access to each of the factorization methods available in Magma. The user has control over parameters for these methods. Factorization functions in Magma return a *factorization sequence*. This is a sequence of two-element tuples $[ <p_1, k_1>,\ldots, <p_r, k_r>]$, with $p_1<p_2<\cdots <p_r$ distinct prime numbers and $k_i$ positive, which is used to represent integers in factored form: $n=\prod_{i=1}^{r}p_i^{k_i}$. Although such sequences are printed like ordinary sequences, they form a separate category `RngIntEltFact`. Operations on such factorization sequences are described in the next section.

#### General Factorization

The general `Factorization` function is designed to give close to optimal performance for the factorization of integers that may be encountered in the course of daily computations. The strategy employed is as follows (the next subsection gives a more detailed description of the individual methods). First of all a compositeness test is used to ensure that the argument is composite; if not the primality proving algorithm is invoked (unless a flag is set to avoid this — see below). See the previous section for compositeness testing and primality proving. This operation is repeated for any non-trivial factor (and cofactor) found along the way. Before any of the general factorization techniques is employed, it is checked whether $|n|$ is of the special form $b^k\pm1$, in which case an intelligent database look-up is used which is likely to be successful if $b$ and $k$ are not too large. This is equivalent to the `Cunningham` function on $b, k, \pm1$, described in the next subsection. In the first true stage of factorization *trial division* is used to find powers of $2$ and other small primes (by default up to 10000). After this it is checked whether the remaining composite number is the power of a positive integer; if so the appropriate root is used henceforth. After this *Pollard’s* $\rho$ *method* is applied (using 8191 iterations by default). The bound on trial division factors and the number of iterations for $\rho$ can be set by the optional parameters `TrialDivisionLimit` and `PollardRhoLimit`. It is possible, from this point on, that several composite factors still need factorization. The description below applies to each of these. The final two algorithms deployed are usually indicated by ECM (for Elliptic Curve Method) and MPQS (for Multiple Polynomial Quadratic Sieve). By default, ECM (which is likely to find ‘smaller’ factors if they exist) is used with parameters that depend on the size of the remaining (composite) factors. After that, if a composite factor of at least 25 digits remains, MPQS is used; it is the best method available for factoring integers of more than about 40 decimal digits especially for products of two primes of roughly equal size. If the remaining composite is smaller than 25 digits, ECM is again invoked, now in an indefinite loop until a factor is found. The latter will also occur if the user, via a flag `MPQSLimit` indicates that MPQS should not be applied to numbers of the given size, and provided the user has not limited the number of ECM trials by setting the `ECMLimit`. Thus, unless both `MPQSLimit` and `ECMLimit` are set as optional parameters by the users, the algorithm will continue until the complete factorization has been completed. Besides the limiting parameters just mentioned it also possible to avoid the use of primality proofs and receive probable primes, with a flag similar to that used on `IsPrime`; see the previous section. A verbose flag can be set to obtain informative printing on progress in the various stages of factorization. Specific flags for ECM and MPQS may be used as well; they are described in the next subsection. Since V2.27, parallel versions of the ECM and MPQS algorithms are also available and are selected by using the procedures `SetNthreads` and [`StartWorkers`](https://docs.magma-maths.org/MagmaLanguage/Parallelism/distributed.md#procedure-par-startworkers). See Subsection [Integer Factorisation](https://docs.magma-maths.org/MagmaLanguage/Parallelism/integer-factorisation.md#par-integer) for more details.

<a id="procedure-setverbose-monstgelt-rngintelt-factorization"></a>
##### `SetVerbose("Factorization", v): MonStgElt, RngIntElt`

(Procedure.) Set the verbose printing level for all of the factorization algorithms to be $v$. Currently the legal values for $v$ are `true`, `false`, 0, or 1 (`false` is the same as 0, and `true` is the same as 1). If the level is 1, information is printed at each stage of the algorithm as a number is factored.

<a id="function-factorization-rngintelt"></a>
##### `Factorization(n): RngIntElt -> RngIntEltFact, RngIntElt, SeqEnum`

<a id="function-factorisation-rngintelt"></a>
##### `Factorisation(n): RngIntElt -> RngIntEltFact, RngIntElt, SeqEnum`

<a id="function-factorization-rngintelt-2"></a>
##### `Factorization(n: parameters): RngIntElt -> RngIntEltFact, RngIntElt, SeqEnum`

<a id="function-factorisation-rngintelt-2"></a>
##### `Factorisation(n: parameters): RngIntElt -> RngIntEltFact, RngIntElt, SeqEnum`

```magma
Proof             : BoolElt                      Default: true
Bases             : RngIntElt                    Default: 20
TrialDivisionLimit: RngIntElt                    Default: 10000
SQUFOFLimit       : RngIntElt                    Default: 24
PollardRhoLimit   : RngIntElt                    Default: 8191
ECMLimit          : RngIntElt                    Default: 
MPQSLimit         : RngIntElt                    Default: Infinity()
```

A combination of algorithms (Cunningham, trial division, SQUFOF, Pollard $\rho$, ECM, and MPQS) is used to attempt to find the complete factorization of $|n|$, where $n$ is a non-zero integer. A factorization sequence is returned, representing the completely factored part of $|n|$ (which is usually all of $|n|$). The second return value is 1 or ${-1}$, reflecting the sign of $n$. If the factorization could not be completed, a third sequence is returned, containing composite factors that could not be decomposed with the given values of the parameters; this can only happen if both `ECMLimit` and `MPQSLimit` have been set. (Note that the third variable will remain unassigned if the full factorization is found.)

When a very large prime (more than 200 decimal digits say), appears in the factorization, proving its primality may dominate the running time.

There are 6 optional parameters.

The parameter `Proof` (`Proof := true` by default) can be set to false to indicate that the first sequence may contain probable primes (see also the previous section), in which case the parameter `Bases` indicates the number of tests used by Miller-Rabin (`Bases := 20` by default).

The parameter `TrialDivisionLimit` can be used to specify an upper bound for the primes used in the trial division stage (default `TrialDivisionLimit := 10000`).

The parameter `SQUFOFLimit` can be used specify the maximum number of decimal digits for an integer to which SQUFOF should be applied; this is Shank’s square form factorization method (default `SQUFOFLimit := 24`).

The parameter `PollardRhoLimit` can be used to specify an upper bound on the number of iterations in the $\rho$ method (default `PollardRhoLimit := 8191`).

This optional parameter can be used to limit the number of curves used by the ECM part of the factorization attempt. Setting `ECMLimit := 0` prevents the use of ECM. The default value depends on the size of the input, and ranges from $2$ for $n$ with less than 37 digits to around 500 for $n$ with 80 digits. The smoothness is incremented in each step to grow by default from 500 to 600 (for 37 digits and less), and from 500 to about 10000 for $n$ having 80 digits. For the indefinite case of ECM (which applies when MPQS is disallowed) the initial smoothness is 500, the number of curves is infinite and the smoothness is incremented by 100 in each step.

The parameter `MPQSLimit` can be used specify the maximum number of decimal digits for an integer to which MPQS should still be applied; MPQS will not be invoked on integers having less than (or sometimes equal) 25 decimal digits. Setting the parameter to anything less than 25 will therefore prevent MPQS from being used. Unless `ECMLimit` has been set, this will imply that ECM will be applied until the full factorization has been obtained.

Note that progress can be monitored by use of `SetVerbose("Factorization", 1)`.

#### Storing Potential Factors

Since V2.14 (October 2007), Magma now internally stores a list of factors found by the ECM and MPQS algorithms. Subsequently, when either of those algorithms are to be invoked by the `Factorization` function, the integers in the list are first tried to see whether factors can be easily found. One may also give prime factors to Magma to store in this list via the following procedure.

<a id="procedure-storefactor-rngintelt"></a>
##### `StoreFactor(n): RngIntElt`

<a id="procedure-storefactor-rngintelt-2"></a>
##### `StoreFactor(S): [ RngIntElt ]`

(Procedure.) Store the single integer $n$ or the integers in the set/sequence $S$ in the list of factors to be tried by the `Factorization` function. Each integer must be a positive *prime*.

<a id="function-getstoredfactors"></a>
##### `GetStoredFactors() -> [ RngIntElt ]`

Return a sequence containing the currently stored integers.

<a id="procedure-clearstoredfactors"></a>
##### `ClearStoredFactors()`

Clear the list of stored integer factors.

#### Specific Factorization Algorithms

In this subsection we discuss how various factorization algorithms can be accessed individually. Generally these function should not be used for ordinary factorization (for that use `Factorization` discussed in the previous subsection), but they can be used for experimentation, or to build a personal factorization function with control over each of the methods used. On some functions a little preprocessing is done to ensure that the argument is composite, that powers of $2$ (and sometimes $3$) are taken out and that the integer to be factored is not the power of an integer. For each of these functions the `Proof` (default `true`) and `Bases` parameters can be used to indicate that primality of prime factors need not be rigorously proved, and how many bases should be used in the compositeness test, as discussed in the subsection on `IsPrime`.

<a id="procedure-setverbose-monstgelt-boolelt-cunningham"></a>
##### `SetVerbose("Cunningham", b): MonStgElt, BoolElt`

<a id="procedure-setverbose-monstgelt-elt-ecm"></a>
##### `SetVerbose("ECM", b): MonStgElt, Elt`

<a id="procedure-setverbose-monstgelt-elt-mpqs"></a>
##### `SetVerbose("MPQS", b): MonStgElt, Elt`

Using this procedure to set either of the verbose flags `"Cunningham"`, `"ECM"`, or `"MPQS"`, (which are `false` by default) enables the user to obtain progress information on attempts to factor integers using the ‘Cunningham’ method, ECM, or MPQS.

<a id="function-cunningham-rngintelt-rngintelt-rngintelt"></a>
##### `Cunningham(b, k, c): RngIntElt, RngIntElt, RngIntElt -> SeqEnum`

This function attempts to factor $n=b^k+c$, where $c\in\{\pm1\}$ and $b$ and $k$ are not too big. This function uses R. Brent’s factor algorithm [[BtR92](https://docs.magma-maths.org/references.md#cite-brentteriele)], which employs a combination of table-lookups and attempts at ‘algebraic’ factorization (Aurifeuillian techniques). An error results if the tables, containing most of the known factors for numbers of this form (including the ‘Cunningham tables’), cannot be located by the system. The function will always return the complete prime factorization (in the form of a factorization sequence) of the number $n$ (but it may take very long before it completes); it should be pointed out, however, that the primes appearing in the factorization are only *probable primes* and a rigorous primality prover has not been applied.

<a id="procedure-assertattribute-cat-monstgelt-rngintelt-cunninghamstoragelimit"></a>
##### `AssertAttribute(RngInt, "CunninghamStorageLimit", l): Cat, MonStgElt, RngIntElt`

This attribute is used to change the number of Cunningham factorizations which are stored in Magma. Normally, Magma stores a certain number of factorizations computed by the `Cunningham` intrinsic function so that commonly needed factorizations can be recalled quickly. When the stored list fills up, the factorization least recently accessed is removed from the list. Setting this attribute to zero ensures that no storage is done. The default value is 20.

<a id="function-trialdivision-rngintelt"></a>
##### `TrialDivision(n): RngIntElt -> RngIntEltFact, RngIntElt`

<a id="function-trialdivision-rngintelt-rngintelt"></a>
##### `TrialDivision(n, B): RngIntElt, RngIntElt -> RngIntEltFact, RngIntElt`

The integer $n\not=0$ is subjected to trial division by primes up to a certain bound $B$ (the sign of $n$ is ignored). If only the argument $n$ is given, $B$ is taken to be 10000. Since V2.29-9, the function returns the factorization sequence of the part of $|n|$ which is composed of the primes up to $B$, together with the residue divisor of $|n|$ which remains; the residue is 1 if and only if $|n|$ is completely factored by the trial division. The bound $B$ is respected exactly, so no prime greater than $B$ ever occurs in the factorization sequence. (In versions before V2.29-9 the primes 2, 3, 5, and 7 were always divided out, whatever $B$ was.) No primality test is performed on the residue: if it is desired to know whether the residue is prime, `IsPrime` should be applied to it afterwards.

For backwards compatibility (with versions before V2.29-9), the parameters `Proof` and `Bases` are still accepted but are now ignored (in earlier versions they controlled a primality test which was applied to the residue).

<a id="function-pollardrho-rngintelt"></a>
##### `PollardRho(n): RngIntElt -> RngIntEltFact, [ RngIntElt ]`

<a id="function-pollardrho-rngintelt-rngintelt-rngintelt-rngintelt"></a>
##### `PollardRho(n, c, s, k): RngIntElt, RngIntElt, RngIntElt, RngIntElt -> RngIntEltFact, [ RngIntElt ]`

```magma
Proof: BoolElt                      Default: true
Bases: RngIntElt                    Default: 20
```

The $\rho$-method of Pollard is invoked by this function to find the factorization of an integer $n>1$. For this method a quadratic function $x^2+c$ is iterated $k$ times, with starting value $x=s$. If only $n$ is used as argument to the function, the default values $c=1$, $s=1$, and $k=8191$ are selected. A speed-up to the original algorithm, due to R.$\,$P. Brent [[Bre80](https://docs.magma-maths.org/references.md#cite-brent80)], is implemented. The function returns two values: a factorization sequence and a sequence containing unfactored composite factors.

<a id="function-pminus1-rngintelt-rngintelt"></a>
##### `pMinus1(n, B1): RngIntElt, RngIntElt -> RngIntElt`

```magma
x0: RngIntElt                    Default: 
B2: RngIntElt                    Default: 
k : RngIntElt                    Default: 
```

Given an integer $n>1$, an attempt to find a factor is made using Paul Zimmermann’s GMP-ECM implementation of Pollard’s $p-1$ method. If a factor $f$ with $1<f<n$ is found, then $f$ is returned; otherwise 0 is returned.

The Step 1 bound $B_1$ is given as the second argument `B1`. By default, the Step 2 bound $B_2$ is optimally chosen, but may be given with the parameter `B2` instead. By default, an optimal number of blocks is chosen for Step 2, but this may be overridden via the parameter `k` (see the function `ECM`). The base $x_0$ is chosen randomly by default, but may instead be supplied via the parameter `x0`.

This method will return a prime factor $p$ of $n$ if $p-1$ has all its prime factors less than or equal to the Step 1 bound $B_1$, except for one factor which may be less than or equal to the Step 2 bound $B_2$.

<a id="function-pplus1-rngintelt-rngintelt"></a>
##### `pPlus1(n, B1): RngIntElt, RngIntElt -> RngIntElt`

```magma
x0: RngIntElt                    Default: 
B2: RngIntElt                    Default: 
k : RngIntElt                    Default: 
```

Given an integer $n>1$, an attempt to find a factor is made using Paul Zimmermann’s GMP-ECM implementation of Williams’ $p+1$ method. If a factor $f$ with $1<f<n$ is found, then $f$ is returned; otherwise 0 is returned.

The Step 1 bound $B_1$ is given as the second argument `B1`. By default, the Step 2 bound $B_2$ is optimally chosen, but may be given with the parameter `B2` instead. By default, an optimal number of blocks is chosen for Step 2, but this may be overridden via the parameter `k` (see the function `ECM`). The base $x_0$ is chosen randomly by default, but may instead be supplied via the parameter `x0`.

This method may return a prime factor $p$ of $n$ if $p+1$ has all its prime factors less than or equal to the Step 1 bound $B_1$, except for one factor which may be less than or equal to the Step 2 bound $B_2$. A base $x_0$ is used, and not all bases will succeed: only half of the bases work (namely those where the Jacobi symbol of $x_0^2-4$ and $p$ is -1.) Unfortunately, since $p$ is usually not known in advance, there is no way to ensure that this holds. However, if the base is chosen randomly, there is a probability of about $1/2$ that it will give a Jacobi symbol of -1 (so that the factor $p$ would be found assuming that $p+1$ is smooth enough). A rule of thumb is to run `pPlus1` three times with different random bases.

<a id="function-squfof-rngintelt"></a>
##### `SQUFOF(n): RngIntElt -> RngIntEltFact, [ RngIntElt ]`

<a id="function-squfof-rngintelt-rngintelt"></a>
##### `SQUFOF(n, k): RngIntElt, RngIntElt -> RngIntEltFact, [ RngIntElt ]`

```magma
Proof: BoolElt                      Default: true
Bases: RngIntElt                    Default: 20
```

This is a fast implementation of Shanks’s square form factorization method that will only work for integers $n>1$ less than $2^{2b-2}$, where $b$ is the number of bits in a long (which is either 32 or 64). The argument $k$ may be used to specify the maximum number of iterations used to find the square; by default it is 200000. The expected number of iterations is $O(N^{1/4}).$

<a id="function-ecm-rngintelt-rngintelt"></a>
##### `ECM(n, B1): RngIntElt, RngIntElt -> RngIntElt, RngIntElt`

```magma
Sigma: RngIntElt                    Default: 
x0   : RngIntElt                    Default: 
B2   : RngIntElt                    Default: 
k    : RngIntElt                    Default: 2
```

Given an integer $n>1$, an attempt is made to find a factor using the GMP-ECM implementation of the Elliptic Curve Method (ECM). If a factor $f$ with $1<f<n$ is found, then $f$ is returned together with the corresponding successful $\sigma$ seed; otherwise 0 is returned.

The Step 1 bound $B_1$ is given as the second argument `B1`. By default, the Step 2 bound $B_2$ is optimally chosen, but may be given with the parameter `B2` instead.

The elliptic curve used is defined by Suyama’s parametrization and is determined by a parameter $\sigma$. By default, $\sigma$ is chosen randomly with $0 < \sigma < 2^{32}$, but an alternative positive integer may be supplied instead via the parameter `Sigma`. Let $u = \sigma^2-5$, $v = 4\sigma$, and $a = (v-u)^3(3u+v)/(4u^3v)-2$. The starting point used is $(x_0:1)$, where by default $x_0=u^3/v^3$, but $x_0$ may instead be supplied via the parameter `x0`. Finally, the curve used is $by^2 = x^3 + ax^2 + x$, where $b = x_0^3 + ax_0^2 + x_0$.

Step 1 uses very little memory, but Step 2 may use a large amount of memory, especially for large $B_2$, since its efficient algorithms use some large tables. To reduce the memory usage of Step 2, one may increase the parameter `k`, which controls the number of “blocks” used. Multiplying the default value of $k$ by 4 will decrease the memory usage by a factor of 2. For example, with $B_2=10^{10}$ and a 155-digit number $n$, Step 2 requires about 96MB with the default $k=2$, but only 42MB with $k=8$. Increasing $k$ does, however, slightly increase the time required for Step 2.

<a id="function-ecmsteps-rngintelt-rngintelt-rngintelt"></a>
##### `ECMSteps(n, L, U): RngIntElt, RngIntElt, RngIntElt -> RngIntElt, RngIntElt`

Given an integer $n>1$, an attempt to find a factor of $n$ is made by repeated calls to ECM. The initial $B_1$ bound is taken to be $L$, and subsequently $B_1$ is replaced with $B_1 + \lfloor \sqrt B_1 \rfloor$ at each step. If a factor is found at any point, then this is returned with the corresponding successful $\sigma$ seed; otherwise, if $B_1$ becomes greater than the upper bound $U$, then 0 is returned.

<a id="function-rngint-mpqs"></a>
##### `MPQS(n): RngIntElt -> RngIntEltFact, [ RngIntElt ]`

```magma
Proof: BoolElt                      Default: true
Bases: RngIntElt                    Default: 20
```

This function can be used to drive Arjen Lenstra’s implementation of the multiple polynomial quadratic sieve MPQS. Given an integer $n>5\cdot10^{24}$ an attempt is made to find the prime factorization of $n$ using MPQS. The function returns two values: a factorization sequence and a sequence containing unfactored composite factors.

#### Factorization Related Functions

<a id="function-ecmorder-rngintelt-rngintelt"></a>
##### `ECMOrder(p, s): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-ecmfactoredorder-rngintelt-rngintelt"></a>
##### `ECMFactoredOrder(p, s): RngIntElt, RngIntElt -> RngIntElt`

Suppose $p$ is a prime factor found by the ECM algorithm and such that the $\sigma$ value determining the successful curve was $s$. These functions compute the order of the corresponding elliptic curve. The first function returns the order as an integer, while the second function returns the factorization of the order. In general, this order will have been smooth with respect to the relevant bounds for the ECM algorithm to have worked, and these functions allow one to examine how small the prime divisors of the curve order really are.

<a id="function-primebasis-rngintelt-2"></a>
##### `PrimeBasis(n): RngIntElt -> [RngIntElt]`

<a id="function-primedivisors-rngintelt-2"></a>
##### `PrimeDivisors(n): RngIntElt -> [RngIntElt]`

A sequence containing the distinct prime divisors of the positive integer $|n|$, given in increasing order.

<a id="function-divisors-rngintelt"></a>
##### `Divisors(n): RngIntElt -> [ RngIntElt ]`

<a id="function-divisors-rnginteltfact"></a>
##### `Divisors(f): RngIntEltFact -> [ RngIntElt ]`

Returns a sequence containing all divisors of the positive integer, including 1 and the integer itself, given in increasing order. The argument given must be either the integer $n$ itself, or a factorization sequence $f$ representing it.

<a id="function-coprimebasis-rngintelt"></a>
##### `CoprimeBasis(S): [ RngIntElt ] -> [ RngIntElt ]`

<a id="function-coprimebasis-rngintelt-2"></a>
##### `CoprimeBasis(S): { RngIntElt } -> [ RngIntElt ]`

Given a set or sequence $S$ of integers, return a coprime basis of $S$ in the form of a factorization sequence $Q$ whose integer value is the same as the product of the elements of $S$ but $Q$ has coprime bases (i.e., the first components of tuples from $Q$ are coprime).

<a id="example-ex-07a3e8"></a>
##### `Example: Perfect Numbers (ex-07a3e8)`

In this example we use the `Divisors` function together with the `&+` reduction of sequences to find the first few perfect numbers, that is, numbers $n$ such that the sum of the divisors less than $n$ equals $n$.

```magma
> {  x : x in [2..1000] | &+Divisors(x) eq 2*x };
{ 6, 28, 496 }
> f := Factorization(496);
> f;
[ <2, 4>, <31, 1> ]
> Divisors(f);
[ 1, 2, 4, 8, 16, 31, 62, 124, 248, 496 ]
```

<a id="function-partialfactorization-rngintelt"></a>
##### `PartialFactorization(S): [ RngIntElt ] -> [ RngIntEltFact ]`

Given a sequence of non-zero integers $S$, return, for each integer $S[i]$, two factorization lists $F_i$ and $G_i$, such that $S[i] =\ $`Facint`$(F_i) *$`Facint`$(G_i)$. All the divisors in $F_i$ are square factors, and, for any $i$ and $j$, the divisors in $G_i$ and $G_j$ are either equal or are pairwise coprime. In other terms, `PartialFactorization(S)` provides a partial decomposition of the integers in $S$ in square and coprime factors. The interesting fact is that this factorization uses only gcd and exact integer division. This algorithm is due to J.E. Cremona.

<a id="example-ex-15e5a0"></a>
##### `Example: Partial Factorization (ex-15e5a0)`

A partial factorization is shown.

```magma
> PartialFactorization([1380, 675, 3408, 654]);
[
  [
    [ <2, 2> ],
    [ <115, 1>, <3, 1> ]
  ],
  [
    [ <5, 2>, <3, 2> ],
    [ <3, 1> ]
  ],
  [
    [ <2, 4> ],
    [ <71, 1>, <3, 1> ]
  ],
  [
    [],
    [ <218, 1>, <3, 1> ]
  ]
]
```

### Factorization Sequences

The factorization of integers results in a factorization sequence, consisting of a sequence of pairs of prime and exponent. It is sometimes convenient to perform operations on such sequences without converting back to the integers they represent — it would, for example, be very inefficient to factor the product of two integers that have both been factored already. In this section we briefly list the operations that are allowed on such factorization sequences — note that these factorization sequences now have their own special type: `RngIntEltFact`. Conversion functions are supplied as well.

#### Creation and Conversion

Factorization sequence usually arise as the result of the `Factorization` of an integer, possibly via functions like `FactoredOrder`. The functions below allow conversion from and to ordinary sequences, and the inverse operation to factorization, creating an integer from a factorization.

<a id="function-facint-rnginteltfact"></a>
##### `Facint(f): RngIntEltFact -> RngIntElt`

<a id="function-factorizationtointeger-rnginteltfact"></a>
##### `FactorizationToInteger(f): RngIntEltFact -> RngIntElt`

Create the integer corresponding to the factorization sequence $f$.

<a id="function-seqfact-seqenum"></a>
##### `SeqFact(s): SeqEnum -> RngIntEltFact`

<a id="function-sequencetofactorization-seqenum"></a>
##### `SequenceToFactorization(s): SeqEnum -> RngIntEltFact`

Given a sequence of tuples, each consisting of pairs of prime integers and positive integer exponents, create the corresponding factorization sequence. The pairs must be ordered with strictly increasing primes as first components.

<a id="function-eltseq-rnginteltfact"></a>
##### `Eltseq(f): RngIntEltFact -> SeqEnum`

<a id="function-elementtosequence-rnginteltfact"></a>
##### `ElementToSequence(f): RngIntEltFact -> SeqEnum`

Given a factorization sequence $f$, create the enumerated sequence containing the same pairs of primes and exponents.

#### Arithmetic

The difference of two factorization sequences is only permitted when the first integer represented is greater than the second integer represented. An error results from division when the quotient does not correspond to an integer.

<a id="operation-op-plus-rnginteltfact-rnginteltfact"></a>
##### `s + t: RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="operation-op-minus-rnginteltfact-rnginteltfact"></a>
##### `s - t: RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="operation-op-times-rnginteltfact-rnginteltfact"></a>
##### `s * t: RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="operation-op-div-rnginteltfact-rnginteltfact"></a>
##### `s / t: RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="operation-op-pow-rnginteltfact-rngintelt"></a>
##### `s ^ k: RngIntEltFact, RngIntElt -> RngIntEltFact`

#### Divisors

The functions listed below can be applied to factorization sequences; their behaviour will be clear, and all of them are documented elsewhere when the argument is the corresponding positive integer.

<a id="function-lcm-rnginteltfact-rnginteltfact"></a>
##### `Lcm(s, t): RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="function-gcd-rnginteltfact-rnginteltfact"></a>
##### `Gcd(s, t): RngIntEltFact, RngIntEltFact -> RngIntEltFact`

<a id="function-squarefreefactorization-rnginteltfact"></a>
##### `SquarefreeFactorization(f): RngIntEltFact -> RngIntEltFact, RngIntEltFact`

<a id="function-moebiusmu-rnginteltfact-2"></a>
##### `MoebiusMu(f): RngIntEltFact -> RngIntElt`

<a id="function-divisors-rnginteltfact-2"></a>
##### `Divisors(f): RngIntEltFact -> SeqEnum`

<a id="function-primedivisors-rnginteltfact"></a>
##### `PrimeDivisors(f): RngIntEltFact -> SeqEnum`

<a id="function-numberofdivisors-rnginteltfact-2"></a>
##### `NumberOfDivisors(f): RngIntEltFact -> RngIntElt`

<a id="function-sumofdivisors-rnginteltfact-2"></a>
##### `SumOfDivisors(f): RngIntEltFact -> RngIntElt`

#### Predicates

All predicates listed below are applicable both to factorization sequences and to the positive integers these represent, and have been documented for integer arguments elsewhere.

<a id="function-isone-rnginteltfact"></a>
##### `IsOne(s): RngIntEltFact -> BoolElt`

<a id="function-isodd-rnginteltfact"></a>
##### `IsOdd(s): RngIntEltFact -> BoolElt`

<a id="function-iseven-rnginteltfact"></a>
##### `IsEven(s): RngIntEltFact -> BoolElt`

<a id="function-isunit-rnginteltfact"></a>
##### `IsUnit(s): RngIntEltFact -> BoolElt`

<a id="function-isprime-rnginteltfact"></a>
##### `IsPrime(s): RngIntEltFact -> BoolElt`

<a id="function-isprimepower-rnginteltfact"></a>
##### `IsPrimePower(s): RngIntEltFact -> BoolElt`

<a id="function-issquare-rnginteltfact"></a>
##### `IsSquare(s): RngIntEltFact -> BoolElt`

<a id="function-issquarefree-rnginteltfact"></a>
##### `IsSquarefree(s): RngIntEltFact -> BoolElt`

### Modular Arithmetic

In this section we describe some functions that make it possible to perform modular arithmetic without conversions to residue class rings.

#### Arithmetic Operations

<a id="function-modexp-rngintelt-rngintelt-rngintelt"></a>
##### `Modexp(n, k, m): RngIntElt, RngIntElt, RngIntElt -> RngIntElt`

The modular power $n^k\bmod m$, where $n$ is an integer, $k$ is an integer and $m$ is an integer greater than one. If $k$ is negative, $n$ must have an inverse $i$ modulo $m$, and the result is then $i^{-k}\bmod m$. The result is always an integer $r$ with $0\leq r< m$.

<a id="operation-operation-mod-rngintelt-rngintelt-rngintelt"></a>
##### `n mod m: RngIntElt, RngIntElt -> RngIntElt`

Remainder upon dividing the integer $n$ by the integer $m$. The result always has the same sign as $m$. An error results if $m$ is zero.

<a id="function-modinv-rngintelt-rngintelt"></a>
##### `Modinv(n, m): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-inversemod-rngintelt-rngintelt"></a>
##### `InverseMod(n, m): RngIntElt, RngIntElt -> RngIntElt`

Given an integer $n$ and a positive integer $m$, such that $n$ and $m$ are coprime, return an inverse $u$ of $n$ modulo $m$, that is, return an integer $1\leq u<m$ such that $u\cdot n\equiv 1\bmod m$.

<a id="function-modsqrt-rngintelt-rngintelt"></a>
##### `Modsqrt(n, m): RngIntElt, RngIntElt -> BoolElt, RngIntElt`

Given an integer $n$ and an integer $m \geq 2$, this function returns an integer $b$ such that $0 \leq b < m$ and $b^2\equiv n\bmod m$ if such $b$ exists; an error results if no such root exists.

<a id="function-modorder-rngintelt-rngintelt"></a>
##### `Modorder(n, m): RngIntElt, RngIntElt -> RngIntElt`

For integers $n$ and $m$, $m > 1$, the function returns the least integer $k \geq 1$ such that $n^k \equiv 1 \bmod m$, or zero if $\gcd(n, m) \neq 1$.

<a id="function-isprimitive-rngintelt-rngintelt"></a>
##### `IsPrimitive(n, m): RngIntElt, RngIntElt -> BoolElt`

Returns `true` if $n$ is a primitive root for $m$, `false` otherwise ($0 < n < m$).

<a id="function-primitiveroot-rngintelt"></a>
##### `PrimitiveRoot(m): RngIntElt -> RngIntElt`

Given an integer $m > 1$, this function returns an integer value defined as follows: If ${\mathbb{Z}}/m{\mathbb{Z}}$ has a primitive root and the function is successful in finding it, the root $a$ is returned. If ${\mathbb{Z}}/m{\mathbb{Z}}$ has a primitive root but the algorithm does not succeed in finding it, or ${\mathbb{Z}}/m{\mathbb{Z}}$ does not possess a primitive root, then zero is returned.

<a id="equation"></a>
<a id="rngint-normeq"></a>
#### The Solution of Modular Equations

The functions described here can be used if an occasional modular operation is required; the results are integers again. For more extensive modular arithmetic it is preferable to convert to residue class ring arithmetic. See section [Residue Class Rings](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#rngint-rngintres) for details.

<a id="function-solution-rngintelt-rngintelt-rngintelt"></a>
##### `Solution(a, b, m): RngIntElt, RngIntElt, RngIntElt -> RngIntElt, RngIntElt`

If a solution exists to the linear congruence $ax\equiv b \bmod m$, then returns $x0, k$ such that $x = x0 + i*k$ represents the complete set of solutions, where i can be any integer. Otherwise, returns -1.

<a id="function-chineseremaindertheorem-rngintelt-rngintelt"></a>
##### `ChineseRemainderTheorem(X, N): [RngIntElt], [RngIntElt] -> RngIntElt`

<a id="function-crt-rngintelt-rngintelt"></a>
##### `CRT(X, N): [RngIntElt], [RngIntElt] -> RngIntElt`

Apply the Chinese Remainder Theorem to the integer sequences $X$ and $N$. The sequences must have the same length, $k$ say. The function returns the unique integer $x$ in the range $0 \leq x < LCM(N[1]\cdot\ldots\cdot N[k])$ such that $x \equiv X[i] \bmod N[i]$. The elements of $N$ must all be positive integers greater than one. If there is no solution, then -1 is returned.

<a id="function-solution-rngintelt-rngintelt-rngintelt-2"></a>
##### `Solution(A, B, N): [RngIntElt], [RngIntElt], [RngIntElt] -> RngIntElt`

Return a solution $x$ to the system of simultaneous linear congruences defined by the integer sequences $A$, $B$, and $N$. Each of these sequences must have the same number of terms, $k$ say. The elements of $N$ must all be positive integers greater than one. The $i$-th congruence is $A[i] \cdot x \equiv B[i] \bmod N[i]$. The solution $x$ will satisfy $0 \leq x < LCM(N[1]\cdot\ldots\cdot N[k])$. If no solution exists, -1 is returned.

<a id="function-normequation-rngintelt-rngintelt"></a>
##### `NormEquation(d, m): RngIntElt, RngIntElt -> BoolElt, RngIntElt, RngIntElt`

<a id="function-normequation-rngintelt-rngintelt-2"></a>
##### `NormEquation(d, m: parameters)): RngIntElt, RngIntElt -> BoolElt, RngIntElt, RngIntElt`

```magma
Factorization: [<RngIntElt, RngIntElt>]                    Default: [ ]
```

Given a positive integer $d$ and a non-negative integer $m$, return `true` and two non-negative integers $x$ and $y$, such that $x^2+y^2d = m$, if such a solution exists. If such a solution does not exists only the value `false` is returned. If the factorization of $m$ is known, it may be supplied as the value of the parameter `Factorization` to speed up the computation.

<a id="example-ex-a39523"></a>
##### `Example: Norm Equation (ex-a39523)`

```magma
> d := 957440000095744000002277749760;
> m := 5102197760510219776012138128480644;
> time NormEquation(d, m);
true 98 73
Time: 2.990
> time f := Factorization(m);
Time: 4.670
> f;
[ <2, 2>, <19, 1>, <67134181059344997052791291164219, 1> ]
> time NormEquation(d, m: Factorization := f);
true 98 73
Time: 0.420
```

### Infinities

Occasionally it is convenient to work with infinite quantities (for example, when working with valuations or cardinalities). Magma provides two such objects, the positive and negative infinities. This section describes the Magma facilities for dealing with such objects.

The infinities are compatible with certain finite quantities: integers, rationals, and real numbers. In contexts where a common universe is needed to contain both finite and infinite quantities (for example, if creating a sequence of valuations) the extended reals (type `ExtRe`) are used. The extended reals are a coproduct-like object that can contain both infinities and compatible finite objects. When viewed as members of the extended reals, the elements are of type `ExtReElt`.

#### Creation

Certain system intrinsics such as `Valuation` which normally return an integer may return an infinite object for appropriate exceptional cases. Two special intrinsics are also provided to create infinite objects.

<a id="function-infinity"></a>
##### `Infinity() -> Infty`

The positive infinity object.

<a id="function-minusinfinity"></a>
##### `MinusInfinity() -> Infty`

The negative infinity object.

#### Arithmetic

Only basic arithmetic operations are provided for infinite objects. The operations described below may freely mix infinite and finite quantities, but note that certain forms (such as $\infty - \infty$ or $\infty * 0$) are not well defined and will cause an error.

<a id="operation-operation-infty-infty"></a>
##### `- x: Infty -> Infty`

<a id="operation-op-plus-infty-infty"></a>
##### `x + y: Infty, Infty -> Infty`

<a id="operation-op-plus-infty-rngintelt"></a>
##### `x + y: Infty, RngIntElt -> Infty`

<a id="operation-op-plus-rngintelt-infty"></a>
##### `x + y: RngIntElt, Infty -> Infty`

<a id="operation-op-minus-infty-infty"></a>
##### `x - y: Infty, Infty -> Infty`

<a id="operation-op-minus-infty-rngintelt"></a>
##### `x - y: Infty, RngIntElt -> Infty`

<a id="operation-op-minus-rngintelt-infty"></a>
##### `x - y: RngIntElt, Infty -> Infty`

<a id="operation-op-times-infty-infty"></a>
##### `x * y: Infty, Infty -> Infty`

<a id="operation-op-times-infty-rngintelt"></a>
##### `x * y: Infty, RngIntElt -> Infty`

<a id="operation-op-times-rngintelt-infty"></a>
##### `x * y: RngIntElt, Infty -> Infty`

<a id="operation-op-div-rngintelt-infty"></a>
##### `x / y: RngIntElt, Infty -> RngIntElt`

<a id="operation-op-div-infty-rngintelt"></a>
##### `x / y: Infty, RngIntElt -> Infty`

<a id="operation-op-pow-infty-infty"></a>
##### `x ^ n: Infty, Infty -> Infty`

<a id="operation-op-pow-infty-rngintelt"></a>
##### `x ^ n: Infty, RngIntElt -> Infty`

#### Comparison

Infinite objects may be compared with themselves and finite quantities.

<a id="operation-op-eq-infty-infty"></a>
##### `x eq y: Infty, Infty -> BoolElt`

<a id="operation-op-eq-infty-rngintelt"></a>
##### `x eq y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-eq-rngintelt-infty"></a>
##### `x eq y: RngIntElt, Infty -> BoolElt`

<a id="operation-op-ne-infty-infty"></a>
##### `x ne y: Infty, Infty -> BoolElt`

<a id="operation-op-ne-infty-rngintelt"></a>
##### `x ne y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-ne-rngintelt-infty"></a>
##### `x ne y: RngIntElt, Infty -> BoolElt`

<a id="operation-op-lt-infty-infty"></a>
##### `x lt y: Infty, Infty -> BoolElt`

<a id="operation-op-lt-infty-rngintelt"></a>
##### `x lt y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-lt-rngintelt-infty"></a>
##### `x lt y: RngIntElt, Infty -> BoolElt`

<a id="operation-op-le-infty-infty"></a>
##### `x le y: Infty, Infty -> BoolElt`

<a id="operation-op-le-infty-rngintelt"></a>
##### `x le y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-le-rngintelt-infty"></a>
##### `x le y: RngIntElt, Infty -> BoolElt`

<a id="operation-op-gt-infty-infty"></a>
##### `x gt y: Infty, Infty -> BoolElt`

<a id="operation-op-gt-infty-rngintelt"></a>
##### `x gt y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-gt-rngintelt-infty"></a>
##### `x gt y: RngIntElt, Infty -> BoolElt`

<a id="operation-op-ge-infty-infty"></a>
##### `x ge y: Infty, Infty -> BoolElt`

<a id="operation-op-ge-infty-rngintelt"></a>
##### `x ge y: Infty, RngIntElt -> BoolElt`

<a id="operation-op-ge-rngintelt-infty"></a>
##### `x ge y: RngIntElt, Infty -> BoolElt`

<a id="function-maximum-infty-infty"></a>
##### `Maximum(x, y): Infty, Infty -> .`

<a id="function-maximum-infty-rngintelt"></a>
##### `Maximum(x, y): Infty, RngIntElt -> .`

<a id="function-maximum-rngintelt-infty"></a>
##### `Maximum(x, y): RngIntElt, Infty -> .`

<a id="function-minimum-infty-infty"></a>
##### `Minimum(x, y): Infty, Infty -> .`

<a id="function-minimum-infty-rngintelt"></a>
##### `Minimum(x, y): Infty, RngIntElt -> .`

<a id="function-minimum-rngintelt-infty"></a>
##### `Minimum(x, y): RngIntElt, Infty -> .`

#### Miscellaneous

<a id="function-sign-infty"></a>
##### `Sign(x): Infty -> RngIntElt`

Returns $1$ if $x$ is the positive infinite object, $-1$ if $x$ is the negative infinite object.

<a id="function-abs-infty"></a>
##### `Abs(x): Infty -> Infty`

<a id="function-absolutevalue-infty"></a>
##### `AbsoluteValue(x): Infty -> Infty`

Returns the positive infinite object.

<a id="function-round-infty"></a>
##### `Round(x): Infty -> Infty`

<a id="function-floor-infty"></a>
##### `Floor(x): Infty -> Infty`

<a id="function-ceiling-infty"></a>
##### `Ceiling(x): Infty -> Infty`

Returns the infinite object $x$ again; these functions are for convenience when dealing with objects which could be either finite numeric types or infinite objects.

<a id="function-isfinite-infty"></a>
##### `IsFinite(x): Infty -> BoolElt`

<a id="function-isfinite-rngintelt"></a>
##### `IsFinite(x): RngIntElt -> BoolElt`

Returns `true` if $x$ is finite, otherwise `false`. This is more convenient than checking the type of $x$.

### Advanced Factorization Techniques: The Number Field Sieve

Magma provides an experimental implementation of the fastest general purpose factoring algorithm known: the Number Field Sieve (NFS). The implementation may be used both as a General Number Field Sieve and a Special Number Field Sieve – the only difference is in the selection of a suitable polynomial.

#### The Magma Number Field Sieve Implementation

In order to make use of the Magma NFS, the user should have some knowledge of the algorithm. The Magma NFS implementation also requires a significant amount of memory and disk space to be available for the duration of the factorization. For example, factorization of an 80-digit number may require at least 64 megabytes of RAM and half a gigabyte of disk space.

Magma’s NFS implementation uses one linear polynomial (the “rational side”) and one polynomial of higher degree (the “algebraic side”). At the time of writing this is not a major restriction, since the best methods for selecting polynomials for factorization of numbers of more than 100 digits involve one linear and one non-linear polynomial. Magma provides a number of functions to assist in choosing a good algebraic-side polynomial for the factorization of a particular number, following the ideas of Montgomery and Murphy in [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)].

Magma provides two methods for using the NFS implementation. The first is the one-step function `NFS`, which provides a naive NFS factorization attempt using default algorithm parameters.

The second, more powerful method is to work with an NFS process object, splitting the algorithm into four stages: Sieving, Auxiliary data, Linear algebra, and Final factorization. This approach allows greater control over the algorithm, as the user may supply their own algorithm parameter values. It also allows the user to distribute the computationally intensive sieving and final factorization stages over several machines or processors.

Some functions are included to allow Magma users to co-operate in factorization attempts using CWI tools.

A verbose flag may be set to obtain informative printing on progress in the various stages of the NFS algorithm.

<a id="procedure-setverbose-monstgelt-rngintelt-nfs"></a>
##### `SetVerbose("NFS", v): MonStgElt, RngIntElt`

Set the verbose printing level for the NFS algorithms to the integer $v$. Currently the legal values for $v$ are 0, 1, 2, and 3. If the level is 0, no verbose output is produced. If the level is 1, NFS will produce basic information about its progress, and will also print information on NFS algorithm parameters. If the level is 2, NFS will provide more detailed information about progress and parameters. If the level is 3, NFS will print out extremely detailed information about progress and data. This level will only be useful for experts and developers.

#### Naive NFS

Magma’s Number Field Sieve implementation provides a one-step black-box function `NFS`. Here, the user provides the integer $n$ to be factored, a homogeneous bivariate integer polynomial $F$, and integers $m1$ and $m2$ such that $F(m1,m2) \equiv 0$ mod $n$. Magma will attempt to factor $n$ using $F$, $m1$, and $m2$, automatically selecting the other parameters (see below) for the algorithm.

The automatically chosen parameters are NOT optimal in general, and therefore no conclusions should be drawn about the speed of the implementation or the algorithm itself based on the use of this function.

For example, note that the default algebraic factor base size of `NFS` is chosen to be rather large to decrease the likelihood of running out of useful relations. This slows the algorithm considerably, since it increases the size of the matrix to be reduced – but it also means that the algorithm should succeed in finding a factor unless one chooses a really bad polynomial.

<a id="function-numberfieldsieve-rngintelt-rngmpolelt-rngintelt-rngintelt"></a>
##### `NumberFieldSieve(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt -> RngIntElt`

<a id="function-nfs-rngintelt-rngmpolelt-rngintelt-rngintelt"></a>
##### `NFS(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt -> RngIntElt`

Performs the factorization of an integer $n$ using the Number Field Sieve with algebraic polynomial $F$, where the integers $m1$ and $m2$ satisfy $F(m1,m2) \equiv 0 \bmod n$. Returns a nontrivial factor of $n$ if one is found, or 0 otherwise.

#### Factoring with NFS Processes

An NFS Process (an object of category `NFSProc`) encapsulates the data of a Magma NFS factorization. It contains the number $n$ to be factored, the algebraic polynomial $F$, and the integers $m_1$ and $m_2$. It also provides access to a number of NFS algorithm parameters (such as approximate factor base sizes). These parameters are attributes of the NFS process. If any of the parameters are not set, sensible (but not necessarily optimal) defaults will be provided by Magma.

The NFS algorithm is divided into four stages:

1. Sieving
2. Auxiliary data gathering
3. Linear algebra
4. Factorization

The stages are described in detail below.

After creating an NFS process for the factorization attempt, the user should proceed through each of the four stages in the above order.

<a id="function-nfsprocess-rngintelt-rngmpolelt-rngintelt-rngintelt"></a>
##### `NFSProcess(n, F, m1, m2): RngIntElt, RngMPolElt, RngIntElt, RngIntElt -> NFSProc`

Given a (composite) integer $n$, a bivariate homogeneous integer polynomial $F$, and nonzero integers $m1$ and $m2$ such that $F(m1,m2) \equiv 0 \bmod n$, this function creates an NFS process object for an NFS factorization of $n$.

<a id="example-ex-53bcfa"></a>
##### `Example: NFS Process Attributes (ex-53bcfa)`

The attributes associated with an NFS process are:

```magma
> ListAttributes(NFSProc);
AlgebraicError              OutputFilename
AlgebraicFBBound            RationalError
AlgebraicLargePrimeBound    RationalFBBound
CacheSize                   RationalLargePrimeBound
F                           m1
Firstb                      m2
Lastb                       n
Maximuma
```

`OutputFilename` is the base name for NFS-generated data files. These files (and their actual names) are discussed below.

`AlgebraicFBBound` is the upper bound for smooth primes in the algebraic-side factor base, and `RationalFBBound`, the upper bound for smooth primes in rational-side factor base.

`Maximuma` bounds the sieve interval for $a$: NFS will sieve for relations with $|a| \le$ `Maximuma`.

`Firstb` is the first value of $b$ to sieve on, and `Lastb` is the last.

`AlgebraicLargePrimeBound` gives the upper bound for “large” (non-smooth) primes in the algebraic-side factor base. Similarly, `RationalLargePrimeBound` is the upper bound for the rational side.

`AlgebraicError` defines an “error” tolerance for logarithm arithmetic on algebraic side. Similarly, `RationalError` defines an “error” tolerance for the rational side.

`CacheSize` is a flag reflecting the computer cache memory size, for optimisation.

##### Attribute Selection

As a guideline for the selection of attributes, we include here a few examples of attributes that we have determined to be good for the Magma NFS implementation.

<a id="example-ex-25ef84"></a>
###### `Example: NFS Attributes for a 70-Digit Number (ex-25ef84)`

Sample attributes for a 70-digit number:

```magma
> n := 5235869680233366295366904510725458053043111241035678897933802235060927;
> R<X,Y> := PolynomialRing(Integers( ), 2);
> F := 2379600*X^4 - 12052850016*X^3*Y - 13804671642407*X^2*Y^2 +
>      11449640164912254*X*Y^3 + 7965530070546332840*Y^4 ;
> m1 := 6848906180202117;
> m2 := 1;
> P := NFSProcess(n,F,m1,m2);
> P`AlgebraicFBBound := 8*10^5;
> P`RationalFBBound := 6*10^5;
> P`OutputFilename := "/tmp/nfs_70_digit";
> P`Maximuma := 4194280;
> P`AlgebraicError := 16;
> P`RationalError := 14;
```

<a id="example-ex-9e7234"></a>
###### `Example: NFS Attributes for an 80-Digit Number (ex-9e7234)`

Sample attributes for an 80-digit number:

```magma
> n := 1871831866357686493451122722951040222063279350383738650253906933489072\\
> 2483083589;
> P<X,Y> := PolynomialRing(Integers(),2);
> F := 15901200*X^4 + 9933631795*X^3*Y - 112425819157429*X^2*Y^2 -
>     231659214929438137*X*Y^3 - 73799500175565303965*Y^4;
> m1 := 1041619817688573426;
> m2 := 1;
> P := NFSProcess(n, F, m1, m2);
> P`AlgebraicFBBound := 8*10^5;
> P`RationalFBBound := 6*10^5;
> P`OutputFilename := "/tmp/nfs_80_dgit";
> P`Maximuma := 10485760;
> P`AlgebraicError := 16;
> P`RationalError := 14;
```

<a id="example-ex-7d7073"></a>
###### `Example: NFS Attributes for an 87-Digit Number (ex-7d7073)`

Sample attributes for an 87-digit number:

```magma
> n := 12118618732463427472219179104631767765107839384219612469780841876821498\\
> 2402918637227743;
> P<X,Y> := PolynomialRing(Integers(),2);
> F := 190512000*X^4 - 450872401242*X^3*Y +
>     1869594915648551*X^2*Y^2 + 2568544235742498*X*Y^3 -
>     9322965583419801010104*Y^4;
> m1 := 28241170741195273211;
> m2 := 1;
> P := NFSProcess(n, F, m1, m2);
> P`AlgebraicFBBound := 16*10^5;
> P`RationalFBBound := 10^6;
> P`OutputFilename := "/tmp/nfs_87_digit";
> P`Maximuma := 2^24;
> P`AlgebraicError := 24;
> P`RationalError := 18;
```

The best choice for the factor base size depends on many variables, including the average log size and the Murphy $\alpha$ parameter (defined in [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)]) for the polynomial $F$. Our polynomials above are quite good: if the user does not know much about determining the quality of polynomials, then he or she should use much larger factor bases.

##### The Sieving Stage

Magma’s NFS uses a “line-by-line” (or “classical”) sieving algorithm. Future versions may include lattice sieving.

The line-by-line siever sieves values of $F(a,b)$ on the algebraic side and corresponding values $a \cdot m2 - b \cdot m1$ on the rational side. This is done by fixing a value of $b$ (beginning with the parameter `Firstb`, if supplied), then sieving all values of $a$ between $-a_0$ and $a_0$, where $a_0$ is approximately equal to the parameter `Maximuma` (some rounding off is done to make sure that the sieve interval length is divisible by a high power of $2$). When this is completed $b$ is incremented, and the next value of $b$ is processed.

The sieving continues until either the maximum value of $b$ (specified by the parameter `Lastb`) has been reached, or until enough relations are obtained to complete the factorization. If `Lastb` is not defined, the sieve simply continues until enough relations are found. The number of relations required may be determined by the function `NumberOfRelationsRequired`.

“Cycles” among partial relations are counted after every 256 iterations.

The sieve implementation uses (rounded natural) logarithms of primes to mark the sieve interval. Moreover, the implementation does not sieve with prime powers. Therefore, we must allow for some error in scanning the sieve arrays for useful relations; the acceptable sieve threshold errors for each side are defined by the `AlgebraicError` and `RationalError` parameters. If, in addition, the user wants to take advantage of large prime relations (recommended), then larger error terms should be used. The implementation will keep relations having up to 2 large primes on each side, but will only find such relations if the user selects large enough sieve threshold error bounds. The user should be cautious when sieving for (and subsequently using) relations with large primes, as they greatly increase overall disk space requirements. Some experimentation may be required in order to determine the best error bounds for speed or disk space optimization purposes.

The `CacheSize` parameter may be used to take advantage of the cache memory size of the computer: a value of 1 indicates a small cache size, 2 a medium cache size, and 3 a for large cache size.

<a id="function-numberofrelationsrequired-nfsproc"></a>
###### `NumberOfRelationsRequired(P): NFSProc -> RngIntElt`

The minimum number of relations required for an NFS factor attempt with NFS process $P$.

<a id="function-findrelations-nfsproc"></a>
###### `FindRelations(P): NFSProc -> RngIntElt`

Given an NFS process $P$ for factoring an integer $n$, generates relations to factor $n$ with the Number Field Sieve algorithm. Returns the number of full relations plus the number of cycles found.

##### The Auxiliary Data Stage

In this stage of the algorithm, “cycles” [[LD95](https://docs.magma-maths.org/references.md#cite-dodsonlenstra)] are detected in the partial relations from the sieving stage, and quadratic characters are calculated for the relations. This greatly improves the efficiency of the NFS.

In a typical factorization, the user should call the procedures `CreateCycleFile` and `CreateCharacterFile` in succession.

<a id="function-createcyclefile-nfsproc"></a>
###### `CreateCycleFile(P): NFSProc -> .`

Creates a file with all the cycle information that the NFS algorithm requires to complete the matrix reduction and final factorization stages for the NFS process $P$.

<a id="function-cyclecount-nfsproc"></a>
###### `CycleCount(P): NFSProc -> RngIntElt`

Returns the number of cycles in the partial relations of the NFS process $P$. This function is mainly intended for factoring with multiple processors.

<a id="function-cyclecount-monstgelt"></a>
###### `CycleCount(fn): MonStgElt -> RngIntElt`

Returns the number of cycles in the partial data file corresponding to the base file name $fn$. This function is mainly intended for factoring with multiple processors.

<a id="function-createcharacterfile-nfsproc"></a>
###### `CreateCharacterFile(P): NFSProc -> .`

Creates a file with the quadratic character data for the full relations and cycles in the NFS process $P$.

<a id="function-createcharacterfile-nfsproc-rngintelt"></a>
###### `CreateCharacterFile(P, cc): NFSProc, RngIntElt -> .`

Creates a file with the quadratic character data for the full relations and cycles in the NFS process $P$. There are $cc$ sets of $32$ quadratic character columns created.

##### Finding Dependencies: the Linear Algebra Stage

In this stage, the relations are collected together to form a matrix, and then block Lanczos reduction is applied to find linear dependencies among the relations. These dependencies become candidates for factorization.

<a id="function-finddependencies-nfsproc"></a>
###### `FindDependencies(P): NFSProc -> .`

Finds dependencies between relations in the NFS process $P$.

##### The Factorization Stage

In this stage, number field square roots are extracted and we attempt to factor the dependencies found in the linear algebra stage.

<a id="function-factor-nfsproc"></a>
###### `Factor(P): NFSProc -> RngIntElt`

Try to factor with each dependency in the NFS process $P$ until a proper factor is found. Returns the factor, or $0$ if no factor is found.

<a id="function-factor-nfsproc-rngintelt"></a>
###### `Factor(P, k): NFSProc, RngIntElt -> RngIntElt`

Attempt to factor with the $k$-th dependency in the NFS process $P$. Returns a proper factor if found, 0 otherwise.

#### Data Files

Many data files are ued for an NFS factorization. The user can control the names and location of the files by specifying the `OutputFilename` parameter; then all output files will have names beginning with the `OutputFilename` string, with a range of suffixes depending on their purpose. In general, all files are appended to rather than overwritten; so to avoid inconsistencies (and to save disk space) the user should call `RemoveFiles` after a successful factorization.

When distributing factorizations, or collecting results from sieving stages that have been broken up into several runs for some reason (for example, if a process has been interrupted), Magma provides the function `MergeFiles`. This takes a sequence of base filenames (which are treated as if they were the value for `OutputFilename`), and reads in the corresponding relation and partial relation files; it then combines the contents of these files, removing duplicates and corrupted lines of data, and places the results into new relation and partial relation files.

<a id="function-removefiles-nfsproc"></a>
##### `RemoveFiles(P): NFSProc -> .`

Deletes any data files created by the NFS process $P$.

<a id="function-mergefiles-monstgelt-monstgelt"></a>
##### `MergeFiles(S, fn): [MonStgElt], MonStgElt -> RngIntElt, RngIntElt`

Merges the NFS relation files named in the sequence $S$ (and their associated partial relation files) into a pair of new relation and partial relation files, while removing duplicate and corrupted lines of data; returns the number of relations and the number of partial relations in the new output files. The combined full relations are stored in a file named $fn$, and the partial relations in a file named $fn$\_partials.

##### Magma Native NFS Data Files

Here we describe the files used in a typical Magma NFS factorization. These files all use formats peculiar to `Magma`’s NFS.

The first kind of file created by NFS stores the relations generated in the sieving stage by the `FindRelations` procedure. The name of the file is precisely the `OutputFilename` string.

NFS also stores partial relations generated in the sieving stage; these are stored in a file named `OutputFilename`\_partials.

Whenever cycles [[LD95](https://docs.magma-maths.org/references.md#cite-dodsonlenstra)] are counted (for example, in `CycleCount`, a file named `OutputFilename`\_cycles is created to store them in. Some other files are also created and then deleted during the cycle counting process.

The quadratic characters calculated in `CreateCharacterFile` are stored in a file named `OutputFilename`\_cc.

The linear algebra stage creates a file named `OutputFilename`\_null_space, which lists relations making up null space vectors for the NFS matrix.

#### Distributing NFS Factorizations

Magma provides a number of tools for distributing the sieving and final factoring stages over a number of computers.

To distribute the sieving stage, each processor should get a unique range of $b$-values to sieve and unique data file names. During the sieving, the user must manually check when the combined data has enough relations to factor the number. To do this, the data files must first be merged using `MergeFiles`, and then the cycles can be counted with `CycleCount`. If the combined number of full relations plus the number of cycles exceeds the size of both factor bases combined, then the user can proceed to the other stages of the factorization attempt using the merged data file name.

To distribute the factorization stage, the user may choose a dependency for each process to factor, then call `Factor(P,k)` where $P$ is the NFS process and $k$ the number specifying the dependency to factor, with a different value of $k$ for each process.

<a id="example-ex-dc02d5"></a>
##### `Example: Distributed NFS Factorization (ex-dc02d5)`

Here we demonstrate a distributed NFS factorization (of a very small $n$) over two processes, $A$ and $B$ – which may be on different machines, or different magma processes on the same machine, or even in the same magma process.

We begin with process $A$:

```magma
> R<X,Y> := PolynomialRing(Integers( ),2);
> n := 70478782497479747987234958341;
> F := 814*X^4 + 3172*X^3*Y - 49218*X^2*Y^2 - 142775*X*Y^3
>     - 65862*Y^4;
> m1 := 3050411;
> m2 := 1;
> A := NFSProcess(n,F,m1,m2);
> A`Firstb := 0;
> A`Lastb := 99;
> A`OutputFilename := "/tmp/nfs-distrib-A";
> FindRelations(A);
3852
```

Now, process $B$, with $n$, $F$, $m1$, and $m2$ as above:

```magma
> B := NFSProcess(n,F,m1,m2);
> B`Firstb := 99;
> B`Lastb := 199;
> B`OutputFilename := "/tmp/nfs-distrib-B";
> FindRelations(B);
2455
```

Then later, on a single machine,

```magma
> input_files := ["/tmp/nfs-distrib-A","/tmp/nfs-distrib-B"];
> P := NFSProcess(n,F,m1,m2);
> P`OutputFilename := "/tmp/nfs-distrib-all";
> MergeFiles(input_files, P`OutputFilename);
4162 25925
> CycleCount(P);
4368
> CreateCycleFile(P);
> CreateCharacterFile(P);
> FindDependencies(P);
```

Now, the final factorization stage may be distributed over more than one processor also. We attempt to factor a relation on $A$:

```magma
> A`OutputFilename := "/tmp/nfs-distrib-all";
> Factor(A,9);  // factor dependency 9
0
```

No factor was found on machine $A$, but meantime on $B$:

```magma
> B`OutputFilename := "/tmp/nfs-distrib-all";
> Factor(P,1);  // factor dependency 1
94899629
> n mod $1, n div $1;
0 742666575624650207929
```

We have a successful factorisation.

#### Magma and CWI NFS Interoperability

At the time of writing, the record NFS factorizations were lead by the CWI group and by people using CWI’s or Arjen Lenstra’s code. The CWI tools use a different data file format to Magma’s native format, but Magma supplies some tools to allow users to assist in CWI factorization attempts.

The user may generate relations in CWI relation format, rather than Magma native format, by using `FindRelationsInCWIFormat`. The user should note that relations in CWI format cannot at present be used in the Auxiliary data, Linear algebra, or Factorization stages of the Magma NFS.

Alternatively, assuming some Magma NFS relations have already been computed for a process, then the user may use the procedure `ConvertToCWIFormat` to convert the relation data files from Magma native format to CWI format. The resulting data file is named `OutputFilename`\_CWI_format, and will contain both the full and partial relations of the process.

<a id="function-findrelationsincwiformat-nfsproc"></a>
##### `FindRelationsInCWIFormat(P): NFSProc -> RngIntElt`

Given an NFS process $P$ for factoring an integer $n$, generates relations to factor $n$ with the Number Field Sieve algorithm, in a file format suitable for use with CWI’s NFS tools. Returns the number of relations found.

<a id="function-converttocwiformat-nfsproc-rngintelt"></a>
##### `ConvertToCWIFormat(P, pb): NFSProc, RngIntElt -> .;`

Converts the relation files of the NFS process $P$ to CWI format, storing primes only greater than or equal to the prime printing bound $pb$. The resulting data file name will be named ``P`OutputFilename``\_CWI_format.

#### Tools for Finding a Suitable Polynomial

Magma does not provide a function to select an optimal polynomial for the factorization of a given number. However, Magma does provide some functions that are useful for the implementation of the polynomial selection algorithms developed by Peter Montgomery and Brian Murphy in [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)].

The functions `BaseMPolynomial`, `MurphyAlphaApproximation`, `OptimalSkewness`, `BestTranslation`, `PolynomialSieve`, and `DickmanRho`, will be useful for those wanting to implement polynomial selection routines within the Magma interpreter language.

<a id="function-basempolynomial-rngintelt-rngintelt-rngintelt"></a>
##### `BaseMPolynomial(n, m, d): RngIntElt, RngIntElt, RngIntElt -> RngMPolElt`

Given integers $n$, $m$, and $d$, returns a homogeneous bivariate polynomial $F = \sum_{i=0}^d c_iX^{i}Y^{d-i}$ such that the coefficients $c_i$ give a base $m$ representation of $n$: that is, $\sum_{i=0}^d c_im^i = n$. The coefficients also satisfy $|c_i| \le m/2$.

This polynomial $F$ may be used to factorize $n$ using the number field sieve (with $m_1 := m$ and $m_2 := 1$).

This function requires that $d \ge 2$ and $n \ge m^d$.

<a id="function-murphyalphaapproximation-rngmpolelt-rngintelt"></a>
##### `MurphyAlphaApproximation(F, b): RngMPolElt, RngIntElt -> FldReElt`

Given a univariate or homogeneous bivariate polynomial $F$, return an approximation of the $\alpha$ value of $F$, using primes less than the positive integer bound $b$.

The $\alpha$ value of a polynomial is defined in [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)].

Since random sampling is used for primes dividing the discriminant, successive calls to this function will give slightly different results.

<a id="function-optimalskewness-rngmpolelt"></a>
##### `OptimalSkewness(F): RngMPolElt -> FldReElt, FldReElt`

Given a univariate or homogeneous bivariate polynomial $F$, return its optimal skewness and corresponding average log size.

The optimal skewness and average log size values are defined in [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)].

<a id="example-ex-112b3b"></a>
##### `Example: Finding a Good NFS Polynomial (ex-112b3b)`

This example illustrates an effective (though not optimal) method for finding a “good” polynomial for use in NFS factorizations.

Here we search for a degree $d=4$ polynomial to use in factoring a 52-digit integer $n$.

We define the rating of a polynomial to be the sum of the $\alpha$ value and corresponding “average log size” (see [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)]).

We then proceed by iterating over base $m$ polynomials with successive leading coefficients (with the values of $m$ near $({m}^{1/d}{m}^{1/{d+1}})^{1/2}$, and chosen to minimize the second-to-leading coefficient), and choosing as a result the polynomial with the smallest rating.

```magma
> n := RandomPrime(90)*RandomPrime(90);
> n;
3596354707256253204076739374167770148715218949803889
> d := 4;
> approx_m := Iroot( Iroot( n, d+1 ) * Iroot( n, d ) , 2 );
> leading_coeff := n div approx_m^d;
> leading_coeff;
143082
> m := Iroot( n div leading_coeff, d );
> P<X,Y> := PolynomialRing( Integers(), 2 );
> F<X,Y> := BaseMPolynomial(n,m,d);
> F;
143082*X^4 + 463535*X^3*Y - 173869838910*X^2*Y^2 + 167201617413*X*Y^3 +
    159859288415*Y^4
> skew, als := OptimalSkewness( F );
> alpha := MurphyAlphaApproximation( F, 2000 );
> rating := als + alpha;
> rating;
23.143714548914575193314917
>
> best_rating := rating;
> best_m := m;
> for i in [1..100] do
>   leading_coeff := leading_coeff + 1;
>   m := Iroot( n div leading_coeff, d );
>   F<X,Y> := BaseMPolynomial(n,m,d);
>   skew, als := OptimalSkewness( F );
>   alpha := MurphyAlphaApproximation( F, 2000 );
>   rating := als + alpha;
>   if rating lt best_rating then
>     best_rating := rating;
>     best_m := m;
>   end if;
> end for;
> best_rating;
20.899568473033257031950385
> best_m;
398116527578
> F<X,Y> := BaseMPolynomial(n,best_m,d);
> F;
143160*X^4 + 199085*X^3*Y - 9094377652*X^2*Y^2 - 93898749030*X*Y^3 -
    169859083883*Y^4
> OptimalSkewness( F );
165.514255523681640625 20.969934467920612180646408
> MurphyAlphaApproximation( F, 2000 );
-0.0542716157630141449500150842
> time NFS( n, F, best_m, 1 );
...
```

<a id="function-besttranslation-rngmpolelt-rngintelt-fldreelt-fldreelt"></a>
##### `BestTranslation(F, m, a): RngMPolElt, RngIntElt, FldReElt, FldReElt -> RngMPolElt, RngIntElt, FldReElt, FldReElt`

Given a univariate or homogeneous bivariate polynomial $F$, an integer $m$, and real value $a$ (which should be the average log size of $F$ for some optimal skewness), returns a polynomial $G$ and an integer $m'$ such that $G(m') = F(m)$, together with the average log size and optimal skewness of $G$. The translation $G$ is selected such that the average log size is a local minimum.

<a id="function-polynomialsieve-rngmpolelt-rngintelt-rngintelt-rngintelt-fldreelt"></a>
##### `PolynomialSieve(F, m, J0, J1, MaxAlpha): RngMPolElt, RngIntElt, RngIntElt, RngIntElt, FldReElt -> List`

```magma
PrimeBound: RngIntElt                    Default: 1000
```

Given a homogeneous bivariate integer polynomial $F$ of degree $d$, together with integers $m$, $J_0$ and $J_1$ and a real value `MaxAlpha`, returns a list of tuples, each of which contains a polynomial $G = F + j_1x^2y^{d-2} - (|j_0| + j_1m)xy^{d-1} + (j_0m)y^d$, where $|j_0| \le J_0$ and $|j_1| \le J_1$ such that the $\alpha$ value (see [[Mur99](https://docs.magma-maths.org/references.md#cite-murphy)]) of $G$ is “better” (that is, lower) than `MaxAlpha`.

Each tuple contains the data `<`average log size + $\alpha$, skewness, $\alpha$, $G$, $m$, $j_0$, $j_1$ `>`.

If the optional parameter `PrimeBound` is set, it is used as an upper bound for primes used to calculate $\alpha$.

<a id="integer-residue"></a>
<a id="rngintres"></a>
## Integer Residue Class Rings

- [Introduction](https://docs.magma-maths.org/BasicRings/ResidueClassRings/introduction.md)
- [Ideals of ${\mathbb{Z}}$](https://docs.magma-maths.org/BasicRings/ResidueClassRings/integer-ideals.md)
  - [`ideal< R | a >: RngInt, RngIntElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/integer-ideals.md#constructor-constructor-ideal-rngint-rngintelt-rngintres)
  - [Example: Ideals of the Integers](https://docs.magma-maths.org/BasicRings/ResidueClassRings/integer-ideals.md#example-ex-1aa6f6)
- [${\mathbb{Z}}$ as a Number Field Order](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md)
  - [`Decomposition(R, p): RngInt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-decomposition-rngint-rngintelt)
  - [`Generator(I): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-generator-rngint)
  - [`RamificationIndex(I, p): RngInt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-ramificationindex-rngint-rngintelt)
  - [`RamificationIndex(I): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-ramificationindex-rngint)
  - [`Degree(I): RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-degree-rngint)
  - [`TwoElementNormal(I): RngInt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-twoelementnormal-rngint)
  - [`ChineseRemainderTheorem(I, J, a, b): RngInt, RngInt, RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-chineseremaindertheorem-rngint-rngint-rngintelt-rngintelt)
  - [`Valuation(x, I): RngIntElt, RngInt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-valuation-rngintelt-rngint)
  - [`ClassRepresentative(I): RngInt → RngInt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#function-classrepresentative-rngint)
- [Residue Class Rings](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md)
  - [Creation](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#creation)
    - [`quo<Z | I>: RngInt, RngInt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#constructor-constructor-quo-rngint-rngint-rngintres)
    - [`quo<Z | m>: RngInt, RngIntElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#constructor-constructor-quo-rngint-rngintelt-rngintres)
    - [`ResidueClassRing(m): RngIntElt → RngIntRes, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-residueclassring-rngintelt)
    - [`IntegerRing(m): RngIntElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-integerring-rngintelt)
    - [`Integers(m): RngIntElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-integers-rngintelt)
    - [`RingOfIntegers(m): RngIntElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-ringofintegers-rngintelt)
    - [`ResidueClassField(p): RngIntElt → FldFin, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-residueclassfield-rngintelt)
    - [`ResidueClassRing(Q): RngIntEltFact → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-residueclassring-rnginteltfact)
    - [`IntegerRing(Q): RngIntEltFact → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-integerring-rnginteltfact)
    - [`Integers(Q): RngIntEltFact → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-integers-rnginteltfact)
    - [Example: Cube Root in a Prime Residue Ring](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#example-ex-d9f52c)
  - [Coercion](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#coercion)
    - [Example: Coercion between Residue Class Rings](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#example-ex-155ae3)
  - [Elementary Invariants](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#elementary-invariants)
    - [`Characteristic(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-characteristic-rngintres)
    - [`# R: RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#operation-operation-rngintres-rngintreselt)
    - [`Modulus(R): RngIntRes → RngInt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-modulus-rngintres)
    - [`FactoredModulus(R): RngIntRes → RngIntEltFact`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-factoredmodulus-rngintres)
  - [Structure Operations](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#structure-operations)
    - [`AdditiveGroup(R): RngIntRes → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-additivegroup-rngintres)
    - [`MultiplicativeGroup(R): RngIntRes → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-multiplicativegroup-rngintres)
    - [`UnitGroup(R): RngIntRes → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-unitgroup-rngintres)
    - [`sub< R | n >: RngIntRes, RngIntResElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#constructor-constructor-sub-rngintres-rngintreselt-rngintres)
    - [`Set(R): RngIntRes → SetEnum`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-set-rngintres)
    - [`Category(R): RngIntRes → Cat`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-category-rngintres)
    - [`Parent(R): RngIntRes → PowerStructure`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-parent-rngintres)
    - [`PrimeRing(R): RngIntRes → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-primering-rngintres)
    - [`Center(R): RngIntRes → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-center-rngintres)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#ring-predicates-and-booleans)
    - [`IsCommutative(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-iscommutative-rngintres)
    - [`IsUnitary(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isunitary-rngintres)
    - [`IsFinite(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isfinite-rngintres)
    - [`IsOrdered(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isordered-rngintres)
    - [`IsField(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isfield-rngintres)
    - [`IsEuclideanDomain(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-iseuclideandomain-rngintres)
    - [`IsPID(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-ispid-rngintres)
    - [`IsUFD(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isufd-rngintres)
    - [`IsDivisionRing(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isdivisionring-rngintres)
    - [`IsEuclideanRing(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-iseuclideanring-rngintres)
    - [`IsPrincipalIdealRing(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isprincipalidealring-rngintres)
    - [`IsDomain(R): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#function-isdomain-rngintres)
    - [`R eq R: RngIntRes, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#operation-op-eq-rngintres-rng)
    - [`R ne R: RngIntRes, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#operation-op-ne-rngintres-rng)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#homomorphisms)
    - [`hom< R -> S | >: RngIntRes, Rng → Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/residue-class-rings.md#constructor-constructor-hom-rngintres-rng-map)
- [Elements of Residue Class Rings](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md)
  - [Creation](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#creation)
    - [`elt< R | k >: RngIntRes, RngIntElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#constructor-constructor-elt-rngintres-rngintelt-rngintreselt)
    - [`R ! k: RngIntRes, RngIntElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-rngintres-rngintelt)
    - [`One(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-one-rngintres)
    - [`Identity(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-identity-rngintres)
    - [`Zero(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-zero-rngintres)
    - [`Representative(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-representative-rngintres)
    - [`Random(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-random-rngintres)
  - [Arithmetic Operators](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#arithmetic-operators)
    - [`+ n: RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt)
    - [`- n: RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-2)
    - [`m + n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-plus-rngintreselt-rngintreselt)
    - [`m - n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-minus-rngintreselt-rngintreselt)
    - [`m * n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-times-rngintreselt-rngintreselt)
    - [`n ^ k: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-pow-rngintreselt-rngintreselt)
    - [`m / n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-div-rngintreselt-rngintreselt)
    - [`m div n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-div-rngintreselt-rngintreselt-rngintreselt)
    - [`m +:= n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-rngintreselt)
    - [`m -:= n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-rngintreselt-2)
    - [`m *:= n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-rngintreselt-3)
    - [`m /:= n: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-rngintreselt-4)
    - [`m ^:= k: RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-operation-rngintreselt-rngintreselt-rngintreselt-5)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#equality-and-membership)
    - [`m eq n: RngIntResElt, RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-eq-rngintreselt-rngintreselt)
    - [`m ne n: RngIntResElt, RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-ne-rngintreselt-rngintreselt)
    - [`n in R: RngIntResElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-in-rngintreselt-rng)
    - [`n notin R: RngIntResElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#operation-op-notin-rngintreselt-rng)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#parent-and-category)
    - [`Parent(n): RngIntResElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-parent-rngintreselt)
    - [`Category(n): RngIntResElt → Cat`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-category-rngintreselt)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#predicates-on-ring-elements)
    - [`IsZero(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-iszero-rngintreselt)
    - [`IsOne(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isone-rngintreselt)
    - [`IsMinusOne(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isminusone-rngintreselt)
    - [`IsNilpotent(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isnilpotent-rngintreselt)
    - [`IsIdempotent(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isidempotent-rngintreselt)
    - [`IsUnit(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isunit-rngintreselt)
    - [`IsZeroDivisor(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-iszerodivisor-rngintreselt)
    - [`IsRegular(n): RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isregular-rngintres)
    - [`IsIrreducible(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isirreducible-rngintreselt)
    - [`IsPrime(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-isprime-rngintreselt)
  - [Solving Equations over ${\mathbb{Z}}/m{\mathbb{Z}}$](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#solving-equations-over-mathbb-z-m-mathbb-z)
    - [`Solution(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-solution-rngintreselt-rngintreselt)
    - [`IsSquare(n): RngIntResElt → BoolElt, RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-issquare-rngintreselt)
    - [`Sqrt(a): RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-sqrt-rngintreselt)
    - [`SquareRoot(a): RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-squareroot-rngintreselt)
    - [`AllSquareRoots(a): RngIntResElt → [ RngIntResElt ]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-allsquareroots-rngintreselt)
    - [`AllSqrts(a): RngIntResElt → [ RngIntResElt ]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#function-allsqrts-rngintreselt)
    - [Example: Square Roots Modulo 2340](https://docs.magma-maths.org/BasicRings/ResidueClassRings/elements.md#example-ex-c52d75)
- [Ideal Operations](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md)
  - [`ideal< R | a₁, ..., aᵣ >: RngIntRes, RngIntResElt, ..., RngIntResElt → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#constructor-constructor-ideal-rngintres-rngintreselt-rngintreselt-rngintres)
  - [`GreatestCommonDivisor(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-greatestcommondivisor-rngintreselt-rngintreselt)
  - [`Gcd(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-gcd-rngintreselt-rngintreselt)
  - [`GCD(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-gcd-rngintreselt-rngintreselt-2)
  - [`GreatestCommonDivisor(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-greatestcommondivisor-rngintreselt)
  - [`Gcd(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-gcd-rngintreselt)
  - [`GCD(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-gcd-rngintreselt-2)
  - [`LeastCommonMultiple(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-leastcommonmultiple-rngintreselt-rngintreselt)
  - [`Lcm(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-lcm-rngintreselt-rngintreselt)
  - [`LCM(a, b): RngIntResElt, RngIntResElt → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-lcm-rngintreselt-rngintreselt-2)
  - [`LeastCommonMultiple(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-leastcommonmultiple-rngintreselt)
  - [`Lcm(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-lcm-rngintreselt)
  - [`LCM(Q): [RngIntResElt] → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#function-lcm-rngintreselt-2)
  - [`I + J: RngIntRes, RngIntRes → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-plus-rngintres-rngintres)
  - [`I * J: RngIntRes, RngIntRes → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-times-rngintres-rngintres)
  - [`I meet J: RngIntRes, RngIntRes → RngIntRes`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-meet-rngintres-rngintres)
  - [`a in I: RngIntResElt, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-in-rngintreselt-rngintres)
  - [`a notin I: RngIntResElt, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-notin-rngintreselt-rngintres)
  - [`I eq J: RngIntRes, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-eq-rngintres-rngintres)
  - [`I ne J: RngIntRes, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-ne-rngintres-rngintres)
  - [`I subset J: RngIntRes, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-op-subset-rngintres-rngintres)
  - [`I notsubset J: RngIntRes, RngIntRes → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/ideal-ops.md#operation-operation-notsubset-rngintres-rngintres-boolelt)
- [The Unit Group](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md)
  - [`UnitGroup(R): RngIntRes → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-unitgroup-rngintres-2)
  - [`IsPrimitive(n): RngIntResElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-isprimitive-rngintreselt)
  - [`PrimitiveElement(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-primitiveelement-rngintres)
  - [`PrimitiveRoot(R): RngIntRes → RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-primitiveroot-rngintres)
  - [`Order(a): RngIntResElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-order-rngintreselt)
  - [`Normalize(x): RngIntRes → RngIntResElt, RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-normalize-rngintres)
  - [`Normalise(x): RngIntRes → RngIntResElt, RngIntResElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#function-normalise-rngintres)
  - [Example: Unit Group of a Residue Class Ring](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#example-ex-8ae5da)
  - [Example: Cyclic Unit Group](https://docs.magma-maths.org/BasicRings/ResidueClassRings/unit-group.md#example-ex-bde8d2)
- [Dirichlet Characters](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md)
  - [Creation](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#creation)
    - [`DirichletGroup(N): RngIntElt → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-dirichletgroup-rngintelt)
    - [`FullDirichletGroup(N): RngIntElt → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-fulldirichletgroup-rngintelt)
    - [`DirichletGroup(N,R): RngIntElt, Rng → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-dirichletgroup-rngintelt-rng)
    - [`DirichletGroup(N,R,z,r): RngIntElt, Rng, RngElt, RngIntElt → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-dirichletgroup-rngintelt-rng-rngelt-rngintelt)
    - [`BaseExtend(G, R): GrpDrch, Rng → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-baseextend-grpdrch-rng)
    - [`BaseExtend(G, R, z): GrpDrch, Rng, RngElt → GrpDrch`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-baseextend-grpdrch-rng-rngelt)
    - [`AssignNames(~G, S): GrpDrch, [MonStgElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#procedure-assignnames-grpdrch-monstgelt-ref)
  - [Element Creation](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#element-creation)
    - [`Elements(G): GrpDrch → [GrpDrchElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-elements-grpdrch)
    - [`Random(G): GrpDrch → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-random-grpdrch)
    - [`G . i: GrpDrch, RngIntElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-operation-grpdrch-rngintelt-grpdrchelt)
    - [`G ! x: GrpDrch, Any → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-grpdrch-any)
    - [`KroneckerCharacter(D): RngIntElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-kroneckercharacter-rngintelt)
    - [`KroneckerCharacter(D, R): RngIntElt, Rng → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-kroneckercharacter-rngintelt-rng)
  - [Attributes of Dirichlet Groups](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#attributes-of-dirichlet-groups)
    - [`BaseRing(G): GrpDrch → Rng`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-basering-grpdrch)
    - [`Modulus(G): GrpDrch → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-modulus-grpdrch)
    - [`Order(G): GrpDrch → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-order-grpdrch)
    - [`Exponent(G): GrpDrch → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-exponent-grpdrch)
    - [`NumberOfGenerators(G): GrpDrch → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-numberofgenerators-grpdrch)
    - [`Generators(G): GrpDrch → [GrpDrchElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-generators-grpdrch)
    - [`UnitGenerators(G): GrpDrch → [RngIntElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-unitgenerators-grpdrch)
    - [`GaloisConjugacyRepresentatives(G): GrpDrch → [GrpDrchElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-galoisconjugacyrepresentatives-grpdrch)
    - [`GaloisConjugacyRepresentatives(seq): [GrpDrchElt] → [GrpDrchElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-galoisconjugacyrepresentatives-grpdrchelt)
    - [`AbelianGroup(G): GrpDrch → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-abeliangroup-grpdrch)
  - [Attributes of Elements](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#attributes-of-elements)
    - [`BaseRing(chi): GrpDrchElt → Rng`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-basering-grpdrchelt)
    - [`Modulus(chi): GrpDrchElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-modulus-grpdrchelt)
    - [`Conductor(chi): GrpDrchElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-conductor-grpdrchelt)
    - [`ElementToSequence(chi): GrpDrchElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-elementtosequence-grpdrchelt)
    - [`x eq y: GrpDrchElt, GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-eq-grpdrchelt-grpdrchelt)
    - [`Order(chi): GrpDrchElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-order-grpdrchelt)
    - [`IsTrivial(chi): GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-istrivial-grpdrchelt)
    - [`IsPrimitive(chi): GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-isprimitive-grpdrchelt)
    - [`AssociatedPrimitiveCharacter(chi): GrpDrchElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-associatedprimitivecharacter-grpdrchelt)
    - [`IsEven(chi): GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-iseven-grpdrchelt)
    - [`IsOdd(chi): GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-isodd-grpdrchelt)
    - [`IsTotallyEven(chi): GrpDrchElt → BoolElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-istotallyeven-grpdrchelt)
    - [`Decomposition(chi): GrpDrchElt → List`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-decomposition-grpdrchelt)
    - [`MinimalBaseRingCharacter(chi): GrpDrchElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-minimalbaseringcharacter-grpdrchelt)
  - [Evaluation](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#evaluation)
    - [`Evaluate(chi,n): GrpDrchElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-evaluate-grpdrchelt-rngintelt)
    - [`chi(n): GrpDrchElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-chi-grpdrchelt-rngintelt)
    - [`ValueList(chi): GrpDrchElt → [RngElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-valuelist-grpdrchelt)
    - [`ValuesOnUnitGenerators(chi): GrpDrchElt → [RngElt]`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-valuesonunitgenerators-grpdrchelt)
    - [`OrderOfRootOfUnity(r, n): RngElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-orderofrootofunity-rngelt-rngintelt)
  - [Arithmetic](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#arithmetic)
    - [`x * y: GrpDrchElt, GrpDrchElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-times-grpdrchelt-grpdrchelt)
    - [`x / y: GrpDrchElt, GrpDrchElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-div-grpdrchelt-grpdrchelt)
    - [`x ^ n: GrpDrchElt, RngIntElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-pow-grpdrchelt-rngintelt)
    - [`x ^ phi: GrpDrchElt, Map → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#operation-op-pow-grpdrchelt-map)
    - [`Sqrt(x): GrpDrchElt → GrpDrchElt`](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#function-sqrt-grpdrchelt)
  - [Example](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#example)
    - [Example: Dirichlet Characters Modulo 5](https://docs.magma-maths.org/BasicRings/ResidueClassRings/dirichlet-characters.md#example-ex-19f11f)

### Introduction

This chapter presents the machinery provided in Magma for computing in quotient rings of the ring of integers ${\mathbb{Z}}$, that is, integer residue class rings. The first half of the chapter describes operations with ideals of ${\mathbb{Z}}$ and their quotient rings while the second half provides an introduction to computing with Dirichlet characters.

<a id="integer-ideals"></a>
<a id="rngintres-ideal-division"></a>
<a id="ideals-of-mathbb-z"></a>
### Ideals of ${\mathbb{Z}}$

The theory of ideals of ${\mathbb{Z}}$ is very elementary but for completeness the general machinery for ring ideals applies. Such ideals will have type `RngInt`, that is, the same type as the ring of integers itself (`ideal<Integers() | 1>`).

In the case of ${\mathbb{Z}}$ any subring is an ideal so that the `sub`-constructor creates the same object as does the `ideal`-constructor. One quirk of this fact that ideals are of type `RngInt` is that taking $R/I$ will result in the *ideal division* rather than the ring-by-ideal quotient (this is for compatibility with orders of number fields, as explained in the next section). Here is an example that shows the difference.

```
> Z := Integers();
> I := ideal<Z|1>; // ideal of Z
> Z/I; // interpreted as ideal division
Integer Ring
> quo<Z|I>; // quotient of ring by ideal
Residue class ring of integers modulo 1
```

<a id="constructor-constructor-ideal-rngint-rngintelt-rngintres"></a>
#### `ideal< R | a >: RngInt, RngIntElt -> RngIntRes`

Given the ring of integers ${\mathbb{Z}}$ and an integer $a$, return the ideal of ${\mathbb{Z}}$ generated by $a$.

<a id="example-ex-1aa6f6"></a>
#### `Example: Ideals of the Integers (ex-1aa6f6)`

We construct some ideals of ${\mathbb{Z}}$.

```magma
> Z := IntegerRing();
> I13 := ideal< Z | 13 >;
> I13;
Ideal of Integer Ring generated by 13
> 1 in I13;
false
> 0 in I13;
true
> -13 in I13;
true
> I0 := ideal< Z | 0 >;
> 0 in I0;
true
> 1 in I0;
false
```

We check that ${\mathbb{Z}}$ is regarded as an ideal.

```magma
> I1 := ideal< Z | 1 >;
> I1 eq Z;
true
```

<a id="mathbb-z-as-a-number-field-order"></a>
<a id="number-field-like"></a>
<a id="rngintres-zasnford"></a>
### ${\mathbb{Z}}$ as a Number Field Order

A collection of functions are provided that make ${\mathbb{Z}}$ behave like an order of a number field. Note however, that ${\mathbb{Z}}$ is not of type `RngOrd`. If complete compatibility is necessary, the user should create the maximal order of a degree $1$ extension of ${\mathbb{Q}}$.

<a id="function-decomposition-rngint-rngintelt"></a>
#### `Decomposition(R, p): RngInt, RngIntElt -> SeqEnum`

Returns the ideal decomposition of the prime $p$, i.e. a list `[ < ideal<Z|p>, 1> ]` as in the number field case.

<a id="function-generator-rngint"></a>
#### `Generator(I): RngInt -> RngIntElt`

A generator for the given ideal.

<a id="function-ramificationindex-rngint-rngintelt"></a>
#### `RamificationIndex(I, p): RngInt, RngIntElt -> RngIntElt`

<a id="function-ramificationindex-rngint"></a>
#### `RamificationIndex(I): RngInt -> RngIntElt`

The ramification index of $I$ over ${\mathbb{Z}}$ which is always $1$.

<a id="function-degree-rngint"></a>
#### `Degree(I): RngInt -> RngIntElt`

The inertia degree of the ideal $I$, which is always $1$.

<a id="function-twoelementnormal-rngint"></a>
#### `TwoElementNormal(I): RngInt -> RngIntElt, RngIntElt`

Two integers that generate the ideal $I$. In this case the generator is returned twice.

<a id="function-chineseremaindertheorem-rngint-rngint-rngintelt-rngintelt"></a>
#### `ChineseRemainderTheorem(I, J, a, b): RngInt, RngInt, RngIntElt, RngIntElt -> RngIntElt`

The Chinese remainder theorem for ideals. Given ideals $I$ and $J$ of ${\mathbb{Z}}$ together with integers $a$ and $b$, an integer $x$ such that $x-a \in I$ and $x-b \in J$ is returned.

<a id="function-valuation-rngintelt-rngint"></a>
#### `Valuation(x, I): RngIntElt, RngInt -> RngIntElt`

The valuation of the integer $x$ at the prime ideal $I$.

<a id="function-classrepresentative-rngint"></a>
#### `ClassRepresentative(I): RngInt -> RngInt`

The representative of the ideal $I$ of ${\mathbb{Z}}$ in the basis of the class group.

<a id="rngint-rngintres"></a>
<a id="id1"></a>
### Residue Class Rings

The ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$ consists of representatives for the residue classes of integers modulo $m > 1$. This Section describes the operations in Magma for such rings and their elements.

At any stage during a session, Magma will have at most one copy of ${{\mathbb{Z}}/m{\mathbb{Z}}}$ present, for any $m>1$. In other words, different names for the same residue class ring will in fact be different references to the same structure. This saves memory and avoids confusion about different but isomorphic structures.

If $m$ is a prime number, the ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$ forms a field; however, Magma has special functions for dealing with finite fields. The operations described here should *not* be used for finite field calculations: the implementation of finite field arithmetic in Magma as described in Chapter [Finite Fields](https://docs.magma-maths.org/BasicRings/FiniteFields/index-finite-fields.md#fldfin) takes full advantage of the special structure of finite fields and leads to superior performance.

#### Creation

In addition to the general quotient constructor, a number of abbreviations are provided for computing residue class rings.

<a id="constructor-constructor-quo-rngint-rngint-rngintres"></a>
##### `quo<Z | I>: RngInt, RngInt -> RngIntRes`

Given the ring of integers ${\mathbb{Z}}$, and an ideal $I$, create the residue class ring modulo the ideal.

Note that $Z/I$ does **not** give this residue ring, but rather, in compatibility with ${\mathbb{Z}}$ as a number field order, returns the ideal quotient, namely ${\mathbb{Z}}$ itself (see Section [${\mathbb{Z}}$ as a Number Field Order](https://docs.magma-maths.org/BasicRings/ResidueClassRings/number-field-like.md#rngintres-zasnford) above, and the example in Sections [Ideals of ${\mathbb{Z}}$](https://docs.magma-maths.org/BasicRings/ResidueClassRings/integer-ideals.md#rngintres-ideal-division)).

<a id="constructor-constructor-quo-rngint-rngintelt-rngintres"></a>
##### `quo<Z | m>: RngInt, RngIntElt -> RngIntRes`

Given the ring of integers ${\mathbb{Z}}$, and an integer $m \ne 0$, create the residue class ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$.

<a id="function-residueclassring-rngintelt"></a>
##### `ResidueClassRing(m): RngIntElt -> RngIntRes, Map`

<a id="function-integerring-rngintelt"></a>
##### `IntegerRing(m): RngIntElt -> RngIntRes`

<a id="function-integers-rngintelt"></a>
##### `Integers(m): RngIntElt -> RngIntRes`

<a id="function-ringofintegers-rngintelt"></a>
##### `RingOfIntegers(m): RngIntElt -> RngIntRes`

Given an integer greater than zero, create the residue class ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$ and also returns the map from ${\mathbb{Z}}$ into ${{\mathbb{Z}}/m{\mathbb{Z}}}$.

<a id="function-residueclassfield-rngintelt"></a>
##### `ResidueClassField(p): RngIntElt -> FldFin, Map`

Given a prime integer $p$ construct the residue class field ${\mathbb{F}}_p$ and the map from ${\mathbb{Z}}$ into ${\mathbb{F}}_p$.

<a id="function-residueclassring-rnginteltfact"></a>
##### `ResidueClassRing(Q): RngIntEltFact -> RngIntRes`

<a id="function-integerring-rnginteltfact"></a>
##### `IntegerRing(Q): RngIntEltFact -> RngIntRes`

<a id="function-integers-rnginteltfact"></a>
##### `Integers(Q): RngIntEltFact -> RngIntRes`

Create the residue class ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$, where $m$ is the integer corresponding to the factorization sequence $Q$. This is more efficient than creating the ring by $m$ alone, since the factorization $Q$ will be stored so it can be reused later.

<a id="example-ex-d9f52c"></a>
##### `Example: Cube Root in a Prime Residue Ring (ex-d9f52c)`

We construct a residue ring having modulus the largest prime not exceeding $2^{16}$.

```magma
> p := PreviousPrime(2^16);
> p;
65521
> R := ResidueClassRing(p);
Residue class ring of integers modulo 65521
```

Now we try to find an element $x$ in $R$ such that $x^3 = 23$.

```magma
> exists(t){x : x in R | x^3 eq 23};
true
> t;
12697
```

#### Coercion

As can be seen from the tables in Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro), automatic coercion takes place between ${{\mathbb{Z}}/m{\mathbb{Z}}}$ and ${\mathbb{Z}}$ so that a binary operation like $+$ applied to an element of ${{\mathbb{Z}}/m{\mathbb{Z}}}$ and an integer will result in a residue class from ${{\mathbb{Z}}/m{\mathbb{Z}}}$. Using `!`, elements from a prime field ${\bf F}_{p}$ can be coerced into ${{\mathbb{Z}}/p{\mathbb{Z}}}$, and elements from ${{\mathbb{Z}}/p{\mathbb{Z}}}$ can be coerced into ${\bf F}_{p^r}$. Also, transitions between ${{\mathbb{Z}}/m{\mathbb{Z}}}$ and ${{\mathbb{Z}}/n{\mathbb{Z}}}$ can be made using `!` provided that $m$ divides $n$ or $n$ divides $m$. In cases where there is a choice – such as when an element $r$ from ${{\mathbb{Z}}/m{\mathbb{Z}}}$ is coerced into ${{\mathbb{Z}}/n{\mathbb{Z}}}$ with $m$ dividing $n$ – the result will be the residue class containing the representative for $r$.

<a id="example-ex-155ae3"></a>
##### `Example: Coercion between Residue Class Rings (ex-155ae3)`

```magma
> r := ResidueClassRing(3) ! 5;
> r;
2
> ResidueClassRing(6) ! r;
2
```

So the representative 2 of $5\bmod 3$ is mapped to the residue class $2 \bmod 6$, and not to $5\bmod 6$.

#### Elementary Invariants

<a id="function-characteristic-rngintres"></a>
##### `Characteristic(R): RngIntRes -> RngIntResElt`

<a id="operation-operation-rngintres-rngintreselt"></a>
##### `# R: RngIntRes -> RngIntResElt`

<a id="function-modulus-rngintres"></a>
##### `Modulus(R): RngIntRes -> RngInt`

Given a residue class ring $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, this function returns the common modulus $m$ for the elements of $R$.

<a id="function-factoredmodulus-rngintres"></a>
##### `FactoredModulus(R): RngIntRes -> RngIntEltFact`

Given a residue class ring $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, this function returns the factorization of the common modulus $m$ for the elements of $R$.

#### Structure Operations

<a id="function-additivegroup-rngintres"></a>
##### `AdditiveGroup(R): RngIntRes -> GrpAb, Map`

Given $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, create the abelian group of integers modulo $m$ under addition. This returns the finite additive abelian group $A$ (of order $m$) together with a map from $A$ to the ring ${{\mathbb{Z}}/m{\mathbb{Z}}}$, sending $A.1$ to $1$.

<a id="function-multiplicativegroup-rngintres"></a>
##### `MultiplicativeGroup(R): RngIntRes -> GrpAb, Map`

<a id="function-unitgroup-rngintres"></a>
##### `UnitGroup(R): RngIntRes -> GrpAb, Map`

Given $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, create the multiplicative group of $R$ as an abelian group. This returns an (additive) abelian group $A$ of order $\phi(m)$, together with a map from $A$ to $R$.

<a id="constructor-constructor-sub-rngintres-rngintreselt-rngintres"></a>
##### `sub< R | n >: RngIntRes, RngIntResElt -> RngIntRes`

Given $R$, the ring of integers modulo $m$ or an ideal of it, and an element $n$ of $R$ create the ideal of $R$ generated by $n$.

<a id="function-set-rngintres"></a>
##### `Set(R): RngIntRes -> SetEnum`

Create the enumerated set consisting of the elements of the residue class ring $R$.

<a id="function-category-rngintres"></a>
##### `Category(R): RngIntRes -> Cat`

<a id="function-parent-rngintres"></a>
##### `Parent(R): RngIntRes -> PowerStructure`

<a id="function-primering-rngintres"></a>
##### `PrimeRing(R): RngIntRes -> RngIntRes`

<a id="function-center-rngintres"></a>
##### `Center(R): RngIntRes -> RngIntRes`

#### Ring Predicates and Booleans

<a id="function-iscommutative-rngintres"></a>
##### `IsCommutative(R): RngIntRes -> BoolElt`

<a id="function-isunitary-rngintres"></a>
##### `IsUnitary(R): RngIntRes -> BoolElt`

<a id="function-isfinite-rngintres"></a>
##### `IsFinite(R): RngIntRes -> BoolElt`

<a id="function-isordered-rngintres"></a>
##### `IsOrdered(R): RngIntRes -> BoolElt`

<a id="function-isfield-rngintres"></a>
##### `IsField(R): RngIntRes -> BoolElt`

<a id="function-iseuclideandomain-rngintres"></a>
##### `IsEuclideanDomain(R): RngIntRes -> BoolElt`

<a id="function-ispid-rngintres"></a>
##### `IsPID(R): RngIntRes -> BoolElt`

<a id="function-isufd-rngintres"></a>
##### `IsUFD(R): RngIntRes -> BoolElt`

<a id="function-isdivisionring-rngintres"></a>
##### `IsDivisionRing(R): RngIntRes -> BoolElt`

<a id="function-iseuclideanring-rngintres"></a>
##### `IsEuclideanRing(R): RngIntRes -> BoolElt`

<a id="function-isprincipalidealring-rngintres"></a>
##### `IsPrincipalIdealRing(R): RngIntRes -> BoolElt`

<a id="function-isdomain-rngintres"></a>
##### `IsDomain(R): RngIntRes -> BoolElt`

<a id="operation-op-eq-rngintres-rng"></a>
##### `R eq R: RngIntRes, Rng -> BoolElt`

<a id="operation-op-ne-rngintres-rng"></a>
##### `R ne R: RngIntRes, Rng -> BoolElt`

#### Homomorphisms

Ring homomorphisms with domain ${{\mathbb{Z}}/m{\mathbb{Z}}}$ are completely determined by the image of $1$. As usual (see Chapter [Ring of Integers](https://docs.magma-maths.org/BasicRings/Integers/index-integers.md#rngint) ), we require our homomorphisms to map 1 to 1. Therefore, the general homomorphism constructor with domain ${{\mathbb{Z}}/m{\mathbb{Z}}}$ needs no arguments.

<a id="constructor-constructor-hom-rngintres-rng-map"></a>
##### `hom< R -> S | >: RngIntRes, Rng -> Map`

Given a residue class ring $R$, and a ring $S$, create a homomorphism from $R$ to $S$, determined by $f(1_R) = 1_S$. Note that it is the responsibility of the user that the map defines a homomorphism!

### Elements of Residue Class Rings

#### Creation

<a id="constructor-constructor-elt-rngintres-rngintelt-rngintreselt"></a>
##### `elt< R | k >: RngIntRes, RngIntElt -> RngIntResElt`

Create the residue class containing the integer $k$ in residue class ring $R$.

<a id="operation-op-rngintres-rngintelt"></a>
##### `R ! k: RngIntRes, RngIntElt -> RngIntResElt`

Create the residue class containing $k$ in the residue class ring $R$. Here $k$ is allowed to be either an integer, or an element of the finite field ${\mathbb{F}}_p$ in the case $R = {\mathbb{Z}}/p{\mathbb{Z}}$, or an element of $S = {\mathbb{Z}}/n{\mathbb{Z}}$ for a multiple or divisor $n$ of $m$ (with $R = {{\mathbb{Z}}/m{\mathbb{Z}}}$).

<a id="function-one-rngintres"></a>
##### `One(R): RngIntRes -> RngIntResElt`

<a id="function-identity-rngintres"></a>
##### `Identity(R): RngIntRes -> RngIntResElt`

<a id="function-zero-rngintres"></a>
##### `Zero(R): RngIntRes -> RngIntResElt`

<a id="function-representative-rngintres"></a>
##### `Representative(R): RngIntRes -> RngIntResElt`

These generic functions (cf. Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro)) create $1$, $1$, $0$, and $0$ respectively, in any ${{\mathbb{Z}}/m{\mathbb{Z}}}$.

<a id="function-random-rngintres"></a>
##### `Random(R): RngIntRes -> RngIntResElt`

Create a “random” residue class in $R$.

#### Arithmetic Operators

<a id="operation-operation-rngintreselt-rngintreselt"></a>
##### `+ n: RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-2"></a>
##### `- n: RngIntResElt -> RngIntResElt`

<a id="operation-op-plus-rngintreselt-rngintreselt"></a>
##### `m + n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-op-minus-rngintreselt-rngintreselt"></a>
##### `m - n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-op-times-rngintreselt-rngintreselt"></a>
##### `m * n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-op-pow-rngintreselt-rngintreselt"></a>
##### `n ^ k: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-op-div-rngintreselt-rngintreselt"></a>
##### `m / n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-div-rngintreselt-rngintreselt-rngintreselt"></a>
##### `m div n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-rngintreselt"></a>
##### `m +:= n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-rngintreselt-2"></a>
##### `m -:= n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-rngintreselt-3"></a>
##### `m *:= n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-rngintreselt-4"></a>
##### `m /:= n: RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="operation-operation-rngintreselt-rngintreselt-rngintreselt-5"></a>
##### `m ^:= k: RngIntResElt, RngIntResElt -> RngIntResElt`

#### Equality and Membership

<a id="operation-op-eq-rngintreselt-rngintreselt"></a>
##### `m eq n: RngIntResElt, RngIntResElt -> BoolElt`

<a id="operation-op-ne-rngintreselt-rngintreselt"></a>
##### `m ne n: RngIntResElt, RngIntResElt -> BoolElt`

<a id="operation-op-in-rngintreselt-rng"></a>
##### `n in R: RngIntResElt, Rng -> BoolElt`

<a id="operation-op-notin-rngintreselt-rng"></a>
##### `n notin R: RngIntResElt, Rng -> BoolElt`

#### Parent and Category

<a id="function-parent-rngintreselt"></a>
##### `Parent(n): RngIntResElt -> RngIntRes`

<a id="function-category-rngintreselt"></a>
##### `Category(n): RngIntResElt -> Cat`

#### Predicates on Ring Elements

<a id="function-iszero-rngintreselt"></a>
##### `IsZero(n): RngIntResElt -> BoolElt`

<a id="function-isone-rngintreselt"></a>
##### `IsOne(n): RngIntResElt -> BoolElt`

<a id="function-isminusone-rngintreselt"></a>
##### `IsMinusOne(n): RngIntResElt -> BoolElt`

<a id="function-isnilpotent-rngintreselt"></a>
##### `IsNilpotent(n): RngIntResElt -> BoolElt`

<a id="function-isidempotent-rngintreselt"></a>
##### `IsIdempotent(n): RngIntResElt -> BoolElt`

<a id="function-isunit-rngintreselt"></a>
##### `IsUnit(n): RngIntResElt -> BoolElt`

<a id="function-iszerodivisor-rngintreselt"></a>
##### `IsZeroDivisor(n): RngIntResElt -> BoolElt`

<a id="function-isregular-rngintres"></a>
##### `IsRegular(n): RngIntRes -> BoolElt`

<a id="function-isirreducible-rngintreselt"></a>
##### `IsIrreducible(n): RngIntResElt -> BoolElt`

<a id="function-isprime-rngintreselt"></a>
##### `IsPrime(n): RngIntResElt -> BoolElt`

<a id="solving-equations-over-mathbb-z-m-mathbb-z"></a>
#### Solving Equations over ${\mathbb{Z}}/m{\mathbb{Z}}$

<a id="function-solution-rngintreselt-rngintreselt"></a>
##### `Solution(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

Given elements $a$ and $b$ of ${\mathbb{Z}}/m{\mathbb{Z}}$, return a solution $x$ to the linear congruence $a\cdot x=b \in {{\mathbb{Z}}/m{\mathbb{Z}}}$. An error is signalled if no solution exists.

<a id="function-issquare-rngintreselt"></a>
##### `IsSquare(n): RngIntResElt -> BoolElt, RngIntResElt`

```magma
Factorization: [<RngIntElt, RngIntElt>]                    Default: [ ]
```

Given an element $n\in{{\mathbb{Z}}/m{\mathbb{Z}}}$ this function returns `true` if there exists $a\in{{\mathbb{Z}}/m{\mathbb{Z}}}$ such that $a^2=n\in{{\mathbb{Z}}/m{\mathbb{Z}}}$, `false` otherwise. If $n$ is a square, a square root $a$ is also returned. If $m$ is large and its prime factorization is known, the computation may be speeded up by assigning the factorization sequence for $m$ to the optional argument `Factorization`.

<a id="function-sqrt-rngintreselt"></a>
##### `Sqrt(a): RngIntResElt -> RngIntResElt`

<a id="function-squareroot-rngintreselt"></a>
##### `SquareRoot(a): RngIntResElt -> RngIntResElt`

```magma
Factorization: [<RngIntElt, RngIntElt>]                    Default: [ ]
```

Given an element $a$ of the ring ${\mathbb{Z}}/m{\mathbb{Z}}$, this function returns an element $b$ of ${\mathbb{Z}}/m{\mathbb{Z}}$ such that $b^2=a\in{{\mathbb{Z}}/m{\mathbb{Z}}}$, if such an element exists, and an error otherwise. If $m$ is large and its prime factorization is known, the computation may be speeded up by assigning the factorization sequence for $m$ to the optional argument `Factorization`.

<a id="function-allsquareroots-rngintreselt"></a>
##### `AllSquareRoots(a): RngIntResElt -> [ RngIntResElt ]`

<a id="function-allsqrts-rngintreselt"></a>
##### `AllSqrts(a): RngIntResElt -> [ RngIntResElt ]`

```magma
Factorization: [<RngIntElt, RngIntElt>]                    Default: [ ]
```

Return a sequence containing all square roots of the element $a$ in a residue class ring ${\mathbb{Z}}/m{\mathbb{Z}}$. If the modulus $m$ is large and its prime factorization is known, the computation may be speeded up by assigning the factorization sequence for $m$ to the optional argument `Factorization`.

<a id="example-ex-c52d75"></a>
##### `Example: Square Roots Modulo 2340 (ex-c52d75)`

We construct the residue class ring having modulus $2340$ and find all the square roots of $1404$.

```magma
> R := ResidueClassRing(2340);
Residue class ring of integers modulo 2340
> x := R!1404;
> sqrts := AllSquareRoots(x);
> sqrts;
[ 78, 312, 468, 702, 858, 1092, 1248, 1482, 1638,
  1872, 2028, 2262 ]
> [ y^2 : y in sqrts ];
[ 1404, 1404, 1404, 1404, 1404, 1404, 1404, 1404,
  1404, 1404, 1404, 1404 ]
```

So 1404 has 12 square roots!

### Ideal Operations

<a id="constructor-constructor-ideal-rngintres-rngintreselt-rngintreselt-rngintres"></a>
#### `ideal< R | a₁, ..., aᵣ >: RngIntRes, RngIntResElt, ..., RngIntResElt -> RngIntRes`

The ideal of the residue ring $R$ generated by the greatest common divisor of the elements $a_i$ and the modulus of $R$.

<a id="function-greatestcommondivisor-rngintreselt-rngintreselt"></a>
#### `GreatestCommonDivisor(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="function-gcd-rngintreselt-rngintreselt"></a>
#### `Gcd(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="function-gcd-rngintreselt-rngintreselt-2"></a>
#### `GCD(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

Greatest common divisor of the elements $a$ and $b$ of $R$, that is, a generator for the $R$-ideal $(a)+(b)$.

<a id="function-greatestcommondivisor-rngintreselt"></a>
#### `GreatestCommonDivisor(Q): [RngIntResElt] -> RngIntResElt`

<a id="function-gcd-rngintreselt"></a>
#### `Gcd(Q): [RngIntResElt] -> RngIntResElt`

<a id="function-gcd-rngintreselt-2"></a>
#### `GCD(Q): [RngIntResElt] -> RngIntResElt`

Greatest common divisor of the sequence of elements $Q$, that is, a generator for the $R$-ideal generated by the elements in $Q$.

<a id="function-leastcommonmultiple-rngintreselt-rngintreselt"></a>
#### `LeastCommonMultiple(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="function-lcm-rngintreselt-rngintreselt"></a>
#### `Lcm(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

<a id="function-lcm-rngintreselt-rngintreselt-2"></a>
#### `LCM(a, b): RngIntResElt, RngIntResElt -> RngIntResElt`

Least common multiple of the elements $a$ and $b$ of $R$, that is, a generator for the $R$-ideal $(a)\cap (b)$.

<a id="function-leastcommonmultiple-rngintreselt"></a>
#### `LeastCommonMultiple(Q): [RngIntResElt] -> RngIntResElt`

<a id="function-lcm-rngintreselt"></a>
#### `Lcm(Q): [RngIntResElt] -> RngIntResElt`

<a id="function-lcm-rngintreselt-2"></a>
#### `LCM(Q): [RngIntResElt] -> RngIntResElt`

Least common multiple of the sequence of elements $Q$, that is, a generator for the $R$-ideal formed by the intersection of the principal ideals generated by elements of $Q$.

<a id="operation-op-plus-rngintres-rngintres"></a>
#### `I + J: RngIntRes, RngIntRes -> RngIntRes`

<a id="operation-op-times-rngintres-rngintres"></a>
#### `I * J: RngIntRes, RngIntRes -> RngIntRes`

<a id="operation-op-meet-rngintres-rngintres"></a>
#### `I meet J: RngIntRes, RngIntRes -> RngIntRes`

<a id="operation-op-in-rngintreselt-rngintres"></a>
#### `a in I: RngIntResElt, RngIntRes -> BoolElt`

<a id="operation-op-notin-rngintreselt-rngintres"></a>
#### `a notin I: RngIntResElt, RngIntRes -> BoolElt`

<a id="operation-op-eq-rngintres-rngintres"></a>
#### `I eq J: RngIntRes, RngIntRes -> BoolElt`

<a id="operation-op-ne-rngintres-rngintres"></a>
#### `I ne J: RngIntRes, RngIntRes -> BoolElt`

<a id="operation-op-subset-rngintres-rngintres"></a>
#### `I subset J: RngIntRes, RngIntRes -> BoolElt`

<a id="operation-operation-notsubset-rngintres-rngintres-boolelt"></a>
#### `I notsubset J: RngIntRes, RngIntRes -> BoolElt`

### The Unit Group

<a id="function-unitgroup-rngintres-2"></a>
#### `UnitGroup(R): RngIntRes -> GrpAb, Map`

Given $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, construct the unit group of $R$ as an abelian group. This returns an (additive) abelian group $A$ of order $\phi(m)$, together with a map from $A$ to $R$.

<a id="function-isprimitive-rngintreselt"></a>
#### `IsPrimitive(n): RngIntResElt -> BoolElt`

Returns `true` if the element $n\in{{\mathbb{Z}}/m{\mathbb{Z}}}$ is primitive, that is, if it generates the multiplicative group of ${{\mathbb{Z}}/m{\mathbb{Z}}}$, `false` otherwise.

<a id="function-primitiveelement-rngintres"></a>
#### `PrimitiveElement(R): RngIntRes -> RngIntResElt`

<a id="function-primitiveroot-rngintres"></a>
#### `PrimitiveRoot(R): RngIntRes -> RngIntResElt`

Given $R = {\mathbb{Z}}/m{\mathbb{Z}}$, this function returns a generator for the group of units of $R$ if this group is cyclic, and returns $0$ otherwise. Thus a valid generator is only returned if $m = 2, 4, p^t$ or $2p^t$, with $p$ an odd prime and $t\geq 1$.

<a id="function-order-rngintreselt"></a>
#### `Order(a): RngIntResElt -> RngIntElt`

Given an element $a$ belonging to ${{\mathbb{Z}}/m{\mathbb{Z}}}$, return the multiplicative order $k \geq 1$ of $a$ if $a$ is in the unit group ${({{\mathbb{Z}}/m{\mathbb{Z}}})^*}$, and zero if $a$ is not a unit.

<a id="function-normalize-rngintres"></a>
#### `Normalize(x): RngIntRes -> RngIntResElt, RngIntResElt`

<a id="function-normalise-rngintres"></a>
#### `Normalise(x): RngIntRes -> RngIntResElt, RngIntResElt`

Given an element $x\in R = {\mathbb{Z}}/m{\mathbb{Z}}$, this function returns the unique canonical associate $y\in R$ of $x$ and a unit $u\in R$ such that $u\cdot x = y$. The canonical associate of $x$ is the GCD of $x$ and $m$, considered as natural integers (unless $x$ is 0, in which case it is 0).

<a id="example-ex-8ae5da"></a>
#### `Example: Unit Group of a Residue Class Ring (ex-8ae5da)`

We determine the unit group of the ring with modulus $735$ and then verify its order by comparing it with $\phi(m)$.

```magma
> m := 735;
> R := ResidueClassRing(m);
Residue class ring of integers modulo 735
> U, psi := UnitGroup(R);
> U;
Abelian Group isomorphic to Z/2 + Z/2 + Z/84
Defined on 3 generators
Relations:
    2*U.1 = 0
    4*U.2 = 0
    42*U.3 = 0
> #U;
336
> EulerPhi(735);
336
```

So the order of $U$ is equal to $\phi(m)$ as it should be. Finally, we look for three elements of $R$ that generate the unit group.

```magma
> gens := [ psi(U.i) : i in [1..3] ]; gens;
> [ Order(x) : x in gens ];
[ 2, 4, 42 ]
```

<a id="example-ex-bde8d2"></a>
#### `Example: Cyclic Unit Group (ex-bde8d2)`

We construct a residue class ring $R = {\mathbb{Z}}/m{\mathbb{Z}}$ having cyclic unit group. By a theorem of Gauss, the ring $R$ has cyclic unit group precisely when $n = 4, n = p^e,$ or $n = 2p^e$, and $p$ is an odd prime.

```magma
> R := IntegerRing(50);
> U, psi := UnitGroup(R);
Abelian Group isomorphic to Z/20
Defined on 1 generator
Relations:
    20*U.1 = 0
> w := PrimitiveElement(R);
> w;
3
> Order(w);
20
```

We verify that the powers of $w$ are precisely the elements of the unit group $U$.

```magma
> powers := { w^i : i in [0..19] };
> powers;
{ 29, 1, 31, 3, 33, 7, 37, 9, 39, 11, 41, 13, 43, 17, 47, 19, 49, 21, 23, 27 }
> powers eq { psi(u) : u in U };
true
```

<a id="rngint-dirichlet"></a>
<a id="id1"></a>
### Dirichlet Characters

Let $R$ be a ring. Then a *Dirichlet character over* $R$ *of modulus* $N$ is a homomorphism

$$
\varepsilon : ({\mathbb{Z}}/N{\mathbb{Z}})^* \rightarrow R^*,
$$

where $R^*$ is the group of invertible elements of $R$. We extend $\varepsilon$ to a set theoretic map on the whole of ${\mathbb{Z}}$ by defining $\varepsilon(x) = 0$ if $\gcd(x,N)\neq 1$. The *conductor* of $\varepsilon$ is the smallest positive integer $M$ such that the homomorphism $({\mathbb{Z}}/N{\mathbb{Z}})^* \rightarrow R^*$ factors through $({\mathbb{Z}}/M{\mathbb{Z}})^*$ via the natural map $({\mathbb{Z}}/N{\mathbb{Z}})^*\rightarrow ({\mathbb{Z}}/M{\mathbb{Z}})^*$.

#### Creation

<a id="function-dirichletgroup-rngintelt"></a>
##### `DirichletGroup(N): RngIntElt -> GrpDrch`

The group of Dirichlet characters modulo $N$ with values in `RationalField()`. (Note that this is a group of exponent at most $2$.)

<a id="function-fulldirichletgroup-rngintelt"></a>
##### `FullDirichletGroup(N): RngIntElt -> GrpDrch`

The group of Dirichlet characters modulo $N$ taking values in the $m$th cyclotomic field, where $m$ is the exponent of the unit group modulo $N$.

<a id="function-dirichletgroup-rngintelt-rng"></a>
##### `DirichletGroup(N, R): RngIntElt, Rng -> GrpDrch`

The group of Dirichlet characters modulo $N$ with values in the ring $R$. Here $R$ can be the integers, rationals, a number field, or a finite field. (Note that this group may be smaller than the full Dirichlet group.)

<a id="function-dirichletgroup-rngintelt-rng-rngelt-rngintelt"></a>
##### `DirichletGroup(N, R, z, r): RngIntElt, Rng, RngElt, RngIntElt -> GrpDrch`

The group of Dirichlet characters mod $N$ with values in the cyclic subgroup generated by the root of unity $z$ in the ring $R$. Here $z$ must be an element of $R$ of exact order $r$ (where $r$ may be smaller than the exponent of the full Dirichlet group).

<a id="function-baseextend-grpdrch-rng"></a>
##### `BaseExtend(G, R): GrpDrch, Rng -> GrpDrch`

<a id="function-baseextend-grpdrch-rng-rngelt"></a>
##### `BaseExtend(G, R, z): GrpDrch, Rng, RngElt -> GrpDrch`

The group of Dirichlet characters corresponding to $G$ with values in the ring $R$. In the second form, the distinguished root of unity of the base ring of $G$ is identified with the given element $z$.

<a id="procedure-assignnames-grpdrch-monstgelt-ref"></a>
##### `AssignNames(~G, S): GrpDrch, [MonStgElt]`

Assign names to the generators of the Dirichlet group $G$.

#### Element Creation

<a id="function-elements-grpdrch"></a>
##### `Elements(G): GrpDrch -> [GrpDrchElt]`

A sequence containing all Dirichlet characters in the Dirichlet group $G$.

<a id="function-random-grpdrch"></a>
##### `Random(G): GrpDrch -> GrpDrchElt`

A random element of the Dirichlet group $G$.

<a id="operation-operation-grpdrch-rngintelt-grpdrchelt"></a>
##### `G . i: GrpDrch, RngIntElt -> GrpDrchElt`

The $i$th generator of the group $G$.

<a id="operation-op-grpdrch-any"></a>
##### `G ! x: GrpDrch, Any -> GrpDrchElt`

This coerces the given element $x$ into the Dirichlet group $G$. Here $x$ may be a Dirichlet character belonging to a different group, or a sequence of integers specifying an element of the `AbelianGroup` of $G$.

<a id="function-kroneckercharacter-rngintelt"></a>
##### `KroneckerCharacter(D): RngIntElt -> GrpDrchElt`

<a id="function-kroneckercharacter-rngintelt-rng"></a>
##### `KroneckerCharacter(D, R): RngIntElt, Rng -> GrpDrchElt`

The Kronecker character $n\mapsto (d/n)$, where $d$ is the fundamental discriminant associated to the integer $D$.

When a ring $R$ is given, this is returned as a character with values in $R$.

#### Attributes of Dirichlet Groups

<a id="function-basering-grpdrch"></a>
##### `BaseRing(G): GrpDrch -> Rng`

The ring in which characters in $G$ take values.

<a id="function-modulus-grpdrch"></a>
##### `Modulus(G): GrpDrch -> RngIntElt`

The integer $N$ such that G is a group of Dirichlet characters on ${\mathbb{Z}}/N$.

<a id="function-order-grpdrch"></a>
##### `Order(G): GrpDrch -> RngIntElt`

The order of the Dirichlet group $G$.

<a id="function-exponent-grpdrch"></a>
##### `Exponent(G): GrpDrch -> RngIntElt`

The exponent of the Dirichlet group $G$.

<a id="function-numberofgenerators-grpdrch"></a>
##### `NumberOfGenerators(G): GrpDrch -> RngIntElt`

The number of generators of the Dirichlet group $G$.

<a id="function-generators-grpdrch"></a>
##### `Generators(G): GrpDrch -> [GrpDrchElt]`

A sequence containing generators for the Dirichlet group $G$.

<a id="function-unitgenerators-grpdrch"></a>
##### `UnitGenerators(G): GrpDrch -> [RngIntElt]`

This returns an ordered sequence of integers that reduce to “canonical” generators of the unit group of $Z/N$, where $N$ is the modulus of G.

<a id="function-galoisconjugacyrepresentatives-grpdrch"></a>
##### `GaloisConjugacyRepresentatives(G): GrpDrch -> [GrpDrchElt]`

<a id="function-galoisconjugacyrepresentatives-grpdrchelt"></a>
##### `GaloisConjugacyRepresentatives(seq): [GrpDrchElt] -> [GrpDrchElt]`

This returns a sequence containing one representative from each Galois conjugacy class (over ${\mathbb{Q}}$) of characters corresponding to a character in the given group or the given sequence.

<a id="function-abeliangroup-grpdrch"></a>
##### `AbelianGroup(G): GrpDrch -> GrpAb, Map`

This returns a finite abelian group isomorphic to the given group $G$ of Dirichlet characters (as an abstract group), and secondly returns a map from the abstract group to $G$.

It is necessary to use this function in order to make group theoretic constructions involving $G$.

#### Attributes of Elements

<a id="function-basering-grpdrchelt"></a>
##### `BaseRing(chi): GrpDrchElt -> Rng`

The ring in which the Dirichlet character $\chi$ takes values.

<a id="function-modulus-grpdrchelt"></a>
##### `Modulus(chi): GrpDrchElt -> RngIntElt`

The modulus of the group of Dirichlet characters that contains $\chi$.

<a id="function-conductor-grpdrchelt"></a>
##### `Conductor(chi): GrpDrchElt -> RngIntElt`

The minimal conductor of the Dirichlet character $\chi$. (That is, the smallest integer $M$ such that `chi` is well-defined on the unit group of $Z/M$.)

<a id="function-elementtosequence-grpdrchelt"></a>
##### `ElementToSequence(chi): GrpDrchElt -> SeqEnum`

A sequence of integers specifying the Dirichlet character $\chi$ (in terms of generators of the group containing $\chi$).

<a id="operation-op-eq-grpdrchelt-grpdrchelt"></a>
##### `x eq y: GrpDrchElt, GrpDrchElt -> BoolElt`

Return `true` iff the given characters have the same modulus and values.

<a id="function-order-grpdrchelt"></a>
##### `Order(chi): GrpDrchElt -> RngIntElt`

The order of the given element $\chi$ in a group of Dirichlet characters.

<a id="function-istrivial-grpdrchelt"></a>
##### `IsTrivial(chi): GrpDrchElt -> BoolElt`

Returns `true` if and only if the Dirichlet character $\chi$ has order $1$.

<a id="function-isprimitive-grpdrchelt"></a>
##### `IsPrimitive(chi): GrpDrchElt -> BoolElt`

Returns `true` iff the Dirichlet character $\chi$ is primitive (equivalently, if its conductor equals its modulus).

<a id="function-associatedprimitivecharacter-grpdrchelt"></a>
##### `AssociatedPrimitiveCharacter(chi): GrpDrchElt -> GrpDrchElt`

The primitive character modulo the conductor of $\chi$ which takes the same values (on units) as $\chi$.

<a id="function-iseven-grpdrchelt"></a>
##### `IsEven(chi): GrpDrchElt -> BoolElt`

Returns `true` if and only if `Evaluate(chi,-1)` is equal to $1$. Note that in characteristic $0$, the space of modular forms of weight $k$ and character $\chi$ is zero if $\chi$ is even and $k$ is odd.

<a id="function-isodd-grpdrchelt"></a>
##### `IsOdd(chi): GrpDrchElt -> BoolElt`

Returns `true` if and only if `Evaluate(chi,-1)` is equal to $-1$. Note that in characteristic $0$, the space of modular forms of weight $k$ and character $\chi$ is zero if $\chi$ is odd and $k$ is even.

<a id="function-istotallyeven-grpdrchelt"></a>
##### `IsTotallyEven(chi): GrpDrchElt -> BoolElt`

For a Dirichlet character $\chi$, this is `true` if and only if every character in the `Decomposition` of $\chi$ (into prime power components) is even.

<a id="function-decomposition-grpdrchelt"></a>
##### `Decomposition(chi): GrpDrchElt -> List`

This decomposes the Dirichlet character $\chi$ as a product of characters with prime power moduli. The function returns a list (not a sequence) containing these characters (which do not belong to the same group).

<a id="function-minimalbaseringcharacter-grpdrchelt"></a>
##### `MinimalBaseRingCharacter(chi): GrpDrchElt -> GrpDrchElt`

This returns a character which is the same as $\chi$, except which takes values in the smallest possible subring of the base ring of $\chi$.

#### Evaluation

<a id="function-evaluate-grpdrchelt-rngintelt"></a>
##### `Evaluate(chi, n): GrpDrchElt, RngIntElt -> RngElt`

<a id="function-chi-grpdrchelt-rngintelt"></a>
##### `chi(n): GrpDrchElt, RngIntElt -> RngElt`

The value of the Dirichlet character $\chi$ at the integer $n$.

<a id="function-valuelist-grpdrchelt"></a>
##### `ValueList(chi): GrpDrchElt -> [RngElt]`

A sequence containing the values $[\chi(1),..,\chi(N)]$ of the given character $\chi$, where $N$ is the modulus of $\chi$.

The list of values is stored; then in later calls to `Evaluate`, the stored value is returned.

<a id="function-valuesonunitgenerators-grpdrchelt"></a>
##### `ValuesOnUnitGenerators(chi): GrpDrchElt -> [RngElt]`

A sequence containing the values of $\chi$ on the ordered sequence of elements of ${\mathbb{Z}}/m$ given by `UnitGenerators(Parent(chi))`, where $m$ is the modulus of $\chi$.

<a id="function-orderofrootofunity-rngelt-rngintelt"></a>
##### `OrderOfRootOfUnity(r, n): RngElt, RngIntElt -> RngIntElt`

Given an element $r$ of some ring which is *assumed* to satisfy $r^n = 1$, this returns the smallest integer $m$ such that $r^m = 1$.

(This provides a convenient way to calculate the order of values of non-real characters.)

#### Arithmetic

<a id="operation-op-times-grpdrchelt-grpdrchelt"></a>
##### `x * y: GrpDrchElt, GrpDrchElt -> GrpDrchElt`

<a id="operation-op-div-grpdrchelt-grpdrchelt"></a>
##### `x / y: GrpDrchElt, GrpDrchElt -> GrpDrchElt`

The product or quotient (respectively) of the Dirichlet characters $x$ and $y$. This is a Dirichlet character of modulus equal to the least common multiple of the moduli of $x$ and $y$. The base rings and chosen roots of unity of the parents of $x$ and $y$ are equal.

<a id="operation-op-pow-grpdrchelt-rngintelt"></a>
##### `x ^ n: GrpDrchElt, RngIntElt -> GrpDrchElt`

The Dirichlet character $x$ raised to the power of $n$, where $n$ is any integer.

<a id="operation-op-pow-grpdrchelt-map"></a>
##### `x ^ phi: GrpDrchElt, Map -> GrpDrchElt`

The image of the Dirichlet character $x$ under the automorphism $\phi$.

<a id="function-sqrt-grpdrchelt"></a>
##### `Sqrt(x): GrpDrchElt -> GrpDrchElt`

Given a Dirichlet character $x$ of odd order, this returns a square root of $x$ (in the same group).

#### Example

<a id="example-ex-19f11f"></a>
##### `Example: Dirichlet Characters Modulo 5 (ex-19f11f)`

We begin by constructing the group of characters $({\mathbb{Z}}/5{\mathbb{Z}})^*\rightarrow{\mathbb{Q}}^*$.

```magma
> G<a> := DirichletGroup(5);  G;  // The default base field is Q.
Group of Dirichlet characters of modulus 5 over Rational Field
> #G;
2
> [Evaluate(a, n) : n in [1..5]];
[ 1, -1, -1, 1, 0 ]
> Eltseq(a);
[ 2 ]
> a eq G![2];
true
> IsEven(a);
true
> IsOdd(a);
false
> IsTrivial(a);
false
```

Next we create a character by building it up “locally”.

```magma
> G1<a4> := DirichletGroup(4);
> Conductor(a4);
4
> G2<a5> := DirichletGroup(25);
> Conductor(a5);
5
> eps := a4*a5;
> Modulus(eps);
100
> Conductor(eps);
20
> Evaluate(eps,7) eq Evaluate(a4,7)*Evaluate(a5,7);
true
```

Characters can be constructed over various fields.

```magma
> G<a> := DirichletGroup(7,GF(7));
> #G;
6
> Evaluate(a,2);
2
>
> G<a3,a5> := DirichletGroup(15,CyclotomicField(EulerPhi(15)));
> G;
Group of Dirichlet characters of modulus 15 over Cyclotomic Field of
order 8 and degree 4
> #G;
8
> Conductor(a3);
3
> Conductor(a5);
5
> Order(a5);
4
> Evaluate(a5,2);
zeta_8^2
```

If $D$ is a fundamental discriminant, then `KroneckerCharacter(D)` is the quadratic Dirichlet character corresponding to the quadratic field ${\mathbb{Q}}(\sqrt{D})$. The following code verifies that `KroneckerCharacter` and `KroneckerSymbol` agree in the case $D=209$.

```magma
> chi := KroneckerCharacter(209);
> for n in [1..209] do
>    assert Evaluate(chi,n) eq KroneckerSymbol(209,n);
> end for;
```

If $E$ is an elliptic curve with newform $f_E$, then the twist $E_D$ corresponds to $f_E$ twisted by this character, as illustrated below.

```magma
> E := EllipticCurve(CremonaDatabase(),"11A");
> f := qEigenform(E,8); f;
q - 2*q^2 - q^3 + 2*q^4 + q^5 + 2*q^6 - 2*q^7 + O(q^8)
> chi := KroneckerCharacter(-7);
> qEigenform(QuadraticTwist(E,-7),8);
q - 2*q^2 + q^3 + 2*q^4 - q^5 - 2*q^6 + O(q^8)
> R<q> := Parent(f);
> &+[Evaluate(chi,n)*Coefficient(f,n)*q^n : n in [1..7]] + O(q^8);
q - 2*q^2 + q^3 + 2*q^4 - q^5 - 2*q^6 + O(q^8)
```

<a id="rational"></a>
<a id="fldrat"></a>
## Rational Field

- [Introduction](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md)
  - [Representation](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#representation)
  - [Coercion](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#coercion)
    - [Example: Automatic Coercion of Rationals](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#example-ex-77bb73)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#homomorphisms)
    - [`hom< Q -> R | >: FldHom, Rng → Map`](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#constructor-constructor-hom-fldhom-rng-map)
    - [Example: Mapping Rationals into the Integers Modulo 11](https://docs.magma-maths.org/BasicRings/Rationals/introduction.md#example-ex-d98da9)
- [Creation Functions](https://docs.magma-maths.org/BasicRings/Rationals/creation.md)
  - [Creation of Structures](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#creation-of-structures)
    - [`Rationals() → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-rationals)
    - [`RationalField() → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-rationalfield)
    - [`MaximalOrder(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-maximalorder-fldrat)
    - [`IntegerRing(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-integerring-fldrat)
    - [`IntegerRing() → RngInt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-integerring)
    - [`Integers() → RngInt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-integers)
    - [`RingOfIntegers(Q): FldRat → RngInt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-ringofintegers-fldrat)
    - [`FieldOfFractions(Q): FldRat → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-fieldoffractions-fldrat)
    - [`FieldOfFractions(Z): RngInt → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-fieldoffractions-rngint)
    - [`Completion(Q, P): FldRat, RngInt → FldLoc, Map`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-completion-fldrat-rngint)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#creation-of-elements)
    - [`a / b: RngIntElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#operation-op-div-rngintelt-rngintelt)
    - [`Q ! [a]: FldRat, RngElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#operation-op-fldrat-rngelt)
    - [`Q ! [a, b]: FldRat, RngIntElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#operation-op-fldrat-rngintelt-rngintelt)
    - [`elt< Q | a, b >: FldRat, RngIntElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#constructor-constructor-elt-fldrat-rngintelt-rngintelt-fldratelt)
    - [`Q ! a: FldRat, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#operation-op-fldrat-rngintelt)
    - [`One(Q): FldRat → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-one-fldrat)
    - [`Identity(Q): FldRat → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-identity-fldrat)
    - [`Zero(Q): FldRat → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-zero-fldrat)
    - [`Representative(Q): FldRat → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-representative-fldrat)
    - [`RootOfUnity(n, Q): RngIntElt, FldRat → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-rootofunity-rngintelt-fldrat)
    - [`Random(Q, m): FldRat, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/creation.md#function-random-fldrat-rngintelt)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/Rationals/operation.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#related-structures)
    - [`Category(Q): FldRat → Cat`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-category-fldrat)
    - [`Parent(Q): FldRat → PowerStructure`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-parent-fldrat)
    - [`PrimeField(Q): FldRat → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-primefield-fldrat)
    - [`IntegralBasis(Q): FldRat → [ FldRatElt ]`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-integralbasis-fldrat)
    - [`MinimalField(q): FldRatElt → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-minimalfield-fldratelt)
    - [`MinimalField(S): SetEnum → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-minimalfield-setenum)
    - [`BaseField(Q): FldRat → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-basefield-fldrat)
    - [`Basis(Q): FldRat → [FldRatElt]`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-basis-fldrat)
    - [`AbsoluteBasis(Q): FldRat → [FldRatElt]`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-absolutebasis-fldrat)
    - [`UnitGroup(Q): FldRat → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-unitgroup-fldrat)
    - [`ClassGroup(Q): FldRat → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-classgroup-fldrat)
    - [`AutomorphismGroup(Q): FldRat → GrpPerm, PowMapAut, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-automorphismgroup-fldrat)
    - [`AutomorphismGroup(Q, Q): FldRat, FldRat → GrpPerm, PowMapAut, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-automorphismgroup-fldrat-fldrat)
    - [`Algebra(Q, Q): FldRat, Fld → AlgAss, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-algebra-fldrat-fld)
    - [`VectorSpace(Q, Q): FldRat, Fld → ModTupFld, Map`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-vectorspace-fldrat-fld)
    - [`Decomposition(Q, p): FldRat, RngIntElt → []`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-decomposition-fldrat-rngintelt)
    - [`Decomposition(Q, p): FldRat, Infty → []`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-decomposition-fldrat-infty)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#numerical-invariants)
    - [`Characteristic(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-characteristic-fldrat)
    - [`Conductor(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-conductor-fldrat)
    - [`Degree(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-degree-fldrat)
    - [`AbsoluteDegree(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-absolutedegree-fldrat)
    - [`Discriminant(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-discriminant-fldrat)
    - [`AbsoluteDiscriminant(Q): FldRat → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-absolutediscriminant-fldrat)
    - [`DefiningPolynomial(Q): FldRat → RngUPolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-definingpolynomial-fldrat)
    - [`Signature(Q): FldRat → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-signature-fldrat)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#ring-predicates-and-booleans)
    - [`IsCommutative(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-iscommutative-fldrat)
    - [`IsUnitary(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isunitary-fldrat)
    - [`IsFinite(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isfinite-fldrat)
    - [`IsOrdered(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isordered-fldrat)
    - [`IsField(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isfield-fldrat)
    - [`IsEuclideanDomain(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-iseuclideandomain-fldrat)
    - [`IsPID(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-ispid-fldrat)
    - [`IsUFD(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isufd-fldrat)
    - [`IsDivisionRing(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isdivisionring-fldrat)
    - [`IsEuclideanRing(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-iseuclideanring-fldrat)
    - [`IsPrincipalIdealRing(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isprincipalidealring-fldrat)
    - [`IsDomain(Q): FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#function-isdomain-fldrat)
    - [`Q eq R: FldRat, FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#operation-op-eq-fldrat-fldrat)
    - [`Q eq R: FldRat, RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#operation-op-eq-fldrat-rngint)
    - [`Q ne R: FldRat, FldRat → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#operation-op-ne-fldrat-fldrat)
    - [`Q ne R: FldRat, RngInt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/operation.md#operation-op-ne-fldrat-rngint)
- [Element Operations](https://docs.magma-maths.org/BasicRings/Rationals/element.md)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/Rationals/element.md#parent-and-category)
    - [`Parent(r): FldRatElt → FldRat`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-parent-fldratelt)
    - [`Category(r): FldRatElt → Cat`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-category-fldratelt)
  - [Arithmetic Operators](https://docs.magma-maths.org/BasicRings/Rationals/element.md#arithmetic-operators)
    - [`+ a: FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt)
    - [`- a: FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt-2)
    - [`a + b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-plus-fldratelt-fldratelt)
    - [`a - b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-minus-fldratelt-fldratelt)
    - [`a * b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-times-fldratelt-fldratelt)
    - [`a ^ k: FldRatElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-pow-fldratelt-rngintelt)
    - [`a / b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-div-fldratelt-fldratelt)
    - [`a +:= b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt-fldratelt)
    - [`a -:= b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt-fldratelt-2)
    - [`a *:= b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt-fldratelt-3)
    - [`a /:= b: FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-fldratelt-fldratelt-4)
    - [`a ^:= k: FldRatElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-operation-fldratelt-rngintelt-fldratelt)
  - [Numerator and Denominator](https://docs.magma-maths.org/BasicRings/Rationals/element.md#numerator-and-denominator)
    - [`Numerator(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-numerator-fldratelt)
    - [`Denominator(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-denominator-fldratelt)
    - [Example: Numerator and Denominator](https://docs.magma-maths.org/BasicRings/Rationals/element.md#example-ex-da083f)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/Rationals/element.md#equality-and-membership)
    - [`a eq b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-eq-fldratelt-fldratelt)
    - [`a ne b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-ne-fldratelt-fldratelt)
    - [`a in R: FldRatElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-in-fldratelt-rng)
    - [`a notin R: FldRatElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-notin-fldratelt-rng)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/Rationals/element.md#predicates-on-ring-elements)
    - [`IsIntegral(q): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isintegral-fldratelt)
    - [`IsZero(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-iszero-fldratelt)
    - [`IsOne(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isone-fldratelt)
    - [`IsMinusOne(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isminusone-fldratelt)
    - [`IsNilpotent(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isnilpotent-fldratelt)
    - [`IsIdempotent(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isidempotent-fldratelt)
    - [`IsUnit(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isunit-fldratelt)
    - [`IsZeroDivisor(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-iszerodivisor-fldratelt)
    - [`IsRegular(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isregular-fldratelt)
    - [`IsIrreducible(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isirreducible-fldratelt)
    - [`IsPrime(a): FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-isprime-fldratelt)
  - [Comparison](https://docs.magma-maths.org/BasicRings/Rationals/element.md#comparison)
    - [`a gt b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-gt-fldratelt-fldratelt)
    - [`a ge b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-ge-fldratelt-fldratelt)
    - [`a lt b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-lt-fldratelt-fldratelt)
    - [`a le b: FldRatElt, FldRatElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#operation-op-le-fldratelt-fldratelt)
    - [`Maximum(a, b): FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-maximum-fldratelt-fldratelt)
    - [`Maximum(Q): [FldRatElt] → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-maximum-fldratelt)
    - [`Minimum(a, b): FldRatElt, FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-minimum-fldratelt-fldratelt)
    - [`Minimum(Q): [FldRatElt] → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-minimum-fldratelt)
  - [Conjugates, Norm, and Trace](https://docs.magma-maths.org/BasicRings/Rationals/element.md#conjugates-norm-and-trace)
    - [`ComplexConjugate(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-complexconjugate-fldratelt)
    - [`Conjugate(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-conjugate-fldratelt)
    - [`Norm(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-norm-fldratelt)
    - [`Trace(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-trace-fldratelt)
    - [`MinimalPolynomial(q): FldRatElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-minimalpolynomial-fldratelt)
  - [Absolute Value and Sign](https://docs.magma-maths.org/BasicRings/Rationals/element.md#absolute-value-and-sign)
    - [`AbsoluteValue(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-absolutevalue-fldratelt)
    - [`Abs(q): FldRatElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-abs-fldratelt)
    - [`Sign(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-sign-fldratelt)
    - [`Height(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-height-fldratelt)
  - [Rounding and Truncating](https://docs.magma-maths.org/BasicRings/Rationals/element.md#rounding-and-truncating)
    - [`Ceiling(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-ceiling-fldratelt)
    - [`Floor(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-floor-fldratelt)
    - [`Round(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-round-fldratelt)
    - [`Truncate(q): FldRatElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-truncate-fldratelt)
    - [`Qround(q, M): FldRatElt, RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-qround-fldratelt-rngintelt)
  - [Continued Fractions](https://docs.magma-maths.org/BasicRings/Rationals/element.md#continued-fractions)
    - [`ContinuedFraction(r): FldRatElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-continuedfraction-fldratelt)
    - [`ContinuedFractionValue(C): [ RngIntElt ] → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-continuedfractionvalue-rngintelt)
    - [`HirzebruchJungContinuedFraction(r): FldRatElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-hirzebruchjungcontinuedfraction-fldratelt)
    - [`HJContinuedFraction(r): FldRatElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-hjcontinuedfraction-fldratelt)
    - [`HirzebruchJungContinuedFractionValue(C): [ RngIntElt ] → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-hirzebruchjungcontinuedfractionvalue-rngintelt)
    - [`HJContinuedFractionValue(C): [ RngIntElt ] → FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-hjcontinuedfractionvalue-rngintelt)
  - [Rational Reconstruction](https://docs.magma-maths.org/BasicRings/Rationals/element.md#rational-reconstruction)
    - [`RationalReconstruction(s): RngIntResElt → BoolElt, FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-rationalreconstruction-rngintreselt)
    - [`RationalReconstruction(s): FldFinElt → BoolElt, FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-rationalreconstruction-fldfinelt)
  - [Valuation](https://docs.magma-maths.org/BasicRings/Rationals/element.md#valuation)
    - [`Valuation(x, p): FldRatElt, RngIntElt → RngIntElt, FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-valuation-fldratelt-rngintelt)
    - [`Valuation(x, I): FldRatElt, RngIntElt → RngIntElt, FldRatElt`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-valuation-fldratelt-rngintelt-2)
  - [Sequence Conversions](https://docs.magma-maths.org/BasicRings/Rationals/element.md#sequence-conversions)
    - [`ElementToSequence(a): FldRatElt → [FldRatElt]`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-elementtosequence-fldratelt)
    - [`Eltseq(a): FldRatElt → [FldRatElt]`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-fldrat-eltseq)

### Introduction

This Chapter describes functions relating to the field of rational numbers ${\mathbb{Q}}$. Note that most functions for rational integers can be found in Chapter [Ring of Integers](https://docs.magma-maths.org/BasicRings/Integers/index-integers.md#rngint).

The rational field ${\mathbb{Q}}$ is automatically created when Magma is started up. That means that in ${\mathbb{Q}}$, unlike most other structures, arithmetic can be done without the need to create the structure explicitly first. The same is true for the ring of integers.

In order to be compatible with the other rings and fields, `Q.1` will return $1$.

#### Representation

Rational numbers are stored as pairs of numerator and denominator. Whenever a rational number is created, it will be put in reduced form (coprime numerator and denominator, positive denominator). It is well possible that a rational number has denominator $1$, and thus represents a rational integer; in such cases it will however never automatically be converted into an integer (that is, its type will not be changed).

#### Coercion

The tables in Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro) describe which coercions of rational numbers are allowed, and which will take place automatically when necessary. As a general rule, automatic coercion occurs between elements of ${\mathbb{Q}}$ and elements of any ring $R$ of characteristic $0$. That means, for example, that addition of any rational number and an element $r$ of such ring can be performed without the need to coerce the elements first; the result will be in the larger of ${\mathbb{Q}}$ and $R$ (usually $R$, unless $R$ is a subring of ${\mathbb{Q}}$ such as ${\mathbb{Z}}$). The most important exceptions to the above rule are those cases where the result would lie in a structure strictly larger than both ${\mathbb{Q}}$ and $R$. Examples of this are $R={\mathbb{Z}}[x]$, and the result would generally be in ${\mathbb{Q}}(x)$, and $R=O_K$, an order in a number field (and the result could be in $K$).

<a id="example-ex-77bb73"></a>
##### `Example: Automatic Coercion of Rationals (ex-77bb73)`

We give three examples of successful automatic coercion, and one where it does not work. Note that in the third case the result, although being integral, is still in the rational field.

```magma
> 1/2 + elt< CyclotomicField(3) | 1,2>;
1/2*(4*zeta_3 + 3)
> 1/2 - 0.12345;
0.37655
> 1/2 * 2;
1
> Parent(1/2 * 2);
Rational Field
> R<x> := PolynomialRing(Integers());
> // The following produces an error:
> 1/2 + x;

>> 1/2 + x;
       ^
Runtime error in '+': Bad argument types
```

#### Homomorphisms

Since homomorphisms are generally only allowed to be unitary, the specification of ring homomorphisms from $Q={\mathbb{Q}}$ to a ring $R$ is particularly simple: the image is completely determined by the image of $1$, which we require to be $1$ in $R$, so

<a id="constructor-constructor-hom-fldhom-rng-map"></a>
##### `hom< Q -> R | >: FldHom, Rng -> Map`

suffices.

Note that Magma allows the user to define maps with `hom` that are not proper homomorphisms; this is sometimes useful, as the example below shows.

<a id="example-ex-d98da9"></a>
##### `Example: Mapping Rationals into the Integers Modulo 11 (ex-d98da9)`

Suppose we wish to coerce rational numbers with denominator not divisible by 11 into the ring ${\mathbb{Z}}/11{\mathbb{Z}}$ in the obvious way by sending $r/s$ to $rs^{-1}\bmod 11$. The coercion rules do not allow you to do so using `!`, but a simple ‘homomorphism’ will work.

```magma
> Z11 := Integers(11);
> Q := RationalField();
> h := hom< Q -> Z11 | >;
> h(1/2);
6
```

### Creation Functions

#### Creation of Structures

The rational field ${\mathbb{Q}}$ is automatically created when Magma is started up. Nevertheless, it may be necessary to formally create the rational field, for instance if it is to be used as the coefficient ring for a polynomial ring. There is a unique rational field structure in Magma, that is, multiple calls to the creation function `RationalField()` will return the same object (and not an isomorphic copy), so no memory will be wasted.

<a id="function-rationals"></a>
##### `Rationals() -> FldRat`

<a id="function-rationalfield"></a>
##### `RationalField() -> FldRat`

Create the field ${\mathbb{Q}}$ of rational numbers.

<a id="function-maximalorder-fldrat"></a>
##### `MaximalOrder(Q): FldRat -> RngInt`

<a id="function-integerring-fldrat"></a>
##### `IntegerRing(Q): FldRat -> RngInt`

<a id="function-integerring"></a>
##### `IntegerRing() -> RngInt`

<a id="function-integers"></a>
##### `Integers() -> RngInt`

<a id="function-ringofintegers-fldrat"></a>
##### `RingOfIntegers(Q): FldRat -> RngInt`

Create the field ${\mathbb{Z}}$ of rational integers.

<a id="function-fieldoffractions-fldrat"></a>
##### `FieldOfFractions(Q): FldRat -> FldRat`

<a id="function-fieldoffractions-rngint"></a>
##### `FieldOfFractions(Z): RngInt -> FldRat`

The function `FieldOfFractions` returns the field ${\mathbb{Q}}$ when $R$ is either the ring ${\mathbb{Z}}$ of rational integers, or the field ${\mathbb{Q}}$ itself.

<a id="function-completion-fldrat-rngint"></a>
##### `Completion(Q, P): FldRat, RngInt -> FldLoc, Map`

```magma
Precision: RngIntElt                    Default: Infinity()
```

Computes the completion of $Q$ at the integral prime ideal $P$ together with the injection into the completion.

The parameter `Precision` may be used to specify a particular precision.

#### Creation of Elements

Unlike elements of other structures, rational numbers and integers can be created as literals without the need to define the parent field ${\mathbb{Q}}$ or the parent ring ${\mathbb{Z}}$ first, since these structures are loaded whenever Magma is started up.

<a id="operation-op-div-rngintelt-rngintelt"></a>
##### `a / b: RngIntElt, RngIntElt -> FldRatElt`

Given integers $a$ and $b\neq 0$, form the rational number $a/b$ (in reduced form). Of course $a$ and $b$ are allowed to be given as expressions defining integers.

<a id="operation-op-fldrat-rngelt"></a>
##### `Q ! [a]: FldRat, RngElt -> FldRatElt`

The inverse function to [`Eltseq`](https://docs.magma-maths.org/BasicRings/Rationals/element.md#function-fldrat-eltseq), returns `Q!a`.

<a id="operation-op-fldrat-rngintelt-rngintelt"></a>
##### `Q ! [a, b]: FldRat, RngIntElt, RngIntElt -> FldRatElt`

<a id="constructor-constructor-elt-fldrat-rngintelt-rngintelt-fldratelt"></a>
##### `elt< Q | a, b >: FldRat, RngIntElt, RngIntElt -> FldRatElt`

Given the rational field ${\mathbb{Q}}$, and integers $a, b$ (with $b\neq 0$), construct the rational number $a / b$, in reduced form.

<a id="operation-op-fldrat-rngintelt"></a>
##### `Q ! a: FldRat, RngIntElt -> FldRatElt`

Given the rational field $\Q$, and an integer $a$, create the rational number $a=a/1$ in $\Q$. Also, any element from a quadratic, cyclotomic, or number field (or an order of such) that is rational can be coerced into the rational field this way.

<a id="function-one-fldrat"></a>
##### `One(Q): FldRat -> FldRatElt`

<a id="function-identity-fldrat"></a>
##### `Identity(Q): FldRat -> FldRatElt`

<a id="function-zero-fldrat"></a>
##### `Zero(Q): FldRat -> FldRatElt`

<a id="function-representative-fldrat"></a>
##### `Representative(Q): FldRat -> FldRatElt`

These generic functions (cf. Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro)) create $1$, $1$, $0$, and $0$ respectively, in the rational field ${\mathbb{Q}}$.

<a id="function-rootofunity-rngintelt-fldrat"></a>
##### `RootOfUnity(n, Q): RngIntElt, FldRat -> FldRatElt`

This function returns, in general, for a positive integer $n$ and a cyclotomic field $Q$ a primitive $n$-th root of unity in $Q$; if $Q$ is the rational field, $n$ must be $1$ or $2$, and the result will be $1$ or $-1$ in $Q$ accordingly.

<a id="function-random-fldrat-rngintelt"></a>
##### `Random(Q, m): FldRat, RngIntElt -> FldRatElt`

This function returns a random rational number with random numerator in $[-u..u]$ and random denominator in $[ 1..u]$, where $u$ is the absolute value of $m$.

### Structure Operations

#### Related Structures

<a id="function-category-fldrat"></a>
##### `Category(Q): FldRat -> Cat`

<a id="function-parent-fldrat"></a>
##### `Parent(Q): FldRat -> PowerStructure`

<a id="function-primefield-fldrat"></a>
##### `PrimeField(Q): FldRat -> FldRat`

<a id="function-integralbasis-fldrat"></a>
##### `IntegralBasis(Q): FldRat -> [ FldRatElt ]`

An integral basis for $Q$ as a number field as a sequence of elements of $Q$ (giving the sequence containing 1 for the rational field).

<a id="function-minimalfield-fldratelt"></a>
##### `MinimalField(q): FldRatElt -> FldRat`

Return the least cyclotomic field containing the cyclotomic field element $q$; if $q$ is rational this returns the rational field.

<a id="function-minimalfield-setenum"></a>
##### `MinimalField(S): SetEnum -> FldRat`

Returns the minimal cyclotomic field containing the cyclotomic field elements in the enumerated set $S$; this will return the rational field if all elements of $S$ are rational numbers.

<a id="function-basefield-fldrat"></a>
##### `BaseField(Q): FldRat -> FldRat`

In analogy to the number fields, returns the coefficient field of $Q$ which will be ${\mathbb{Q}}$.

<a id="function-basis-fldrat"></a>
##### `Basis(Q): FldRat -> [FldRatElt]`

<a id="function-absolutebasis-fldrat"></a>
##### `AbsoluteBasis(Q): FldRat -> [FldRatElt]`

A basis for $Q$ as a ${\mathbb{Q}}$-vector space, i.e. $[1]$.

<a id="function-unitgroup-fldrat"></a>
##### `UnitGroup(Q): FldRat -> GrpAb, Map`

The unit group of the maximal order of ${\mathbb{Q}}$ (i.e. of ${\mathbb{Z}}$).

<a id="function-classgroup-fldrat"></a>
##### `ClassGroup(Q): FldRat -> GrpAb, Map`

The class group of the ring of integers ${\mathbb{Z}}$ of ${\mathbb{Q}}$ (which is trivial).

<a id="function-automorphismgroup-fldrat"></a>
##### `AutomorphismGroup(Q): FldRat -> GrpPerm, PowMapAut, Map`

<a id="function-automorphismgroup-fldrat-fldrat"></a>
##### `AutomorphismGroup(Q, Q): FldRat, FldRat -> GrpPerm, PowMapAut, Map`

The group of ${\mathbb{Q}}$ automorphisms of ${\mathbb{Q}}$, ie. a trivial finitely presented group, the parent structure for ${\mathbb{Q}}$-automorphisms and a map from the group to actual field automorphisms. In this case, of course the only ${\mathbb{Q}}$-automorphism will be the identity.

<a id="function-algebra-fldrat-fld"></a>
##### `Algebra(Q, Q): FldRat, Fld -> AlgAss, Map`

The rational numbers form canonically an algebra. This function returns an associative ${\mathbb{Q}}$-algebra isomorphic to ${\mathbb{Q}}$ and the map from the algebra to ${\mathbb{Q}}$.

<a id="function-vectorspace-fldrat-fld"></a>
##### `VectorSpace(Q, Q): FldRat, Fld -> ModTupFld, Map`

The rational numbers form canonically a vector space. This function returns a ${\mathbb{Q}}$-vector space isomorphic to ${\mathbb{Q}}$ and the map from the vector space to ${\mathbb{Q}}$.

<a id="function-decomposition-fldrat-rngintelt"></a>
##### `Decomposition(Q, p): FldRat, RngIntElt -> []`

<a id="function-decomposition-fldrat-infty"></a>
##### `Decomposition(Q, p): FldRat, Infty -> []`

For a prime $p$ or for the “infinite prime” `Infinity()` compute the decomposition in ${\mathbb{Q}}$ as a number field. This returns a list of length one containing a 2-tuple describing the splitting behaviour: the first component contains $p$ and the second it’s ramification degree, ie. 1.

#### Numerical Invariants

The functions below are defined for the rational field ${\mathbb{Q}}$ mainly because it often arises as a degenerate case of quadratic or cyclotomic field constructions. See the corresponding Chapters [Quadratic Fields](https://docs.magma-maths.org/GlobalFields/QuadraticFields/index-quadratic-fields.md#chapfldquad) and [Cyclotomic Fields](https://docs.magma-maths.org/GlobalFields/CyclotomicFields/index-cyclotomic-fields.md#chapfldcyc) for more.

<a id="function-characteristic-fldrat"></a>
##### `Characteristic(Q): FldRat -> RngIntElt`

<a id="function-conductor-fldrat"></a>
##### `Conductor(Q): FldRat -> RngIntElt`

The smallest positive integer $n$ such that $Q$ is contained in the cyclotomic field ${\mathbb{Q}}(\zeta_n)$. For the rational field this is $1$.

<a id="function-degree-fldrat"></a>
##### `Degree(Q): FldRat -> RngIntElt`

<a id="function-absolutedegree-fldrat"></a>
##### `AbsoluteDegree(Q): FldRat -> RngIntElt`

The degree of $Q$ as a number field (which is 1 for the rational field).

<a id="function-discriminant-fldrat"></a>
##### `Discriminant(Q): FldRat -> RngIntElt`

<a id="function-absolutediscriminant-fldrat"></a>
##### `AbsoluteDiscriminant(Q): FldRat -> RngIntElt`

The field discriminant of $Q$ (which is 1 for the rational field).

<a id="function-definingpolynomial-fldrat"></a>
##### `DefiningPolynomial(Q): FldRat -> RngUPolElt`

An irreducible polynomial over ${\mathbb{Q}}$ a root of which generates $Q$ as a number field (for the rational field this returns the linear polynomial $x-1$).

<a id="function-signature-fldrat"></a>
##### `Signature(Q): FldRat -> RngIntElt, RngIntElt`

The signature (number of real embeddings and pairs of complex embeddings) of ${\mathbb{Q}}$.

#### Ring Predicates and Booleans

<a id="function-iscommutative-fldrat"></a>
##### `IsCommutative(Q): FldRat -> BoolElt`

<a id="function-isunitary-fldrat"></a>
##### `IsUnitary(Q): FldRat -> BoolElt`

<a id="function-isfinite-fldrat"></a>
##### `IsFinite(Q): FldRat -> BoolElt`

<a id="function-isordered-fldrat"></a>
##### `IsOrdered(Q): FldRat -> BoolElt`

<a id="function-isfield-fldrat"></a>
##### `IsField(Q): FldRat -> BoolElt`

<a id="function-iseuclideandomain-fldrat"></a>
##### `IsEuclideanDomain(Q): FldRat -> BoolElt`

<a id="function-ispid-fldrat"></a>
##### `IsPID(Q): FldRat -> BoolElt`

<a id="function-isufd-fldrat"></a>
##### `IsUFD(Q): FldRat -> BoolElt`

<a id="function-isdivisionring-fldrat"></a>
##### `IsDivisionRing(Q): FldRat -> BoolElt`

<a id="function-iseuclideanring-fldrat"></a>
##### `IsEuclideanRing(Q): FldRat -> BoolElt`

<a id="function-isprincipalidealring-fldrat"></a>
##### `IsPrincipalIdealRing(Q): FldRat -> BoolElt`

<a id="function-isdomain-fldrat"></a>
##### `IsDomain(Q): FldRat -> BoolElt`

<a id="operation-op-eq-fldrat-fldrat"></a>
##### `Q eq R: FldRat, FldRat -> BoolElt`

<a id="operation-op-eq-fldrat-rngint"></a>
##### `Q eq R: FldRat, RngInt -> BoolElt`

<a id="operation-op-ne-fldrat-fldrat"></a>
##### `Q ne R: FldRat, FldRat -> BoolElt`

<a id="operation-op-ne-fldrat-rngint"></a>
##### `Q ne R: FldRat, RngInt -> BoolElt`

### Element Operations

A variety of different types of operations are provided for rational elements including arithmetic operations, comparison and predicates, and converting to a sequence.

#### Parent and Category

<a id="function-parent-fldratelt"></a>
##### `Parent(r): FldRatElt -> FldRat`

<a id="function-category-fldratelt"></a>
##### `Category(r): FldRatElt -> Cat`

#### Arithmetic Operators

<a id="operation-operation-fldratelt-fldratelt"></a>
##### `+ a: FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-fldratelt-2"></a>
##### `- a: FldRatElt -> FldRatElt`

<a id="operation-op-plus-fldratelt-fldratelt"></a>
##### `a + b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-op-minus-fldratelt-fldratelt"></a>
##### `a - b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-op-times-fldratelt-fldratelt"></a>
##### `a * b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-op-pow-fldratelt-rngintelt"></a>
##### `a ^ k: FldRatElt, RngIntElt -> FldRatElt`

<a id="operation-op-div-fldratelt-fldratelt"></a>
##### `a / b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-fldratelt-fldratelt"></a>
##### `a +:= b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-fldratelt-fldratelt-2"></a>
##### `a -:= b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-fldratelt-fldratelt-3"></a>
##### `a *:= b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-fldratelt-fldratelt-4"></a>
##### `a /:= b: FldRatElt, FldRatElt -> FldRatElt`

<a id="operation-operation-fldratelt-rngintelt-fldratelt"></a>
##### `a ^:= k: FldRatElt, RngIntElt -> FldRatElt`

#### Numerator and Denominator

<a id="function-numerator-fldratelt"></a>
##### `Numerator(q): FldRatElt -> RngIntElt`

The (integer) numerator of the rational number $q$ in reduced form.

<a id="function-denominator-fldratelt"></a>
##### `Denominator(q): FldRatElt -> RngIntElt`

The (integer) denominator of the rational number $q$ in reduced form. This will always be a positive integer.

<a id="example-ex-da083f"></a>
##### `Example: Numerator and Denominator (ex-da083f)`

Rational numbers are always immediately put in reduced form, that is, the greatest common divisor of numerator and denominator is taken out, and the denominator will be positive.

```magma
> Numerator(10/-4);
-5
> Denominator(10/-4);
2
```

#### Equality and Membership

<a id="operation-op-eq-fldratelt-fldratelt"></a>
##### `a eq b: FldRatElt, FldRatElt -> BoolElt`

<a id="operation-op-ne-fldratelt-fldratelt"></a>
##### `a ne b: FldRatElt, FldRatElt -> BoolElt`

<a id="operation-op-in-fldratelt-rng"></a>
##### `a in R: FldRatElt, Rng -> BoolElt`

<a id="operation-op-notin-fldratelt-rng"></a>
##### `a notin R: FldRatElt, Rng -> BoolElt`

#### Predicates on Ring Elements

<a id="function-isintegral-fldratelt"></a>
##### `IsIntegral(q): FldRatElt -> BoolElt`

Returns `true` if the rational number $q$ is an element of the ring of integers, `false` otherwise.

<a id="function-iszero-fldratelt"></a>
##### `IsZero(a): FldRatElt -> BoolElt`

<a id="function-isone-fldratelt"></a>
##### `IsOne(a): FldRatElt -> BoolElt`

<a id="function-isminusone-fldratelt"></a>
##### `IsMinusOne(a): FldRatElt -> BoolElt`

<a id="function-isnilpotent-fldratelt"></a>
##### `IsNilpotent(a): FldRatElt -> BoolElt`

<a id="function-isidempotent-fldratelt"></a>
##### `IsIdempotent(a): FldRatElt -> BoolElt`

<a id="function-isunit-fldratelt"></a>
##### `IsUnit(a): FldRatElt -> BoolElt`

<a id="function-iszerodivisor-fldratelt"></a>
##### `IsZeroDivisor(a): FldRatElt -> BoolElt`

<a id="function-isregular-fldratelt"></a>
##### `IsRegular(a): FldRatElt -> BoolElt`

<a id="function-isirreducible-fldratelt"></a>
##### `IsIrreducible(a): FldRatElt -> BoolElt`

<a id="function-isprime-fldratelt"></a>
##### `IsPrime(a): FldRatElt -> BoolElt`

#### Comparison

<a id="operation-op-gt-fldratelt-fldratelt"></a>
##### `a gt b: FldRatElt, FldRatElt -> BoolElt`

<a id="operation-op-ge-fldratelt-fldratelt"></a>
##### `a ge b: FldRatElt, FldRatElt -> BoolElt`

<a id="operation-op-lt-fldratelt-fldratelt"></a>
##### `a lt b: FldRatElt, FldRatElt -> BoolElt`

<a id="operation-op-le-fldratelt-fldratelt"></a>
##### `a le b: FldRatElt, FldRatElt -> BoolElt`

<a id="function-maximum-fldratelt-fldratelt"></a>
##### `Maximum(a, b): FldRatElt, FldRatElt -> FldRatElt`

<a id="function-maximum-fldratelt"></a>
##### `Maximum(Q): [FldRatElt] -> FldRatElt`

<a id="function-minimum-fldratelt-fldratelt"></a>
##### `Minimum(a, b): FldRatElt, FldRatElt -> FldRatElt`

<a id="function-minimum-fldratelt"></a>
##### `Minimum(Q): [FldRatElt] -> FldRatElt`

#### Conjugates, Norm, and Trace

<a id="function-complexconjugate-fldratelt"></a>
##### `ComplexConjugate(q): FldRatElt -> FldRatElt`

The complex conjugate of $q$, which will be the rational number $q$ itself.

<a id="function-conjugate-fldratelt"></a>
##### `Conjugate(q): FldRatElt -> FldRatElt`

The conjugate of $q$, which will be the rational number $q$ itself.

<a id="function-norm-fldratelt"></a>
##### `Norm(q): FldRatElt -> FldRatElt`

The norm (in ${\mathbb{Q}}$) of $q$, which will be the rational number $q$ itself.

<a id="function-trace-fldratelt"></a>
##### `Trace(q): FldRatElt -> FldRatElt`

The trace (in ${\mathbb{Q}}$) of $q$, which will be the rational number $q$ itself.

<a id="function-minimalpolynomial-fldratelt"></a>
##### `MinimalPolynomial(q): FldRatElt -> RngUPolElt`

Returns the minimal polynomial of the rational number $q$, which is the monic linear polynomial with constant coefficient $q$ in a univariate polynomial ring $R$ over the rational field. (If $R$ has not been created before with a name for its indeterminate, `$.1-q` will be returned.)

#### Absolute Value and Sign

<a id="function-absolutevalue-fldratelt"></a>
##### `AbsoluteValue(q): FldRatElt -> FldRatElt`

<a id="function-abs-fldratelt"></a>
##### `Abs(q): FldRatElt -> FldRatElt`

The absolute value $\vert q\vert$ of a rational number $q$.

<a id="function-sign-fldratelt"></a>
##### `Sign(q): FldRatElt -> RngIntElt`

Returns the sign of the rational number $q$, which is one of the integers $-1$, $0$, $1$, corresponding to the cases $q<0$, $q=0$, and $q>0$.

<a id="function-height-fldratelt"></a>
##### `Height(q): FldRatElt -> RngIntElt`

The height of $q=r/s$. For $r$ and $s$ coprime, the height is defined as the maximum of the absolute value of $r$ and $s$.

#### Rounding and Truncating

<a id="function-ceiling-fldratelt"></a>
##### `Ceiling(q): FldRatElt -> RngIntElt`

The ceiling of the rational number $q$, that is, the least integer greater than or equal to $q$.

<a id="function-floor-fldratelt"></a>
##### `Floor(q): FldRatElt -> RngIntElt`

The floor of the rational number $q$, that is, the largest integer less than or equal to $q$.

<a id="function-round-fldratelt"></a>
##### `Round(q): FldRatElt -> RngIntElt`

This function returns the integer value of the rational number $q$ rounded to the nearest integer. In the case of a tie, rounding is done away from zero (that is, $i+{1\over2}$ is rounded to $i+1$, for non-negative integers $i$ and $i-{1\over2}$ is rounded to $i-1$, for non-positive integers $i$).

<a id="function-truncate-fldratelt"></a>
##### `Truncate(q): FldRatElt -> RngIntElt`

This function returns the integer truncation of the rational number $q$, that is the integral part of $q$. Thus the effect is that of rounding towards $0$.

<a id="function-qround-fldratelt-rngintelt"></a>
##### `Qround(q, M): FldRatElt, RngIntElt -> FldRatElt`

```magma
ContFrac: BoolElt                    Default: false
```

Finds a rational approximation $d$ of $q$ such that the denominator of $d$ is bounded by $M$. If `ContFrac` is given then an optimal approximation is computed using the continued fraction process. By default $d$ is obtained by some rounding procedure which is faster but gives worse results.

#### Continued Fractions

<a id="function-continuedfraction-fldratelt"></a>
##### `ContinuedFraction(r): FldRatElt -> [ RngIntElt ]`

Given a rational $r$, return the sequence of partial quotients of the continued fraction expansion of $r$.

<a id="function-continuedfractionvalue-rngintelt"></a>
##### `ContinuedFractionValue(C): [ RngIntElt ] -> FldRatElt`

Given a continued fraction expansion $C$, return the rational $r$ such that $C$ equals `ContinuedFraction(r)`.

<a id="function-hirzebruchjungcontinuedfraction-fldratelt"></a>
##### `HirzebruchJungContinuedFraction(r): FldRatElt -> [ RngIntElt ]`

<a id="function-hjcontinuedfraction-fldratelt"></a>
##### `HJContinuedFraction(r): FldRatElt -> [ RngIntElt ]`

Given a rational $r$, return the sequence of partial quotients of the Hirzebruch-Jung continued fraction expansion of $r$.

<a id="function-hirzebruchjungcontinuedfractionvalue-rngintelt"></a>
##### `HirzebruchJungContinuedFractionValue(C): [ RngIntElt ] -> FldRatElt`

<a id="function-hjcontinuedfractionvalue-rngintelt"></a>
##### `HJContinuedFractionValue(C): [ RngIntElt ] -> FldRatElt`

Given a Hirzebruch-Jung continued fraction expansion $C$, return the rational $r$ so that `HJContinuedFraction(r)` equals $C$.

#### Rational Reconstruction

Under certain circumstances it is useful to have a partial inverse of the function $\psi_m\colon{\mathbb{Q}}\rightarrow {\mathbb{Z}}/m{\mathbb{Z}}$ of taking residues modulo $m$ (where the obvious value of $\psi_m$ is only defined for rational numbers with denominator in smallest terms coprime to $m$); the partial inverse of the function is sometimes referred to as ‘rational reconstruction’. For $s\in {\mathbb{Z}}/m{\mathbb{Z}}$ the value of $\psi^{-1}(s)$ is the rational number $r$ for which $\psi_m(r)=s$ and, in addition, the absolute values of both the numerator and denominator of $r$ are at most $\sqrt{m/2}$; such $r$ does not always exist, but if $r$ exists it is unique.

<a id="function-rationalreconstruction-rngintreselt"></a>
##### `RationalReconstruction(s): RngIntResElt -> BoolElt, FldRatElt`

<a id="function-rationalreconstruction-fldfinelt"></a>
##### `RationalReconstruction(s): FldFinElt -> BoolElt, FldRatElt`

Given an element $s$ of a ring $S$ of $m$ elements, return a Boolean flag indicating whether or not a rational number $r$ exists such that for the representation $r=n/d$ in minimal terms it holds that $n\cdot d^{-1}\equiv s\bmod m$, $\vert n\vert\le\sqrt{m/2}$ and $0 < d \le\sqrt{m/2}$. If the flag is true, the element $r$ is also returned. The ring $S$ is allowed to be a residue class ring `Integers(m)` or a finite field of prime cardinality $p=m$: `FiniteField(p)`.

In addition, $s$ is allowed to be a matrix over a prime finite field, in which case the existence (and, if possible, value) of a rational reconstruction of the matrix is determined.

#### Valuation

<a id="function-valuation-fldratelt-rngintelt"></a>
##### `Valuation(x, p): FldRatElt, RngIntElt -> RngIntElt, FldRatElt`

<a id="function-valuation-fldratelt-rngintelt-2"></a>
##### `Valuation(x, I): FldRatElt, RngIntElt -> RngIntElt, FldRatElt`

The valuation $v$ of the rational number $x$ at the prime $p$ (the prime ideal $I$). This is the difference of the valuations of the numerator and denominator of $x$. The optional second return value is the rational $u$ such that $x = p^v u$.

#### Sequence Conversions

<a id="function-elementtosequence-fldratelt"></a>
##### `ElementToSequence(a): FldRatElt -> [FldRatElt]`

<a id="function-fldrat-eltseq"></a>
##### `Eltseq(a): FldRatElt -> [FldRatElt]`

The sequence $[a]$ for compatibility with the other field types.

<a id="finite-galois-field"></a>
<a id="fldfin"></a>
## Finite Fields

- [Introduction](https://docs.magma-maths.org/BasicRings/FiniteFields/introduction.md)
  - [Representation of Finite Fields](https://docs.magma-maths.org/BasicRings/FiniteFields/introduction.md#representation-of-finite-fields)
  - [Conway Polynomials](https://docs.magma-maths.org/BasicRings/FiniteFields/introduction.md#conway-polynomials)
  - [Ground Field and Relationships](https://docs.magma-maths.org/BasicRings/FiniteFields/introduction.md#ground-field-and-relationships)
- [Creation Functions](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md)
  - [Creation of Structures](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#creation-of-structures)
    - [`FiniteField(q): RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-finitefield-rngintelt)
    - [`GaloisField(q): RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-galoisfield-rngintelt)
    - [`GF(q): RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-gf-rngintelt)
    - [`FiniteField(p, n): RngIntElt, RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-finitefield-rngintelt-rngintelt)
    - [`GaloisField(p, n): RngIntElt, RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-galoisfield-rngintelt-rngintelt)
    - [`GF(p, n): RngIntElt, RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-gf-rngintelt-rngintelt)
    - [`ext<F | n>: FldFin, RngIntElt → FldFin, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-ext-fldfin-rngintelt-fldfin-map)
    - [`ext<F | P>: FldFin, RngUPolElt[FldFin] → FldFin, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-ext-fldfin-rngupolelt-fldfin-fldfin-map)
    - [`ExtensionField<F, x | P>: FldFin, ... → FldFin, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-extensionfield-fldfin-fldfin-map)
    - [`RandomExtension(F, n): FldFin, RngIntElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-randomextension-fldfin-rngintelt)
    - [`SplittingField(P): RngUPolElt[FldFin] → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-splittingfield-rngupolelt-fldfin)
    - [`SplittingField(S): { RngUPolElt[FldFin] } → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-splittingfield-rngupolelt-fldfin-2)
    - [`sub<F | d>: FldFin, RngIntElt → FldFin, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-sub-fldfin-rngintelt-fldfin-map)
    - [`sub<F | f>: FldFin, FldFinElt → FldFin, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-sub-fldfin-fldfinelt-fldfin-map)
    - [`GroundField(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-groundfield-fldfin)
    - [`BaseField(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-basefield-fldfin)
    - [`PrimeField(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-primefield-fldfin)
    - [`IsPrimeField(F): Fld → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-isprimefield-fld)
    - [`F meet G: FldFin, FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#operation-op-meet-fldfin-fldfin)
    - [`CommonOverfield(K, L): FldFin, FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-commonoverfield-fldfin-fldfin)
    - [Example: Ways to Define a Finite Field](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#example-ex-591238)
  - [Creating Relations](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#creating-relations)
    - [`Embed(E, F): FldFin, FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-embed-fldfin-fldfin)
    - [`Embed(E, F, x): FldFin, FldFin, FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-embed-fldfin-fldfin-fldfinelt)
    - [`IsIsomorphic(E, F): FldFin, FldFin → BoolElt, Map[FldFin, FldFin]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-isisomorphic-fldfin-fldfin)
  - [Special Options](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#special-options)
    - [`AssertAttribute(FldFin, "PowerPrinting", l): Cat, MonStgElt, BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-assertattribute-cat-monstgelt-boolelt-powerprinting)
    - [`SetPowerPrinting(F, l): FldFin, BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-setpowerprinting-fldfin-boolelt)
    - [`AssertAttribute(F, "PowerPrinting", l): FldFin, MonStgElt, BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-assertattribute-fldfin-monstgelt-boolelt-powerprinting)
    - [`HasAttribute(FldFin, "PowerPrinting", l): Cat, MonStgElt, BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-hasattribute-cat-monstgelt-boolelt-powerprinting)
    - [`HasAttribute(F, "PowerPrinting"): FldFin, MonStgElt → BoolElt, BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-hasattribute-fldfin-monstgelt-powerprinting)
    - [`AssignNames(~F, [f]): FldFin, [ MonStgElt ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-assignnames-fldfin-monstgelt-ref)
    - [`Name(F, 1): FldFin, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-name-fldfin-rngintelt)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#homomorphisms)
    - [`hom< F -> G | x >: FldFin, Rng → Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-hom-fldfin-rng-map)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#creation-of-elements)
    - [`F . 1: FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#operation-operation-fldfin-fldfinelt)
    - [`elt<F | a>: FldFin, RngElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-elt-fldfin-rngelt-fldfinelt)
    - [`F ! a: FldFin, RngElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#operation-op-fldfin-rngelt)
    - [`elt<F | a₀, ..., aₙ₋₁>: FldFin, [FldFinElt] → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#constructor-constructor-elt-fldfin-fldfinelt-fldfinelt)
    - [`One(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-one-fldfin)
    - [`Identity(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-identity-fldfin)
    - [`Zero(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-zero-fldfin)
    - [`Representative(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-representative-fldfin)
    - [`Random(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-random-fldfin)
  - [Special Elements](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#special-elements)
    - [`F . 1: FldFin, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#operation-operation-fldfin-rngintelt-fldfinelt)
    - [`Generator(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-generator-fldfin)
    - [`Generator(F, E): FldFin, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-generator-fldfin-fldfin)
    - [`PrimitiveElement(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-primitiveelement-fldfin)
    - [`SetPrimitiveElement(F, x): FldFin, FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-ff-setprimitiveelement)
    - [`NormalElement(F): FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-normalelement-fldfin)
    - [`NormalElement(F, E): FldFin, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-normalelement-fldfin-fldfin)
  - [Sequence Conversions](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#sequence-conversions)
    - [`SequenceToElement(s, F): [ FldFinElt ] → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-sequencetoelement-fldfinelt)
    - [`Seqelt(s, F): [ FldFinElt ] → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-seqelt-fldfinelt)
    - [`ElementToSequence(a): FldFinElt → [ FldFinElt ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-elementtosequence-fldfinelt)
    - [`Eltseq(a): FldFinElt → [ FldFinElt ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-eltseq-fldfinelt)
    - [`ElementToSequence(a, E): FldFinElt, FldFin → [ FldFinElt ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-elementtosequence-fldfinelt-fldfin)
    - [`Eltseq(a, E): FldFinElt, FldFin → [ FldFinElt ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#function-eltseq-fldfinelt-fldfin)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#related-structures)
    - [`Category(F): FldFin → Cat`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-category-fldfin)
    - [`Parent(F): FldFin → PowerStructure`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-parent-fldfin)
    - [`Centre(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-centre-fldfin)
    - [`PrimeRing(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-primering-fldfin)
    - [`PrimeField(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-primefield-fldfin-2)
    - [`FieldOfFractions(F): FldFin → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-fieldoffractions-fldfin)
    - [`AdditiveGroup(F): FldFin → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-additivegroup-fldfin)
    - [`MultiplicativeGroup(F): FldFin → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-multiplicativegroup-fldfin)
    - [`UnitGroup(F): FldFin → GrpAb, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-unitgroup-fldfin)
    - [`Set(F): FldFin → SetEnum`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-set-fldfin)
    - [`VectorSpace(F, E): FldFin, FldFin → ModTupFld, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-vectorspace-fldfin-fldfin)
    - [`VectorSpace(F, E, B): FldFin, FldFin, [ FldFinElt ] → ModTupFld, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-vectorspace-fldfin-fldfin-fldfinelt)
    - [`MatrixAlgebra(F, E): FldFin, FldFin → AlgMat, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-matrixalgebra-fldfin-fldfin)
    - [`MatrixAlgebra(A, E): AlgMat, FldFin → AlgMat, Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-matrixalgebra-algmat-fldfin)
    - [Example: Finite Field as a Vector Space](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#example-ex-c6682e)
    - [`GaloisGroup(K, k): FldFin, FldFin → GrpPerm, [FldFinElt]`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-galoisgroup-fldfin-fldfin)
    - [`AutomorphismGroup(K, k): FldFin, FldFin → GrpPerm, [Map], Map`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-automorphismgroup-fldfin-fldfin)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#numerical-invariants)
    - [`Characteristic(F): FldFin → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-characteristic-fldfin)
    - [`# F: FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#operation-operation-fldfin-fldfinelt)
    - [`Degree(F): FldFin → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-degree-fldfin)
    - [`Degree(F, E): FldFin, FldFin → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-degree-fldfin-fldfin)
  - [Defining Polynomial](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#defining-polynomial)
    - [`DefiningPolynomial(F): FldFin → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-definingpolynomial-fldfin)
    - [`DefiningPolynomial(F, E): FldFin → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-definingpolynomial-fldfin-2)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#ring-predicates-and-booleans)
    - [`IsConway(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isconway-fldfin)
    - [`IsDefault(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isdefault-fldfin)
    - [`IsCommutative(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-iscommutative-fldfin)
    - [`IsUnitary(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isunitary-fldfin)
    - [`IsFinite(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isfinite-fldfin)
    - [`IsOrdered(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isordered-fldfin)
    - [`IsField(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isfield-fldfin)
    - [`IsEuclideanDomain(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-iseuclideandomain-fldfin)
    - [`IsPID(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-ispid-fldfin)
    - [`IsUFD(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isufd-fldfin)
    - [`IsDivisionRing(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isdivisionring-fldfin)
    - [`IsEuclideanRing(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-iseuclideanring-fldfin)
    - [`IsPrincipalIdealRing(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isprincipalidealring-fldfin)
    - [`IsDomain(F): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-isdomain-fldfin)
    - [`F eq G: FldFin, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#operation-op-eq-fldfin-rng)
    - [`F ne G: FldFin, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#operation-op-ne-fldfin-rng)
  - [Roots](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#roots)
    - [`Roots(f): RngUPolElt → [ < FldFinElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-roots-rngupolelt)
    - [`RootsInSplittingField(f): RngUPolElt[FldFin] → [<RngUPolElt, RngIntElt>], FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-rootsinsplittingfield-rngupolelt-fldfin)
    - [`FactorizationOverSplittingField(f): RngUPolElt[FldFin] → [<RngUPolElt, RngIntElt>], FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-factorizationoversplittingfield-rngupolelt-fldfin)
    - [`FactorisationOverSplittingField(f): RngUPolElt[FldFin] → [<RngUPolElt, RngIntElt>], FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-factorisationoversplittingfield-rngupolelt-fldfin)
    - [`RootOfUnity(n, K): RngIntElt, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#function-rootofunity-rngintelt-fldfin)
    - [Example: Roots in a Splitting Field](https://docs.magma-maths.org/BasicRings/FiniteFields/operation.md#example-ex-f06af7)
- [Element Operations](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md)
  - [Arithmetic Operators](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#arithmetic-operators)
    - [`+ a: FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-operation-fldfinelt-fldfinelt)
    - [`- a: FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-operation-fldfinelt-fldfinelt-2)
    - [`a + b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-plus-fldfinelt-fldfinelt)
    - [`a - b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-minus-fldfinelt-fldfinelt)
    - [`a * b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-times-fldfinelt-fldfinelt)
    - [`a / b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-div-fldfinelt-fldfinelt)
    - [`a ^ k: FldFinElt, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-pow-fldfinelt-rngintelt)
    - [`a +:= b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-operation-fldfinelt-fldfinelt-fldfinelt)
    - [`a -:= b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-operation-fldfinelt-fldfinelt-fldfinelt-2)
    - [`a *:= b: FldFinElt, FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-operation-fldfinelt-fldfinelt-fldfinelt-3)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#equality-and-membership)
    - [`a eq b: FldFinElt, FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-eq-fldfinelt-fldfinelt)
    - [`a ne b: FldFinElt, FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-ne-fldfinelt-fldfinelt)
    - [`a in F: FldFinElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-in-fldfinelt-rng)
    - [`a notin F: FldFinElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#operation-op-notin-fldfinelt-rng)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#parent-and-category)
    - [`Parent(a): FldFinElt → FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-parent-fldfinelt)
    - [`Category(a): FldFinElt → Cat`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-category-fldfinelt)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#predicates-on-ring-elements)
    - [`IsZero(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-iszero-fldfinelt)
    - [`IsOne(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isone-fldfinelt)
    - [`IsMinusOne(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isminusone-fldfinelt)
    - [`IsNilpotent(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isnilpotent-fldfinelt)
    - [`IsIdempotent(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isidempotent-fldfinelt)
    - [`IsUnit(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isunit-fldfinelt)
    - [`IsZeroDivisor(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-iszerodivisor-fldfinelt)
    - [`IsRegular(a): FldFin → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isregular-fldfin)
    - [`IsIrreducible(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isirreducible-fldfinelt)
    - [`IsPrime(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isprime-fldfinelt)
    - [`IsPrimitive(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isprimitive-fldfinelt)
    - [`IsPrimitive(f): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isprimitive-rngupolelt)
    - [`IsNormal(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isnormal-fldfinelt)
    - [`IsNormal(a, E): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-isnormal-fldfinelt-2)
    - [`IsSquare(a): FldFinElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-issquare-fldfinelt)
  - [Minimal and Characteristic Polynomial](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#minimal-and-characteristic-polynomial)
    - [`MinimalPolynomial(a): FldFinElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-minimalpolynomial-fldfinelt)
    - [`MinimalPolynomial(a, E): FldFinElt, FldFin → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-minimalpolynomial-fldfinelt-fldfin)
    - [`CharacteristicPolynomial(a): FldFinElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-characteristicpolynomial-fldfinelt)
    - [`CharacteristicPolynomial(a, E): FldFinElt, FldFin → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-characteristicpolynomial-fldfinelt-fldfin)
  - [Norm, Trace, and Frobenius](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#norm-trace-and-frobenius)
    - [`Norm(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-norm-fldfinelt)
    - [`Norm(a, E): FldFinElt, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-norm-fldfinelt-fldfin)
    - [`AbsoluteNorm(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-absolutenorm-fldfinelt)
    - [`NormAbs(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-normabs-fldfinelt)
    - [`Trace(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-trace-fldfinelt)
    - [`Trace(a, E): FldFinElt, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-trace-fldfinelt-fldfin)
    - [`AbsoluteTrace(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-absolutetrace-fldfinelt)
    - [`TraceAbs(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-traceabs-fldfinelt)
    - [`Frobenius(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-frobenius-fldfinelt)
    - [`Frobenius(a, r): FldFinElt, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-frobenius-fldfinelt-rngintelt)
    - [`Frobenius(a, E): FldFinElt, FldFin → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-frobenius-fldfinelt-fldfin)
    - [`Frobenius(a, E, r): FldFinElt, FldFin, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-frobenius-fldfinelt-fldfin-rngintelt)
    - [`NormEquation(K, y): FldFin, FldFin → BoolElt, FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-normequation-fldfin-fldfin)
    - [`Hilbert90(a, q): FldFinElt, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-hilbert90-fldfinelt-rngintelt)
    - [`AdditiveHilbert90(a, q): FldFinElt, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-additivehilbert90-fldfinelt-rngintelt)
  - [Order and Roots](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#order-and-roots)
    - [`Order(a): FldFinElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-order-fldfinelt)
    - [`FactoredOrder(a): FldFinElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-factoredorder-fldfinelt)
    - [`SquareRoot(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-squareroot-fldfinelt)
    - [`Sqrt(a): FldFinElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-sqrt-fldfinelt)
    - [`Root(a, n): FldFinElt, RngIntElt → FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-root-fldfinelt-rngintelt)
    - [`IsPower(a, n): FldFinElt, RngIntElt → BoolElt, FldFinElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-ispower-fldfinelt-rngintelt)
    - [`AllRoots(a, n): FldFinElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#function-allroots-fldfinelt-rngintelt)
    - [Example: Roots and Traces of Elements](https://docs.magma-maths.org/BasicRings/FiniteFields/operation-element.md#example-ex-ead4e7)
- [Polynomials for Finite Fields](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md)
  - [`IrreduciblePolynomial(F, n): FldFin, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblepolynomial-fldfin-rngintelt)
  - [`RandomIrreduciblePolynomial(F, n): FldFin, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-randomirreduciblepolynomial-fldfin-rngintelt)
  - [`IrreducibleLowTermGF2Polynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblelowtermgf2polynomial)
  - [`IrreducibleSparseGF2Polynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblesparsegf2polynomial)
  - [`PrimitivePolynomial(F, m): FldFin, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-primitivepolynomial-fldfin-rngintelt)
  - [`AllIrreduciblePolynomials(F, m): FldFin, RngIntElt → { RngUPolElt }`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-allirreduciblepolynomials-fldfin-rngintelt)
  - [`ConwayPolynomial(p, n): RngIntElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-conwaypolynomial-rngintelt-rngintelt)
  - [`ExistsConwayPolynomial(p, n): RngIntElt, RngIntElt → BoolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-existsconwaypolynomial-rngintelt-rngintelt)
- [Discrete Logarithms](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md)
  - [`Log(x): FldFinElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#function-log-fldfinelt)
  - [`Log(b, x): FldFinElt, FldFinElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#function-log-fldfinelt-fldfinelt)
  - [`ZechLog(K, n): FldFin, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#function-zechlog-fldfin-rngintelt)
  - [`Sieve(K): FldFin`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#procedure-ff-sieve)
  - [`SetVerbose("FFLog", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#procedure-setverbose-monstgelt-rngintelt-fflog)
  - [Example: Discrete Logarithms in a Finite Field](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#example-ex-e6dfa5)
- [Permutation Polynomials](https://docs.magma-maths.org/BasicRings/FiniteFields/permutation-polynomials.md)
  - [`DicksonFirst(n, a): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/permutation-polynomials.md#function-dicksonfirst-rngintelt-rngelt)
  - [`DicksonSecond(n, a): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/permutation-polynomials.md#function-dicksonsecond-rngintelt-rngelt)
  - [`IsProbablyPermutationPolynomial(p): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/FiniteFields/permutation-polynomials.md#function-isprobablypermutationpolynomial-rngupolelt)
  - [Example: Dickson Permutation Polynomials](https://docs.magma-maths.org/BasicRings/FiniteFields/permutation-polynomials.md#example-ex-41c38e)
- [Bibliography](https://docs.magma-maths.org/BasicRings/FiniteFields/bibliography.md)

### Introduction

Magma provides a powerful environment for computing with lattices of finite fields. Complete freedom in the manner in which fields are constructed is allowed, while assuring compatibility. Finite fields of various kinds are supported, with optimized representations for each kind. For a detailed description of how finite fields are presented in Magma, see [[BCS97](https://docs.magma-maths.org/references.md#cite-finitefields)].

#### Representation of Finite Fields

In Magma, arithmetic in small non-prime finite fields is carried out using tables of Zech logarithms. While this ensures that finite field arithmetic is fast, its use is limited to finite fields of small cardinality. Larger finite fields are internally represented as polynomial rings over a small finite field. It is possible for the user to specify his own irreducible polynomial (although internally an alternative representation may well be used). Although two finite fields of the same cardinality are isomorphic, in practical applications it is often important to be guaranteed to work in a field defined by a specific polynomial. Moreover, in passing between fields and subfields, choices regarding the embeddings have to be made, so that these embeddings are *compatible* (so that ‘diagrams commute’). The scheme implemented in Magma and described in [[BCS97](https://docs.magma-maths.org/references.md#cite-finitefields)] ensures that this is so.

#### Conway Polynomials

To avoid ambiguities when talking about (small) finite fields, *Conway polynomials* have been defined and calculated by R. Parker. The Conway polynomial $C_{p, n}$ is the lexicographically first monic irreducible, primitive polynomial of degree $n$ over ${\bf F}_{p}$ with the property that it is consistent with all $C_{p, m}$ for $m$ dividing $n$. Consistency of $C_{p, n}$ and $C_{p, m}$ for $m$ dividing $n$ means that for a root $\alpha$ of $C_{p, n}$ it holds that $\beta = \alpha^{{p^n-1}\over {p^m-1}}$ is a root of $C_{p, m}$. Lexicographically first is with respect to the system of representatives $-{{p-1}\over 2}, \ldots, -1, 0, 1, \ldots, {{p-1}\over 2}$ for the residue classes modulo $p$, ordered via $0 < -1 < 1 < -2 < \cdots {{p-1}\over 2}$ (and we only need to compare polynomials of the same degree). To compute the Conway polynomial $C_{p, n}$ one needs to know all Conway polynomials $C_{p, m}$ for $m$ dividing $n$, and as far as we know, no essentially better method is known than enumerating and testing the primitive polynomials of degree $n$ in lexicographical order. Conway polynomials are used in Magma by default for the construction of ${\bf F}_{p^n}$ using `FiniteField(p, n)` or its synonyms, whenever the Conway polynomial is available. However, it must be stressed that Conway polynomials are **only** used in Magma to provide standard defining polynomials for ${\bf F}_{p^n}$ – the special properties of Conway polynomials are never used because they are totally irrelevant in the scheme implemented in Magma!

#### Ground Field and Relationships

Throughout this Chapter we will use the notions of *ground field* and *prime field* in the following way. The prime field of a finite field $F$ is the unique field of cardinality $p$, the characteristic of $F$. Here we mean unique not just in the mathematical sense, but in the sense that all prime fields of the same cardinality are identical in Magma, and their elements are denoted $0, 1, \ldots, p-1$. The ground field of $F$ is the field over which $F$ is created as an extension. If $F$ was not explicitly created as an extension of a finite field $E$ by using `ext`, its ground field will be the prime field. Printing in Magma always takes place with respect to the ground field, that is, elements of $F$ are expressed as polynomials in the generator `F.1` of the field with coefficients in the ground field; there is one exception to this rule: if the field $F$ is small enough to be represented by means of Zech logarithms, the printing of elements is in the form of powers of the primitive element (see the option on `AssertAttribute` below for ways of changing that). It should be kept in mind that finite fields may be related mathematically without Magma being aware of the relation between them. This happens for example when two fields of dividing degrees are created as *extensions* of one field; although an isomorphic image of the smaller field will be contained in the larger, Magma will not establish this relation (unless the user explicitly asks for it, using the `Embed` function). However, all `subfields` of one common overfield in Magma will have their inclusion relations set up automatically.

### Creation Functions

A database of low-term irreducible polynomials for finite fields of small characteristic is available in Magma (see the function [`IrreducibleLowTermGF2Polynomial`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblelowtermgf2polynomial) below). This database goes up to degree 120,000 for ${\bf F}_{2}$, and to reasonably high degrees for the fields ${\bf F}_{q}$ for $q$ up to 128. Thus one can create the finite field ${\bf F}_{p^k}$ for $p,k$ within this range and compute within the field without any delay in the creation. Advantage is also taken of the special form of the defining polynomial. Previous to V2.11, sparse trinomial/pentanomial irreducible polynomials (see the function [`IrreducibleSparseGF2Polynomial`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblesparsegf2polynomial)) were used by default for constructing $GF(2^k)$ when $k$ is beyond the Conway range. To enable compatibility with older versions, one may select these sparse polynomials with the parameter `Sparse` in the creation functions.

#### Creation of Structures

<a id="function-finitefield-rngintelt"></a>
##### `FiniteField(q): RngIntElt -> FldFin`

<a id="function-galoisfield-rngintelt"></a>
##### `GaloisField(q): RngIntElt -> FldFin`

<a id="function-gf-rngintelt"></a>
##### `GF(q): RngIntElt -> FldFin`

```magma
Optimize: BoolElt                    Default: true
Sparse  : BoolElt                    Default: false
```

Given $q = p^n$, where $p$ is a prime, create the finite field ${\bf F}_{q}$. If $p$ is very big, it is advised to use the form `FiniteField(p, n)` described below instead, because Magma will first attempt to factor $q$ completely. The primitive polynomial used to construct ${\bf F}_{q}$ when $n > 1$ will be a Conway polynomial, if it is available. If the parameter `Optimize` is `false`, then no optimized representation (i.e., by using Zech logarithm tables or internal multi-step extensions) will be constructed for the new field which means that the time to create the field will be trivial but arithmetic operations in the field may be slower – this is useful if say one wishes to just compute a few trivial operations on a few elements of the field alone. If $q=2^k$ and $k$ is beyond the Conway range, then a low-term irreducible is used (see [`IrreducibleLowTermGF2Polynomial`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblelowtermgf2polynomial) below). Setting the parameter `Sparse` to `true` will cause a sparse polynomial to be used instead if possible (see [`IrreducibleSparseGF2Polynomial`](https://docs.magma-maths.org/BasicRings/FiniteFields/polynomial.md#function-irreduciblesparsegf2polynomial) below).

<a id="function-finitefield-rngintelt-rngintelt"></a>
##### `FiniteField(p, n): RngIntElt, RngIntElt -> FldFin`

<a id="function-galoisfield-rngintelt-rngintelt"></a>
##### `GaloisField(p, n): RngIntElt, RngIntElt -> FldFin`

<a id="function-gf-rngintelt-rngintelt"></a>
##### `GF(p, n): RngIntElt, RngIntElt -> FldFin`

```magma
Check   : BoolElt                    Default: true
Optimize: BoolElt                    Default: true
Sparse  : BoolElt                    Default: false
```

Given a prime $p$ and an exponent $n \geq 1$, create the finite field ${\bf F}_{p^n}$. The primitive polynomial used to construct ${\bf F}_{q}$ when $n > 1$ will be a Conway polynomial, if it is available. By default $p$ is checked to be a strong pseudoprime for 20 random bases $b$ with $1 < b < p$; if the parameter `Check` is `false`, then no check is done on $p$ at all (this is useful when $p$ is very large and one does not wish to perform an expensive primality test on $p$). The parameters are as above.

<a id="constructor-constructor-ext-fldfin-rngintelt-fldfin-map"></a>
##### `ext<F | n>: FldFin, RngIntElt -> FldFin, Map`

```magma
Optimize: BoolElt                    Default: true
Sparse  : BoolElt                    Default: false
```

Given a finite field $F$ and a positive integer $n$, create an extension $G$ of degree $n$ of $F$, as well as the embedding map $\phi : F\rightarrow G$. The parameter `Optimize` has the same behaviour as that for the `FiniteField` function. If $F$ is a default field, then $G$ will also be a default field (so its ground field will be the prime field). Otherwise, the ground field of $G$ will be $F$. The parameters are as above.

<a id="constructor-constructor-ext-fldfin-rngupolelt-fldfin-fldfin-map"></a>
##### `ext<F | P>: FldFin, RngUPolElt[FldFin] -> FldFin, Map`

```magma
Optimize: BoolElt                    Default: true
```

Given a finite field $F$ and a polynomial $P$ of degree $n$ over $F$, create an extension $G=F[\alpha]$ of degree $n$ of $F$, as well as the natural embedding map $\phi : F\rightarrow G$; the polynomial $P$ must be irreducible over $F$, and $\alpha$ is one of its roots. Thus the defining polynomial of $G$ over $F$ will be $P$. The parameter `Optimize` has the same behaviour as that for the `FiniteField` function. The ground field of $G$ will be $F$. The parameter is as above.

<a id="constructor-constructor-extensionfield-fldfin-fldfin-map"></a>
##### `ExtensionField<F, x | P>: FldFin, ... -> FldFin, Map`

Given a finite field $F$, a literal identifier $x$, and a polynomial $P$ of degree $n$ over $F$ presented as a (polynomial) expression in $x$, create an extension $G=F[x]$ of degree $n$ of $F$, as well as the natural embedding map $\phi : F\rightarrow G$; the polynomial $P$ must be irreducible over $F$, and $x$ is one of its roots. Thus the defining polynomial of $G$ over $F$ will be $P$. The parameter `Optimize` has the same behaviour as in the `FiniteField` function.

<a id="function-randomextension-fldfin-rngintelt"></a>
##### `RandomExtension(F, n): FldFin, RngIntElt -> FldFin`

Given a finite field $F$ and a degree $n$, return the extension of $F$ by a random degree-$n$ irreducible polynomial over $F$.

<a id="function-splittingfield-rngupolelt-fldfin"></a>
##### `SplittingField(P): RngUPolElt[FldFin] -> FldFin`

Given a univariate polynomial $P$ over a finite field $F$, create the minimal splitting field of $P$, that is, the smallest-degree extension field $G$ of $F$ such that $P$ factors completely into linear factors over $G$.

<a id="function-splittingfield-rngupolelt-fldfin-2"></a>
##### `SplittingField(S): { RngUPolElt[FldFin] } -> FldFin`

Given a set $S$ of univariate polynomials each over a finite field $F$, create the minimal splitting field of $S$, that is, the smallest-degree extension field $G$ of $F$ such that for every polynomial $P$ of $S$, $P$ factors completely into linear factors over $G$.

<a id="constructor-constructor-sub-fldfin-rngintelt-fldfin-map"></a>
##### `sub<F | d>: FldFin, RngIntElt -> FldFin, Map`

```magma
Optimize: BoolElt                    Default: true
Sparse  : BoolElt                    Default: false
```

Given a finite field $F$ of cardinality $p^n$ and a positive divisor $d$ of $n$, create a subfield $E$ of $F$ of degree $d$, as well as the embedding map $\phi : E\rightarrow F$. The parameters are as above.

<a id="constructor-constructor-sub-fldfin-fldfinelt-fldfin-map"></a>
##### `sub<F | f>: FldFin, FldFinElt -> FldFin, Map`

```magma
Optimize: BoolElt                    Default: true
Sparse  : BoolElt                    Default: false
```

Given a finite field $F$ and an element $f$ of $F$, create the subfield $E$ of $F$ generated by $f$, together with the embedding map $\phi : E\rightarrow F$. The map and field are constructed so that $\phi(w)=f$, where $w$ is the generator of $E$ (that is, `E.1`). The parameters are as above.

<a id="function-groundfield-fldfin"></a>
##### `GroundField(F): FldFin -> FldFin`

<a id="function-basefield-fldfin"></a>
##### `BaseField(F): FldFin -> FldFin`

Given a finite field $F$, return its ground field. If $F$ was constructed as an extension of the field $E$, this function returns $E$; if $F$ was not explicitly constructed as an extension then the prime field is returned.

<a id="function-primefield-fldfin"></a>
##### `PrimeField(F): FldFin -> FldFin`

The subfield of $F$ of prime cardinality.

<a id="function-isprimefield-fld"></a>
##### `IsPrimeField(F): Fld -> BoolElt`

Returns whether field $F$ is a prime field.

<a id="operation-op-meet-fldfin-fldfin"></a>
##### `F meet G: FldFin, FldFin -> FldFin`

Given finite fields $F$ and $G$ of the same characteristic $p$, return the finite field that forms the intersection $F\cap G$.

<a id="function-commonoverfield-fldfin-fldfin"></a>
##### `CommonOverfield(K, L): FldFin, FldFin -> FldFin`

Given finite fields $K$ and $L$, both of characteristic $p$, return the smallest field which contains both of them.

<a id="example-ex-591238"></a>
##### `Example: Ways to Define a Finite Field (ex-591238)`

To define the field of 7 elements, use

```magma
> F7 := FiniteField(7);
```

We can define the field of $7^4$ elements in several different ways. We can use the Conway polynomial:

```magma
> F<z> := FiniteField(7^4);
> F;
Finite field of size 7^4
```

We can define it as an extension of the field of 7 elements, using the internal polynomial:

```magma
> F<z> := ext< F7 | 4 >;
> F;
Finite field of size 7^4
```

We can supply our own polynomial, say $x^4 + 4x^3 + 2x + 3$:

```magma
> P<x> := PolynomialRing(F7);
> p := x^4+4*x^3+2*x+3;
> F<z> := ext< F7 | p >;
> F;
Finite field of size 7^4
```

We can define it as an extension of the field of $7^2$ elements:

```magma
> F49<w> := ext< F7 | 2 >;
> F<z> := ext< F49 | 2 >;
> F;
Finite field of size 7^4
```

#### Creating Relations

<a id="procedure-embed-fldfin-fldfin"></a>
##### `Embed(E, F): FldFin, FldFin`

Given finite fields $E$ and $F$ of cardinality $p^d$ and $p^n$, such that $d$ divides $n$, assert the embedding relation between $E$ and $F$. That is, an isomorphism between $E$ and the subfield of $F$ of cardinality $p^d$ is chosen and set up, and can be used from then on to move between the fields $E$ and $F$. See [[BCS97](https://docs.magma-maths.org/references.md#cite-finitefields)] for details as to how this is done. If both $E$ and $F$ have been defined with Conway polynomials then the isomorphism will be such that the generator $\beta$ of $F$ is mapped to $\alpha^{{p^n-1}\over {p^d-1}}$, where $\alpha$ is the generator of $F$.

<a id="procedure-embed-fldfin-fldfin-fldfinelt"></a>
##### `Embed(E, F, x): FldFin, FldFin, FldFinElt`

Given finite fields $E$ and $F$ of cardinality $p^d$ and $p^n$ such that $d$ divides $n$, as well as an element $x\in F$, assert the embedding relation between $E$ and $F$ mapping the generator of $E$ to $x$. The element $x$ must be a root of the polynomial defining $E$ over the prime field. Thus an isomorphism between $E$ and the subfield of $F$ of cardinality $p^d$ is set up, and can be used from then on to move between the fields $E$ and $F$.

<a id="function-isisomorphic-fldfin-fldfin"></a>
##### `IsIsomorphic(E, F): FldFin, FldFin -> BoolElt, Map[FldFin, FldFin]`

Given finite fields $E$ and $F$, returns whether they are isomorphic (have the same cardinality), and returns an isomorphism $\phi : E \to F$, without implicitly embedding $E$ into $F$.

#### Special Options

For finite fields for which the complete table of Zech logarithms is stored (and which must therefore be small), printing of elements can be done in two ways: either as powers of the primitive element or as polynomials in the generating element. Note that power printing is not available in all cases where the logarithm table is stored however (the defining polynomial may not be primitive); for convenience element of a prime field are always printed as integers, and therefore power printing on prime fields will not work. Also, if a field is created with a generator that is not primitive, then power printing will be impossible.

<a id="procedure-assertattribute-cat-monstgelt-boolelt-powerprinting"></a>
##### `AssertAttribute(FldFin, "PowerPrinting", l): Cat, MonStgElt, BoolElt`

This attribute is used to change the *default* printing for all (small) finite fields created after the `AssertAttribute` command is executed. If $l$ is `true` all elements of finite fields small enough for the Zech logarithms to be stored will be printed by default as a power of the primitive element – see `PrimitiveElement`). If $l$ is `false` every finite field element is printed by default as a polynomial in the generator `F.1` of degree less than $n$ over the ground field. The default can be overruled for a particular finite field by use of the `AssertAttribute` option listed below. The value of this attribute is obtained by use of `HasAttribute(FldFin, "PowerPrinting")`.

<a id="procedure-setpowerprinting-fldfin-boolelt"></a>
##### `SetPowerPrinting(F, l): FldFin, BoolElt`

<a id="procedure-assertattribute-fldfin-monstgelt-boolelt-powerprinting"></a>
##### `AssertAttribute(F, "PowerPrinting", l): FldFin, MonStgElt, BoolElt`

Given a finite field $F$, the Boolean value $l$ can be used to control the printing of elements of $F$, provided that $F$ is small enough for the table of Zech logarithms to be stored. If $l$ is `true` all elements will be printed as a power of the primitive element – see `PrimitiveElement`). If $l$ is `false` (which is the only possibility for big fields), every element of $F$ is printed as a polynomial in the generator `F.1` of degree less than $n$ over the ground field of $F$, where $n$ is the degree of $F$ over its ground field. The function `HasAttribute(F, "PowerPrinting")` may be used to obtain the current value of this flag.

<a id="procedure-hasattribute-cat-monstgelt-boolelt-powerprinting"></a>
##### `HasAttribute(FldFin, "PowerPrinting", l): Cat, MonStgElt, BoolElt`

This function is used to find the current default printing style for all (small) finite fields. It returns `true` (since this attribute is always defined for FldFin), and also returns the current value of the attribute. The procedure `AssertAttribute(FldFin, "PowerPrinting", l)` may be used to control the value of this flag.

<a id="function-hasattribute-fldfin-monstgelt-powerprinting"></a>
##### `HasAttribute(F, "PowerPrinting"): FldFin, MonStgElt -> BoolElt, BoolElt`

Given a finite field $F$ that is small enough for the table of Zech logarithms to be stored, returns `true` if the attribute `"PowerPrinting"` is defined, else returns `false`. If the attribute is defined, the function also returns the value of the attribute. The procedure `AssertAttribute(F, "PowerPrinting", l)` may be used to control the value of this flag.

<a id="procedure-assignnames-fldfin-monstgelt-ref"></a>
##### `AssignNames(~F, [f]): FldFin, [ MonStgElt ]`

Procedure to change the name of the generating element in the finite field $F$ to the contents of the string $f$. When $F$ is created, the name will be `F.1`. This procedure only changes the name used in printing the elements of $F$. It does *not* assign to an identifier called $f$ the value of the generator in $F$; to do this, use an assignment statement, or use angle brackets when creating the field. Note that since this is a procedure that modifies $F$, it is necessary to have a reference `~F` to $F$ in the call to this function.

<a id="function-name-fldfin-rngintelt"></a>
##### `Name(F, 1): FldFin, RngIntElt -> FldFinElt`

Given a finite field $F$, return the element which has the name attached to it, that is, return the element `F.1` of $F$.

#### Homomorphisms

<a id="constructor-constructor-hom-fldfin-rng-map"></a>
##### `hom< F -> G | x >: FldFin, Rng -> Map`

Given a finite field $F$, create a homomorphism with $F$ as its domain and $G$ as its codomain. If $F$ is a prime field, then the right hand side in the constructor must be empty; in this case the ring homomorphism is completely determined by the rule that the map must be unitary, that is, $1$ of $F$ is mapped to $1$ of $G$. If $F$ is not of prime cardinality, then the homomorphism must be specified by supplying one element $x$ in the codomain, which serves as the image of the generator of the field $F$ over its prime field. Note that it is the responsibility of the user that the map defines a homomorphism.

#### Creation of Elements

<a id="operation-operation-fldfin-fldfinelt"></a>
##### `F . 1: FldFin -> FldFinElt`

The generator for $F$ as an algebra over its ground field. Thus, if $F$ was defined by the polynomial $P=P(X)$ over $E$, so $F\cong E[X]/P(X)$, then `F.1` is the image of $X$ in $F$. If $F$ is a prime field, then $1=1_F$ will be returned.

<a id="constructor-constructor-elt-fldfin-rngelt-fldfinelt"></a>
##### `elt<F | a>: FldFin, RngElt -> FldFinElt`

<a id="operation-op-fldfin-rngelt"></a>
##### `F ! a: FldFin, RngElt -> FldFinElt`

Given a finite field $F$ create the element specified by $a$; here $a$ is allowed to be an element coercible into $F$, which means that $a$ may be

**(i)**
an element of $F$;

**(ii)**
an element of a subfield of $F$;

**(iii)**
an element of an overfield of $F$ that lies in $F$;

**(iv)**
an integer, to be identified with $a$ modulo the characteristic of $F$;

**(v)**
a sequence of elements of the ground field $E$ of $F$, of length equal to the degree of $F$ over $E$. In this case the element $a_0+a_1w+\cdots+a_{n-1}w^{n-1}$ is created, where $a=[a_0, \ldots a_{n-1}]$ and $w$ is the generator `F.1` of $F$ over $E$.

<a id="constructor-constructor-elt-fldfin-fldfinelt-fldfinelt"></a>
##### `elt<F | a₀, ..., aₙ₋₁>: FldFin, [FldFinElt] -> FldFinElt`

Given a finite field $F$ with generator $w$ of degree $n$ over the ground field $E$, create the element $a_0+a_1w+\cdots+a_{n-1}w^{n-1}\in F$, where $a_i\in E$ ($0\leq i\leq {n-1}$). If the $a_i$ are in some subfield of $E$ or the $a_i$ are integers, they will be coerced into the ground field.

<a id="function-one-fldfin"></a>
##### `One(F): FldFin -> FldFinElt`

<a id="function-identity-fldfin"></a>
##### `Identity(F): FldFin -> FldFinElt`

<a id="function-zero-fldfin"></a>
##### `Zero(F): FldFin -> FldFinElt`

<a id="function-representative-fldfin"></a>
##### `Representative(F): FldFin -> FldFinElt`

These generic functions (cf. Chapter [Introduction to Rings](https://docs.magma-maths.org/BasicRings/IntroductionToRings/index-introduction-to-rings.md#rngintro)) create $1$, $1$, $0$, and $0$ respectively, in any finite field.

<a id="function-random-fldfin"></a>
##### `Random(F): FldFin -> FldFinElt`

Create a ‘random’ element of finite field $F$.

#### Special Elements

<a id="operation-operation-fldfin-rngintelt-fldfinelt"></a>
##### `F . 1: FldFin, RngIntElt -> FldFinElt`

<a id="function-generator-fldfin"></a>
##### `Generator(F): FldFin -> FldFinElt`

Given a finite field $F$, this function returns the element $f$ of $F$ that generates $F$ over its ground field $E$, so $F=E[f]$. This is the same as the element `F.1`.

<a id="function-generator-fldfin-fldfin"></a>
##### `Generator(F, E): FldFin, FldFin -> FldFinElt`

Given a finite field $F$ and a subfield $E$ of $F$, this function returns an element $f$ of $F$ that generates $F$ over $E$, so $F=E[f]$. Note that this element may be different from the element `F.1`, but if `F.1` works it will be returned.

<a id="function-primitiveelement-fldfin"></a>
##### `PrimitiveElement(F): FldFin -> FldFinElt`

Given a finite field $F$, this function returns a primitive element for $F$, that is, a generator for the multiplicative group $F^*$ of $F$. Note that this may be an element different from the generator `F.1` for the field as an algebra. This function will return the same element upon different calls with the same field; the primitive element that is returned is the one that is used as basis for the `Log` function.

<a id="procedure-ff-setprimitiveelement"></a>
##### `SetPrimitiveElement(F, x): FldFin, FldFinElt`

(Procedure.) Given a finite field $F$ and a *primitive* element $x$ of $F$, set the internal primitive element $p$ of $F$ to be $x$. If the internal primitive element $p$ of $F$ has already been computed or set, $x$ must equal it. The function `Log` (given one argument) returns the logarithm of its argument with respect to the base $p$; this function thus allows one to specify which base should be used. (One can also use `Log(x, b)` for a given base but setting the primitive element and using `Log(x)` will be faster if many logarithms are to be computed.)

<a id="function-normalelement-fldfin"></a>
##### `NormalElement(F): FldFin -> FldFinElt`

Given a finite field $F={\bf F}_{p^n}$, this function returns a normal element for $F$ over the ground field $G$, that is, an element $\alpha\in F$ such that $\alpha, \alpha^q, \ldots, \alpha^{q^{n-1}}$ forms a basis for $F$ over $G$, where $q$ is the cardinality of $G$, and $n$ the degree for $F$ over $G$. Two calls to this function with the same field may result in different normal elements.

<a id="function-normalelement-fldfin-fldfin"></a>
##### `NormalElement(F, E): FldFin, FldFin -> FldFinElt`

Given a finite field $F={\bf F}_{q^n}$ and a subfield $E={\bf F}_{q}$, this function returns a normal element for $F$ over $E$, that is, an element $\alpha\in F$ such that $\alpha, \alpha^q, \ldots, \alpha^{q^{n-1}}$ forms a basis for $F$ over $E$.

#### Sequence Conversions

<a id="function-sequencetoelement-fldfinelt"></a>
##### `SequenceToElement(s, F): [ FldFinElt ] -> FldFinElt`

<a id="function-seqelt-fldfinelt"></a>
##### `Seqelt(s, F): [ FldFinElt ] -> FldFinElt`

Given a sequence $s=[s_0, \ldots, s_{n-1}]$ of elements of a finite field $E$, of length equal to the degree of the field $F$ over its subfield $E$, construct the element $s=s_0+s_1w+\cdots+s_{n-1}w^{n-1}$ of $F$, where $w$ is the generator `F.1` of $F$ over $E$.

<a id="function-elementtosequence-fldfinelt"></a>
##### `ElementToSequence(a): FldFinElt -> [ FldFinElt ]`

<a id="function-eltseq-fldfinelt"></a>
##### `Eltseq(a): FldFinElt -> [ FldFinElt ]`

Given an element $a$ of the finite field $F$, return the sequence of coefficients $[a_0, \ldots, a_{n-1}]$ in the ground field $E$ of $F$ such that $a=a_0+a_1w+\cdots+a_{n-1}w^{n-1}$, with $w$ the generator of $F$ over $E$, and $n$ the degree of $F$ over $E$.

<a id="function-elementtosequence-fldfinelt-fldfin"></a>
##### `ElementToSequence(a, E): FldFinElt, FldFin -> [ FldFinElt ]`

<a id="function-eltseq-fldfinelt-fldfin"></a>
##### `Eltseq(a, E): FldFinElt, FldFin -> [ FldFinElt ]`

Given an element $a$ of the finite field $F$, return the sequence of coefficients $[a_0, \ldots, a_{n-1}]$ in the subfield $E$ of $F$ such that $a=a_0+a_1w+\cdots+a_{n-1}w^{n-1}$, with $w$ the generator of $F$ over $E$, and $n$ the degree of $F$ over $E$.

### Structure Operations

#### Related Structures

<a id="function-category-fldfin"></a>
##### `Category(F): FldFin -> Cat`

<a id="function-parent-fldfin"></a>
##### `Parent(F): FldFin -> PowerStructure`

<a id="function-centre-fldfin"></a>
##### `Centre(F): FldFin -> FldFin`

<a id="function-primering-fldfin"></a>
##### `PrimeRing(F): FldFin -> FldFin`

<a id="function-primefield-fldfin-2"></a>
##### `PrimeField(F): FldFin -> FldFin`

<a id="function-fieldoffractions-fldfin"></a>
##### `FieldOfFractions(F): FldFin -> FldFin`

<a id="function-additivegroup-fldfin"></a>
##### `AdditiveGroup(F): FldFin -> GrpAb, Map`

Given $F={\bf F}_{q}$, create the finite additive abelian group $A$ of order $q=p^r$ that is the direct sum of $r$ copies of the cyclic group of order $p$, together with the corresponding isomorphism from the group $A$ to the field $F$.

<a id="function-multiplicativegroup-fldfin"></a>
##### `MultiplicativeGroup(F): FldFin -> GrpAb, Map`

<a id="function-unitgroup-fldfin"></a>
##### `UnitGroup(F): FldFin -> GrpAb, Map`

Given $F={\bf F}_{q}$, create the multiplicative group of $R$ as an abelian group. This returns the (additive) cyclic group $A$ of order $q-1$, together with a map from $A$ to $F\setminus 0$, sending $1$ to a primitive element of $F$.

<a id="function-set-fldfin"></a>
##### `Set(F): FldFin -> SetEnum`

Create the enumerated set consisting of the elements of finite field $F$.

<a id="function-vectorspace-fldfin-fldfin"></a>
##### `VectorSpace(F, E): FldFin, FldFin -> ModTupFld, Map`

Given a finite field $F$ that is an extension of degree $n$ of $E$, define the natural isomorphism between $F$ and the $n$-dimensional vector space $E^n$. The function returns two values:

**(a)**
A vector space $V\cong E^n$;

**(b)**
The isomorphism $\phi : F \rightarrow V$.

The basis of $V$ is chosen to correspond with the power basis $\alpha^0$, $\alpha^1$, $\ldots$, $\alpha^{n-1}$ of $F$, where $\alpha$ is the generator returned by `Generator(F, E)`, so that $V=E\cdot1\times E\cdot\alpha\times\cdots\times E\cdot\alpha^{n-1}$ and $\phi : \alpha^i \rightarrow e_{i+1}$, (for $i = 0, \ldots, n-1$), where $e_i$ is the basis vector of $V$ having all components zero, except the $i$-th, which is one.

<a id="function-vectorspace-fldfin-fldfin-fldfinelt"></a>
##### `VectorSpace(F, E, B): FldFin, FldFin, [ FldFinElt ] -> ModTupFld, Map`

Given a finite field $F$ that is an extension of degree $n$ of $E$, define the isomorphism between $F$ and the $n$-dimensional vector space $E^n$ defined by the basis $B$ for $F$ over $E$. The function returns two values:

**(a)**
A vector space $V\cong E^n$;

**(b)**
The isomorphism $\phi : F \rightarrow V$.

The basis of $V$ is chosen to correspond with the basis $B=\beta_1, \beta_2, \ldots, \beta_{n}$ of $F$ over $E$, as specified by the user, so that $V=E\cdot\beta_1\times E\cdot\beta_2\times\cdots\times E\cdot\beta_{n}$. $\phi : \beta_i \rightarrow e_{i}$, (for $i = 1, \ldots, n$), where $e_i$ is the basis vector of $V$ having all components zero, except the $i$-th, which is one.

<a id="function-matrixalgebra-fldfin-fldfin"></a>
##### `MatrixAlgebra(F, E): FldFin, FldFin -> AlgMat, Map`

Let $F$ be a finite field that is an extension of degree $n$ of $E$. The function returns two values:

**(a)**
A matrix algebra $A$ of degree $n$, such that $A$ is isomorphic to $F$;

**(b)**
An isomorphism $\phi : F \rightarrow A$.

The matrix algebra $A$ will be the subalgebra of the full algebra of $n\times n$ matrices over $E$ generated by the companion matrix $C$ of the defining polynomial of $F$ over $E$. The generator `Generator(F, E)` of $F$ over $E$ is thus mapped to $C$.

<a id="function-matrixalgebra-algmat-fldfin"></a>
##### `MatrixAlgebra(A, E): AlgMat, FldFin -> AlgMat, Map`

Let $F$ be a finite field. Let $A$ be a matrix algebra over $F$, and $E$ be a subfield of $F$. The function returns two values:

**(a)**
A matrix algebra $N$ over $E$ isomorphic to $A$, obtained from $A$ by expanding each component of an element of $A$ into the block matrix associated with it;

**(b)**
An $E$-isomorphism $\phi : A \rightarrow N$.

The matrix algebra $N$ is $A$ considered as an $E$-matrix algebra.

<a id="example-ex-c6682e"></a>
##### `Example: Finite Field as a Vector Space (ex-c6682e)`

Given the field $F$ of $7^4$ elements defined as an extension of the field $F49$ of $7^2$ elements as above, we can construct two vector spaces, one of dimension 2, and the other of dimension 4:

```magma
> F7 := FiniteField(7);
> F49<w> := ext< F7 | 2 >;
> F<z> := ext< F49 | 2 >;
> v2, i2 := VectorSpace(F, F49);
> v2;
Full Vector space of degree 2 over GF(7^2)
> i2(z^12);
(   w w^28)
> v4, i4 := VectorSpace(F, PrimeField(F));
> v4;
Full Vector space of degree 4 over GF(7)
> i4(z^12);
(5 3 6 4)
```

<a id="function-galoisgroup-fldfin-fldfin"></a>
##### `GaloisGroup(K, k): FldFin, FldFin -> GrpPerm, [FldFinElt]`

Compute the Galois group (which is of course cyclic) of $K/k$ as a permutation group. The group is returned as well as the roots of the defining polynomial of $K/k$ in a compatible ordering.

<a id="function-automorphismgroup-fldfin-fldfin"></a>
##### `AutomorphismGroup(K, k): FldFin, FldFin -> GrpPerm, [Map], Map`

Computes the (cyclic) group of $k$-automorphisms of $K$. The group is returned as well as a sequence of all automorphisms and a map sending an element of the abstract automorphism group to an explicit automorphism.

#### Numerical Invariants

<a id="function-characteristic-fldfin"></a>
##### `Characteristic(F): FldFin -> RngIntElt`

<a id="operation-operation-fldfin-fldfinelt"></a>
##### `# F: FldFin -> FldFinElt`

<a id="function-degree-fldfin"></a>
##### `Degree(F): FldFin -> RngIntElt`

The absolute degree of $F$, that is, the degree over its prime subfield.

<a id="function-degree-fldfin-fldfin"></a>
##### `Degree(F, E): FldFin, FldFin -> RngIntElt`

Given a finite field $F$ that has been constructed as an extension of a field $E$, return the degree of $F$ over $E$.

#### Defining Polynomial

<a id="function-definingpolynomial-fldfin"></a>
##### `DefiningPolynomial(F): FldFin -> RngUPolElt`

Given a finite field $F$ that has been constructed as an extension of a field $E$, return the polynomial with coefficients in $E$ that was used to define $F$ as an extension of $E$. This is the minimum polynomial of `F.1`.

<a id="function-definingpolynomial-fldfin-2"></a>
##### `DefiningPolynomial(F, E): FldFin -> RngUPolElt`

Given a finite field $F$ and a subfield $E$, return the polynomial with coefficients in $E$ used to define $F$ as an extension of $E$. This is the same as the minimum polynomial of the generator `Generator(F, E)` over $E$.

#### Ring Predicates and Booleans

<a id="function-isconway-fldfin"></a>
##### `IsConway(F): FldFin -> BoolElt`

Given a finite field $F$, this function returns `true` iff $F$ is defined over its prime field using a Conway polynomial.

<a id="function-isdefault-fldfin"></a>
##### `IsDefault(F): FldFin -> BoolElt`

Given a finite field $F$, this function returns `true` iff $F$ is a default field.

<a id="function-iscommutative-fldfin"></a>
##### `IsCommutative(F): FldFin -> BoolElt`

<a id="function-isunitary-fldfin"></a>
##### `IsUnitary(F): FldFin -> BoolElt`

<a id="function-isfinite-fldfin"></a>
##### `IsFinite(F): FldFin -> BoolElt`

<a id="function-isordered-fldfin"></a>
##### `IsOrdered(F): FldFin -> BoolElt`

<a id="function-isfield-fldfin"></a>
##### `IsField(F): FldFin -> BoolElt`

<a id="function-iseuclideandomain-fldfin"></a>
##### `IsEuclideanDomain(F): FldFin -> BoolElt`

<a id="function-ispid-fldfin"></a>
##### `IsPID(F): FldFin -> BoolElt`

<a id="function-isufd-fldfin"></a>
##### `IsUFD(F): FldFin -> BoolElt`

<a id="function-isdivisionring-fldfin"></a>
##### `IsDivisionRing(F): FldFin -> BoolElt`

<a id="function-iseuclideanring-fldfin"></a>
##### `IsEuclideanRing(F): FldFin -> BoolElt`

<a id="function-isprincipalidealring-fldfin"></a>
##### `IsPrincipalIdealRing(F): FldFin -> BoolElt`

<a id="function-isdomain-fldfin"></a>
##### `IsDomain(F): FldFin -> BoolElt`

<a id="operation-op-eq-fldfin-rng"></a>
##### `F eq G: FldFin, Rng -> BoolElt`

<a id="operation-op-ne-fldfin-rng"></a>
##### `F ne G: FldFin, Rng -> BoolElt`

#### Roots

<a id="function-roots-rngupolelt"></a>
##### `Roots(f): RngUPolElt -> [ < FldFinElt, RngIntElt> ]`

Given a polynomial $f$ over a finite field $F$, this function finds all roots of $f$ in $F$, and returns a sorted sequence of tuples (pairs), each consisting of a root of $f$ in $F$ and its multiplicity.

<a id="function-rootsinsplittingfield-rngupolelt-fldfin"></a>
##### `RootsInSplittingField(f): RngUPolElt[FldFin] -> [<RngUPolElt, RngIntElt>], FldFin`

Given a univariate polynomial $f$ over a finite field $K$, compute the minimal splitting field $S$ of $f$ as an extension field of $K$, and return the roots of $f$ in $S$, together with $S$. Using this function will be faster than computing the roots of $f$ anew over the splitting field.

<a id="function-factorizationoversplittingfield-rngupolelt-fldfin"></a>
##### `FactorizationOverSplittingField(f): RngUPolElt[FldFin] -> [<RngUPolElt, RngIntElt>], FldFin`

<a id="function-factorisationoversplittingfield-rngupolelt-fldfin"></a>
##### `FactorisationOverSplittingField(f): RngUPolElt[FldFin] -> [<RngUPolElt, RngIntElt>], FldFin`

Given a univariate polynomial $f$ over a finite field $K$, compute the minimal splitting field $S$ of $f$ as an extension field of $K$, and return the factorization (into linears) of $f$ over $S$, together with $S$. Using this function will be faster than factorizing $f$ anew over the splitting field.

<a id="function-rootofunity-rngintelt-fldfin"></a>
##### `RootOfUnity(n, K): RngIntElt, FldFin -> FldFinElt`

Return a primitive $n$-th root of unity in the smallest possible extension field of $K$.

<a id="example-ex-f06af7"></a>
##### `Example: Roots in a Splitting Field (ex-f06af7)`

We compute the roots of a certain degree-20 polynomial $f$ in its minimal splitting field.

```magma
> K := GF(2);
> P<x> := PolynomialRing(GF(2));
> f := x^20 + x^11 + 1;
> Factorization(f);
[
    <x^3 + x^2 + 1, 1>,
    <x^8 + x^7 + x^3 + x^2 + 1, 1>,
    <x^9 + x^7 + x^6 + x^4 + 1, 1>
]
> time r, S<w> := RootsInSplittingField(f);
Time: 0.040
```

We note that the splitting field $S$ has degree 72 and there are 20 roots of $f$ in $S$ of course. We check that the evaluation of $f$ at each root is zero.

```magma
> S;
Finite field of size 2^72
> DefiningPolynomial(S);
x^72 + x^48 + x^47 + x^44 + x^38 + x^35 + x^32 + x^31 + x^30 +
    x^29 + x^27 + x^25 + x^23 + x^22 + x^21 + x^18 + x^15 +
    x^12 + x^8 + x^4 + 1
> #r;
20
> r[1];
<w^68 + w^67 + w^64 + w^62 + w^60 + w^59 + w^56 + w^50 + w^49 +
    w^48 + w^47 + w^44 + w^43 + w^39 + w^37 + w^35 + w^33 + w^32
    + w^30 + w^29 + w^28 + w^25 + w^21 + w^19 + w^18 + w^16 +
    w^15 + w^14 + w^12 + w^10 + w^6 + w, 1>
> [IsZero(Evaluate(f, t[1])): t in r];
[ true, true, true, true, true, true, true, true, true, true, true, true,
true, true, true, true, true, true, true, true ]
```

### Element Operations

See also Section [Generic Element Functions](https://docs.magma-maths.org/BasicRings/IntroductionToRings/element.md#rngintro-elt-funcs).

#### Arithmetic Operators

<a id="operation-operation-fldfinelt-fldfinelt"></a>
##### `+ a: FldFinElt -> FldFinElt`

<a id="operation-operation-fldfinelt-fldfinelt-2"></a>
##### `- a: FldFinElt -> FldFinElt`

<a id="operation-op-plus-fldfinelt-fldfinelt"></a>
##### `a + b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-op-minus-fldfinelt-fldfinelt"></a>
##### `a - b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-op-times-fldfinelt-fldfinelt"></a>
##### `a * b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-op-div-fldfinelt-fldfinelt"></a>
##### `a / b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-op-pow-fldfinelt-rngintelt"></a>
##### `a ^ k: FldFinElt, RngIntElt -> FldFinElt`

<a id="operation-operation-fldfinelt-fldfinelt-fldfinelt"></a>
##### `a +:= b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-operation-fldfinelt-fldfinelt-fldfinelt-2"></a>
##### `a -:= b: FldFinElt, FldFinElt -> FldFinElt`

<a id="operation-operation-fldfinelt-fldfinelt-fldfinelt-3"></a>
##### `a *:= b: FldFinElt, FldFinElt -> FldFinElt`

#### Equality and Membership

<a id="operation-op-eq-fldfinelt-fldfinelt"></a>
##### `a eq b: FldFinElt, FldFinElt -> BoolElt`

<a id="operation-op-ne-fldfinelt-fldfinelt"></a>
##### `a ne b: FldFinElt, FldFinElt -> BoolElt`

<a id="operation-op-in-fldfinelt-rng"></a>
##### `a in F: FldFinElt, Rng -> BoolElt`

<a id="operation-op-notin-fldfinelt-rng"></a>
##### `a notin F: FldFinElt, Rng -> BoolElt`

#### Parent and Category

<a id="function-parent-fldfinelt"></a>
##### `Parent(a): FldFinElt -> FldFin`

<a id="function-category-fldfinelt"></a>
##### `Category(a): FldFinElt -> Cat`

#### Predicates on Ring Elements

<a id="function-iszero-fldfinelt"></a>
##### `IsZero(a): FldFinElt -> BoolElt`

<a id="function-isone-fldfinelt"></a>
##### `IsOne(a): FldFinElt -> BoolElt`

<a id="function-isminusone-fldfinelt"></a>
##### `IsMinusOne(a): FldFinElt -> BoolElt`

<a id="function-isnilpotent-fldfinelt"></a>
##### `IsNilpotent(a): FldFinElt -> BoolElt`

<a id="function-isidempotent-fldfinelt"></a>
##### `IsIdempotent(a): FldFinElt -> BoolElt`

<a id="function-isunit-fldfinelt"></a>
##### `IsUnit(a): FldFinElt -> BoolElt`

<a id="function-iszerodivisor-fldfinelt"></a>
##### `IsZeroDivisor(a): FldFinElt -> BoolElt`

<a id="function-isregular-fldfin"></a>
##### `IsRegular(a): FldFin -> BoolElt`

<a id="function-isirreducible-fldfinelt"></a>
##### `IsIrreducible(a): FldFinElt -> BoolElt`

<a id="function-isprime-fldfinelt"></a>
##### `IsPrime(a): FldFinElt -> BoolElt`

<a id="function-isprimitive-fldfinelt"></a>
##### `IsPrimitive(a): FldFinElt -> BoolElt`

Returns `true` if and only if the element $a$ of $F$ is a primitive element for $F$ (i.e., if and only if the multiplicative order of $a$ is $\#F-1$).

<a id="function-isprimitive-rngupolelt"></a>
##### `IsPrimitive(f): RngUPolElt -> BoolElt`

Given a univariate polynomial $f\in F[x]$, over a finite field $F$, such that the degree of $f$ is greater than or equal to 1, this function returns `true` if and only if $f$ defines a primitive extension $G=F[x]/f$ of $F$ (that is, $x$ is primitive in $G$).

<a id="function-isnormal-fldfinelt"></a>
##### `IsNormal(a): FldFinElt -> BoolElt`

Returns `true` if and only if the element $a$ of $F$ generates a normal basis for the field over the ground field, that is, if and only if $a, a^q, \ldots, a^{q^{n-1}}$ form a basis for $F$ over the ground field $G={\bf F}_{q}$.

<a id="function-isnormal-fldfinelt-2"></a>
##### `IsNormal(a, E): FldFinElt -> BoolElt`

Returns `true` if and only if the element $a$ of the finite field $F$ with $q^n$ elements generates a normal basis for $F$ over its subfield $E$, that is, if and only if $a, a^q, \ldots, a^{q^{n-1}}$ form a basis for $F$ over $E$ for $q=\#E$.

<a id="function-issquare-fldfinelt"></a>
##### `IsSquare(a): FldFinElt -> BoolElt`

Given a finite field element $a\in F$, this function returns either `true` and an element $b\in F$ such that $b^2=a$, or it returns `false` in the case that such an element does not exist.

#### Minimal and Characteristic Polynomial

<a id="function-minimalpolynomial-fldfinelt"></a>
##### `MinimalPolynomial(a): FldFinElt -> RngUPolElt`

The minimal polynomial of the element $a$ of the field $F$, relative to the ground field of $F$. This is the unique minimal-degree monic polynomial with coefficients in the ground field, having $a$ as a root.

<a id="function-minimalpolynomial-fldfinelt-fldfin"></a>
##### `MinimalPolynomial(a, E): FldFinElt, FldFin -> RngUPolElt`

The minimal polynomial of the element $a$ of the field $F$, relative to the subfield $E$ of $F$. This is the unique minimal-degree monic polynomial with coefficients in $E$, having $a$ as a root.

<a id="function-characteristicpolynomial-fldfinelt"></a>
##### `CharacteristicPolynomial(a): FldFinElt -> RngUPolElt`

Given an element $a$ of a finite field $F$, return the characteristic polynomial of $a$ with respect to the ground field of $F$. (This polynomial is the characteristic polynomial of the companion matrix of $a$ written as a polynomial over the ground field, and is a power of the minimal polynomial.)

<a id="function-characteristicpolynomial-fldfinelt-fldfin"></a>
##### `CharacteristicPolynomial(a, E): FldFinElt, FldFin -> RngUPolElt`

Given an element $a$ of a finite field $F$, return the characteristic polynomial of $a$ with respect to the subfield $E$ of $F$. (This polynomial is the characteristic polynomial of the companion matrix of $a$ written as a polynomial over $E$, and is a power of the minimal polynomial over $E$.)

#### Norm, Trace, and Frobenius

<a id="function-norm-fldfinelt"></a>
##### `Norm(a): FldFinElt -> FldFinElt`

The norm of the element $a$ from the field $F$ to the ground field of $F$.

<a id="function-norm-fldfinelt-fldfin"></a>
##### `Norm(a, E): FldFinElt, FldFin -> FldFinElt`

The relative norm of the element $a$ from the field $F$, with respect to the subfield $E$ of $F$. The result is an element of $E$.

<a id="function-absolutenorm-fldfinelt"></a>
##### `AbsoluteNorm(a): FldFinElt -> FldFinElt`

<a id="function-normabs-fldfinelt"></a>
##### `NormAbs(a): FldFinElt -> FldFinElt`

The absolute norm of the element $a$, that is, the norm to the prime subfield of the parent field $F$ of $a$.

<a id="function-trace-fldfinelt"></a>
##### `Trace(a): FldFinElt -> FldFinElt`

The trace of the element $a$ from the field $F$ to the ground field of $F$.

<a id="function-trace-fldfinelt-fldfin"></a>
##### `Trace(a, E): FldFinElt, FldFin -> FldFinElt`

The relative trace of the element $a$ from field $F$, with respect to the subfield $E$ of $F$. The result is an element of $E$.

<a id="function-absolutetrace-fldfinelt"></a>
##### `AbsoluteTrace(a): FldFinElt -> FldFinElt`

<a id="function-traceabs-fldfinelt"></a>
##### `TraceAbs(a): FldFinElt -> FldFinElt`

The trace of the element $a$, that is, the trace to the prime subfield of the parent field $F$ of $a$.

<a id="function-frobenius-fldfinelt"></a>
##### `Frobenius(a): FldFinElt -> FldFinElt`

The Frobenius image of $a$ w.r.t. the ground field of $K$; i.e., $a^{\#G}$, where $G$ is the ground field of the parent of $a$.

<a id="function-frobenius-fldfinelt-rngintelt"></a>
##### `Frobenius(a, r): FldFinElt, RngIntElt -> FldFinElt`

The $r$-th Frobenius image of $a$ w.r.t. the ground field of $K$; i.e., $a^{(\#G)^r}$, where $G$ is the ground field of the parent of $a$.

<a id="function-frobenius-fldfinelt-fldfin"></a>
##### `Frobenius(a, E): FldFinElt, FldFin -> FldFinElt`

The Frobenius image of x w.r.t. $E$; i.e., $x^{\#E}$.

<a id="function-frobenius-fldfinelt-fldfin-rngintelt"></a>
##### `Frobenius(a, E, r): FldFinElt, FldFin, RngIntElt -> FldFinElt`

The Frobenius image of x w.r.t. $E$; i.e., $x^{(\#E)^r}$.

<a id="function-normequation-fldfin-fldfin"></a>
##### `NormEquation(K, y): FldFin, FldFin -> BoolElt, FldFinElt`

Given a finite field $K$ and an element $y$ of a subfield $S$ of $K$, return whether an element $x\in K$ exists such that [`Norm`](https://docs.magma-maths.org/search.html?q=Norm&show=intrinsics&match=exact)$(x, S) = y$, and, if so, such an element $x$ (in $K$).

<a id="function-hilbert90-fldfinelt-rngintelt"></a>
##### `Hilbert90(a, q): FldFinElt, RngIntElt -> FldFinElt`

Given an element $a$ of some finite field $k$ and a power $q$ of the characteristic of $k$, return a solution of the Hilbert 90 equation $x^qx^{-1}=a$. Note that the solution may be in a finite-degree extension of $k$.

<a id="function-additivehilbert90-fldfinelt-rngintelt"></a>
##### `AdditiveHilbert90(a, q): FldFinElt, RngIntElt -> FldFinElt`

Given an element $a$ of some finite field $k$ and a power $q$ of the characteristic of $k$, return a solution of the additive Hilbert 90 equation $x^q - x=a$. Note that the solution may be in a finite-degree extension of $k$.

#### Order and Roots

<a id="function-order-fldfinelt"></a>
##### `Order(a): FldFinElt -> RngIntElt`

The multiplicative order of the non-zero element $a$ of the field $F$.

<a id="function-factoredorder-fldfinelt"></a>
##### `FactoredOrder(a): FldFinElt -> RngIntElt`

The multiplicative order of the non-zero element $a$ of the field $F$ as a factorization sequence.

<a id="function-squareroot-fldfinelt"></a>
##### `SquareRoot(a): FldFinElt -> FldFinElt`

<a id="function-sqrt-fldfinelt"></a>
##### `Sqrt(a): FldFinElt -> FldFinElt`

The square root of the non-zero element $a$ from the field $F$, i.e., an element $y$ of $F$ such that $y^2 = a$. An error results if $a$ is not a square.

<a id="function-root-fldfinelt-rngintelt"></a>
##### `Root(a, n): FldFinElt, RngIntElt -> FldFinElt`

The $n$-th root of the non-zero element $a$ from the field $F$, i.e., an element $y$ of $F$ such that $y^n = a$. An error results if no such root exists.

<a id="function-ispower-fldfinelt-rngintelt"></a>
##### `IsPower(a, n): FldFinElt, RngIntElt -> BoolElt, FldFinElt`

Given a finite field element $a\in F$, and an integer $n>0$, this function returns either `true` and an element $b\in F$ such that $b^n=a$, or it returns `false` in the case that such an element does not exist.

<a id="function-allroots-fldfinelt-rngintelt"></a>
##### `AllRoots(a, n): FldFinElt, RngIntElt -> SeqEnum`

Given a finite field element $a\in F$, and an integer $n>0$, return a sequence containing all of the $n$-th roots of $a$ which lie in the same field $F$.

<a id="example-ex-ead4e7"></a>
##### `Example: Roots and Traces of Elements (ex-ead4e7)`

Given the fields $F$ and $F49$ defined above, we can use the following functions:

```magma
> F7 := FiniteField(7);
> F49<w> := ext< F7 | 2 >;
> F<z> := ext< F49 | 2 >;
> Root(z^73, 7);
z^1039
> Trace(z^73);
1
> Trace(z^73, F49);
w^44
> Norm(z^73);
3
> Norm(z^73, F49);
w^37
> Norm(w^37);
3
> MinimalPolynomial(z^73);
x^2 + w^20*x + w^43
> MinimalPolynomial(z^73, F7);
x^4 + 4*x^2 + 4*x + 3
```

We now demonstrate the `NormEquation` function.

```magma
> Norm(z);
3
> NormEquation(F, F7!3);
true z
> Norm(z^30, F49);
w^30
> Parent(z) eq F;
true
> NormEquation(F, w^30);
true z^30
```

### Polynomials for Finite Fields

<a id="function-irreduciblepolynomial-fldfin-rngintelt"></a>
#### `IrreduciblePolynomial(F, n): FldFin, RngIntElt -> RngUPolElt`

Given a finite field $F$ and a positive integer $n > 1$, return a polynomial of degree $n$ that is irreducible over $F$. If a Conway polynomial or a sparse polynomial is available, then it is returned.

<a id="function-randomirreduciblepolynomial-fldfin-rngintelt"></a>
#### `RandomIrreduciblePolynomial(F, n): FldFin, RngIntElt -> RngUPolElt`

Given a finite field $F$ and a positive integer $n > 1$, return a random irreducible polynomial of degree $n$ that is irreducible over $F$. The polynomial will be dense in general (that is, a Conway or stored sparse polynomial is not used).

<a id="function-irreduciblelowtermgf2polynomial"></a>
#### `IrreducibleLowTermGF2Polynomial(n): RngIntElt -> RngUPolElt`

Given an integer $n$ in the range $1 \leq n \leq 100000$, return the irreducible polynomial $f$ of the form $x^n + g$ where the degree of $g$ is minimal and $g$ is the first such polynomial in lexicographical order. This uses a database of low-term irreducible polynomials over ${\bf F}_{2}$, constructed by Allan Steel in 2004 (thanks are expressed to William Stein for providing machines for some of the computations).

<a id="function-irreduciblesparsegf2polynomial"></a>
#### `IrreducibleSparseGF2Polynomial(n): RngIntElt -> RngUPolElt`

Given an integer $n$ in the range $4 \leq n \leq 12800$, return the irreducible polynomial $f$ of the form $x^n + g$ where $g$ has 2 non-zero terms if possible and 4 non-zero terms if not; $g$ is the first such polynomial in lexicographical order in either case. This uses a database of sparse irreducible polynomials over ${\bf F}_{2}$ constructed by Allan Steel in 1998.

<a id="function-primitivepolynomial-fldfin-rngintelt"></a>
#### `PrimitivePolynomial(F, m): FldFin, RngIntElt -> RngUPolElt`

Given a finite field $F$ and a positive integer $m > 1$, construct a polynomial $f$ of degree $m$ that is primitive over $F$. Thus, $f$ is irreducible over $F$, and it has a primitive root of the degree $m$ extension field of $F$ as a root.

<a id="function-allirreduciblepolynomials-fldfin-rngintelt"></a>
#### `AllIrreduciblePolynomials(F, m): FldFin, RngIntElt -> { RngUPolElt }`

Given a finite field $F$ and a positive integer $m > 1$, construct the set of all monic polynomials of degree $m$ that are irreducible over $F$.

<a id="function-conwaypolynomial-rngintelt-rngintelt"></a>
#### `ConwayPolynomial(p, n): RngIntElt, RngIntElt -> RngUPolElt`

Given a prime $p$ and an exponent $n \geq 1$, return the Conway polynomial of degree $n$ over ${\bf F}_{p}$. The Conway polynomial is defined in the introduction. Note that this polynomial is read in from a table containing Conway polynomials for a limited range of $p, n$ only.

<a id="function-existsconwaypolynomial-rngintelt-rngintelt"></a>
#### `ExistsConwayPolynomial(p, n): RngIntElt, RngIntElt -> BoolElt, RngUPolElt`

Given a prime $p$ and an exponent $n\geq1$, return `true` and the Conway polynomial for the field ${\bf F}_{p^n}$ if it is present in the table of Conway polynomials, which covers a limited range of $p$, $n$ only (see `ConwayPolynomial` above), `false` otherwise.

### Discrete Logarithms

Let $K$ be a field of cardinality $q=p^k$, with $p$ prime. Magma contains several advanced algorithms for computing discrete logarithms of elements of $K$. The two main kinds of algorithms used are as follows: (1) *Pohlig-Hellman* [[PH78](https://docs.magma-maths.org/references.md#cite-pohlighellman)]: The running time is usually proportional to the square root of the largest prime $l$ dividing $q-1$; this is combined with the Shanks baby-step/giant-step algorithm (when $l$ is very small) or the Pollard-$\rho$ algorithm. (2) *Index-Calculus*: There is first a precomputation stage which computes and stores all the logarithms of a *factor base* (all the elements of the field corresponding to irreducible polynomials up to some bound) and then each subsequent individual logarithm is computed by expressing the given element in terms of the factor base.

The different kinds of finite fields in Magma are handled as follows (in this order):

**(a)**
*Small Fields (any characteristic)*:

**•**
If the largest prime $l$ dividing $q-1$ is reasonably small (typically, less than $2^{36}$), the Pohlig-Hellman algorithm is used (the characteristic $p$ is irrelevant).

**(b)**
*Large Prime* :

**•**
Suppose $K$ is a prime field (so $q=p$). Then the *Gaussian integer sieve* [[COS86](https://docs.magma-maths.org/references.md#cite-cos-log), [LO91a](https://docs.magma-maths.org/references.md#cite-lo-log)] is used if $p$ has at least 4 bits but no more than 400 bits, $p-1$ is not a square, and one of the following is a quadratic residue modulo $p$: -1, -2, -3, -7, or -11. If the Gaussian integer sieve cannot be used and if $p$ is no more than 300-bits, then the *linear sieve* [[COS86](https://docs.magma-maths.org/references.md#cite-cos-log), [LO91a](https://docs.magma-maths.org/references.md#cite-lo-log)] is used. The precomputation stage always takes place and typically requires a lot more time than for computing individual logarithms (and may also require a lot of memory for large fields). Thus, the first call to the function `Log` below may take much more time than for subsequent calls. Also, for large prime fields, in comparison to the Gaussian method the linear sieve requires much more time and memory than the Gaussian method for the precomputation stage, and therefore it is only used when the Gaussian integer algorithm cannot be used. See the example [Discrete Logarithms by Linear Sieve](https://docs.magma-maths.org/MatricesLinearAlgebra/SparseMatrices/solution.md#example-ex-a75220) in the chapter on sparse matrices for an explanation of the basic linear sieve algorithm and for more information on the sparse linear algebra techniques employed.

**(c)**
*Small Characteristic, Non-prime* :

**•**
Since V2.19, if $K$ is a finite field of characteristic $p$, where either $p \le 7$ or a table as described below is present for $K$ (such tables exist only for $p$ less than about 100), then an implementation by Allan Steel of Coppersmith’s index-calculus algorithm [[Cop84](https://docs.magma-maths.org/references.md#cite-coppersmith84), [GM93](https://docs.magma-maths.org/references.md#cite-gomc93), [Tho01](https://docs.magma-maths.org/references.md#cite-thome01)] is used. (Strictly speaking, Coppersmith’s algorithm is for the case $p=2$ only, but a straightforward generalization is used when $p>2$.) A suite of external auxiliary tables boost the algorithm so that the precomputation stage computation to determine the logarithms of a factor base can be avoided for a large number of fields of small characteristic. This means that logarithms of individual elements can be computed immediately if a relevant table is present for the specific field; for $p > 7$ the algorithm is only used when such a table is present. By default, tables are included in the standard Magma distribution at least for all fields of characteristic 2, 3, 5, or 7 with cardinality up to $2^{200}$. The user can optionally download a much larger suite of tables from the Magma optional downloads page$\,$ `http://magma.maths.usyd.edu.au/magma/download/db/` (files `FldFinLog_2.tar.gz`, etc.; about 5GB total).

**(d)**
*Medium Characteristic, Non-prime* :

**•**
Since V2.30, if $K$ is a non-prime field of characteristic $p$, where $7 < p < 2^{20}$, with $q$ at least $2^{32}$ elements, the largest prime dividing $q-1$ is at least $2^{37}$ (so that the Pohlig-Hellman algorithm is impractical), and no table as in (c) is available for $K$, then, apart from a few special cases, an implementation by Allan Steel of the *function field sieve* (FFS) [[AH99](https://docs.magma-maths.org/references.md#cite-adlemanhuang99), [JL06](https://docs.magma-maths.org/references.md#cite-jouxlercier06)] is used. This covers in particular all such fields with $p > 100$, which previously could only be handled by the Pohlig-Hellman algorithm. Two polynomials $g_1$ and $g_2$ of small degrees $d_1$ and $d_2$ over ${\bf F}_{p}$ are chosen such that $g_2(g_1(x))-x$ and $g_1(g_2(x))-x$ both have a factor of degree $k$, giving two representations of $K$ between which there is an explicit isomorphism; the factor base consists of the monic irreducible polynomials over ${\bf F}_{p}$ of degree at most a bound $B$ on each side, and relations are found by a lattice sieve. The parameters $B$, $d_1$, $d_2$, and a limit on the size of the factor base are chosen automatically: by a rule calibrated on extensive timings, together with a table of measured optimal parameters for about 140 fields (with $101 \le p \le 211$ and $13 \le k \le 25$). Typically $B=1$ is chosen for $k$ up to about 19 and $B=2$ beyond that. As in (b), the precomputation stage takes place once for the given $p$ and $k$ (and is then used for any field of cardinality $p^k$, whatever its defining polynomial), and takes much longer than the computation of subsequent individual logarithms. For example, the precomputation for ${\bf F}_{101^{13}}$ or ${\bf F}_{1013^9}$ takes a few seconds, and that for ${\bf F}_{223^{21}}$ takes several minutes.

**(e)**
*Large Characteristic, Non-prime* :

**•**
In all other cases, the Pohlig-Hellman algorithm is used.

<a id="function-log-fldfinelt"></a>
#### `Log(x): FldFinElt -> RngIntElt`

The discrete logarithm of the non-zero element $x$ from the field $F$, i.e., the unique integer $k$ such that $x = w^k$ and $0 \leq k < (\#F-1)$, where $w$ is the primitive element of $F$ (as returned by `PrimitiveElement`). Default parameters are automatically chosen if an index-calculus method is used (use [`Sieve`](https://docs.magma-maths.org/BasicRings/FiniteFields/log.md#procedure-ff-sieve) below to set parameters). See also the procedure [`SetPrimitiveElement`](https://docs.magma-maths.org/BasicRings/FiniteFields/creation.md#procedure-ff-setprimitiveelement).

<a id="function-log-fldfinelt-fldfinelt"></a>
#### `Log(b, x): FldFinElt, FldFinElt -> RngIntElt`

The discrete logarithm to the base $b$ of the non-zero element $x$ from the field $F$, i.e., the unique integer $k$ such that $x = b^k$ and $0 \leq k < (\#F-1)$. If $b$ is not a primitive element, then in some unusual cases the algorithm may take much longer than normal.

<a id="function-zechlog-fldfin-rngintelt"></a>
#### `ZechLog(K, n): FldFin, RngIntElt -> RngIntElt`

The Zech logarithm $Z(n)$ of the integer $n$ for the field $F$, which equals the logarithm to base $w$ of $w^n + 1$, where $w$ is the primitive element of $F$. If $w^n$ is the minus one element of $K$, then -1 is returned.

<a id="procedure-ff-sieve"></a>
#### `Sieve(K): FldFin`

```magma
Lanczos: BoolElt                    Default: false
```

(Procedure.) Call the Gaussian integer sieve on the prime finite field $K$ if possible; otherwise call the linear sieve on $K$ (assuming $K$ is not too small).

If the parameter `Lanczos` is set to `true`, then the *Lanczos* algorithm [[LO91b](https://docs.magma-maths.org/references.md#cite-lo-slinalg), Sec. 3] will be used for the linear algebra phase. This is generally *very much slower* than the default method (often 10 to 50 times slower), but it will take considerably less memory, so may be preferable for extremely large fields. See also the function [`ModularSolution`](https://docs.magma-maths.org/MatricesLinearAlgebra/SparseMatrices/solution.md#function-smat-modularsolution) in the chapter on sparse matrices for more information.

<a id="procedure-setverbose-monstgelt-rngintelt-fflog"></a>
#### `SetVerbose("FFLog", v): MonStgElt, RngIntElt`

(Procedure.) Set the verbose printing level for the finite field logarithm algorithm to be $v$. Currently the legal values for $v$ are 0, 1, and 2. If the level is 1, information is printed whenever the logarithm of an element is computed (unless the field is very small, in which case a lookup table is used). The value of 2 will print a very large amount of information.

<a id="example-ex-e6dfa5"></a>
#### `Example: Discrete Logarithms in a Finite Field (ex-e6dfa5)`

We demonstrate the `Log` function.

```magma
> F<z> := FiniteField(7^4);
> PrimitiveElement(F);
z;
> Log(z);
1
> Log(z^2);
2
> Log(z + 1);
419
> z^419 eq z + 1;
true
> b := z + 1;
> b;
z^419
> Log(b, b);
1
> Log(b, z);
779
> b^779 eq z;
true
```

We now do similar things for a larger field of characteristic 2, which will use Coppersmith’s algorithm to compute the logarithms.

```magma
> F<z> := GF(2, 73);
> Factorization(#F-1);
[ <439, 1>, <2298041, 1>, <9361973132609, 1> ]
> PrimitiveElement(F);
z
> time Log(z + 1);
4295700317032218908392
Time: 5.400
> z^4295700317032218908392;
z + 1
> time Log(z + 1);
4295700317032218908392
Time: 0.000
> time Log(z^2);
2
Time: 0.000
> time Log(z^2134914112412412);
2134914112412412
Time: 0.000
> b := z + 1;
> b;
z + 1
> time Log(b, b);
1
Time: 0.010
> time Log(b, z);
2260630912967574270198
Time: 0.000
> b^2260630912967574270198;
z
```

### Permutation Polynomials

Let $K$ be a finite field. A polynomial representing (by the evaluation map) a bijection of $K$ into itself is known as a *permutation polynomial*. The Dickson polynomials of the first and second kind are permutation polynomials when certain conditions are satisfied.

<a id="function-dicksonfirst-rngintelt-rngelt"></a>
#### `DicksonFirst(n, a): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Dickson polynomial of the first kind $D_n (x, a)$ of degree $n$, where $D_n (x, a)$ is defined by

$$
D_n(x, a) = \sum_{i=0}^{\lfloor n/2 \rfloor}
   {n \over {n - i}} {{n - i} \choose i} (-a)^i x^{n - 2i}.
$$

<a id="function-dicksonsecond-rngintelt-rngelt"></a>
#### `DicksonSecond(n, a): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Dickson polynomial of the second kind $E_n (x, a)$ of degree $n$, where $E_n (x, a)$ is defined by

$$
E_n(x, a) = \sum_{i=0}^{\lfloor n/2 \rfloor}
   {{n - i} \choose {i}} (-a)^i x^{n - 2i}.
$$

<a id="function-isprobablypermutationpolynomial-rngupolelt"></a>
#### `IsProbablyPermutationPolynomial(p): RngUPolElt -> BoolElt`

```magma
NumAttempts: RngIntElt                    Default: 100
```

Let $p$ denote a polynomial defined over a finite field $K$. A probabilistic test is applied to determine whether the mapping on $K$ defined by $p$ is a bijection. The function returns `true` if the test succeeds for each of $n$ attempts, otherwise `false`. By default, $n$ is taken to be 100; a different value for $n$ can be specified by use of the parameter `NumAttempts`.

<a id="example-ex-41c38e"></a>
#### `Example: Dickson Permutation Polynomials (ex-41c38e)`

Let $K$ be a finite field of cardinality $q$. By a theorem of Nöbauer, the Dickson polynomial of the first kind of degree $n$ is a permutation polynomial for $K$ if and only if $(n, q^2 -1)=1$. Consider $K={\bf F}_{16}$.

```magma
> Factorization(16^2 - 1);
[ <3, 1>, <5, 1>, <17, 1> ]
```

Thus, $D_n (x, a)$ will be a permutation polynomial for $K$ providing that $n$ is coprime to 3, 5, and 17.

```magma
> K<w> := GF(16);
> R<x> := PolynomialRing(K);
> a := w^5;
> p1 := DicksonFirst(3, a);
> p1;
x^3 + w^5*x
> #{ Evaluate(p1, x) : x in K };
11
> IsProbablyPermutationPolynomial(p1);
false
```

So $D_3 (x, a)$ is not a permutation polynomial. However, $D_4 (x, a)$ is a permutation polynomial:

```magma
> p1 := DicksonFirst(4, a);
> p1;
x^7 + w^5*x^5 + x
> #{ Evaluate(p1, x) : x in K };
16
> IsProbablyPermutationPolynomial(p1);
true
```

<a id="field-near"></a>
<a id="chapnearfields"></a>
## Nearfields

- [Introduction](https://docs.magma-maths.org/BasicRings/Nearfields/Introduction.md)
- [Nearfield Properties](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-properties.md)
  - [Sharply Doubly Transitive Groups](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-properties.md#sharply-doubly-transitive-groups)
- [Constructing Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md)
  - [Dickson Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#dickson-nearfields)
    - [`DicksonPairs(p, hlo, hhi, vlo, vhi): RngIntElt, RngIntElt, RngIntElt, RngIntElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-dicksonpairs-rngintelt-rngintelt-rngintelt-rngintelt-rngintelt)
    - [`DicksonPairs(p, h1, v1): RngIntElt, RngIntElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-dicksonpairs-rngintelt-rngintelt-rngintelt)
    - [`DicksonTriples(p, hb, vb): RngIntElt, RngIntElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-dicksontriples-rngintelt-rngintelt-rngintelt)
    - [Example: Dickson Pairs](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#example-ex-d7494c)
    - [`NumberOfVariants(q, v): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-numberofvariants-rngintelt-rngintelt)
    - [`NumberOfVariants(N): NfdDck → RngIntElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-numberofvariants-nfddck)
    - [`VariantRepresentatives(q, v): RngIntElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-variantrepresentatives-rngintelt-rngintelt)
    - [Example: Variants of a Dickson Pair](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#example-ex-20e6ea)
    - [`DicksonNearfield(q, v : parameters): RngIntElt, RngIntElt → NfdDck`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-dicksonnearfield-rngintelt-rngintelt)
    - [Example: Constructing Dickson Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#example-ex-da0033)
  - [Zassenhaus Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#zassenhaus-nearfields)
    - [`ZassenhausNearfield(n): RngIntElt → NfdZss`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#function-zassenhausnearfield-rngintelt)
    - [Example: Zassenhaus Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-code.md#example-ex-af8523)
- [Operations on Elements](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md)
  - [Nearfield Arithmetic](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#nearfield-arithmetic)
    - [`+ a: NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-operation-nfdelt-nfdelt)
    - [`- a: NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-operation-nfdelt-nfdelt-2)
    - [`a + b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-plus-nfdelt-nfdelt)
    - [`a - b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-minus-nfdelt-nfdelt)
    - [`a * b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-times-nfdelt-nfdelt)
    - [`a / b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-div-nfdelt-nfdelt)
    - [`a ^ k: NfdElt, RngIntElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-pow-nfdelt-rngintelt)
    - [`a +:= b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-operation-nfdelt-nfdelt-nfdelt)
    - [`a -:= b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-operation-nfdelt-nfdelt-nfdelt-2)
    - [`a *:= b: NfdElt, NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-operation-nfdelt-nfdelt-nfdelt-3)
    - [`Inverse(a): NfdElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-inverse-nfdelt)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#equality-and-membership)
    - [`a eq b: NfdElt, NfdElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-eq-nfdelt-nfdelt)
    - [`a ne b: NfdElt, NfdElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-ne-nfdelt-nfdelt)
    - [`a in N: NfdElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-in-nfdelt-rng)
    - [`a notin N: NfdElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-notin-nfdelt-rng)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#parent-and-category)
    - [`Parent(a): NfdElt → FldFin`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-parent-nfdelt)
    - [`Category(a): NfdElt → Cat`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-category-nfdelt)
    - [`N ! x: Nfd, FldFinElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#operation-op-nfd-fldfinelt)
    - [`Element(N, x): Nfd, FldFinElt → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-element-nfd-fldfinelt)
    - [`ElementToSequence(x): NfdElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-elementtosequence-nfdelt)
  - [Predicates on Nearfield Elements](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#predicates-on-nearfield-elements)
    - [`IsZero(a): NfdElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-iszero-nfdelt)
    - [`IsUnit(a): NfdElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-isunit-nfdelt)
    - [`IsIdentity(a): NfdElt → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#function-isidentity-nfdelt)
    - [Example: Simple Nearfield Arithmetic](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#example-ex-bb693c)
    - [Example: Failure of Left Distributivity](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-eltops.md#example-ex-60b080)
- [Operations on Nearfields](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md)
  - [`N eq M: NfdDck, NfdDck → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#operation-op-eq-nfddck-nfddck)
  - [`N ne M: NfdDck, NfdDck → BoolElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#operation-op-ne-nfddck-nfddck)
  - [`#N: Nfd → RngIntElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#operation-operation-nfd-rngintelt)
  - [`Cardinality(N): Nfd → RngIntElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-cardinality-nfd)
  - [`Random(N): Nfd → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-random-nfd)
  - [`Identity(N): Nfd → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-identity-nfd)
  - [`Zero(N): Nfd → NfdElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-zero-nfd)
  - [`PrimeField(N): Nfd → FldFin`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-primefield-nfd)
  - [`Kernel(N): Nfd → FldFin`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-ops.md#function-kernel-nfd)
- [The Group of Units](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md)
  - [`UnitGroup(N): Nfd → GrpMat, Map`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-unitgroup-nfd)
  - [`UnitGroup(GrpPerm, N): Nfd → GrpPerm`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-unitgroup-nfd-2)
  - [`UnitGroup(GrpPC, N): NfdDck → GrpPC`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-unitgroup-nfddck)
  - [`UnitGroup(GrpPC, N): NfdZss → GrpPC`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-unitgroup-nfdzss)
  - [Example: Unit Group of a Subnearfield](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#example-ex-110490)
  - [`Order(x): NfdElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-order-nfdelt)
  - [`AffineGroup(N): Nfd → GrpMat`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-affinegroup-nfd)
  - [`AffineGroup(GrpPerm, N): Nfd → GrpPerm`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-affinegroup-nfd-2)
  - [`AffineGroup(GrpPC, N): NfdDck → GrpPC`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-affinegroup-nfddck)
  - [`AffineGroup(GrpPC, N): NfdZss → GrpPC`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-affinegroup-nfdzss)
  - [`ExtendedUnitGroup(D): NfdDck → GrpMat`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-units.md#function-extendedunitgroup-nfddck)
- [Automorphisms](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-iso.md)
  - [`IsIsomorphic(N1, N2): NfdDck, NfdDck → BoolElt, Map`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-iso.md#function-isisomorphic-nfddck-nfddck)
  - [`AutomorphismGroup(N): NfdDck → GrpPerm, Map`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-iso.md#function-automorphismgroup-nfddck)
  - [`AutomorphismGroup(N): NfdZss → GrpPerm`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-iso.md#function-automorphismgroup-nfdzss)
- [Nearfield Planes](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md)
  - [`ProjectivePlane(N : parameters): Nfd → PlaneProj, PlanePtSet, PlaneLnSet`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md#function-projectiveplane-nfd)
  - [Example: Projective Plane of a Nearfield](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md#example-ex-f4d8e0)
  - [Hughes Planes](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md#hughes-planes)
    - [`HughesPlane(N : parameters): Nfd → PlaneProj, PlanePtSet, PlaneLnSet`](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md#function-hughesplane-nfd)
    - [Example: Hughes Planes](https://docs.magma-maths.org/BasicRings/Nearfields/nearfield-planes.md#example-ex-c201b6)
- [Bibliography](https://docs.magma-maths.org/BasicRings/Nearfields/bibliography.md)

<a id="sectfldnearintro"></a>
<a id="id1"></a>
### Introduction

In 1905, in the course of proving the independence of the field postulates, L. E. Dickson [[Dic05a](https://docs.magma-maths.org/references.md#cite-dickson-1905a)] (p. 203) introduced the first example of a nearfield. His example is a set of 9 elements with operations of addition and multiplication which satisfy all the axioms of a field except for the commutative law of multiplication and the right distributive law. Later that year Dickson [[Dic05b](https://docs.magma-maths.org/references.md#cite-dickson-1905b)] published a more extensive collection of examples: an infinite series obtained by twisting the multiplication of a Galois field and seven “irregular” examples.

The terminology ‘nearfield’ seems to have been introduced by Zassenhaus in his 1935 paper [[Zas35](https://docs.magma-maths.org/references.md#cite-zassenhaus-1935b)] where he showed that the only finite nearfields (endliche Fastkörper) are those due to Dickson.

The irregular nearfields are often referred to as Zassenhaus nearfields and the nearfields in the infinite series are called Dickson nearfields.

In the papers of Dickson and Zassenhaus the nearfields are left-distributive but for the purposes of the Magma implementation we consider only right-distributive nearfields.

Nearfields are important in group theory, geometry, and a combination of these two fields. On the one hand, the finite sharply doubly transitive permutation groups are in one-to-one correspondence with the finite nearfields and on the other hand, nearfields coordinatise a class of translation planes [[Hal59](https://docs.magma-maths.org/references.md#cite-hall-1959), [Lun69](https://docs.magma-maths.org/references.md#cite-luneburg-1968)] and they are the starting point for the construction of the Hughes planes [[Dem71](https://docs.magma-maths.org/references.md#cite-dembowski-1971), [Hug57](https://docs.magma-maths.org/references.md#cite-hughes-1957)]. Furthermore, every sharply transitive collineation group of projective space over a finite field is a quotient of the group of units of a nearfield [[EK63](https://docs.magma-maths.org/references.md#cite-ellers-karzel-1963)] (see also, [[Dem68](https://docs.magma-maths.org/references.md#cite-dembowski-1968)] (§1.4, n${}^{\rm o}$ 17)).

<a id="sectfldnearprop"></a>
<a id="id1"></a>
### Nearfield Properties

A (right-distributive) *nearfield* is a set $N$ containing elements $0$ and $1$ and with binary operations $+$ and $\circ$ such that

**•**
**NF1:** $(N,+)$ is an abelian group and $0$ is its identity element. Let $N^\times$ denote the set of non-zero elements of $N$.

**•**
**NF2:** $(N^\times,\circ)$ is a group and $1$ is its identity element.

**•**
**NF3:** $a\circ 0 = 0\circ a = 0$ for all $a\in N$.

**•**
**NF4:** $(a+b)\circ c = a\circ c + b\circ c$ for all $a,b,c \in N$.

A subset $S$ of a nearfield $N$ is a *sub-nearfield* if $(S,+)$ and $(S\setminus \{0\},\circ)$ are groups. The sub-nearfield *generated* by a subset $X$ is the intersection of all sub-nearfields containing $X$. The *prime field* ${\cal P}(N)$ of $N$ is the sub-nearfield generated by $1$.

The inverse of $x\in N^\times$ is written $x^{[-1]}$. But where no confusion is possible we write multiplication of nearfield elements $x$ and $y$ as $xy$ rather than $x\circ y$ and we write the inverse of $x$ as $x^{-1}$. (In the Magma code we use “\*” as the symbol for multiplication.)

If $N$ is a finite nearfield, the prime field of $N$ is a Galois field ${\bf F}_{p}$ for some prime $p$ and $p$ is the *characteristic* of $N$.

A nearfield of characteristic $p$ is a vector space over its prime field and therefore its cardinality is $p^n$ for some $n$. Every field is a nearfield.

If $N$ is a nearfield, the *centre* of $N$ is the set

$$
{\cal Z}(N) = \{\, x \in N \mid xy = yx\text{ for all }y\in N\,\}
$$

and the *kernel* of $N$ is the subfield

$$
{\cal K}(N) = \{\, x \in N \mid x(y+z) = xy + xz\text{ for all
  }y,z\in N\,\}.
$$

It is clear that ${\cal Z}(N) \subseteq {\cal K}(N)$ but equality need not hold because, in general, ${\cal Z}(N)$ need not be closed under addition. Furthermore, the prime field ${\cal P}(N)$ need not be contained in ${\cal Z}(N)$. However, for the Dickson nearfields ${\cal Z}(N) = {\cal K}(N)$.

If $N$ is a nearfield, then ${\cal Z}(N) = \bigcap\{ {\cal K}(N)^x \mid x \in N, x \ne 0\}$.

<a id="twotrans"></a>
<a id="subsectsharp"></a>
#### Sharply Doubly Transitive Groups

A group $G$ acting on a set $\Omega$ is *sharply doubly transitive* if $G$ is doubly transitive on $\Omega$ and only the identity element fixes two points.

If $G$ is a finite sharply doubly transitive group on $\Omega$ then

1. The set $M$ consisting of the identity element and the elements of $G$ without fixed points is an elementary abelian normal subgroup of $G$ of order $p^n$ for some $n$ and some prime $p$.
2. Addition and multiplication between elements of $\Omega$ can be defined so that $\Omega$ becomes a nearfield and so that the group $G$ is isomorphic to the group of all affine transformations $v \mapsto va+b$ of $\Omega$, where $a\in \Omega^\times$ and $b\in \Omega$.

There is a converse to this theorem, namely if $N$ is a nearfield, the group of all transformations $v \mapsto va+b$ acts sharply doubly transitively on $N$.

Let $F$ be the prime field of $N$, regard $N$ as a vector space over $F$ and define $\mu : N^\times \to {\operatorname{GL}}(N)$ by $v^{\mu(a)} = va$. Then for all $a\in N^\times$, $a \ne 1$, the linear transformation $\mu(a)$ is fixed-point-free. Furthermore, $\mu$ defines an isomorphism between the multiplicative group $N^\times$ and its image in ${\operatorname{GL}}(N)$.

Suppose that $G = H\ltimes M$ is a sharply doubly transitive group of degree $p^n$, as above. The centre of $G$ is trivial and $M$ is a minimal normal subgroup. Thus if $\Omega'$ is a minimal permutation representation we may suppose that it is primitive. Then $M$ is transitive on $\Omega'$ and since $M$ is abelian, it acts regularly on $\Omega'$. Thus $p^n$ is the minimal degree of a faithful permutation representation of $G$.

<a id="nearfield-code"></a>
<a id="sectfldnearcode"></a>
### Constructing Nearfields

There are two types of finite nearfield: the *regular* nearfields of Dickson and the *irregular* nearfields of Zassenhaus. In order to accommodate both types Magma has a ‘virtual type’ `Nfd` and types `NfdDck` and `NfdZss` which inherit from `Nfd`.

<a id="dickson"></a>
<a id="subsectdickson"></a>
#### Dickson Nearfields

In order to begin exploring `Nfd` types in Magma we need a way to create instances of nearfields and their elements. As already mentioned there is a large class of nearfields first described by L. E. Dickson [[Dic05a](https://docs.magma-maths.org/references.md#cite-dickson-1905a), [Dic05b](https://docs.magma-maths.org/references.md#cite-dickson-1905b)] in 1905 and in this section we describe how to construct them in Magma.

The nearfields resulting from this construction will be called *Dickson* (or *regular*) nearfields.

If $p$ is a prime and if the positive integers $h$ and $v$ satisfy

- *if* $r$ *is a prime or* $4$ *and if* $r$ *divides* $v$*, then* $r$ *divides* $p^h-1$

then $(p,h,v)$ is a *Dickson triple*.

If we write $q = p^h$, the condition above is equivalent to

- *All prime factors of* $v$ *divide* $q-1$ *and* $q\equiv 3 \bmod 4$ *implies* $v \not\equiv 0 \bmod 4$*.*

We call $(q,v)$ a *Dickson pair*.

<a id="function-dicksonpairs-rngintelt-rngintelt-rngintelt-rngintelt-rngintelt"></a>
##### `DicksonPairs(p, hlo, hhi, vlo, vhi): RngIntElt, RngIntElt, RngIntElt, RngIntElt, RngIntElt -> SeqEnum`

The list of Dickson pairs $(q, v)$ for prime $p$, where *hlo* and *hhi* are the lower and upper bounds on $h$ and where *vlo* and *vhi* are the lower and upper bounds on $v$.

<a id="function-dicksonpairs-rngintelt-rngintelt-rngintelt"></a>
##### `DicksonPairs(p, h1, v1): RngIntElt, RngIntElt, RngIntElt -> SeqEnum`

The list of Dickson pairs $(p^h, v)$ for the prime $p$, where $h1$ and $v1$ are upper bounds on $h$ and $v$.

<a id="function-dicksontriples-rngintelt-rngintelt-rngintelt"></a>
##### `DicksonTriples(p, hb, vb): RngIntElt, RngIntElt, RngIntElt -> SeqEnum`

The list of Dickson triples $(p,h,v)$ for the prime $p$, where $hb$ and $vb$ are bounds on $h$ and $v$.

<a id="example-ex-d7494c"></a>
##### `Example: Dickson Pairs (ex-d7494c)`

For each Dickson pair (equivalently Dickson triple), there is at least one Dickson nearfield.

```magma
> DicksonPairs(5,3,4,4,5);
[
    [ 125, 4 ],
    [ 625, 4 ]
]
> DicksonPairs(5,4,5);
[
    [ 5, 1 ],
    [ 5, 2 ],
    [ 5, 4 ],
    [ 25, 1 ],
    [ 25, 2 ],
    [ 25, 3 ],
    [ 25, 4 ],
    [ 125, 1 ],
    [ 125, 2 ],
    [ 125, 4 ],
    [ 625, 1 ],
    [ 625, 2 ],
    [ 625, 3 ],
    [ 625, 4 ]
]
> DicksonTriples(5,4,5);
[
    [ 5, 1, 1 ],
    [ 5, 1, 2 ],
    [ 5, 1, 4 ],
    [ 5, 2, 1 ],
    [ 5, 2, 2 ],
    [ 5, 2, 3 ],
    [ 5, 2, 4 ],
    [ 5, 3, 1 ],
    [ 5, 3, 2 ],
    [ 5, 3, 4 ],
    [ 5, 4, 1 ],
    [ 5, 4, 2 ],
    [ 5, 4, 3 ],
    [ 5, 4, 4 ]
]
```

The isomorphism type of a Dickson nearfield depends on the choice of primitive element of the underlying Galois field. It has been shown by Lüneburg [[Lun71](https://docs.magma-maths.org/references.md#cite-luneburg-1971)] that if $\phi$ is the Euler phi-function and $g$ is the order of $p$ modulo $v$, there are $\phi(v)/g$ isomorphism classes of Dickson nearfields with the same Dickson triple $(p,h,v)$.

The default nearfield will use the ‘standard’ primitive element of the field. The other variants with the same Dickson pair can be obtained by providing an integer $s$ coprime to $v$. Internally this is converted to a suitable integer $e$ coprime to $q^v -1$ such that $s\equiv e \pmod v$.

<a id="function-numberofvariants-rngintelt-rngintelt"></a>
##### `NumberOfVariants(q, v): RngIntElt, RngIntElt -> RngIntElt`

The number of non-isomorphic nearfields with Dickson pair $(q,v)$.

<a id="function-numberofvariants-nfddck"></a>
##### `NumberOfVariants(N): NfdDck -> RngIntElt`

The number of variants of the Dickson nearfield $N$.

<a id="function-variantrepresentatives-rngintelt-rngintelt"></a>
##### `VariantRepresentatives(q, v): RngIntElt, RngIntElt -> SeqEnum`

Representatives for the variant parameter of nearfields with Dickson pair $(q,v)$.

<a id="example-ex-20e6ea"></a>
##### `Example: Variants of a Dickson Pair (ex-20e6ea)`

For each Dickson pair there can be several variants. The variant representative can be used when constructing the corresponding Dickson nearfield.

```magma
> NumberOfVariants(625,4);
2
> VariantRepresentatives(625,4);
[ 1, 3 ]
```

<a id="function-dicksonnearfield-rngintelt-rngintelt"></a>
##### `DicksonNearfield(q, v : parameters): RngIntElt, RngIntElt -> NfdDck`

```magma
Variant      : RngIntElt                    Default: 1
LargeMatrices: BoolElt                      Default: false
```

Create a Dickson nearfield from the Dickson pair $(q,v)$. The `Variant` parameter is an integer $s$ which can be used to specify the choice of primitive element (see the discussion following the intrinsic `DicksonTriples`). The parameter `LargeMatrices` is used only when the group of units of the nearfield is requested. The default is to represent the group of units as a matrix group defined over the kernel of the nearfield. But if `LargeMatrices` is `true`, the matrices are defined over the prime field.

<a id="example-ex-da0033"></a>
##### `Example: Constructing Dickson Nearfields (ex-da0033)`

As indicated in the previous example, up to isomorphism, there are two Dickson nearfields with Dickson pair $(625,4)$.

```magma
> D := DicksonNearfield(625,4);
> D3 := DicksonNearfield(625,4 : Variant := 3);
> D5 := DicksonNearfield(625,4 : Variant := 5);
> D eq D3;
false
> D3 eq D5;
false
> D eq D5;
true
> D;
Nearfield D of Dickson type defined by the pair (625, 4)
Order = 152587890625
```

<a id="irreg"></a>
<a id="subsectirreg"></a>
#### Zassenhaus Nearfields

It was shown by Zassenhaus [[Zas35](https://docs.magma-maths.org/references.md#cite-zassenhaus-1935b)] that in addition to the regular nearfields there are seven *irregular* nearfields. Zassenhaus gave constructions but did not prove their uniqueness. The proofs in [[Zas35](https://docs.magma-maths.org/references.md#cite-zassenhaus-1935b)] are known to contain gaps. Perhaps the most reliable account of the existence and uniqueness of the irregular nearfields is the PhD thesis of Dancs-Groves [[Gro74](https://docs.magma-maths.org/references.md#cite-dancs-1974)].

The seven finite nearfields which are not Dickson nearfields are the *Zassenhaus* nearfields.

Zassenhaus nearfields can be distinguished from regular nearfields by the fact that the multiplicative group of a finite nearfield $N$ is metacyclic if and only if $N$ is regular.

As a consequence, a Zassenhaus nearfield cannot occur as a subfield of a Dickson nearfield.

<a id="function-zassenhausnearfield-rngintelt"></a>
##### `ZassenhausNearfield(n): RngIntElt -> NfdZss`

Creates the $n$th Zassenhaus nearfield.

<a id="example-ex-af8523"></a>
##### `Example: Zassenhaus Nearfields (ex-af8523)`

The orders of the Zassenhaus nearfields are $5^2$, $11^2$, $7^2$, $23^2$, $11^2$, $29^2$, and $59^2$.

```magma
> for n := 1 to 7 do ZassenhausNearfield(n); end for;
Irregular nearfield Z with Zassenhaus number 1
Order = 25
Irregular nearfield Z with Zassenhaus number 2
Order = 121
Irregular nearfield Z with Zassenhaus number 3
Order = 49
Irregular nearfield Z with Zassenhaus number 4
Order = 529
Irregular nearfield Z with Zassenhaus number 5
Order = 121
Irregular nearfield Z with Zassenhaus number 6
Order = 841
Irregular nearfield Z with Zassenhaus number 7
Order = 3481
```

<a id="nearfield-eltops"></a>
<a id="sectfldneareltops"></a>
### Operations on Elements

<a id="arithmetic"></a>
<a id="subsectarith"></a>
#### Nearfield Arithmetic

The operations of addition, subtraction, and negation are inherited from the underlying Galois field.

The operation of multiplication distinguishes a nearfield from a field. In a nearfield, multiplication is not commutative and the left distributive law fails.

<a id="operation-operation-nfdelt-nfdelt"></a>
##### `+ a: NfdElt -> NfdElt`

<a id="operation-operation-nfdelt-nfdelt-2"></a>
##### `- a: NfdElt -> NfdElt`

<a id="operation-op-plus-nfdelt-nfdelt"></a>
##### `a + b: NfdElt, NfdElt -> NfdElt`

<a id="operation-op-minus-nfdelt-nfdelt"></a>
##### `a - b: NfdElt, NfdElt -> NfdElt`

<a id="operation-op-times-nfdelt-nfdelt"></a>
##### `a * b: NfdElt, NfdElt -> NfdElt`

<a id="operation-op-div-nfdelt-nfdelt"></a>
##### `a / b: NfdElt, NfdElt -> NfdElt`

<a id="operation-op-pow-nfdelt-rngintelt"></a>
##### `a ^ k: NfdElt, RngIntElt -> NfdElt`

<a id="operation-operation-nfdelt-nfdelt-nfdelt"></a>
##### `a +:= b: NfdElt, NfdElt -> NfdElt`

<a id="operation-operation-nfdelt-nfdelt-nfdelt-2"></a>
##### `a -:= b: NfdElt, NfdElt -> NfdElt`

<a id="operation-operation-nfdelt-nfdelt-nfdelt-3"></a>
##### `a *:= b: NfdElt, NfdElt -> NfdElt`

<a id="function-inverse-nfdelt"></a>
##### `Inverse(a): NfdElt -> NfdElt`

The inverse of $a$.

#### Equality and Membership

<a id="operation-op-eq-nfdelt-nfdelt"></a>
##### `a eq b: NfdElt, NfdElt -> BoolElt`

<a id="operation-op-ne-nfdelt-nfdelt"></a>
##### `a ne b: NfdElt, NfdElt -> BoolElt`

<a id="operation-op-in-nfdelt-rng"></a>
##### `a in N: NfdElt, Rng -> BoolElt`

<a id="operation-op-notin-nfdelt-rng"></a>
##### `a notin N: NfdElt, Rng -> BoolElt`

#### Parent and Category

<a id="function-parent-nfdelt"></a>
##### `Parent(a): NfdElt -> FldFin`

<a id="function-category-nfdelt"></a>
##### `Category(a): NfdElt -> Cat`

<a id="operation-op-nfd-fldfinelt"></a>
##### `N ! x: Nfd, FldFinElt -> NfdElt`

<a id="function-element-nfd-fldfinelt"></a>
##### `Element(N, x): Nfd, FldFinElt -> NfdElt`

Create a nearfield element from a finite field element.

<a id="function-elementtosequence-nfdelt"></a>
##### `ElementToSequence(x): NfdElt -> SeqEnum`

Create a sequence from an element $x$ of a nearfield.

#### Predicates on Nearfield Elements

<a id="function-iszero-nfdelt"></a>
##### `IsZero(a): NfdElt -> BoolElt`

<a id="function-isunit-nfdelt"></a>
##### `IsUnit(a): NfdElt -> BoolElt`

<a id="function-isidentity-nfdelt"></a>
##### `IsIdentity(a): NfdElt -> BoolElt`

<a id="example-ex-bb693c"></a>
##### `Example: Simple Nearfield Arithmetic (ex-bb693c)`

This example illustrates some of the basic operations available on nearfields and their elements. There is a strong connection with the arithmetic of the underlying Galois field of a nearfield `D`, which is available as the attribute ``D`gf``.

```magma
> D := DicksonNearfield(3^2,2);
> K := D`gf;
> x := Element(D,K.1);
> x;
$.1
> Parent(x);
Nearfield D of Dickson type defined by the pair (9, 2)
Order = 81
> x^2;
$.1^10
> Identity(D);
1
> assert x ne Identity(D);
> assert x eq x;
> Zero(D);
0
> Parent(Zero(D));
Nearfield D of Dickson type defined by the pair (9, 2)
Order = 81
> assert not IsZero(D!1);
> assert not IsZero(x);
> assert IsZero(Zero(D));
> K<z> := GF(3,4);
> x := Element(D,z^61);
> y := Element(D,z^54);
> assert x + y eq Element(D,z^61+z^54);
> assert x - y eq Element(D,z^61-z^54);
> x*y;
z^35
> x/y;
z^7
> x^y;
z^29
```

<a id="example-ex-60b080"></a>
##### `Example: Failure of Left Distributivity (ex-60b080)`

A nearfield is right-distributive, but unlike a Galois field, multiplication is not commutative and the left-distributive law may fail.

```magma
> N := DicksonNearfield(3^2,4);
> F<a> := N`gf;
> x := Element(N,a^5215);
> y := Element(N,a^5140);
> z := Element(N,a^5819);
> x*y eq y*x;
false
> x*(y+z) eq x*y+x*z;
false
> (y+z)*x eq y*x+z*x;
true
```

<a id="nearfield-ops"></a>
<a id="sectfldnearops"></a>
### Operations on Nearfields

<a id="operation-op-eq-nfddck-nfddck"></a>
#### `N eq M: NfdDck, NfdDck -> BoolElt`

<a id="operation-op-ne-nfddck-nfddck"></a>
#### `N ne M: NfdDck, NfdDck -> BoolElt`

<a id="operation-operation-nfd-rngintelt"></a>
#### `#N: Nfd -> RngIntElt`

<a id="function-cardinality-nfd"></a>
#### `Cardinality(N): Nfd -> RngIntElt`

The cardinality of the nearfield $N$.

<a id="function-random-nfd"></a>
#### `Random(N): Nfd -> NfdElt`

A random element of the nearfield $N$.

<a id="function-identity-nfd"></a>
#### `Identity(N): Nfd -> NfdElt`

The multiplicative identity of the nearfield $N$.

<a id="function-zero-nfd"></a>
#### `Zero(N): Nfd -> NfdElt`

The additive identity of the nearfield $N$.

<a id="function-primefield-nfd"></a>
#### `PrimeField(N): Nfd -> FldFin`

The prime field of the nearfield $N$.

<a id="function-kernel-nfd"></a>
#### `Kernel(N): Nfd -> FldFin`

Return the kernel of the nearfield $N$ as a finite field.

<a id="nearfield-units"></a>
<a id="sectfldnearunits"></a>
### The Group of Units

If $N$ is a nearfield and $F = {\cal K}(N)$ is its kernel, $N$ is a vector space over $F$ and for all $u\in N^\times$, the map $x \mapsto x\circ u$ is an $F$-linear transformation. This action of $N^\times$ on the non-zero elements of the vector space is transitive and fixed-point-free.

Similarly, we may regard $N$ as a vector space over its prime field and again the elements of $N^\times$ act as linear transformations. In the following code the vector space $E$ could be either a vector space over the kernel or a vector space of the prime field. The default setting is to use the kernel. But if the parameter `LargeMatrices` is set to `true` when a regular nearfield is first defined, the prime field will be used. For irregular nearfields the kernel coincides with the prime field.

Let $(p,h,v)$ be the Dickson triple for $N$, let $\zeta$ be a primitive element of $K = {\bf F}_{q^v}$ and put $A = \langle \zeta^v\rangle$. Then $A$ is a group of order $m = (q^v-1)/v$ and the elements $s_i = \zeta^{(q^i-1)/(q-1)}$ ($1\le i \le v$) are coset representatives for $A$ in $K^\times$. Let $\Phi$ denote the Frobenius automorphism $x \mapsto x^q$ of $K$ and define $\rho : K^\times \to {\operatorname{Gal}}(K/{\bf F}_{p})$ by $\rho(u) = \Phi^i$ if $u\in s_iA$; that is, letting automorphisms of $K$ act on the right, we have $x^{\rho(u)} = x^{q^i}$. The map $\rho$ is not a homomorphism. However, its image is the cyclic group of order $v$ generated by $\Phi = \rho(\zeta)$ and the fixed field of $\hbox{im}\rho$ is ${\bf F}_{q}$; thus $\hbox{im}\rho$ may be identified with ${\operatorname{Gal}}(K/{\bf F}_{q})$.

The underlying set of $N$ is identified with $K$ and multiplication in $N$ is defined to be $w\circ u = w^{\rho(u)}u$.

The group $U$ of units of the Dickson nearfield $D = D(p,h,v,\zeta)$ has generators $a$ and $b$ and relations $a^m = 1$, $b^v = a^t$, and $b^{-1}ab = a^q$, where $q = p^h$, $m = (q^v-1)/v$, and $t = m/(q-1)$. Furthermore, Ellers and Karzel [[EK64](https://docs.magma-maths.org/references.md#cite-ellers-karzel-1964)] show that $\gcd(v,t) = \gcd(q-1,t) \le 2$. Equality holds if and only if $v \equiv 2 \pmod 4$ and $q\equiv 3\pmod 4$ and this in turn is equivalent to the Sylow $2$-subgroup of $U$ being a generalised quaternion group.

The centre of $D$ is ${\bf F}_{q}$ and its group of units is generated by $\zeta^{vt}$.

<a id="function-unitgroup-nfd"></a>
#### `UnitGroup(N): Nfd -> GrpMat, Map`

<a id="function-unitgroup-nfd-2"></a>
#### `UnitGroup(GrpPerm, N): Nfd -> GrpPerm`

<a id="function-unitgroup-nfddck"></a>
#### `UnitGroup(GrpPC, N): NfdDck -> GrpPC`

<a id="function-unitgroup-nfdzss"></a>
#### `UnitGroup(GrpPC, N): NfdZss -> GrpPC`

The unit group of the nearfield $N$.

<a id="example-ex-110490"></a>
#### `Example: Unit Group of a Subnearfield (ex-110490)`

In this example we construct the group of units of a subnearfield.

```magma
> N := DicksonNearfield(3^3,13);
> zeta := N`prim;
> x := N!(zeta^((3^39-1) div (3^13-1)));
> S := sub< N | x >;
> U := UnitGroup(S);
> IsAbelian(U);
true
> Factorisation(#N);
[ <3, 39> ]
> Factorisation(#S);
[ <3, 13> ]
> Factorisation(#Kernel(N));
[ <3, 3> ]
> S;
Nearfield S of Dickson type defined by the pair (1594323, 1)
Order = 1594323
```

<a id="function-order-nfdelt"></a>
#### `Order(x): NfdElt -> RngIntElt`

The order of the unit $x$ of a nearfield.

As a matrix group, the unit group $U$ of a nearfield acts regularly on the non-zero vectors of the underlying vector space $E$ and consequently the affine group $E\cdot U$ is sharply two-transitive. All sharply two-transitive groups occur in this way.

<a id="function-affinegroup-nfd"></a>
#### `AffineGroup(N): Nfd -> GrpMat`

<a id="function-affinegroup-nfd-2"></a>
#### `AffineGroup(GrpPerm, N): Nfd -> GrpPerm`

<a id="function-affinegroup-nfddck"></a>
#### `AffineGroup(GrpPC, N): NfdDck -> GrpPC`

<a id="function-affinegroup-nfdzss"></a>
#### `AffineGroup(GrpPC, N): NfdZss -> GrpPC`

The sharply two-transitive affine group associated with a nearfield, returned as a matrix group.

If $\Gamma = {\operatorname{Gal}}(K/{\bf F}_{p})$ and $S = \Gamma\ltimes K^\times$ is the semidirect product of $\Gamma$ and $K^\times$, then $D^\times \to S : w \mapsto \rho(w)w$ is an embedding of the multiplicative group $D^\times$ of $D = D(p,h,v,\zeta)$ in $S$, where multiplication in $S$ is defined by

$$
(\gamma_1 a_1)(\gamma_2 a_2) = \gamma_1\gamma_2 a_1^{\gamma_2} a_2.
$$

If $U$ is the image of $D^\times$ in $S$, then $\Gamma\cap U = 1$, $\Gamma U = S$, and $K^\times \cap U = A = \langle\zeta^v\rangle$. In fact, from the definition of $\rho$, we have $UK^\times = \Gamma_0\ltimes K^\times$, where $\Gamma_0 = \Gal(K/{\bf F}_{q})$. This is the *extended unit group* of the Dickson nearfield $D$.

<a id="function-extendedunitgroup-nfddck"></a>
#### `ExtendedUnitGroup(D): NfdDck -> GrpMat`

The extended unit group of a Dickson nearfield.

<a id="nearfield-iso"></a>
<a id="sectfldneariso"></a>
### Automorphisms

<a id="function-isisomorphic-nfddck-nfddck"></a>
#### `IsIsomorphic(N1, N2): NfdDck, NfdDck -> BoolElt, Map`

Test whether the regular nearfields $N_1$ and $N_2$ are isomorphic. If they are, return an isomorphism.

<a id="function-automorphismgroup-nfddck"></a>
#### `AutomorphismGroup(N): NfdDck -> GrpPerm, Map`

<a id="function-automorphismgroup-nfdzss"></a>
#### `AutomorphismGroup(N): NfdZss -> GrpPerm`

The automorphism group $A$ of the regular nearfield $N$ and a map giving the action of $A$ on $N$.

<a id="sectfldnearplanes"></a>
<a id="id1"></a>
### Nearfield Planes

A nearfield $N$ is said to be *planar* if the mapping $x\mapsto -xa+xb$ is a permutation of $N$ whenever $a\ne b$. Every finite nearfield is planar.

Given a finite nearfield $N$, there is an *affine* plane $\cal A$ with point set $N\times N$ and lines given by the equations

$$
\begin{aligned}y &= xm+b\\
  x &= c\end{aligned}
$$

Let $\cal P$ be the corresponding projective plane, obtained from $\cal A$ by adjoining a line $L_\infty$ called the *line at infinity*. We label the points of $\cal P$ with triples of elements of $N$ as follows.

(1) For every point $(x,y)$ of $\cal A$ there is a point $[1,x,y]$ of $\cal P$.

(2) For every $m$ there is an “ideal” point $[0,1,m]$ of $\cal P$ which lies on every line $y = xm+b$ ($b\in N$) and on $L_\infty$.

(3)There is a point $[0,0,1]$ of $\cal P$ which lies on every line $x = c$ and on $L_\infty$.

The lines of $\cal P$ may also be labelled by triples of elements of $N$: the line $y = xm+b$ corresponds to the triple $[-b,-m,1]$ and the line $x = c$ corresponds to $[-c,1,0]$. The line $L_\infty$ is labelled $[1,0,0]$. A point $\pi = [w,x,y]$ is incident with a line $L = [a,b,c]$ if and only if $wa+xb+yc= 0$.

Every collineation of $\cal A$ extends to a collineation of $\cal P$.

<a id="function-projectiveplane-nfd"></a>
#### `ProjectivePlane(N : parameters): Nfd -> PlaneProj, PlanePtSet, PlaneLnSet`

```magma
Check: BoolElt                    Default: false
```

The finite projective plane coordinatised by the nearfield $N$. The points of the nearfield plane are represented as triples of Galois field elements.

<a id="example-ex-f4d8e0"></a>
#### `Example: Projective Plane of a Nearfield (ex-f4d8e0)`

```magma
> N := DicksonNearfield(3,2);
> pl := ProjectivePlane(N);
> A := AutomorphismGroup(pl);
> #A;
311040
> CompositionFactors(A);
    G
    |  Cyclic(2)
    *
    |  Alternating(5)
    *
    |  Cyclic(2)
    *
    |  Cyclic(2)
    *
    |  Cyclic(2)
    *
    |  Cyclic(2)
    *
    |  Cyclic(2)
    *
    |  Cyclic(3)
    *
    |  Cyclic(3)
    *
    |  Cyclic(3)
    *
    |  Cyclic(3)
    1
```

<a id="hughes"></a>
<a id="subsecthughes"></a>
#### Hughes Planes

In 1957 Hughes [[Hug57](https://docs.magma-maths.org/references.md#cite-hughes-1957)] discovered a class of finite projective planes constructed from the Dickson nearfields which have rank 2 over their kernel. Neither these planes nor their duals are translation planes and therefore they cannot be obtained by the coordinatisation method of the previous section. Hughes’ methods required the kernel to be central but in 1960 the construction was generalised by Rosati [[Ros60](https://docs.magma-maths.org/references.md#cite-rosati-1960b)] to include the Zassenhaus nearfields (see also Dembowski [[Dem68](https://docs.magma-maths.org/references.md#cite-dembowski-1968), §5.4] and [[Dem71](https://docs.magma-maths.org/references.md#cite-dembowski-1971)]). For simplicity of notation we shall use the term ‘Hughes plane’ to include both Hughes planes and generalised Hughes planes.

<a id="function-hughesplane-nfd"></a>
##### `HughesPlane(N : parameters): Nfd -> PlaneProj, PlanePtSet, PlaneLnSet`

```magma
Check: BoolElt                    Default: false
```

The Hughes plane based on the nearfield $N$.

<a id="example-ex-c201b6"></a>
##### `Example: Hughes Planes (ex-c201b6)`

We construct the Desarguesian projective plane `PG(2,49)` and then, using nearfields of order 49, we construct three non-Desarguesian projective planes. These four planes can be distinguished by the orders of their collineation groups.

```magma
> DP := FiniteProjectivePlane(49); // Desarguesian plane
> DP;
Projective Plane PG(2, 49)
> CD  := CollineationGroup(DP);
> FactoredOrder(CD);
[ <2, 10>, <3, 3>, <5, 2>, <7, 6>, <19, 1>, <43, 1> ]
> N := DicksonNearfield(7,2);
> NP := ProjectivePlane(N);
> NP;
Projective Plane of order 49
> CN := CollineationGroup(NP);
> FactoredOrder(CN);
[ <2, 10>, <3, 2>, <7, 4> ]
> Z := ZassenhausNearfield(3);
> #Z;
49
> ZP := ProjectivePlane(Z);
> CZ := CollineationGroup(ZP);
> FactoredOrder(CZ);
[ <2, 9>, <3, 3>, <7, 4> ]
> HP := HughesPlane(N);
> HP;
Projective Plane of order 49
> CH := CollineationGroup(HP);
> FactoredOrder(CH);
[ <2, 6>, <3, 3>, <7, 3>, <19, 1> ]
> CompositionFactors(CH);
    G
    |  Cyclic(3)
    *
    |  A(2, 7)                = L(3, 7)
    *
    |  Cyclic(2)
    1
```

<a id="univariate-polynomial"></a>
<a id="rngpol"></a>
## Univariate Polynomial Rings

- [Introduction](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/introduction.md)
  - [Representation](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/introduction.md#representation)
- [Creation Functions](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md)
  - [Creation of Structures](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#creation-of-structures)
    - [`PolynomialAlgebra(R): Rng → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-polynomialalgebra-rng)
    - [`PolynomialRing(R): Rng → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-polynomialring-rng)
    - [Example: Global and Non-Global Polynomial Rings](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#example-ex-2d4846)
  - [Print Options](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#print-options)
    - [`AssignNames(~P, s): RngUPol, [ MonStgElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#procedure-assignnames-rngupol-monstgelt-ref)
    - [`Name(P, i): RngUPol, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-name-rngupol-rngintelt)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#creation-of-elements)
    - [`P . 1: RngUPol, RngInt → RngPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#operation-operation-rngupol-rngint-rngpolelt)
    - [`elt< P | a₀, ..., a_d >: RngUPol, RngElt, ..., RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#constructor-constructor-elt-rngupol-rngelt-rngelt-rngupolelt)
    - [`P ! s: RngUPol, RngElt → RngPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#operation-op-rngupol-rngelt)
    - [`P ! s: RngUPol, [ RngElt ] → RngPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#operation-op-rngupol-rngelt-2)
    - [`elt< P | s >: RngUPol, [ RngElt ] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#constructor-constructor-elt-rngupol-rngelt-rngupolelt)
    - [`Polynomial(Q): [ RngElt ] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-polynomial-rngelt)
    - [`Polynomial(R, Q): Rng, [ RngElt] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-polynomial-rng-rngelt)
    - [`Polynomial(R, f): Rng, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-polynomial-rng-rngupolelt)
    - [`One(P): RngUPol → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-one-rngupol)
    - [`Identity(P): RngUPol → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-identity-rngupol)
    - [`Zero(P): RngUPol → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-zero-rngupol)
    - [`Representative(P): RngUPol → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#function-representative-rngupol)
    - [Example: Creating Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/creation.md#example-ex-365cfe)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#related-structures)
    - [`BaseRing(P): RngUPol → Rng`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-basering-rngupol)
    - [`CoefficientRing(P): RngUPol → Rng`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-coefficientring-rngupol)
    - [`CoefficientRing(f): RngUPolElt → Rng`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-coefficientring-rngupolelt)
    - [`Category(P): RngUPol → Cat`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-category-rngupol)
    - [`Parent(P): RngUPol → Pow`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-parent-rngupol)
    - [`PrimeRing(P): RngUPol → Rng`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-primering-rngupol)
  - [Changing Rings](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#changing-rings)
    - [`ChangeRing(P, S): RngUPol, Rng → RngUPol, Map`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-changering-rngupol-rng)
    - [`ChangeRing(P, S, f): RngUPol, Rng, Map → RngUPol, Map`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-changering-rngupol-rng-map)
    - [Example: Changing the Coefficient Ring](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#example-ex-332ea1)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#numerical-invariants)
    - [`Rank(P): RngUPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-rank-rngupol)
    - [`# P: RngUPolRes → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-operation-rngupolres-rngintelt)
    - [`Characteristic(P): RngUPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-characteristic-rngupol)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#ring-predicates-and-booleans)
    - [`IsCommutative(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-iscommutative-rngupol)
    - [`IsUnitary(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isunitary-rngupol)
    - [`IsFinite(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isfinite-rngupol)
    - [`IsOrdered(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isordered-rngupol)
    - [`IsField(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isfield-rngupol)
    - [`IsEuclideanDomain(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-iseuclideandomain-rngupol)
    - [`IsPID(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-ispid-rngupol)
    - [`IsUFD(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isufd-rngupol)
    - [`IsDivisionRing(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isdivisionring-rngupol)
    - [`IsEuclideanRing(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-iseuclideanring-rngupol)
    - [`IsDomain(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isdomain-rngupol)
    - [`IsPrincipalIdealRing(P): RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#function-isprincipalidealring-rngupol)
    - [`P eq Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-eq-rngupol-rngupol)
    - [`P ne Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-ne-rngupol-rngupol)
    - [`P lt Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-lt-rngupol-rngupol)
    - [`P gt Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-gt-rngupol-rngupol)
    - [`P le Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-le-rngupol-rngupol)
    - [`P ge Q: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#operation-op-ge-rngupol-rngupol)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#homomorphisms)
    - [`hom< P -> S | f, y >: RngUPol, Rng, Map, RngElt → Map`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#constructor-constructor-hom-rngupol-rng-map-rngelt-map)
    - [`hom< P -> S | y >: RngPol, Rng, RngElt → Map`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#constructor-constructor-hom-rngpol-rng-rngelt-map)
    - [Example: Homomorphism into the Real Field](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation.md#example-ex-c83216)
- [Element Operations](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md)
  - [Parent and Category](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#parent-and-category)
    - [`Parent(p): RngUPolElt → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-parent-rngupolelt)
    - [`Category(p): RngUPolElt → Cat`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-category-rngupolelt)
  - [Arithmetic Operators](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#arithmetic-operators)
    - [`+ a: RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-rngupolelt-rngupolelt)
    - [`- a: RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-rngupolelt-rngupolelt-2)
    - [`a + b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-plus-rngupolelt-rngupolelt)
    - [`a - b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-minus-rngupolelt-rngupolelt)
    - [`a * b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-times-rngupolelt-rngupolelt)
    - [`a ^ k: RngUPolElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-pow-rngupolelt-rngintelt)
    - [`a / b: RngUPolElt, RngElt → FldFunUElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-div-rngupolelt-rngelt)
    - [`a div b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-div-rngupolelt-rngupolelt-rngupolelt)
    - [`a mod b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-mod-rngupolelt-rngupolelt-rngupolelt)
    - [`a +:= b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-rngupolelt-rngupolelt-rngupolelt)
    - [`a -:= b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-rngupolelt-rngupolelt-rngupolelt-2)
    - [`a *:= b: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-rngupolelt-rngupolelt-rngupolelt-3)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#equality-and-membership)
    - [`a eq b: RngUPolElt, RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-eq-rngupolelt-rngupolelt)
    - [`a ne b: RngUPolElt, RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-ne-rngupolelt-rngupolelt)
    - [`a in R: RngUPolElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-in-rngupolelt-rng)
    - [`a notin R: RngUPolElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-notin-rngupolelt-rng)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#predicates-on-ring-elements)
    - [`IsZero(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-iszero-rngupolelt)
    - [`IsOne(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isone-rngupolelt)
    - [`IsMinusOne(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isminusone-rngupolelt)
    - [`IsNilpotent(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isnilpotent-rngupolelt)
    - [`IsIdempotent(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isidempotent-rngupolelt)
    - [`IsUnit(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isunit-rngupolelt)
    - [`IsZeroDivisor(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-iszerodivisor-rngupolelt)
    - [`IsRegular(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isregular-rngupolelt)
    - [`IsIrreducible(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isirreducible-rngupolelt)
    - [`IsPrime(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isprime-rngupolelt)
    - [`IsMonic(a): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-ismonic-rngupolelt)
  - [Coefficients and Terms](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#coefficients-and-terms)
    - [`Coefficients(p): RngUPolElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-coefficients-rngupolelt)
    - [`ElementToSequence(p): RngUPolElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-elementtosequence-rngupolelt)
    - [`Eltseq(p): RngUPolElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-eltseq-rngupolelt)
    - [`Coefficient(p, i): RngUPolElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-coefficient-rngupolelt-rngintelt)
    - [`MonomialCoefficient(p, m): RngUPolElt, RngUPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-monomialcoefficient-rngupolelt-rngupolelt)
    - [`LeadingCoefficient(p): RngUPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-leadingcoefficient-rngupolelt)
    - [`TrailingCoefficient(p): RngUPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-trailingcoefficient-rngupolelt)
    - [`ConstantCoefficient(p): RngUPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-constantcoefficient-rngupolelt)
    - [`Terms(p): RngUPolElt → [ RngUPolElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-terms-rngupolelt)
    - [`LeadingTerm(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-leadingterm-rngupolelt)
    - [`TrailingTerm(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-trailingterm-rngupolelt)
    - [`Monomials(p): RngUPolElt → SeqEnum`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-monomials-rngupolelt)
    - [`Support(p): RngUPolElt → [RngIntElt], [RngElt]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-support-rngupolelt)
    - [`Round(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-round-rngupolelt)
    - [`Valuation(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-valuation-rngupolelt)
  - [Degree](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#degree)
    - [`Degree(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-degree-rngupolelt)
  - [Roots](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#roots)
    - [`Roots(p): RngUPolElt → [ < RngElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-roots-rngupolelt)
    - [`Roots(p, S): RngUPolElt → [ < RngElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-roots-rngupolelt-2)
    - [`HasRoot(p): RngUPolElt → BoolElt, RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-hasroot-rngupolelt)
    - [`HasRoot(p, S): RngUPolElt, Rng → BoolElt, RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-hasroot-rngupolelt-rng)
    - [`SmallRoots(p, N, X): RngUPolElt, RngElt, RngElt → [RngElt]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-smallroots-rngupolelt-rngelt-rngelt)
    - [Example: Factoring an RSA Modulus with Small Roots](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#example-ex-2984f7)
    - [`SetVerbose("SmallRoots", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#procedure-setverbose-monstgelt-rngintelt-smallroots)
  - [Derivative, Integral](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#derivative-integral)
    - [`Derivative(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-derivative-rngupolelt)
    - [`Derivative(p, n): RngUPolElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-derivative-rngupolelt-rngintelt)
    - [`Integral(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-integral-rngupolelt)
  - [Evaluation, Interpolation](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#evaluation-interpolation)
    - [`Evaluate(p, r): RngUPolElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-evaluate-rngupolelt-rngelt)
    - [`Interpolation(I, V): [ RngElt ], [ RngElt ] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-interpolation-rngelt-rngelt)
  - [Decomposition](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#decomposition)
    - [`Decomposition(f): RngUPolElt → [[RngUPolElt]]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-decomposition-rngupolelt)
    - [Example: Polynomial Decomposition](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#example-ex-b0e795)
  - [Quotient and Remainder](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#quotient-and-remainder)
    - [`Quotrem(f, g): RngUPolElt, RngUPolElt → RngUPolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-quotrem-rngupolelt-rngupolelt)
    - [`f div g: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-div-rngupolelt-rngupolelt-rngupolelt-2)
    - [`IsDivisibleBy(f, g): RngUPolElt, RngUPolElt → BoolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-isdivisibleby-rngupolelt-rngupolelt)
    - [`ExactQuotient(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-exactquotient-rngupolelt-rngupolelt)
    - [`f mod g: RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-operation-mod-rngupolelt-rngupolelt-rngupolelt-2)
    - [`Valuation(f, g): RngUPolElt, RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-valuation-rngupolelt-rngupolelt)
    - [`Reductum(f): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-reductum-rngupolelt)
    - [`PseudoRemainder(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-pseudoremainder-rngupolelt-rngupolelt)
    - [`EuclideanNorm(p): RngUPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-euclideannorm-rngupol)
  - [Modular Arithmetic](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#modular-arithmetic)
    - [`Modexp(f, n, g): RngUPolElt, RngIntElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-modexp-rngupolelt-rngintelt-rngupolelt)
    - [`ChineseRemainderTheorem(X, M): [RngUPolElt], [RngUPolElt] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-chineseremaindertheorem-rngupolelt-rngupolelt)
    - [`CRT(X, M): [RngUPolElt], [RngUPolElt] → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-crt-rngupolelt-rngupolelt)
  - [Other Operations](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#other-operations)
    - [`ReciprocalPolynomial(f): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-reciprocalpolynomial-rngupolelt)
    - [`PowerPolynomial(f,n): RngUPolElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#function-powerpolynomial-rngupolelt-rngintelt)
    - [`f ^ M: RngUPolElt, Mtrx → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/operation-element.md#operation-op-pow-rngupolelt-mtrx)
- [Common Divisors and Common Multiples](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md)
  - [Common Divisors and Common Multiples](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#id1)
    - [`GreatestCommonDivisor(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-gcd)
    - [`Gcd(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-gcd-rngupolelt-rngupolelt)
    - [`GCD(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-gcd-rngupolelt-rngupolelt-2)
    - [`ExtendedGreatestCommonDivisor(f, g): RngUPolElt, RngUPolElt → RngUPolElt, RngUPolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-extendedgreatestcommondivisor-rngupolelt-rngupolelt)
    - [`Xgcd(f, g): RngUPolElt, RngUPolElt → RngUPolElt, RngUPolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-xgcd-rngupolelt-rngupolelt)
    - [`XGCD(f, g): RngUPolElt, RngUPolElt → RngUPolElt, RngUPolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-xgcd-rngupolelt-rngupolelt-2)
    - [`LeastCommonMultiple(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-leastcommonmultiple-rngupolelt-rngupolelt)
    - [`Lcm(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-lcm-rngupolelt-rngupolelt)
    - [`LCM(f, g): RngUPolElt, RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-lcm-rngupolelt-rngupolelt-2)
    - [`Normalize(f): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-normalize)
  - [Content and Primitive Part](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#content-and-primitive-part)
    - [`Content(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-content-rngupolelt)
    - [`PrimitivePart(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-primitivepart-rngupolelt)
    - [`ContentAndPrimitivePart(p): RngUPolElt → RngIntElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-contentandprimitivepart-rngupolelt)
    - [`Contpp(p): RngUPolElt → RngIntElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-contpp-rngupolelt)
- [Polynomials over the Integers](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md)
  - [`Sign(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-sign-rngupolelt)
  - [`AbsoluteValue(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-absolutevalue-rngupolelt)
  - [`Abs(p): RngUPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-abs-rngupolelt)
  - [`MaxNorm(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-maxnorm-rngupolelt)
  - [`SumNorm(p): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-sumnorm-rngupolelt)
  - [`DedekindTest(p, m): RngUPolElt, RngIntElt → Boolelt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/integer.md#function-dedekindtest-rngupolelt-rngintelt)
- [Polynomials over Finite Fields](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md)
  - [`PrimePolynomials(R, d): RngUPol, RngIntElt → SeqEnum[ RngUPolElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-primepolynomials-rngupol-rngintelt)
  - [`PrimePolynomials(R, d, n): RngUPol, RngIntElt, RngIntElt → SeqEnum[ RngUPolElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-primepolynomials-rngupol-rngintelt-rngintelt)
  - [`RandomPrimePolynomial(R, d): RngUPol, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-randomprimepolynomial-rngupol-rngintelt)
  - [`NumberOfPrimePolynomials(q, d): RngIntElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-numberofprimepolynomials-rngintelt-rngintelt)
  - [`NumberOfPrimePolynomials(K, d): FldFin, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-numberofprimepolynomials-fldfin-rngintelt)
  - [`NumberOfPrimePolynomials(R, d): RngUPol, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-numberofprimepolynomials-rngupol-rngintelt)
  - [`JacobiSymbol(a,b): RngUPol, RngUPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/finitefields.md#function-jacobisymbol-rngupol-rngupol)
- [Factorization](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md)
  - [Factorization and Irreducibility](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#factorization-and-irreducibility)
    - [`Factorization(f): RngUPolElt → [ < RngUPolElt, RngIntElt >], RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-vpoly-factorization)
    - [`Factorisation(f): RngUPolElt → [ < RngUPolElt, RngIntElt >], RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-factorisation-rngupolelt)
    - [`HasPolynomialFactorization(R): Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-haspolynomialfactorization-rng)
    - [`SetVerbose("PolyFact", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#procedure-setverbose-monstgelt-rngintelt-polyfact)
    - [`FactorisationToPolynomial(f): [Tup] → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-factorisationtopolynomial-tup)
    - [`Facpol(f): [Tup] → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-facpol-tup)
    - [Example: Factoring Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#example-ex-d3c652)
    - [`SquarefreeFactorization(f): RngUPolElt → [ <RngUPolElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-squarefreefactorization-rngupolelt)
    - [`DistinctDegreeFactorization(f): RngUPolElt → [ <RngIntElt, RngUPolElt> ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-distinctdegreefactorization-rngupolelt)
    - [`EqualDegreeFactorization(f, d, g): RngUPolElt, RngIntElt, RngUPolElt → [ RngUPolElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-equaldegreefactorization-rngupolelt-rngintelt-rngupolelt)
    - [`IsIrreducible(f): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-isirreducible-rngupolelt-2)
    - [`IsSeparable(f): RngUPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-isseparable-rngupolelt)
    - [`QMatrix(f): RngUPolElt → AlgMatElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-qmatrix-rngupolelt)
  - [Sylvester Matrix, Resultant, and Discriminant](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#sylvester-matrix-resultant-and-discriminant)
    - [`SylvesterMatrix(f, g): RngUPolElt, RngUPolElt → Mtrx`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-sylvestermatrix-rngupolelt-rngupolelt)
    - [`Resultant(f, g): RngUPolElt, RngUPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-resultant-rngupolelt-rngupolelt)
    - [`Discriminant(f): RngUPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-discriminant-rngupolelt)
    - [`CompanionMatrix(f): RngUPolElt → AlgMatElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-companionmatrix-rngupolelt)
  - [Hensel Lifting](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#hensel-lifting)
    - [`HenselLift(f, s, P): RngUPolElt, [ RngUPolElt ], RngUPol → [ RngUPolElt ]`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-hensellift-rngupolelt-rngupolelt-rngupol)
    - [Example: Hensel Lifting](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#example-ex-4d71ca)
- [Ideals and Quotient Rings](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md)
  - [Creation of Ideals and Quotients](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#creation-of-ideals-and-quotients)
    - [`ideal< R | a₁, ..., aᵣ >: RngUPol, RngUPolElt, ..., RngUPolElt → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#constructor-constructor-ideal-rngupol-rngupolelt-rngupolelt-rngupol)
    - [`quo< R | I >: RngUPol, RngUPol → RngUPolRes`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#constructor-constructor-quo-rngupol-rngupol-rngupolres)
    - [`quo< R | a₁, ..., aᵣ >: RngUPol, RngUPolElt, ..., RngUPolElt → RngUPolRes, Map`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#constructor-constructor-quo-rngupol-rngupolelt-rngupolelt-rngupolres-map)
  - [Ideal Arithmetic](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#ideal-arithmetic)
    - [`I + J: RngUPol, RngUPol → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-plus-rngupol-rngupol)
    - [`I * J: RngUPol, RngUPol → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-times-rngupol-rngupol)
    - [`I meet J: RngUPol, RngUPol → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-meet-rngupol-rngupol)
    - [`a in I: RngUPolElt, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-in-rngupolelt-rngupol)
    - [`a notin I: RngUPolElt, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-notin-rngupolelt-rngupol)
    - [`I eq J: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-eq-rngupol-rngupol-2)
    - [`I ne J: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-ne-rngupol-rngupol-2)
    - [`I subset J: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-op-subset-rngupol-rngupol)
    - [`I notsubset J: RngUPol, RngUPol → BoolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-operation-notsubset-rngupol-rngupol-boolelt)
  - [Other Functions on Ideals](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#other-functions-on-ideals)
    - [`I . 1: RngUPol → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#operation-operation-rngupol-rngupolelt)
  - [Other Functions on Quotients](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#other-functions-on-quotients)
    - [`Modulus(Q): RngUPolRes → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#function-modulus-rngupolres)
    - [`PreimageRing(Q): RngUPolRes → RngUPol`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/ideal-quotient.md#function-preimagering-rngupolres)
- [Special Families of Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md)
  - [Orthogonal Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#orthogonal-polynomials)
    - [`ChebyshevFirst(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-chebyshevfirst-rngintelt)
    - [`ChebyshevT(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-chebyshevt-rngintelt)
    - [`ChebyshevSecond(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-chebyshevsecond-rngintelt)
    - [`ChebyshevU(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-chebyshevu-rngintelt)
    - [`LegendrePolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-legendrepolynomial-rngintelt)
    - [`LaguerrePolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-laguerrepolynomial-rngintelt)
    - [`LaguerrePolynomial(n, m): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-laguerrepolynomial-rngintelt-rngelt)
    - [`HermitePolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-hermitepolynomial-rngintelt)
    - [`GegenbauerPolynomial(n, m): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-gegenbauerpolynomial-rngintelt-rngelt)
  - [Permutation Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#permutation-polynomials)
    - [`DicksonFirst(n, a): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-dicksonfirst-rngintelt-rngelt)
    - [`DicksonSecond(n, a): RngIntElt, RngElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-dicksonsecond-rngintelt-rngelt)
  - [The Bernoulli Polynomial](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#the-bernoulli-polynomial)
    - [`BernoulliPolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-bernoullipolynomial-rngintelt)
  - [Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#swinnerton-dyer-polynomials)
    - [`SwinnertonDyerPolynomial(n): RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/families-polynomials.md#function-swinnertondyerpolynomial-rngintelt)
- [Bibliography](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/bibliography.md)

### Introduction

Univariate polynomial rings may be defined over any ring $R$. Let us denote the univariate polynomial ring in indeterminate $x$ over the coefficient ring $R$ by $P=R[x]$. There are two kinds of polynomials in Magma: *univariate* polynomials, represented as vectors of coefficients; and *multivariate polynomials* represented in distributive form (linear sums of coefficient-monomial pairs). In this chapter we discuss univariate polynomials.

#### Representation

The vector representation enables fast arithmetic on univariate polynomials, but it requires considerable amounts of memory for multivariate polynomials; therefore, only univariate polynomial rings using the vector representation can be created directly (but, if one insists, it is possible to create univariate polynomial rings over univariate polynomial rings, etc.). Multivariate polynomials can be stored efficiently in distributive form, but the arithmetic operations on polynomials of one variable stored in this way may be considerably slower.

### Creation Functions

#### Creation of Structures

There are two different ways to create polynomial rings, corresponding to the different internal representations (vector versus distributive — see the introductory section): `PolynomialRing(R)` and `PolynomialRing(R, n)`. The latter should be used to create multivariate polynomials; the former should be used for univariate polynomials.

<a id="function-polynomialalgebra-rng"></a>
##### `PolynomialAlgebra(R): Rng -> RngUPol`

<a id="function-polynomialring-rng"></a>
##### `PolynomialRing(R): Rng -> RngUPol`

```magma
Global: BoolElt                    Default: true
```

Create a univariate polynomial ring over the ring $R$. The ring is regarded as an $R$-algebra via the usual identification of elements of $R$ and the constant polynomials. The polynomials are stored in vector form, which allows fast arithmetic. It is not recommended to use this function recursively to build multivariate polynomial rings. The angle bracket notation can be used to assign names to the indeterminate, e.g.: `P<x> := PolynomialRing(R)`. By default, the unique *global* univariate polynomial ring over $R$ will be returned; if the parameter `Global` is set to `false`, then a non-global univariate polynomial ring over $R$ will be returned (to which a separate name for the indeterminate can be assigned).

<a id="example-ex-2d4846"></a>
##### `Example: Global and Non-Global Polynomial Rings (ex-2d4846)`

We demonstrate the difference between global and non-global rings. We first create the global univariate polynomial ring over ${\mathbb{Q}}$ twice.

```magma
> Q := RationalField();
> P<x> := PolynomialRing(Q);
> PP := PolynomialRing(Q);
> P;
Univariate Polynomial Ring in x over Rational Field
> PP;
Univariate Polynomial Ring in x over Rational Field
> PP.1;
x
```

$PP$ is identical to $P$. We now create non-global univariate polynomial rings (which are also different to the global polynomial ring $P$). Note that elements of all the rings are mathematically equal by automatic coercion.

```magma
> Pa<a> := PolynomialRing(Q: Global := false);
> Pb<b> := PolynomialRing(Q: Global := false);
> Pa;
Univariate Polynomial Ring in a over Rational Field
> Pb;
Univariate Polynomial Ring in b over Rational Field
> a;
a
> b;
b
> P;
Univariate Polynomial Ring in x over Rational Field
> x;
x
> x eq a; // Automatic coercion
true
> x + a;
2*x
```

#### Print Options

The `AssignNames` and `Name` functions can be used to associate a name with the indeterminate of a polynomial ring after creation.

<a id="procedure-assignnames-rngupol-monstgelt-ref"></a>
##### `AssignNames(~P, s): RngUPol, [ MonStgElt ]`

Procedure to change the name of the indeterminate of a polynomial ring $P$. The indeterminate will be given the name of the string in the sequence $s$. This procedure only changes the name used in printing the elements of $P$. It does *not* assign to identifiers corresponding to the strings the indeterminates in $P$; to do this, use an assignment statement, or use angle brackets when creating the field. Note that since this is a procedure that modifies $P$, it is necessary to have a reference `~P` to $P$ in the call to this function.

<a id="function-name-rngupol-rngintelt"></a>
##### `Name(P, i): RngUPol, RngIntElt -> RngUPolElt`

Given a polynomial ring $P$, return the $i$-th indeterminate of $P$ (as an element of $P$).

#### Creation of Elements

The easiest way to create polynomials in a given ring is to use the angle bracket construction to attach names to the indeterminates, and to use these names to express polynomials (see the examples). Below we list other options.

<a id="operation-operation-rngupol-rngint-rngpolelt"></a>
##### `P . 1: RngUPol, RngInt -> RngPolElt`

Return the indeterminate for the polynomial ring $P$, as an element of $P$.

<a id="constructor-constructor-elt-rngupol-rngelt-rngelt-rngupolelt"></a>
##### `elt< P | a₀, ..., a_d >: RngUPol, RngElt, ..., RngElt -> RngUPolElt`

Given a polynomial ring $P=R[x]$ and elements $a_0, \ldots, a_d$ coercible into the coefficient ring $R$, return the polynomial $a_0+a_1x_n+\cdots+a_dx_n^d$ as an element of $P$.

<a id="operation-op-rngupol-rngelt"></a>
##### `P ! s: RngUPol, RngElt -> RngPolElt`

<a id="operation-op-rngupol-rngelt-2"></a>
##### `P ! s: RngUPol, [ RngElt ] -> RngPolElt`

<a id="constructor-constructor-elt-rngupol-rngelt-rngupolelt"></a>
##### `elt< P | s >: RngUPol, [ RngElt ] -> RngUPolElt`

Coerce the element $s$ into the polynomial ring $P = R[x]$. The following possibilities for $s$ exist.

**(a)**
$s$ is an element of $P$: it is returned unchanged;

**(b)**
$s$ is an element of a ring that can be coerced into the coefficient ring $R$ of $P$: the constant polynomial $s$ is returned;

**(c)**
$s=\sum_j s_jy^j$ is an element of a univariate polynomial ring whose coefficient ring elements $s_j$ can be coerced into $R$: the polynomial $\sum_j r_jx^j$ is returned, where $r_j$ is the result of coercing $s_j$ into $R$;

**(c)**
$s$ is a sequence: if $s$ is empty then the zero element of $P$ is returned, and if it is non-empty but the elements of the sequence can be coerced into $R$ then the polynomial $\sum_j s[j]x_n^{j-1}$ is returned.

Note that constant polynomials may be coerced into their coefficient rings.

<a id="function-polynomial-rngelt"></a>
##### `Polynomial(Q): [ RngElt ] -> RngUPolElt`

Given a sequence $Q$ of elements from a ring $R$, create the polynomial over $R$ whose coefficients are given by $Q$. This is equivalent to `PolynomialRing(Universe(Q))!Q`.

<a id="function-polynomial-rng-rngelt"></a>
##### `Polynomial(R, Q): Rng, [ RngElt] -> RngUPolElt`

Given a ring $R$ and sequence $Q$ of elements from a ring $S$, create the polynomial over $R$ whose coefficients are given by the elements of $Q$, coerced into $S$. This is equivalent to `PolynomialRing(R)!ChangeUniverse(Q, R)`.

<a id="function-polynomial-rng-rngupolelt"></a>
##### `Polynomial(R, f): Rng, RngUPolElt -> RngUPolElt`

Given a ring $R$ and a polynomial $f$ over a ring $S$, create the polynomial over $R$ obtained from $f$ by coercing its coefficients into $S$. This is equivalent to `PolynomialRing(R)!f`.

<a id="function-one-rngupol"></a>
##### `One(P): RngUPol -> RngUPolElt`

<a id="function-identity-rngupol"></a>
##### `Identity(P): RngUPol -> RngUPolElt`

<a id="function-zero-rngupol"></a>
##### `Zero(P): RngUPol -> RngUPolElt`

<a id="function-representative-rngupol"></a>
##### `Representative(P): RngUPol -> RngUPolElt`

<a id="example-ex-365cfe"></a>
##### `Example: Creating Polynomials (ex-365cfe)`

The easiest way to create the polynomial $x^3+3x+1$ (over the integers) is as follows.

```magma
> P<x> := PolynomialRing(Integers());
> f := x^3+3*x+1;
> f;
x^3 + 3*x + 1
```

Alternative ways to create polynomials are given by the element constructor (rarely used) and the `!` operator:

```magma
> P<x> := PolynomialAlgebra(Integers());
> f := elt< P | 2, 3, 0, 1 >;
> f;
x^3 + 3*x + 2
> P ! [ 2, 3, 0, 1 ];
x^3 + 3*x + 2
```

Note that it is important to realize that a sequence is coerced into a polynomial ring by coercing its entries into the coefficient ring, and it is not attempted first to coerce the sequence as a whole into the coefficient ring:

```magma
> Q := RationalField();
> Q ! [1, 2];
1/2
> P<x> := PolynomialRing(Q);
> P ! [1,2];
2*x + 1
> P ! Q ! [1,2];
1/2
> P ! [ [1,2], [2,3] ];
2/3*x + 1/2
```

### Structure Operations

#### Related Structures

The main structure related to a polynomial ring is its coefficient ring. Univariate polynomial rings belong to the Magma category `RngUPol`.

<a id="function-basering-rngupol"></a>
##### `BaseRing(P): RngUPol -> Rng`

<a id="function-coefficientring-rngupol"></a>
##### `CoefficientRing(P): RngUPol -> Rng`

<a id="function-coefficientring-rngupolelt"></a>
##### `CoefficientRing(f): RngUPolElt -> Rng`

Return the coefficient ring of polynomial ring $P$ (the parent of $f$).

<a id="function-category-rngupol"></a>
##### `Category(P): RngUPol -> Cat`

<a id="function-parent-rngupol"></a>
##### `Parent(P): RngUPol -> Pow`

<a id="function-primering-rngupol"></a>
##### `PrimeRing(P): RngUPol -> Rng`

#### Changing Rings

The `ChangeRing` function enables changing coefficient rings on a polynomial ring.

<a id="function-changering-rngupol-rng"></a>
##### `ChangeRing(P, S): RngUPol, Rng -> RngUPol, Map`

Given a polynomial ring $P=R[x]$, together with a ring $S$, construct the polynomial ring $Q=S[y]$, together with the homomorphism $h$ from $P$ to $Q$. It is necessary that all elements of the old coefficient ring $R$ can be automatically coerced into the new coefficient ring $S$. The homomorphism $h$ will apply this coercion to the coefficients of elements in $P$ to return elements of $Q$. The usual angle bracket notation can be used for indeterminate names on the result.

<a id="function-changering-rngupol-rng-map"></a>
##### `ChangeRing(P, S, f): RngUPol, Rng, Map -> RngUPol, Map`

Given a polynomial ring $P=R[x]$, together with a ring $S$ and a map $f\colon R\rightarrow S$, construct the polynomial ring $Q=S[y]$ together with the homomorphism $h$ from $P$ to $Q$ obtained by applying $h$ to the coefficients of elements of $P$. The usual angle bracket notation can be used for indeterminate names on the result.

<a id="example-ex-332ea1"></a>
##### `Example: Changing the Coefficient Ring (ex-332ea1)`

In the first example of `ChangeRing` below we use automatic coercion of integers to rationals to go from ${\mathbb{Z}}[x]$ to ${\mathbb{Q}}[y]$. In fact `!` can be used for this as well. In the second example we use a map to obtain a non-standard embedding (not mapping $1$ to $1$) of ${\mathbb{Z}}$ in ${\mathbb{Q}}$.

```magma
> Z := Integers();
> Q := RationalField();
> P<x> := PolynomialRing(Z);
> S<y>, h := ChangeRing(P, Q);
> h(x^3-2*x+5);
y^3 - 2*y + 5
> S ! (x^3-2*x+5);
y^3 - 2*y + 5
> m := hom< Z -> Q | x :-> 3*x >;
> S<y>, h := ChangeRing(P, Q, m);
> h(x^3-2*x+5);
3*y^3 - 6*y + 15
```

#### Numerical Invariants

The characteristic can be obtained for any polynomial ring, the rank for free polynomial rings, and the cardinality only for finite quotients.

<a id="function-rank-rngupol"></a>
##### `Rank(P): RngUPol -> RngIntElt`

Return the rank of the polynomial ring $P$, defined as the maximal number of independent indeterminates in $P$ over its coefficient ring; for univariate polynomial rings this will therefore always return $1$.

<a id="operation-operation-rngupolres-rngintelt"></a>
##### `# P: RngUPolRes -> RngIntElt`

Return the number of elements of $P$; this will only return an integer value if $P$ is finite, which for polynomial rings can only happen for quotients of polynomial rings over finite coefficient rings.

<a id="function-characteristic-rngupol"></a>
##### `Characteristic(P): RngUPol -> RngIntElt`

#### Ring Predicates and Booleans

The usual ring functions returning Boolean values are available on polynomial rings.

<a id="function-iscommutative-rngupol"></a>
##### `IsCommutative(P): RngUPol -> BoolElt`

<a id="function-isunitary-rngupol"></a>
##### `IsUnitary(P): RngUPol -> BoolElt`

<a id="function-isfinite-rngupol"></a>
##### `IsFinite(P): RngUPol -> BoolElt`

<a id="function-isordered-rngupol"></a>
##### `IsOrdered(P): RngUPol -> BoolElt`

<a id="function-isfield-rngupol"></a>
##### `IsField(P): RngUPol -> BoolElt`

<a id="function-iseuclideandomain-rngupol"></a>
##### `IsEuclideanDomain(P): RngUPol -> BoolElt`

<a id="function-ispid-rngupol"></a>
##### `IsPID(P): RngUPol -> BoolElt`

<a id="function-isufd-rngupol"></a>
##### `IsUFD(P): RngUPol -> BoolElt`

<a id="function-isdivisionring-rngupol"></a>
##### `IsDivisionRing(P): RngUPol -> BoolElt`

<a id="function-iseuclideanring-rngupol"></a>
##### `IsEuclideanRing(P): RngUPol -> BoolElt`

<a id="function-isdomain-rngupol"></a>
##### `IsDomain(P): RngUPol -> BoolElt`

<a id="function-isprincipalidealring-rngupol"></a>
##### `IsPrincipalIdealRing(P): RngUPol -> BoolElt`

<a id="operation-op-eq-rngupol-rngupol"></a>
##### `P eq Q: RngUPol, RngUPol -> BoolElt`

<a id="operation-op-ne-rngupol-rngupol"></a>
##### `P ne Q: RngUPol, RngUPol -> BoolElt`

<a id="operation-op-lt-rngupol-rngupol"></a>
##### `P lt Q: RngUPol, RngUPol -> BoolElt`

<a id="operation-op-gt-rngupol-rngupol"></a>
##### `P gt Q: RngUPol, RngUPol -> BoolElt`

<a id="operation-op-le-rngupol-rngupol"></a>
##### `P le Q: RngUPol, RngUPol -> BoolElt`

<a id="operation-op-ge-rngupol-rngupol"></a>
##### `P ge Q: RngUPol, RngUPol -> BoolElt`

#### Homomorphisms

A ring homomorphism taking a polynomial ring $R[x]$ as its domain requires $2$ pieces of information, namely, a map (homomorphism) telling how to map the coefficient ring $R$, together with the image of the indeterminate $x$. The map may be omitted.

<a id="constructor-constructor-hom-rngupol-rng-map-rngelt-map"></a>
##### `hom< P -> S | f, y >: RngUPol, Rng, Map, RngElt -> Map`

<a id="constructor-constructor-hom-rngpol-rng-rngelt-map"></a>
##### `hom< P -> S | y >: RngPol, Rng, RngElt -> Map`

Given a polynomial ring $P=R[x]$, a ring $S$, a map $f : R\ar S$, and an element $y\in S$, create the homomorphism $g : P\ar S$ given by that $g(\sum s_ix^i)=\sum f(s_i)y^{i}$. The coefficient ring map may be omitted, in which case the coefficients are mapped into $S$ by the unitary homomorphism sending $1_R$ to $1_S$. Also, the image $y$ is allowed to be from a structure that allows automatic coercion into $S$.

<a id="example-ex-c83216"></a>
##### `Example: Homomorphism into the Real Field (ex-c83216)`

In this example we map ${\mathbb{Z}}[x]$ into the reals by sending $x$ to $1/2$. Note that we do not have a choice for the coefficient map (since we require it to be unitary), and also that we give the image of $x$ as a rational number that is automatically coerced into the reals.

```magma
> Z := Integers();
> P<x> := PolynomialRing(Z);
> Re := RealField(20);
> half := hom< P -> Re | 1/2 >;
> half(x^3-3*x+5);
3.625
```

### Element Operations

The categories for elements in univariate polynomial rings and their quotients are `RngUPolElt` and `RngUPolResElt`

#### Parent and Category

<a id="function-parent-rngupolelt"></a>
##### `Parent(p): RngUPolElt -> RngUPol`

<a id="function-category-rngupolelt"></a>
##### `Category(p): RngUPolElt -> Cat`

#### Arithmetic Operators

The usual unary and binary ring operations are available for univariate polynomials, with the following notable restrictions. Since inverses cannot generally be obtained in polynomial rings, division (using `/`) of polynomials is not allowed, and neither are negative powers. For polynomial rings over fields division by elements of the coefficient field are allowed. The operators `div` and `mod` give results corresponding to the quotient and the remainder of division of the arguments. See the section on quotient and remainder for details.

<a id="operation-operation-rngupolelt-rngupolelt"></a>
##### `+ a: RngUPolElt -> RngUPolElt`

<a id="operation-operation-rngupolelt-rngupolelt-2"></a>
##### `- a: RngUPolElt -> RngUPolElt`

<a id="operation-op-plus-rngupolelt-rngupolelt"></a>
##### `a + b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-op-minus-rngupolelt-rngupolelt"></a>
##### `a - b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-op-times-rngupolelt-rngupolelt"></a>
##### `a * b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-op-pow-rngupolelt-rngintelt"></a>
##### `a ^ k: RngUPolElt, RngIntElt -> RngUPolElt`

<a id="operation-op-div-rngupolelt-rngelt"></a>
##### `a / b: RngUPolElt, RngElt -> FldFunUElt`

<a id="operation-operation-div-rngupolelt-rngupolelt-rngupolelt"></a>
##### `a div b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-operation-mod-rngupolelt-rngupolelt-rngupolelt"></a>
##### `a mod b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-operation-rngupolelt-rngupolelt-rngupolelt"></a>
##### `a +:= b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-operation-rngupolelt-rngupolelt-rngupolelt-2"></a>
##### `a -:= b: RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="operation-operation-rngupolelt-rngupolelt-rngupolelt-3"></a>
##### `a *:= b: RngUPolElt, RngUPolElt -> RngUPolElt`

#### Equality and Membership

<a id="operation-op-eq-rngupolelt-rngupolelt"></a>
##### `a eq b: RngUPolElt, RngUPolElt -> BoolElt`

<a id="operation-op-ne-rngupolelt-rngupolelt"></a>
##### `a ne b: RngUPolElt, RngUPolElt -> BoolElt`

<a id="operation-op-in-rngupolelt-rng"></a>
##### `a in R: RngUPolElt, Rng -> BoolElt`

<a id="operation-op-notin-rngupolelt-rng"></a>
##### `a notin R: RngUPolElt, Rng -> BoolElt`

#### Predicates on Ring Elements

The list belows contains the general ring element predicates. Note that not all functions are available for every coefficient ring.

<a id="function-iszero-rngupolelt"></a>
##### `IsZero(a): RngUPolElt -> BoolElt`

<a id="function-isone-rngupolelt"></a>
##### `IsOne(a): RngUPolElt -> BoolElt`

<a id="function-isminusone-rngupolelt"></a>
##### `IsMinusOne(a): RngUPolElt -> BoolElt`

<a id="function-isnilpotent-rngupolelt"></a>
##### `IsNilpotent(a): RngUPolElt -> BoolElt`

<a id="function-isidempotent-rngupolelt"></a>
##### `IsIdempotent(a): RngUPolElt -> BoolElt`

<a id="function-isunit-rngupolelt"></a>
##### `IsUnit(a): RngUPolElt -> BoolElt`

<a id="function-iszerodivisor-rngupolelt"></a>
##### `IsZeroDivisor(a): RngUPolElt -> BoolElt`

<a id="function-isregular-rngupolelt"></a>
##### `IsRegular(a): RngUPolElt -> BoolElt`

<a id="function-isirreducible-rngupolelt"></a>
##### `IsIrreducible(a): RngUPolElt -> BoolElt`

<a id="function-isprime-rngupolelt"></a>
##### `IsPrime(a): RngUPolElt -> BoolElt`

<a id="function-ismonic-rngupolelt"></a>
##### `IsMonic(a): RngUPolElt -> BoolElt`

#### Coefficients and Terms

<a id="function-coefficients-rngupolelt"></a>
##### `Coefficients(p): RngUPolElt -> [ RngElt ]`

<a id="function-elementtosequence-rngupolelt"></a>
##### `ElementToSequence(p): RngUPolElt -> [ RngElt ]`

<a id="function-eltseq-rngupolelt"></a>
##### `Eltseq(p): RngUPolElt -> [ RngElt ]`

The coefficients of the polynomial $p\in R[x]$ in ascending order, as a sequence of elements of $R$.

<a id="function-coefficient-rngupolelt-rngintelt"></a>
##### `Coefficient(p, i): RngUPolElt, RngIntElt -> RngElt`

Given a polynomial $p\in R[x]$ and an integer $i\geq 0$, return the coefficient of the $i$-th power of $x$ in $f$. (If $i$ exceeds the degree of $f$ then zero is returned.) The return value is an element of $R$.

<a id="function-monomialcoefficient-rngupolelt-rngupolelt"></a>
##### `MonomialCoefficient(p, m): RngUPolElt, RngUPolElt -> RngElt`

Given elements $p$ and $m$ of a polynomial ring $P=R[x]$, where $m$ is a monomial (that is, has exactly one non-zero base coefficient, which must be $1$), return the coefficient of $m$ in $p$, as an element of the coefficient ring $R$.

<a id="function-leadingcoefficient-rngupolelt"></a>
##### `LeadingCoefficient(p): RngUPolElt -> RngElt`

Return the coefficient of the highest occurring power of $x$ in $p\in R[x]$, as an element of the coefficient ring $R$.

<a id="function-trailingcoefficient-rngupolelt"></a>
##### `TrailingCoefficient(p): RngUPolElt -> RngElt`

Return the coefficient of the lowest occurring power of $x$ in $p\in R[x]$, as an element of the coefficient ring $R$.

<a id="function-constantcoefficient-rngupolelt"></a>
##### `ConstantCoefficient(p): RngUPolElt -> RngElt`

Return the constant term, i.e., the coefficient of $x^0$ as an element of the coefficient ring $R$.

<a id="function-terms-rngupolelt"></a>
##### `Terms(p): RngUPolElt -> [ RngUPolElt ]`

Return the non-zero terms of the polynomial $p\in P=R[x]$ in ascending order with respect to the degree, as a sequence of elements of $P$ with ascending degrees.

<a id="function-leadingterm-rngupolelt"></a>
##### `LeadingTerm(p): RngUPolElt -> RngUPolElt`

Return the term of $p\in P= R[x]$ with the highest occurring power of $x$, as an element of $P$. The coefficient of the result will be the leading coefficient of $p$.

<a id="function-trailingterm-rngupolelt"></a>
##### `TrailingTerm(p): RngUPolElt -> RngUPolElt`

Return the term of $p\in P= R[x]$ with the lowest occurring power of $x$, as an element of $P$. The coefficient of the result will be the trailing coefficient of $p$.

<a id="function-monomials-rngupolelt"></a>
##### `Monomials(p): RngUPolElt -> SeqEnum`

The monomials of the univariate $p$, matching up with `Coefficients(p)`, that is a sequence of powers of the indeterminate up to the degree of $p$.

<a id="function-support-rngupolelt"></a>
##### `Support(p): RngUPolElt -> [RngIntElt], [RngElt]`

Given a polynomial $p\in R[x]$, return the positions in $p$ for which there are non-zero coefficients, and the corresponding coefficients.

<a id="function-round-rngupolelt"></a>
##### `Round(p): RngUPolElt -> RngUPolElt`

Given a polynomial $p\in P= R[x]$ where $R$ is a subring of the real field (the ring of integers ${\mathbb{Z}}$, the rational field ${\mathbb{Q}}$, or a real field), return the polynomial in $Z[x]$ obtained from $p$ by rounding all the coefficients of $p$.

<a id="function-valuation-rngupolelt"></a>
##### `Valuation(p): RngUPolElt -> RngIntElt`

The valuation of a polynomial $p \in R[x]$, that is, the exponent of the largest power of $x$ which divides $p$. Note that the zero polynomial has valuation $\infty$.

#### Degree

<a id="function-degree-rngupolelt"></a>
##### `Degree(p): RngUPolElt -> RngIntElt`

The degree of a polynomial $p \in R[x]$, that is, the exponent of the largest power of $x$ that occurs with non-zero coefficient. Note that the zero polynomial has degree $-1$.

#### Roots

<a id="function-roots-rngupolelt"></a>
##### `Roots(p): RngUPolElt -> [ < RngElt, RngIntElt> ]`

```magma
Max: RngIntElt                    Default: 
```

Given a polynomial $p$ over one of a certain collection of coefficient rings, this function returns a sorted sequence of pairs of coefficient ring element and integer, where the ring element is a root of $p$ in the coefficient ring, and the integer its multiplicity. Currently the coefficient rings that are allowed comprise complex and real fields, integers and rationals, finite fields and residue class rings with prime modulus. If the parameter `Max` is set to a non-negative number $m$, at most $m$ roots are returned.

<a id="function-roots-rngupolelt-2"></a>
##### `Roots(p, S): RngUPolElt -> [ < RngElt, RngIntElt> ]`

Given a polynomial $p$ over one of a certain collection of coefficient rings as well as a ring $S$ into which the coefficients of $p$ can be coerced automatically, this function returns a sorted sequence of pairs of ring element and integer, where the ring element is a root of $p$ in the ring $S$, and the integer its multiplicity. Currently the coefficient rings that are allowed comprise complex and real fields, integers and rationals, finite fields and residue class rings with prime modulus.

<a id="function-hasroot-rngupolelt"></a>
##### `HasRoot(p): RngUPolElt -> BoolElt, RngElt`

Given a polynomial $p$ over the coefficient ring $R$ this function returns `true` iff $p$ has a root in $R$. If the result is `true`, the function also returns a root of $p$ as a second return value. Currently the coefficient rings that are allowed comprise complex and real fields, integers and rationals, finite fields and residue class rings with prime modulus. Note that particularly for finite fields, this method may be much faster than the computation of all roots of the polynomial.

<a id="function-hasroot-rngupolelt-rng"></a>
##### `HasRoot(p, S): RngUPolElt, Rng -> BoolElt, RngElt`

Given a polynomial $p$ over the coefficient ring $R$ and a ring $S$ which contains $R$, this function returns `true` iff $p$ has a root in $S$. If the result is `true`, the function also returns a root of $p$ in $S$ as a second return value. Currently the coefficient rings that are allowed comprise complex and real fields, integers and rationals, finite fields and residue class rings with prime modulus. Note that particularly for finite fields, this method may be much faster than the computation of all roots of the polynomial.

<a id="function-smallroots-rngupolelt-rngelt-rngelt"></a>
##### `SmallRoots(p, N, X): RngUPolElt, RngElt, RngElt -> [RngElt]`

```magma
Bits       : BoolElt                      Default: false
Beta       : FldReElt                     Default: 1.0
Exponent   : RngIntElt                    Default: 
Finalshifts: RngIntElt                    Default: 
Direct     : BoolElt                      Default: false
```

Given a monic non-zero univariate integer polynomial $p$ and two positive integers $N$ and $X$, this function returns all $x_0$’s such that $|x_0| \leq X$ and $P(x_0)=0 \  [N]$, as long as $X \leq 0.5 \cdot N^{1/d}$, where $d$ is the degree of $p$. This function implements Coppersmith’s algorithm to compute the small roots of a univariate polynomial modulo an integer [[Cop96](https://docs.magma-maths.org/references.md#cite-coppersmith96)], as described in Alexander May’s PhD thesis [[May03](https://docs.magma-maths.org/references.md#cite-may03)]. It relies upon the LLL algorithm for reducing euclidean lattices [[LLL82](https://docs.magma-maths.org/references.md#cite-lll)]. It is frequently used for cryptanalysing public-key cryptosystems (see the example below).

When `Bits` is set to `true`, the input $X$ is read as $2^X$. The parameter `Beta` can be set to any value in $(0.0, 1.0]$. The routine will then find all $x_0$’s such that $|x_0| \leq X$ and $P(x_0)=0 \cong N'$, as long as $X \leq 0.5 \cdot N^{\beta^2/d}$, where $d$ is the degree of $p$ and $N'\geq N^{\beta}$ is any divisor of $N$. The `Exponent` and `Finalshifts` specify the shape of the lattice basis to be reduced. If `Exponent` is $m$, then $p^m$ will be the highest power of $p$ used to build the lattice basis, and if `Finalshifts` is $t$, $t$ shifts of $p^m$ will be used. Unless requested by the user, these parameters are chosen automatically. Finally, the `Direct` option allows the user to require the lattice basis to be reduced at once, and not progressively while constructed. This is can be slower.

<a id="example-ex-2984f7"></a>
##### `Example: Factoring an RSA Modulus with Small Roots (ex-2984f7)`

We show how to use the `SmallRoots` routine to factor an RSA modulus when some most significant bits of one of the factors is known. We first generate an RSA modulus.

```magma
> SetSeed(1);
> F<x> := PolynomialRing (Integers());
> length := 1024;
> p:=NextPrime (2^(Round(length/2)): Proof:=false);
> pi:=Pi(RealField());
> q:=NextPrime (Round (pi*p): Proof:=false);
> N := p*q;
```

Suppose that $N$ is known, as well as an approximation of the factor $q$:

```magma
> hidden:=220;
> approxq := q+Random(2^hidden-1);
```

Our goal is to recover `q` from our knowledge of `approxq`. We are therefore interested in the small roots of the polynomial $x-approxq$ modulo $q$, whose multiple $N$ is known.

```magma
> A:=x-approxq;
> time perturb:=SmallRoots (A, N, hidden : Bits, Beta:=0.5)[1];
Time 0.050
> q eq approxq-perturb;
true
```

<a id="procedure-setverbose-monstgelt-rngintelt-smallroots"></a>
##### `SetVerbose("SmallRoots", v): MonStgElt, RngIntElt`

(Procedure.) Set the verbose printing level for the `SmallRoots` routine to be $v$. Currently the legal values for $v$ are `true`, `false`, 0, 1, or 2 (`false` is the same as 0, and `true` is the same as 1).

#### Derivative, Integral

<a id="function-derivative-rngupolelt"></a>
##### `Derivative(p): RngUPolElt -> RngUPolElt`

Given a polynomial $p\in P$, return the derivative of $p$ as an element of $P$.

<a id="function-derivative-rngupolelt-rngintelt"></a>
##### `Derivative(p, n): RngUPolElt, RngIntElt -> RngUPolElt`

Given a polynomial $p\in P$ and an integer $n \geq 0$, return the $n$-th derivative of $p$ as an element of $P$.

<a id="function-integral-rngupolelt"></a>
##### `Integral(p): RngUPolElt -> RngUPolElt`

Given a polynomial $p\in P$ over a field of characteristic zero, return the formal integral of $p$ as an element of $P$.

#### Evaluation, Interpolation

<a id="function-evaluate-rngupolelt-rngelt"></a>
##### `Evaluate(p, r): RngUPolElt, RngElt -> RngElt`

Given an element $p$ of a polynomial ring $P$ and an element $r$ of a ring $S$, return the value of $p$ evaluated at $r$. If $r$ can be coerced into the coefficient ring $R$ of $P$, the result will be an element of $R$. If $r$ cannot be coerced to the coefficient ring, then an attempt is made to do a generic evaluation of $p$ at $r$. In this case, the result will be an element of $S$.

<a id="function-interpolation-rngelt-rngelt"></a>
##### `Interpolation(I, V): [ RngElt ], [ RngElt ] -> RngUPolElt`

This function finds a univariate polynomial that evaluates to the values $V$ in the interpolation points $I$. Let $K$ be a field and $n>0$ an integer; given sequences $I$ and $V$, both consisting of $n$ elements of $K$, return the unique univariate polynomial $p$ over $K$ of degree less than $n$ such that $p(I[i]) = V[i]$ for each $1\leq i\leq n$.

#### Decomposition

The following function provides an inverse operation to composing polynomials.

<a id="function-decomposition-rngupolelt"></a>
##### `Decomposition(f): RngUPolElt -> [[RngUPolElt]]`

```magma
All: BoolElt                    Default: true
```

Given a polynomial $f$ defined over a field $k$, return all complete decompositions $[f_1,\ldots, f_r]$ of $f$ such that $f(t) = f_r(\ldots(f_1(t))$. These decompositions are found, as explained in [[ACvHS17](https://docs.magma-maths.org/references.md#cite-szutkoski)], by computing the subfield lattice of $k(t)/k(f)$, which in turn, is found by first computing the principal subfields of this extension and then computing all intersections of principal subfields. These intersections are computed by joining partitions.

<a id="example-ex-b0e795"></a>
##### `Example: Polynomial Decomposition (ex-b0e795)`

We show a decomposition of a polynomial and the corresponding evaluations which retrieve the polynomial which was decomposed.

```magma
> k:=GF(3^2);
> P<x>:=PolynomialRing(k);
> f:=x^9-x;
> Decomposition(f);
[
    [
        x^3 + x,
        x^3 + 2*x
    ],
    [
        x^3 + k.1^6*x,
        x^3 + k.1^6*x
    ],
    [
        x^3 + k.1^2*x,
        x^3 + k.1^2*x
    ],
    [
        x^3 + 2*x,
        x^3 + x
    ]
]
> Decomposition(f : All := false);
[
    [
        x^3 + x,
        x^3 + 2*x
    ]
]
> Evaluate($1[1][2], $1[1][1]) eq f;
true
```

#### Quotient and Remainder

<a id="function-quotrem-rngupolelt-rngupolelt"></a>
##### `Quotrem(f, g): RngUPolElt, RngUPolElt -> RngUPolElt, RngUPolElt`

Given elements $f$ and $g$ of the polynomial ring $P=R[x]$, this function returns polynomials $q$ (quotient) and $r$ (remainder) in $P$ such that $f = q\cdot g + r$, and the degree of $r$ is minimal. The leading coefficient of $g$ has to be a non-zero divisor in $R$. If the leading coefficient of $g$ is a unit, then the degree of $r$ will be strictly less than that of $g$ (taking the degree of $0$ to be $-1$). Over the integers ($R={\mathbb{Z}}$) this will be true in general when the leading coefficient of $g$ divides that of $f$.

<a id="operation-operation-div-rngupolelt-rngupolelt-rngupolelt-2"></a>
##### `f div g: RngUPolElt, RngUPolElt -> RngUPolElt`

The quotient of the polynomial $f$ by $g$, which is the first return value of `Quotrem` described above.

<a id="function-isdivisibleby-rngupolelt-rngupolelt"></a>
##### `IsDivisibleBy(f, g): RngUPolElt, RngUPolElt -> BoolElt, RngUPolElt`

Return whether the polynomial $f$ is exactly divisible by the polynomial $g$; that is, whether there exists $q$ with $f=qg$. If so, return also the exact divisor $q$.

<a id="function-exactquotient-rngupolelt-rngupolelt"></a>
##### `ExactQuotient(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

Assuming that the polynomial $f$ is exactly divisible by the polynomial $g$, return the exact quotient of $f$ by $g$ (as a polynomial in the same polynomial ring). An error results if $g$ does not divide $f$ exactly.

<a id="operation-operation-mod-rngupolelt-rngupolelt-rngupolelt-2"></a>
##### `f mod g: RngUPolElt, RngUPolElt -> RngUPolElt`

The remainder of division of the polynomial $f$ by $g$, which is the second return value of `Quotrem` described above.

<a id="function-valuation-rngupolelt-rngupolelt"></a>
##### `Valuation(f, g): RngUPolElt, RngUPolElt -> RngIntElt`

The exponent of the highest power of the polynomial $g$ which divides the polynomial $f$.

<a id="function-reductum-rngupolelt"></a>
##### `Reductum(f): RngUPolElt -> RngUPolElt`

The reductum of a polynomial $f$, which is the polynomial obtained by removing the leading term of $f$.

<a id="function-pseudoremainder-rngupolelt-rngupolelt"></a>
##### `PseudoRemainder(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

Given polynomials $f, g$ in $P=R[x]$, where $R$ is an integral domain, this function returns the pseudo-remainder $r$ of $f$ and $g$ defined as follows. Let $d$ be the maximum of $0$ and $\deg(f)-\deg(g)+1$, and let $c$ be the leading coefficient of $g$; then $r$ will be the unique polynomial in $P$ such that $c^d\cdot f=q\cdot g + r$ and the degree of $r$ is less than that of $g$ (possibly $-1$ for $r=0$).

<a id="function-euclideannorm-rngupol"></a>
##### `EuclideanNorm(p): RngUPol -> RngIntElt`

Return the Euclidean norm of the univariate polynomial $p\in P$, where the Euclidean norm is the function that makes $P$ into a Euclidean ring, which is the degree function.

#### Modular Arithmetic

The following functions allow modular arithmetic for univariate polynomials over a field without the need to move into the quotient ring. See also the description of `mod` in the section on quotient and remainder.

<a id="function-modexp-rngupolelt-rngintelt-rngupolelt"></a>
##### `Modexp(f, n, g): RngUPolElt, RngIntElt, RngUPolElt -> RngUPolElt`

Given univariate polynomials $f$ and $g$ in $K[x]$ over a field $K$, return $f^n \bmod g$ as an element of $K[x]$. Here $n$ must be a non-negative integer, and $g$ is allowed to be a constant polynomial.

<a id="function-chineseremaindertheorem-rngupolelt-rngupolelt"></a>
##### `ChineseRemainderTheorem(X, M): [RngUPolElt], [RngUPolElt] -> RngUPolElt`

<a id="function-crt-rngupolelt-rngupolelt"></a>
##### `CRT(X, M): [RngUPolElt], [RngUPolElt] -> RngUPolElt`

Given two sequences $X$ and $M$ of polynomials where the elements in $M$ are assumed to be pairwise coprime, find a single polynomial $t$ that solve the modular equation $X_i = t$ modulo $M_i$.

#### Other Operations

<a id="function-reciprocalpolynomial-rngupolelt"></a>
##### `ReciprocalPolynomial(f): RngUPolElt -> RngUPolElt`

The reciprocal of the given univariate polynomial.

<a id="function-powerpolynomial-rngupolelt-rngintelt"></a>
##### `PowerPolynomial(f, n): RngUPolElt, RngIntElt -> RngUPolElt`

The polynomial whose roots are the $n$th powers of the roots of the given polynomial (which should have coefficients in some field).

<a id="operation-op-pow-rngupolelt-mtrx"></a>
##### `f ^ M: RngUPolElt, Mtrx -> RngUPolElt`

The transformation of the univariate polynomial $f$ under the linear fractional transformation given by the $2$ by $2$ matrix $M$ (obtained by homogenizing $f$ and making a linear substitution).

### Common Divisors and Common Multiples

The functions in this section are restricted to univariate polynomials over a field, over the integers, or over a residue class ring of integers with prime modulus, or any polynomial ring over these.

<a id="id1"></a>
#### Common Divisors and Common Multiples

<a id="function-vpoly-gcd"></a>
##### `GreatestCommonDivisor(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="function-gcd-rngupolelt-rngupolelt"></a>
##### `Gcd(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="function-gcd-rngupolelt-rngupolelt-2"></a>
##### `GCD(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

Given univariate polynomials $f$ and $g$ over the ring $R$, this function returns the greatest common divisor (GCD) of $f$ and $g$. The valid coefficient rings are those which themselves have a GCD algorithm for their elements (which includes most commutative rings in Magma).

If either of the inputs is zero, then the result is the other input (and if the inputs are both zero then the result is zero). The result is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-normalize)), so the result is always unique.

For polynomials over finite fields, the simple Euclidean algorithm is used, since this is efficient (there is no intermediate coefficient blowup).

For polynomials over the integers or rationals, a combination of two algorithms is used: (1) the heuristic evaluation ‘GCDHEU’ algorithm of Char et al. ([[CGG89](https://docs.magma-maths.org/references.md#cite-gcdheu)] and [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 7.7]), suitable for small to moderate-degree dense polynomials; (2) a modular algorithm similar to that presented in [[vzGG99](https://docs.magma-maths.org/references.md#cite-gathengerhard), Algorithm 6.38] or [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 7.4] (although lifting all the way up to a bound is not used since it is completely unnecessary for correctness in this algorithm!).

For polynomials over an algebraic number field, quadratic field, or cyclotomic field, a fast modular algorithm is used, which maps the field to a residue class polynomial ring modulo a small prime.

Since V2.10, for polynomials over an algebraic function field or polynomial quotient ring over a function field, a new fast modular algorithm of Allan Steel (to be published) is used, which evaluates and interpolates for each base transcendental variable.

For polynomials over another polynomial ring or function field, the polynomials are first “flattened” to be inside a multivariate polynomial ring over the base coefficient ring, then the appropriate (multivariate) algorithm is used for that base coefficient ring.

For polynomials over any other ring, the generic subresultant algorithm [[Coh93](https://docs.magma-maths.org/references.md#cite-cohen1), section 3.3] is used.

<a id="function-extendedgreatestcommondivisor-rngupolelt-rngupolelt"></a>
##### `ExtendedGreatestCommonDivisor(f, g): RngUPolElt, RngUPolElt -> RngUPolElt, RngUPolElt, RngUPolElt`

<a id="function-xgcd-rngupolelt-rngupolelt"></a>
##### `Xgcd(f, g): RngUPolElt, RngUPolElt -> RngUPolElt, RngUPolElt, RngUPolElt`

<a id="function-xgcd-rngupolelt-rngupolelt-2"></a>
##### `XGCD(f, g): RngUPolElt, RngUPolElt -> RngUPolElt, RngUPolElt, RngUPolElt`

The extended greatest common divisor of polynomials $f$ and $g$ in a univariate polynomial ring $P$: the function returns polynomials $c$, $a$, and $b$ in $P$ with $\deg(a) < \deg(g)$ and $\deg(b) < \deg(f)$ such that $c$ is the monic GCD of $f$ and $g$, and $c = a\cdot f+ b\cdot g$. The multipliers $a$ and $b$ are unique if $f$ and $g$ are both non-zero. The coefficient ring must be a field.

For polynomials over the rational field, a modular algorithm due to Allan Steel (unpublished) is used; over other fields the basic Euclidean algorithm is used.

<a id="function-leastcommonmultiple-rngupolelt-rngupolelt"></a>
##### `LeastCommonMultiple(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="function-lcm-rngupolelt-rngupolelt"></a>
##### `Lcm(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

<a id="function-lcm-rngupolelt-rngupolelt-2"></a>
##### `LCM(f, g): RngUPolElt, RngUPolElt -> RngUPolElt`

The least common multiple of polynomials $f$ and $g$ in a univariate polynomial ring $P$. The LCM of zero and anything else is zero. The result is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-normalize)), so the result is always unique. The valid coefficient rings are as for the function `GCD`, above.

The LCM is effectively computed as `Normalize((F div GCD(F, G)) * G)`, for non-zero inputs.

<a id="function-vpoly-normalize"></a>
##### `Normalize(f): RngUPolElt -> RngUPolElt`

Given a univariate polynomial $f$ over the ring $R$, this function returns the unique normalized polynomial $g$ which is associate to $f$ (so $g=uf$ for some unit in $R$). This is chosen so that if $R$ is a field then $g$ is monic, if $R$ is ${\mathbb{Z}}$ then the leading coefficient of $g$ is positive, if $R$ is a polynomial ring itself, then the leading coefficient of $g$ is recursively normalized, and so on for other rings.

#### Content and Primitive Part

<a id="function-content-rngupolelt"></a>
##### `Content(p): RngUPolElt -> RngIntElt`

The content of $p$, that is, the greatest common divisor of the coefficients of $p$ as an element of the coefficient ring.

<a id="function-primitivepart-rngupolelt"></a>
##### `PrimitivePart(p): RngUPolElt -> RngUPolElt`

The primitive part of $p$, being $p$ divided by the content of $p$.

<a id="function-contentandprimitivepart-rngupolelt"></a>
##### `ContentAndPrimitivePart(p): RngUPolElt -> RngIntElt, RngUPolElt`

<a id="function-contpp-rngupolelt"></a>
##### `Contpp(p): RngUPolElt -> RngIntElt, RngUPolElt`

The content (the greatest common divisor of the coefficients) of $p$, as an element of the coefficient ring, as well as the primitive part ($p$ divided by the content) of $p$.

### Polynomials over the Integers

The functions in this section are available for univariate polynomials over the integers only.

<a id="function-sign-rngupolelt"></a>
#### `Sign(p): RngUPolElt -> RngIntElt`

The sign of the leading coefficient of $p$.

<a id="function-absolutevalue-rngupolelt"></a>
#### `AbsoluteValue(p): RngUPolElt -> RngUPolElt`

<a id="function-abs-rngupolelt"></a>
#### `Abs(p): RngUPolElt -> RngUPolElt`

Returns either $p$ or $-p$ according to which one has non-negative leading coefficient.

<a id="function-maxnorm-rngupolelt"></a>
#### `MaxNorm(p): RngUPolElt -> RngIntElt`

The maximum of the absolute values of the coefficients of $p$.

<a id="function-sumnorm-rngupolelt"></a>
#### `SumNorm(p): RngUPolElt -> RngIntElt`

The sum of the coefficients of $p$.

<a id="function-dedekindtest-rngupolelt-rngintelt"></a>
#### `DedekindTest(p, m): RngUPolElt, RngIntElt -> Boolelt`

Given a monic polynomial $p$ (univariate or multivariate in one variable) and a prime number $m$, this returns true if $p$ satisfies the Dedekind criterion at $m$, and false otherwise. The Dedekind criterion is satisfied at $m$ if and only if the equation order corresponding to $p$ is locally maximal at $m$ [[PZ89](https://docs.magma-maths.org/references.md#cite-pohst1), p. 295].

### Polynomials over Finite Fields

The functions in this section are available for univariate polynomials over finite fields only.

<a id="function-primepolynomials-rngupol-rngintelt"></a>
#### `PrimePolynomials(R, d): RngUPol, RngIntElt -> SeqEnum[ RngUPolElt ]`

<a id="function-primepolynomials-rngupol-rngintelt-rngintelt"></a>
#### `PrimePolynomials(R, d, n): RngUPol, RngIntElt, RngIntElt -> SeqEnum[ RngUPolElt ]`

A sequence of all monic prime polynomials of $R$ of degree $d$, resp. a sequence of $n$ monic prime polynomials of $R$ of degree $d$.

<a id="function-randomprimepolynomial-rngupol-rngintelt"></a>
#### `RandomPrimePolynomial(R, d): RngUPol, RngIntElt -> RngUPolElt`

A random monic prime polynomial of $R$ of degree $d$.

<a id="function-numberofprimepolynomials-rngintelt-rngintelt"></a>
#### `NumberOfPrimePolynomials(q, d): RngIntElt, RngIntElt -> RngIntElt`

<a id="function-numberofprimepolynomials-fldfin-rngintelt"></a>
#### `NumberOfPrimePolynomials(K, d): FldFin, RngIntElt -> RngIntElt`

<a id="function-numberofprimepolynomials-rngupol-rngintelt"></a>
#### `NumberOfPrimePolynomials(R, d): RngUPol, RngIntElt -> RngIntElt`

The number of monic prime polynomials of degree $d$ over the respective finite field.

<a id="function-jacobisymbol-rngupol-rngupol"></a>
#### `JacobiSymbol(a, b): RngUPol, RngUPol -> RngIntElt`

The Jacobi symbol (a/b) of the two polynomials $a,b \in {\mathbb{F}}_q[x]$ where $q$ must be odd. If $b$ is irreducible, the symbol equals $0$ if $b$ divides $a$. It equals $1$ if $a$ is a square mod $b$ and $-1$ otherwise. The symbol then extends multiplicatively to all non-constant polynomials $b$.

<a id="polfact"></a>
<a id="id1"></a>
### Factorization

This section describes the functions for polynomial factorization and associated computations. These are available for several kinds of coefficient rings.

#### Factorization and Irreducibility

<a id="function-vpoly-factorization"></a>
##### `Factorization(f): RngUPolElt -> [ < RngUPolElt, RngIntElt >], RngElt`

<a id="function-factorisation-rngupolelt"></a>
##### `Factorisation(f): RngUPolElt -> [ < RngUPolElt, RngIntElt >], RngElt`

```magma
Al: MonStgElt                    Default: "Default"
```

Given a univariate polynomial $f$ over the ring $R$, this function returns the factorization of $f$ as a factorization sequence $Q$, that is, a sequence of pairs, each consisting of an irreducible factor $q_i$ a positive integer $k_i$ (its multiplicity). Each irreducible factor is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-normalize)), so the expansion of the factorization sequence is the unique canonical associate of $f$. The function also returns the unit $u$ of $R$ giving the normalization, so $f=u\cdot \prod_i q_i^{k_i}$. The coefficient ring $R$ must be one of the following: a finite field ${\mathbb{F}}_q$, the ring of integers ${\mathbb{Z}}$, the field of rationals ${\mathbb{Q}}$, an algebraic number field ${\mathbb{Q}}(\alpha)$, a local ring, or a polynomial ring, function field (rational or algebraic) or finite-dimensional affine algebra (which is a field) over any of the above. For factorization over very small finite fields, the Berlekamp algorithm is used by default, which depends on fast linear algebra (see, for example, [[Knu97](https://docs.magma-maths.org/references.md#cite-knuth2), section 4.6.2] or [[vzGG99](https://docs.magma-maths.org/references.md#cite-gathengerhard), section 14.8]). For medium to large finite fields, the von zur Gathen/Kaltofen/Shoup algorithm ([[KS95](https://docs.magma-maths.org/references.md#cite-ks-factorization), [Sho95b](https://docs.magma-maths.org/references.md#cite-shoup-factorization), [vzGS92](https://docs.magma-maths.org/references.md#cite-gs-frobenius)]) is used by default. The parameter `Al` may be used to specify the factorization algorithm over finite fields. The possible values are:

**(1)**
`"Default"`: The default strategy, whereby an appropriate choice will be made.

**(2)**
`"BerlekampSmall"` or `"BerlekampLarge"` for the Berlekamp algorithm (see [[Knu97](https://docs.magma-maths.org/references.md#cite-knuth2), pp. 446--447] for the difference between these two variants).

**(3)**
`"GKS"` for the von zur Gathen/Kaltofen/Shoup algorithm.

Since V2.8 (July 2001), Magma uses the algorithm of Mark van Hoeij [[vH01](https://docs.magma-maths.org/references.md#cite-vhoeij2), [vH02](https://docs.magma-maths.org/references.md#cite-vhoeij1)] to factor polynomials over the integers or rationals. First a factorization of $f$ is found modulo a suitable small prime, then Hensel lifting is applied, as in the standard Berlekamp-Zassenhaus (BZ) algorithm [[Knu97](https://docs.magma-maths.org/references.md#cite-knuth2), p. 452]. The Hensel lifting is performed using Victor Shoup’s ‘tree lifting’ algorithm, as described in [[vzGG99](https://docs.magma-maths.org/references.md#cite-gathengerhard), Sec. 15.5]. Easy factors are also detected at various stages, if possible, using heuristics developed by Allan Steel. But the final search for the correct combination of modular factors (which has exponential worst-case complexity in the standard BZ algorithm) is now performed by van Hoeij’s algorithm, which efficiently finds the correct combinations by solving a Knapsack problem via the LLL lattice-basis reduction algorithm [[LLL82](https://docs.magma-maths.org/references.md#cite-lll)].

van Hoeij’s new algorithm is *much* more efficient in practice than the original lattice-based factoring algorithm proposed in [[LLL82](https://docs.magma-maths.org/references.md#cite-lll)]: the lattice constructed in van Hoeij’s algorithm has dimension equal to the number of modular factors (not the degree of the input polynomial), and the entries of the lattice are very much smaller. Many polynomials can now be easily factored which were out of reach for any previous algorithm (see the examples below).

For polynomials over algebraic number fields, algebraic function fields, and affine algebras, the norm-based algorithm of Trager [[Tra76](https://docs.magma-maths.org/references.md#cite-trager-factorization)] is used, which performs a suitable substitution and resultant computation, and then factors the resulting polynomial with one less variable. In characteristic zero, the difficult case (where there are very many factors of this integral polynomial modulo any prime) is now easily handled by van Hoeij’s combination algorithm above. In small characteristic, where inseparable field extensions may occur, an algorithm of Allan Steel ([[Ste05](https://docs.magma-maths.org/references.md#cite-steelinsep)]) is used.

<a id="function-haspolynomialfactorization-rng"></a>
##### `HasPolynomialFactorization(R): Rng -> BoolElt`

Given a ring $R$, return whether factorization of polynomials over $R$ is allowed in Magma.

<a id="procedure-setverbose-monstgelt-rngintelt-polyfact"></a>
##### `SetVerbose("PolyFact", v): MonStgElt, RngIntElt`

(Procedure.) Change the verbose printing level for all polynomial factorization algorithms to be $v$. Currently the legal levels are 0, 1, 2, or 3.

<a id="function-factorisationtopolynomial-tup"></a>
##### `FactorisationToPolynomial(f): [Tup] -> BoolElt`

<a id="function-facpol-tup"></a>
##### `Facpol(f): [Tup] -> BoolElt`

Given a sequence of tuples, each consisting of pairs of irreducible polynomials and positive integer exponents, return the product polynomial.

<a id="example-ex-d3c652"></a>
##### `Example: Factoring Swinnerton-Dyer Polynomials (ex-d3c652)`

To demonstrate the power of the van Hoeij combination algorithm, in this example we factor Swinnerton-Dyer polynomials, which are worse-case inputs for the Berlekamp-Zassenhaus factorization algorithm for polynomials over ${\mathbb{Z}}$.

The $n$-th Swinnerton-Dyer polynomial is defined to be

$$
\prod (x \pm \sqrt{2} \pm \sqrt{3} \pm \sqrt{5} \pm \cdots \pm \sqrt{p_n}),
$$

where $p_i$ is the $i$-th prime and the product runs over all $2^n$ possible combinations of $+$ and $-$ signs. This polynomial lies in ${\mathbb{Z}}[x]$, has degree $2^n$, is irreducible over ${\mathbb{Z}}$, and has at least $2^{n-1}$ factors modulo any prime. This last fact is easy to see, since, given any finite field $K$, the polynomial must split into linear factors over a quadratic extension of $K$, so it will have only linear or quadratic factors over $K$. See also [[vzGG99](https://docs.magma-maths.org/references.md#cite-gathengerhard), section 15.3] for further discussion.

In this example, we use the function `SwinnertonDyerPolynomial` to construct the polynomials (see Example [Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/GlobalFields/AlgebraicallyClosedFields/creation.md#example-ex-681d9c) in the chapter on algebraically closed fields for an explanation of how this function works).

First we display the first 4 polynomials.

```magma
> P<x> := PolynomialRing(IntegerRing());
> SwinnertonDyerPolynomial(1);
x^2 - 2
> SwinnertonDyerPolynomial(2);
x^4 - 10*x^2 + 1
> SwinnertonDyerPolynomial(3);
x^8 - 40*x^6 + 352*x^4 - 960*x^2 + 576
> SwinnertonDyerPolynomial(4);
x^16 - 136*x^14 + 6476*x^12 - 141912*x^10 + 1513334*x^8 - 7453176*x^6 +
    13950764*x^4 - 5596840*x^2 + 46225
> IsIrreducible($1);
true
```

We note the degree patterns of the factorizations of the first eight Swinnerton-Dyer polynomials over the three finite fields ${\bf F}_{3}$, ${\bf F}_{23}$, and ${\bf F}_{503}$. There are only linear or quadratic factors, as expected.

```magma
> for i := 1 to 8 do
>    f := SwinnertonDyerPolynomial(i);
>    printf "%o:", i;
>    for p in [3, 23, 503] do
>         L := Factorization(PolynomialRing(GF(p)) ! f);
>         printf " %o", {* Degree(t[1])^^t[2]: t in L *};
>     end for;
>     "";
> end for;
1: {* 2 *} {* 1^^2 *} {* 1^^2 *}
2: {* 2^^2 *} {* 1^^4 *} {* 1^^4 *}
3: {* 1^^4, 2^^2 *} {* 2^^4 *} {* 2^^4 *}
4: {* 1^^8, 2^^4 *} {* 2^^8 *} {* 2^^8 *}
5: {* 1^^8, 2^^12 *} {* 2^^16 *} {* 2^^16 *}
6: {* 1^^16, 2^^24 *} {* 2^^32 *} {* 2^^32 *}
7: {* 1^^48, 2^^40 *} {* 2^^64 *} {* 2^^64 *}
8: {* 1^^96, 2^^80 *} {* 1^^16, 2^^120 *} {* 2^^128 *}
```

We now construct the 6-th polynomial, note its largest coefficient, and then factor it; it takes only a second to prove that it is irreducible, even though there are 32 modular factors.

```magma
> sd6 := SwinnertonDyerPolynomial(6);
> Degree(sd6);
64
> Max([Abs(x): x in Coefficients(sd6)]);
1771080720430629161685158978892152599456 11
> time L := Factorization(sd6);
Time: 1.009
> #L;
1
```

Now we factor the 7-th polynomial!

```magma
> sd7 := SwinnertonDyerPolynomial(7);
> Degree(sd7);
128
> Max([Abs(x): x in Coefficients(sd7)]);
8578344714036018778166274416336425267466563380359649680696924587\\
44011458425706833248256 19
> time L := Factorization(sd7);
Time: 11.670
> #L;
1
```

We now factor the product of the 6-th and 7-th polynomials. This has degree 192 and has at least 96 factors modulo any prime! But the van Hoeij algorithms easily finds the correct factors over the integers.

```magma
> p := sd6*sd7;
> Degree(p);
192
> Max([Abs(x): x in Coefficients(p)]);
4617807523303144159751988353619837233948679680057885997820625979\\
481789171112550210109817070112666284891955285248592492005163008
31
> time L := Factorization(p);
Time: 16.840
> #L;
2
> L[1,1] eq sd6;
true
> L[2,1] eq sd7;
true
```

See also Example [Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/GlobalFields/AlgebraicallyClosedFields/creation.md#example-ex-681d9c) in the chapter on algebraically closed fields for a generalization of the Swinnerton-Dyer polynomials.

<a id="function-squarefreefactorization-rngupolelt"></a>
##### `SquarefreeFactorization(f): RngUPolElt -> [ <RngUPolElt, RngIntElt> ]`

Given a univariate polynomial $f$ over the ring $R$, this function returns the squarefree factorization of $f$ as a sequence of pairs, each consisting of a (not necessarily irreducible) factor and an integer indicating the multiplicity. The factors do not contain the square of any non-constant polynomial.

The coefficient ring $R$ must be the integer ring or any field. The algorithm works by computing the GCD of $f$ with its derivative and repeating as necessary (special considerations are also necessary for characteristic $p$).

<a id="function-distinctdegreefactorization-rngupolelt"></a>
##### `DistinctDegreeFactorization(f): RngUPolElt -> [ <RngIntElt, RngUPolElt> ]`

```magma
Degree: RngIntElt                    Default: 0
```

Given a squarefree univariate polynomial $f\in F[x]$ with $F$ a finite field, this function returns the distinct-degree factorization of $f$ as a sequence of pairs, each consisting of a degree $d$, together with the product of the degree-$d$ irreducible factors of $f$. If the optional parameter `Degree` is given a value $L > 0$, then only (products of) factors up to degree $L$ are returned.

<a id="function-equaldegreefactorization-rngupolelt-rngintelt-rngupolelt"></a>
##### `EqualDegreeFactorization(f, d, g): RngUPolElt, RngIntElt, RngUPolElt -> [ RngUPolElt ]`

Given a squarefree univariate polynomial $f\in F[x]$ with $F$ a finite field, and integer $d$ and another polynomial $g\in F[x]$ such that $F$ is known to be the product of distinct degree-$d$ irreducible polynomials alone, and $g$ is $x^q \bmod f$, where $q$ is the cardinality of $F$, this function returns the irreducible factors of $f$ as a sequence of polynomials (no multiplicities are needed). If the conditions are not satisfied, the result is unpredictable. This function allows one to split $f$, assuming that one has computed $f$ in some special way.

<a id="function-isirreducible-rngupolelt-2"></a>
##### `IsIrreducible(f): RngUPolElt -> BoolElt`

Given a univariate polynomial $f$ over the ring $R$, this function returns `true` if and only $f$ is irreducible over $R$. The conditions on $R$ are the same as for the function [`Factorization`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-vpoly-factorization) above.

<a id="function-isseparable-rngupolelt"></a>
##### `IsSeparable(f): RngUPolElt -> BoolElt`

Given a polynomial $f\in K[x]$ such that $f$ is a polynomial of degree $\geq 1$ and $K$ is a field allowing polynomial factorization, this function returns `true` iff $f$ is separable.

<a id="function-qmatrix-rngupolelt"></a>
##### `QMatrix(f): RngUPolElt -> AlgMatElt`

Given a univariate polynomial $f$ of degree $d$ over a finite field $F$ this function returns the Berlekamp $Q$-matrix associated with $f$, which is an element of the degree $d-1$ matrix algebra over $F$.

#### Sylvester Matrix, Resultant, and Discriminant

<a id="function-sylvestermatrix-rngupolelt-rngupolelt"></a>
##### `SylvesterMatrix(f, g): RngUPolElt, RngUPolElt -> Mtrx`

The Sylvester matrix of univariate polynomials $f$ and $g$ (of degree $m$ and $n$ respectively). This is an $(m+n)\times (m+n)$ matrix with entries in $R$, which is constructed by first creating $n$ rows from the coefficients of $f$, followed by $m$ rows from the coefficients of $g$. Within the two above blocks for rows, each subsequent row is a shifted version of the row above, with zeros filling in the empty spaces. The coefficient ring $R$ may be any ring.

<a id="function-resultant-rngupolelt-rngupolelt"></a>
##### `Resultant(f, g): RngUPolElt, RngUPolElt -> RngElt`

The resultant of univariate polynomials $f$ and $g$ (of degree $m$ and $n$ respectively) in $R[x]$, which is by definition the determinant of the Sylvester matrix of $f$ and $g$. The resultant is an element of $R$. The coefficient ring $R$ may be any commutative ring.

<a id="function-discriminant-rngupolelt"></a>
##### `Discriminant(f): RngUPolElt -> RngIntElt`

The discriminant $D$ of $f\in R[x]$, where $R$ is any commutative ring. This is an element of $R$ that is exactly equivalent to the Magma call:

`LeadingCoefficient(f)^(Degree(f) - Degree(d) - 2) * Resultant(f, d)`

`where d := Derivative(f)`.

<a id="function-companionmatrix-rngupolelt"></a>
##### `CompanionMatrix(f): RngUPolElt -> AlgMatElt`

Given a monic univariate polynomial $f$ of degree $d$ over some ring $R$, return the companion matrix of $f$ as an element of the full matrix algebra of degree $d-1$ over $R$. The companion matrix for $f=a_0+a_1x+\cdots +a_{d-1}x^{d-1}+x^d$ is given by

$$
\begin{pmatrix}0& 1& 0& \cdots& 0\\
   0& 0& 1& \cdots& 0\\
   \vdots& \vdots& \ddots&\vdots\\
   -a_0& -a_1& -a_2&\cdots -a_{d-2}&-a_{d-1}\end{pmatrix}.
$$

#### Hensel Lifting

<a id="function-hensellift-rngupolelt-rngupolelt-rngupol"></a>
##### `HenselLift(f, s, P): RngUPolElt, [ RngUPolElt ], RngUPol -> [ RngUPolElt ]`

Given the sequence of irreducible factors $s$ modulo some prime $p$ of the univariate integer polynomial $f$, return the Hensel lifting into the polynomial ring $P$, which must be the univariate polynomial ring over a residue class ring modulo some power of $p$. Thus given $f \equiv \prod_i s_i \bmod p$, this returns $f \equiv \prod_i t_i \bmod p^k$ for some $k \geq 1$, as a sequence of polynomials in ${\mathbb{Z}}/p^k{\mathbb{Z}}$. The factorization of $f$ modulo $p$ must be squarefree, that is, $s$ should not contain repeated factors.

<a id="example-ex-4d71ca"></a>
##### `Example: Hensel Lifting (ex-4d71ca)`

```magma
> R<x> := PolynomialRing(Integers());
> b := x^5 - x^3 + 2*x^2 - 2;
> F<f> := PolynomialRing(GF(5));
> s := [ w[1] : w in Factorization( F ! b ) ];
> s;
[
    f + 1,
    f + 3,
    f + 4,
    f^2 + 2*f + 4
]
> T<t> := PolynomialRing(Integers(5^3));
> h := HenselLift(b, s, T);
> h;
[
    t + 1,
    t + 53,
    t + 124,
    t^2 + 72*t + 59
]
> &*h;
t^5 + 124*t^3 + 2*t^2 + 123
```

### Ideals and Quotient Rings

Currently it is only possible to create ideals and quotient rings in univariate polynomial rings over fields. Note that these are principal ideal domains: all ideals can be generated by a single element.

#### Creation of Ideals and Quotients

<a id="constructor-constructor-ideal-rngupol-rngupolelt-rngupolelt-rngupol"></a>
##### `ideal< R | a₁, ..., aᵣ >: RngUPol, RngUPolElt, ..., RngUPolElt -> RngUPol`

Given a univariate polynomial ring $R$ over a field $K$, this function returns the ideal of $R$ generated by the elements $a_1, \ldots, a_r\in R$. This is the same as the ideal generated by the greatest common divisor of the elements $a_i$ in $R$. The function returns the ideal as a subring of $R$, generated by a single element.

<a id="constructor-constructor-quo-rngupol-rngupol-rngupolres"></a>
##### `quo< R | I >: RngUPol, RngUPol -> RngUPolRes`

<a id="constructor-constructor-quo-rngupol-rngupolelt-rngupolelt-rngupolres-map"></a>
##### `quo< R | a₁, ..., aᵣ >: RngUPol, RngUPolElt, ..., RngUPolElt -> RngUPolRes, Map`

Given an ideal $I$ in the univariate polynomial ring $R$ (over a field), return the quotient $R/I$, as well as the projection map $h: R\rightarrow R/I$. The ideal $I$ may either be specified as an ideal or by a list $a_1$, $a_2$, $\ldots$, $a_r$, of generators. The angle bracket notation can be used to assign names to the indeterminates: `Q<q> := quo< I | I >;`.

#### Ideal Arithmetic

Since ideals of $R$ are regarded as subrings of $R$, the ring $R$ itself is a valid ideal as well.

<a id="operation-op-plus-rngupol-rngupol"></a>
##### `I + J: RngUPol, RngUPol -> RngUPol`

Given ideals $I$ and $J$ in the same polynomial ring $R$, this function returns the sum of the ideals $I$ and $J$, which is the ideal generated by the generators of $I$ and those of $J$. Since we require $R$ to be a principal ideal domain, the resulting ideal will be simply generated by the greatest common divisor of `I.1` and `J.1`.

<a id="operation-op-times-rngupol-rngupol"></a>
##### `I * J: RngUPol, RngUPol -> RngUPol`

Given ideals $I$ and $J$ in the same polynomial ring $R$, this function returns the product of the ideals $I$ and $J$, which is the ideal generated by the products of the generators of $I$ and those of $J$. Since we require $R$ to be a principal ideal domain, the resulting ideal will be simply generated by `I.1 * J.1`.

<a id="operation-op-meet-rngupol-rngupol"></a>
##### `I meet J: RngUPol, RngUPol -> RngUPol`

Given ideals $I$ and $J$ in the same polynomial ring $R$, this function returns the intersection of the ideals $I$ and $J$. Since we require $R$ to be a principal ideal domain, the resulting ideal will equal the product of $I$ and $J$ and be simply generated by `I.1 * J.1`.

<a id="operation-op-in-rngupolelt-rngupol"></a>
##### `a in I: RngUPolElt, RngUPol -> BoolElt`

Given an element $a$ of a polynomial ring $P$ as well as an ideal $I$ of $P$, this function returns `true` if and only if $a$ is contained in $I$, and `false` otherwise.

<a id="operation-op-notin-rngupolelt-rngupol"></a>
##### `a notin I: RngUPolElt, RngUPol -> BoolElt`

Given an element $a$ of a polynomial ring $P$ as well as an ideal $I$ of $P$, this function returns `false` if and only if $a$ is contained in $I$, and `true` otherwise.

<a id="operation-op-eq-rngupol-rngupol-2"></a>
##### `I eq J: RngUPol, RngUPol -> BoolElt`

Given two ideals $I$ and $J$ in the same polynomial ring $R$ this returns `true` if and only if $I$ and $J$ are the same, and `false` otherwise.

<a id="operation-op-ne-rngupol-rngupol-2"></a>
##### `I ne J: RngUPol, RngUPol -> BoolElt`

Given two ideals $I$ and $J$ in the same polynomial ring $R$ this returns `false` if and only if $I$ and $J$ are the same, and `true` otherwise.

<a id="operation-op-subset-rngupol-rngupol"></a>
##### `I subset J: RngUPol, RngUPol -> BoolElt`

Given two ideals $I$ and $J$ in the same polynomial ring $R$ this returns `true` if and only if $I$ is contained in $J$, and `false` otherwise.

<a id="operation-operation-notsubset-rngupol-rngupol-boolelt"></a>
##### `I notsubset J: RngUPol, RngUPol -> BoolElt`

Given two ideals $I$ and $J$ in the same polynomial ring $R$ this returns `false` if and only if $I$ is contained in $J$, and `true` otherwise.

#### Other Functions on Ideals

Since ideals are considered as subrings of polynomial rings, and in particular are in the same Magma category as polynomial rings, most of the function listed in this chapter for polynomial rings do also apply to ideals, but some restrictions apply. Thus it will be possible to get the coefficient ring but it will not be possible to use `ChangeRing` to change it. We list some functions here that additional comments.

<a id="operation-operation-rngupol-rngupolelt"></a>
##### `I . 1: RngUPol -> RngUPolElt`

Given an ideal $I$ in a univariate polynomial ring $R$, return the generator of $I$ in $R$ as an element of $I$.

#### Other Functions on Quotients

Contrary to ideals, quotient rings form a separate Magma category. Only very few functions are available on these rings; however most element functions for polynomial rings apply to elements of quotients as well, in particular the coefficient, term, and degree functions.

<a id="function-modulus-rngupolres"></a>
##### `Modulus(Q): RngUPolRes -> RngUPolElt`

Given a quotient ring $Q=R[x]/I$ of the univariate polynomial ring $R[x]$ obtained by factoring out by the ideal $I$, return the generator for $I$ as an element of $R$.

<a id="function-preimagering-rngupolres"></a>
##### `PreimageRing(Q): RngUPolRes -> RngUPol`

If $Q$ is the quotient $Q = R / I$ for some univariate polynomial ring $R$, this function returns $R$.

### Special Families of Polynomials

#### Orthogonal Polynomials

<a id="function-chebyshevfirst-rngintelt"></a>
##### `ChebyshevFirst(n): RngIntElt -> RngUPolElt`

<a id="function-chebyshevt-rngintelt"></a>
##### `ChebyshevT(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Chebyshev polynomial of the first kind $T_n(x)$, where $T_n(x)$ is defined by $T_n(x) = \cos n \theta$ with $x = \cos \theta$.

<a id="function-chebyshevsecond-rngintelt"></a>
##### `ChebyshevSecond(n): RngIntElt -> RngUPolElt`

<a id="function-chebyshevu-rngintelt"></a>
##### `ChebyshevU(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Chebyshev polynomial of the second kind, $U_n(x)$, of degree $n - 1$. The polynomial is defined by $U_n(x) = {{1} \over {n}} T_n ' (x) = {{\sin n \theta} \over {\sin \theta}}$ where $x = \cos \theta$.

<a id="function-legendrepolynomial-rngintelt"></a>
##### `LegendrePolynomial(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Legendre polynomial $P_n(x)$ of degree $n$, where $P_n(x)$ is defined by

$$
\begin{aligned}P_0(x) &= 1, \ P_1(x) = x, \\
   P_n(x) &= {1 \over {n}} ((2n - 1) x P_{n - 1}(x)
    - (n - 1) P_{n - 2}(x)).\end{aligned}
$$

<a id="function-laguerrepolynomial-rngintelt"></a>
##### `LaguerrePolynomial(n): RngIntElt -> RngUPolElt`

<a id="function-laguerrepolynomial-rngintelt-rngelt"></a>
##### `LaguerrePolynomial(n, m): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Laguerre polynomial $L_n^m(x)$ of degree $n$ with parameter $m$. If $m$ is omitted, it is assumed to be zero if it is not specified. The polynomial satisfies the recurrence relation

$$
\begin{aligned}L_0(x) &= 1, \ L_1(x) = 1 + m - x,
   \\
   L_n(x) &= {1 \over n} (((2n+m-1) - x) L_{n - 1}^m(x) -
   (n - 1 + m) L_{n - 2}^m(x)).\end{aligned}
$$

<a id="function-hermitepolynomial-rngintelt"></a>
##### `HermitePolynomial(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Hermite polynomial $H_n(x)$ of degree $n$, where $H_n(x)$ is defined by

$$
\begin{aligned}H_0(x) &= 1, \ H_1(x) = 2x, \\ H_n(x) &= 2x H_{n - 1}(x) -
   2n H_{n - 2}(x).\end{aligned}
$$

<a id="function-gegenbauerpolynomial-rngintelt-rngelt"></a>
##### `GegenbauerPolynomial(n, m): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$ and an integer $m$, this function constructs the Gegenbauer polynomial $C_n^m(x)$ of degree $n$ with parameter $m$, where $C_n^m(x)$ is defined by

$$
\begin{aligned}C_0^m(x) &= 1, \ C_1^m(x) = 2 m x,\\
   C_n^m(x) &= {1 \over n}(2(n - 1 + m) x C_{n - 1}^m(x) -
   (n + 2m - 2) C_{n - 2}^m(x)).\end{aligned}
$$

#### Permutation Polynomials

<a id="function-dicksonfirst-rngintelt-rngelt"></a>
##### `DicksonFirst(n, a): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Dickson polynomial of the first kind $D_n (x, a)$ of degree $n$, where $D_n (x, a)$ is defined by

$$
D_n(x, a) = \sum_{i=0}^{\lfloor n/2 \rfloor}
   {n \over {n - i}} {{n - i} \choose i} (-a)^i x^{n - 2i}.
$$

<a id="function-dicksonsecond-rngintelt-rngelt"></a>
##### `DicksonSecond(n, a): RngIntElt, RngElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the Dickson polynomial of the second kind $E_n (x, a)$ of degree $n$, where $E_n (x, a)$ is defined by

$$
E_n(x, a) = \sum_{i=0}^{\lfloor n/2 \rfloor}
   {{n - i} \choose {i}} (-a)^i x^{n - 2i}.
$$

#### The Bernoulli Polynomial

<a id="function-bernoullipolynomial-rngintelt"></a>
##### `BernoulliPolynomial(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the $n$-th Bernoulli polynomial.

#### Swinnerton-Dyer Polynomials

<a id="function-swinnertondyerpolynomial-rngintelt"></a>
##### `SwinnertonDyerPolynomial(n): RngIntElt -> RngUPolElt`

Given a positive integer $n$, this function constructs the $n$-th Swinnerton-Dyer polynomial, which is defined to be

$$
\prod (x \pm \sqrt{2} \pm \sqrt{3} \pm \sqrt{5} \pm
   \cdots \pm \sqrt{p_n}),
$$

where $p_i$ is the $i$-th prime and the product runs over all $2^n$ possible combinations of $+$ and $-$ signs. This polynomial lies in ${\mathbb{Z}}[x]$, has degree $2^n$, and is irreducible over ${\mathbb{Z}}$.

See Example [Factoring Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#example-ex-d3c652) above which explains more about this class of polynomials, and see also Example [Swinnerton-Dyer Polynomials](https://docs.magma-maths.org/GlobalFields/AlgebraicallyClosedFields/creation.md#example-ex-681d9c) in the chapter on algebraically closed fields to see how these polynomials are constructed and also for a generalization.

<a id="distributive-multivariate-polynomial"></a>
<a id="dpoly-chap"></a>
## Multivariate Polynomial Rings

- [Introduction](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/introduction.md)
  - [Representation](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/introduction.md#representation)
- [Polynomial Rings and Polynomials](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md)
  - [Creation of Polynomial Rings](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#creation-of-polynomial-rings)
    - [`PolynomialRing(R, n): Rng, RngIntElt → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-polynomialring-rng-rngintelt)
    - [`PolynomialAlgebra(R, n): Rng, RngIntElt → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-polynomialalgebra-rng-rngintelt)
    - [`PolynomialRing(R, n, order): Rng, RngIntElt, MonStgElt, ... → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-polynomialring-rng-rngintelt-monstgelt)
    - [`PolynomialAlgebra(R, n, order): Rng, RngIntElt, MonStgElt, ... → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-polynomialalgebra-rng-rngintelt-monstgelt)
    - [Example: Assigning Generator Names](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#example-ex-1b3506)
    - [Example: Global and Non-Global Polynomial Rings](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#example-ex-a068bd)
  - [Print Names](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#print-names)
    - [`AssignNames(~P, s): RngMPol, [ MonStgElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#procedure-assignnames-rngmpol-monstgelt-ref)
    - [`Name(P, i): RngMPol, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-name-rngmpol-rngintelt)
  - [Graded Polynomial Rings](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#graded-polynomial-rings)
  - [Creation of Polynomials](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#creation-of-polynomials)
    - [`P . i: RngMPol, RngInt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#operation-operation-rngmpol-rngint-rngmpolelt)
    - [`elt< R | a >: RngMPol, RngElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#constructor-constructor-elt-rngmpol-rngelt-rngmpolelt)
    - [`R ! s: RngMPol, RngElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#operation-op-rngmpol-rngelt)
    - [`R ! s: RngMPol, [ RngElt ] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#operation-op-rngmpol-rngelt-2)
    - [`elt< R | s >: RngMPol, [ RngElt ] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#constructor-constructor-elt-rngmpol-rngelt-rngmpolelt-2)
    - [`MultivariatePolynomial(P, f, i): RngMPol, RngUPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-multivariatepolynomial-rngmpol-rngupolelt-rngintelt)
    - [`MultivariatePolynomial(P, f, v): RngMPol, RngUPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-multivariatepolynomial-rngmpol-rngupolelt-rngmpolelt)
    - [`One(P): RngMPol → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-one-rngmpol)
    - [`Identity(P): RngMPol → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-identity-rngmpol)
    - [`Zero(P): RngMPol → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-zero-rngmpol)
    - [`Representative(P): RngMPol → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/rings.md#function-representative-rngmpol)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#related-structures)
    - [`BaseRing(P): RngMPol → Rng`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-basering-rngmpol)
    - [`CoefficientRing(P): RngMPol → Rng`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-coefficientring-rngmpol)
    - [`Category(P): RngMPol → Cat`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-category-rngmpol)
    - [`Parent(P): RngMPol → Pow`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-parent-rngmpol)
    - [`PrimeRing(P): RngMPol → Rng`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-primering-rngmpol)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#numerical-invariants)
    - [`Rank(P): RngMPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-rank-rngmpol)
    - [`Characteristic(P): RngMPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-characteristic-rngmpol)
    - [`#P: RngMPol → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#operation-operation-rngmpol-rngintelt)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#ring-predicates-and-booleans)
    - [`IsCommutative(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-iscommutative-rngmpol)
    - [`IsUnitary(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isunitary-rngmpol)
    - [`IsFinite(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isfinite-rngmpol)
    - [`IsOrdered(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isordered-rngmpol)
    - [`IsField(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isfield-rngmpol)
    - [`IsEuclideanDomain(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-iseuclideandomain-rngmpol)
    - [`IsPID(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-ispid-rngmpol)
    - [`IsUFD(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isufd-rngmpol)
    - [`IsDivisionRing(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isdivisionring-rngmpol)
    - [`IsEuclideanRing(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-iseuclideanring-rngmpol)
    - [`IsDomain(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isdomain-rngmpol)
    - [`IsPrincipalIdealRing(P): RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-isprincipalidealring-rngmpol)
    - [`P eq Q: RngMPol, RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#operation-op-eq-rngmpol-rngmpol)
    - [`P ne Q: RngMPol, RngMPol → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#operation-op-ne-rngmpol-rngmpol)
  - [Changing Coefficient Ring](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#changing-coefficient-ring)
    - [`ChangeRing(P, S): RngMPol, Rng → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#function-changering-rngmpol-rng)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#homomorphisms)
    - [`hom< P -> S | f, y₁, ..., yₙ >: RngMPol, Rng → Map`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#constructor-constructor-hom-rngmpol-rng-map)
    - [`hom< P -> S | y₁, ..., yₙ >: RngMPol, Rng → Map`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#constructor-constructor-hom-rngmpol-rng-map-2)
    - [Example: Homomorphism into a Number Field](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation.md#example-ex-a59b0c)
- [Element Operations](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md)
  - [Arithmetic Operators](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#arithmetic-operators)
    - [`+ a: RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-rngmpolelt-rngmpolelt)
    - [`- a: RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-rngmpolelt-rngmpolelt-2)
    - [`a + b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-plus-rngmpolelt-rngmpolelt)
    - [`a - b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-minus-rngmpolelt-rngmpolelt)
    - [`a * b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-times-rngmpolelt-rngmpolelt)
    - [`a ^ k: RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-pow-rngmpolelt-rngintelt)
    - [`a / b: RngMPolElt, RngMPolElt → FldFunMElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-div-rngmpolelt-rngmpolelt)
    - [`a div b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt)
    - [`a +:= b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-rngmpolelt-rngmpolelt-rngmpolelt)
    - [`a -:= b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-rngmpolelt-rngmpolelt-rngmpolelt-2)
    - [`a *:= b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-rngmpolelt-rngmpolelt-rngmpolelt-3)
    - [`a div:= b: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt-2)
  - [Equality and Membership](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#equality-and-membership)
    - [`a eq b: RngMPolElt, RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-eq-rngmpolelt-rngmpolelt)
    - [`a ne b: RngMPolElt, RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-ne-rngmpolelt-rngmpolelt)
    - [`a in R: RngMPolElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-in-rngmpolelt-rng)
    - [`a notin R: RngMPolElt, Rng → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-op-notin-rngmpolelt-rng)
  - [Predicates on Ring Elements](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#predicates-on-ring-elements)
    - [`IsDivisibleBy(a, b): RngMPolElt, RngMPolElt → BoolElt, RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isdivisibleby-rngmpolelt-rngmpolelt)
    - [`IsAlgebraicallyDependent(S): {RngMPolElt} → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isalgebraicallydependent-rngmpolelt)
    - [`IsZero(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-iszero-rngmpolelt)
    - [`IsOne(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isone-rngmpolelt)
    - [`IsMinusOne(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isminusone-rngmpolelt)
    - [`IsNilpotent(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isnilpotent-rngmpolelt)
    - [`IsIdempotent(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isidempotent-rngmpolelt)
    - [`IsUnit(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isunit-rngmpolelt)
    - [`IsZeroDivisor(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-iszerodivisor-rngmpolelt)
    - [`IsRegular(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isregular-rngmpolelt)
    - [`IsIrreducible(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isirreducible-rngmpolelt)
    - [`IsPrime(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isprime-rngmpolelt)
  - [Coefficients, Monomials, and Terms](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#coefficients-monomials-and-terms)
    - [`Coefficients(f): RngMPolElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficients-rngmpolelt)
    - [`Coefficients(f, i): RngMPolElt, RngIntElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficients-rngmpolelt-rngintelt)
    - [`Coefficients(f, v): RngMPolElt, RngMPolElt → [ RngElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficients-rngmpolelt-rngmpolelt)
    - [`Coefficient(f, i, k): RngMPolElt, RngIntElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficient-rngmpolelt-rngintelt-rngintelt)
    - [`Coefficient(f, v, k): RngMPolElt, RngMPolElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficient-rngmpolelt-rngmpolelt-rngintelt)
    - [`LeadingCoefficient(f): RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingcoefficient-rngmpolelt)
    - [`LeadingCoefficient(f, i): RngMPolElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingcoefficient-rngmpolelt-rngintelt)
    - [`LeadingCoefficient(f, v): RngMPolElt, RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingcoefficient-rngmpolelt-rngmpolelt)
    - [`Length(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-length-rngmpolelt)
    - [`TrailingCoefficient(f): RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingcoefficient-rngmpolelt)
    - [`TrailingCoefficient(f, i): RngMPolElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingcoefficient-rngmpolelt-rngintelt)
    - [`TrailingCoefficient(f, v): RngMPolElt, RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingcoefficient-rngmpolelt-rngmpolelt)
    - [`CoefficientDenominator(f): RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficientdenominator-rngmpolelt)
    - [`CoefficientNumerator(f): RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficientnumerator-rngmpolelt)
    - [`MonomialCoefficient(f, m): RngMPolElt, RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-monomialcoefficient-rngmpolelt-rngmpolelt)
    - [`Monomials(f): RngMPolElt → [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-monomials-rngmpolelt)
    - [`CoefficientsAndMonomials(f): RngMPolElt → [ RngElt ], [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-coefficientsandmonomials-rngmpolelt)
    - [`LeadingMonomial(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingmonomial-rngmpolelt)
    - [`Terms(f): RngMPolElt → [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-terms-rngmpolelt)
    - [`Terms(f, i): RngMPolElt, RngIntElt → [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-terms-rngmpolelt-rngintelt)
    - [`Terms(f, v): RngMPolElt, RngMPolElt → [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-terms-rngmpolelt-rngmpolelt)
    - [`Term(f, i, k): RngMPolElt, RngIntElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-term-rngmpolelt-rngintelt-rngintelt)
    - [`Term(f, v, k): RngMPolElt, RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-term-rngmpolelt-rngmpolelt-rngintelt)
    - [`LeadingTerm(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingterm-rngmpolelt)
    - [`LeadingTerm(f, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingterm-rngmpolelt-rngintelt)
    - [`LeadingTerm(f, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingterm-rngmpolelt-rngmpolelt)
    - [`TrailingTerm(f): RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingterm-rngmpolelt)
    - [`TrailingTerm(f, i): RngMPolElt, RngIntElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingterm-rngmpolelt-rngintelt)
    - [`TrailingTerm(f, v): RngMPolElt, RngMPolElt → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-trailingterm-rngmpolelt-rngmpolelt)
    - [`Exponents(f): RngMPolElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-exponents-rngmpolelt)
    - [`Monomial(P, E): RngMPol, [ RngIntElt ] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-monomial-rngmpol-rngintelt)
    - [`Polynomial(C, M): [RngElt], [RngMPolElt] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-polynomial-rngelt-rngmpolelt)
    - [Example: Coefficients and Monomials](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#example-ex-f062e9)
  - [Degrees](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#degrees)
    - [`Degree(f, i): RngMPolElt, RngIntElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-degree-rngmpolelt-rngintelt)
    - [`Degree(f, v): RngMPolElt, RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-degree-rngmpolelt-rngmpolelt)
    - [`TotalDegree(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-totaldegree-rngmpolelt)
    - [`LeadingTotalDegree(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-leadingtotaldegree-rngmpolelt)
  - [Univariate Polynomials](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#univariate-polynomials)
    - [`IsUnivariate(f): RngMPolElt → BoolElt, RngUPolElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isunivariate-rngmpolelt)
    - [`IsUnivariate(f, i): RngMPolElt, RngIntElt → BoolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isunivariate-rngmpolelt-rngintelt)
    - [`IsUnivariate(f, v): RngMPolElt, RngMPolElt → BoolElt, RngUPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-isunivariate-rngmpolelt-rngmpolelt)
    - [`UnivariatePolynomial(f): RngMPolElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-univariatepolynomial-rngmpolelt)
    - [Example: Converting to a Univariate Polynomial](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#example-ex-f54865)
  - [Derivative, Integral](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#derivative-integral)
    - [`Derivative(f, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-derivative-rngmpolelt-rngintelt)
    - [`Derivative(f, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-derivative-rngmpolelt-rngmpolelt)
    - [`Derivative(f, k, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-derivative-rngmpolelt-rngintelt-2)
    - [`Derivative(f, k, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-derivative-rngmpolelt-rngmpolelt-2)
    - [`Integral(f, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-integral-rngmpolelt-rngintelt)
    - [`Integral(f, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-integral-rngmpolelt-rngmpolelt)
    - [`JacobianMatrix( [ f ] ): [ RngMPolElt ] → RngMPol`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-jacobianmatrix-rngmpolelt)
  - [Evaluation, Interpolation](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#evaluation-interpolation)
    - [`Evaluate(f, s): RngMPolElt, [ RngElt ] → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-evaluate-rngmpolelt-rngelt)
    - [`Evaluate(f, s): RngMPolElt, < RngElt, ..., RngElt > → RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-evaluate-rngmpolelt-rngelt-rngelt)
    - [`Evaluate(f, i, r): RngMPolElt, RngMPolElt, RngElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-evaluate-rngmpolelt-rngmpolelt-rngelt)
    - [`Evaluate(f, v, r): RngMPolElt, RngMPolElt, RngElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-evaluate-rngmpolelt-rngmpolelt-rngelt-2)
    - [`Interpolation(I, V, i): [ RngElt ], [ RngMPolElt ], RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-interpolation-rngelt-rngmpolelt-rngintelt)
    - [`Interpolation(I, V, v): [ RngElt ], [ RngMPolElt ], RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-interpolation-rngelt-rngmpolelt-rngintelt-2)
    - [Example: Polynomial Interpolation](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#example-ex-ca9d39)
  - [Quotient and Reductum](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#quotient-and-reductum)
    - [`f div g: RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt-3)
    - [`ExactQuotient(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-exactquotient-rngmpolelt-rngmpolelt)
    - [`Reductum(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-reductum-rngmpolelt)
    - [`Reductum(f, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-reductum-rngmpolelt-rngintelt)
    - [`Reductum(f, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-reductum-rngmpolelt-rngmpolelt)
  - [Diagonalizing a Polynomial of Degree 2](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#diagonalizing-a-polynomial-of-degree-2)
    - [`SymmetricBilinearForm(f): RngMPolElt → ModMatRngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-symmetricbilinearform-rngmpolelt)
    - [`DiagonalForm(f): RngMPolElt → RngMPolElt, ModMatRngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#function-diagonalform-rngmpolelt)
    - [Example: Symmetric Bilinear Form of a Quadratic Polynomial](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/operation-element.md#example-ex-649fdb)
- [Greatest Common Divisors](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md)
  - [Common Divisors and Common Multiples](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#common-divisors-and-common-multiples)
    - [`GreatestCommonDivisor(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-greatestcommondivisor-rngmpolelt-rngmpolelt)
    - [`Gcd(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-gcd-rngmpolelt-rngmpolelt)
    - [`GCD(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-gcd-rngmpolelt-rngmpolelt-2)
    - [`GCD(Q): [ RngMPolElt ] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-gcd-rngmpolelt)
    - [`LeastCommonMultiple(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-leastcommonmultiple-rngmpolelt-rngmpolelt)
    - [`Lcm(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-lcm-rngmpolelt-rngmpolelt)
    - [`LCM(f, g): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-lcm-rngmpolelt-rngmpolelt-2)
    - [`LCM(Q): [ RngMPolElt ] → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-lcm-rngmpolelt)
    - [`Normalize(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-dpoly-normalize)
    - [`ClearDenominators(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-cleardenominators-rngmpolelt)
    - [`ClearDenominators(Q): [ RngMPolElt ] → [ RngMPolElt ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-cleardenominators-rngmpolelt-2)
  - [Content and Primitive Part](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#content-and-primitive-part)
    - [`Content(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-content-rngmpolelt)
    - [`PrimitivePart(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-primitivepart-rngmpolelt)
    - [`ContentAndPrimitivePart(f): RngMPolElt → RngIntElt, RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-contentandprimitivepart-rngmpolelt)
    - [`Contpp(f): RngMPolElt → RngIntElt, RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-contpp-rngmpolelt)
- [Factorization and Irreducibility](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md)
  - [`Factorization(f): RngMPolElt → [ < RngMPolElt, RngIntElt >], RngElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#function-factorization-rngmpolelt)
  - [`SquarefreeFactorization(f): RngMPolElt → [ <RngMPolElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#function-squarefreefactorization-rngmpolelt)
  - [`SquarefreePart(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#function-squarefreepart-rngmpolelt)
  - [`IsIrreducible(f): RngMPolElt → BoolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#function-isirreducible-rngmpolelt-2)
  - [`SetVerbose("PolyFact", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#procedure-setverbose-monstgelt-rngintelt-polyfact)
  - [Example: Factorizing a Product of Trinomials](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#example-ex-2f44bb)
  - [Example: Factorizing a Vandermonde Determinant](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#example-ex-12897c)
  - [Example: Heron's Formula for the Area of a Triangle](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#example-ex-f94225)
  - [Example: Finite Field Factorization](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/factorization-irreducibility.md#example-ex-8e8a69)
- [Resultants and Discriminants](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/resultant-discriminant.md)
  - [`Resultant(f, g, i): RngMPolElt, RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/resultant-discriminant.md#function-resultant-rngmpolelt-rngmpolelt-rngintelt)
  - [`Resultant(f, g, v): RngMPolElt, RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/resultant-discriminant.md#function-resultant-rngmpolelt-rngmpolelt-rngmpolelt)
  - [`Discriminant(f, i): RngMPolElt, RngIntElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/resultant-discriminant.md#function-discriminant-rngmpolelt-rngintelt)
  - [`Discriminant(f, v): RngMPolElt, RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/resultant-discriminant.md#function-discriminant-rngmpolelt-rngmpolelt)
- [Polynomials over the Integers](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md)
  - [`Sign(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md#function-sign-rngmpolelt)
  - [`AbsoluteValue(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md#function-absolutevalue-rngmpolelt)
  - [`Abs(f): RngMPolElt → RngMPolElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md#function-abs-rngmpolelt)
  - [`MaxNorm(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md#function-maxnorm-rngmpolelt)
  - [`SumNorm(f): RngMPolElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/integer.md#function-sumnorm-rngmpolelt)
- [Bibliography](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/bibliography.md)

### Introduction

This chapter describes multivariate polynomial rings in Magma. A multivariate polynomial ring in any number of variables $n\geq 1$ can be created over an arbitrary coefficient ring $R$, and we will denote it by $P=R[x_1, \ldots, x_n]$. Certain functions, however, will only apply for coefficient rings satisfying certain conditions. Magma contains a powerful system for computing with ideals of multivariate polynomial rings. This is based on the construction of Gröbner bases of such ideals. This chapter only deals with polynomial rings and operations on their elements; see Chapter [Gröbner Bases](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/index-grobner-bases.md#chapgb) for the details concerning ideals and Gröbner bases. Permutation and matrix groups have a natural action on multivariate polynomial rings. This leads to the subject of invariant rings of finite groups, which is covered in Chapter [Invariant Theory](https://docs.magma-maths.org/CommutativeAlgebra/InvariantTheory/index-invariant-theory.md#invar-rings). See also the chapters on affine algebras (Chapter [Affine Algebras](https://docs.magma-maths.org/CommutativeAlgebra/AffineAlgebras/index-affine-algebras.md#chapalgaff)) and on modules over affine algebras (Chapter [Modules over Multivariate Rings](https://docs.magma-maths.org/CommutativeAlgebra/ModulesOverMultivariateRings/index-modules-over-multivariate-rings.md#pmod-chap)).

#### Representation

Let $P$ be the polynomial ring $R[x_1, \ldots, x_n]$ of rank $n$ over a ring $R$. A *monomial* (or *power product*) of $P$ is a product of powers of the variables of $P$, that is, an expression of the form $x_1^{e_1} \cdots x_n^{e_n}$ with $e_i \geq 0$ for $1 \leq i \leq n$. Multivariate polynomials in Magma are stored efficiently in distributive form, using arrays of coefficient-monomial pairs, where the coefficient is in the base ring $R$. The word ‘term’ will always refer to a coefficient multiplied by a monomial. Various orders can be applied to the monomials, and these are of great importance when dealing with Gröbner bases. A polynomial ring in Magma may defined with a certain monomial order, but as this does not affect the basic arithmetic operations in the polynomial ring, these orders are not described here but in the chapter dealing with Gröbner bases (see Section [Representation and Monomial Orders](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/order.md#dpoly-monomial-orders)). Since V2.7 (June 2000), a new generalized monomial representation has been developed, which uses differing byte sizes for monomials depending on the size of the monomials encountered. Monomial overflow is rigorously detected, and the system automatically extends the byte size of the monomials in the background if possible. Thus there is no need for the user to know beforehand the maximum degree which may occur, and much memory is also saved for low- to medium-degree computations. The total degree of any monomial may now be anything up to $2^{30}-1 = 1073741823$. It is possible but not advised to use distributive ‘multivariate’ polynomials in one single variable. (See Chapter [Univariate Polynomial Rings](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/index-univariate-polynomial-rings.md#rngpol) which is devoted to univariate polynomial rings.)

### Polynomial Rings and Polynomials

<a id="creation"></a>
<a id="dpoly-creation"></a>
#### Creation of Polynomial Rings

Multivariate polynomial rings are created from a coefficient ring, the number of indeterminates, and a monomial order. If no order is specified, the monomial order is taken to be the lexicographical order (see Section [Representation and Monomial Orders](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/order.md#dpoly-monomial-orders) for details).

<a id="function-polynomialring-rng-rngintelt"></a>
##### `PolynomialRing(R, n): Rng, RngIntElt -> RngMPol`

<a id="function-polynomialalgebra-rng-rngintelt"></a>
##### `PolynomialAlgebra(R, n): Rng, RngIntElt -> RngMPol`

```magma
Global: BoolElt                    Default: false
```

Create a multivariate polynomial ring in $n>0$ indeterminates over the ring $R$. The ring is regarded as an $R$-algebra via the usual identification of elements of $R$ and the constant polynomials. The lexicographical ordering on the monomials is used for this default construction (see Section [Representation and Monomial Orders](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/order.md#dpoly-monomial-orders)). The angle bracket notation can be used to assign names to the indeterminates; e.g.: `P<x, y> := PolynomialRing(R, 2);` etc. By default, a *non-global* polynomial ring will be returned; if the parameter `Global` is set to `true`, then the unique global polynomial ring over $R$ with $n$ variables will be returned. This may be useful in some contexts, but a non-global result is returned by default since one often wishes to have several rings with the same numbers of variables but with different variable names (and create mappings between them, for example). Explicit coercion is always allowed between polynomial rings having the same number of variables (and suitable base rings), whether they are global or not, and the coercion maps the $i$-variable of one ring to the $i$-th variable of the other ring.

<a id="function-polynomialring-rng-rngintelt-monstgelt"></a>
##### `PolynomialRing(R, n, order): Rng, RngIntElt, MonStgElt, ... -> RngMPol`

<a id="function-polynomialalgebra-rng-rngintelt-monstgelt"></a>
##### `PolynomialAlgebra(R, n, order): Rng, RngIntElt, MonStgElt, ... -> RngMPol`

Create a multivariate polynomial ring in $n>0$ indeterminates over the ring $R$ with the given order order on the monomials. See Section [Representation and Monomial Orders](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/order.md#dpoly-monomial-orders) for details.

<a id="example-ex-1b3506"></a>
##### `Example: Assigning Generator Names (ex-1b3506)`

We show the use of angle brackets for generator names.

```magma
> Z := IntegerRing();
> S := PolynomialRing(Z, 2);
```

If we define $S$ this way, we can only refer to the indeterminates by $S.1$ and $S.2$ (see below). So we could assign these generators to variables, say $x$ and $y$, as follows:

```magma
> x := S.1;
> y := S.2;
```

In this case it is easy to construct polynomials, but printing is slightly awkward:

```magma
> f := x^3*y +3*y^2;
> f;
$.1^3*$.2 + 3*$.2^2
```

To overcome that, it is possible to assign names to the indeterminates that are used in the printing routines, using the `AssignNames` function, before assigning to $x$ and $y$.

```magma
> AssignNames(~S, ["x", "y"]);
> x := S.1; y := S.2;
> f := x^3*y +3*y^2;
> f;
x^3*y + 3*y^2
```

Alternatively, we use the angle brackets to assign generator names that will be used in printing as well:

```magma
> S<x, y> := PolynomialRing(Z, 2);
> f := x^3*y +3*y^2;
> f;
x^3*y + 3*y^2
```

<a id="example-ex-a068bd"></a>
##### `Example: Global and Non-Global Polynomial Rings (ex-a068bd)`

We demonstrate the difference between global and non-global rings. We first create the global multivariate polynomial ring over ${\mathbb{Q}}$ with 3 variables twice.

```magma
> Q := RationalField();
> P<x,y,z> := PolynomialRing(Q, 3: Global);
> PP := PolynomialRing(Q, 3: Global);
> P;
Polynomial ring of rank 3 over Rational Field
Lexicographical Order
Variables: x, y, z
> PP;
Polynomial ring of rank 3 over Rational Field
Lexicographical Order
Variables: x, y, z
> PP.1;
x
```

$PP$ is identical to $P$. We now create default (non-global) multivariate polynomial rings (which are also different to the global polynomial ring $P$). Explicit coercion is allowed, and maps the $i$-variable of one ring to the $i$-th variable of the other ring.

```magma
> P1<a,b,c> := PolynomialRing(Q, 3);
> P2<d,e,f> := PolynomialRing(Q, 3);
> P1;
Polynomial ring of rank 3 over Rational Field
Lexicographical Order
Variables: a, b, c
> P2;
Polynomial ring of rank 3 over Rational Field
Lexicographical Order
Variables: d, e, f
> a;
a
> d;
d
> P1 ! d;
a
> P ! e;
y
```

#### Print Names

The `AssignNames` and `Name` functions can be used to associate names with the indeterminates of polynomial rings after creation.

<a id="procedure-assignnames-rngmpol-monstgelt-ref"></a>
##### `AssignNames(~P, s): RngMPol, [ MonStgElt ]`

Procedure to change the name of the indeterminates of a polynomial ring $P$. The $i$-th indeterminate will be given the name of the $i$-th element of the sequence of strings $s$ (for $1\leq i\leq \#s$); the sequence may have length less than the number of indeterminates of $P$, in which case the remaining indeterminate names remain unchanged. This procedure only changes the name used in printing the elements of $P$. It does *not* assign to identifiers corresponding to the strings the indeterminates in $P$; to do this, use an assignment statement, or use angle brackets when creating the polynomial ring. Note that since this is a procedure that modifies $P$, it is necessary to have a reference `~P` to $P$ in the call to this function.

<a id="function-name-rngmpol-rngintelt"></a>
##### `Name(P, i): RngMPol, RngIntElt -> RngMPolElt`

Given a polynomial ring $P$, return the $i$-th indeterminate of $P$ (as an element of $P$).

#### Graded Polynomial Rings

It is possible within Magma to assign weights to the variables of a multivariate polynomial ring. This means that monomials of the ring then have a *weighted degree* with respect to the weights of the variables. Such a multivariate polynomial ring is called *graded* or *weighted*. Since this subject is intimately related to ideals, it is covered in the chapter on ideals and Gröbner bases (see Subsection [Creation of Graded Polynomial Rings](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/creation.md#gb-graded)).

#### Creation of Polynomials

The easiest way to create polynomials in a given ring is to use the angle bracket construction to attach variables to the indeterminates, and then to use these variables to create polynomials (see the examples). Below we list other options.

<a id="operation-operation-rngmpol-rngint-rngmpolelt"></a>
##### `P . i: RngMPol, RngInt -> RngMPolElt`

Return the $i$-th indeterminate for the polynomial ring $P$ in $n$ variables ($1\leq i\leq n$) as an element of $P$.

<a id="constructor-constructor-elt-rngmpol-rngelt-rngmpolelt"></a>
##### `elt< R | a >: RngMPol, RngElt -> RngMPolElt`

<a id="operation-op-rngmpol-rngelt"></a>
##### `R ! s: RngMPol, RngElt -> RngMPolElt`

<a id="operation-op-rngmpol-rngelt-2"></a>
##### `R ! s: RngMPol, [ RngElt ] -> RngMPolElt`

<a id="constructor-constructor-elt-rngmpol-rngelt-rngmpolelt-2"></a>
##### `elt< R | s >: RngMPol, [ RngElt ] -> RngMPolElt`

This element constructor can only be used for trivial purposes in multivariate polynomial rings: given a polynomial ring $P=R[x_1, \ldots, x_{n}]$ and an element $a$ that can be coerced into the coefficient ring $R$, the constant polynomial $a$ is returned; if $a$ is in $P$ already it will be returned unchanged.

<a id="function-multivariatepolynomial-rngmpol-rngupolelt-rngintelt"></a>
##### `MultivariatePolynomial(P, f, i): RngMPol, RngUPolElt, RngIntElt -> RngMPolElt`

<a id="function-multivariatepolynomial-rngmpol-rngupolelt-rngmpolelt"></a>
##### `MultivariatePolynomial(P, f, v): RngMPol, RngUPolElt, RngMPolElt -> RngMPolElt`

Given a multivariate polynomial ring $P=R[x_1, \ldots, x_n]$, as well as a polynomial $f$ in a univariate polynomial ring $R[x]$ over the same coefficient ring $R$, return an element $q$ of $P$ corresponding to $f$ in the indeterminate $v=x_i$; that is, $q\in P$ is defined by $q=\sum_j f_jx_i^j$ where $f=\sum_j f_jx^j$. The indeterminate $x_i$ can either be specified as a polynomial $v=x_i$ in $P$, or by simply providing the integer $i$ with $1\leq i\leq n$. The inverse operation is performed by the `UnivariatePolynomial` function.

<a id="function-one-rngmpol"></a>
##### `One(P): RngMPol -> RngMPolElt`

<a id="function-identity-rngmpol"></a>
##### `Identity(P): RngMPol -> RngMPolElt`

<a id="function-zero-rngmpol"></a>
##### `Zero(P): RngMPol -> RngMPolElt`

<a id="function-representative-rngmpol"></a>
##### `Representative(P): RngMPol -> RngMPolElt`

### Structure Operations

#### Related Structures

The main structure related to a polynomial ring is its coefficient ring. Multivariate polynomial rings belong to the Magma category `RngMPol`.

<a id="function-basering-rngmpol"></a>
##### `BaseRing(P): RngMPol -> Rng`

<a id="function-coefficientring-rngmpol"></a>
##### `CoefficientRing(P): RngMPol -> Rng`

Return the coefficient ring of polynomial ring $P$.

<a id="function-category-rngmpol"></a>
##### `Category(P): RngMPol -> Cat`

<a id="function-parent-rngmpol"></a>
##### `Parent(P): RngMPol -> Pow`

<a id="function-primering-rngmpol"></a>
##### `PrimeRing(P): RngMPol -> Rng`

#### Numerical Invariants

Note that the `#` operator only returns a value for finite (quotients of) polynomial rings.

<a id="function-rank-rngmpol"></a>
##### `Rank(P): RngMPol -> RngIntElt`

Return the number of indeterminates of polynomial ring $P$ over its coefficient ring.

<a id="function-characteristic-rngmpol"></a>
##### `Characteristic(P): RngMPol -> RngIntElt`

<a id="operation-operation-rngmpol-rngintelt"></a>
##### `#P: RngMPol -> RngIntElt`

#### Ring Predicates and Booleans

The usual ring functions returning Boolean values are available on polynomial rings.

<a id="function-iscommutative-rngmpol"></a>
##### `IsCommutative(P): RngMPol -> BoolElt`

<a id="function-isunitary-rngmpol"></a>
##### `IsUnitary(P): RngMPol -> BoolElt`

<a id="function-isfinite-rngmpol"></a>
##### `IsFinite(P): RngMPol -> BoolElt`

<a id="function-isordered-rngmpol"></a>
##### `IsOrdered(P): RngMPol -> BoolElt`

<a id="function-isfield-rngmpol"></a>
##### `IsField(P): RngMPol -> BoolElt`

<a id="function-iseuclideandomain-rngmpol"></a>
##### `IsEuclideanDomain(P): RngMPol -> BoolElt`

<a id="function-ispid-rngmpol"></a>
##### `IsPID(P): RngMPol -> BoolElt`

<a id="function-isufd-rngmpol"></a>
##### `IsUFD(P): RngMPol -> BoolElt`

<a id="function-isdivisionring-rngmpol"></a>
##### `IsDivisionRing(P): RngMPol -> BoolElt`

<a id="function-iseuclideanring-rngmpol"></a>
##### `IsEuclideanRing(P): RngMPol -> BoolElt`

<a id="function-isdomain-rngmpol"></a>
##### `IsDomain(P): RngMPol -> BoolElt`

<a id="function-isprincipalidealring-rngmpol"></a>
##### `IsPrincipalIdealRing(P): RngMPol -> BoolElt`

<a id="operation-op-eq-rngmpol-rngmpol"></a>
##### `P eq Q: RngMPol, RngMPol -> BoolElt`

<a id="operation-op-ne-rngmpol-rngmpol"></a>
##### `P ne Q: RngMPol, RngMPol -> BoolElt`

#### Changing Coefficient Ring

The `ChangeRing` function enables the changing of the coefficient ring of a polynomial ring.

<a id="function-changering-rngmpol-rng"></a>
##### `ChangeRing(P, S): RngMPol, Rng -> RngMPol`

Given a polynomial ring $P=R[x_1, \ldots, x_n]$ of rank $n$ with coefficient ring $R$, together with a ring $S$, construct the polynomial ring $Q=S[x_1, \ldots, x_n]$. It is necessary that all elements of the old coefficient ring $R$ can be automatically coerced into the new coefficient ring $S$.

#### Homomorphisms

In its general form, a ring homomorphism taking a polynomial ring $R[x_1, \ldots, x_n]$ as domain requires $n+1$ pieces of information, namely, a map (homomorphism) telling how to map the coefficient ring $R$ together with the images of the $n$ indeterminates.

<a id="constructor-constructor-hom-rngmpol-rng-map"></a>
##### `hom< P -> S | f, y₁, ..., yₙ >: RngMPol, Rng -> Map`

<a id="constructor-constructor-hom-rngmpol-rng-map-2"></a>
##### `hom< P -> S | y₁, ..., yₙ >: RngMPol, Rng -> Map`

Given a polynomial ring $P=R[x_1,\ldots, x_n]$, a ring $S$, a map $f : R\ar S$, and $n$ elements $y_1, \ldots, y_n\in S$, create the homomorphism $g : P\ar S$ by applying the rules that $g(rx_1^{a_1}\cdots x_n^{a_n})=f(r)y_1^{a_1}\cdots y_n^{a_n}$ for monomials and linearity, that is, $g(M+N)=g(M)+g(N)$. The coefficient ring map may be omitted, in which case the coefficients are mapped into $S$ by the unitary homomorphism sending $1_R$ to $1_S$. Also, the images $y_i$ are allowed to be from a structure that allows automatic coercion into $S$.

<a id="example-ex-a59b0c"></a>
##### `Example: Homomorphism into a Number Field (ex-a59b0c)`

In this example we map ${\mathbb{Q}}[x, y]$ into the number field ${\mathbb{Q}}(\root 3 \of 2, \sqrt{5})$ by sending $x$ to $\root 3 \of 2$ and $y$ to $\sqrt{5}$ and the identity map on the coefficients (which we omit).

```magma
> Q := RationalField();
> R<x, y> := PolynomialRing(Q, 2);
> A<a> := PolynomialRing(IntegerRing());
> N<z, w> := NumberField([a^3-2, a^2+5]);
> h := hom< R -> N | z, w >;
> h(x^11*y^3-x+4/5*y-13/4);
-40*w*z^2 - z + 4/5*w - 13/4
```

### Element Operations

#### Arithmetic Operators

The usual unary and binary ring operations are available for multivariate polynomials. For polynomial rings over fields division by elements of the coefficient field are allowed (with the result in the original polynomial ring). The operator `div` has slightly different semantics from the univariate case: if $b$ divides $a$, that is, if there exists a polynomial $q\in P$ such that $a = b\cdot q\in P$ then $q$ will be the result of `a div b`, but if such polynomial does not exist an error results.

<a id="operation-operation-rngmpolelt-rngmpolelt"></a>
##### `+ a: RngMPolElt -> RngMPolElt`

<a id="operation-operation-rngmpolelt-rngmpolelt-2"></a>
##### `- a: RngMPolElt -> RngMPolElt`

<a id="operation-op-plus-rngmpolelt-rngmpolelt"></a>
##### `a + b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-op-minus-rngmpolelt-rngmpolelt"></a>
##### `a - b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-op-times-rngmpolelt-rngmpolelt"></a>
##### `a * b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-op-pow-rngmpolelt-rngintelt"></a>
##### `a ^ k: RngMPolElt, RngIntElt -> RngMPolElt`

<a id="operation-op-div-rngmpolelt-rngmpolelt"></a>
##### `a / b: RngMPolElt, RngMPolElt -> FldFunMElt`

<a id="operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt"></a>
##### `a div b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-operation-rngmpolelt-rngmpolelt-rngmpolelt"></a>
##### `a +:= b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-operation-rngmpolelt-rngmpolelt-rngmpolelt-2"></a>
##### `a -:= b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-operation-rngmpolelt-rngmpolelt-rngmpolelt-3"></a>
##### `a *:= b: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt-2"></a>
##### `a div:= b: RngMPolElt, RngMPolElt -> RngMPolElt`

#### Equality and Membership

<a id="operation-op-eq-rngmpolelt-rngmpolelt"></a>
##### `a eq b: RngMPolElt, RngMPolElt -> BoolElt`

<a id="operation-op-ne-rngmpolelt-rngmpolelt"></a>
##### `a ne b: RngMPolElt, RngMPolElt -> BoolElt`

<a id="operation-op-in-rngmpolelt-rng"></a>
##### `a in R: RngMPolElt, Rng -> BoolElt`

<a id="operation-op-notin-rngmpolelt-rng"></a>
##### `a notin R: RngMPolElt, Rng -> BoolElt`

#### Predicates on Ring Elements

The list belows contains the general ring element predicates. Also, the `IsDivisibleBy` function allows a divisibility test, and the `IsAlgebraicallyDependent` function determines if a set of ring elements is algebraically dependent. Note that not all functions are available for every coefficient ring.

<a id="function-isdivisibleby-rngmpolelt-rngmpolelt"></a>
##### `IsDivisibleBy(a, b): RngMPolElt, RngMPolElt -> BoolElt, RngMPolElt`

Given elements $a, b$ in a multivariate polynomial ring $P$, this function returns whether the polynomial $a$ is divisible by $b$ in $P$, that is, if and only if there exists $q\in P$ such that $a=q\cdot b$. If `true` is returned, the quotient polynomial $q$ is also returned.

<a id="function-isalgebraicallydependent-rngmpolelt"></a>
##### `IsAlgebraicallyDependent(S): {RngMPolElt} -> BoolElt`

Returns `true` iff the set $S$ of multivariate polynomials is algebraically dependent.

<a id="function-iszero-rngmpolelt"></a>
##### `IsZero(f): RngMPolElt -> BoolElt`

<a id="function-isone-rngmpolelt"></a>
##### `IsOne(f): RngMPolElt -> BoolElt`

<a id="function-isminusone-rngmpolelt"></a>
##### `IsMinusOne(f): RngMPolElt -> BoolElt`

<a id="function-isnilpotent-rngmpolelt"></a>
##### `IsNilpotent(f): RngMPolElt -> BoolElt`

<a id="function-isidempotent-rngmpolelt"></a>
##### `IsIdempotent(f): RngMPolElt -> BoolElt`

<a id="function-isunit-rngmpolelt"></a>
##### `IsUnit(f): RngMPolElt -> BoolElt`

<a id="function-iszerodivisor-rngmpolelt"></a>
##### `IsZeroDivisor(f): RngMPolElt -> BoolElt`

<a id="function-isregular-rngmpolelt"></a>
##### `IsRegular(f): RngMPolElt -> BoolElt`

<a id="function-isirreducible-rngmpolelt"></a>
##### `IsIrreducible(f): RngMPolElt -> BoolElt`

<a id="function-isprime-rngmpolelt"></a>
##### `IsPrime(f): RngMPolElt -> BoolElt`

<a id="coefficient-monomial-term"></a>
<a id="rngmpol-coeffs"></a>
#### Coefficients, Monomials, and Terms

Many of the functions in this subsection come in three different forms: one in which no variable is specified, which usually returns values in the coefficient ring, and two in which a particular variable is referred, either by name or by number, and these usually return values in the polynomial ring itself.

<a id="function-coefficients-rngmpolelt"></a>
##### `Coefficients(f): RngMPolElt -> [ RngElt ]`

Given a multivariate polynomial $f$ with coefficients in $R$, this function returns a sequence of ‘base’ coefficients, that is, a sequence of elements of $R$ occurring as coefficients of the monomials in $f$. Note that the monomials are ordered, and that the sequence of coefficients corresponds exactly to the sequence of monomials returned by `Monomials(f)`.

<a id="function-coefficients-rngmpolelt-rngintelt"></a>
##### `Coefficients(f, i): RngMPolElt, RngIntElt -> [ RngElt ]`

<a id="function-coefficients-rngmpolelt-rngmpolelt"></a>
##### `Coefficients(f, v): RngMPolElt, RngMPolElt -> [ RngElt ]`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns a sequence of coefficients with respect to a given variable $v=x_i$, that is, the function returns a sequence of elements of $P$ that form the coefficients of the powers of $v$ (in ascending order) when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$; note that the variable $x_i$ itself will not occur in the coefficients. There are two ways to indicate with respect to which variable the coefficients are to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-coefficient-rngmpolelt-rngintelt-rngintelt"></a>
##### `Coefficient(f, i, k): RngMPolElt, RngIntElt, RngIntElt -> RngElt`

<a id="function-coefficient-rngmpolelt-rngmpolelt-rngintelt"></a>
##### `Coefficient(f, v, k): RngMPolElt, RngMPolElt, RngIntElt -> RngElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the coefficient of $v^k=x_i^k$, that is, the function returns the element of $P$ that forms the coefficient of the $k$-th power of $x_i$, when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$; note that the variable $x_i$ itself will not occur in the coefficient. There are two ways to indicate with respect to which variable the coefficient is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-leadingcoefficient-rngmpolelt"></a>
##### `LeadingCoefficient(f): RngMPolElt -> RngElt`

Given a multivariate polynomial $f$ with coefficients in $R$, this function returns the leading coefficient of $f$ as an element of $R$; this is the coefficient of the leading monomial of $f$, that is, the first among the monomials occurring in $f$ with respect to the ordering of monomials used in $P$.

<a id="function-leadingcoefficient-rngmpolelt-rngintelt"></a>
##### `LeadingCoefficient(f, i): RngMPolElt, RngIntElt -> RngElt`

<a id="function-leadingcoefficient-rngmpolelt-rngmpolelt"></a>
##### `LeadingCoefficient(f, v): RngMPolElt, RngMPolElt -> RngElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the element of $P$ that forms the coefficient of the largest power of $v=x_i$ that occurs with non-zero coefficient in $f$, when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$; note that the variable $x_i$ itself will not occur in the coefficient. There are two ways to indicate with respect to which variable the leading coefficient is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-length-rngmpolelt"></a>
##### `Length(f): RngMPolElt -> RngIntElt`

Given a multivariate polynomial $f$, return the length of $f$, i.e., the number of terms of $f$.

<a id="function-trailingcoefficient-rngmpolelt"></a>
##### `TrailingCoefficient(f): RngMPolElt -> RngElt`

Given a multivariate polynomial $f$ with coefficients in $R$, this function returns the trailing coefficient of $f$ as an element of $R$; this is the coefficient of the trailing monomial of $f$, that is, the last among the monomials occurring in $f$ with respect to the ordering of monomials used in $P$.

<a id="function-trailingcoefficient-rngmpolelt-rngintelt"></a>
##### `TrailingCoefficient(f, i): RngMPolElt, RngIntElt -> RngElt`

<a id="function-trailingcoefficient-rngmpolelt-rngmpolelt"></a>
##### `TrailingCoefficient(f, v): RngMPolElt, RngMPolElt -> RngElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the element of $P$ that forms the coefficient of the least power of $v=x_i$ that occurs with non-zero coefficient in $f$, when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$; note that the variable $x_i$ itself will not occur in the coefficient. There are two ways to indicate with respect to which variable the leading coefficient is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-coefficientdenominator-rngmpolelt"></a>
##### `CoefficientDenominator(f): RngMPolElt -> RngElt`

<a id="function-coefficientnumerator-rngmpolelt"></a>
##### `CoefficientNumerator(f): RngMPolElt -> RngElt`

Given a multivariate polynomial $f$ with coefficients in $\Q$, a rational function field, or a field of fractions of an order of a number or function field, return the LCM of the denominators of the coefficients of $f$ (`CoefficientDenominator`) or the product of that LCM with $f$ itself (`CoefficientNumerator`).

<a id="function-monomialcoefficient-rngmpolelt-rngmpolelt"></a>
##### `MonomialCoefficient(f, m): RngMPolElt, RngMPolElt -> RngElt`

Given a multivariate polynomial $f$ and a monomial $m$, both in $P\in R[x_1, \ldots, x_n]$, this function returns the coefficient with which $m$ occurs in $f$ as an element of $R$.

<a id="function-monomials-rngmpolelt"></a>
##### `Monomials(f): RngMPolElt -> [ RngMPolElt ]`

Given a multivariate polynomial $f\in P$, this function returns a sequence of monomials, that is, a sequence of monomial elements of $P$ occurring in $f$. Note that the monomials in $P$ are ordered, and that the sequence of monomials corresponds exactly to the sequence of coefficients returned by `Coefficients(f)`.

<a id="function-coefficientsandmonomials-rngmpolelt"></a>
##### `CoefficientsAndMonomials(f): RngMPolElt -> [ RngElt ], [ RngMPolElt ]`

Given a multivariate polynomial $f\in P$, this function returns parallel sequences $C$ and $M$ of the coefficients and monomials, respectively, of $f$. Thus this function is equivalent to calling `Coefficients` and `Monomials` separately, but is more efficient (particularly for large polynomials) since only one scan of the polynomial needs to be done.

<a id="function-leadingmonomial-rngmpolelt"></a>
##### `LeadingMonomial(f): RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P$ this function returns the leading monomial of $f$, that is, the first monomial element of $P$ that occurs in $f$, with respect to the ordering of monomials used in $P$.

<a id="function-terms-rngmpolelt"></a>
##### `Terms(f): RngMPolElt -> [ RngMPolElt ]`

Given a multivariate polynomial $f\in P$, this function returns the sequence of (non-zero) terms of $f$ as elements of $P$. The terms are ordered according to the ordering on the monomials in $P$. Consequently the $i$-th element of this sequence of terms will be equal to the product of the $i$-th element of the sequence of coefficients and the $i$-th element of the sequence of monomials.

<a id="function-terms-rngmpolelt-rngintelt"></a>
##### `Terms(f, i): RngMPolElt, RngIntElt -> [ RngMPolElt ]`

<a id="function-terms-rngmpolelt-rngmpolelt"></a>
##### `Terms(f, v): RngMPolElt, RngMPolElt -> [ RngMPolElt ]`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns a sequence of terms with respect to a given variable $v=x_i$, that is, the function returns a sequence of elements of $P$ that form the terms (ascending order) of $f$ regarded as a polynomial $\sum_j c_j x_i^j$. There are two ways to indicate with respect to which variable the terms are to be ordered: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-term-rngmpolelt-rngintelt-rngintelt"></a>
##### `Term(f, i, k): RngMPolElt, RngIntElt, RngIntElt -> RngMPolElt`

<a id="function-term-rngmpolelt-rngmpolelt-rngintelt"></a>
##### `Term(f, v, k): RngMPolElt, RngMPolElt, RngIntElt -> RngMPolElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the $k$-th term of $f$ (with $k\geq 0$), that is, the function returns the term of $f$ involving the $k$-th power of $x_i$, when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$. There are two ways to indicate with respect to which variable the term is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-leadingterm-rngmpolelt"></a>
##### `LeadingTerm(f): RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P$, this function returns the leading term of $f$ as an element of $P$; this is the product of the leading monomial and the leading coefficient that is, the first among the monomial terms occurring in $f$ with respect to the ordering of monomials used in $P$.

<a id="function-leadingterm-rngmpolelt-rngintelt"></a>
##### `LeadingTerm(f, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-leadingterm-rngmpolelt-rngmpolelt"></a>
##### `LeadingTerm(f, v): RngMPolElt, RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the element of $P$ that forms the leading term of $f$ when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$. Thus it is the term involving the largest power of $x_i$ that occurs with non-zero coefficient. There are two ways to indicate with respect to which variable the leading coefficient is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-trailingterm-rngmpolelt"></a>
##### `TrailingTerm(f): RngMPolElt -> RngElt`

Given a multivariate polynomial $f\in P$, this function returns the trailing term of $f$ as an element of $P$; this is the last among the monomial terms occurring in $f$ with respect to the ordering of monomials used in $P$.

<a id="function-trailingterm-rngmpolelt-rngintelt"></a>
##### `TrailingTerm(f, i): RngMPolElt, RngIntElt -> RngElt`

<a id="function-trailingterm-rngmpolelt-rngmpolelt"></a>
##### `TrailingTerm(f, v): RngMPolElt, RngMPolElt -> RngElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the element of $P$ that forms the trailing term of $f$ when $f$ is regarded as a polynomial $\sum_j c_j x_i^j$. Thus it is the term involving the least power of $x_i$ that occurs with non-zero coefficient. There are two ways to indicate with respect to which variable the leading coefficient is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-exponents-rngmpolelt"></a>
##### `Exponents(f): RngMPolElt -> [ RngIntElt ]`

Given a single term $f$ (a polynomial having exactly one term) in a polynomial ring of rank $n$, return the exponents of the monomial of $f$, as a sequence of length $n$ of integers. (The coefficient of $f$ is ignored; it need not be $1$.)

<a id="function-monomial-rngmpol-rngintelt"></a>
##### `Monomial(P, E): RngMPol, [ RngIntElt ] -> RngMPolElt`

Given a multivariate polynomial ring $P = R[x_1, \ldots, x_n]$, and a sequence $E$ of non-negative integers, return the monomial ${x_1}^{E[1]}\ldots {x_n}^{E[n]}$ in $P$. This function is a semi-inverse of `Exponents`.

<a id="function-polynomial-rngelt-rngmpolelt"></a>
##### `Polynomial(C, M): [RngElt], [RngMPolElt] -> RngMPolElt`

Given a length-$k$ sequence $C$ of coefficients in a ring $R$ and a length-$k$ sequence $M$ of monomials of a polynomial ring $R$, return the multivariate polynomial $f\in R$ whose coefficients are $C$ and monomials are $M$. (Thus for any $f\in R$, `Polynomial(Coefficients(f), Monomials(f))` equals $f$.)

<a id="example-ex-f062e9"></a>
##### `Example: Coefficients and Monomials (ex-f062e9)`

In this and the next example we illustrate the coefficient and term functions, using the polynomial in three variables $x, y, z$ over the rational field that is given by $f=(2x+y)z^3+11xyz+x^2y^2$.

```magma
> R<x, y, z> := PolynomialAlgebra(RationalField(), 3);
> f := (2*x+y)*z^3+11*x*y*z+x^2*y^2;
> f;
x^2*y^2 + 11*x*y*z + 2*x*z^3 + y*z^3
> Coefficients(f);
[ 1, 11, 2, 1 ]
> Monomials(f);
[
   x^2*y^2,
   x*y*z,
   x*z^3,
   y*z^3
]
> CoefficientsAndMonomials(f);
[ 1, 11, 2, 1 ]
[
    x^2*y^2,
    x*y*z,
    x*z^3,
    y*z^3
]
> Terms(f);
[
   x^2*y^2,
   11*x*y*z,
   2*x*z^3,
   y*z^3
]
> Coefficients(f, y);
[
   2*x*z^3,
   11*x*z + z^3,
   x^2
]
> Terms(f, 2);
[
   2*x*z^3,
   11*x*y*z + y*z^3,
   x^2*y^2
]
> MonomialCoefficient(f, x*y*z);
11
> LeadingTerm(f);
x^2*y^2
> LeadingTerm(f, z);
2*x*z^3 + y*z^3
> LeadingCoefficient(f, z);
2*x + y
> Polynomial([1, 2, 3], [x*y, y, z^2]);
x*y + 2*y + 3*z^2
```

#### Degrees

<a id="function-degree-rngmpolelt-rngintelt"></a>
##### `Degree(f, i): RngMPolElt, RngIntElt -> RngIntElt`

<a id="function-degree-rngmpolelt-rngmpolelt"></a>
##### `Degree(f, v): RngMPolElt, RngMPolElt -> RngIntElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the degree of $f$ in $v^k=x_i^k$, that is, the function returns the degree of $f$ when it is regarded as a polynomial $\sum_j c_j x_i^j$. The resulting integer is thus the largest power of $x_i$ occurring in any monomial of $f$. There are two ways to indicate with respect to which variable the degree is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$). If $f$ is the zero polynomial, the return value is always $-1$.

<a id="function-totaldegree-rngmpolelt"></a>
##### `TotalDegree(f): RngMPolElt -> RngIntElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the total degree of $f$, which is the maximum of the total degrees of all monomials that occur in $f$. The total degree of a monomial $m$ is the sum of the exponents of the indeterminates that make up $m$. Note that this ignores the weights on the variables if there are any (see the section on graded polynomial rings below). If $f$ is the zero polynomial, the return value is $-1$.

<a id="function-leadingtotaldegree-rngmpolelt"></a>
##### `LeadingTotalDegree(f): RngMPolElt -> RngIntElt`

Given a multivariate polynomial $f\in P = R[x_1, \ldots, x_n]$, this function returns the leading total degree of $f$, which is the total degree of the leading monomial of $f$. If $f$ is the zero polynomial, the return value is $-1$.

#### Univariate Polynomials

<a id="function-isunivariate-rngmpolelt"></a>
##### `IsUnivariate(f): RngMPolElt -> BoolElt, RngUPolElt, RngIntElt`

Given a multivariate polynomial $f\in R[x_1, \ldots, x_n]$, this function returns whether $f$ is in fact a univariate polynomial in one of its indeterminates $x_1, \ldots, x_n$. If true is returned, then the function also returns a univariate version $u$ of $f$ and (the first) $i$ such that $f$ is univariate in $x_i$. Note that there will only be ambiguity about $i$ if $f$ is a constant polynomial. The univariate polynomial $u$ will be an element of $R[x]$ with the same coefficients as $f$.

<a id="function-isunivariate-rngmpolelt-rngintelt"></a>
##### `IsUnivariate(f, i): RngMPolElt, RngIntElt -> BoolElt, RngUPolElt`

<a id="function-isunivariate-rngmpolelt-rngmpolelt"></a>
##### `IsUnivariate(f, v): RngMPolElt, RngMPolElt -> BoolElt, RngUPolElt`

Given a multivariate polynomial $f\in R[x_1, \ldots, x_n]$, this function returns whether $f$ is in fact a univariate polynomial in $x_i$. If true is returned, then the function also returns a univariate version $u$ of $f$, which will be an element of the univariate polynomial ring $R[x]$ with the same coefficients as $f$. The indeterminate $x_i$ should either be specified as a (polynomial) argument $v$ or as an integer $i$.

<a id="function-univariatepolynomial-rngmpolelt"></a>
##### `UnivariatePolynomial(f): RngMPolElt -> RngUPolElt`

Given a multivariate polynomial $f\in R[x_1, \ldots, x_n]$, which is known to be a univariate polynomial in $x_i$ for some $i$ with $1\leq i\leq n$, return a univariate version $u$ of $f$, which will be an element of the univariate polynomial ring $R[x]$ with the same coefficients as $f$.

<a id="example-ex-f54865"></a>
##### `Example: Converting to a Univariate Polynomial (ex-f54865)`

Suppose we have two bivariate polynomials $f$ and $g$ over some ring.

```magma
> P<x,y> := PolynomialRing(GF(5), 2);
> f := x^2 - y + 3;
> g := y^3 - x*y + x;
```

If we compute the resultant in either variable of the two polynomials, then we can apply `UnivariatePolynomial` to this to obtain a univariate version of it, from which we can compute the roots.

```magma
> ry := Resultant(f, g, y);
> ry;
4*x^6 + x^4 + x^3 + 3*x^2 + 2*x + 3
> Roots(UnivariatePolynomial(ry));
[ <3, 1> ]
> Evaluate(f, x, 3);
4*y + 2
> Evaluate(g, x, 3);
y^3 + 2*y + 3
> GCD($1, $2);
y + 3
> rx := Resultant(f, g, x);
> rx;
y^6 + 4*y^3 + 3*y + 3
> Roots(UnivariatePolynomial(rx));
[ <2, 1> ]
> Evaluate(f, y, 2);
x^2 + 1
> Evaluate(g, y, 2);
4*x + 3
> GCD($1, $2);
x + 2
```

#### Derivative, Integral

<a id="function-derivative-rngmpolelt-rngintelt"></a>
##### `Derivative(f, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-derivative-rngmpolelt-rngmpolelt"></a>
##### `Derivative(f, v): RngMPolElt, RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P$, return the derivative of $f$ with respect to the variable $v=x_i$, as an element of $P$. There are two ways to indicate with respect to which variable the derivative is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-derivative-rngmpolelt-rngintelt-2"></a>
##### `Derivative(f, k, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-derivative-rngmpolelt-rngmpolelt-2"></a>
##### `Derivative(f, k, v): RngMPolElt, RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P$ and an integer $k > 0$, return the $k$-th derivative of $f$ with respect to the variable $v=x_i$, as an element of $P$. There are two ways to indicate with respect to which variable the derivative is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-integral-rngmpolelt-rngintelt"></a>
##### `Integral(f, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-integral-rngmpolelt-rngmpolelt"></a>
##### `Integral(f, v): RngMPolElt, RngMPolElt -> RngMPolElt`

Given a multivariate polynomial $f\in P$ over a field of characteristic zero, return the formal integral of $f$ with respect to $v=x_i$ as an element of $P$. There are two ways to indicate with respect to which variable the integral is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

<a id="function-jacobianmatrix-rngmpolelt"></a>
##### `JacobianMatrix([ f ]): [ RngMPolElt ] -> RngMPol`

Creates the matrix with $(i,j)$’th entry the partial derivative of the $i$’th polynomial in the list with the $j$’th indeterminate of its parent ring.

#### Evaluation, Interpolation

<a id="function-evaluate-rngmpolelt-rngelt"></a>
##### `Evaluate(f, s): RngMPolElt, [ RngElt ] -> RngElt`

<a id="function-evaluate-rngmpolelt-rngelt-rngelt"></a>
##### `Evaluate(f, s): RngMPolElt, < RngElt, ..., RngElt > -> RngElt`

Given an element $f$ of a polynomial ring $P=R[x_1, \ldots, x_n]$ and a sequence or tuple $s$ of ring elements of length $n$, return the value of $f$ at $s$, that is, obtained by substituting $x_i=s[i]$. If the elements of $s$ can be lifted into the coefficient ring $R$, then the result will be an element of $R$. If the elements of $s$ cannot be lifted to the coefficient ring, then an attempt is made to do a generic evaluation of $f$ at $s$. In this case, the result will be of the same type as the elements of $s$.

<a id="function-evaluate-rngmpolelt-rngmpolelt-rngelt"></a>
##### `Evaluate(f, i, r): RngMPolElt, RngMPolElt, RngElt -> RngMPolElt`

<a id="function-evaluate-rngmpolelt-rngmpolelt-rngelt-2"></a>
##### `Evaluate(f, v, r): RngMPolElt, RngMPolElt, RngElt -> RngMPolElt`

Given an element $f$ of a multivariate polynomial ring $P$ and a ring element $r$ return the value of $f$ when the variable $v=x_i$ is evaluated at $r$. If $r$ can be coerced into the coefficient ring of $P$, the result will be an element in $P$ again. Otherwise the other variables of $P$ must be coercible into the parent of $r$, and the result will have the same parent as $r$.

<a id="function-interpolation-rngelt-rngmpolelt-rngintelt"></a>
##### `Interpolation(I, V, i): [ RngElt ], [ RngMPolElt ], RngIntElt -> RngMPolElt`

<a id="function-interpolation-rngelt-rngmpolelt-rngintelt-2"></a>
##### `Interpolation(I, V, v): [ RngElt ], [ RngMPolElt ], RngIntElt -> RngMPolElt`

Let $K$ be a field, and $P=K[x_1, \ldots, x_n]$ a multivariate polynomial ring over $K$; let $v=x_i$ be the $i$-th indeterminate of $P$. Given a sequence $I$ of elements of $K$ (the interpolation points) and a sequence $V$ of elements of $P$ (the interpolation values), both sequences of length $k>0$, return the unique polynomial $f\in P$ of degree less than $k$ in the variable $x_i$ such that $f(I[j]) = V[j]$, for $j=1, \ldots, k$. The variable $x_i$ may not occur anywhere in the values $V$. There are two ways to indicate with respect to which variable to interpolate: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable or the variable $v$ itself (as a polynomial).

<a id="example-ex-ca9d39"></a>
##### `Example: Polynomial Interpolation (ex-ca9d39)`

We define $P={\mathbb{Q}}[x, y, z]$, and give an example of interpolation. We find a polynomial which, when evaluated in the first variable $x$ in the rational points $1, 2, 3$, yields $y, z, y+z$ respectively. We check the result by evaluating.

```magma
> Q := RationalField();
> P<x, y, z> := PolynomialRing(Q, 3);
> f := Interpolation([Q | 1, 2, 3], [y, z, y + z], 1);
> f;
x^2*y - 1/2*x^2*z - 4*x*y + 5/2*x*z + 4*y - 2*z
> [ Evaluate(f, 1, v) : v in [1, 2, 3] ];
[
   y,
   z,
   y + z
]
```

#### Quotient and Reductum

<a id="operation-operation-div-rngmpolelt-rngmpolelt-rngmpolelt-3"></a>
##### `f div g: RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="function-exactquotient-rngmpolelt-rngmpolelt"></a>
##### `ExactQuotient(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

The quotient of the multivariate polynomial $f$ by $g$ in $R[x_1, \ldots, x_n]$, provided the result lies in $P$ again. If a polynomial $q$ in $P$ exists such that $f=q\cdot g$ then it will be returned, but if none exists an error results. When $R$ is a domain the quotient is unique and is always found. Over a ring with zero divisors the quotient need not be unique, and the function may report that $g$ does not divide $f$ even when it does.

<a id="function-reductum-rngmpolelt"></a>
##### `Reductum(f): RngMPolElt -> RngMPolElt`

The reductum of a polynomial $f$, which is the polynomial obtained by removing the leading term of $f$.

<a id="function-reductum-rngmpolelt-rngintelt"></a>
##### `Reductum(f, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-reductum-rngmpolelt-rngmpolelt"></a>
##### `Reductum(f, v): RngMPolElt, RngMPolElt -> RngMPolElt`

The reductum of a multivariate polynomial $f\in R[x_1, \ldots, x_n]$ obtained by removing the leading term with respect to the variable $v=x_i$. Here either $v$ must be specified as a polynomial, or $x_i$ must be specified by providing the integer $i$, with $1\leq i\leq n$.

#### Diagonalizing a Polynomial of Degree 2

We provide two basic tools that deal with polynomial diagonalization.

<a id="function-symmetricbilinearform-rngmpolelt"></a>
##### `SymmetricBilinearForm(f): RngMPolElt -> ModMatRngElt`

The symmetric bilinear form (as a matrix) of a multivariate polynomial of degree 2.

<a id="function-diagonalform-rngmpolelt"></a>
##### `DiagonalForm(f): RngMPolElt -> RngMPolElt, ModMatRngElt`

The diagonal form of the multivariate polynomial of degree 2. Also returns the transformation matrix.

<a id="example-ex-649fdb"></a>
##### `Example: Symmetric Bilinear Form of a Quadratic Polynomial (ex-649fdb)`

```magma
> Q := RationalField();
> PR<x, y, z> := PolynomialRing(Q, 3);
> g := 119/44*x^2 - 93759/41440*x*y + 390935/91427*x*z
>      + 212/243*x - 3/17*y^2 + 52808/172227*y*z
>      - 287/227*y + 537/934*z^2 - 127/422*z;
> SymmetricBilinearForm(g);
[       119/44  -93759/82880 390935/182854       106/243]
[ -93759/82880         -3/17  26404/172227      -287/454]
[390935/182854  26404/172227       537/934      -127/844]
[      106/243      -287/454      -127/844             0]
> DiagonalForm(g);
119/44*x^2 - 15798558582429/4*y^2 +
34932799628335074761085292707227419544217/934*z^2 -
176588732861018934524371210556883645619275217398116147234837710457404146371/2
>
> bl := SymmetricBilinearForm(g);
> NBL := Matrix(PR, bl);
> D, T := OrthogonalizeGram(bl);
> NT := Matrix(PR, T);
> C := Matrix(PR, [[x,y,z,1]]);
> NC := C * NT;
> NCT := Transpose(NC);
> (NC * NBL * NCT)[1][1] eq DiagonalForm(g);
true
```

The last few statements demonstrate how the polynomial’s diagonal form is obtained from its symmetric bilinear form. Note also that since the polynomial $g$ is not homogeneous its symmetric bilinear form is given on four variables, the fourth variable being a homogenizing variable.

### Greatest Common Divisors

The functions in this section can be applied to multivariate polynomials over any ring which has a GCD algorithm.

#### Common Divisors and Common Multiples

<a id="function-greatestcommondivisor-rngmpolelt-rngmpolelt"></a>
##### `GreatestCommonDivisor(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="function-gcd-rngmpolelt-rngmpolelt"></a>
##### `Gcd(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="function-gcd-rngmpolelt-rngmpolelt-2"></a>
##### `GCD(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

The greatest common divisor of $f$ and $g$ in a multivariate polynomial ring $P$. If either of the inputs is zero, then the result is the other input (and if the inputs are both zero then the result is zero). The result is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-dpoly-normalize)), so the result is always unique.

The valid coefficient rings are those which themselves have a GCD algorithm for their elements (which includes most commutative rings in Magma).

For polynomials over the integers or rationals, a combination of three algorithms is used: (1) the heuristic evaluation ‘GCDHEU’ algorithm of Char et al. ([[CGG89](https://docs.magma-maths.org/references.md#cite-gcdheu)] and [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 7.7]), suitable for moderate-degree dense polynomials with several variables; (2) the EEZ-GCD algorithm of Wang ([[MY73](https://docs.magma-maths.org/references.md#cite-mosesyun-ezgcd), [Wan80](https://docs.magma-maths.org/references.md#cite-wang-eez)] and [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 7.6]), based on evaluation and sparse ideal-adic multivariate Hensel lifting ([[Wan78](https://docs.magma-maths.org/references.md#cite-wang-fact)] and [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 6.8]), suitable for sparse polynomials; (3) a recursive multivariate evaluation-interpolation algorithm (similar to that in [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 7.4]), which in fact works generically over ${\mathbb{Z}}$ or most fields.

For polynomials over any finite field or any field of characteristic zero besides ${\mathbb{Q}}$, the generic recursive multivariate evaluation-interpolation algorithm (3) above is used, which effectively takes advantage of any fast modular algorithm for the base univariate polynomials (e.g., for number fields). See the function [`GreatestCommonDivisor`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/common.md#function-vpoly-gcd) in the univariate polynomials chapter for details of univariate GCD algorithms.

For polynomials over another polynomial ring or rational function field, the polynomials are first “flattened” to be inside a multivariate polynomial ring over the base coefficient ring, then the appropriate algorithm is used for that base coefficient ring.

For polynomials over any other ring, the generic subresultant algorithm [[Coh93](https://docs.magma-maths.org/references.md#cite-cohen1), section 3.3] is called recursively on a subring with one less variable.

<a id="function-gcd-rngmpolelt"></a>
##### `GCD(Q): [ RngMPolElt ] -> RngMPolElt`

Given a sequence $Q$ of polynomials, return the GCD of the elements of $Q$. If $Q$ has length 0 and universe $P$, then the zero element of $P$ is returned.

<a id="function-leastcommonmultiple-rngmpolelt-rngmpolelt"></a>
##### `LeastCommonMultiple(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="function-lcm-rngmpolelt-rngmpolelt"></a>
##### `Lcm(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

<a id="function-lcm-rngmpolelt-rngmpolelt-2"></a>
##### `LCM(f, g): RngMPolElt, RngMPolElt -> RngMPolElt`

The least common multiple of $f$ and $g$ in a multivariate polynomial ring $P$. The LCM of zero and anything else is zero. The result is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-dpoly-normalize)), so the result is always unique. The valid coefficient rings are as for the function `GCD`, above.

The LCM is effectively computed as `Normalize((F div GCD(F, G)) * G)`, for non-zero inputs.

<a id="function-lcm-rngmpolelt"></a>
##### `LCM(Q): [ RngMPolElt ] -> RngMPolElt`

Given a sequence $Q$ of polynomials, return the LCM of the elements of $Q$. If $Q$ has length 0 and universe $P$, then the one element of $P$ is returned.

<a id="function-dpoly-normalize"></a>
##### `Normalize(f): RngMPolElt -> RngMPolElt`

Given a polynomial $f$ over the base ring $R$, this function returns the unique normalized polynomial $g$ which is associate to $f$ (so $g=uf$ for some unit in $R$). This is chosen so that if $R$ is a field then $g$ is monic, if $R$ is ${\mathbb{Z}}$ then the leading coefficient of $g$ is positive, if $R$ is a polynomial ring itself, then the leading coefficient of $g$ is recursively normalized, and so on for other rings.

<a id="function-cleardenominators-rngmpolelt"></a>
##### `ClearDenominators(f): RngMPolElt -> RngMPolElt`

<a id="function-cleardenominators-rngmpolelt-2"></a>
##### `ClearDenominators(Q): [ RngMPolElt ] -> [ RngMPolElt ]`

Given a polynomial $f$ over a field $K$ such that $K$ is the field of fractions of a domain $D$, the first function computes the lowest common denominator $L$ of the coefficients of $f$ and returns the polynomial $g=L\cdot f$ over $D$ with cleared denominators, and $L$. The second function returns the sequence of polynomials derived from independently clearing the denominators in each polynomial in the given sequence $Q$.

#### Content and Primitive Part

<a id="function-content-rngmpolelt"></a>
##### `Content(f): RngMPolElt -> RngIntElt`

The content of $f$, that is, the greatest common divisor of the coefficients of $f$ as an element of the coefficient ring.

<a id="function-primitivepart-rngmpolelt"></a>
##### `PrimitivePart(f): RngMPolElt -> RngMPolElt`

The primitive part of $f$, being $f$ divided by the content of $f$.

<a id="function-contentandprimitivepart-rngmpolelt"></a>
##### `ContentAndPrimitivePart(f): RngMPolElt -> RngIntElt, RngMPolElt`

<a id="function-contpp-rngmpolelt"></a>
##### `Contpp(f): RngMPolElt -> RngIntElt, RngMPolElt`

The content (the greatest common divisor of the coefficients) of $f$, as an element of the coefficient ring, as well as the primitive part ($f$ divided by the content) of $f$.

### Factorization and Irreducibility

We describe the functions for multivariate polynomial factorization and associated computations.

<a id="function-factorization-rngmpolelt"></a>
#### `Factorization(f): RngMPolElt -> [ < RngMPolElt, RngIntElt >], RngElt`

Given a multivariate polynomial $f$ over the ring $R$, this function returns the factorization of $f$ as a factorization sequence $Q$, that is, a sequence of pairs, each consisting of an irreducible factor $q_i$ a positive integer $k_i$ (its multiplicity). Each irreducible factor is normalized (see the function [`Normalize`](https://docs.magma-maths.org/BasicRings/MultivariatePolynomialRings/common.md#function-dpoly-normalize)), so the expansion of the factorization sequence is the unique canonical associate of $f$. The function also returns the unit $u$ of $R$ giving the normalization, so $f=u\cdot \prod_i q_i^{k_i}$.

The coefficient ring $R$ must be one of the following: a finite field ${\mathbb{F}}_q$, the ring of integers ${\mathbb{Z}}$, the field of rationals ${\mathbb{Q}}$, an algebraic number field ${\mathbb{Q}}(\alpha)$, or a polynomial ring, function field (rational or algebraic) or finite-dimensional affine algebra (which is a field) over any of the above.

For bivariate polynomials, a polynomial-time algorithm in the same spirit as van Hoeij’s Knapsack factoring algorithm [[vH02](https://docs.magma-maths.org/references.md#cite-vhoeij1)] is used.

For polynomials over the integers or rationals, an algorithm similar to that presented in [[Wan78](https://docs.magma-maths.org/references.md#cite-wang-fact)] and [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), section 6.8], based on evaluation and sparse ideal-adic multivariate Hensel lifting, is used.

For polynomials over any finite field, a similar algorithm is used, with a few special modifications for non-zero characteristic (see, for example, [[BM97](https://docs.magma-maths.org/references.md#cite-bernardinmonagan-fact)]).

For polynomials over algebraic number fields and affine algebras, a multivariate version of the norm-based algorithm of Trager [[Tra76](https://docs.magma-maths.org/references.md#cite-trager-factorization)] is used, which performs a suitable substitution and multivariate resultant computation, and then factors the resulting integral multivariate polynomial.

Each of these algorithms reduces to univariate factorization over the base ring; for details of how this factorization is done in each case, see the function [`Factorization`](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#function-vpoly-factorization) in the univariate polynomial rings chapter.

For polynomials over another polynomial ring or function field, the polynomials are first “flattened” to be inside a multivariate polynomial ring over the base coefficient ring, then the appropriate algorithm is used for that base coefficient ring.

<a id="function-squarefreefactorization-rngmpolelt"></a>
#### `SquarefreeFactorization(f): RngMPolElt -> [ <RngMPolElt, RngIntElt> ]`

Return the squarefree factorization of the multivariate polynomial $f$ as a sequence of tuples of length 2, each consisting of a (not necessarily irreducible) factor and an integer indicating the multiplicity. The factors do not contain the square of any polynomial of degree greater than 0. The allowable coefficient rings are the same as those allowable for the function `Factorization`.

<a id="function-squarefreepart-rngmpolelt"></a>
#### `SquarefreePart(f): RngMPolElt -> RngMPolElt`

Return the squarefree part of the multivariate polynomial $f$, which is the largest (normalized) divisor $g$ of $f$ which is squarefree.

<a id="function-isirreducible-rngmpolelt-2"></a>
#### `IsIrreducible(f): RngMPolElt -> BoolElt`

Given a multivariate polynomial $f$ over a ring $R$, this function returns whether $f$ is irreducible over $R$. The allowable coefficient rings are the same as those allowable for the function `Factorization`.

<a id="procedure-setverbose-monstgelt-rngintelt-polyfact"></a>
#### `SetVerbose("PolyFact", v): MonStgElt, RngIntElt`

(Procedure.) Change the verbose printing level for all polynomial factorization algorithms to be $v$. Currently the legal levels are 0, 1, 2, or 3.

<a id="example-ex-2f44bb"></a>
#### `Example: Factorizing a Product of Trinomials (ex-2f44bb)`

We create a polynomial $f$ in the polynomial ring in three indeterminates over the ring of integers by multiplying together various trinomials. The resulting product $f$ has 461 terms and total degree 15. We then factorize $f$ to recover the trinomials.

```magma
> P<x, y, z> := PolynomialRing(IntegerRing(), 3);
> f := &*[x^i+y^j+z^k: i,j,k in [1..2]];
> #Terms(f);
461
> TotalDegree(f);
15
> time Factorization(f);
[
    <x + y + z, 1>,
    <x + y + z^2, 1>,
    <x + y^2 + z, 1>,
    <x + y^2 + z^2, 1>,
    <x^2 + y + z, 1>,
    <x^2 + y + z^2, 1>,
    <x^2 + y^2 + z, 1>,
    <x^2 + y^2 + z^2, 1>
]
Time: 0.290
```

<a id="example-ex-12897c"></a>
#### `Example: Factorizing a Vandermonde Determinant (ex-12897c)`

We construct a Vandermonde matrix of rank 6, find its determinant, and factorize that determinant.

```magma
> // Create polynomial ring over R of rank n
> PRing := function(R, n)
>     P := PolynomialRing(R, n);
>     AssignNames(~P, ["x" cat IntegerToString(i): i in [1..n]]);
>     return P;
> end function;
>
> // Create Vandermonde matrix of rank n
> Vandermonde := function(n)
>     P := PRing(IntegerRing(), n);
>     return MatrixRing(P, n) ! [P.i^(j - 1): i, j in [1 .. n]];
> end function;
>
> V := Vandermonde(6);
> V;
[   1   x1 x1^2 x1^3 x1^4 x1^5]
[   1   x2 x2^2 x2^3 x2^4 x2^5]
[   1   x3 x3^2 x3^3 x3^4 x3^5]
[   1   x4 x4^2 x4^3 x4^4 x4^5]
[   1   x5 x5^2 x5^3 x5^4 x5^5]
[   1   x6 x6^2 x6^3 x6^4 x6^5]
> D := Determinant(V);
> #Terms(D);
720
> TotalDegree(D);
15
> time Factorization(D);
[
    <x5 - x6, 1>,
    <x4 - x6, 1>,
    <x4 - x5, 1>,
    <x3 - x6, 1>,
    <x3 - x5, 1>,
    <x3 - x4, 1>,
    <x2 - x6, 1>,
    <x2 - x5, 1>,
    <x2 - x4, 1>,
    <x2 - x3, 1>,
    <x1 - x6, 1>,
    <x1 - x5, 1>,
    <x1 - x4, 1>,
    <x1 - x3, 1>,
    <x1 - x2, 1>
]
Time: 0.030
```

<a id="example-ex-f94225"></a>
#### `Example: Heron's Formula for the Area of a Triangle (ex-f94225)`

We construct a polynomial $A2$ in three indeterminates $a$, $b$, and $c$ over the rational field such that $A2$ is the square of the area of the triangle with side lengths $a$, $b$, $c$. Using elementary trigonometry one can derive the expression $(4*a^2*b^2 - (a^2 + b^2 - c^2)^2)/16$ for $A2$. Factorizing $A2$ gives a nice formulation of the square of the area which is similar to that given by *Heron’s formula*.

```magma
> P<a, b, c> := PolynomialRing(RationalField(), 3);
> A2 := 1/16 * (4*a^2*b^2 - (a^2 + b^2 - c^2)^2);
> A2;
-1/16*a^4 + 1/8*a^2*b^2 + 1/8*a^2*c^2 - 1/16*b^4 + 1/8*b^2*c^2 - 1/16*c^4
> F, u := Factorization(A2);
> F;
[
    <a - b - c, 1>,
    <a - b + c, 1>,
    <a + b - c, 1>,
    <a + b + c, 1>
]
> u;
-1/16
```

<a id="example-ex-8e8a69"></a>
#### `Example: Finite Field Factorization (ex-8e8a69)`

We factorize a multivariate polynomial over a finite field.

```magma
> Frob := function(G)
>     n := #G;
>     I := {@ g: g in G @};
>     P := PolynomialRing(GF(2), n);
>     AssignNames(~P, [CodeToString(96 + i): i in [1 .. n]]);
>     M := MatrixRing(P, n);
>     return M ! &cat[
>         [P.Index(I, I[i] * I[j]): j in [1 .. n]]: i in [1 .. n]
>     ];
> end function;
> A := Frob(Sym(3));
> A;
[a b c d e f]
[b c a f d e]
[c a b e f d]
[d e f a b c]
[e f d c a b]
[f d e b c a]
> Determinant(A);
a^6 + a^4*d^2 + a^4*e^2 + a^4*f^2 + a^2*b^2*c^2 +
    a^2*b^2*d^2 + a^2*b^2*e^2 + a^2*b^2*f^2 + a^2*c^2*d^2 +
    a^2*c^2*e^2 + a^2*c^2*f^2 + a^2*d^4 + a^2*d^2*e^2 +
    a^2*d^2*f^2 + a^2*e^4 + a^2*e^2*f^2 + a^2*f^4 + b^6 +
    b^4*d^2 + b^4*e^2 + b^4*f^2 + b^2*c^2*d^2 + b^2*c^2*e^2
    + b^2*c^2*f^2 + b^2*d^4 + b^2*d^2*e^2 + b^2*d^2*f^2 +
    b^2*e^4 + b^2*e^2*f^2 + b^2*f^4 + c^6 + c^4*d^2 +
    c^4*e^2 + c^4*f^2 + c^2*d^4 + c^2*d^2*e^2 + c^2*d^2*f^2
    + c^2*e^4 + c^2*e^2*f^2 + c^2*f^4 + d^6 + d^2*e^2*f^2 +
    e^6 + f^6
> time Factorization(Determinant(A));
[
    <a + b + c + d + e + f, 2>,
    <a^2 + a*b + a*c + b^2 + b*c + c^2 + d^2 + d*e + d*f +
        e^2 + e*f + f^2, 2>
]
Time: 0.049
```

### Resultants and Discriminants

<a id="function-resultant-rngmpolelt-rngmpolelt-rngintelt"></a>
#### `Resultant(f, g, i): RngMPolElt, RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-resultant-rngmpolelt-rngmpolelt-rngmpolelt"></a>
#### `Resultant(f, g, v): RngMPolElt, RngMPolElt, RngMPolElt -> RngMPolElt`

The resultant of multivariate polynomials $f$ and $g$ in $P=R[x_1,\ldots, x_n]$ with respect to the variable $v=x_i$, which is by definition the determinant of the Sylvester matrix for $f$ and $g$ when considered as polynomials in the single variable $x_i$. The result will be an element of $P$ again. There are two ways to indicate with respect to which variable the integral is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$). The algorithm used is the modular interpolation method, as given in [[GCL92](https://docs.magma-maths.org/references.md#cite-gcl), pp. 412--413].

<a id="function-discriminant-rngmpolelt-rngintelt"></a>
#### `Discriminant(f, i): RngMPolElt, RngIntElt -> RngMPolElt`

<a id="function-discriminant-rngmpolelt-rngmpolelt"></a>
#### `Discriminant(f, v): RngMPolElt, RngMPolElt -> RngMPolElt`

The discriminant $D$ of $f\in R[x_1, \ldots, x_n]$ is returned, where $f$ is considered as a polynomial in $v=x_i$. The result will be an element of $P$ again. The coefficient ring $R$ must be a domain, or the leading coefficient of $f$ in $v$ must be a unit. There are two ways to indicate with respect to which variable the integral is to be taken: either one specifies $i$, the integer $1\leq i\leq n$ that is the number of the variable (upon creation of $P$, corresponding to `P.i`) or the variable $v$ itself (as an element of $P$).

### Polynomials over the Integers

The functions in this section are available for multivariate polynomials over the integers only.

<a id="function-sign-rngmpolelt"></a>
#### `Sign(f): RngMPolElt -> RngIntElt`

The sign of the leading coefficient of $f$.

<a id="function-absolutevalue-rngmpolelt"></a>
#### `AbsoluteValue(f): RngMPolElt -> RngMPolElt`

<a id="function-abs-rngmpolelt"></a>
#### `Abs(f): RngMPolElt -> RngMPolElt`

Return either $f$ or $-f$ according to which one has non-negative leading coefficient.

<a id="function-maxnorm-rngmpolelt"></a>
#### `MaxNorm(f): RngMPolElt -> RngIntElt`

The maximum of the absolute values of the coefficients of $f$.

<a id="function-sumnorm-rngmpolelt"></a>
#### `SumNorm(f): RngMPolElt -> RngIntElt`

The sum of the base coefficients of $f$.

<a id="real-complex"></a>
<a id="chapfldre"></a>
## Real and Complex Fields

- [Introduction](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md)
  - [Real Numbers in Magma](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#real-numbers-in-magma)
    - [Example: Real Numbers and Loss of Precision](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#example-ex-5afbbc)
  - [Coercion](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#coercion)
  - [Homomorphisms](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#homomorphisms)
    - [`hom< R -> S | >: FldRe, Str → Map`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#constructor-constructor-hom-fldre-str-map)
    - [Example: Embedding a Real Field in a Polynomial Ring](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#example-ex-edd37f)
  - [Special Options](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#special-options)
    - [`SetDefaultRealField(R): FldRe`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#procedure-setdefaultrealfield-fldre)
    - [`GetDefaultRealField() → FldRe`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#function-getdefaultrealfield)
    - [`AssignNames(~C, [s]): FldCom, [ MonStgElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#procedure-assignnames-fldcom-monstgelt-ref)
    - [`Name(C, 1): FldCom, RngIntElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#function-name-fldcom-rngintelt)
  - [Version Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#version-functions)
    - [`GetGMPVersion()`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#procedure-getgmpversion)
    - [`GetMPFRVersion()`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#procedure-getmpfrversion)
    - [`GetMPCVersion()`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/introduction.md#procedure-getmpcversion)
- [Creation Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md)
  - [Creation of Structures](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#creation-of-structures)
    - [`RealField(p): RngIntElt → FldRe`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-fldre-realfield)
    - [`RealField() → FldRe`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-realfield)
    - [`ComplexField(p): RngIntElt → FldCom`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-complexfield-rngintelt)
    - [`ComplexField() → FldCom`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-complexfield)
    - [`ComplexField(R): FldRe → FldCom`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-complexfield-fldre)
    - [Example: Creating a Complex Field](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#example-ex-108c46)
  - [Creation of Elements](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#creation-of-elements)
    - [`a . becpd: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt)
    - [`a . bEcPd: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-2)
    - [`a.bec P d: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-3)
    - [`a.bec p d: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-4)
    - [`a.b E cpd: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-5)
    - [`a.b e cpd: RngIntElt, RngIntElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-6)
    - [`elt<R | m, n>: FldRe, FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#constructor-constructor-elt-fldre-fldreelt-rngintelt-fldreelt)
    - [`elt<C | x, y>: FldCom, FldReElt, FldReElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#constructor-constructor-elt-fldcom-fldreelt-fldreelt-fldcomelt)
    - [`C ! [x, y]: FldCom, [FldReElt, FldReElt] → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-op-fldcom-fldreelt-fldreelt)
    - [`R ! a: FldRe, RngElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-op-fldre-rngelt)
    - [`C ! a: FldCom, RngElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#operation-op-fldcom-rngelt)
    - [Example: Creating Real Numbers](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#example-ex-356721)
    - [`One(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-one-fldre)
    - [`One(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-one-fldcom)
    - [`Identity(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-identity-fldre)
    - [`Identity(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-identity-fldcom)
    - [`Zero(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-zero-fldre)
    - [`Zero(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-zero-fldcom)
    - [`Representative(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-representative-fldre)
    - [`Representative(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-representative-fldcom)
- [Structure Operations](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md)
  - [Related Structures](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#related-structures)
    - [`Category(R): FldRe → Cat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-category-fldre)
    - [`Category(R): FldCom → Cat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-category-fldcom)
    - [`Parent(R): FldRe → PowerStructure`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-parent-fldre)
    - [`Parent(R): FldCom → PowerStructure`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-parent-fldcom)
    - [`PrimeField(R): FldRe → FldRat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-primefield-fldre)
    - [`PrimeField(R): FldCom → FldRat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-primefield-fldcom)
  - [Numerical Invariants](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#numerical-invariants)
    - [`Characteristic(R): FldRe → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-characteristic-fldre)
    - [`Characteristic(R): FldCom → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-characteristic-fldcom)
  - [Ring Predicates and Booleans](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#ring-predicates-and-booleans)
    - [`IsCommutative(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iscommutative-fldre)
    - [`IsCommutative(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iscommutative-fldcom)
    - [`IsUnitary(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isunitary-fldre)
    - [`IsUnitary(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isunitary-fldcom)
    - [`IsFinite(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isfinite-fldre)
    - [`IsFinite(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isfinite-fldcom)
    - [`IsOrdered(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isordered-fldre)
    - [`IsOrdered(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isordered-fldcom)
    - [`IsField(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isfield-fldre)
    - [`IsField(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isfield-fldcom)
    - [`IsEuclideanDomain(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iseuclideandomain-fldre)
    - [`IsEuclideanDomain(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iseuclideandomain-fldcom)
    - [`IsPID(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-ispid-fldre)
    - [`IsPID(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-ispid-fldcom)
    - [`IsUFD(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isufd-fldre)
    - [`IsUFD(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isufd-fldcom)
    - [`IsDivisionRing(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isdivisionring-fldre)
    - [`IsDivisionRing(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isdivisionring-fldcom)
    - [`IsEuclideanRing(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iseuclideanring-fldre)
    - [`IsEuclideanRing(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-iseuclideanring-fldcom)
    - [`IsPrincipalIdealRing(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isprincipalidealring-fldre)
    - [`IsPrincipalIdealRing(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isprincipalidealring-fldcom)
    - [`IsDomain(R): FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isdomain-fldre)
    - [`IsDomain(R): FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-isdomain-fldcom)
    - [`R eq S: FldRe, FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#operation-op-eq-fldre-fldre)
    - [`R ne S: FldRe, FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#operation-op-ne-fldre-fldre)
    - [`R eq S: FldCom, FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#operation-op-eq-fldcom-fldcom)
    - [`R ne S: FldCom, FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#operation-op-ne-fldcom-fldcom)
  - [Other Structure Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#other-structure-functions)
    - [`Precision(R): FldCom → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-precision-fldcom)
    - [`Precision(R): FldRe → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-precision-fldre)
    - [`BitPrecision(R): FldCom → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-bitprecision-fldcom)
    - [`BitPrecision(R): FldRe → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-structure.md#function-bitprecision-fldre)
- [Element Operations](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md)
  - [Generic Element Functions and Predicates](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#generic-element-functions-and-predicates)
    - [`Parent(r): FldReElt → Rng`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-parent-fldreelt)
    - [`Parent(r): FldComElt → Rng`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-parent-fldcomelt)
    - [`Category(r): FldReElt → Cat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-category-fldreelt)
    - [`Category(r): FldComElt → Cat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-category-fldcomelt)
    - [`IsZero(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-iszero-fldreelt)
    - [`IsZero(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-iszero-fldcomelt)
    - [`IsOne(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isone-fldreelt)
    - [`IsOne(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isone-fldcomelt)
    - [`IsMinusOne(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isminusone-fldreelt)
    - [`IsMinusOne(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isminusone-fldcomelt)
    - [`IsUnit(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isunit-fldreelt)
    - [`IsUnit(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isunit-fldcomelt)
    - [`IsZeroDivisor(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-iszerodivisor-fldreelt)
    - [`IsZeroDivisor(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-iszerodivisor-fldcomelt)
    - [`IsIdempotent(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isidempotent-fldreelt)
    - [`IsIdempotent(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isidempotent-fldcomelt)
    - [`IsNilpotent(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isnilpotent-fldreelt)
    - [`IsNilpotent(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isnilpotent-fldcomelt)
    - [`IsIrreducible(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isirreducible-fldreelt)
    - [`IsIrreducible(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isirreducible-fldcomelt)
    - [`IsPrime(r): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isprime-fldreelt)
    - [`IsPrime(r): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isprime-fldcomelt)
  - [Comparison of and Membership](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#comparison-of-and-membership)
    - [`a eq b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-eq-fldreelt-fldreelt)
    - [`a ne b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-ne-fldreelt-fldreelt)
    - [`a eq b: FldComElt, FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-eq-fldcomelt-fldcomelt)
    - [`a ne b: FldComElt, FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-ne-fldcomelt-fldcomelt)
    - [`a in R: FldReElt, FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-in-fldreelt-fldre)
    - [`a notin R: FldReElt, FldRe → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-notin-fldreelt-fldre)
    - [`a in R: FldComElt, FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-in-fldcomelt-fldcom)
    - [`a notin R: FldComElt, FldCom → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-notin-fldcomelt-fldcom)
    - [`a gt b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-gt-fldreelt-fldreelt)
    - [`a ge b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-ge-fldreelt-fldreelt)
    - [`a lt b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-lt-fldreelt-fldreelt)
    - [`a le b: FldReElt, FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-le-fldreelt-fldreelt)
    - [`Maximum(a, b): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-maximum-fldreelt-fldreelt)
    - [`Minimum(a, b): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimum-fldreelt-fldreelt)
    - [`Maximum(Q): [FldReElt] → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-maximum-fldreelt)
    - [`Minimum(Q): [FldReElt] → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimum-fldreelt)
  - [Other Predicates](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#other-predicates)
    - [`IsIntegral(c): FldReElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isintegral-fldreelt)
    - [`IsIntegral(c): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isintegral-fldcomelt)
    - [`IsReal(c): FldComElt → BoolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-isreal-fldcomelt)
  - [Arithmetic](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#arithmetic)
    - [`+ r: FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt)
    - [`+ r: FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt)
    - [`- r: FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-2)
    - [`- r: FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-2)
    - [`r + s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-plus-fldreelt-fldreelt)
    - [`r + s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-plus-fldcomelt-fldcomelt)
    - [`r - s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-minus-fldreelt-fldreelt)
    - [`r - s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-minus-fldcomelt-fldcomelt)
    - [`r * s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-times-fldreelt-fldreelt)
    - [`r * s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-times-fldcomelt-fldcomelt)
    - [`r / s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-div-fldreelt-fldreelt)
    - [`r / s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-div-fldcomelt-fldcomelt)
    - [`r ^ k: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-pow-fldreelt-fldreelt)
    - [`r ^ k: FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-pow-fldreelt-rngintelt)
    - [`r ^ k: FldComElt, RngIntElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-pow-fldcomelt-rngintelt)
    - [`r ^ k: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-op-pow-fldcomelt-fldcomelt)
    - [`r +:= s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-fldreelt)
    - [`r +:= s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-fldcomelt)
    - [`r -:= s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-fldreelt-2)
    - [`r -:= s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-fldcomelt-2)
    - [`r *:= s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-fldreelt-3)
    - [`r *:= s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-fldcomelt-3)
    - [`r /:= s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-fldreelt-4)
    - [`r /:= s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-fldcomelt-4)
    - [`r ^:= s: FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldreelt-fldreelt-fldreelt-5)
    - [`r ^:= s: FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#operation-operation-fldcomelt-fldcomelt-fldcomelt-5)
  - [Conversions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#conversions)
    - [`MantissaExponent(r): FldReElt → RngIntElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-mantissaexponent-fldreelt)
    - [`ComplexToPolar(c): FldComElt → FldReElt, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-complextopolar-fldcomelt)
    - [`PolarToComplex(m, a): FldReElt, FldReElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-polartocomplex-fldreelt-fldreelt)
    - [`Argument(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-argument-fldcomelt)
    - [`Arg(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-arg-fldcomelt)
    - [Example: Argument of a Signed Zero](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#example-ex-9ff75f)
    - [`Modulus(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-modulus-fldcomelt)
    - [`Real(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-real-fldcomelt)
    - [`Re(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-re-fldcomelt)
    - [`Imaginary(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-imaginary-fldcomelt)
    - [`Im(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-im-fldcomelt)
  - [Rounding](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#rounding)
    - [`Round(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-round-fldreelt)
    - [`Round(r): FldComElt → RngQuadElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-round-fldcomelt)
    - [`Truncate(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-truncate-fldreelt)
    - [`Ceiling(r): Infty → Infty`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-ceiling-infty)
    - [`Ceiling(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-ceiling-fldreelt)
    - [`Floor(r): Infty → Infty`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-floor-infty)
    - [`Floor(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-floor-fldreelt)
  - [Precision](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#precision)
    - [`Precision(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-precision-fldreelt)
    - [`Precision(c): FldComElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-precision-fldcomelt)
    - [`BitPrecision(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-bitprecision-fldreelt)
    - [`BitPrecision(c): FldComElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-bitprecision-fldcomelt)
    - [`Precision(L): [FldReElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-precision-fldreelt-2)
    - [`Precision(L): [FldComElt] → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-precision-fldcomelt-2)
    - [`ChangePrecision(r, n): FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-changeprecision-fldreelt-rngintelt)
    - [`ChangePrecision(c, n): FldComElt, RngIntElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-changeprecision-fldcomelt-rngintelt)
  - [Constants](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#constants)
    - [`Catalan(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-catalan-fldre)
    - [`Catalan(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-catalan-fldcom)
    - [`EulerGamma(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-eulergamma-fldre)
    - [`EulerGamma(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-eulergamma-fldcom)
    - [`Pi(R): FldRe → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-pi-fldre)
    - [`Pi(R): FldCom → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-pi-fldcom)
  - [Simple Element Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#simple-element-functions)
    - [`AbsoluteValue(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-absolutevalue-fldreelt)
    - [`AbsoluteValue(r): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-absolutevalue-fldcomelt)
    - [`Abs(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-abs-fldreelt)
    - [`Abs(r): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-abs-fldcomelt)
    - [`Sign(r): FldReElt → RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-sign-fldreelt)
    - [`ComplexConjugate(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-complexconjugate-fldreelt)
    - [`ComplexConjugate(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-complexconjugate-fldcomelt)
    - [`Conjugate(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-conjugate-fldcomelt)
    - [`Norm(c): FldComElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-norm-fldcomelt)
    - [`Norm(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-norm-fldreelt)
    - [`Root(r, n): FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-root-fldreelt-rngintelt)
    - [`Root(r, n): FldComElt, RngIntElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-root-fldcomelt-rngintelt)
    - [`SquareRoot(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-squareroot-fldcomelt)
    - [`Sqrt(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-sqrt-fldcomelt)
    - [`SquareRoot(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-squareroot-fldreelt)
    - [`Sqrt(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-sqrt-fldreelt)
    - [`Distance(x, L): FldReElt, [FldReElt] → FldReElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-distance-fldreelt-fldreelt)
    - [`Distance(x, L): FldReElt, [FldComElt] → FldReElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-distance-fldreelt-fldcomelt)
    - [`Distance(x, L): FldComElt, [FldReElt] → FldReElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-distance-fldcomelt-fldreelt)
    - [`Distance(x, L): FldComElt, [FldComElt] → FldReElt, RngIntElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-distance-fldcomelt-fldcomelt)
    - [`Diameter(L): [FldReElt] → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-diameter-fldreelt)
    - [`Diameter(L): [FldComElt] → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-diameter-fldcomelt)
  - [Roots](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#roots)
    - [`Roots(p): RngUPolElt → [ <FldComElt, RngIntElt> ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-fldre-roots)
    - [Example: Roots of a Polynomial with a Multiple Root](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#example-ex-04bda5)
    - [`RootsNonExact(p): RngUPolElt[FldRe] → [ FldComElt ], [ FldComElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-rootsnonexact-rngupolelt-fldre)
    - [`RootsNonExact(p): RngUPolElt[FldCom] → [ FldComElt ], [ FldComElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-rootsnonexact-rngupolelt-fldcom)
    - [Example: Roots with Error Estimates](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#example-ex-a1670d)
    - [`HenselLift(f, R, k): RngUPolElt, FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-hensellift-rngupolelt-fldreelt-rngintelt)
    - [`HenselLift(f, R, k): RngUPolElt, FldComElt, RngIntElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-hensellift-rngupolelt-fldcomelt-rngintelt)
  - [Continued Fractions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#continued-fractions)
    - [`ContinuedFraction(r): FldRatElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-continuedfraction-fldratelt)
    - [`ContinuedFraction(r): FldReElt → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-continuedfraction-fldreelt)
    - [`BestApproximation(r, n): FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-bestapproximation-fldreelt-rngintelt)
    - [`Convergents(s): [ RngIntElt ] → ModMatRngElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-convergents-rngintelt)
  - [Linear and Algebraic Dependencies](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#linear-and-algebraic-dependencies)
    - [`LinearRelation(q: parameters): [ FldComElt ] → [ RngIntElt ]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-linearrelationlabel)
    - [`LinearRelation(v: parameters): ModTupRngElt → ModTupRngElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-linearrelation-modtuprngelt)
    - [`AllLinearRelations(q,p): SeqEnum, RngIntElt → Lat`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-alllinearrelations-seqenum-rngintelt)
    - [`IntegerRelation(q): SeqEnum → SeqEnum, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-integerrelation-seqenum)
    - [`IntegerRelation(q,N): SeqEnum, RngIntElt → SeqEnum, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-integerrelation-seqenum-rngintelt)
    - [`PowerRelation(r, k: parameters): FldReElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-powerrelation-fldreelt-rngintelt)
    - [`PowerRelation(r, k: parameters): FldComElt, RngIntElt → RngUPolElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-powerrelation-fldcomelt-rngintelt)
    - [`MinimalPolynomial(r,d,N): FldReElt, RngIntElt, RngIntElt → RngUPolElt, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimalpolynomial-fldreelt-rngintelt-rngintelt)
    - [`MinimalPolynomial(r,d,N): FldComElt, RngIntElt, RngIntElt → RngUPolElt, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimalpolynomial-fldcomelt-rngintelt-rngintelt)
    - [`MinimalPolynomial(r,d): FldReElt, RngIntElt → RngUPolElt -> FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimalpolynomial-fldreelt-rngintelt)
    - [`MinimalPolynomial(r,d): FldComElt, RngIntElt → RngUPolElt -> FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#function-minimalpolynomial-fldcomelt-rngintelt)
    - [Example: Polynomial Factorization via LLL](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/operation-element.md#example-ex-b60a49)
- [Transcendental Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md)
  - [Exponential, Logarithmic, and Polylogarithmic Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#exponential-logarithmic-and-polylogarithmic-functions)
    - [`Exp(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-exp-rngserelt)
    - [`Exp(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-exp-fldcomelt)
    - [`Exp(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-exp-fldreelt)
    - [`Log(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-log-rngserelt)
    - [`Log(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-log-fldreelt)
    - [`Log(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-log-fldcomelt)
    - [`Log(b, r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-log-fldreelt-2)
    - [`Dilog(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-dilog-fldcomelt)
    - [`Dilog(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-dilog-fldreelt)
    - [`Polylog(m, f): RngIntElt, RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-polylog-rngintelt-rngserelt)
    - [`Polylog(m, s): RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-polylog-rngintelt-fldcomelt)
    - [`PolylogD(m, s): RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-polylogd-rngintelt-fldcomelt)
    - [`PolylogDold(m, s): RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-polylogdold-rngintelt-fldcomelt)
    - [`PolylogP(m, s): RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-polylogp-rngintelt-fldcomelt)
  - [Trigonometric Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#trigonometric-functions)
    - [`Sin(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sin-rngserelt)
    - [`Sin(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sin-fldcomelt)
    - [`Sin(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sin-fldreelt)
    - [`Cos(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cos-rngserelt)
    - [`Cos(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cos-fldcomelt)
    - [`Cos(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cos-fldreelt)
    - [`Sincos(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sincos-rngserelt)
    - [`Sincos(s): FldReElt → FldReElt, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sincos-fldreelt)
    - [`Sincos(s): FldComElt → FldComElt, FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sincos-fldcomelt)
    - [`Tan(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tan-rngserelt)
    - [`Tan(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tan-fldcomelt)
    - [`Tan(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tan-fldreelt)
    - [`Cot(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cot-rngserelt)
    - [`Cot(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cot-fldcomelt)
    - [`Cot(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cot-fldreelt)
    - [`Sec(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sec-rngserelt)
    - [`Sec(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sec-fldcomelt)
    - [`Sec(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sec-fldreelt)
    - [`Cosec(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosec-rngserelt)
    - [`Cosec(c): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosec-fldcomelt)
    - [`Cosec(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosec-fldreelt)
  - [Inverse Trigonometric Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#inverse-trigonometric-functions)
    - [`Arcsin(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arcsin-rngserelt)
    - [`Arcsin(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arcsin-fldreelt)
    - [`Arcsin(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arcsin-fldcomelt)
    - [`Arccos(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccos-rngserelt)
    - [`Arccos(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccos-fldreelt)
    - [`Arccos(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccos-fldcomelt)
    - [`Arctan(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arctan-rngserelt)
    - [`Arctan(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arctan-fldreelt)
    - [`Arctan(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arctan-fldcomelt)
    - [`Arctan(x, y): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arctan-fldreelt-fldreelt)
    - [`Arctan2(x, y): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arctan2-fldreelt-fldreelt)
    - [`Arccot(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccot-fldreelt)
    - [`Arccot(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccot-fldcomelt)
    - [`Arcsec(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arcsec-fldreelt)
    - [`Arcsec(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arcsec-fldcomelt)
    - [`Arccosec(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccosec-fldreelt)
    - [`Arccosec(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-arccosec-fldcomelt)
  - [Hyperbolic Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#hyperbolic-functions)
    - [`Sinh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sinh-rngserelt)
    - [`Sinh(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sinh-fldcomelt)
    - [`Sinh(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sinh-fldreelt)
    - [`Cosh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosh-rngserelt)
    - [`Cosh(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosh-fldreelt)
    - [`Cosh(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosh-fldcomelt)
    - [`Tanh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tanh-rngserelt)
    - [`Tanh(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tanh-fldreelt)
    - [`Tanh(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-tanh-fldcomelt)
    - [`Coth(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-coth-fldreelt)
    - [`Coth(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-coth-fldcomelt)
    - [`Sech(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sech-fldreelt)
    - [`Sech(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-sech-fldcomelt)
    - [`Cosech(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosech-fldreelt)
    - [`Cosech(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-cosech-fldcomelt)
  - [Inverse Hyperbolic Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#inverse-hyperbolic-functions)
    - [`Argsinh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argsinh-rngserelt)
    - [`Argsinh(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argsinh-fldreelt)
    - [`Argsinh(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argsinh-fldcomelt)
    - [`Argcosh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcosh-rngserelt)
    - [`Argcosh(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcosh-fldreelt)
    - [`Argcosh(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcosh-fldcomelt)
    - [`Argtanh(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argtanh-rngserelt)
    - [`Argtanh(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argtanh-fldreelt)
    - [`Argtanh(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argtanh-fldcomelt)
    - [`Argsech(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argsech-fldreelt)
    - [`Argsech(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argsech-fldcomelt)
    - [`Argcosech(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcosech-fldreelt)
    - [`Argcosech(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcosech-fldcomelt)
    - [`Argcoth(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcoth-fldreelt)
    - [`Argcoth(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/transcendental.md#function-argcoth-fldcomelt)
- [Elliptic and Modular Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md)
  - [Eisenstein Series](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#eisenstein-series)
    - [`Eisenstein(k, z): RngIntElt, RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-eisenstein-rngintelt-rngserelt)
    - [`Eisenstein(k, t): RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-eisenstein-rngintelt-fldcomelt)
    - [`Eisenstein(k, L): RngIntElt, SeqEnum → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-eisenstein-rngintelt-seqenum)
    - [`Eisenstein(k, F): RngIntElt, QuadBinElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-eisenstein-rngintelt-quadbinelt)
    - [Example: q-Expansion of an Eisenstein Series](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#example-ex-db3e10)
  - [Weierstrass Series](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#weierstrass-series)
    - [`WeierstrassSeries(z, q): RngSerElt, RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weierstrassseries-rngserelt-rngserelt)
    - [`WeierstrassSeries(z, t): RngSerElt, FldComElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weierstrassseries-rngserelt-fldcomelt)
    - [`WeierstrassSeries(z, L): RngSerElt, SeqEnum → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weierstrassseries-rngserelt-seqenum)
    - [`WeierstrassSeries(z, F): RngSerElt, QuadBinElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weierstrassseries-rngserelt-quadbinelt)
  - [The Jacobi $\theta$ and Dedekind $\eta$-functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#the-jacobi-theta-and-dedekind-eta-functions)
    - [`JacobiTheta(q, z): FldReElt, RngSerElt[FldRe] → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jacobitheta-fldreelt-rngserelt-fldre)
    - [`JacobiTheta(q, z): FldComElt, RngSerElt[FldCom] → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jacobitheta-fldcomelt-rngserelt-fldcom)
    - [`JacobiTheta(q, z): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jacobitheta-fldreelt-fldreelt)
    - [`JacobiTheta(q, z): FldComElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jacobitheta-fldcomelt-fldcomelt)
    - [`JacobiThetaNullK(q, k): FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jacobithetanullk-fldreelt-rngintelt)
    - [`DedekindEta(z): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-dedekindeta-rngserelt)
    - [`DedekindEta(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-dedekindeta-fldcomelt)
  - [The $j$-Invariant and the Discriminant](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#the-j-invariant-and-the-discriminant)
    - [`jInvariant(q): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jinvariant-rngserelt)
    - [`jInvariant(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jinvariant-fldcomelt)
    - [`jInvariant(L): SeqEnum → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jinvariant-seqenum)
    - [`jInvariant(F): QuadBinElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-jinvariant-quadbinelt)
    - [`Delta(z): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-delta-rngserelt)
    - [`Delta(t): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-delta-fldcomelt)
    - [`Delta(L): SeqEnum → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-delta-seqenum)
  - [Weber’s Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#weber-s-functions)
    - [`WeberF(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weberf-fldcomelt)
    - [`WeberF2(g): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weberf2-rngserelt)
    - [`WeberF1(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weberf1-fldcomelt)
    - [`WeberF2(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#function-weberf2-fldcomelt)
    - [Example: q-Expansion of a Weber Function](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/elliptic-modular.md#example-ex-3718fd)
- [Theta Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/theta.md)
  - [`Theta(char, z, tau): Mtrx, Mtrx, Mtrx → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/theta.md#function-theta-mtrx-mtrx-mtrx)
  - [`Theta(char, z, A): Mtrx, Mtrx, AnHcJac → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/theta.md#function-theta-mtrx-mtrx-anhcjac)
- [Gamma, Bessel, and Associated Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md)
  - [`Gamma(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-gamma-rngserelt)
  - [`Gamma(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-gamma-fldreelt)
  - [`Gamma(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-gamma-fldcomelt)
  - [`Gamma(s, t): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-gamma-fldreelt-fldreelt)
  - [`GammaD(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-gammad-fldreelt)
  - [`LogGamma(f): RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-loggamma-rngserelt)
  - [`LogGamma(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-loggamma-fldreelt)
  - [`LogGamma(r): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-loggamma-fldcomelt)
  - [`LogDerivative(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-logderivative-fldreelt)
  - [`LogDerivative(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-logderivative-fldcomelt)
  - [`Psi(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-psi-fldreelt)
  - [`Psi(s): FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-psi-fldcomelt)
  - [`BesselFunction(n, r): RngIntElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-besselfunction-rngintelt-fldreelt)
  - [`BesselFunctionSecondKind(n, r): RngIntElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-besselfunctionsecondkind-rngintelt-fldreelt)
  - [`JBessel(n, s): RngIntElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-jbessel-rngintelt-fldreelt)
  - [`JBessel(n, s): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-jbessel-fldreelt-fldreelt)
  - [`KBessel(n, s): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-kbessel-fldreelt-fldreelt)
  - [`KBessel(n, s): FldComElt, FldReElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-kbessel-fldcomelt-fldreelt)
  - [`KBessel2(n, s): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-kbessel2-fldreelt-fldreelt)
  - [`KBessel2(n, s): FldComElt, FldReElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/gamma-bessel.md#function-kbessel2-fldcomelt-fldreelt)
- [The Hypergeometric Function](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/hypergeometric.md)
  - [`HypergeometricSeries(a, b, c, z): RngElt, RngElt, RngElt, RngElt → RngElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/hypergeometric.md#function-hypergeometricseries-rngelt-rngelt-rngelt-rngelt)
  - [`HypergeometricU(a, b, s): FldReElt, FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/hypergeometric.md#function-hypergeometricu-fldreelt-fldreelt-fldreelt)
- [Other Special Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md)
  - [`ArithmeticGeometricMean(x, y): RngSerElt, RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-arithmeticgeometricmean-rngserelt-rngserelt)
  - [`AGM(f, g): RngSerElt, RngSerElt → RngSerElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-agm-rngserelt-rngserelt)
  - [`ArithmeticGeometricMean(x, y): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-arithmeticgeometricmean-fldreelt-fldreelt)
  - [`AGM(x, y): FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-agm-fldreelt-fldreelt)
  - [`BernoulliNumber(n): RngIntElt → FldRatElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-bernoullinumber-rngintelt)
  - [`BernoulliApproximation(n): RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-bernoulliapproximation-rngintelt)
  - [`DawsonIntegral(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-dawsonintegral-fldreelt)
  - [`ErrorFunction(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-errorfunction-fldreelt)
  - [`Erf(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-erf-fldreelt)
  - [`ComplementaryErrorFunction(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-complementaryerrorfunction-fldreelt)
  - [`Erfc(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-erfc-fldreelt)
  - [`ExponentialIntegral(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-exponentialintegral-fldreelt)
  - [`ExponentialIntegralE1(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-exponentialintegrale1-fldreelt)
  - [`LogIntegral(r): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-logintegral-fldreelt)
  - [`ZetaFunction(s): FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-zetafunction-fldreelt)
  - [`ZetaFunction(R, n): FldRe, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/special.md#function-zetafunction-fldre-rngintelt)
- [Summation of Infinite Series](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/infinite-summation.md)
  - [`InfiniteSum(m, i): Map, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/infinite-summation.md#function-infinitesum-map-rngintelt)
  - [`PositiveSum(m, i): Map, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/infinite-summation.md#function-positivesum-map-rngintelt)
  - [`AlternatingSum(m, i): Map, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/infinite-summation.md#function-alternatingsum-map-rngintelt)
- [Numerical Integration](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md)
  - [Polynomial Interpolation](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#polynomial-interpolation)
    - [`Interpolation(P, V, t): [FldReElt], [FldReElt], FldReElt → FldReElt, FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-interpolation-fldreelt-fldreelt-fldreelt)
  - [Discrete Fourier Transform](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#discrete-fourier-transform)
    - [`DiscreteFourierTransform(E): SeqEnum[FldComElt] → SeqEnum[FldComElt]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-discretefouriertransform-seqenum-fldcomelt)
  - [Integration of Complex Functions](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#integration-of-complex-functions)
    - [Gaussian Quadratures](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#gaussian-quadratures)
      - [`GaussLegendreIntegrationPoints(N,D): RngIntElt, RngIntElt → SeqEnum[FldReElt], SeqEnum[FldReElt]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-gausslegendreintegrationpoints-rngintelt-rngintelt)
      - [`GaussJacobiIntegrationPoints(N,D,a,b): RngIntElt, RngIntElt, RngReSubElt, RngReSubElt → SeqEnum, SeqEnum`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-gaussjacobiintegrationpoints-rngintelt-rngintelt-rngresubelt-rngresubelt)
    - [Clenshaw–Curtis Quadrature](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#clenshaw-curtis-quadrature)
      - [`ClenshawCurtisIntegrationPoints(N,D): RngIntElt, RngIntElt → SeqEnum[FldReElt], SeqEnum[FldReElt]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-clenshawcurtisintegrationpoints-rngintelt-rngintelt)
    - [Tanh–Sinh Quadrature](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#tanh-sinh-quadrature)
      - [`TanhSinhIntegrationPoints(N,h): RngIntElt, FldReElt → SeqEnum[FldReElt], SeqEnum[FldReElt], SeqEnum[FldReElt]`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-tanhsinhintegrationpoints-rngintelt-fldreelt)
      - [Example: Numerical Integration on the Unit Interval](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#example-ex-fd7870)
      - [Example: Integral with Endpoint Singularities](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#example-ex-9327e9)
      - [Example: Integral over an Infinite Interval](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#example-ex-1222c3)
  - [Romberg-Type Integration](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#romberg-type-integration)
    - [`RombergQuadrature(f, a, b: parameters): Program, FldReElt, FldReElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-rombergquadrature-program-fldreelt-fldreelt)
    - [`SimpsonQuadrature(f, a, b, n): Program, FldReElt, FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-simpsonquadrature-program-fldreelt-fldreelt-rngintelt)
    - [`TrapezoidalQuadrature(f, a, b, n): Program, FldReElt, FldReElt, RngIntElt → FldReElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-trapezoidalquadrature-program-fldreelt-fldreelt-rngintelt)
  - [Numerical Derivatives](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#numerical-derivatives)
    - [`NumericalDerivative(f, n, z): UserProgram, RngIntElt, FldComElt → FldComElt`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#function-numericalderivative-userprogram-rngintelt-fldcomelt)
    - [Example: Numerical Derivative](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/integration1.md#example-ex-c82809)
- [Bibliography](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/bibliography.md)

### Introduction

Real and complex numbers can only be stored in the computer effectively in approximations. Magma provides a number of facilities for calculating with such approximations. Most of these facilities are based upon the C libraries MPFR, which provides algorithms for manipulating real numbers with *exact rounding*, and MPC, an extension of MPFR to handle complex numbers. More specifically, the MPFR library extends the semantics of the ANSI/IEEE-754 standard for double-precision numbers — which are used in virtually all major programming languages — to handle real numbers of arbitrary precision. The precise semantics of MPFR give the user fine control over precision loss, which is a tremendous advantage when working with reals and complexes. Magma currently uses MPFR 2.4.1 and MPC 0.8. Documentation for algorithms used in MPFR can be found at `mpfr.org`.

As MPFR and MPC are works in progress, they do not yet provide a complete framework for working with the reals and complexes. For those functions that these libraries are missing, Magma falls back to algorithms taken from Pari. The documentation of MPFR and MPC provide a list of the functions that they provide. Assume that each intrinsic uses MPFR unless otherwise stated.

Although we use the terms *real field* and *complex field* for Magma structures containing real or complex approximations, it should be noted that such a subset of the real or complex field may not even form a commutative ring. Never the less, the real and complex fields are considered to be fields by Magma, they comprise objects of type `FldRe` and `FldCom` with elements of type `FldReElt` and `FldComElt` respectively.

<a id="overview-reals"></a>
<a id="overview-reals-label"></a>
#### Real Numbers in Magma

Real numbers are stored internally as a sign bit and an expansion $\sum b_i 2^i$ with $b_i\in {0,1}$. Note that MPFR has both positive and negative zeros. Complex numbers consist of a pair of real numbers of identical precision. Each real or complex number is associated with a corresponding field structure, which has the same precision as all of its elements. Magma stores a list of real and complex fields that have been created during a session, and it is guaranteed that any two fields of the same fixed precision are the same. This means in particular that changing the name of $\sqrt{-1}$ (see `AssignNames` below) on one of the complex fields of precision $r$ will change the name on every complex field of that same precision. As a convenience, Magma allows real and complex numbers of differing precisions to be used in the same expression; internally, Magma implicitly reduces the precision of the higher precision element to the precision of the lower element.

While internally we store real numbers in base two, when creating real or complex fields the precision is by default specified in the number of *decimal* digits, not binary digits, required. It is possible to specify the precision in binary digits if needed see the documentation for [`RealField`](https://docs.magma-maths.org/BasicRings/RealAndComplexFields/creation.md#function-fldre-realfield) for details).

<a id="example-ex-5afbbc"></a>
##### `Example: Real Numbers and Loss of Precision (ex-5afbbc)`

We show how to create and manipulate real numbers. In particular, note that there is an inherent loss of precision in the conversion between base 10 and base 2 representations of some real numbers.

```magma
> S1 := RealField(20);
> S2 := RealField(10);
> a := S1 ! 0.5;
> a;
0.50000000000000000000
> b := S2 ! 0.05;
> b;
0.05000000000
> a + b;
0.5500000000
> Precision(a + b);
10
```

A warning is in place here; in the examples above, the real number on the right hand side had to be constructed in some real field *before* it could be coerced into $S_1$ and $S_2$. That real field is the so-called *default real field*. In these examples it is assumed that the default field has sufficiently large precision to store the real numbers on the right accurately to the last digit.

#### Coercion

Automatic coercion ensures that all functions listed below that take an element of some real field as an argument, will also accept an integer or a rational number as an argument; in this case the integer or rational number will be coerced automatically into the default real field. For the binary operations (such as `+, *`) coercion also takes place: if one argument is real and the other is integral or rational, automatic coercion will put them both in the parent field of the real argument. If the arguments are real numbers of different fixed precision, the result will have the smaller precision of the two.

The same coercion rules apply for functions taking a complex number as an argument; in that case real numbers will be valid input as well: if necessary reals, rationals, or integers will be coerced into the appropriate complex field.

Elements of quadratic and cyclotomic fields that are real can be coerced into any real field using `!`; any quadratic or cyclotomic field element can be coerced by `!` into any complex field. Functions taking real or complex arguments will not *automatically* coerce such arguments though.

#### Homomorphisms

The only homomorphisms that have a real field or a complex field as domain are the coercion functions. Therefore, homomorphisms from the reals or complexes may be specified as follows.

<a id="constructor-constructor-hom-fldre-str-map"></a>
##### `hom< R -> S | >: FldRe, Str -> Map`

Here $S$ must be a structure into which all elements of the real or complex field $R$ are coercible, such as another real or complex field, or a polynomial ring over one of these. These homomorphisms can also be obtained as map by using the function `Coercion`, also called `Bang`.

<a id="example-ex-edd37f"></a>
##### `Example: Embedding a Real Field in a Polynomial Ring (ex-edd37f)`

Here are two equivalent ways of creating the embedding function from a real field into a polynomial ring over some complex field.

```magma
> Re := RealField(20);
> PC<x, y> := PolynomialRing(ComplexField(8), 2);
> f := hom< Re -> PC | >;
> bangf := Bang(Re, PC);
> f(Pi(Re));
3.1415927
> f(Pi(Re)) eq bangf(Pi(Re));
true
```

#### Special Options

When Magma is started up, real and complex fields of precision 30 are created by default. They serve (among other things) as a parent for reals that are created as literals, such as $1.2345$, in the same way as the default ring of integers is the parent for literal integers. It is possible to change this default real field with `SetDefaultRealField`.

Finally, `AssignNames` can be used to change the name for $\sqrt{-1}$ in a complex field.

<a id="procedure-setdefaultrealfield-fldre"></a>
##### `SetDefaultRealField(R): FldRe`

Procedure to change the default parent for literal real numbers to the real field $R$. This parent is the real field of precision 30 by default.

<a id="function-getdefaultrealfield"></a>
##### `GetDefaultRealField() -> FldRe`

Return the current parent for literal real numbers.

<a id="procedure-assignnames-fldcom-monstgelt-ref"></a>
##### `AssignNames(~C, [s]): FldCom, [ MonStgElt ]`

Procedure to change the name of the purely imaginary element $\sqrt{-1}$ in the complex field $C$ to the contents of the string $s$. When $C$ is created, the name is “C.1”; suitable choices of $s$ might be `"i"`, `"I"`, or `"j"`. This procedure only changes the name used in printing the elements of $C$. It does *not* assign to an identifier called $s$ the value of $\sqrt{-1}$ in $C$; to do this, use an assignment statement, or use angle brackets when creating the field. Note that since this is a procedure that modifies $C$, it is necessary to have a reference `~C` to $C$ in the call to this function.

<a id="function-name-fldcom-rngintelt"></a>
##### `Name(C, 1): FldCom, RngIntElt -> FldComElt`

Given a complex field $C$, return the element which has the name attached to it, that is, return the purely imaginary element $\sqrt{-1}$ of $C$.

#### Version Functions

The following intrinsics retrieve the versions of MPFR, MPC, and GMP which the current Magma is using.

<a id="procedure-getgmpversion"></a>
##### `GetGMPVersion()`

<a id="procedure-getmpfrversion"></a>
##### `GetMPFRVersion()`

<a id="procedure-getmpcversion"></a>
##### `GetMPCVersion()`

The version of GMP, MPFR, or MPC being used.

### Creation Functions

We describe the creation of real and complex fields and their elements.

#### Creation of Structures

At the time Magma is loaded, a real field is automatically created. This is used as the default parent for literal reals and real values returned by Magma.

<a id="function-fldre-realfield"></a>
##### `RealField(p): RngIntElt -> FldRe`

```magma
Bits: BoolElt                    Default: false
```

Given a positive integer $p$, create and return a version $R$ of the real field ${\mathbb{R}}$ in which all calculations are correct to precision $p$. If the parameter `Bits` is `true`, then the precision $p$ is specified as the number of binary digits. If `Bits` is `false`, then the precision is given as the number of decimal digits — this is translated into a binary precision of $\lceil \log_2 {10^p} \rceil$.

<a id="function-realfield"></a>
##### `RealField() -> FldRe`

Return the default real field.

<a id="function-complexfield-rngintelt"></a>
##### `ComplexField(p): RngIntElt -> FldCom`

```magma
Bits: BoolElt                    Default: false
```

Given a positive integer $p$, create and return a version $C$ of the complex field ${\mathbb{C}}$ in which all calculations are correct to precision $p$. If the parameter `Bits` is `true`, then the precision $p$ is specified as the number of binary digits. If `Bits` is `false`, then the precision is given as the number of decimal digits — this is translated into a binary precision of $\lceil \log_2 {10^p} \rceil$. By default no name is given to $\sqrt{-1}$; this may be changed with `AssignNames`. Angle brackets, e.g. `C<i> := ComplexField(20)`, may be used to assign $\sqrt{-1}$ to an identifier.

<a id="function-complexfield"></a>
##### `ComplexField() -> FldCom`

Return the default complex field. By default no name is given to $\sqrt{-1}$; this may be changed with `AssignNames`. Angle brackets, e.g. `C<i> := ComplexField()`, may be used to assign $\sqrt{-1}$ to an identifier.

<a id="function-complexfield-fldre"></a>
##### `ComplexField(R): FldRe -> FldCom`

Return the complex field which has real subfield $R$; in other words, return the complex field with the same precision as the real field $R$.

<a id="example-ex-108c46"></a>
##### `Example: Creating a Complex Field (ex-108c46)`

It is convenient to use ${\rm i}$ to define elements of a complex field. It is also possible to change the default printing of i, using `AssignNames`, as follows. Note that the latter procedure does not assign to an identifier, it only changes the printing.

```magma
> C<i> := ComplexField(20);
> Pi(C)+ 1/4*i;
3.1415926535897932385 + 0.25000000000000000000*i
> AssignNames(~C, ["k"]);
> Pi(C)+ 1/4*i;
3.1415926535897932385 + 0.25000000000000000000*k
> k := Name(C, 1);
> Pi(C)+ 1/4*k;
3.1415926535897932385 + 0.25000000000000000000*k
```

#### Creation of Elements

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt"></a>
##### `a . becpd: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-2"></a>
##### `a . bEcPd: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-3"></a>
##### `a.bec P d: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-4"></a>
##### `a.bec p d: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-5"></a>
##### `a.b E cpd: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

<a id="operation-operation-rngintelt-rngintelt-rngintelt-fldreelt-6"></a>
##### `a.b e cpd: RngIntElt, RngIntElt, RngIntElt -> FldReElt`

Given a succession of literal decimal digits $a$, a succession of literal decimal digits $b$, a succession of literal decimal digits $c$, and an integer $d$, construct the real number $r=a.b \times 10^c$. If specified, the effect of $d$ is to create $r$ as an element of the real field of precision $d$. If $d$ is omitted (together with `p` or `P`), the real number will be created as an element of the default real field. Both $a$ and $c$ may include a leading sign `+` or `-`; leading zeroes in $a$ and $c$ are ignored. If $b$ consists entirely of zeroes it may be omitted together with the `.` and if $c$ is zero it may be omitted together with `E` (or `e`). But note that if all of $b$, $c$, and $d$ are omitted the result will be an integer.

<a id="constructor-constructor-elt-fldre-fldreelt-rngintelt-fldreelt"></a>
##### `elt<R | m, n>: FldRe, FldReElt, RngIntElt -> FldReElt`

Given the real field $R$, an element $m$ coercible into $R$, and an integer $n$, construct the real number $m \times 2^n$ in $R$.

<a id="constructor-constructor-elt-fldcom-fldreelt-fldreelt-fldcomelt"></a>
##### `elt<C | x, y>: FldCom, FldReElt, FldReElt -> FldComElt`

<a id="operation-op-fldcom-fldreelt-fldreelt"></a>
##### `C ! [x, y]: FldCom, [FldReElt, FldReElt] -> FldComElt`

Given the complex field $C$ and elements $x$ and $y$ coercible into the real field underlying $C$, construct the complex number $x+y{\mathrm{i}}$.

<a id="operation-op-fldre-rngelt"></a>
##### `R ! a: FldRe, RngElt -> FldReElt`

Given an integer, a rational number, a quadratic or cyclotomic number field element $a$, this returns an element from the real field $R$ that best approximates $a$. An error results if $a$ is a non-real quadratic or cyclotomic field element. If $R$ is a field of precision $r$ and $a$ is an element of a real field $S$ of precision $s$ then:

**•**
if $a$ is an element of a real field $S$ of precision $s \geq r$, then an element of $R$ approximating $a$ to $r$ digits is returned;

**•**
if $a$ is an element of a real field $S$ of precision $s < r$, then an element of $R$ is returned approximating $a$, obtained by padding with zeroes until the required precision $r$ is reached;

<a id="operation-op-fldcom-rngelt"></a>
##### `C ! a: FldCom, RngElt -> FldComElt`

Given an integer, a rational number, a quadratic or cyclotomic number field element $a$, this returns an element from the complex field $C$ that best approximates $a$. The rules of coercion for the real and imaginary parts are the same as those for coercion into a real field.

<a id="example-ex-356721"></a>
##### `Example: Creating Real Numbers (ex-356721)`

We create the real number $1.2345$ in many ways. We assume that the default real field has not been changed.

```magma
> x := 1.2345;
> x, Parent(x);
1.23450000000000000000000000000 Real field of precision 30
> SetDefaultRealField(RealField(20));
> x1 := 1.2345;
> x1, Parent(x1);
1.2345000000000000000 Real field of precision 20
> x2 := 12345e-4;
> x2, Parent(x2);
1.2345000000000000000 Real field of precision 20
> x3 := 1.2345p10;
> x3, Parent(x3);
1.234500000 Real field of precision 10
> x4 := 12345e-4p8;
> x4, Parent(x4);
1.2345000 Real field of precision 8
> x5 := RealField(12) ! 1.2345;
> x5, Parent(x5);
1.23450000000 Real field of precision 12
```

The following generic element constructions are available; they return the $1$ and $0$ element of a real or complex field, where any zero elements are the “positive zero” in MPFR.

<a id="function-one-fldre"></a>
##### `One(R): FldRe -> FldReElt`

<a id="function-one-fldcom"></a>
##### `One(R): FldCom -> FldComElt`

<a id="function-identity-fldre"></a>
##### `Identity(R): FldRe -> FldReElt`

<a id="function-identity-fldcom"></a>
##### `Identity(R): FldCom -> FldComElt`

<a id="function-zero-fldre"></a>
##### `Zero(R): FldRe -> FldReElt`

<a id="function-zero-fldcom"></a>
##### `Zero(R): FldCom -> FldComElt`

<a id="function-representative-fldre"></a>
##### `Representative(R): FldRe -> FldReElt`

<a id="function-representative-fldcom"></a>
##### `Representative(R): FldCom -> FldComElt`

### Structure Operations

#### Related Structures

<a id="function-category-fldre"></a>
##### `Category(R): FldRe -> Cat`

<a id="function-category-fldcom"></a>
##### `Category(R): FldCom -> Cat`

<a id="function-parent-fldre"></a>
##### `Parent(R): FldRe -> PowerStructure`

<a id="function-parent-fldcom"></a>
##### `Parent(R): FldCom -> PowerStructure`

<a id="function-primefield-fldre"></a>
##### `PrimeField(R): FldRe -> FldRat`

<a id="function-primefield-fldcom"></a>
##### `PrimeField(R): FldCom -> FldRat`

#### Numerical Invariants

<a id="function-characteristic-fldre"></a>
##### `Characteristic(R): FldRe -> RngIntElt`

<a id="function-characteristic-fldcom"></a>
##### `Characteristic(R): FldCom -> RngIntElt`

#### Ring Predicates and Booleans

<a id="function-iscommutative-fldre"></a>
##### `IsCommutative(R): FldRe -> BoolElt`

<a id="function-iscommutative-fldcom"></a>
##### `IsCommutative(R): FldCom -> BoolElt`

<a id="function-isunitary-fldre"></a>
##### `IsUnitary(R): FldRe -> BoolElt`

<a id="function-isunitary-fldcom"></a>
##### `IsUnitary(R): FldCom -> BoolElt`

<a id="function-isfinite-fldre"></a>
##### `IsFinite(R): FldRe -> BoolElt`

<a id="function-isfinite-fldcom"></a>
##### `IsFinite(R): FldCom -> BoolElt`

<a id="function-isordered-fldre"></a>
##### `IsOrdered(R): FldRe -> BoolElt`

<a id="function-isordered-fldcom"></a>
##### `IsOrdered(R): FldCom -> BoolElt`

<a id="function-isfield-fldre"></a>
##### `IsField(R): FldRe -> BoolElt`

<a id="function-isfield-fldcom"></a>
##### `IsField(R): FldCom -> BoolElt`

<a id="function-iseuclideandomain-fldre"></a>
##### `IsEuclideanDomain(R): FldRe -> BoolElt`

<a id="function-iseuclideandomain-fldcom"></a>
##### `IsEuclideanDomain(R): FldCom -> BoolElt`

<a id="function-ispid-fldre"></a>
##### `IsPID(R): FldRe -> BoolElt`

<a id="function-ispid-fldcom"></a>
##### `IsPID(R): FldCom -> BoolElt`

<a id="function-isufd-fldre"></a>
##### `IsUFD(R): FldRe -> BoolElt`

<a id="function-isufd-fldcom"></a>
##### `IsUFD(R): FldCom -> BoolElt`

<a id="function-isdivisionring-fldre"></a>
##### `IsDivisionRing(R): FldRe -> BoolElt`

<a id="function-isdivisionring-fldcom"></a>
##### `IsDivisionRing(R): FldCom -> BoolElt`

<a id="function-iseuclideanring-fldre"></a>
##### `IsEuclideanRing(R): FldRe -> BoolElt`

<a id="function-iseuclideanring-fldcom"></a>
##### `IsEuclideanRing(R): FldCom -> BoolElt`

<a id="function-isprincipalidealring-fldre"></a>
##### `IsPrincipalIdealRing(R): FldRe -> BoolElt`

<a id="function-isprincipalidealring-fldcom"></a>
##### `IsPrincipalIdealRing(R): FldCom -> BoolElt`

<a id="function-isdomain-fldre"></a>
##### `IsDomain(R): FldRe -> BoolElt`

<a id="function-isdomain-fldcom"></a>
##### `IsDomain(R): FldCom -> BoolElt`

<a id="operation-op-eq-fldre-fldre"></a>
##### `R eq S: FldRe, FldRe -> BoolElt`

<a id="operation-op-ne-fldre-fldre"></a>
##### `R ne S: FldRe, FldRe -> BoolElt`

<a id="operation-op-eq-fldcom-fldcom"></a>
##### `R eq S: FldCom, FldCom -> BoolElt`

<a id="operation-op-ne-fldcom-fldcom"></a>
##### `R ne S: FldCom, FldCom -> BoolElt`

#### Other Structure Functions

<a id="function-precision-fldcom"></a>
##### `Precision(R): FldCom -> RngIntElt`

<a id="function-precision-fldre"></a>
##### `Precision(R): FldRe -> RngIntElt`

Return the decimal precision $p$ to which calculations are performed in the real or complex field $R$.

<a id="function-bitprecision-fldcom"></a>
##### `BitPrecision(R): FldCom -> RngIntElt`

<a id="function-bitprecision-fldre"></a>
##### `BitPrecision(R): FldRe -> RngIntElt`

Return the (internally used) bit precision $p$ to which calculations are performed in the real or complex field $R$.

### Element Operations

#### Generic Element Functions and Predicates

All predicates on real or complex numbers that check whether these numbers are equal to an integer do so within the given precision of the parent field. Thus `IsOne(c)` for an element of a complex domain of precision 20 returns true if and only if the real part equals one and the imaginary part equals 0 up to 20 decimals.

Note that `IsZero` will match either the positive or negative zero in MPFR.

<a id="function-parent-fldreelt"></a>
##### `Parent(r): FldReElt -> Rng`

<a id="function-parent-fldcomelt"></a>
##### `Parent(r): FldComElt -> Rng`

<a id="function-category-fldreelt"></a>
##### `Category(r): FldReElt -> Cat`

<a id="function-category-fldcomelt"></a>
##### `Category(r): FldComElt -> Cat`

<a id="function-iszero-fldreelt"></a>
##### `IsZero(r): FldReElt -> BoolElt`

<a id="function-iszero-fldcomelt"></a>
##### `IsZero(r): FldComElt -> BoolElt`

<a id="function-isone-fldreelt"></a>
##### `IsOne(r): FldReElt -> BoolElt`

<a id="function-isone-fldcomelt"></a>
##### `IsOne(r): FldComElt -> BoolElt`

<a id="function-isminusone-fldreelt"></a>
##### `IsMinusOne(r): FldReElt -> BoolElt`

<a id="function-isminusone-fldcomelt"></a>
##### `IsMinusOne(r): FldComElt -> BoolElt`

<a id="function-isunit-fldreelt"></a>
##### `IsUnit(r): FldReElt -> BoolElt`

<a id="function-isunit-fldcomelt"></a>
##### `IsUnit(r): FldComElt -> BoolElt`

<a id="function-iszerodivisor-fldreelt"></a>
##### `IsZeroDivisor(r): FldReElt -> BoolElt`

<a id="function-iszerodivisor-fldcomelt"></a>
##### `IsZeroDivisor(r): FldComElt -> BoolElt`

<a id="function-isidempotent-fldreelt"></a>
##### `IsIdempotent(r): FldReElt -> BoolElt`

<a id="function-isidempotent-fldcomelt"></a>
##### `IsIdempotent(r): FldComElt -> BoolElt`

<a id="function-isnilpotent-fldreelt"></a>
##### `IsNilpotent(r): FldReElt -> BoolElt`

<a id="function-isnilpotent-fldcomelt"></a>
##### `IsNilpotent(r): FldComElt -> BoolElt`

<a id="function-isirreducible-fldreelt"></a>
##### `IsIrreducible(r): FldReElt -> BoolElt`

<a id="function-isirreducible-fldcomelt"></a>
##### `IsIrreducible(r): FldComElt -> BoolElt`

<a id="function-isprime-fldreelt"></a>
##### `IsPrime(r): FldReElt -> BoolElt`

<a id="function-isprime-fldcomelt"></a>
##### `IsPrime(r): FldComElt -> BoolElt`

#### Comparison of and Membership

The (in)equality test on real numbers of only test for equality up to the given precision. Equality testing on complex numbers is done by testing the real and imaginary parts.

Again the positive and negative zero in MPFR are equal.

The comparison functions `gt, ge, lt, le` are not defined for complex numbers.

<a id="operation-op-eq-fldreelt-fldreelt"></a>
##### `a eq b: FldReElt, FldReElt -> BoolElt`

<a id="operation-op-ne-fldreelt-fldreelt"></a>
##### `a ne b: FldReElt, FldReElt -> BoolElt`

<a id="operation-op-eq-fldcomelt-fldcomelt"></a>
##### `a eq b: FldComElt, FldComElt -> BoolElt`

<a id="operation-op-ne-fldcomelt-fldcomelt"></a>
##### `a ne b: FldComElt, FldComElt -> BoolElt`

<a id="operation-op-in-fldreelt-fldre"></a>
##### `a in R: FldReElt, FldRe -> BoolElt`

<a id="operation-op-notin-fldreelt-fldre"></a>
##### `a notin R: FldReElt, FldRe -> BoolElt`

<a id="operation-op-in-fldcomelt-fldcom"></a>
##### `a in R: FldComElt, FldCom -> BoolElt`

<a id="operation-op-notin-fldcomelt-fldcom"></a>
##### `a notin R: FldComElt, FldCom -> BoolElt`

<a id="operation-op-gt-fldreelt-fldreelt"></a>
##### `a gt b: FldReElt, FldReElt -> BoolElt`

<a id="operation-op-ge-fldreelt-fldreelt"></a>
##### `a ge b: FldReElt, FldReElt -> BoolElt`

<a id="operation-op-lt-fldreelt-fldreelt"></a>
##### `a lt b: FldReElt, FldReElt -> BoolElt`

<a id="operation-op-le-fldreelt-fldreelt"></a>
##### `a le b: FldReElt, FldReElt -> BoolElt`

<a id="function-maximum-fldreelt-fldreelt"></a>
##### `Maximum(a, b): FldReElt, FldReElt -> FldReElt`

<a id="function-minimum-fldreelt-fldreelt"></a>
##### `Minimum(a, b): FldReElt, FldReElt -> FldReElt`

<a id="function-maximum-fldreelt"></a>
##### `Maximum(Q): [FldReElt] -> FldReElt`

<a id="function-minimum-fldreelt"></a>
##### `Minimum(Q): [FldReElt] -> FldReElt`

#### Other Predicates

<a id="function-isintegral-fldreelt"></a>
##### `IsIntegral(c): FldReElt -> BoolElt`

<a id="function-isintegral-fldcomelt"></a>
##### `IsIntegral(c): FldComElt -> BoolElt`

Returns `true` if and only if the real or complex number $c$ is a rational integer.

<a id="function-isreal-fldcomelt"></a>
##### `IsReal(c): FldComElt -> BoolElt`

Returns `true` if the complex number $c$ is real, `false` otherwise. This checks whether the digits of the imaginary part of $c$ are $0$ up to the precision of the parent complex field.

#### Arithmetic

The binary operations `+, -, *, /` allow combinations of arguments from the integers, the rationals, and real and complex fields; automatic coercion is applied where necessary (see the Introduction).

<a id="operation-operation-fldreelt-fldreelt"></a>
##### `+ r: FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt"></a>
##### `+ r: FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-2"></a>
##### `- r: FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-2"></a>
##### `- r: FldComElt -> FldComElt`

<a id="operation-op-plus-fldreelt-fldreelt"></a>
##### `r + s: FldReElt, FldReElt -> FldReElt`

<a id="operation-op-plus-fldcomelt-fldcomelt"></a>
##### `r + s: FldComElt, FldComElt -> FldComElt`

<a id="operation-op-minus-fldreelt-fldreelt"></a>
##### `r - s: FldReElt, FldReElt -> FldReElt`

<a id="operation-op-minus-fldcomelt-fldcomelt"></a>
##### `r - s: FldComElt, FldComElt -> FldComElt`

<a id="operation-op-times-fldreelt-fldreelt"></a>
##### `r * s: FldReElt, FldReElt -> FldReElt`

<a id="operation-op-times-fldcomelt-fldcomelt"></a>
##### `r * s: FldComElt, FldComElt -> FldComElt`

<a id="operation-op-div-fldreelt-fldreelt"></a>
##### `r / s: FldReElt, FldReElt -> FldReElt`

<a id="operation-op-div-fldcomelt-fldcomelt"></a>
##### `r / s: FldComElt, FldComElt -> FldComElt`

<a id="operation-op-pow-fldreelt-fldreelt"></a>
##### `r ^ k: FldReElt, FldReElt -> FldReElt`

<a id="operation-op-pow-fldreelt-rngintelt"></a>
##### `r ^ k: FldReElt, RngIntElt -> FldReElt`

<a id="operation-op-pow-fldcomelt-rngintelt"></a>
##### `r ^ k: FldComElt, RngIntElt -> FldComElt`

<a id="operation-op-pow-fldcomelt-fldcomelt"></a>
##### `r ^ k: FldComElt, FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-fldreelt"></a>
##### `r +:= s: FldReElt, FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-fldcomelt"></a>
##### `r +:= s: FldComElt, FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-fldreelt-2"></a>
##### `r -:= s: FldReElt, FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-fldcomelt-2"></a>
##### `r -:= s: FldComElt, FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-fldreelt-3"></a>
##### `r *:= s: FldReElt, FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-fldcomelt-3"></a>
##### `r *:= s: FldComElt, FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-fldreelt-4"></a>
##### `r /:= s: FldReElt, FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-fldcomelt-4"></a>
##### `r /:= s: FldComElt, FldComElt -> FldComElt`

<a id="operation-operation-fldreelt-fldreelt-fldreelt-5"></a>
##### `r ^:= s: FldReElt, FldReElt -> FldReElt`

<a id="operation-operation-fldcomelt-fldcomelt-fldcomelt-5"></a>
##### `r ^:= s: FldComElt, FldComElt -> FldComElt`

#### Conversions

Here we list various ways to convert between integers, reals of fixed precision, complexes, and their various representations, other than by the creation functions and `!`. See also the rounding functions in a later section.

<a id="function-mantissaexponent-fldreelt"></a>
##### `MantissaExponent(r): FldReElt -> RngIntElt, RngIntElt`

Given a real number $r$, this function returns an integer $m$ (the mantissa of $r$) and an integer $e$ (the exponent of $r$) such that $r\approx m\times 2^e$, with the size of $m$ being the same as that of the internal representation of $r$.

<a id="function-complextopolar-fldcomelt"></a>
##### `ComplexToPolar(c): FldComElt -> FldReElt, FldReElt`

Given a complex number $c$, return the modulus $m\geq 0$ and the argument $a$ (with $-\pi\leq a\leq\pi$) of $c$ as real numbers to the same precision as $c$.

<a id="function-polartocomplex-fldreelt-fldreelt"></a>
##### `PolarToComplex(m, a): FldReElt, FldReElt -> FldComElt`

Given real numbers $m$ and $a$, construct the complex number $me^{ia}$. The result will have the smaller of the precisions of $m$ and $a$; each of $m$ and $a$ is allowed to be an integer or rational number; if both are integral or rational then the result will have the default precision, otherwise the result will be of the same precision as the real argument.

<a id="function-argument-fldcomelt"></a>
##### `Argument(c): FldComElt -> FldReElt`

<a id="function-arg-fldcomelt"></a>
##### `Arg(c): FldComElt -> FldReElt`

Given a complex number $c$, return the real number (to the same precision) that is the argument (in radians between $-\pi$ and $\pi$) of $c$.

<a id="example-ex-9ff75f"></a>
##### `Example: Argument of a Signed Zero (ex-9ff75f)`

We note the argument of $-1$ with an imaginary part of positive zero differs from that of the argument of $-1$ with an imaginary part of negative zero. This follows the MPFR/MPC specifications.

```magma
> C := ComplexField(30);
> x := -One(C);
> Imaginary(x); // imaginary part is negative zero
-0.000000000000000000000000000000
> Arg(x); // approximately negative pi as Arg
-3.14159265358979323846264338328
> y := C!-1; // coerce, so imag part is positive zero
> Imaginary(y); // positive zero
0.000000000000000000000000000000
> Arg(y); // approximately positive pi as Arg
3.14159265358979323846264338328
> assert x eq y; // note that x and y are indeed equal!
```

<a id="function-modulus-fldcomelt"></a>
##### `Modulus(c): FldComElt -> FldReElt`

Given a complex number $c$, return the real number (to the same precision as $c$) that is the modulus of $c$.

<a id="function-real-fldcomelt"></a>
##### `Real(c): FldComElt -> FldReElt`

<a id="function-re-fldcomelt"></a>
##### `Re(c): FldComElt -> FldReElt`

Given a complex number $c=x+y{\mathrm{i}}$, return the real part $x$ of $c$ (as a real number to the same precision as $c$).

<a id="function-imaginary-fldcomelt"></a>
##### `Imaginary(c): FldComElt -> FldReElt`

<a id="function-im-fldcomelt"></a>
##### `Im(c): FldComElt -> FldReElt`

Given a complex number $c=x+y{\mathrm{i}}$, return the imaginary part $y$ of $c$ (as a real number to the same precision as $c$).

#### Rounding

<a id="function-round-fldreelt"></a>
##### `Round(r): FldReElt -> FldReElt`

<a id="function-round-fldcomelt"></a>
##### `Round(r): FldComElt -> RngQuadElt`

Given a real number $r$, return the integer $i$ for which $|r - i|$ is a minimum. i.e., the integer closest to $r$. If there are two such integers, the one of larger magnitude is chosen (rounding away from zero). Given a (non-real) complex number $r$, return the Gaussian integer $i$ for which $|r - i|$ is a minimum, i.e. the Gaussian integer closest to $r$.

<a id="function-truncate-fldreelt"></a>
##### `Truncate(r): FldReElt -> RngIntElt`

Given a real number $r$, return $\lfloor r\rfloor$ if $r$ is positive, and return $-\lfloor -r\rfloor + 1$ if $r$ is negative. Thus, the effect of this function is to round towards zero.

<a id="function-ceiling-infty"></a>
##### `Ceiling(r): Infty -> Infty`

<a id="function-ceiling-fldreelt"></a>
##### `Ceiling(r): FldReElt -> RngIntElt`

The ceiling of the real number $r$, i.e. the smallest integer greater than or equal to $r$.

<a id="function-floor-infty"></a>
##### `Floor(r): Infty -> Infty`

<a id="function-floor-fldreelt"></a>
##### `Floor(r): FldReElt -> RngIntElt`

The floor of the real number $r$, i.e. the greatest integer less than or equal to $r$.

#### Precision

<a id="function-precision-fldreelt"></a>
##### `Precision(r): FldReElt -> RngIntElt`

<a id="function-precision-fldcomelt"></a>
##### `Precision(c): FldComElt -> RngIntElt`

Given a real or complex number $c$ belonging to the real or complex field $C$, return the decimal precision $p$ to which calculations are performed in $C$.

<a id="function-bitprecision-fldreelt"></a>
##### `BitPrecision(r): FldReElt -> RngIntElt`

<a id="function-bitprecision-fldcomelt"></a>
##### `BitPrecision(c): FldComElt -> RngIntElt`

Given a real or complex number $c$ belonging to the real or complex field $C$, return the (internally used) bit precision $p$ to which calculations are performed in $C$.

<a id="function-precision-fldreelt-2"></a>
##### `Precision(L): [FldReElt] -> RngIntElt`

<a id="function-precision-fldcomelt-2"></a>
##### `Precision(L): [FldComElt] -> RngIntElt`

Gives a sequence of real or complex numbers, return the precision $p$ of their parent field.

<a id="function-changeprecision-fldreelt-rngintelt"></a>
##### `ChangePrecision(r, n): FldReElt, RngIntElt -> FldReElt`

<a id="function-changeprecision-fldcomelt-rngintelt"></a>
##### `ChangePrecision(c, n): FldComElt, RngIntElt -> FldComElt`

Coerces the real ($r$) or complex ($c$) number into a field of precision $n$.

#### Constants

Let $R$ denote a real or complex field. The functions described below will return an approximation of certain constants to the precision associated with a given real or complex field $R$. If $R$ is real, a real number is returned; if $R$ is complex, a complex number with imaginary part zero is returned.

<a id="function-catalan-fldre"></a>
##### `Catalan(R): FldRe -> FldReElt`

<a id="function-catalan-fldcom"></a>
##### `Catalan(R): FldCom -> FldComElt`

The value of Catalan’s constant computed to the accuracy associated with the real or complex field $R$. Catalan’s constant is the sum

$$
\sum_{k=0}^\infty (-1)^k (2k + 1)^{-2}.
$$

MPFR calculates this constant using formula (31) of Victor Adamchik’s document “33 representations for Catalan’s constant” `https://web.archive.org/web/20120805142652/http://www.cs.cmu.edu/~adamchik/articles/catalan/catalan.htm`, for more information see `mpfr.org`.

<a id="function-eulergamma-fldre"></a>
##### `EulerGamma(R): FldRe -> FldReElt`

<a id="function-eulergamma-fldcom"></a>
##### `EulerGamma(R): FldCom -> FldComElt`

The value of Euler’s constant

$$
\gamma = \lim_{n\rightarrow\infty}(1+{1\over2}+{1\over3}+\cdots+{1\over n}-\log n) \approx 0.57721566
$$

computed to the precision of $R$.

<a id="function-pi-fldre"></a>
##### `Pi(R): FldRe -> FldReElt`

<a id="function-pi-fldcom"></a>
##### `Pi(R): FldCom -> FldComElt`

The value of $\pi$ computed to the precision of $R$.

#### Simple Element Functions

<a id="function-absolutevalue-fldreelt"></a>
##### `AbsoluteValue(r): FldReElt -> FldReElt`

<a id="function-absolutevalue-fldcomelt"></a>
##### `AbsoluteValue(r): FldComElt -> FldReElt`

<a id="function-abs-fldreelt"></a>
##### `Abs(r): FldReElt -> FldReElt`

<a id="function-abs-fldcomelt"></a>
##### `Abs(r): FldComElt -> FldReElt`

The absolute value of the real or complex number $r$.

<a id="function-sign-fldreelt"></a>
##### `Sign(r): FldReElt -> RngIntElt`

Return one of the integer values $+1$, 0, $-1$ depending upon whether the real number $r$ is positive, zero, or negative, respectively.

<a id="function-complexconjugate-fldreelt"></a>
##### `ComplexConjugate(r): FldReElt -> FldReElt`

<a id="function-complexconjugate-fldcomelt"></a>
##### `ComplexConjugate(c): FldComElt -> FldComElt`

<a id="function-conjugate-fldcomelt"></a>
##### `Conjugate(c): FldComElt -> FldComElt`

The complex conjugate $x-y{\mathrm{i}}$ of a complex number $x+y{\mathrm{i}}$.

<a id="function-norm-fldcomelt"></a>
##### `Norm(c): FldComElt -> FldReElt`

<a id="function-norm-fldreelt"></a>
##### `Norm(r): FldReElt -> FldReElt`

The real norm of a real or complex number $c$; note that for complex $c=x+y{\mathrm{i}}$ this returns $x^2+y^2$, while for elements of real domains it just returns the absolute value. The result lies in the same field as the argument.

<a id="function-root-fldreelt-rngintelt"></a>
##### `Root(r, n): FldReElt, RngIntElt -> FldReElt`

<a id="function-root-fldcomelt-rngintelt"></a>
##### `Root(r, n): FldComElt, RngIntElt -> FldComElt`

Given a real number $R$ and a positive integer $n$, calculate $\root n \of r$ (using Newton’s method without divisions) with the same precision. If $n$ is even then $r$ must be non-negative.

<a id="function-squareroot-fldcomelt"></a>
##### `SquareRoot(c): FldComElt -> FldComElt`

<a id="function-sqrt-fldcomelt"></a>
##### `Sqrt(c): FldComElt -> FldComElt`

<a id="function-squareroot-fldreelt"></a>
##### `SquareRoot(r): FldReElt -> FldReElt`

<a id="function-sqrt-fldreelt"></a>
##### `Sqrt(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the square root of $r$ as an element of the same field to which $r$ belongs.

<a id="function-distance-fldreelt-fldreelt"></a>
##### `Distance(x, L): FldReElt, [FldReElt] -> FldReElt, RngIntElt`

<a id="function-distance-fldreelt-fldcomelt"></a>
##### `Distance(x, L): FldReElt, [FldComElt] -> FldReElt, RngIntElt`

<a id="function-distance-fldcomelt-fldreelt"></a>
##### `Distance(x, L): FldComElt, [FldReElt] -> FldReElt, RngIntElt`

<a id="function-distance-fldcomelt-fldcomelt"></a>
##### `Distance(x, L): FldComElt, [FldComElt] -> FldReElt, RngIntElt`

```magma
Max: ExtReElt                    Default: Infinity()
```

Given a sequence $L$ of real or complex numbers and an additional number $x$ compute the distance between $x$ and $L$, ie. $\min_{y\in L} |x-y|$, that is the shortest distance between $x$ and any element of $L$. Furthermore, the index in $L$ of an element realising the distance is returned as a second argument.

Note: prior to V2.21, the `Distance` was only to be used for *short* distances, and thus a maximum of 1 was returned. Through the use of a new `Max` vararg (setting this equal to 1), this old behaviour can be obtained.

<a id="function-diameter-fldreelt"></a>
##### `Diameter(L): [FldReElt] -> FldReElt`

<a id="function-diameter-fldcomelt"></a>
##### `Diameter(L): [FldComElt] -> FldReElt`

```magma
Max: ExtReElt                    Default: Infinity()
```

Given a sequence $L$ of real of complex numbers, compute the diameter of the set defined by $L$, ie. the smallest distance between distinct elements of $L$.

Note: prior to V2.21, the `Diameter` was only to be used for *short* distances, and thus a maximum of 1 was returned. Through the use of a new `Max` vararg (setting this equal to 1), this old behaviour can be obtained.

#### Roots

Magma contains a very powerful algorithm for finding highly accurate approximations to the complex roots of a polynomial; it is based on Xavier Gourdon’s implementation of Schönhage’s algorithm, which we will summarize below.

Given a polynomial $p = a_0 + a_1 z + \cdots + a_n z^n \in {\mathbb{C}}[z]$, define the norm of $p$, $|p|$, by

$$
|p| = |a_0| + |a_1| + \cdots + |a_n|.
$$

Schönhage’s algorithm (given in his technical report of 1982 [[Sch82](https://docs.magma-maths.org/references.md#cite-schoenhage82)]) takes as input a univariate polynomial $p$ in ${\mathbb{C}}[z]$ and a positive real number $\varepsilon$, and finds linear factors $L_j = u_j z - v_j$ ($j = 1, \ldots, n = \deg(p)$) such that

$$
|p - L_1 \cdots L_n| < \varepsilon |p|.
$$

The parameter $\varepsilon$ may be chosen so as to find the roots of $p$ to within a certain $\varepsilon'$, and this is how the function `Roots` described below works (when run with Schönhage’s algorithm).

The algorithm uses the concept of a ‘splitting circle’ to find polynomials $F$ and $G$ such that $|p - FG| < \varepsilon_1 |p|$ for some $\varepsilon_1$ depending on $\varepsilon$.

This splitting circle method can then be applied recursively to $F$ and $G$ until we have only linear factors, as required.

The splitting circle method works as follows. For the purposes of this discussion assume that $p$ is monic. Suppose we know a circle $\Gamma$ such that, for some integer $k$ with $0 < k < n$, there are $k$ roots of $p$ (say $u_1, \ldots, u_k$) which lie inside $\Gamma$, and the other $n-k$ roots ($u_{k+1}, \ldots, u_n$) lie outside $\Gamma$. Note that the circle $\Gamma$ is chosen so that the roots of $p$ are not too close to it. Then we can write $p = FG$, where $F = (z-u_1)\ldots(z-u_k)$ and $G = (z-u_{k+1})\ldots(z-u_n)$. Through shifts and scalings, we may assume that $\Gamma = \{c\in{\mathbb{C}}: \| z\|  = 1\}$.

For $m$ in $\{1, \ldots, k\}$, let $s_m$ denote the $m$-th power sum of the roots of $p$ which lie inside the splitting circle. That is,

$$
s_m = u_1^m + \cdots + u_k^m.
$$

The residue theorem can then be used to calculate $s_m$ ($1 \le m \le k$):

$$
s_m = {1 \over 2\pi i} \int_{\Gamma} z^m {p'(z) \over p(z)}\, dz.
$$

where the integration can be computed to the required precision by the discrete sum

$$
s_m \approx {1 \over N} \sum_{j=0}^{N-1} {p'(\omega^j) \over p(\omega^j)} \omega^{(m+1)j}.
$$

for a large enough integer $N$, where $\omega = \exp(2\pi i/N)$.

The coefficients of the polynomial $F$ can then be computed from the Newton sums $s_m$ ($1 \le m \le k$) using the classical Newton formulae. Then set $G = p/F$.

The integer $N$ above needed to get $F$ and $G$ to the required precision can be quite large. It is more efficient to use a smaller value of $N$ to give an approximation $F_0$ of $F$, and then use the following refining technique.

Define $G_0$ (an approximation of $G$) by $p = F_0 G_0 + r$, where $\deg(r) < \deg(F_0)$. We want polynomials $f$ and $g$ such that $F_1 = F_0 + f$ and $G_1 = G_0 + g$ are better approximations of $F$ and $G$. Now

$$
p - F_1 G_1 = p - F_0 G_0 - f G_0 - g F_0 - fg.
$$

Hence choosing $f$ and $g$ such that

$$
p - F_0 G_0 = f G_0 + g F_0
$$

will lead to a second order error.

The Euclidean algorithm could be used to find $f$ and $g$, but this is numerically unstable. It suffices to find polynomials $H$ (called the auxiliary polynomial) and $L$ such that $1 = H G_0 + L F_0,$ where $\deg(H)<\deg(F_0)$ and $\deg(L)<\deg(G_0)$.

The polynomial $H$ can be calculated using the formula

$$
H(z) = {1\over 2\pi i} \int_{\Gamma} {1 \over (F_0 G_0)(t)} {F_0(z)-F_0(t)\over z-t}\, dt.
$$

Again, rather than computing the integral to the required precision directly, we find only an approximation $H_0$ and then refine it using Newton iteration:

$$
H_{m+1} \equiv H_m (2 - H_m G_0) \pmod{F_0}.
$$

Assuming that $|H - H_0|$ is small, the sequence $(H_m)$ converges quadratically to $H$.

Once $H$ is known to a large enough precision, $f$ can be computed by

$$
f \equiv H (p - F_0 G_0) \pmod{F_0}.
$$

This gives us the new approximation $F_1$ of $F$, and $G_1$ is computed by division of $p$ by $F_1$. We repeat this process until

$$
|p - FG| < \varepsilon_1 |p|
$$

and we are done.

The problem remains to find the splitting circle.

This relies mainly on the computation of the moduli of the roots of $p$. Let $r_1(p) \le r_2(p) \le \cdots \le r_n(p)$ denote the moduli of the roots of $p$ in ascending order. For each $k$, the computation of $r_k(p)$ with a small number of digits can be achieved in a reliable way using the Graeffe process. The Graeffe process is a root squaring step transforming any given polynomial $p$ into a polynomial $q$ of the same degree whose roots are the square of the roots of $p$.

By the use of a suitable shift, we may assume that the sum of the roots of $p$ is zero. If $p(0)=0$, then we have found a factorization $p\approx FG$ with $F=z$ and $G=p/z$. If not, then the computation of the maximum root modulus $r_n(p)$ allows us to scale $p$ so that its maximum root modulus is now close to $1$. For $j = 0, 1, 2, 3$, set

$$
q_j(z)=p(z + 2 i^j).
$$

Then amongst these four polynomials there exists $q$ such that

$$
{r_n(q) \over r_1(q)} = \exp(\Delta),
$$

with $\Delta > 0.3$. A dichotomic process from the computation of some $r_j(q)$ can then be applied to find $k$ ($1 \le k \le n-1$) such that

$$
{r_{k+1}(q) \over r_k(q)} > \exp({\Delta \over n-1}).
$$

Then the circle $\{c: \|c\|=\sqrt{r_k(q) r_{k+1}(q)}\}$ is a suitable splitting circle, with the roots not too close to it.

<a id="function-fldre-roots"></a>
##### `Roots(p): RngUPolElt -> [ <FldComElt, RngIntElt> ]`

```magma
Al    : MonStgElt                    Default: "Schonhage"
Digits: RngIntElt                    Default: 
```

Given a univariate polynomial $p$ over a real or complex field, this returns a sequence of complex approximations to the roots of $p$. The elements of this sequence are of the form $<r, m>$, where $r$ is a root and $m$ its multiplicity.

The algorithm used to find the roots of $p$ may be specified by using the optional argument `Al`. This must be one of `"Schonhage"` (which is the default), `"Laguerre"`, `"NewtonRaphson"`, or `"Combination"` (a combination of Laguerre and Newton-Raphson). When using the (default) Schönhage algorithm, the roots given are correct to within an absolute error of $10^{-d}$, where $d$ is the value of `Digits`. This algorithm gives correct results in all cases. When using the other algorithms (for which correct answers are not guaranteed in all cases), the results are found with `Digits` significant figures. The default value for `Digits` is the current precision of the free real field.

Pari is used here for complex polynomials.

*Warning*: Beware of the problems of floating point numbers. Because real numbers are stored in the computer with finite precision, you may not be finding the roots of the polynomial you want. If you know the polynomial exactly, you should enter it with exact (that is, integer or rational) coefficients. This is illustrated in the following example.

<a id="example-ex-04bda5"></a>
##### `Example: Roots of a Polynomial with a Multiple Root (ex-04bda5)`

```magma
> P<z> := PolynomialRing(ComplexField());
> p := (z-1.1)^6;
> p;
z^6 - 6.60000000000000000000000000001*z^5 +
    18.1500000000000000000000000000*z^4 -
    26.6200000000000000000000000000*z^3 +
    21.9615000000000000000000000000*z^2 -
    9.66306000000000000000000000003*z +
    1.77156100000000000000000000001
> R := Roots(p);
> R;
[ <1.10001330596590605421651999857, 1>,
<1.10000665289430860969298668917 +
1.15233044958179825651486651257E-5*i, 1>,
<1.10000665289430860969298668917 -
1.15233044958179825651486651257E-5*i, 1>,
<1.09998669421138030521834731234, 1>,
<1.09999334701704821058957965537 +
1.15231509613269858004669167711E-5*i, 1>,
<1.09999334701704821058957965537 -
1.15231509613269858004669167711E-5*i, 1> ]
> P<x> := PolynomialRing(Rationals());
> q := (x-11/10)^6;
> Roots(q);
[ <11/10, 6> ]
```

The function `RootsNonExact` (below) is more suitable for non-exact polynomials.

<a id="function-rootsnonexact-rngupolelt-fldre"></a>
##### `RootsNonExact(p): RngUPolElt[FldRe] -> [ FldComElt ], [ FldComElt ]`

<a id="function-rootsnonexact-rngupolelt-fldcom"></a>
##### `RootsNonExact(p): RngUPolElt[FldCom] -> [ FldComElt ], [ FldComElt ]`

Given a polynomial $p$ of degree $n$ defined over a real or complex field, returns a sequence $[v_1, \ldots, v_n]$ of complex numbers such that

$$
|p-a(z-v_1)\ldots(z-v_n)| < 10^{-d} |p|,
$$

where $a$ is the leading coefficient of $p$, and $d$ is the precision of the field.

A second sequence $[e_1, \ldots, e_n]$ of (free) real numbers may also be returned. Given any polynomial $\hat p$ such that $|p - \hat p| < 10^{-d} |p|$, we can write $\hat p = a(z-u_1)\ldots(z-u_n)$ with $|v_i - u_i| < e_i$. In some cases, such error bounds cannot be derived, because the value $d$ of `Digits` is too small for the given polynomial. In these cases, this second sequence is not returned.

This function acknowledges the fact that the polynomial $p$ may not be the exact polynomial wanted, but only an approximation (to a certain number of decimal places), and so the roots of the true polynomial can only be found to a limited number of decimal places. Increasing the precision will decrease the errors on the ‘roots’.

<a id="example-ex-a1670d"></a>
##### `Example: Roots with Error Estimates (ex-a1670d)`

```magma
> P<z> := PolynomialRing(ComplexField());
> p := (z-1.1)^6;
> R, E := RootsNonExact(p);
> R;
[ 1.10001483296913451410370191006 -
8.56404454142796527111307103383E-6*i,
1.10001483296913451410370191006 +
8.56404454142796527111304767692E-6*i,
1.09998516742199321904393975959 +
8.56336708832137724325720239457E-6*i,
1.09999999960887226685235833026 +
1.71274116266516824685125851069E-5*i,
1.09998516742199321904393771623 -
8.56336708832137723945115457519E-6*i,
1.09999999960887226685236037365 -
1.71274116266516824723187272572E-5*i ]
> E;
[ 0.00482314415421569719910621643066,
0.00482314415421569719910621643066,
0.00482301408919738605618476867676,
0.00482307911261159460991621017456,
0.00482301408919738605618476867676,
0.00482307911261159460991621017456 ]
```

<a id="function-hensellift-rngupolelt-fldreelt-rngintelt"></a>
##### `HenselLift(f, R, k): RngUPolElt, FldReElt, RngIntElt -> FldReElt`

<a id="function-hensellift-rngupolelt-fldcomelt-rngintelt"></a>
##### `HenselLift(f, R, k): RngUPolElt, FldComElt, RngIntElt -> FldComElt`

Let $f$ be a real or complex polynomial and $x$ an approximation to a single zero of $f$. This function will apply the Newton-iteration to improve the accuracy of the root to the precision indicated by $k$.

#### Continued Fractions

The following functions use the continued fraction expansion of real numbers to get Diophantine approximations. They were obtained from corresponding Pari implementations.

<a id="function-continuedfraction-fldratelt"></a>
##### `ContinuedFraction(r): FldRatElt -> [ RngIntElt ]`

<a id="function-continuedfraction-fldreelt"></a>
##### `ContinuedFraction(r): FldReElt -> [ RngIntElt ]`

```magma
Bound: RngIntElt                    Default: -1
```

Given an element $r$ from a real field, return a sequence of integers $s$ that form the partial quotient for the (regular) continued fraction expansion for $r$, so $r$ is approximately equal to

$$
s_1 + {1\over s_2 + { 1\over s_3 +
    \cdots + { 1\over s_n}}}.
$$

The length $n$ of the sequence is determined in such a way that the last significant partial quotient is obtained (determined by the precision with which $r$ is known), unless the optional integer argument `Bound` is used to limit the length.

<a id="function-bestapproximation-fldreelt-rngintelt"></a>
##### `BestApproximation(r, n): FldReElt, RngIntElt -> FldReElt`

Given an element $r$ from a real field and a positive integer $n$, this function determines a rational approximation to $r$ with denominator not exceeding $n$. The approximation is at least as close as the best continued fraction convergent with denominator not exceeding $n$. Pari is used here.

<a id="function-convergents-rngintelt"></a>
##### `Convergents(s): [ RngIntElt ] -> ModMatRngElt`

Given a sequence $s$ of $n$ non-negative integers (forming the partial fractions of a real number $r$, say), this function returns a $2\times 2$ matrix with integer coefficients

$$
\begin{pmatrix}p_n&p_{n-1}\\ q_n&q_{n-1}\end{pmatrix};
$$

the quotients $p_{n-1}/q_{n-1}$ and $p_{n}/q_{n}$ form the last two convergents for $r$ as provided by $s$.

#### Linear and Algebraic Dependencies

<a id="function-linearrelationlabel"></a>
##### `LinearRelation(q: parameters): [ FldComElt ] -> [ RngIntElt ]`

<a id="function-linearrelation-modtuprngelt"></a>
##### `LinearRelation(v: parameters): ModTupRngElt -> ModTupRngElt`

```magma
Al: MonStgElt                    Default: "LLL"
```

(Deprecated). Given a sequence $q$ or a vector $v$ with entries from a complex field, return an integer sequence or vector forming the coefficients for a (small) linear dependency among the entries. The algorithm now only uses `"LLL"` (not “Hastad”), and this function is deprecated in any case. The new version of this function is `IntegerRelation`.

<a id="function-alllinearrelations-seqenum-rngintelt"></a>
##### `AllLinearRelations(q, p): SeqEnum, RngIntElt -> Lat`

Given a sequence $q$ with entries from a real or complex field, return the lattice of all (small) integer linear dependencies among the entries. The precision $p$ is used both in the relation-detection, and to define “small” dependencies.

<a id="function-integerrelation-seqenum"></a>
##### `IntegerRelation(q): SeqEnum -> SeqEnum, FldReElt`

<a id="function-integerrelation-seqenum-rngintelt"></a>
##### `IntegerRelation(q, N): SeqEnum, RngIntElt -> SeqEnum, FldReElt`

```magma
Delta: FldReElt                    Default: 0.75
```

Given a sequence $q=(q_1,\ldots,q_d)$ with entries from a real or complex field, along possibly with an integer $N>0$, return a sequence $(n_1,\ldots,n_d)$ of integers such that: any $n_i$ has magnitude less or equal to $N$ and the quantity $|\sum n_i q_i|$ is small. The routine is based on the LLL lattice reduction algorithm [[LLL82](https://docs.magma-maths.org/references.md#cite-lll)] (see Chapter [Reduction of Matrices and Lattices](https://docs.magma-maths.org/LatticesQuadraticForms/Lattices/reduction.md#sectlatreduction)). The second return value is a measure of goodness-of-fit, and the second input value will be determined from the input precision of real/complex numbers if it is omitted.

<a id="function-powerrelation-fldreelt-rngintelt"></a>
##### `PowerRelation(r, k: parameters): FldReElt, RngIntElt -> RngUPolElt`

<a id="function-powerrelation-fldcomelt-rngintelt"></a>
##### `PowerRelation(r, k: parameters): FldComElt, RngIntElt -> RngUPolElt`

```magma
Al       : MonStgElt                    Default: "LLL"
Precision: RngIntElt                    Default: 
```

(Deprecated). Given an element $r$ from a real or complex field, and an integer $k>0$, return a univariate integer polynomial of degree at most $k$ having $r$ as an approximate root. The parameters here have the same usage and meaning as for `LinearRelation`. Pari is used here. The new version of this function is `MinimalPolynomial`.

<a id="function-minimalpolynomial-fldreelt-rngintelt-rngintelt"></a>
##### `MinimalPolynomial(r, d, N): FldReElt, RngIntElt, RngIntElt -> RngUPolElt, FldReElt`

<a id="function-minimalpolynomial-fldcomelt-rngintelt-rngintelt"></a>
##### `MinimalPolynomial(r, d, N): FldComElt, RngIntElt, RngIntElt -> RngUPolElt, FldReElt`

<a id="function-minimalpolynomial-fldreelt-rngintelt"></a>
##### `MinimalPolynomial(r, d): FldReElt, RngIntElt -> RngUPolElt -> FldReElt`

<a id="function-minimalpolynomial-fldcomelt-rngintelt"></a>
##### `MinimalPolynomial(r, d): FldComElt, RngIntElt -> RngUPolElt -> FldReElt`

```magma
Delta      : FldReElt                    Default: 0.75
ExactDegree: BoolElt                     Default: false
Squarefree : BoolElt                     Default: true
```

Given an element $r$ from a real or complex field and two integers $d\geq 1$ and $N\geq 1$, tries to compute a univariate integer polynomial of degree at most $d$ and coefficients of absolute values no greater than $N$ which is the minimal polynomial of a number close to $r$. The routine relies on the LLL lattice reduction algorithm [[LLL82](https://docs.magma-maths.org/references.md#cite-lll)] (see Chapter [Reduction of Matrices and Lattices](https://docs.magma-maths.org/LatticesQuadraticForms/Lattices/reduction.md#sectlatreduction)). When $N$ is not given, it is determined from the precision of $r$. The `ExactDegree` vararg requires that the output degree be exactly as stated, and `Squarefree` removes any repeated factors. The second return value is a measure of goodness-of-fit.

<a id="example-ex-b60a49"></a>
##### `Example: Polynomial Factorization via LLL (ex-b60a49)`

This example illustrates the `MinimalPolynomial` routine. It describes informally the Kannan-Lenstra-Lovász algorithm to factor univariate integer polynomials [[KLL84](https://docs.magma-maths.org/references.md#cite-kalelo84)]. The idea is to compute a complex root of the polynomial $P$ to be factored, and then compute the minimal polynomial $Q$ of this root. This polynomial is irreducible and divides $P$. We then continue recursively with $P/Q$.

Notice that the polynomial factorisation routine `Factorization` (see Section [Factorization](https://docs.magma-maths.org/BasicRings/UnivariatePolynomialRings/factorization.md#polfact)) relies upon Van Hoeij’s algorithm [[vH01](https://docs.magma-maths.org/references.md#cite-vhoeij2), [vH02](https://docs.magma-maths.org/references.md#cite-vhoeij1)]. Though both approaches have polynomial time complexities, Van Hoeij’s algorithm is significantly faster.

```magma
> C<i> := ComplexField(1000);
> P<X> := PolynomialRing(Integers());
> P_C<Z> := PolynomialRing(C);
> p0 := 5*X^12 + 64*X^11 + 51*X^10 + 38*X^9 - 60*X^8 - 56*X^7
>     - 51*X^6 - 14*X^5 - X^4 + 12*X^3 + 8*X^2 + 4*X;
> R := Roots (P_C!p0);
> root := R[1][1];
> res0 := MinimalPolynomial (root, 12, 100);
> p1 := P!(p0/res0);
> //
> R := Roots (P_C!p1);
> root := R[1][1];
> res1 := MinimalPolynomial (root, 11, 100);
> p2 := P!(p1/res1);
> //
> R := Roots (P_C!p2);
> root := R[1][1];
> res2 := MinimalPolynomial (root, 5, 100);
> p3 := P!(p2/res2);
> //
> R := Roots (P_C!p3);
> root := R[1][1];
> res3 := MinimalPolynomial (root, 4, 100);
> //
> assert p0 eq res0*res1*res2*res3;
> res0, res1, res2, res3;
X
X^6 + 13*X^5 + 13*X^4 + 13*X^3 - 4*X^2 - 4*X - 4
X - 1
5*X^4 + 4*X^3 + 3*X^2 + 2*X + 1
```

### Transcendental Functions

#### Exponential, Logarithmic, and Polylogarithmic Functions

In this section the exponential and logarithmic functions to the natural base $e$ are described, as well as the conversion to the logarithm with respect to any base. The power series expansions are

$$
e^z=\sum_{n=0}^\infty{z^n\over n!}, \quad\ln(1+z)=\sum_{n=1}^\infty(-1)^{n-1}{z^n\over n}.
$$

Further information on the Dilog and Polylog functions can be found in Lewin [[Lew81](https://docs.magma-maths.org/references.md#cite-lewin81)].

<a id="function-exp-rngserelt"></a>
##### `Exp(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the exponential power series of $f$.

<a id="function-exp-fldcomelt"></a>
##### `Exp(c): FldComElt -> FldComElt`

<a id="function-exp-fldreelt"></a>
##### `Exp(r): FldReElt -> FldReElt`

Given an arbitrary real or complex number $c$, return the exponential $e^c$ of $c$. Here $c$ is allowed to be free or of fixed precision, and the result is in the same field as $c$.

<a id="function-log-rngserelt"></a>
##### `Log(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the logarithm of $f$. The valuation of $f$ must be zero.

<a id="function-log-fldreelt"></a>
##### `Log(r): FldReElt -> FldReElt`

<a id="function-log-fldcomelt"></a>
##### `Log(c): FldComElt -> FldComElt`

Given a non-zero real or complex number $c$, return the logarithm of $c$ (to the natural base $e$). The principal value with imaginary part in $(-\pi, \pi]$ is chosen. The result will be a complex number, unless the argument is real and positive, in which case a real number is returned.

<a id="function-log-fldreelt-2"></a>
##### `Log(b, r): FldReElt -> FldReElt`

Given real numbers $b>0$, $b\ne 1$, and $r>0$, return the logarithm $\log_b(r)$ of $r$ to the base $b$. Automatic coercion is applied if necessary.

<a id="function-dilog-fldcomelt"></a>
##### `Dilog(s): FldComElt -> FldComElt`

<a id="function-dilog-fldreelt"></a>
##### `Dilog(s): FldReElt -> FldReElt`

For a given complex $s$, this returns the value of the principal branch of the *dilogarithm* ${\operatorname{Li}}_2(s)$, which can be defined by

$$
{\operatorname{Li}}_2(s)=-\int_0^s{\log(1-s)\over s}ds,
$$

and forms the analytic continuation of the power series

$$
\sum_{n=1}^\infty {s^n\over n^2},
$$

(which is convergent for $\vert s\vert\leq 1$). For large values of the argument a functional equation like

$$
{\operatorname{Li}}_2({-1\over s})+{\operatorname{Li}}_2(-s)=2{\operatorname{Li}}_2(-1)-{1\over2}\log^2(s)
$$

should be used.

<a id="function-polylog-rngintelt-rngserelt"></a>
##### `Polylog(m, f): RngIntElt, RngSerElt -> RngSerElt`

For an integer $m\geq 2$ and power series $f$ defined over a real or complex field, return the $m$-th polylogarithm of the series $f$. The valuation of $f$ must be positive for $m>1$.

<a id="function-polylog-rngintelt-fldcomelt"></a>
##### `Polylog(m, s): RngIntElt, FldComElt -> FldComElt`

For given integer $m\geq 2$ and complex $s$ this returns the value of the principal branch of the *polylogarithm* ${\operatorname{Li}}_m(s)$, defined for $m\geq 3$ by

$$
{\operatorname{Li}}_m(s)=\int_0^s{{\operatorname{Li}}_{m-1}(s)\over s}ds
$$

(and for $m=2$ as the dilogarithm ${\operatorname{Li}}_2$). Then ${\operatorname{Li}}_m$ is the analytic continuation of

$$
\sum_{n=1}^\infty {s^n\over n^m},
$$

(which is convergent for $\vert s\vert\leq 1$). For large values of the argument a functional equation like

$$
(-1)^m{\operatorname{Li}}_m({-1\over s})+{\operatorname{Li}}_m(-s)=-{1\over m!}\log^m(s)+2\sum_{r=1}^{\lfloor
   m/2\rfloor}{\log^{m-2r}(s)\over (m-2r)!}{\operatorname{Li}}_{2r}(-1)
$$

should be used. Pari is used here.

<a id="function-polylogd-rngintelt-fldcomelt"></a>
##### `PolylogD(m, s): RngIntElt, FldComElt -> FldComElt`

<a id="function-polylogdold-rngintelt-fldcomelt"></a>
##### `PolylogDold(m, s): RngIntElt, FldComElt -> FldComElt`

<a id="function-polylogp-rngintelt-fldcomelt"></a>
##### `PolylogP(m, s): RngIntElt, FldComElt -> FldComElt`

Given integer $m\geq 2$ and complex $s$, this returns the value of the principal branch of the modified versions $\tilde D_m, D_m$ and $P_m$ of the polylogarithm ${\operatorname{Li}}_m(s)$; all of these satisfy functional equations of the form $f_m(1/s)=(-1)^mf_m(s)$. For their definition and main properties, see Zagier [[Zag](https://docs.magma-maths.org/references.md#cite-zagier89)]. Pari is used here.

#### Trigonometric Functions

The trigonometric functions may be computed for real and complex arguments or for power series defined over a real or complex field. The basic power series expansions are

$$
\sin(z)=\sum_{n=0}^\infty{(-1)^{n+1}z^{2n+1}\over (2n+1)!}, \quad
\cos(z)=\sum_{n=0}^\infty{(-1)^nz^{2n}\over (2n)!}.
$$

Euler’s formulas relate these with the exponential functions via

$$
\sin(z)={e^{{\mathrm{i}}z}-e^{-{\mathrm{i}}z}\over 2{\mathrm{i}}}, \quad \cos(z)={e^{{\mathrm{i}}z}+e^{-{\mathrm{i}}z}\over 2}.
$$

<a id="function-sin-rngserelt"></a>
##### `Sin(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the power series $\sin(f)$.

<a id="function-sin-fldcomelt"></a>
##### `Sin(c): FldComElt -> FldComElt`

<a id="function-sin-fldreelt"></a>
##### `Sin(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value $\sin(c)$.

<a id="function-cos-rngserelt"></a>
##### `Cos(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the power series $\cos(f)$.

<a id="function-cos-fldcomelt"></a>
##### `Cos(c): FldComElt -> FldComElt`

<a id="function-cos-fldreelt"></a>
##### `Cos(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value $\cos(c)$.

<a id="function-sincos-rngserelt"></a>
##### `Sincos(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the two power series $\sin(f)$ and $\cos(f)$.

<a id="function-sincos-fldreelt"></a>
##### `Sincos(s): FldReElt -> FldReElt, FldReElt`

<a id="function-sincos-fldcomelt"></a>
##### `Sincos(s): FldComElt -> FldComElt, FldComElt`

Given a real or complex number $s$, return the two values $\sin(s)$ and $\cos(s)$.

<a id="function-tan-rngserelt"></a>
##### `Tan(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over the real or complex field, return the power series $\tan(f)$.

<a id="function-tan-fldcomelt"></a>
##### `Tan(c): FldComElt -> FldComElt`

<a id="function-tan-fldreelt"></a>
##### `Tan(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value $\tan(c)={\sin(c)\over\cos(c)}$. Note that $c$ should not be too close to one of the zeroes $(\pi/2 + n \cdot \pi)$ of $\cos(z)$.

<a id="function-cot-rngserelt"></a>
##### `Cot(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field having valuation zero, return the power series $\cot(f)$.

<a id="function-cot-fldcomelt"></a>
##### `Cot(c): FldComElt -> FldComElt`

<a id="function-cot-fldreelt"></a>
##### `Cot(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value $\cot(c)={\cos(c)/\sin(c)}$. Note that $c$ should not be too close to one of the zeroes $n \cdot \pi$ of $\sin(z)$.

<a id="function-sec-rngserelt"></a>
##### `Sec(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the power series $\sec(f)$.

<a id="function-sec-fldcomelt"></a>
##### `Sec(c): FldComElt -> FldComElt`

<a id="function-sec-fldreelt"></a>
##### `Sec(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value $\sec(c)=1/\cos(c)$. Note that $c$ should not be too close to one of the zeroes $(\pi/2 + n \cdot \pi)$ of $\cos(z)$.

<a id="function-cosec-rngserelt"></a>
##### `Cosec(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field having valuation zero, return the power series ${\operatorname{cosec}}(f)$.

<a id="function-cosec-fldcomelt"></a>
##### `Cosec(c): FldComElt -> FldComElt`

<a id="function-cosec-fldreelt"></a>
##### `Cosec(r): FldReElt -> FldReElt`

Given a real or complex number $c$, return the value ${\operatorname{cosec}}(c)=1/\sin(c)$. Note that $c$ should not be too close to one of the zeroes $n \cdot \pi$ of $\sin(z)$.

#### Inverse Trigonometric Functions

The inverse trigonometric functions are all available for arbitrary real or complex arguments. The principal values are chosen as indicated. We mention the power series expansions for the inverse of the sine and tangent functions (for $\vert z\vert\leq 1$):

$$
\begin{aligned}\arcsin(z)&=\sum_{n=0}^\infty\bigl(\prod_{k=1}^{2n} k^{(-1)^{k-1}}\bigr){z^{2n+1}\over 2n+1},\\
\arctan(z)&=\sum_{n=1}^\infty(-1)^n{z^{2n+1}\over 2n+1}.\end{aligned}
$$

The important relations with the logarithmic function include

$$
\begin{aligned}\arcsin(z)&={1\over{\mathrm{i}}}\log({\mathrm{i}}z+\sqrt{1-z^2}),\\
\arccos(z)&={1\over{\mathrm{i}}}\log(z+\sqrt{z^2-1}),\\
\arctan(z)&={1\over2{\mathrm{i}}}\log({1+{\mathrm{i}}z\over 1-{\mathrm{i}}z}).\end{aligned}
$$

<a id="function-arcsin-rngserelt"></a>
##### `Arcsin(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field. return the inverse sine of the power series $f$.

<a id="function-arcsin-fldreelt"></a>
##### `Arcsin(r): FldReElt -> FldReElt`

<a id="function-arcsin-fldcomelt"></a>
##### `Arcsin(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that $\sin(t)=s$. The principal value with real part in $[-\pi/2, \pi/2]$ is chosen. The return value is a complex number, unless $s$ is real and $-1\leq s\leq 1$, in which case a free real number is returned.

<a id="function-arccos-rngserelt"></a>
##### `Arccos(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field. return the inverse cosine of the power series $f$.

<a id="function-arccos-fldreelt"></a>
##### `Arccos(r): FldReElt -> FldReElt`

<a id="function-arccos-fldcomelt"></a>
##### `Arccos(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that $\cos(t)=s$. The principal value with real part in $[0, \pi]$ is chosen. The return value is a complex number, unless $s$ is real and $-1\leq s\leq 1$, in which case a free real number is returned.

<a id="function-arctan-rngserelt"></a>
##### `Arctan(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over the real or complex field, return the inverse tangent of the power series $f$.

<a id="function-arctan-fldreelt"></a>
##### `Arctan(r): FldReElt -> FldReElt`

<a id="function-arctan-fldcomelt"></a>
##### `Arctan(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that $\tan(t)=s$. The principal value with real part in $(-\pi/2, \pi/2)$ is chosen. The return value is a complex number, unless $s$ is real, in which case a free real number is returned.

<a id="function-arctan-fldreelt-fldreelt"></a>
##### `Arctan(x, y): FldReElt, FldReElt -> FldReElt`

<a id="function-arctan2-fldreelt-fldreelt"></a>
##### `Arctan2(x, y): FldReElt, FldReElt -> FldReElt`

Given the real numbers $x$ and $y$, return the value $v$ of $\arctan(y/x)$ determined by the choice of signs for $x$ and $y$. That is, the value $v$ is chosen in $(-\pi, \pi)$ in such a way that the signs of $y$ and $\sin(v)$ coincide, as well as the signs of $x$ and $\cos(v)$. An error occurs if $x$ and $y$ are both zero; if $y$ is zero and $x$ non-zero, the value returned is ${\operatorname{sign}}(x) \cdot \pi/2$.

The arguments are allowed to be in any real field (automatic coercion is used whenever necessary). Note that the ordering of $x$ and $y$ differs from the C math library function.

<a id="function-arccot-fldreelt"></a>
##### `Arccot(r): FldReElt -> FldReElt`

<a id="function-arccot-fldcomelt"></a>
##### `Arccot(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that $\cot(t)=s$. The principal value with real part in $(-\pi/2, \pi/2)$ is chosen. The return value is a complex number, unless $s$ is real, in which case a real number is returned.

<a id="function-arcsec-fldreelt"></a>
##### `Arcsec(r): FldReElt -> FldReElt`

<a id="function-arcsec-fldcomelt"></a>
##### `Arcsec(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that $\sec(t)=s$. The principal value with real part in $[0, \pi/2)\cup(\pi/2, \pi]$ is chosen. The return value is a complex number, unless $s$ is real, in which case a real number is returned.

<a id="function-arccosec-fldreelt"></a>
##### `Arccosec(r): FldReElt -> FldReElt`

<a id="function-arccosec-fldcomelt"></a>
##### `Arccosec(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return a value $t$ such that ${\operatorname{cosec}}(t)=s$. The principal value with real part in $[-\pi/2, 0)\cup(0, \pi/2]$ is chosen. The return value is a complex number, unless $s$ is real, in which case a real number is returned.

#### Hyperbolic Functions

The hyperbolic functions are available for real and complex arguments, as specified below. The hyperbolic functions are defined using

$$
\begin{aligned}\sinh(z)&={e^z-e^{-z}\over 2}, \\
\cosh(z)&={e^z+e^{-z}\over 2}.\end{aligned}
$$

<a id="function-sinh-rngserelt"></a>
##### `Sinh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the hyperbolic sine of the power series $f$.

<a id="function-sinh-fldcomelt"></a>
##### `Sinh(s): FldComElt -> FldComElt`

<a id="function-sinh-fldreelt"></a>
##### `Sinh(r): FldReElt -> FldReElt`

Given a real or complex number $s$, return $\sinh(s)$. The result will be a real or complex value, in accordance with the argument.

<a id="function-cosh-rngserelt"></a>
##### `Cosh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the hyperbolic cosine of the power series $f$.

<a id="function-cosh-fldreelt"></a>
##### `Cosh(r): FldReElt -> FldReElt`

<a id="function-cosh-fldcomelt"></a>
##### `Cosh(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $\cosh(s)$. The result will be a real or complex value, in accordance with the argument.

<a id="function-tanh-rngserelt"></a>
##### `Tanh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the hyperbolic tangent of the power series $f$.

<a id="function-tanh-fldreelt"></a>
##### `Tanh(r): FldReElt -> FldReElt`

<a id="function-tanh-fldcomelt"></a>
##### `Tanh(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $\tanh(s)={\sinh(s) \over\cosh(s)}$. The result will be a real or complex value, in accordance with the argument.

<a id="function-coth-fldreelt"></a>
##### `Coth(r): FldReElt -> FldReElt`

<a id="function-coth-fldcomelt"></a>
##### `Coth(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $\coth(s)={\cosh(s) \over\sinh(s)}$. The result will be a real or complex value, in accordance with the argument.

<a id="function-sech-fldreelt"></a>
##### `Sech(r): FldReElt -> FldReElt`

<a id="function-sech-fldcomelt"></a>
##### `Sech(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return ${\operatorname{sech}}(s)=1/\cosh(s)$. The result will be a real or complex value, in accordance with the argument.

<a id="function-cosech-fldreelt"></a>
##### `Cosech(r): FldReElt -> FldReElt`

<a id="function-cosech-fldcomelt"></a>
##### `Cosech(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return ${\operatorname{cosech}}(s)=1/\sinh(s)$. The result will be a real or complex value, in accordance with the argument.

#### Inverse Hyperbolic Functions

The inverse hyperbolic functions are available for real or complex arguments. The principal values are chosen as indicated.

<a id="function-argsinh-rngserelt"></a>
##### `Argsinh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the inverse hyperbolic sine of the power series $f$.

<a id="function-argsinh-fldreelt"></a>
##### `Argsinh(r): FldReElt -> FldReElt`

<a id="function-argsinh-fldcomelt"></a>
##### `Argsinh(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that $\sinh(t)=s$; the principal value with imaginary part in $[\-\pi/2, \pi/2]$ is chosen. The return value is a complex number, unless the argument is real, in which case a real number is returned.

<a id="function-argcosh-rngserelt"></a>
##### `Argcosh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the inverse hyperbolic cosine of the power series $f$.

<a id="function-argcosh-fldreelt"></a>
##### `Argcosh(r): FldReElt -> FldReElt`

<a id="function-argcosh-fldcomelt"></a>
##### `Argcosh(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that $\cosh(t))=s$; the principal value with imaginary part in $[0, \pi]$ is chosen. The return value is a complex number, unless the argument is real and $s\ge 1$, in which case a real number is returned.

<a id="function-argtanh-rngserelt"></a>
##### `Argtanh(f): RngSerElt -> RngSerElt`

Given a power series $f$ defined over a real or complex field, return the inverse hyperbolic tangent of the power series $f$.

<a id="function-argtanh-fldreelt"></a>
##### `Argtanh(s): FldReElt -> FldReElt`

<a id="function-argtanh-fldcomelt"></a>
##### `Argtanh(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that $\tanh(t)=s$; the principal value with imaginary part in $[\-\pi/2, \pi/2]$ is chosen. The return value is a complex number, unless the argument is real and $-1<s<1$, in which case a real number is returned.

<a id="function-argsech-fldreelt"></a>
##### `Argsech(s): FldReElt -> FldReElt`

<a id="function-argsech-fldcomelt"></a>
##### `Argsech(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that ${\operatorname{sech}}(t))=s$; the principal value with imaginary part in $[0, \pi]$ is chosen. The return value is a complex number, unless the argument is real and $\vert s\vert\ge 1$, in which case a real number is returned.

<a id="function-argcosech-fldreelt"></a>
##### `Argcosech(s): FldReElt -> FldReElt`

<a id="function-argcosech-fldcomelt"></a>
##### `Argcosech(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that ${\operatorname{cosech}}(t))=s$; the principal value with imaginary part in $[-\pi/2, \pi/2]$ is chosen. The return value is a complex number, unless the argument is real, in which case a real number is returned.

<a id="function-argcoth-fldreelt"></a>
##### `Argcoth(s): FldReElt -> FldReElt`

<a id="function-argcoth-fldcomelt"></a>
##### `Argcoth(r): FldComElt -> FldComElt`

Given a real or complex number $s$, return $t$ such that $\coth(t))=s$; the principal value with imaginary part in $[-\pi/2, \pi/2]$ is chosen. The return value is a complex number, unless the argument is real and $0<s\le 1$, in which case free real number is returned.

### Elliptic and Modular Functions

More information on elliptic functions can be found for example in Chandrasekharan [[Cha85](https://docs.magma-maths.org/references.md#cite-chand85)], and for modular functions and their use see Koblitz [[Kob84](https://docs.magma-maths.org/references.md#cite-koblitz84)].

#### Eisenstein Series

Let $f(z)$ be a modular function. Then $f(z)$ may be written as a Fourier series $f(z) = \sum_{n \in {\mathbb{Z}}} a_{n} q^{n},$ where $q = e^{2 \pi i z}$, which has at most finitely many nonzero coefficients $a_{n}$ with $n<0$. Such a Fourier expansion of a modular function is called its $q$*-expansion*. In this and the next section we present intrinsics for $q$-expansions of the Eisenstein series and the Weierstrass $\wp$-function.

Let $z$ be a point in the upper half-plane and let $L$ be a lattice in ${\mathbb{C}}$. The Eisenstein series are defined as the coefficients of the Laurent Series expansion of the Weierstrass $\wp$-function:

$$
\wp(z, L) = {{1}\over{z^2}} + \sum_{2\le k} G_k(L)(2k-1)z^{2k-2}
$$

where $G_k(L)$ are the Eisenstein series. The normalization $E_{2n}(z) = {{1}\over{2 \zeta(2n)}} G_{2n}(z)$ ensures that $E_{2n}(z)$ has a *rational* $q$-expansion.

<a id="function-eisenstein-rngintelt-rngserelt"></a>
##### `Eisenstein(k, z): RngIntElt, RngSerElt -> RngSerElt`

```magma
Precision: RngIntElt                    Default: 
```

Given a positive even integer $k = 2n$ and a complex power series $z$ with positive valuation, return the $q$-expansion of the normalized Eisenstein series $E_{2n}(z)$. If $z$ has finite precision this is the default for `Precision` otherwise the default precision of the parent of $z$ is used.

<a id="function-eisenstein-rngintelt-fldcomelt"></a>
##### `Eisenstein(k, t): RngIntElt, FldComElt -> FldComElt`

Given a positive even integer $k = 2n$ and a point $t$ in the upper half plane, return the value of $E_{2n}(z)$ at $t$.

<a id="function-eisenstein-rngintelt-seqenum"></a>
##### `Eisenstein(k, L): RngIntElt, SeqEnum -> FldComElt`

Given a positive even integer $k = 2n$ and a lattice $L = [a, b]$ in the complex plane, return the value of the Eisenstein series $E_{2n}(z)$ relative to the lattice $L$.

<a id="function-eisenstein-rngintelt-quadbinelt"></a>
##### `Eisenstein(k, F): RngIntElt, QuadBinElt -> RngSerElt`

Given a positive even integer $k = 2n$ and a binary quadratic form $F = ax^2+bxy+cy^2$, return the value of the Eisenstein series $E_{2n}(z)$ at the point $\tau = \left(-b+\sqrt{b^2-4ac} \right)/(2a)$ where $z$ is $e^{2\pi*{\mathrm{i}}*\tau}$.

<a id="example-ex-db3e10"></a>
##### `Example: q-Expansion of an Eisenstein Series (ex-db3e10)`

We compute the $q$-expansion for the normalized Eisenstein series $E_{4}(z)$.

```magma
> C<i> := ComplexField();
> R<z> := PowerSeriesRing(C);
> E4<q> := Eisenstein(4, z);
> E4;
1.00000000000000000000000000000 +
    240.000000000000000000000000000*q +
    2160.00000000000000000000000000*q^2 +
    6720.00000000000000000000000000*q^3 +
    17520.0000000000000000000000000*q^4 +
    30240.0000000000000000000000000*q^5 +
    60480.0000000000000000000000000*q^6 +
    82560.0000000000000000000000000*q^7 +
    140400.000000000000000000000000*q^8 +
    181680.000000000000000000000000*q^9 +
    272160.000000000000000000000000*q^10 +
    319680.000000000000000000000000*q^11 +
    490560.000000000000000000000000*q^12 +
    527520.000000000000000000000000*q^13 +
    743040.000000000000000000000000*q^14 +
    846720.000000000000000000000000*q^15 +
    1123440.00000000000000000000000*q^16 +
    1179360.00000000000000000000000*q^17 +
    1635120.00000000000000000000000*q^18 +
    1646400.00000000000000000000000*q^19 + O(q^20)
```

We now evaluate this series at the point $z1 = 2.5 + i$. Since the expansion is in terms of $q$ rather than $z$ we first must calculate the point $q1$ that corresponds to $z1$.

```magma
> q1 := Exp(2*Pi(RealField())*i*(2.5 +i));
> Evaluate(E4, q1);
0.559302852856190773766762411942 +
3.67329046709782088758389413820E-31*i
```

If we are interested only in the value of $E_{4}$ at a single point, then we can compute it directly:

```magma
> Eisenstein(4, 2.5 + i);
0.559302852856190773766762411942 +
3.67329046709782088758389413820E-31*i
```

#### Weierstrass Series

<a id="function-weierstrassseries-rngserelt-rngserelt"></a>
##### `WeierstrassSeries(z, q): RngSerElt, RngSerElt -> RngSerElt`

```magma
Precision: RngIntElt                    Default: 
```

Return a normalized $q$-expansion of the Weierstrass $\wp$-function:

$$
\wp(z, L) = {{1}\over{z^2}} + \sum_{2\le k} G_k(L)(2k-1)z^{2k-2}
$$

where $G_k(L)$ are the Eisenstein series and

$$
\hbox{\tt WeierstrassSeries}(z,q) = (2 \pi i)^{-2}\wp(q, z/(2 \pi i))
$$

Each term is an Eisenstein series, calculated to precision `Precision`, which is by default the precision of $q$.

<a id="function-weierstrassseries-rngserelt-fldcomelt"></a>
##### `WeierstrassSeries(z, t): RngSerElt, FldComElt -> RngSerElt`

Given a complex power series $z$ with positive valuation and a point $t =\tau$ in the upper-half complex plane, return the normalized $q$-expansion of the Weierstrass $\wp$-function. This is equivalent to evaluating the $q$-series expansion at $q = e^{2\pi i\tau}$.

<a id="function-weierstrassseries-rngserelt-seqenum"></a>
##### `WeierstrassSeries(z, L): RngSerElt, SeqEnum -> RngSerElt`

Given a complex power series $z$ with positive valuation and a lattice $L = [a, b]$ in the complex plane, returns the normalized $q$-expansion of the Weierstrass $\wp$-function relative to the lattice $L$.

<a id="function-weierstrassseries-rngserelt-quadbinelt"></a>
##### `WeierstrassSeries(z, F): RngSerElt, QuadBinElt -> RngSerElt`

Given a complex power series $z$ with positive valuation and a binary quadratic form $F = ax^2+bxy+cy^2$, this function returns the $q$-expansion of the Weierstrass $\wp$-function at $\tau = \left(-b+\sqrt{b^2-4ac} \right)/(2a)$.

#### The Jacobi $\theta$ and Dedekind $\eta$-functions

The first Jacobi $\theta$-function, $\theta(q, z)$, is defined by

$$
\theta(q, z)={1\over{\mathrm{i}}}\sum_{n=-\infty}^\infty(-1)^nq^{(n+{1\over2})^2}e^{(2n+1){\mathrm{i}}z}=2\sum_{n=0}^\infty(-1)^nq^{(n+{1\over2})^2}\sin(2n+1)z.
$$

Defined this way, $\theta$ satisfies $\theta(q, -z)=-\theta(q, z)$, it is periodic with period $2\pi$ in the second variable: $\theta(q, z+2\pi)= \theta(q, z)$, and its zeroes are of the form $m_1\pi+m_2{\log x\over{\mathrm{i}}}$ for any integers $m_1, m_2$.

<a id="function-jacobitheta-fldreelt-rngserelt-fldre"></a>
##### `JacobiTheta(q, z): FldReElt, RngSerElt[FldRe] -> RngSerElt`

<a id="function-jacobitheta-fldcomelt-rngserelt-fldcom"></a>
##### `JacobiTheta(q, z): FldComElt, RngSerElt[FldCom] -> RngSerElt`

For a real or complex number $q$ satisfying $\vert q\vert<1$, return the first of Jacobi’s theta functions $\theta(q,z)$ as a power series expansion in $z$, a series over the complex numbers. Pari is used here.

<a id="function-jacobitheta-fldreelt-fldreelt"></a>
##### `JacobiTheta(q, z): FldReElt, FldReElt -> FldReElt`

<a id="function-jacobitheta-fldcomelt-fldcomelt"></a>
##### `JacobiTheta(q, z): FldComElt, FldComElt -> FldComElt`

For real or complex numbers $q, z$ satisfying $\vert q\vert<1$, return the value of $\theta(q, z)$, the first of Jacobi’s theta functions. Pari is used here.

<a id="function-jacobithetanullk-fldreelt-rngintelt"></a>
##### `JacobiThetaNullK(q, k): FldReElt, RngIntElt -> FldReElt`

For integer $k\geq 0$, return the $k$-th derivative $\theta^{(k)}(q, 0)$ of $\theta(q, z)$ at $z=0$. Pari is used here.

<a id="function-dedekindeta-rngserelt"></a>
##### `DedekindEta(z): RngSerElt -> RngSerElt`

Given a complex power series $z$ with positive valuation, return the $q$-expansion of Dedekind’s $\eta$-function. Note that the unnormalized series is returned, that is, the factor $q^{1/24}$ is *not* removed. See [[Lan87](https://docs.magma-maths.org/references.md#cite-lang87)].

<a id="function-dedekindeta-fldcomelt"></a>
##### `DedekindEta(s): FldComElt -> FldComElt`

For complex argument $s$ with positive imaginary part, this returns the actual value of Dedekind’s $\eta$-function which is defined by $\eta(s)=e^{2\pi{\mathrm{i}}s\over 24} \left(1 + \sum_{n=1}^\infty(-1)^n (q^{n(3n-1)/2} + q^{n(3n+1)/2}) \right)$ where $q = e^{2\pi{\mathrm{i}}s}$.

#### The $j$-Invariant and the Discriminant

The discriminant of the elliptic curve corresponding to the complex lattice $L_{\tau}$, spanned by $1$ and $\tau$ is given by

$$
\Delta(\tau) = q \left(1 + \sum_{n=1}^\infty(-1)^n (q^{n(3n-1)/2} + q^{n(3n+1)/2}) \right)
$$

where $q = e^{2\pi{\mathrm{i}}\tau}$.

<a id="function-jinvariant-rngserelt"></a>
##### `jInvariant(q): RngSerElt -> RngSerElt`

Given a power series $q$ over a real or complex field with positive valuation, return the $q$-expansion of the elliptic $j$-invariant. The expansion begins with

$$
j(q) = q^{-1} + 744 + 196884 q + \cdots.
$$

Note that:

$$
j(q) = {{{E_4(q)}^3}\over{\Delta(q)}}
$$

where $E_4(q)$ = `Eisenstein(4, q)` and $\Delta(q)$ = `Delta(q)`.

<a id="function-jinvariant-fldcomelt"></a>
##### `jInvariant(s): FldComElt -> FldComElt`

For complex argument $s$ with positive imaginary part, this returns the value of the elliptic $j$-invariant at $s$. This is a modular function of weight $0$ whose Fourier expansion starts with

$$
j(s)=e^{-2\pi{\mathrm{i}}s}+744+196884e^{2\pi{\mathrm{i}}s}+\cdots.
$$

<a id="function-jinvariant-seqenum"></a>
##### `jInvariant(L): SeqEnum -> FldComElt`

Given a lattice $L = [a, b]$ in the complex plane, this function returns the value of the elliptic $j$-invariant of $L$. This is the $j$-invariant of $\tau$ where $\tau = a/b$ or $\tau = b / a$, whichever is in the upper half complex plane.

<a id="function-jinvariant-quadbinelt"></a>
##### `jInvariant(F): QuadBinElt -> FldComElt`

For a binary quadratic form $F = ax^2+bxy+cy^2$ with negative discriminant, this returns the elliptic $j$-invariant of $F$. This is the $j$-invariant of $\tau$ where $\tau = \left(-b + \sqrt{b^2-4ac}\right) / (2a)$.

<a id="function-delta-rngserelt"></a>
##### `Delta(z): RngSerElt -> RngSerElt`

Given a complex power series $z$, this function returns a $q$-series expansion of the discriminant $\Delta(z)$.

<a id="function-delta-fldcomelt"></a>
##### `Delta(t): FldComElt -> FldComElt`

Given a point $t$ in the upper half plane, return the $q$-series expansion of the discriminant $\Delta(q)$ evaluated at $q = e^{2\pi{\mathrm{i}}t}$.

<a id="function-delta-seqenum"></a>
##### `Delta(L): SeqEnum -> FldComElt`

Given a pair $L$ = [$a$,$b$] of complex numbers generating a lattice in ${\mathbb{C}}$, return the $q$-series expansion of the discriminant $\Delta(q)$ evaluated at $q = e^{2\pi{\mathrm{i}}\tau}$ where $\tau = a/b$ or $\tau = b / a$, whichever is in the upper half complex plane.

<a id="weber-s-functions"></a>
#### Weber’s Functions

<a id="function-weberf-fldcomelt"></a>
##### `WeberF(s): FldComElt -> FldComElt`

For complex argument $s$ in the upper half-plane, this returns the value of Weber’s function $f$, defined in such a way that

$$
j(s)={(f(s)^{24}-16)^3\over f(s)^{24}}.
$$

<a id="function-weberf2-rngserelt"></a>
##### `WeberF2(g): RngSerElt -> RngSerElt`

For a complex power series $g$ having positive valuation, this function returns the $q$-expansion of Weber’s $f_2$ function

$$
f_2(x)={\eta(2x)\sqrt{2}\over\eta(x)}
$$

defined in such a way that

$$
j(s)={(f_2(s)^{24}+16)^3\over f_2(s)^{24}}.
$$

<a id="function-weberf1-fldcomelt"></a>
##### `WeberF1(s): FldComElt -> FldComElt`

<a id="function-weberf2-fldcomelt"></a>
##### `WeberF2(s): FldComElt -> FldComElt`

For complex number $s$ lying in the upper half-plane, these return the value of Weber’s functions $f_1$ and $f_2$, defined in such a way that

$$
j(s)={(f_{1/2}(s)^{24}+16)^3\over f_{1/2}(s)^{24}}.
$$

In fact, $f_2$ is as defined above and

$$
f_1(x)=f_2(-1/x)={\eta(x/2)/\eta(x)}.
$$

<a id="example-ex-3718fd"></a>
##### `Example: q-Expansion of a Weber Function (ex-3718fd)`

We compute the $q$-expansion for the Weber function $f_{2}(z)$.

```magma
> C<i> := ComplexField();
> R<x> := PowerSeriesRing(C);
> f2<q> := WeberF2(x);
> f2;
1.41421356237309504880168872421 +
    (1.41421356237309504880168872421 +
    0.370240244846530520584656749172*i)*q +
    (1.36574922765338060759226121771 +
    0.370240244846530520584656749172*i)*q^2 +
    (2.77996279002647565639394994192 +
    0.366010933793292419482272977081*i)*q^3 +
    (2.78023959778761313408864734217 +
    0.736251178639822940066929726253*i)*q^4 +
    (4.14598882544099374168090855987 +
    0.736265672260303709036837819528*i)*q^5 +
    (5.56020175541059398072755542234 +
    1.10227660605359612851911079661*i)*q^6 +
    ...
```

### Theta Functions

One of the main tools for working with analytic Jacobians is the theta function. For instance it is used by [`FromAnalyticJacobian`](https://docs.magma-maths.org/ArithmeticGeometry/HyperellipticCurves/analytic.md#function-fromanalyticjacobianlabel) and [`RosenhainInvariants`](https://docs.magma-maths.org/ArithmeticGeometry/HyperellipticCurves/analytic.md#function-rosenhaininvariantslabel). For $c \in {\mathbb{R}}^{2g}$ let $c'$ be the first $g$ entries and $c''$ the second $g$ entries of $c$. For such a $c$, $z \in {\mathbb{C}}^g$ and $\tau$ an element of Siegel upper half-space the classical multi-variable theta function is defined by

$$
\theta[c](z,\tau) = \sum_{m \in {\mathbb{Z}}^g} \exp (\pi i
{}^t(m+c')\tau(m+c') + 2\pi i {}^t(m+c')(z+c'')).
$$

The vector $c$ is called the characteristic of the theta function.

<a id="function-theta-mtrx-mtrx-mtrx"></a>
#### `Theta(char, z, tau): Mtrx, Mtrx, Mtrx -> FldComElt`

This computes the multidimensional theta function with characteristic `char` (a $2g \times 1$ matrix) at $z$ (a $g \times 1$ matrix) and $\tau$ (a symmetric $g \times g$ matrix with positive definite imaginary part).

<a id="function-theta-mtrx-mtrx-anhcjac"></a>
#### `Theta(char, z, A): Mtrx, Mtrx, AnHcJac -> FldComElt`

This computes the multidimensional theta function with characteristic `char` (a $2g \times 1$ matrix) at $z$ (a $g \times 1$ matrix) and $\tau$, the small period matrix of the analytic Jacobian $A$. This function caches the values of theta null values ($z = 0$) at half-integer characteristics.

### Gamma, Bessel, and Associated Functions

As a general reference to the functions described in this section (and much more), we refer the reader to Whittaker and Watson [[WW15](https://docs.magma-maths.org/references.md#cite-whit15)].

<a id="function-gamma-rngserelt"></a>
#### `Gamma(f): RngSerElt -> RngSerElt`

Return the Gamma function $\Gamma(f)$ of the series $f$. The series $f$ must be defined over the free real or complex field, the valuation of $f$ must be 0 and the constant term of $f$ must be 1.

<a id="function-gamma-fldreelt"></a>
#### `Gamma(r): FldReElt -> FldReElt`

<a id="function-gamma-fldcomelt"></a>
#### `Gamma(r): FldComElt -> FldComElt`

Given a real or complex number $s$ (not equal to $0, -1, -2, \ldots$), calculate the value $\Gamma(s)$ of the *gamma function* at $s$. For $s$ with positive real part this is the value of

$$
\Gamma(s)=\int_0^{\infty}u^{s-1}e^{-u}du.
$$

For other $s$ (not a non-positive integer) the function is defined by analytic continuation, and it satisfies the product formula

$$
{1\over s\Gamma(s)}=e^{\gamma s}\prod_{n=1}^\infty (1+{s\over n})e^{-s/n}.
$$

The function $\Gamma$ also satisfies

$$
\Gamma(s)\Gamma(1-s)={\pi\over{\sin(\pi s)}},
$$

and

$$
\Gamma(s+1)=s\Gamma(s).
$$

<a id="function-gamma-fldreelt-fldreelt"></a>
#### `Gamma(s, t): FldReElt, FldReElt -> FldReElt`

```magma
Complementary: BoolElt                     Default: false
Gamma        : FldReElt                    Default: 
```

For real numbers $s, t$ this returns the value of the incomplete gamma function

$$
\gamma(s, t)=\int_0^t u^{s-1}e^{-u}du.
$$

The optional argument `Complementary` can be used to find the complement

$$
\int_t^\infty  u^{s-1}e^{-u}du
$$

instead. There is a second optional argument that may be used in the computation of the incomplete gamma value; the free real value of `Gamma` should be the value of $\Gamma(s)$, in which case $\gamma(s, t)$ may be computed as the difference between the given value for $\Gamma(s)$ and that of the complementary $\gamma$ at $s, t$. Pari is used here.

<a id="function-gammad-fldreelt"></a>
#### `GammaD(s): FldReElt -> FldReElt`

For free real $s$ (such that $s+{1\over2}$ is not a non-positive integer) this returns the value of $\Gamma(s+{1\over2})$. For integer values of $s$ this is faster than `Gamma(s+(1/2))`, because Legendre’s doubling formula

$$
\Gamma(s+{1\over2})=2^{1-2s}\sqrt{\pi}{\Gamma(2s)\over\Gamma(s)}
$$

is used. Pari is used here.

<a id="function-loggamma-rngserelt"></a>
#### `LogGamma(f): RngSerElt -> RngSerElt`

Return the Log-Gamma function ${\rm Log}(\Gamma(f))$ of the series $f$. $f$ must be defined over a real or complex field, the valuation of $f$ must be 0 and the constant term of $f$ must be 1.

<a id="function-loggamma-fldreelt"></a>
#### `LogGamma(r): FldReElt -> FldReElt`

<a id="function-loggamma-fldcomelt"></a>
#### `LogGamma(r): FldComElt -> FldComElt`

For real or complex $s$ (not a non-positive integer) return the value of the principal branch of the logarithm of the gamma function of $s$.

<a id="function-logderivative-fldreelt"></a>
#### `LogDerivative(s): FldReElt -> FldReElt`

<a id="function-logderivative-fldcomelt"></a>
#### `LogDerivative(s): FldComElt -> FldComElt`

<a id="function-psi-fldreelt"></a>
#### `Psi(s): FldReElt -> FldReElt`

<a id="function-psi-fldcomelt"></a>
#### `Psi(s): FldComElt -> FldComElt`

For real or complex $s$ (not a non-positive integer) return the principal value of the logarithmic derivative

$$
\Psi(s)={d \log\Gamma(s)\over ds}={\Gamma'(s)\over\Gamma(s)},
$$

of the gamma function, which allows the expansion

$$
\Psi(s)=-\gamma-{1\over s}+s\sum_{n=1}^\infty{1\over n(s+n)};
$$

here $\gamma$ is Euler’s gamma. Pari is used here.

<a id="function-besselfunction-rngintelt-fldreelt"></a>
#### `BesselFunction(n, r): RngIntElt, FldReElt -> FldReElt`

Given a small integer $n$ and a real number $r$, calculate the value of the *Bessel function* $y$ = $J_n(r)$, of the first kind of order $n$. Results for negative arguments are defined by: $J_{-n}(r) = J_n(-r) = (-1)^n J_n(r)$. The Bessel function of the first kind of order $n$ is defined by

$$
J_n(x)={1\over2\pi{\mathrm{i}}}\left({z\over2}\right)^n\int_{-\infty}^{0^+}
   u^{-n-1}e^{u-{z^2\over4t}}du,
$$

and satisfies

$$
J_n(x)=\sum_{k=0}^\infty {(-1)^kz^{n+2k}\over 2^{n+2k}k!\Gamma(n+k+1)}.
$$

<a id="function-besselfunctionsecondkind-rngintelt-fldreelt"></a>
#### `BesselFunctionSecondKind(n, r): RngIntElt, FldReElt -> FldReElt`

Given a small integer $n$ and a real number $r$, calculate the value of the *Bessel function* $y$ = $Y_n(r)$, of the second kind of order $n$. Results for negative arguments are defined by: $Y_{-n}(r) = -(-1)^n Y_n(r)$, $Y_n(-r)$ is not a real number. The Bessel function of the second kind of order $n$ satisfies the Bessel differential equation.

<a id="function-jbessel-rngintelt-fldreelt"></a>
#### `JBessel(n, s): RngIntElt, FldReElt -> FldReElt`

<a id="function-jbessel-fldreelt-fldreelt"></a>
#### `JBessel(n, s): FldReElt, FldReElt -> FldReElt`

Given a small integer $n$ and a real number $s$, calculate the value of the *Bessel function* of the first kind of half integral index $n+{1\over2}$, $J_{n+{1\over2}}$, defined as above. Pari is used here.

<a id="function-kbessel-fldreelt-fldreelt"></a>
#### `KBessel(n, s): FldReElt, FldReElt -> FldReElt`

<a id="function-kbessel-fldcomelt-fldreelt"></a>
#### `KBessel(n, s): FldComElt, FldReElt -> FldComElt`

<a id="function-kbessel2-fldreelt-fldreelt"></a>
#### `KBessel2(n, s): FldReElt, FldReElt -> FldReElt`

<a id="function-kbessel2-fldcomelt-fldreelt"></a>
#### `KBessel2(n, s): FldComElt, FldReElt -> FldComElt`

Given a complex $n$ and a positive real $s$, compute the value of the *modified Bessel function of the second kind* $K_n(s)$, which may be defined by

$$
K_n(s)={\pi\over 2}\left({\mathrm{i}}^nJ_{-n}({\mathrm{i}}s)-{\mathrm{i}}^{-n}J_n(s)\right)\cot(n\pi).
$$

The function `KBessel2` is an alternative (often faster) implementation of this function. Pari is used here.

### The Hypergeometric Function

For more information on the Hypergeometric Series, see Husemöller [[Hus87](https://docs.magma-maths.org/references.md#cite-husem87)], page 176.

<a id="function-hypergeometricseries-rngelt-rngelt-rngelt-rngelt"></a>
#### `HypergeometricSeries(a, b, c, z): RngElt, RngElt, RngElt, RngElt -> RngElt`

Return the hypergeometric series $F(a,b,c;z)$ defined by

$$
F(a,b,c;z) = \sum_{0\le n} {{(a)_n(b)_n}\over{n!(c)_n} z^n}
$$

where $(a)_n = a (a+1) \cdots (a+n-1)$.

<a id="function-hypergeometricu-fldreelt-fldreelt-fldreelt"></a>
#### `HypergeometricU(a, b, s): FldReElt, FldReElt, FldReElt -> FldReElt`

For positive real $s$ and complex arguments $a$ and $b$ this function returns the value of the confluent hypergeometric function $U(a, b, s)$. This can be defined by

$$
U(a, b, s)={1\over\Gamma(a)}\int_{u=0}^\infty e^{-su}u^{a-1}(1+u)^{b-a-1)}du.
$$

Pari is used here.

### Other Special Functions

<a id="function-arithmeticgeometricmean-rngserelt-rngserelt"></a>
#### `ArithmeticGeometricMean(x, y): RngSerElt, RngSerElt -> RngSerElt`

<a id="function-agm-rngserelt-rngserelt"></a>
#### `AGM(f, g): RngSerElt, RngSerElt -> RngSerElt`

Return the hyperbolic arithmetic-geometric mean of the series $f$ and $g$ defined over a field. The valuations of $f$ and $g$ must be equal.

<a id="function-arithmeticgeometricmean-fldreelt-fldreelt"></a>
#### `ArithmeticGeometricMean(x, y): FldReElt, FldReElt -> FldReElt`

<a id="function-agm-fldreelt-fldreelt"></a>
#### `AGM(x, y): FldReElt, FldReElt -> FldReElt`

Returns the arithmetic-geometric mean of the real or complex numbers $x$ and $y$, defined as the limit of either of the sequences $x_i, y_i$ where $x_0 = x$, $y_0 = y$, and $x_{i+1} = (x_i + y_i)/2, y_{i+1} = \sqrt{x_i y_i}$. The function calculates both sequences, and when the numbers are within the desired precision of each other, it returns one of them.

<a id="function-bernoullinumber-rngintelt"></a>
#### `BernoulliNumber(n): RngIntElt -> FldRatElt`

For a non-negative integer $n$, return the value of the $n$-th Bernoulli number $B_n$, defined by

$$
{t\over e^t-1}=\sum_{n=0}^\infty B_n{t^n\over n!}.
$$

<a id="function-bernoulliapproximation-rngintelt"></a>
#### `BernoulliApproximation(n): RngIntElt -> FldReElt`

For a non-negative integer $n$, return an approximation in the field of real numbers to the value of the $n$-th Bernoulli number $B_n$, defined by

$$
{t\over e^t-1}=\sum_{n=0}^\infty B_n{t^n\over n!}.
$$

<a id="function-dawsonintegral-fldreelt"></a>
#### `DawsonIntegral(r): FldReElt -> FldReElt`

Given a real number $r$, compute the value of *Dawson’s integral*,

$$
e^{-x^2}\cdot\int_0^xe^{u^2} du,
$$

at $x = r$.

<a id="function-errorfunction-fldreelt"></a>
#### `ErrorFunction(r): FldReElt -> FldReElt`

<a id="function-erf-fldreelt"></a>
#### `Erf(r): FldReElt -> FldReElt`

Given a real number $r$, calculate the value of the *error function* ${\operatorname{erf}}$. This is the value of

$$
\sqrt{4\over \pi}\cdot \int_0^xe^{-u^2} du,
$$

at $x = r$ for $r>0$, and for $r<0$ it is defined by ${\operatorname{erf}}(x)=-{\operatorname{erf}}(-x)$, while ${\operatorname{erf}}(0)=0$.

<a id="function-complementaryerrorfunction-fldreelt"></a>
#### `ComplementaryErrorFunction(r): FldReElt -> FldReElt`

<a id="function-erfc-fldreelt"></a>
#### `Erfc(r): FldReElt -> FldReElt`

Given a real number $r$, calculate the value of the *complementary error function*. This is the value of $y = {\rm erfc}(x) = 1 - {\operatorname{erf}}(x)$ for the error function ${\operatorname{erf}}$ as defined above.

<a id="function-exponentialintegral-fldreelt"></a>
#### `ExponentialIntegral(r): FldReElt -> FldReElt`

Given a real number $r$, calculate the value of the *exponential integral*, that is, the principal value of

$$
\int_{-\infty}^x{e^u\over u}du
$$

at $x = r$.

<a id="function-exponentialintegrale1-fldreelt"></a>
#### `ExponentialIntegralE1(r): FldReElt -> FldReElt`

Given a real number $r$, calculate the value of the *exponential integral E1*, that is, the principal value of

$$
\int_x^{\infty}{e^{-u}\over u}du
$$

at $x = r$.

<a id="function-logintegral-fldreelt"></a>
#### `LogIntegral(r): FldReElt -> FldReElt`

Given a non-negative real number $r$ that is not equal to 1, evaluate the *logarithmic integral* $y = {\operatorname{li}}(x)$ at $x = r$. This integral is defined to be the principal value of $\int_0^x{1\over \log(u)}du.$

<a id="function-zetafunction-fldreelt"></a>
#### `ZetaFunction(s): FldReElt -> FldReElt`

<a id="function-zetafunction-fldre-rngintelt"></a>
#### `ZetaFunction(R, n): FldRe, RngIntElt -> FldReElt`

These functions calculate values of the Riemann $\zeta$-function, which is the analytic continuation of

$$
\zeta(z)=\sum_{i=1}^\infty{1\over i^z}
$$

(convergent for $\operatorname{Re}(z)> 1$). The version with one argument takes a real or complex number $r\neq 1$ and returns a real or complex number. The version with two arguments is much more restricted; it takes a real field $R$ and an integer $n \neq 1$, and returns $\zeta(n)$ in $R$.

MPFR uses the algorithm of Jean-Luc Rémy and Sapphorain Pétermann [[PR06](https://docs.magma-maths.org/references.md#cite-pere06)].

### Summation of Infinite Series

There are three functions for evaluating infinite sums of real numbers. The sum should be specified as a map $m$ from the integers to the real field, such that $m(n)$ is the $n^{\rm th}$ term of the sum. The summation begins at term $i$. The precision of the result will be the default precision of the real field.

<a id="function-infinitesum-map-rngintelt"></a>
#### `InfiniteSum(m, i): Map, RngIntElt -> FldReElt`

An approximation to the infinite sum $m(i)+m(i+1)+m(i+2)+\cdots$. This function also works for maps to the complex field.

<a id="function-positivesum-map-rngintelt"></a>
#### `PositiveSum(m, i): Map, RngIntElt -> FldReElt`

An approximation to the infinite sum $m(i)+m(i+1)+m(i+2)+\cdots$. Designed for series in which every term is positive, it uses van Wijngaarden’s trick for converting the series into an alternating one. Due to the stopping criterion, terms equal to 0 will create problems and should be removed.

<a id="function-alternatingsum-map-rngintelt"></a>
#### `AlternatingSum(m, i): Map, RngIntElt -> FldReElt`

```magma
Al: MonStgElt                    Default: "Villegas"
```

An approximation to the infinite sum $m(i)+m(i+1)+m(i+2)+\cdots$. Designed for series in which the terms alternate in sign. The optional argument `Al` can be used to specify the algorithm used. The possible values are `"Villegas"` (the default), and `"EulerVanWijngaarden"`. Due to the stopping criterion, terms equal to 0 will create problems and should be removed.

### Numerical Integration

Two groups of intrinsics for numerical integration are provided. The first group are designed for the numerical integration of complex-valued functions along the interval $[-1, 1]$. They have been researched and implemented by Christian Neurohr. The second group consist of three basic Romberg-like numerical integration methods that are based on those in Pari.

#### Polynomial Interpolation

Given $n + 1$ points $(x_i, y_i)$, there is a unique polynomial $p(x)$ of degree $n$ which passes through these points. Given some $t$, *polynomial interpolation* computes the value $u = p(t)$.

<a id="function-interpolation-fldreelt-fldreelt-fldreelt"></a>
##### `Interpolation(P, V, t): [FldReElt], [FldReElt], FldReElt -> FldReElt, FldReElt`

Using Neville’s algorithm, interpolate the value of $t$ with respect to a polynomial $p$ such that $p(P[i]) = V[i]$. An estimate of the error is also returned.

#### Discrete Fourier Transform

An intrinsic is provided to compute the discrete Fourier transform of a sequence of complex numbers.

<a id="function-discretefouriertransform-seqenum-fldcomelt"></a>
##### `DiscreteFourierTransform(E): SeqEnum[FldComElt] -> SeqEnum[FldComElt]`

Given a sequence $E$ of complex numbers, return their discrete Fourier transform as a sequence of complex numbers.

#### Integration of Complex Functions

In this section several integration schemes that are useful for numerical integration along the interval $[-1, 1]$ are described. They have been designed and implemented by Christian Neurohr. In particular, the routines are suitable for numerically approximating integrals of complex-valued functions that are analytic over the interval [-1,1] or have integrable singularities at the end points. These should not be regarded as general purpose numerical integration tools. The examples in this section merely indicate how to use these integration methods. Error bounds for them and more details on how to use them can be found in [[Neu18](https://docs.magma-maths.org/references.md#cite-neurohr-phd), Chapter 3] as well as many other references on numerical analysis.

##### Gaussian Quadratures

Gaussian quadratures are well-known quadrature rules that integrate exactly polynomials of degree $2N-1$ using $N$ integration points. In particular, they are highly efficient for integrands that are well-behaved around the integration path. The following functions compute the *Gauss-Jacobi integration scheme* on the interval $[-1,1]$, i.e. a sequence of abscissas $A$ and a sequence of weights $W$ such that can be used to approximate the definite integral

$$
\int_{-1}^1 (1-x)^a(1+x)^b f(x) dx \approx \sum_{k=1}^N W[k] \cdot A[k]
$$

for a well-behaved, complex-valued function $f : [-1,1] \rightarrow {\mathbb{C}}$, $a,b > -1$ and $N$ sufficiently large. The *Gauss-Legendre integration scheme* occurs as the special case $a=b=0$. For more details see also [[Neu18](https://docs.magma-maths.org/references.md#cite-neurohr-phd), Section 3.2].

<a id="function-gausslegendreintegrationpoints-rngintelt-rngintelt"></a>
###### `GaussLegendreIntegrationPoints(N, D): RngIntElt, RngIntElt -> SeqEnum[FldReElt], SeqEnum[FldReElt]`

Construct the Gauss–Legendre integration scheme on $N$ points and precision $D$.

<a id="function-gaussjacobiintegrationpoints-rngintelt-rngintelt-rngresubelt-rngresubelt"></a>
###### `GaussJacobiIntegrationPoints(N, D, a, b): RngIntElt, RngIntElt, RngReSubElt, RngReSubElt -> SeqEnum, SeqEnum`

Construct the Gauss–Jacobi integration scheme on $N$ points and precision $D$.

<a id="clenshaw-curtis-quadrature"></a>
##### Clenshaw–Curtis Quadrature

The Clenshaw–Curtis quadrature on $N+1$ is an interpolation integration scheme that integrates polynomials exactly up to degree $N$. The abscissas are the $N-1$ extrema of the $N$-th Chebyshev polynomial plus the boundary points $\pm 1$ and the weights are obtained by interpolation. It is best suited for integrands that are analytic around $[-1,1]$ and can be computed quite quickly using a discrete Fourier transform. As before, a sequence of abscissas $A$ and a sequence of weights $W$ on interval $[-1,1]$ can be used to approximate

$$
\int_{-1}^1 f(x) dx \approx \sum_{k=1}^N W[k] \cdot A[k]
$$

for a well-behaved, complex-valued function $f : [-1,1] \rightarrow {\mathbb{C}}$ and $N$ chosen large enough. For more details on Clenshaw–Curtis integration and this particular implementation see [[Neu18](https://docs.magma-maths.org/references.md#cite-neurohr-phd), Section 3.3].

<a id="function-clenshawcurtisintegrationpoints-rngintelt-rngintelt"></a>
###### `ClenshawCurtisIntegrationPoints(N, D): RngIntElt, RngIntElt -> SeqEnum[FldReElt], SeqEnum[FldReElt]`

Construct the Clenshaw–Curtis integration scheme on $N+1$ points and precision $D$.

<a id="tanh-sinh-quadrature"></a>
##### Tanh–Sinh Quadrature

Double–exponential integration (or tanh–sinh quadrature) is a quite versatile integration scheme. While it is far less efficient than Gaussian or Clenshaw–Curtis quadrature for well-behaved integrands, double-exponential integration can easily handle difficult integrands with endpoint singularities. In fact, the double–exponential integration as implemented here can handle integrands similar to Gauss–Jacobi quadrature. It returns three sequences of real numbers of length $2N+1$: abscissas $A$, weights $W_1$, and ‘extra weights’ $W_2$.

$$
\int_{-1}^1 (1-x)^a(1+x)^b f(x) dx \approx \sum_{k=1}^{2N+1} W_1[k] \cdot W_2[k]^b \cdot (1+A[k])^{b-a} \cdot f(A[k])\,.
$$

for a well–behaved, complex–valued function $f : [-1,1] \rightarrow {\mathbb{C}}$ and $N$ chosen large enough and, without loss of generality, $b>a$.

<a id="function-tanhsinhintegrationpoints-rngintelt-fldreelt"></a>
###### `TanhSinhIntegrationPoints(N, h): RngIntElt, FldReElt -> SeqEnum[FldReElt], SeqEnum[FldReElt], SeqEnum[FldReElt]`

Construct the double–exponential integration scheme with $2N+1$ points and step-length $h>0$. The precision of the abscissas and weights is inherited from $h$.

<a id="example-ex-fd7870"></a>
###### `Example: Numerical Integration on the Unit Interval (ex-fd7870)`

The easy integral

$$
\int_{0}^{1} x \log(1+x) dx = {1 \over 4}\,.
$$

is chosen to illustrate how these integration schemes may be used. The computation is performed using precision $D=50$.

```magma
> N := 20;
> D := 50;
> function f(x)
>    return x*Log(1+x);
> end function;
> A_GL, W_GL := GaussLegendreIntegrationPoints(N,D);
> /* Map abscissas to the interval [0,1] */
> A_GL := [ (1/2)*(a+1) : a in A_GL ];
> int_GL := (1/2) * &+[ W_GL[k] * f(A_GL[k]) : k in [1..N] ];
> Abs(int_GL - 1/4);
9.3232511485451973751923945899073760403381175208927E-33
```

Now, using Clenshaw–Curtis integration on $N+1=21$ points

```magma
> A_CC, W_CC := ClenshawCurtisIntegrationPoints(N,D);
> A_CC := [ (1/2)*(a+1) : a in A_CC ];
> int_CC := (1/2) * &+[ W_CC[k] * f(A_CC[k]) : k in [1..N+1] ];
> Abs(int_CC - 1/4);
1.4644696752310341410357330113758869025438089669910E-20
```

and, finally, double-exponential with steplength $h=6/N$

```magma
> h := RealField(D)!6/N;
> A_DE, W_DE := TanhSinhIntegrationPoints(N,h);
> A_DE := [ (1/2)*(a+1) : a in A_DE ];
> int_DE := (1/2) * &+[ W_DE[k] * f(A_DE[k]) : k in [1..2*N+1] ];
> Abs(int_DE - 1/4);
4.4223451294316356251002317691142668875095964280941E-10
```

<a id="example-ex-9327e9"></a>
###### `Example: Integral with Endpoint Singularities (ex-9327e9)`

One could, for example, want to approximate the integral

$$
\int_{-1}^{1} {\cos(x)\sin(x) \over (1-x)^{1 \over 3}(1+x)^{1 \over 3}} dx \approx 0.128866348618482136010608730745\,.
$$

using $N=10$ integration points in precision $D=30$.

```magma
> c := 0.128866348618482136010608730745;
> N := 10;
> D := 30;
> function f(x)
>    return Sin(x)*Cos(x);
> end function;
> A, W := GaussJacobiIntegrationPoints(N,D,-1/3,-1/5);
> int_GJ := &+[ W[k] * f(A[k]) : k in [1..N] ];
> Abs(int_GJ - c);
1.14406228730447597223836768506E-20
```

A similar result can be achieved when using double-exponential integration (or Tanh–Sinh quadrature) with steplength $h = 1/8$ and $N = 48$

```magma
> h := Real(2^-3);
> N := Ceiling(6/h);
> A, W1, W2 := TanhSinhIntegrationPoints(N,h);
> int_DE := &+[ W1[k]*W2[k]^(1/3)*(1+A[k])^(1/3-1/5)*f(A[k]) : k in [1..2*N+1] ];
> Abs(int_DE - c);
1.32999219914892690177636985694E-20
```

<a id="example-ex-1222c3"></a>
###### `Example: Integral over an Infinite Interval (ex-1222c3)`

The double-exponential integration can also be used to approximate tough integrals such as

$$
\int_{0}^{\infty} e^{-x}\cos(x) dx = \int_{0}^{1} {e^{1-{1 \over z}}\cos({1 \over z}-1) \over z^2} dz = {1 \over 2}\,.
$$

```magma
> h := RealField(1000)!(2^-10);
> N := Ceiling(7.2/h);
> A_DE, W_DE := TanhSinhIntegrationPoints(N,h);
> assert A_DE[1] gt -1;
> assert A_DE[2*N+1] lt 1;
> A_DE := [ (1/2)*(a+1) : a in A_DE ];
> function f(z)
>    return (Exp(1-1/z) * Cos(1/z-1)/z^2);
> end function;
> int_DE := (1/2) * &+[ W_DE[k] * f(A_DE[k]) : k in [1..2*N+1] ];
> Abs(int_DE - 1/2) lt 10^-300;
true
```

#### Romberg-Type Integration

A number of ‘Romberg-Type’ integration methods are provided which are based on Pari implementations. The precision should not be made too large for this, and the range of integration (including its boundaries) must be free of singularities.

<a id="function-rombergquadrature-program-fldreelt-fldreelt"></a>
##### `RombergQuadrature(f, a, b: parameters): Program, FldReElt, FldReElt -> FldReElt`

```magma
Precision: FldReElt                     Default: 1.0e-6
MaxSteps : RngIntElt                    Default: 20
K        : RngIntElt                    Default: 5
```

Using Romberg’s method of order $2K$, approximate the integral of $f$ from $a$ to $b$. The desired accuracy may be specified by setting the `Precision` parameter, and the order of the algorithm by changing `K`. The algorithm ceases after `MaxSteps` iterations if the desired accuracy has not been achieved.

<a id="function-simpsonquadrature-program-fldreelt-fldreelt-rngintelt"></a>
##### `SimpsonQuadrature(f, a, b, n): Program, FldReElt, FldReElt, RngIntElt -> FldReElt`

Using Simpson’s rule on $n$ sub-intervals, approximate the integral of $f$ from $a$ to $b$.

<a id="function-trapezoidalquadrature-program-fldreelt-fldreelt-rngintelt"></a>
##### `TrapezoidalQuadrature(f, a, b, n): Program, FldReElt, FldReElt, RngIntElt -> FldReElt`

Using the trapezoidal rule on $n$ sub-intervals, approximate the integral of $f$ from $a$ to $b$.

#### Numerical Derivatives

A function is provided to compute the numerical derivative of a function. This is achieved by computing enough interpolation points and performing a Taylor expansion.

<a id="function-numericalderivative-userprogram-rngintelt-fldcomelt"></a>
##### `NumericalDerivative(f, n, z): UserProgram, RngIntElt, FldComElt -> FldComElt`

Given a suitably nice function $f$, compute a numerical approximation to the $n$th derivative at the point $z$.

<a id="example-ex-c82809"></a>
##### `Example: Numerical Derivative (ex-c82809)`

```magma
> f := func<x|Exp(2*x)>;
> NumericalDerivative(f, 10, ComplexField(30)! 1.0) / f (1.0);
1024.00000000000000000000000000
> NumericalDerivative(func<x|LogGamma(x)>,1,ComplexField()!3.0);
0.922784335098467139393487909918
> Psi(3.0); // Psi is Gamma'/Gamma
0.922784335098467139393487909918
```