more on Betti diagrams (#2706)

* more on Betti diagrams

* correction

docs/src/CommutativeAlgebra/affine_algebras.md

@@ -649,3 +649,9 @@ multi_hilbert_series(A::MPolyQuoRing; algorithm::Symbol=:BayerStillmanA)
 multi_hilbert_series_reduced(A::MPolyQuoRing; algorithm::Symbol=:BayerStillmanA)
 multi_hilbert_function(A::MPolyQuoRing, g::GrpAbFinGenElem)
 ```
+
+## Affine Algebras as Modules
+
+```@docs
+quotient_ring_as_module(A::MPolyQuoRing)
+```

docs/src/CommutativeAlgebra/homological_algebra.md

@@ -33,7 +33,7 @@ free_resolution(M::SubquoModule{<:MPolyRingElem};
   )
 ```
 
-## Betti Diagrams
+## Betti Tables
 
 Given a $\mathbb Z$-graded multivariate polynomial ring $S$, and given
 a graded free resolution  with finitely generated graded free $S$-modules 
@@ -78,9 +78,15 @@ betti_table(F::FreeResolution)
 ```
 
 ```@docs
-minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
+minimal_betti_table(F::FreeResolution{T}) where {T<:ModuleFP}
 ```
 
+```@docs
+minimal_betti_table(M::ModuleFP{T}) where {T<:MPolyDecRingElem}
+```
+
+## Castelnuovo-Mumford Regularity
+
 ```@docs
 cm_regularity(M::ModuleFP)
 ```

docs/src/CommutativeAlgebra/ideals.md

@@ -271,6 +271,11 @@ homogenization(f::MPolyRingElem, var::VarName; pos::Union{Int,Nothing}=nothing)
 dehomogenization(F::MPolyDecRingElem, pos::Int)
 ```
 
+## Ideals as Modules
+
+```@docs
+ideal_as_module(I::MPolyIdeal)
+```
 
 ## Generating Special Ideals
 

src/Modules/ModulesGraded.jl

@@ -1311,7 +1311,7 @@ of `F` in form of a Betti table.
 Alternatively, use `betti`.
 
 # Examples
-```jldoctest
+```julia
 julia> R, (w, x, y, z) = graded_polynomial_ring(QQ, ["w", "x", "y", "z"]);
 
 julia> I = ideal(R, [x*z, y*z, x*w^2, y*w^2])
@@ -1326,8 +1326,14 @@ Free resolution of A
 R^1 <---- R^4 <---- R^4 <---- R^1 <---- 0
 0         1         2         3         4
 
-julia> betti_table(FA);
-
+julia> betti_table(FA)
+       0  1  2  3  
+------------------
+0    : 1  -  -  -  
+1    : -  2  1  -  
+2    : -  2  3  1  
+------------------
+total: 1  4  4  1  
 ```
 """
 function betti_table(F::FreeResolution; project::Union{GrpAbFinGenElem, Nothing} = nothing, reverse_direction::Bool=false)
@@ -1963,12 +1969,46 @@ end
 # TODO: Are the signatures sufficient to assure that the modules are graded?
 
 @doc raw"""
-    minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
+    minimal_betti_table(M::ModuleFP{T}) where {T<:MPolyDecRingElem}
+    minimal_betti_table(A::MPolyQuoRing{T}) where {T<:MPolyDecRingElem}
+    minimal_betti_table(I::MPolyIdeal{T}) where {T<:MPolyDecRingElem} 
+
+Given a finitely presented graded module `M` over a standard $\mathbb Z$-graded 
+multivariate polynomial ring with coefficients in a field, return the Betti Table
+of the minimal free resolution of `M`. Similarly for `A` and `I`.
+
+# Examples
+```julia
+julia> R, (w, x, y, z) = graded_polynomial_ring(QQ, ["w", "x", "y", "z"]);
+
+julia> I = ideal(R, [w^2-x*z, w*x-y*z, x^2-w*y, x*y-z^2, y^2-w*z]);
+
+julia> A, _ = quo(R, I)
+(Quotient of multivariate polynomial ring by ideal with 5 generators, Map from
+R to A defined by a julia-function with inverse)
+
+julia> minimal_betti_table(A)
+       0  1  2  3  
+------------------
+0    : 1  -  -  -  
+1    : -  5  5  -  
+2    : -  -  -  1  
+------------------
+total: 1  5  5  1  
+```
 """
+function minimal_betti_table(M::ModuleFP{T}) where {T<:MPolyDecRingElem}
+ error("Not implemented for the given type")
+end
+
 function minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
   return minimal_betti_table(free_resolution(M))
 end
 
+function minimal_betti_table(F::FreeMod{T}) where {T<:MPolyDecRingElem}
+  return minimal_betti_table(free_resolution(M))
+end
+
 function minimal_betti_table(A::MPolyQuoRing{T}) where {T<:MPolyDecRingElem}
   return minimal_betti_table(free_resolution(A))
 end
@@ -1977,50 +2017,53 @@ function minimal_betti_table(I::MPolyIdeal{T}) where {T<:MPolyDecRingElem}
   return minimal_betti_table(free_resolution(I))
 end
 
-#=
- The examples below don't run because of a bug in the documenter. 
- We can put them back in, once that works.
 
-# Examples
-```jldoctest
-julia> R, _ = polynomial_ring(QQ, [:w, :x, :y, :z]);
 
-julia> R, (w, x, y, z) = grade(R)
-(Graded multivariate polynomial ring in 4 variables over QQ, MPolyDecRingElem{QQFieldElem, QQMPolyRingElem}[w, x, y, z])
+@doc raw"""
+    minimal_betti_table(F::FreeResolution{T}) where {T<:ModuleFP}
+
+Given a graded free resolution `F` over a standard $\mathbb Z$-graded 
+multivariate polynomial ring with coefficients in a field, return the
+Betti table of the minimal free resolution arising from `F`.
+
+!!! note
+    The algorithm proceeds without actually minimizing the resolution.
+
+# Examples
+```julia
+julia> R, (w, x, y, z) = graded_polynomial_ring(QQ, ["w", "x", "y", "z"]);
 
-julia> I = ideal(R, [w^2 - x*z, w*x - y*z, x^2 - w*y, x*y - z^2, y^2 - w*z])
-ideal(w^2 - x*z, w*x - y*z, -w*y + x^2, x*y - z^2, -w*z + y^2)
+julia> I = ideal(R, [w^2-x*z, w*x-y*z, x^2-w*y, x*y-z^2, y^2-w*z]);
 
 julia> A, _ = quo(R, I)
 (Quotient of multivariate polynomial ring by ideal with 5 generators, Map from
 R to A defined by a julia-function with inverse)
 
-julia> betti_table(free_resolution(A))
-       0  1  2  3
+julia> FA = free_resolution(A)
+Free resolution of A
+R^1 <---- R^5 <---- R^6 <---- R^2 <---- 0
+0         1         2         3         4
+
+julia> betti_table(FA)
+       0  1  2  3  
 ------------------
-0    : 1  -  -  -
-1    : -  5  5  1
-2    : -  -  1  1
+0    : 1  -  -  -  
+1    : -  5  5  1  
+2    : -  -  1  1  
 ------------------
-total: 1  5  6  2
+total: 1  5  6  2  
 
-julia> minimal_betti_table(free_resolution(A))
-       0  1  2  3
+
+julia> minimal_betti_table(FA)
+       0  1  2  3  
 ------------------
-0    : 1  -  -  -
-1    : -  5  5  -
-2    : -  -  -  1
+0    : 1  -  -  -  
+1    : -  5  5  -  
+2    : -  -  -  1  
 ------------------
-total: 1  5  5  1
-
+total: 1  5  5  1  
 ```
 """
-=#
-@doc raw"""
-    minimal_betti_table(res::FreeResolution{T}) where {T<:ModuleFP}
-
-The Betti table of a minimized version of `res` without actually computing a minimalization.
-"""
 function minimal_betti_table(res::FreeResolution{T}) where {T<:ModuleFP}
   @assert is_standard_graded(base_ring(res)) "resolution must be defined over a standard graded ring"
   @assert is_graded(res) "resolution must be graded"
@@ -2207,10 +2250,17 @@ end
     cm_regularity(M::ModuleFP)
 
 Given a finitely presented graded module `M` over a standard $\mathbb Z$-graded 
-multivariate polynomial ring, return the Castelnuovo-Mumford regularity of `M`.
- 
+multivariate polynomial ring with coefficients in a field, return the
+Castelnuovo-Mumford regularity of `M`.
+
+    cm_regularity(I::MPolyIdeal)
+
+Given a (homogeneous) ideal `I` in a standard $\mathbb Z$-graded 
+multivariate polynomial ring with coefficients in a field, return the
+Castelnuovo-Mumford regularity of `I`.
+
 # Examples
-```jldoctest
+```julia
 julia> R, (x, y, z) = graded_polynomial_ring(QQ, ["x", "y", "z"]);
 
 julia> F = graded_free_module(R, 1);
@@ -2228,22 +2278,154 @@ Homogeneous module homomorphism)
 julia> cm_regularity(M)
 3
 
