From 746ec2b51c2a7f2a250af9cb332abc6b4ce0852f Mon Sep 17 00:00:00 2001 From: John Abbott Date: Fri, 10 Oct 2025 15:26:02 +0200 Subject: [PATCH 1/2] Condense doc for is_square into single docstring --- src/AbsSeries.jl | 1 + src/Fraction.jl | 6 +----- src/MatRing.jl | 1 + src/NCRings.jl | 11 +++++++++++ src/Poly.jl | 6 +----- src/RelSeries.jl | 1 + src/ResidueField.jl | 6 +----- src/generic/LaurentSeries.jl | 1 + src/generic/MPoly.jl | 1 + src/generic/Matrix.jl | 1 + src/generic/PuiseuxSeries.jl | 1 + src/generic/RationalFunctionField.jl | 6 +----- src/generic/UnivPoly.jl | 1 + src/julia/Float.jl | 5 +++-- src/julia/GF.jl | 1 + src/julia/Integer.jl | 7 ++----- src/julia/Rational.jl | 1 + 17 files changed, 30 insertions(+), 27 deletions(-) diff --git a/src/AbsSeries.jl b/src/AbsSeries.jl index d875c5e409..d774fdef52 100644 --- a/src/AbsSeries.jl +++ b/src/AbsSeries.jl @@ -920,6 +920,7 @@ function Base.sqrt(a::AbsPowerSeriesRingElem; check::Bool=true) return q end +# See generic documentation in NCRings.jl function is_square(a::AbsPowerSeriesRingElem) flag, q = sqrt_classical(a; check=true) return flag diff --git a/src/Fraction.jl b/src/Fraction.jl index 12f2a7cc81..815f8df532 100644 --- a/src/Fraction.jl +++ b/src/Fraction.jl @@ -693,11 +693,7 @@ end # ############################################################################### -@doc raw""" - is_square(a::FracElem{T}) where T <: RingElem - -Return `true` if $a$ is a square. -""" +# See generic documentation in NCRings.jl function is_square(a::FracElem{T}) where T <: RingElem return is_square(numerator(a)) && is_square(denominator(a)) end diff --git a/src/MatRing.jl b/src/MatRing.jl index faf2feacb6..eb0e22410d 100644 --- a/src/MatRing.jl +++ b/src/MatRing.jl @@ -152,6 +152,7 @@ end # ################################################################################ +# See generic documentation in NCRings.jl is_square(a::MatRingElem) = true ############################################################################### diff --git a/src/NCRings.jl b/src/NCRings.jl index c8c7219275..ef2395dfd0 100644 --- a/src/NCRings.jl +++ b/src/NCRings.jl @@ -176,6 +176,17 @@ function is_nilpotent(a::T) where {T <: NCRingElement} end +@doc raw""" + is_square(a::T) where {T <: NCRingElement} + is_square(M::MatElem) + is_square(M::MatRingElem) + +There are two distinct situations: +(1) if the argument is matrix then check whether the matrix **shape** is square +(2) if the argument is not a matrix then check whether the **value** is a square (in the same ring) +""" +function is_square end + ############################################################################### # # Characteristic diff --git a/src/Poly.jl b/src/Poly.jl index d7e62e8cf1..7dd3364524 100644 --- a/src/Poly.jl +++ b/src/Poly.jl @@ -1837,11 +1837,7 @@ function Base.sqrt(f::PolyRingElem{T}; check::Bool=true) where T <: RingElement return q end -@doc raw""" - is_square(f::PolyRingElem{T}) where T <: RingElement - -Return `true` if $f$ is a perfect square. -""" +# See generic documentation in NCRings.jl function is_square(f::PolyRingElem{T}) where T <: RingElement flag, q = sqrt_classical(f) return flag diff --git a/src/RelSeries.jl b/src/RelSeries.jl index fd9370a060..5b1fe04414 100644 --- a/src/RelSeries.jl +++ b/src/RelSeries.jl @@ -1187,6 +1187,7 @@ function Base.sqrt(a::RelPowerSeriesRingElem; check::Bool=true) return q end +# See generic documentation in NCRings.jl function is_square(a::RelPowerSeriesRingElem) flag, q = sqrt_classical(a; check=true) return flag diff --git a/src/ResidueField.jl b/src/ResidueField.jl index 3a6b54bc77..fc0b62ef12 100644 --- a/src/ResidueField.jl +++ b/src/ResidueField.jl @@ -340,11 +340,7 @@ end # ############################################################################### -@doc raw""" - is_square(a::ResFieldElem{T}) where T <: Integer - -Return `true` if $a$ is a square. -""" +# See generic documentation in NCRings.jl function is_square(a::ResFieldElem{T}) where T <: Integer if iszero(a) return true diff --git a/src/generic/LaurentSeries.jl b/src/generic/LaurentSeries.jl index ff51d6031e..bd0f8aba89 100644 --- a/src/generic/LaurentSeries.jl +++ b/src/generic/LaurentSeries.jl @@ -1408,6 +1408,7 @@ function Base.sqrt(a::LaurentSeriesElem; check::Bool=true) return s end +# See generic documentation in NCRings.jl function is_square(a::LaurentSeriesElem) flag, q = sqrt_classical(a; check=true) return flag diff --git a/src/generic/MPoly.jl b/src/generic/MPoly.jl index 29a5b337da..9dfdd3169c 100644 --- a/src/generic/MPoly.jl +++ b/src/generic/MPoly.jl @@ -1872,6 +1872,7 @@ function Base.sqrt(a::MPoly{T}; check::Bool=true) where {T <: RingElement} return q end +# See generic documentation in NCRings.jl function is_square(a::MPoly{T}) where {T <: RingElement} flag, q = sqrt_heap(a; check=true) return flag diff --git a/src/generic/Matrix.jl b/src/generic/Matrix.jl index db4089a490..946f2e6f7c 100644 --- a/src/generic/Matrix.jl +++ b/src/generic/Matrix.jl @@ -101,6 +101,7 @@ end # ################################################################################ +# See generic documentation in NCRings.jl is_square(a::MatElem) = (nrows(a) == ncols(a)) ############################################################################### diff --git a/src/generic/PuiseuxSeries.jl b/src/generic/PuiseuxSeries.jl index 6e71d2fe78..f5d0568d47 100644 --- a/src/generic/PuiseuxSeries.jl +++ b/src/generic/PuiseuxSeries.jl @@ -626,6 +626,7 @@ function Base.sqrt(a::PuiseuxSeriesElem{T}; check::Bool=true) where T <: RingEle return s end +# See generic documentation in NCRings.jl function is_square(a::PuiseuxSeriesElem{T}) where T <: RingElement flag, s = sqrt_classical(a; check=true) return flag diff --git a/src/generic/RationalFunctionField.jl b/src/generic/RationalFunctionField.jl index 52ec32715c..36f553bc8d 100644 --- a/src/generic/RationalFunctionField.jl +++ b/src/generic/RationalFunctionField.jl @@ -451,11 +451,7 @@ end # ############################################################################### -@doc raw""" - is_square(a::RationalFunctionFieldElem) - -Return `true` if $a$ is a square. -""" +# See generic documentation in NCRings.jl function is_square(a::RationalFunctionFieldElem) return is_square(data(a)) end diff --git a/src/generic/UnivPoly.jl b/src/generic/UnivPoly.jl index 391b2ebe40..49fd699b62 100644 --- a/src/generic/UnivPoly.jl +++ b/src/generic/UnivPoly.jl @@ -534,6 +534,7 @@ function Base.sqrt(p::UnivPoly{T}; check::Bool=true) where {T} return UnivPoly{T}(s, S) end +# See generic documentation in NCRings.jl function is_square(p::UnivPoly) return is_square(data(p)) end diff --git a/src/julia/Float.jl b/src/julia/Float.jl index 8da9cdbfe2..432e4533da 100644 --- a/src/julia/Float.jl +++ b/src/julia/Float.jl @@ -143,12 +143,13 @@ function Base.sqrt(a::AbstractFloat; check::Bool=true) return Base.sqrt(a) end +# See generic documentation in NCRings.jl function is_square(a::AbstractFloat) - return a > 0 + return a >= 0 end function is_square_with_sqrt(a::T) where T <: AbstractFloat - if a > 0 + if a >= 0 return true, Base.sqrt(a) else return false, zero(T) diff --git a/src/julia/GF.jl b/src/julia/GF.jl index 2d47f54a10..80c64ae233 100644 --- a/src/julia/GF.jl +++ b/src/julia/GF.jl @@ -332,6 +332,7 @@ function Base.sqrt(a::GFElem{T}; check::Bool=true) where T <: Integer return s1 end +# See generic documentation in NCRings.jl function is_square(a::GFElem{T}) where T <: Integer f1, s1 = sqrt_tonelli_shanks(a; check=true) return f1 diff --git a/src/julia/Integer.jl b/src/julia/Integer.jl index e43327c39e..59d7574e8a 100644 --- a/src/julia/Integer.jl +++ b/src/julia/Integer.jl @@ -311,11 +311,7 @@ function is_square_with_sqrt(a::BigInt) end end -@doc raw""" - is_square(a::T) where T <: Integer - -Return true if $a$ is a square. -""" +# See generic documentation in NCRings.jl function is_square(a::T) where T <: Integer if a < 0 return false @@ -324,6 +320,7 @@ function is_square(a::T) where T <: Integer return a == s*s end +# See generic documentation in NCRings.jl function is_square(a::BigInt) if a < 0 return false diff --git a/src/julia/Rational.jl b/src/julia/Rational.jl index 81a327eb26..3e9723fa2b 100644 --- a/src/julia/Rational.jl +++ b/src/julia/Rational.jl @@ -132,6 +132,7 @@ function sqrt(a::Rational{T}; check::Bool=true) where T <: Integer return sqrt(numerator(a, false); check=check)//sqrt(denominator(a, false); check=check) end +# See generic documentation in NCRings.jl function is_square(a::Rational{T}) where T <: Integer return is_square(numerator(a)) && is_square(denominator(a)) end From ddd73004d0b439897ca0733b54068f68bb2ca7c7 Mon Sep 17 00:00:00 2001 From: John Abbott Date: Wed, 15 Oct 2025 14:20:40 +0200 Subject: [PATCH 2/2] Added test for is_square of float zero; removed some docblocks from md files --- docs/src/fraction.md | 4 ---- docs/src/function_field.md | 4 ---- docs/src/integer.md | 1 - docs/src/polynomial.md | 4 ---- docs/src/residue.md | 4 ---- src/NCRings.jl | 7 ++----- src/generic/Matrix.jl | 7 +++++++ test/julia/Floats-test.jl | 17 +++++++++++++++-- 8 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/src/fraction.md b/docs/src/fraction.md index fffeec2c87..67a08d15bd 100644 --- a/docs/src/fraction.md +++ b/docs/src/fraction.md @@ -301,10 +301,6 @@ julia> h = gcd(f, g) ### Square root -```@docs -is_square{T <: RingElem}(::FracElem{T}) -``` - ```@docs Base.sqrt(::FracElem{T}) where {T <: RingElem} ``` diff --git a/docs/src/function_field.md b/docs/src/function_field.md index 06492a9a37..9d4a015a2e 100644 --- a/docs/src/function_field.md +++ b/docs/src/function_field.md @@ -162,10 +162,6 @@ julia> h = gcd(f, g) ### Square root -```@docs -is_square(::Generic.RationalFunctionFieldElem{T, U}) where {T <: FieldElem, U <: Union{PolyRingElem, MPolyRingElem}} -``` - ```@docs Base.sqrt(::Generic.RationalFunctionFieldElem{T, U}) where {T <: FieldElem, U <: Union{PolyRingElem, MPolyRingElem}} ``` diff --git a/docs/src/integer.md b/docs/src/integer.md index ab66394611..fab00ce290 100644 --- a/docs/src/integer.md +++ b/docs/src/integer.md @@ -166,7 +166,6 @@ AbstractAlgebra.sqrt(a::BigInt) ``` ```@docs -is_square(a::BigInt) is_square_with_sqrt(a::BigInt) ``` diff --git a/docs/src/polynomial.md b/docs/src/polynomial.md index 4c77a6a768..5609d909ee 100644 --- a/docs/src/polynomial.md +++ b/docs/src/polynomial.md @@ -405,10 +405,6 @@ is_gen(::PolyRingElem) is_monic(::PolyRingElem) ``` -```@docs -is_square(::PolyRingElem) -``` - ```@docs length(::PolynomialElem) ``` diff --git a/docs/src/residue.md b/docs/src/residue.md index a5ac8eec04..842faefd64 100644 --- a/docs/src/residue.md +++ b/docs/src/residue.md @@ -264,10 +264,6 @@ julia> h = gcd(f, g) ### Square Root -```@docs -is_square{T <: Integer}(::ResFieldElem{T}) -``` - ```@docs Base.sqrt{T <: Integer}(::ResFieldElem{T}) ``` diff --git a/src/NCRings.jl b/src/NCRings.jl index ef2395dfd0..f9feafac7b 100644 --- a/src/NCRings.jl +++ b/src/NCRings.jl @@ -178,12 +178,9 @@ end @doc raw""" is_square(a::T) where {T <: NCRingElement} - is_square(M::MatElem) - is_square(M::MatRingElem) -There are two distinct situations: -(1) if the argument is matrix then check whether the matrix **shape** is square -(2) if the argument is not a matrix then check whether the **value** is a square (in the same ring) +Return `true` iff `a` is the square of a value in its own ring. +See also `is_square(M::MatElem)` which tests whether a matrix has square shape. """ function is_square end diff --git a/src/generic/Matrix.jl b/src/generic/Matrix.jl index 946f2e6f7c..f91b211c1c 100644 --- a/src/generic/Matrix.jl +++ b/src/generic/Matrix.jl @@ -101,6 +101,13 @@ end # ################################################################################ +@doc raw""" + is_square(M::MatElem) + is_square(M::MatRingElem) + +Return `true` iff the matrix `M` has square shape. +See also `is_square(a::T) where {T <: NCRingElement}` which tests whether the given value `a` is a square in its own ring. +""" # See generic documentation in NCRings.jl is_square(a::MatElem) = (nrows(a) == ncols(a)) diff --git a/test/julia/Floats-test.jl b/test/julia/Floats-test.jl index 2ad98f933e..4aaa778afd 100644 --- a/test/julia/Floats-test.jl +++ b/test/julia/Floats-test.jl @@ -83,13 +83,26 @@ end end end -@testset "Julia.Floats.gcd" begin +@testset "Julia.Floats.is_square" begin R = RDF S = RealField + z1 = R(0.0) + z2 = S(0.0) + + @test is_square(z1) + @test is_square(z2) + + fz1, z1root = is_square_with_sqrt(z1) + @test fz1 + @test is_zero(z1root) + + fz2, z2root = is_square_with_sqrt(z2) + @test fz2 + @test is_zero(z2root) + r = R(-0.1) s = S(-0.1) - @test !is_square(r) @test !is_square(s)