From 11e4fd49ded70543448e79538cae9c1b4386a704 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Sat, 4 Nov 2023 20:06:37 +0100 Subject: [PATCH] Move a bunch of examples into docstring This way they are also helpful for users of the REPL help --- docs/src/ideal.md | 127 --------------------------------------------- src/ideal/ideal.jl | 119 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 127 deletions(-) diff --git a/docs/src/ideal.md b/docs/src/ideal.md index 3d32fbbf2..2d85f0ceb 100644 --- a/docs/src/ideal.md +++ b/docs/src/ideal.md @@ -163,22 +163,6 @@ true contains{T <: AbstractAlgebra.RingElem}(::sideal{T}, ::sideal{T}) ``` -**Examples** - -```jldoctest -julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, x^2 + 1, x*y) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) - -julia> J = Ideal(R, x^2 + 1) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1) - -julia> contains(I, J) == true -true -``` - ### Comparison Checking whether two ideals are algebraically equal is very expensive, as it usually @@ -218,22 +202,6 @@ true intersection(I::sideal{S}, J::sideal{S}) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} ``` -**Examples** - -```jldoctest -julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, x^2 + 1, x*y) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) - -julia> J = Ideal(R, x^2 + x*y + 1, x^2 - x*y + 1) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + x*y + 1, x^2 - x*y + 1) - -julia> V = intersection(I, J) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (y, x^2 - x*y + 1) -``` - ### Quotient ```@docs @@ -244,41 +212,12 @@ quotient(I::sideal{S}, J::sideal{S}) where S <: spoly quotient(I::sideal{S}, J::sideal{S}) where S <: spluralg ``` -**Examples** - -```jldoctest -julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, x^2 + 1, x*y) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) - -julia> J = Ideal(R, x + y) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x + y) - -julia> V = quotient(I, J) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (y, x^2 + 1) -``` - ### Leading terms ```@docs lead(I::sideal{S}) where S <: SPolyUnion ``` -**Examples** - -```jldoctest -julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, x^2 + 1, x*y) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) - -julia> V = lead(I) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2, x*y) -``` - ### Homogeneous ideals ```@docs @@ -295,22 +234,6 @@ homogenize(I::sideal{S}, v::S) where S <: spoly saturation(I::sideal{T}, J::sideal{T}) where T <: Nemo.RingElem ``` -**Examples** - -```jldoctest -julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, (x^2 + x*y + 1)*(2y^2+1)^3, (2y^2 + 3)*(2y^2+1)^2) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (8*x^2*y^6 + 8*x*y^7 + 12*x^2*y^4 + 12*x*y^5 + 8*y^6 + 6*x^2*y^2 + 6*x*y^3 + 12*y^4 + x^2 + x*y + 6*y^2 + 1, 8*y^6 + 20*y^4 + 14*y^2 + 3) - -julia> J = Ideal(R, 2y^2 + 1) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (2*y^2 + 1) - -julia> S = saturation(I, J) -(Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (2*y^2 + 3, x^2 + x*y + 1), 2) -``` - ### Standard basis ```@docs @@ -414,49 +337,12 @@ x + 1 eliminate(I::sideal{S}, polys::S...) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} ``` -**Examples** - -```jldoctest -julia> R, (x, y, t) = polynomial_ring(QQ, ["x", "y", "t"]) -(Singular polynomial ring (QQ),(x,y,t),(dp(3),C), spoly{n_Q}[x, y, t]) - -julia> I = Ideal(R, x - t^2, y - t^3) -Singular ideal over Singular polynomial ring (QQ),(x,y,t),(dp(3),C) with generators (-t^2 + x, -t^3 + y) - -julia> J = eliminate(I, t) -Singular ideal over Singular polynomial ring (QQ),(x,y,t),(dp(3),C) with generators (x^3 - y^2) -``` - ### Syzygies ```@docs syz(::sideal) ``` -**Examples** - -```jldoctest -julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]) -(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) - -julia> I = Ideal(R, x^2*y + 2y + 1, y^2 + 1) -Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2*y + 2*y + 1, y^2 + 1) - -julia> F = syz(I) -Singular Module over Singular polynomial ring (QQ),(x,y),(dp(2),C), with Generators: -x^2*y*gen(2)-y^2*gen(1)+2*y*gen(2)+gen(2)-gen(1) - -julia> M = Singular.Matrix(I) -[x^2*y + 2*y + 1, y^2 + 1] - -julia> N = Singular.Matrix(F) -[-y^2 - 1 -x^2*y + 2*y + 1] - -julia> iszero(M*N) # check they are actually syzygies -true -``` - ### Free resolutions ```@docs @@ -491,19 +377,6 @@ R^1 <- R^2 <- R^1 jet(I::sideal{S}, n::Int) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} ``` -**Examples** - -```jldoctest -julia> R, (x, y, z) = polynomial_ring(QQ, ["x", "y", "z"]) -(Singular polynomial ring (QQ),(x,y,z),(dp(3),C), spoly{n_Q}[x, y, z]) - -julia> I = Ideal(R, x^5 - y^2, y^3 - x^6 + z^3) -Singular ideal over Singular polynomial ring (QQ),(x,y,z),(dp(3),C) with generators (x^5 - y^2, -x^6 + y^3 + z^3) - -julia> J1 = jet(I, 3) -Singular ideal over Singular polynomial ring (QQ),(x,y,z),(dp(3),C) with generators (-y^2, y^3 + z^3) -``` - ### Operations on zero-dimensional ideals ```@docs diff --git a/src/ideal/ideal.jl b/src/ideal/ideal.jl index 359bea0b2..46c99305a 100644 --- a/src/ideal/ideal.jl +++ b/src/ideal/ideal.jl @@ -380,6 +380,21 @@ end Return `true` if the ideal $I$ contains the ideal $J$. This will be expensive if $I$ is not a Groebner ideal, since its standard basis must be computed. + +# Examples +```jldoctest +julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, x^2 + 1, x*y) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) + +julia> J = Ideal(R, x^2 + 1) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1) + +julia> contains(I, J) == true +true +``` """ function contains(I::sideal{S}, J::sideal{S}) where S check_parent(I, J) @@ -440,6 +455,18 @@ end Return the ideal generated by the leading terms of the polynomials generating $I$. + +# Examples +```jldoctest +julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, x^2 + 1, x*y) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) + +julia> V = lead(I) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2, x*y) +``` """ function lead(I::sideal{S}) where S <: SPolyUnion R = base_ring(I) @@ -457,6 +484,21 @@ end intersection(I::sideal{S}, J::sideal{S}) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} Return the intersection of the two given ideals. + +# Examples +```jldoctest +julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, x^2 + 1, x*y) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) + +julia> J = Ideal(R, x^2 + x*y + 1, x^2 - x*y + 1) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + x*y + 1, x^2 - x*y + 1) + +julia> V = intersection(I, J) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (y, x^2 - x*y + 1) +``` """ function intersection(I::sideal{S}, J::sideal{S}) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} @@ -495,6 +537,21 @@ end Return the quotient of the two given ideals. Recall that the ideal quotient $(I:J)$ over a polynomial ring $R$ is defined by $\{r \in R \;|\; rJ \subseteq I\}$. + +# Examples +```jldoctest +julia> R, (x , y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, x^2 + 1, x*y) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2 + 1, x*y) + +julia> J = Ideal(R, x + y) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x + y) + +julia> V = quotient(I, J) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (y, x^2 + 1) +``` """ function quotient(I::sideal{S}, J::sideal{S}) where S <: spoly check_parent(I, J) @@ -527,6 +584,21 @@ end Return the saturation of the ideal $I$ with respect to $J$, i.e. returns the quotient ideal $(I:J^\infty)$ and the number of iterations. + +# Examples +```jldoctest +julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, (x^2 + x*y + 1)*(2y^2+1)^3, (2y^2 + 3)*(2y^2+1)^2) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (8*x^2*y^6 + 8*x*y^7 + 12*x^2*y^4 + 12*x*y^5 + 8*y^6 + 6*x^2*y^2 + 6*x*y^3 + 12*y^4 + x^2 + x*y + 6*y^2 + 1, 8*y^6 + 20*y^4 + 14*y^2 + 3) + +julia> J = Ideal(R, 2y^2 + 1) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (2*y^2 + 1) + +julia> S = saturation(I, J) +(Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (2*y^2 + 3, x^2 + x*y + 1), 2) +``` """ function saturation(I::sideal{T}, J::sideal{T}) where T <: Nemo.RingElem check_parent(I, J) @@ -782,6 +854,18 @@ end Given a list of polynomials which are variables, construct the ideal corresponding geometrically to the projection of the variety given by the ideal $I$ where those variables have been eliminated. + +# Examples +```jldoctest +julia> R, (x, y, t) = polynomial_ring(QQ, ["x", "y", "t"]) +(Singular polynomial ring (QQ),(x,y,t),(dp(3),C), spoly{n_Q}[x, y, t]) + +julia> I = Ideal(R, x - t^2, y - t^3) +Singular ideal over Singular polynomial ring (QQ),(x,y,t),(dp(3),C) with generators (-t^2 + x, -t^3 + y) + +julia> J = eliminate(I, t) +Singular ideal over Singular polynomial ring (QQ),(x,y,t),(dp(3),C) with generators (x^3 - y^2) +``` """ function eliminate(I::sideal{S}, polys::S...) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}} @@ -821,6 +905,29 @@ end syz(I::sideal) Compute the module of syzygies of the ideal. + +# Examples +```jldoctest +julia> R, (x, y) = polynomial_ring(QQ, ["x", "y"]) +(Singular polynomial ring (QQ),(x,y),(dp(2),C), spoly{n_Q}[x, y]) + +julia> I = Ideal(R, x^2*y + 2y + 1, y^2 + 1) +Singular ideal over Singular polynomial ring (QQ),(x,y),(dp(2),C) with generators (x^2*y + 2*y + 1, y^2 + 1) + +julia> F = syz(I) +Singular Module over Singular polynomial ring (QQ),(x,y),(dp(2),C), with Generators: +x^2*y*gen(2)-y^2*gen(1)+2*y*gen(2)+gen(2)-gen(1) + +julia> M = Singular.Matrix(I) +[x^2*y + 2*y + 1, y^2 + 1] + +julia> N = Singular.Matrix(F) +[-y^2 - 1 +x^2*y + 2*y + 1] + +julia> iszero(M*N) # check they are actually syzygies +true +``` """ function syz(I::sideal) R = base_ring(I) @@ -1095,6 +1202,18 @@ end Given an ideal $I$ this function truncates the generators of $I$ up to degree $n$. + +# Examples +```jldoctest +julia> R, (x, y, z) = polynomial_ring(QQ, ["x", "y", "z"]) +(Singular polynomial ring (QQ),(x,y,z),(dp(3),C), spoly{n_Q}[x, y, z]) + +julia> I = Ideal(R, x^5 - y^2, y^3 - x^6 + z^3) +Singular ideal over Singular polynomial ring (QQ),(x,y,z),(dp(3),C) with generators (x^5 - y^2, -x^6 + y^3 + z^3) + +julia> J1 = jet(I, 3) +Singular ideal over Singular polynomial ring (QQ),(x,y,z),(dp(3),C) with generators (-y^2, y^3 + z^3) +``` """ function jet(I::sideal{S}, n::Int) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}}