Fraction field docs.

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

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)
+```
+

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)
+```
+

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