Merge pull request #935 from oscar-system/Wolfram

corrections to docu

Author: fingolfin

docs/src/CommutativeAlgebra/affine_algebras.md

@@ -30,9 +30,8 @@ functionality for handling such algebras in OSCAR.
 
 ## Types
 
-!!! note
-    All types for quotient rings of  multivariate polynomial rings belong to the abstract type `MPolyQuo{T}`,
-    irrespective of whether they are graded or not.
+The OSCAR type for quotient rings of  a multivariate polynomial ring -- decorated or not -- is of parametrized form `MPolyQuo{T}`,
+where `T` is the element type of the polynomial ring. In turn, the type for elements of quotient rings is of parametrized form `MPolyQuoElem{T}`.
 
 ## Constructors
 

docs/src/CommutativeAlgebra/ideals.md

@@ -10,16 +10,13 @@ using Oscar
 Pages = ["ideals.md"]
 ```
 
-# Ideals in Polynomial Rings
-
-In this section, we describe functionality for  handling ideals in multivariate polynomial rings.
+# Ideals in Multivariate Rings
 
 ## Types
 
-!!! note
-    Irrespective of whether the rings are graded or not, all types for ideals in multivariate polynomial rings
-    belong to the abstract type `MPolyIdeal{T}` which, in turn,  is a subtype of `Ideal{T}`.
-
+The OSCAR type for ideals in multivariate polynomial rings -- decorated or not --
+is of parametrized form `MPolyIdeal{T}`, where `T` is the element type of the
+polynomial ring.
 
 ## Constructors
 
@@ -30,8 +27,8 @@ ideal(g::Vector{T}) where {T <: MPolyElem}
 ## Gröbner Bases
 
 Algorithmic means to deal with ideals in multivariate polynomial rings are provided by
-the concept of Gröbner bases and its workhorse, Buchberger's algorithm for computing
-such bases. For both the concept and the algorithm a convenient way of ordering the monomials
+the concept of Gröbner bases and the workhorse of this concept, Buchberger's algorithm for computing
+Gröbner bases. For both the concept and the algorithm a convenient way of ordering the monomials
 appearing in multivariate polynomials and, thus, to distinguish leading terms of such
 polynomials is needed.
 
@@ -326,7 +323,7 @@ saturation_with_index(I::MPolyIdeal{T}, J::MPolyIdeal{T}) where T
 ### Elimination
 
 ```@docs
-eliminate(I::MPolyIdeal{T}, l::Vector{T}) where T <: Union{MPolyElem, MPolyElem_dec}
+eliminate(I::MPolyIdeal{T}, l::Vector{T}) where T <: MPolyElem
 ```
 
 ## Tests on Ideals
@@ -353,13 +350,13 @@ issubset(I::MPolyIdeal{T}, J::MPolyIdeal{T}) where T
 ### Ideal Membership
 
 ```@docs
-ideal_membership(f::T, I::MPolyIdeal{T}) where T <: Union{MPolyElem, MPolyElem_dec}
+ideal_membership(f::T, I::MPolyIdeal{T}) where T
 ```
 
 ### Radical Membership
 
 ```@docs
-radical_membership(f::T, I::MPolyIdeal{T}) where T <: Union{MPolyElem, MPolyElem_dec}
+radical_membership(f::T, I::MPolyIdeal{T}) where T
 ```
 
 ### Primality Test

docs/src/CommutativeAlgebra/rings.md

@@ -10,36 +10,50 @@ using Oscar
 Pages = ["rings.md"]
 ```
 
-# Creating Polynomial Rings
+# Creating Multivariate Rings
 
-Referring to the corrresponding section of the ring chapter for details, we recall how to create
-multivariate polynomial rings and their elements. We also show how to assign gradings to these rings.
-Homomorphisms of multivariate polynomial rings are described in a more general context in the section on affine algebras. 
+Referring to the rings and fields chapters for more details, our focus in this section is on examples
+which illustrate how to create multivariate polynomial rings and their elements. Of particular
+interest to us is the introduction of decorated ring types which allow one to implement multivariate
+polynomial rings with gradings and/or filtrations.
 
 ## Types
 
