Skip to content

Commit

Permalink
Move a bunch of examples into docstring
Browse files Browse the repository at this point in the history 
This way they are also helpful for users of the REPL help
  • Loading branch information
@fingolfin
fingolfin committed Nov 4, 2023
1 parent 6304657 commit 11e4fd4
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 127 deletions.
127 changes: 0 additions & 127 deletions docs/src/ideal.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
119 changes: 119 additions & 0 deletions src/ideal/ideal.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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}}}
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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}}}
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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}}}
Expand Down

0 comments on commit 11e4fd4

Please sign in to comment.