Expand the common code for ideal implementations

This includes the addition of a `DefaultIdealSet` struct type
which can be used with zero overhead, and hopefully can simply
be used as parent type for all ideal implementations (in Hecke,
Oscar or wherever) down the road.

Also semi-documented the interfaces to be implemented (the list
is surely incomplete but better than nothing).

Author: fingolfin

docs/src/ideal_interface.md

@@ -1,12 +1,13 @@
 ```@meta
 CurrentModule = AbstractAlgebra
+CollapsedDocStrings = true
 DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Ideal Interface
 
 AbstractAlgebra.jl generic code makes use of a standardised set of functions which it
-expects to be implemented by anyone implementing ideals for AbstractAlgebra rings. 
+expects to be implemented by anyone implementing ideals for commutative rings.
 Here we document this interface. All libraries which want to make use of the generic
 capabilities of AbstractAlgebra.jl must supply all of the required functionality for their ideals.
 There are already many helper methods in AbstractAlgebra.jl for the methods mentioned below.
@@ -16,14 +17,17 @@ provided for certain types of ideals e.g., for ideals of polynomial rings. If im
 these allow the generic code to provide additional functionality for those ideals, or in
 some cases, to select more efficient algorithms.
 
+
 ## Types and parents
 
-New ideal types should come with the following type information:
+Below we describe this interface for a fictitious type `NewIdeal` which is a subtype of
+`Ideal`, representing ideals over a base ring of type `NewRing`, with element type
+`NewRingElem`. To inform the system about this relationship, it is necessary to provide the
+following methods:
 
 ```julia
-ideal_type(::Type{NewRing}) = NewIdealType 
-base_ring_type(::Type{NewIdeal}) = NewRingType
-parent_type(::Type{NewIdeal{T}}) = DefaultIdealSet{T}
+ideal_type(::Type{NewRing}) = NewIdeal
+base_ring_type(::Type{NewIdeal}) = NewRing
 ```
 
 However, new implementations of ideals needn't necessarily supply new types and could just extend
@@ -36,39 +40,32 @@ about implementing new rings, see the [Ring interface](@ref "Ring Interface").
 In the following, we list all the functions that are required to be provided for ideals
 in AbstractAlgebra.jl or by external libraries wanting to use AbstractAlgebra.jl.
 
-We give this interface for fictitious type `NewIdeal` and `Ring` or `NewRing` for the type of the base ring
-object `R`, and `RingElem` for the type of the elements of the ring.
-We assume that the function
-
+To facilitate construction of new ideals, implementations must provide a method with signature
 ```julia
-ideal(R::Ring, xs::Vector{U})
+ideal(R::NewRing, xs::Vector{NewRingElem})
 ```
+Here `xs` is a list of generators, and `NewRingElem === elem_type(NewRing)` holds.
 
-with `U === elem_type(Ring)` and `xs` a list of generators,
-is implemented by anyone implementing ideals for AbstractAlgebra rings. 
-Additionally, the following constructors are already implemented generically:
-
+With this in place, the following additional ideal constructors will automatically work via
+generic implementations:
 ```julia
-ideal(R::Ring, x::U)
-ideal(xs::Vector{U}) = ideal(parent(xs[1]), xs)
-ideal(x::U) = ideal(parent(x), x)
-*(x::RingElem, R::Ring)
-*(R::Ring, x::RingElem)
+ideal(R::NewRing, x::RingElement...) = ideal(R, [x...])
+ideal(x::RingElement, y::RingElement...) = ideal(parent(x), x, y...)
+ideal(xs::Vector{NewRingElem}) = ideal(parent(xs[1]), xs)
+*(x::NewRingElem, R::NewRing) = ideal(R, x)
+*(R::NewRing, x::NewRingElem) = ideal(R, x)
 ```
-
-An implementation of an Ideal subtype should also provide the
-following methods:
-
+In addition sums and products of ideals can be formed:
 ```julia
-base_ring(I::NewIdeal)
++(I::T, J::T) where {T <: NewIdeal}
+*(I::T, J::T) where {T <: NewIdeal}
 ```
+
+An implementation of an `Ideal` subtype must also provide the following methods:
 ```julia
+base_ring(I::NewIdeal)
 gen(I::NewIdeal, k::Int)
-```
-```julia
 gens(I::NewIdeal)
-```
-```julia
 ngens(I::NewIdeal)
 ```
 
@@ -84,24 +81,29 @@ functions. As these functions are optional, they do not need to exist. Julia wil
 already inform the user that the function has not been implemented if it is called but
 doesn't exist.
 
+The following method have no generic implementation and only work when explicitly
+implemented.
 ```julia