-julia> minimal_betti_table(M);
+julia> minimal_betti_table(M)
+       0 1 2 3 
+--------------
+0    : 1 - - - 
+1    : - 3 - - 
+2    : - - 3 - 
+3    : - - - 1 
+--------------
+total: 1 3 3 1 
+```
+```julia
+julia> R, (w, x, y, z) = graded_polynomial_ring(QQ, ["w", "x", "y", "z"]);
+
+julia> I = ideal(R, [-x*z+y^2, x*y-w*z, x^2-w*y]);
+
+julia> cm_regularity(I)
+2
+
+julia> A, _ = quo(R, I);
+
+julia> minimal_betti_table(A)
+       0 1 2 
+------------
+0    : 1 - - 
+1    : - 3 2 
+------------
+total: 1 3 2 
 ```
 """
 function cm_regularity(M::ModuleFP)
  error("Not implemented for the given type")
 end
 
 function cm_regularity(M::FreeMod)
-   @req is_standard_graded(base_ring(M)) "The base ring is not standard ZZ-graded"
+   R = base_ring(M)
+   @req coefficient_ring(R) isa AbstractAlgebra.Field "The coefficient ring must be a field"
+   @req is_standard_graded(R) "The base ring is not standard ZZ-graded"
    return 0
 end
 
 function cm_regularity(M::SubquoModule)
-   @req is_standard_graded(base_ring(M)) "The base ring is not standard ZZ-graded"
+   R = base_ring(M)
+   @req coefficient_ring(R) isa AbstractAlgebra.Field "The coefficient ring must be a field"
+   @req is_standard_graded(R) "The base ring is not standard ZZ-graded"
    B = minimal_betti_table(M)
    S = as_dictionary(B)
    V = [x[2][1] - x[1] for x in keys(S)] 
   return maximum(V)
 end
+
+#####affine algebras as modules#####
+
+@doc raw"""
+    quotient_ring_as_module(A::MPolyQuoRing)
+
+Return `A` considered as an object of type `SubquoModule`.
+
+    quotient_ring_as_module(I::MPolyIdeal)
+
+As above, where `A` is the quotient of `base_ring(I)` modulo `I`.
+
+# Examples
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]);
+
+julia> I = ideal(R, [x^2, y^3])
+ideal(x^2, y^3)
+
+julia> quotient_ring_as_module(I)
+Subquotient of Submodule with 1 generator
+1 -> e[1]
+by Submodule with 2 generators
+1 -> x^2*e[1]
+2 -> y^3*e[1]
+```
+```jldoctest
+julia> S, (x, y) = graded_polynomial_ring(QQ, ["x", "y"]);
+
+julia> I = ideal(S, [x^2, y^3])
+ideal(x^2, y^3)
+
+julia> quotient_ring_as_module(I)
+Graded subquotient of submodule of S^1 generated by
+1 -> e[1]
+by submodule of S^1 generated by
+1 -> x^2*e[1]
+2 -> y^3*e[1]
+
+```
+"""
+function quotient_ring_as_module(A::MPolyQuoRing)
+  I = modulus(A)
+  return quotient_ring_as_module(I)
+end
+
+function quotient_ring_as_module(I::MPolyIdeal)
+  R = base_ring(I)
+  if is_graded(R)
+     F = graded_free_module(R, 1)
+  else
+     F = free_module(R, 1)
+  end
+  V = [x*F[1] for x in gens(I)]
+  M, _ = quo(F, V)
+  return M
+end
+
+#####ideals as modules#####
+
+@doc raw"""
+    ideal_as_module(I::MPolyIdeal)
+
+Return `I` considered as an object of type `SubquoModule`.
+
+# Examples
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]);
+
+julia> I = ideal(R, [x^2, y^3])
+ideal(x^2, y^3)
+
+julia> ideal_as_module(I)
+Submodule with 2 generators
+1 -> x^2*e[1]
+2 -> y^3*e[1]
+represented as subquotient with no relations.
+```
+```jldoctest
+julia> S, (x, y) = graded_polynomial_ring(QQ, ["x", "y"]);
+
+julia> I = ideal(S, [x^2, y^3])
+ideal(x^2, y^3)
+
+julia> ideal_as_module(I)
+Graded submodule of S^1
+1 -> x^2*e[1]
+2 -> y^3*e[1]
+represented as subquotient with no relations
+```
+"""
+function ideal_as_module(I::MPolyIdeal)
+  R = base_ring(I)
+  if is_graded(R)
+     F = graded_free_module(R, 1)
+  else
+     F = free_module(R, 1)
+  end
+  V = [x*F[1] for x in gens(I)]
+  M, _ = sub(F, V)
+  return M
+end

src/Rings/mpoly-graded.jl

@@ -2485,8 +2485,8 @@ end
 @doc raw"""
     cm_regularity(I::MPolyIdeal)
 
-Given a (homogeneous) ideal `I` in a standard $\mathbb Z$-graded multivariate polynomial ring,
-return the Castelnuovo-Mumford regularity of I.
+Given a (homogeneous) ideal `I` in a standard $\mathbb Z$-graded multivariate polynomial ring
+with coefficients in a field, return the Castelnuovo-Mumford regularity of I.
  
 # Examples
 ```jldoctest