-!!! note
-    All types for multivariate polynomial rings belong to the abstract type
-    `MPolyRing{T}`, irrespective of whether they are graded or not. In contrast, the types for univariate polynomial rings belong to `PolyRing{T}`.
-	The elements of these rings are stored in a sparse and dense format,  respectively.
+OSCAR provides types for dense univariate and sparse multivariate polynomials. The univariate
+ring types belong to the abstract type `PolyRing{T}`, their elements have abstract type
+`PolyRingElem{T}`. The multivariate ring types belong to the abstract type `MPolyRing{T}`,
+their elements have abstract type `MPolyRingElem{T}`. Here, `T` is the element type
+of the coefficient ring of the polynomial ring.
+
+Multivariate rings with gradings and/or filtrations are modelled by objects of type
+`MPolyRing_dec{T, S}  :< MPolyRing{T}`, with elements of type
+`MPolyRingElem_dec{T, S}  :< MPolyRingElem{T}`. Here, `S` is the element type of the
+multivariate ring, and  `T` is the element type of its coefficient ring as above.
 
 ## Constructors
 
-The standard constructor below allows one to build multivariate polynomial rings:
+The basic constructor below allows one to build multivariate polynomial rings:
 
 ```@julia
-PolynomialRing(C::Ring, v::Vector{String}; ordering=:lex)
+PolynomialRing(C::Ring, v::Vector{String}; ordering=:lex, cached = true)
 ```
 
 Its return value is a tuple, say `R, vars`, consisting of a polynomial ring `R` with coefficient ring `C` and a vector `vars` of generators (variables) which print according to the strings in the vector `v` .
 The input `ordering=:lex` refers to the lexicograpical monomial ordering which specifies the default way of storing and displaying polynomials in OSCAR  (terms are sorted in descending
 order). The other possible choices are `:deglex` and `:degrevlex`. Gröbner bases, however, can be computed with respect to any monomial ordering. See the section on Gröbner bases.
 
-
-
+!!! note
+    Caching is used to ensure that a given ring constructed from given parameters is unique in the system. For example, there is only one ring of multivariate polynomials over  $\mathbb{Z}$ in the variables x, y, z with `ordering=:lex`.
 
 ###### Examples
 
+```@repl oscar
+R, (x, y, z) = PolynomialRing(ZZ, ["x", "y", "z"])
+typeof(R)
+typeof(x)
+S, (x, y, z) = PolynomialRing(ZZ, ["x", "y", "z"])
+R === S
+```
 
 ```@repl oscar
 R1, x = PolynomialRing(QQ, ["x"])
@@ -50,12 +64,6 @@ R3, x = PolynomialRing(QQ, "x")
 typeof(x)
 ```
 
-```@repl oscar
-R, (x, y, z) = PolynomialRing(ZZ, ["x", "y", "z"])
-typeof(R)
-typeof(x)
-```
-
 ```@repl oscar
 V = ["x[1]", "x[2]"]
 T, x = PolynomialRing(GF(3), V)
@@ -120,14 +128,29 @@ QT = FractionField(T)
 ZZ
 ```
 
-## Data Associated to Polynomial Rings
+## Gradings and Filtrations
+
+The following functions implement multivariate polynomial rings decorated with $\mathbb Z$-gradings by (weighted) degree:
+
+```@docs
+grade(R::MPolyRing, W::Vector{Int})
+```
+
+```@docs
+GradedPolynomialRing(C::Ring, V::Vector{String}, W::Vector{Int}; ordering=:lex)
+```
+
+!!! note
+    OSCAR functionality for working with gradings by arbitrary abelian groups and for working with filtrations is currently under development.
+
+## Data Associated to Multivariate Rings
 
-If `R` is  a multivariate polynomial ring `R` with coefficient ring `C`, then
+If `R` is  a multivariate polynomial ring with coefficient ring `C`, then
 
 - `base_ring(R)` refers to `C`,
 - `gens(R)` to the generators (variables) of `R`,
 - `ngens(R)` to the number of these generators, and
-- `gen(R, i)` as well as `R[i]` to the `i`th generator.
+- `gen(R, i)` as well as `R[i]` to the `i`-th generator.
 
 ###### Examples
 
@@ -140,12 +163,9 @@ R[3]
 ngens(R)
 ```
 
-## Elements of Polynomial Rings
-
-!!! note
-    The types for multivariate polynomials belong to the abstract type `MPolyElem{T}`.
+## Elements of Multivariate Rings
 
-One way to construct elements of a multivariate  polynomial ring `R` is
+One way to create elements of a multivariate  polynomial ring, `R`, is
 to build up polynomials from the generators (variables) of `R` using
 basic arithmetic as shown below:
 
@@ -157,6 +177,12 @@ f = 3*x^2+y*z
 typeof(f)
 ```
 
