From be0d6d4eb162fb682eb8d3ec095444821307719a Mon Sep 17 00:00:00 2001 From: William Hart Date: Thu, 15 Feb 2018 14:45:23 +0100 Subject: [PATCH] Fraction field docs. --- docs/make.jl | 24 +++--- docs/src/fraction.md | 153 ++++++++++++++++++++++++++++++++++++ docs/src/fraction_fields.md | 102 ++++++++++++++++++++++++ docs/src/residue.md | 6 +- 4 files changed, 271 insertions(+), 14 deletions(-) create mode 100644 docs/src/fraction.md create mode 100644 docs/src/fraction_fields.md diff --git a/docs/make.jl b/docs/make.jl index 4ff45c0e94..86c23f84e5 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,17 +6,19 @@ makedocs( pages = [ "index.md", "constructors.md", - "rings.md", - "euclidean.md", - "polynomial_rings.md", - "polynomial.md", - "mpolynomial_rings.md", - "mpolynomial.md", - "series_rings.md", - "series.md", - "residue_rings.md", - "residue.md", - "fields.md", + "Rings" => [ "rings.md", + "euclidean.md", + "polynomial_rings.md", + "polynomial.md", + "mpolynomial_rings.md", + "mpolynomial.md", + "series_rings.md", + "series.md", + "residue_rings.md", + "residue.md"], + "Fields" => [ "fields.md", + "fraction_fields.md", + "fraction.md"], "matrix_spaces.md", "matrix.md", "types.md" # Appendix A diff --git a/docs/src/fraction.md b/docs/src/fraction.md new file mode 100644 index 0000000000..0823d9b342 --- /dev/null +++ b/docs/src/fraction.md @@ -0,0 +1,153 @@ +```@meta +CurrentModule = AbstractAlgebra +``` + +# Generic fraction fields + +AbstractAlgebra.jl provides a module, implemented in `src/generic/Fraction.jl` for +generic fraction fields over any gcd domain belonging to the AbstractAlgebra.jl +abstract type hierarchy. + +As well as implementing the Fraction Field interface a number of generic algorithms are +implemented for fraction fields. We describe this generic functionality below. + +All of the generic functionality is part of a submodule of AbstractAlgebra called +`Generic`. This is exported by default so that it is not necessary to qualify the +function names with the submodule name. + +## Types and parent objects + +Fractions implemented using the AbstractAlgebra generics have type `Generic.Frac{T}` +where `T` is the type of elements of the base ring. See the file +`src/generic/GenericTypes.jl` for details. + +Parent objects of such fraction elements have type `Generic.FracField{T}`. + +The fraction element types belong to the abstract type `AbstractAlgebra.FracElem{T}` +and the fraction field types belong to the abstract type `AbstractAlgebra.FracRing{T}`. +This enables one to write generic functions that can accept any AbstractAlgebra +fraction type. + +Note that both the generic fraction field type `Generic.FracField{T}` and the abstract +type it belongs to, `AbstractAlgebra.FracField{T}` are both called `FracField`. The +former is a (parameterised) concrete type for a fraction field over a given base ring +whose elements have type `T`. The latter is an abstract type representing all +fraction field types in AbstractAlgebra.jl, whether generic or very specialised (e.g. +supplied by a C library). + +## Fraction field constructors + +In order to construct fractions in AbstractAlgebra.jl, one can first construct the +fraction field itself. This is accomplished with the following constructor. + +```julia +FractionField(R::AbstractAlgebra.Ring; cached::Bool = true) +``` + +Given a base ring `R` return the parent object of the fraction field of $R$. By default +the parent object `S` will depend only on `R` and will be cached. Setting the optional +argument `cached` to `false` will prevent the parent object `S` from being cached. + +Here are some examples of creating fraction fields and making use of the +resulting parent objects to coerce various elements into the fraction field. + +**Examples** + +```julia +R, x = PolynomialRing(JuliaZZ, "x") +S = FractionField(R) + +f = S() +g = S(123) +h = S(BigInt(1234)) +k = S(x + 1) +``` + +All of the examples here are generic fraction fields, but specialised implementations +of fraction fields provided by external modules will also usually provide a +`FractionField` constructor to allow creation of the fraction fields they provide. + +## Basic field functionality + +Fraction fields in AbstractAlgebra.jl implement the full Field interface. Of course +the entire Fraction Field interface is also implemented. + +We give some examples of such functionality. + +**Examples** + +```julia +R, x = PolynomialRing(JuliaQQ, "x") +S = FractionField(R) + +f = S(x + 1) +g = (x^2 + x + 1)//(x^3 + 3x + 1) + +h = zero(S) +k = one(S) +isone(k) == true +iszero(f) == false +m = characteristic(S) +U = base_ring(S) +V = base_ring(f) +T = parent(f) +r = deepcopy(f) +n = numerator(g) +d = denominator(g) +``` + +## Fraction field functionality provided by AbstractAlgebra.jl + +The functionality listed below is automatically provided by AbstractAlgebra.jl for +any fraction field module that implements the full Fraction Field interface. +This includes AbstractAlgebra.jl's own generic fraction fields. + +But if a C library provides all the functionality documented in the Fraction Field +interface, then all the functions described here will also be automatically supplied by +AbstractAlgebra.jl for that fraction field type. + +Of course, modules are free to provide specific implementations of the functions +described here, that override the generic implementation. + +### Greatest common divisor + +```@docs +gcd{T <: RingElem}(::FracElem{T}, ::FracElem{T}) +``` + +**Examples** + +```julia +R, x = PolynomialRing(JuliaQQ, "x") + +f = (x + 1)//(x^3 + 3x + 1) +g = (x^2 + 2x + 1)//(x^2 + x + 1) + +h = gcd(f, g) +``` + +### Remove and valuation + +When working over a Euclidean domain, it is convenient to extend valuations to the +fraction field. To facilitate this, we define the following functions. + +```@docs +remove{T <: RingElem}(::FracElem{T}, ::T) +``` + +```@docs +valuation{T <: RingElem}(::FracElem{T}, ::T) +``` + +**Examples** + +```julia +R, x = PolynomialRing(JuliaZZ, "x") + +f = (x + 1)//(x^3 + 3x + 1) +g = (x^2 + 1)//(x^2 + x + 1) + +v, q = remove(f^3*g, x + 1) +v = valuation(f^3*g, x + 1) +``` + diff --git a/docs/src/fraction_fields.md b/docs/src/fraction_fields.md new file mode 100644 index 0000000000..0e27e18701 --- /dev/null +++ b/docs/src/fraction_fields.md @@ -0,0 +1,102 @@ +# Fraction Field Interface + +Fraction fields are supported in AbstractAlgebra.jl, at least for gcd domains. +In addition to the standard Ring interface, some additional functions are required to be +present for fraction fields. + +## Types and parents + +AbstractAlgebra provides two abstract types for fraction fields and their elements: + + * `FracField{T}` is the abstract type for fraction field parent types + * `FracElem{T}` is the abstract type for types of fractions + +We have that `FracField{T} <: AbstractAlgebra.Field` and +`FracElem{T} <: AbstractAlgebra.FieldElem`. + +Note that both abstract types are parameterised. The type `T` should usually be the type +of elements of the base ring of the fraction field. + +Fraction fields should be made unique on the system by caching parent objects (unless +an optional `cache` parameter is set to `false`). Fraction fields should at least be +distinguished based on their base ring. + +See `src/generic/GenericTypes.jl` for an example of how to implement such a cache (which +usually makes use of a dictionary). + +## Required functionality for fraction fields + +In addition to the required functionality for the Field interface the Fraction Field +interface has the following required functions. + +We suppose that `R` is a fictitious base ring, and that `S` is the fraction field with +parent object `S` of type `MyFracField{T}`. We also assume the fractions in the field +have type `MyFrac{T}`, where `T` is the type of elements of the base ring. + +Of course, in practice these types may not be parameterised, but we use parameterised +types here to make the interface clearer. + +Note that the type `T` must (transitively) belong to the abstract type `RingElem`. + +### Constructors + +We provide the following constructors. Note that these constructors don't require +construction of the parent object first. This is easier to achieve if the fraction +element type doesn't contain a reference to the parent object, but merely contains a +reference to the base ring. The parent object can then be constructed on demand. + +```julia +//(x::T, y::T) where T <: AbstractAlgebra.RingElem +``` + +Return the fraction $x/y$. + +```julia +//(x::T, y::AbstractAlgebra.FracElem{T}) where T <: AbstractAlgebra.RingElem +``` + +Return $x/y$ where $x$ is in the base ring of $y$. + +```julia +//(x::AbstractAlgebra.FracElem{T}, y::T) where T <: AbstractAlgebra.RingElem +``` + +Return $x/y$ where $y$ is in the base ring of $x$. + +**Examples** + +```julia +R, x = PolynomialRing(JuliaZZ, "x") + +f = (x^2 + x + 1)//(x^3 + 3x + 1) +g = f//x +h = x//f +``` + +### Basic manipulation of fields and elements + +```julia +numerator(d::MyFrac{T}) where T <: AbstractAlgebra.RingElem +``` + +Given a fraction $d = a/b$ return $a$, where $a/b$ is in lowest terms with respect to +the `canonical_unit` and `gcd` functions on the base ring. + +```julia +denominator(d::MyFrac{T}) where T <: AbstractAlgebra.RingElem +``` + +Given a fraction $d = a/b$ return $b$, where $a/b$ is in lowest terms with respect to +the `canonical_unit` and `gcd` functions on the base ring. + +**Examples** + +```julia +R, x = PolynomialRing(JuliaQQ, "x") + +f = (x^2 + x + 1)//(x^3 + 3x + 1) + +n = numerator(f) +d = denominator(f) +``` + diff --git a/docs/src/residue.md b/docs/src/residue.md index 7ac2e2c24b..2db95841c3 100644 --- a/docs/src/residue.md +++ b/docs/src/residue.md @@ -9,7 +9,7 @@ generic residue rings over any Euclidean domain (in practice most of the functio is provided for GCD domains that provide a meaningful GCD function) belonging to the AbstractAlgebra.jl abstract type hierarchy. -As well as implementing the ResidueRing interface a number of generic algorithms are +As well as implementing the Residue Ring interface a number of generic algorithms are implemented for residue rings. We describe this generic functionality below. All of the generic functionality is part of a submodule of AbstractAlgebra called @@ -19,7 +19,7 @@ function names with the submodule name. ## Types and parent objects Residues implemented using the AbstractAlgebra generics have type `Generic.Res{T}` -where `T` is the type of elements of the residue ring. See the file +where `T` is the type of elements of the base ring. See the file `src/generic/GenericTypes.jl` for details. Parent objects of such residue ring elements have type `Generic.ResRing{T}`. @@ -94,7 +94,7 @@ m = modulus(S) U = base_ring(S) V = base_ring(f) T = parent(f) -g == deepcopy(f) +f == deepcopy(f) ``` ## Residue ring functionality provided by AbstractAlgebra.jl