Add coefficient_ring for modules and improve the docs for base_ring

Author: SoongNoonien

docs/src/extending_abstractalgebra.md

@@ -29,6 +29,14 @@ base_ring
 base_ring_type
 ```
 
+If there is a well-defined notion of a coefficient ring (e.g. in the case of
+polynomial rings or modules), then one should implement
+
+```@docs
+coefficient_ring
+coefficient_ring_type
+```
+
 ## Special elements
 
 For rings, one has to extend the following methods:

src/fundamental_interface.jl

@@ -77,7 +77,7 @@ parent_type(T::DataType) = throw(MethodError(parent_type, (T,)))
 @doc raw"""
     base_ring(a)
 
-Return base ring $R$ of given element or parent $a$.
+Return the internal base ring of the given element or parent $a$.
 
 # Examples
 ```jldoctest
@@ -101,7 +101,7 @@ base_ring(x::NCRingElement) = base_ring(parent(x))
 @doc raw"""
     base_ring_type(a)
 
-Return the type of the base ring of the given element, element type, parent or parent type $a$.
+Return the type of the internal base ring of the given element, element type, parent or parent type $a$.
 
 # Examples
 ```jldoctest
@@ -133,9 +133,52 @@ base_ring_type(x::Type{<:ModuleElem}) = base_ring_type(parent_type(x))
 base_ring_type(x::Type{<:Ideal}) = base_ring_type(parent_type(x))
 base_ring_type(T::DataType) = throw(MethodError(base_ring_type, (T,)))
 
-# generic coefficient_ring method
+@doc raw"""
+    coefficient_ring(a)
+
+Return the coefficient ring of the given element or parent $a$.
+
+# Examples
+```jldoctest
+julia> R, x = polynomial_ring(QQ, :x)
+(Univariate polynomial ring in x over rationals, x)
+
+julia> coefficient_ring(x^2+1) == QQ
+true
+
+julia> S, (z,w) = universal_polynomial_ring(QQ, [:z,:w])
+(Universal Polynomial Ring over Rationals, AbstractAlgebra.Generic.UnivPoly{Rational{BigInt}}[z, w])
+
+julia> coefficient_ring(S) == QQ
+true
+```
+"""
+function coefficient_ring end
 coefficient_ring(x::NCRingElement) = coefficient_ring(parent(x))
 
+@doc raw"""
+    coefficient_ring_type(a)
+
+Return the type of the coefficient ring of the given element, element type, parent or parent type $a$.
+
+# Examples
+```jldoctest
+julia> R, x = polynomial_ring(ZZ, :x)
+(Univariate polynomial ring in x over integers, x)
+
+julia> coefficient_ring_type(R) == typeof(coefficient_ring(R))
+true
+
+julia> coefficient_ring_type(zero(R)) == typeof(coefficient_ring(zero(R)))
+true
+
+julia> coefficient_ring_type(typeof(R)) == typeof(coefficient_ring(R))
+true
+
+julia> coefficient_ring_type(typeof(zero(R))) == typeof(coefficient_ring(zero(R)))
+true
+```
+"""
 coefficient_ring_type(x) = coefficient_ring_type(typeof(x))
 coefficient_ring_type(x::Type{<:NCRingElement}) = coefficient_ring_type(parent_type(x))
 coefficient_ring_type(x::Type{<:ModuleElem}) = coefficient_ring_type(parent_type(x))

src/generic/FreeModule.jl

@@ -16,6 +16,10 @@ base_ring_type(::Type{FreeModule{T}}) where T <: Union{RingElement, NCRingElem}
 
 base_ring(M::FreeModule{T}) where T <: Union{RingElement, NCRingElem} = M.base_ring::parent_type(T)
 
+coefficient_ring_type(T::Type{FreeModule}) = base_ring_type(T)
+
+coefficient_ring(M::FreeModule) = base_ring(M)
+
 elem_type(::Type{FreeModule{T}}) where T <: Union{RingElement, NCRingElem} = FreeModuleElem{T}
 
 parent(m::FreeModuleElem{T}) where T <: Union{RingElement, NCRingElem} = m.parent
@@ -50,7 +54,7 @@ end
 
 function gen(N::FreeModule{T}, i::Int) where T <: Union{RingElement, NCRingElem}
    @boundscheck 1 <= i <= ngens(N) || throw(ArgumentError("generator index out of range"))
-   R = base_ring(N)
+   R = coefficient_ring(N)
    m = zero_matrix(R, 1, ngens(N))
    add_one!(m, 1, i)
    return N(m)
@@ -72,7 +76,7 @@ function show(io::IO, M::FreeModule{T}) where T <: Union{RingElement, NCRingElem
    print(io, "Free module of rank ")
    print(io, rank(M))
    print(io, " over ")
-   print(terse(pretty(io)), Lowercase(), base_ring(M))
+   print(terse(pretty(io)), Lowercase(), coefficient_ring(M))
 end
 
 function show(io::IO, M::FreeModule{T}) where T <: FieldElement
@@ -81,7 +85,7 @@ function show(io::IO, M::FreeModule{T}) where T <: FieldElement
    print(io, "Vector space of dimension ")
    print(io, dim(M))
    print(io, " over ")
-   print(terse(pretty(io)), Lowercase(), base_ring(M))
+   print(terse(pretty(io)), Lowercase(), coefficient_ring(M))
 end
 
 function show(io::IO, a::FreeModuleElem)
@@ -105,23 +109,23 @@ end
 
 function (M::FreeModule{T})(a::Vector{T}) where T <: Union{RingElement, NCRingElem}
    length(a) != rank(M) && error("Number of elements does not equal rank")
-   R = base_ring(M)
+   R = coefficient_ring(M)
    v = matrix(R, 1, length(a), a)
    z = FreeModuleElem{T}(M, v)
    return z
 end
 
 #function (M::FreeModule{T})(a::Vector{<: Integer}) where T <: Union{RingElement, NCRingElem}
 #   length(a) != rank(M) && error("Number of elements does not equal rank")
-#   R = base_ring(M)
+#   R = coefficient_ring(M)
 #   v = matrix(R, 1, length(a), a)
 #   z = FreeModuleElem{T}(M, v)
 #   return z
 #end
 
 function (M::FreeModule{T})(a::Vector{S}) where {T <: Union{RingElement, NCRingElem}, S <: RingElement}
    length(a) != rank(M) && error("Number of elements does not equal rank")
-   R = base_ring(M)
+   R = coefficient_ring(M)
    v = matrix(R, 1, length(a), a)
    z = FreeModuleElem{T}(M, v)
    return z
@@ -141,7 +145,7 @@ end
 
 function (M::FreeModule{T})(a::SubmoduleElem{T}) where T <: RingElement
    R = parent(a)
-   base_ring(R) !== base_ring(M) && error("Incompatible modules")
+   coefficient_ring(R) !== coefficient_ring(M) && error("Incompatible modules")
    return M(R.map(a))
 end
 

src/generic/QuotientModule.jl

@@ -20,6 +20,10 @@ base_ring_type(::Type{QuotientModule{T}}) where T <: RingElement = parent_type(T
 
 base_ring(N::QuotientModule{T}) where T <: RingElement = N.base_ring::parent_type(T)
 
+coefficient_ring_type(T::Type{QuotientModule}) = base_ring_type(T)
+
+coefficient_ring(N::QuotientModule) = base_ring(N)
+
 number_of_generators(N::QuotientModule{T}) where T <: RingElement = length(N.gen_cols)
 
 gens(N::QuotientModule{T}) where T <: RingElement = elem_type(N)[gen(N, i) for i = 1:ngens(N)]
@@ -28,7 +32,7 @@ rank(M::QuotientModule{T}) where T <: FieldElement = dim(M)
 
 function gen(N::QuotientModule{T}, i::Int) where T <: RingElement
    @boundscheck 1 <= i <= ngens(N) || throw(ArgumentError("generator index out of range"))
-   R = base_ring(N)
+   R = coefficient_ring(N)
    mat = matrix(R, 1, ngens(N),
                 [(j == i ? one(R) : zero(R)) for j = 1:ngens(N)])
    return QuotientModuleElem{T}(N, mat)
@@ -70,15 +74,15 @@ function show(io::IO, N::QuotientModule{T}) where T <: RingElement
    @show_name(io, N)
    @show_special(io, N)
    print(io, "Quotient module over ")
-   print(terse(pretty(io)), Lowercase(), base_ring(N))
+   print(terse(pretty(io)), Lowercase(), coefficient_ring(N))
    show_gens_rels(io, N)
 end
 
 function show(io::IO, N::QuotientModule{T}) where T <: FieldElement
    @show_name(io, N)
    @show_special(io, N)
    print(io, "Quotient space over ")
-   print(terse(pretty(io)), Lowercase(), base_ring(N))
+   print(terse(pretty(io)), Lowercase(), coefficient_ring(N))
    show_gens_rels(io, N)
 end
 
@@ -114,7 +118,7 @@ end
 
 # Reduce the vector v by the relations vrels starting at column start of v
 function reduce_mod_rels(v::AbstractAlgebra.MatElem{T}, vrels::Vector{<:AbstractAlgebra.MatElem{T}}, start::Int) where T <: RingElement
-   R = base_ring(v)
+   R = coefficient_ring(v)
    v = deepcopy(v) # don't destroy input
    i = 1
    t1 = R()
@@ -136,7 +140,7 @@ end
 
 function (N::QuotientModule{T})(v::Vector{T}) where T <: RingElement
    length(v) != ngens(N) && error("Length of vector does not match number of generators")
-   mat = matrix(base_ring(N), 1, length(v), v)
+   mat = matrix(coefficient_ring(N), 1, length(v), v)
    mat = reduce_mod_rels(mat, rels(N), 1)
    return QuotientModuleElem{T}(N, mat)
 end
@@ -155,8 +159,8 @@ end
 
 function (M::QuotientModule{T})(a::AbstractAlgebra.FPModuleElem{T}) where T <: RingElement
    N = parent(a)
-   R = base_ring(N)
-   base_ring(M) != R && error("Incompatible modules")
+   R = coefficient_ring(N)
+   coefficient_ring(M) != R && error("Incompatible modules")
    if M === N
       return a
    else
@@ -180,7 +184,7 @@ end
 ###############################################################################
 
 function projection(v::AbstractAlgebra.MatElem{T}, crels::AbstractAlgebra.MatElem{T}, N::QuotientModule{T}) where {T <: RingElement}
-   R = base_ring(N)
+   R = coefficient_ring(N)
    # remove zero rows
    nr = nrows(crels)
    while nr > 0 && is_zero_row(crels, nr)
@@ -203,7 +207,7 @@ end
 
 function compute_combined_rels(m::AbstractAlgebra.FPModule{T}, srels::Vector{S}) where {T <: RingElement, S <: AbstractAlgebra.MatElem{T}}
    # concatenate relations in m and new rels
-   R = base_ring(m)
+   R = coefficient_ring(m)
    old_rels = rels(m)
    combined_rels = zero_matrix(R, length(old_rels) + length(srels), ngens(m))
    for i = 1:length(old_rels)
@@ -265,7 +269,7 @@ function quo(m::AbstractAlgebra.FPModule{T}, subm::Submodule{T}) where T <: Ring
      @assert is_submodule(m, subm)
    end
 
-   R = base_ring(m)
+   R = coefficient_ring(m)
    if subm === m # quotient of submodule by itself
       srels = dense_matrix_type(T)[_matrix(v) for v in gens(subm)]
       combined_rels = compute_combined_rels(m, srels)
@@ -305,7 +309,7 @@ function quo(m::AbstractAlgebra.FPModule{T}, subm::AbstractAlgebra.FPModule{T})
    srels = dense_matrix_type(T)[_matrix(v) for v in gens(subm)]
    combined_rels = compute_combined_rels(m, srels)
    M = QuotientModule{T}(m, combined_rels)
-   R = base_ring(m)
+   R = coefficient_ring(m)
    f = ModuleHomomorphism(m, M, matrix(R, ngens(m), 0, []))
    M.map = f
    return M, f   

test/generic/Module-test.jl

@@ -1,7 +1,7 @@
 function rand_homomorphism(M::AbstractAlgebra.FPModule{T}, vals...) where T <: RingElement
    rk = rand(1:5)
    m = ngens(M)
-   R = base_ring(M)
+   R = coefficient_ring(M)
    F = free_module(R, rk)
    S = matrix_space(R, rk, m)
    mat = rand(S, vals...)