Betti diagrams in Docu (oscar-system#2688)

docs/doc.main

@@ -132,8 +132,9 @@
 	"CommutativeAlgebra/ModulesOverMultivariateRings/module_operations.md",
 	"CommutativeAlgebra/ModulesOverMultivariateRings/hom_operations.md",
 	"CommutativeAlgebra/ModulesOverMultivariateRings/complexes.md",
-	"CommutativeAlgebra/ModulesOverMultivariateRings/homological_algebra.md",
      ],
+     "CommutativeAlgebra/homological_algebra.md",
+
      "Gröbner/Standard Bases" => [
         "CommutativeAlgebra/GroebnerBases/orderings.md",
         "CommutativeAlgebra/GroebnerBases/groebner_bases.md",

docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/homological_algebra.md → docs/src/CommutativeAlgebra/homological_algebra.md

@@ -8,8 +8,8 @@ end
 # Homological Algebra
 
 Some OSCAR functions which are fundamental to homological algebra such as the `kernel` function
-and basic functions for handling chain and cochain complexes have already been discussed
-in previous sections. Building on these functions, we now introduce further OSCAR functionality
+for module homomorphisms and basic functions for handling chain and cochain complexes are
+discussed in the module section. Building on these functions, we here introduce further OSCAR functionality
 supporting computations in homological algebra.
 
 ## Presentations
@@ -35,6 +35,52 @@ free_resolution(M::SubquoModule{<:MPolyRingElem};
 
 ## Betti Diagrams
 
+Given a $\mathbb Z$-graded multivariate polynomial ring $S$, and given
+a graded free resolution  with finitely generated graded free $S$-modules 
+
+$F_i=\bigoplus_j S(-j) ^{\beta_{ij}},$
+
+the numbers $\beta_{ij}$ are commonly known as the *graded Betti numbers*
+of the resolution. A convenient way of visualizing these numbers is to write a
+*Betti table* as in the example below:
+
+
+```@julia
+       0  1  2  3  
+------------------
+0    : 1  -  -  -  
+1    : -  2  1  -  
+2    : -  2  3  1  
+------------------
+total: 1  4  4  1
+```
+
+A number $i$ in the top row of the table refers to the $i$-th free 
+module $F_i$ of the resolution. More precisely, the column with first 
+entry $i$ lists the number of free generators
+of $F_i$ in different degrees and, in the bottom row,
+the total number of free generators (that is, the rank of
+$F_i$). If $k$ is the first entry of a row containing 
+a number $\beta$ in the column corresponding to $F_i$, 
+then $F_i$ has $\beta$ generators in degree $k+i$. That is,
+for a free module $F_i$ written as a direct sum as above,
+$\beta$ is the number $\beta_{ij}$
+with $j=k+i$. The explicit example table above indicates, for instance, 
+that $F_2$ has one generator in degree 3 and three generators 
+in degree 4. In total, the diagram corresponds to a 
+graded free resolution of type 
+
+$S \leftarrow S(-2)^2\oplus S(-3)^2 \leftarrow S(-3)\oplus S(-4)^3 \leftarrow S(-5) \leftarrow 0.$
+
+
+```@docs
+betti_table(F::FreeResolution)
+```
+
+```@docs
+minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
+```
+
 ```@docs
 cm_regularity(M::ModuleFP)
 ```

src/Modules/ModulesGraded.jl

@@ -1302,6 +1302,34 @@ end
 # Betti table
 ###############################################################################
 
+@doc raw"""
+    betti_table(F::FreeResolution)
+
+Given a $\mathbb Z$-graded free resolution `F`, return the graded Betti numbers 
+of `F` in form of a Betti table.
+
+Alternatively, use `betti`.
+
+# Examples
+```jldoctest
+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])
+ideal(x*z, y*z, w^2*x, w^2*y)
+
+julia> A, _= quo(R, I)
+(Quotient of multivariate polynomial ring by ideal with 4 generators, Map from
+R to A defined by a julia-function with inverse)
+
+julia> FA  = free_resolution(A)
+Free resolution of A
+R^1 <---- R^4 <---- R^4 <---- R^1 <---- 0
+0         1         2         3         4
+
+julia> betti_table(FA);
+
+```
+"""
 function betti_table(F::FreeResolution; project::Union{GrpAbFinGenElem, Nothing} = nothing, reverse_direction::Bool=false)
   generator_count = Dict{Tuple{Int, Any}, Int}()
   C = F.C
@@ -1318,8 +1346,8 @@ function betti_table(F::FreeResolution; project::Union{GrpAbFinGenElem, Nothing}
   return BettiTable(generator_count, project = project, reverse_direction = reverse_direction)
 end
 
-function betti(b::FreeResolution; reverse_direction::Bool = false)
-  return betti_table(b, project = nothing, reverse_direction = reverse_direction)
+function betti(b::FreeResolution; project::Union{GrpAbFinGenElem, Nothing} = nothing, reverse_direction::Bool = false)
+  return betti_table(b; project, reverse_direction)
 end
 
 function as_dictionary(b::BettiTable)
@@ -1933,6 +1961,10 @@ end
 ########################################################################
 
 # TODO: Are the signatures sufficient to assure that the modules are graded?
+
+@doc raw"""
+    minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
+"""
 function minimal_betti_table(M::SubquoModule{T}) where {T<:MPolyDecRingElem}
   return minimal_betti_table(free_resolution(M))
 end

src/Modules/UngradedModules.jl

@@ -4233,7 +4233,7 @@ end
 @doc raw"""
     presentation(F::FreeMod)
 
-Return a free presentation of $F$.
+Return a free presentation of `F`.
 """
 function presentation(F::FreeMod)
   if is_graded(F)
@@ -4250,7 +4250,7 @@ end
 @doc raw"""
     presentation(M::ModuleFP)
 
-Return a free presentation of $M$.
+Return a free presentation of `M`.
 
 # Examples
 ```jldoctest

src/Rings/mpoly-graded.jl

@@ -352,10 +352,17 @@ julia> is_positively_graded(S)
 false
 ```
 """
-function is_positively_graded(R::MPolyDecRing)
+@attr Bool function is_positively_graded(R::MPolyDecRing)
+  @req coefficient_ring(R) isa AbstractAlgebra.Field "The coefficient ring must be a field"
   is_graded(R) || return false
   G = grading_group(R)
   is_free(G) || return false
+  if ngens(G) == rank(G)
+    W = vcat([x.coeff for x = R.d])
+    if is_positive_grading_matrix(W)
+       return true
+    end
+  end
   try 
     homogeneous_component(R, zero(G))
   catch e