-in(v::RingElem, I::NewIdeal)
+in(v::NewRingElem, I::NewIdeal)
+intersect(I::T, J::T) where {T <: NewIdeal}
 ```
+
+If a method for `in` as above is provided, then the following automatically works:
 ```julia
 issubset(I::NewIdeal, J::NewIdeal)
 ```
+
+If a method for `in` as above is provided (e.g. indirectly by providing method for `in`),
+then the following automatically works:
 ```julia
-iszero(I::NewIdeal)
-```
-```julia
-+(I::T, J::T) where {T <: NewIdeal}
-```
-```julia
-*(I::T, J::T) where {T <: NewIdeal}
-```
-```julia
-intersect(I::T, J::T) where {T <: NewIdeal}
+==(I::T, J::T) where {T <: NewIdeal}
 ```
+Note that implementing `==` for a Julia type comes means that we have to pr
+a matching `hash` method which preserves the invariant that `I == J` implies `hash(I) == hash(J)`.
+We provide such a method but by necessity it is very conservative and hence does
+not provide good hashing. You may wish to implement a better `hash` methods.
+
+The following method is implemented generically via the ideal generators.
 ```julia
-==(I::T, J::T) where {T <: NewIdeal}
+iszero(I::Ideal) = all(iszero, gens(I))
 ```

src/AbstractAlgebra.jl

@@ -229,6 +229,10 @@ function check_parent(a, b, throw::Bool = true)
    return flag
 end
 
+function check_base_ring(a, b)
+   base_ring(a) === base_ring(b) || error("base rings do not match")
+end
+
 include("algorithms/LaurentPoly.jl")
 include("algorithms/FinField.jl")
 include("algorithms/GenericFunctions.jl")

src/Ideal.jl

@@ -1,14 +1,51 @@
 ###############################################################################
 #
-#   Ideal constructor
+#   Generic functionality for ideals
 #
 ###############################################################################
 
-# We assume that the function
-#   ideal(R::T, xs::Vector{U})
-# with U === elem_type(T) is implemented by anyone implementing ideals
-# for AbstractAlgebra rings.
-# The functions in this file extend the interface for `ideal`.
+###############################################################################
+#
+#   Type and parent functions
+#
+###############################################################################
+
+# fundamental interface
+@doc raw"""
+    ideal_type(a)
+
+Return the type of the base ring of the given element, element type, ring or ring type $a$.
+"""
+ideal_type(x) = ideal_type(typeof(x))
+ideal_type(x::Type{<:RingElement}) = ideal_type(parent_type(x))
+ideal_type(T::DataType) = throw(MethodError(ideal_type, (T,)))
+
+base_ring_type(::Type{<:IdealSet{T}}) where {T} = parent_type(T)
+
+elem_type(::Type{<:IdealSet{T}}) where {T} = ideal_type(parent_type(T))
+
+###############################################################################
+#
+#   Ideal constructors
+#
+###############################################################################
+
+@doc raw"""
+    ideal(R::Ring, elms::AbstractVector{<:RingElement})
+    ideal(R::Ring, elms...)
+    ideal(elms::AbstractVector{<:RingElement})
+    ideal(elms...)
+
+Return the `R`-ideal generated by `elms`.
+
+If `R` is omitted then `elms` must be non-empty, otherwise an error is raised.
+"""
+ideal
+
+# All constructors ultimately delegate to a method
+#   ideal(R::T, xs::Vector{U}) where T <: NCRing
+# and U === elem_type(T)
+
 
 # the following helper enables things like `ideal(R, [])` or `ideal(R, [1])`
 # the type check ensures we don't run into an infinite recursion
@@ -21,6 +58,78 @@ function ideal(R::NCRing, x, y...; kw...)
   return ideal(R, elem_type(R)[R(z) for z in [x, y...]]; kw...)
 end
 
+function ideal(x::T, y::T...; kw...) where T<:NCRingElement
+  return ideal(parent(x), x, y...; kw...)
+end
+
+function ideal(xs::AbstractVector{T}; kw...) where T<:NCRingElement
+  @req !is_empty(xs) "Empty collection, cannot determine parent ring. Try ideal(ring, xs) instead of ideal(xs)"
+  return ideal(parent(xs[1]), xs; kw...)
+end
+
+###############################################################################
+#
+#   Basic predicates
+#
+###############################################################################
+
+@doc raw"""
+    iszero(I::Ideal)
+
+Check if the ideal `I` is the zero ideal.
+"""
+iszero(I::Ideal) = all(iszero, gens(I))
+
+@doc raw"""
+    Base.issubset(I::T, J::T) where {T <: Ideal}
+
+Return `true` if the ideal `I` is a subset of the ideal `J`.
+An exception is thrown if the ideals are not defined over the same base ring.
+"""
+function Base.issubset(I::T, J::T) where {T <: Ideal}
+  I === J && return true
+  check_base_ring(I, J)
+  return all(in(J), gens(I))
+end
+
+###############################################################################
+#
+#   Comparison
+#
+###############################################################################
+
+function Base.:(==)(I::T, J::T) where {T <: Ideal}
+  return is_subset(I, J) && is_subset(J, I)
+end
+
+function Base.:hash(I::T, h::UInt) where {T <: Ideal}
+  h = hash(base_ring(I), h)
+  return h
+end
+
+###############################################################################
+#
+#   Binary operations
+#
+###############################################################################
+
+function Base.:+(I::T, J::T) where {T <: Ideal}
+  check_base_ring(I, J)
+  return ideal(base_ring(I), vcat(gens(I), gens(J)))
+end
+
+# The following method for I*J is only applicable to commutative ideals
+function Base.:*(I::T, J::T) where {T <: Ideal{<:RingElement}}
+  check_base_ring(I, J)
+  return ideal(base_ring(I), [x*y for x in gens(I) for y in gens(J)])
+end
+
+###############################################################################
+#
+#   Ad hoc binary operations
+#
+###############################################################################
+
 function *(R::Ring, x::RingElement)
   return ideal(R, x)
 end
@@ -29,19 +138,22 @@ function *(x::RingElement, R::Ring)
   return ideal(R, x)
 end
 
-function ideal(x::NCRingElement; kw...)
-  return ideal(parent(x), x; kw...)
+function *(I::Ideal{T}, p::T) where T <: RingElement
+  R = base_ring(I)
+  iszero(p) && return ideal(R, T[])
+  return ideal(R, [v*p for v in gens(I)])
 end
 
-function ideal(xs::AbstractVector{T}; kw...) where T<:NCRingElement
-  @req !is_empty(xs) "Empty collection, cannot determine parent ring. Try ideal(ring, xs) instead of ideal(xs)"
-  return ideal(parent(xs[1]), xs; kw...)
+function *(p::T, I::Ideal{T}) where T <: RingElement
+  return I*p
 end
 
-iszero(I::Ideal) = all(iszero, gens(I))
-
-base_ring_type(::Type{<:IdealSet{T}}) where T <: RingElement = parent_type(T)
+function *(I::Ideal{<:RingElement}, p::RingElement)
+  R = base_ring(I)
+  iszero(p*one(R)) && return ideal(R, T[])
+  return ideal(R, [v*p for v in gens(I)])
+end
 
-# fundamental interface, to be documented
-ideal_type(x) = ideal_type(typeof(x))
-ideal_type(T::DataType) = throw(MethodError(ideal_type, (T,)))
+function *(p::RingElement, I::Ideal{<:RingElement})
+  return I*p
+end

src/generic/Ideal.jl

@@ -34,7 +34,11 @@ parent_type(::Type{Ideal{S}}) where S <: RingElement = IdealSet{S}
 
 Return a list of generators of the ideal `I` in reduced form and canonicalised.
 """
-gens(I::Ideal{T}) where T <: RingElement = I.gens
+gens(I::Ideal) = I.gens
+
+number_of_generators(I::Ideal) = length(I.gens)
+
+gen(I::Ideal, i::Int) = I.gens[i]
 
 ###############################################################################
 #
@@ -2094,33 +2098,14 @@ end
 
 ###############################################################################
 #
-#   Comparison
-#
-###############################################################################
-
-function ==(I::Ideal{T}, J::Ideal{T}) where T <: RingElement
-   return gens(I) == gens(J)
-end
-
-###############################################################################
-#
-#   Containment
+#   Membership
 #
 ###############################################################################
 
 function Base.in(v::T, I::Ideal{T}) where T <: RingElement
   return is_zero(normal_form(v, I))
 end
 
-@doc raw"""
-    Base.issubset(I::Ideal{T}, J::Ideal{T}) where T <: RingElement
-
-Return `true` if the ideal `I` is a subset of the ideal `J`.
-"""
-function Base.issubset(I::Ideal{T}, J::Ideal{T}) where T <: RingElement
-   return all(in(J), gens(I))
-end
-
 ###############################################################################
 #
 #   Intersection
@@ -2204,26 +2189,6 @@ function intersect(I::Ideal{T}, J::Ideal{T}) where {U <: RingElement, T <: Abstr
    return Ideal(S, GInt)
 end
 
-###############################################################################
-#
-#   Binary operations
-#
-###############################################################################
-
-function +(I::Ideal{T}, J::Ideal{T}) where T <: RingElement
-   R = base_ring(I)
-   G1 = gens(I)
-   G2 = gens(J)
-   return Ideal(R, vcat(G1, G2))
-end
-
-function *(I::Ideal{T}, J::Ideal{T}) where T <: RingElement
-   R = base_ring(I)
-   G1 = gens(I)
-   G2 = gens(J)
-   return Ideal(R, [v*w for v in G1 for w in G2])
-end
-
 ###############################################################################
 #
 #   Ad hoc binary operations