+```@repl oscar
+R, (x, y, z) = GradedPolynomialRing(QQ, ["x", "y", "z"])
+f = 3*x^2+y*z
+typeof(f)
+```
+
 Alternatively, there is the following constructor:
 
 ```@julia
@@ -170,11 +196,15 @@ with exponent vectors given by the elements of `e`.
 
 ```@repl oscar
 R, (x, y, z) = PolynomialRing(QQ, ["x", "y", "z"])
-f = R(QQ.([3, 1]), [[2, 0, 0], [0, 1, 1]])
-QQ.([3, 1]) == map(QQ, [3, 1]) 
+f = 3*x^2+y*z
+g = R(QQ.([3, 1]), [[2, 0, 0], [0, 1, 1]])
+f == g
 ```
 
-If an element `f` of `R` has been constructed, then
+!!! note
+    An often more effective way to create polynomials is to use the `MPoly` build context, see the chapter on rings.
+
+Given an element `f` of a multivariate polynomial ring `R`,
 - `parent(f)` refers to `R`,
 - `monomial(f, i)` to the `i`-th monomial of `f`, 
 - `term(f, i)` to the `i`-th term of `f`,
@@ -196,28 +226,7 @@ monomial(f, 2)
 term(f, 2)
 ```
 
-!!! note
-    An often more effective way to construct polynomials  is to use the `MPoly` build context as explained in the chapter on rings.
-
-
-## Gradings
-
-The following functions allow one to assign gradings to multivariate polynomial rings:
-
-```@docs
-grade(R::MPolyRing, W::Vector{Int})
-```
-
-More directly, graded polynomial rings can be constructed as follows:
-
-```@docs
-GradedPolynomialRing(C::Ring, V::Vector{String}, W::Vector{Int}; ordering=:lex)
-```
-
-!!! note
-    OSCAR functionality for working with gradings by arbitrary abelian groups is currently under development.
-
-## Homomorphisms of Polynomial Rings
+## Homomorphisms of Multivariate Rings
 
-How to handle homomorphisms of multivariate polynomial rings is described in
+How to handle homomorphisms of multivariate polynomial rings and their decorated types is described in
 a more general context in the section on affine algebras. 

src/Rings/mpoly-graded.jl

@@ -133,6 +133,12 @@ julia> R, (x, y, z) = GradedPolynomialRing(QQ, ["x", "y", "z"], [1, 2, 3])
   x -> [1]
   y -> [2]
   z -> [3], MPolyElem_dec{fmpq, fmpq_mpoly}[x, y, z])
+
+julia> S, (x, y, z) = GradedPolynomialRing(QQ, ["x", "y", "z"])
+(Multivariate Polynomial Ring in x, y, z over Rational Field graded by 
+  x -> [1]
+  y -> [1]
+  z -> [1], MPolyElem_dec{fmpq, fmpq_mpoly}[x, y, z])
 ```
 """
 function GradedPolynomialRing(C::Ring, V::Vector{String}, W::Vector{Int}; ordering=:lex)
@@ -411,8 +417,6 @@ end
     ishomogeneous(F::MPolyElem_dec)
 
 Return `true` if `F` is homogeneous, `false` otherwise.
-
-Return the homogenization of `f`, `V`, or `I` in a graded ring with additional variable `var` at position `pos`.
 """
 function ishomogeneous(F::MPolyElem_dec)
   D = parent(F).D
@@ -758,7 +762,8 @@ end
 
     homogenization(I::MPolyIdeal{T}, var::String, pos::Int = 1; ordering::Symbol = :degrevlex) where {T <: MPolyElem}
 
-Return the homogenization of `f`, `V`, or `I` in a graded ring with additional variable `var` at position `pos`.
+Homogenize `f`, `V`, or `I` using an additional variable printing as `var`.
+Return the result as an element of a graded polynomial ring with an additional variable at position `pos` printing as `var`.
 
 !!! warning
     Homogenizing an ideal requires a Gröbner basis computation. This may take some time.
@@ -809,7 +814,8 @@ end
 
     dehomogenization(I::MPolyIdeal{T}, pos::Int) where {T <: MPolyElem_dec}
 
-Return the dehomogenization of `F`, `V`, or `I` in a ring not depending on the variable at position `pos`.
+Dehomogenize `F`, `V`, or `I` using the variable at position `pos`. 
+Return the result as an element of a polynomial ring not depending on the variable at position `pos`.
 """
 function dehomogenization(F::MPolyElem_dec, pos::Int)
   S = parent(F)