From e5c48877ff605602b9ce292b03177b4a8cdf17a0 Mon Sep 17 00:00:00 2001
From: Max Horn <max@quendi.de>
Date: Tue, 26 Sep 2023 12:25:30 +0200
Subject: [PATCH] Rename rank(A::GrpAbFinGen) to torsion_free_rank

Unfortunately the notion of 'rank' for groups clashes with that for abelian groups.
The latter is also known as 'torsion free rank'. Hence I propose to rename `rank`
for abelian groups here accordingly.
---
 docs/src/abelian/introduction.md |  2 +-
 src/GrpAb/GrpAbFinGen.jl         | 38 +++++++++++++++++++++++---------
 src/exports.jl                   |  1 +
 test/GrpAb/GrpAbFinGen.jl        | 12 ++++++----
 4 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/docs/src/abelian/introduction.md b/docs/src/abelian/introduction.md
index ef4a93455a..96ff80d970 100644
--- a/docs/src/abelian/introduction.md
+++ b/docs/src/abelian/introduction.md
@@ -58,7 +58,7 @@ nrels(G::FinGenAbGroup)
 rels(A::FinGenAbGroup)
 is_finite(A::FinGenAbGroup)
 is_infinite(A::FinGenAbGroup)
-rank(A::FinGenAbGroup)
+torsion_free_rank(A::FinGenAbGroup)
 order(A::FinGenAbGroup)
 exponent(A::FinGenAbGroup)
 is_trivial(A::FinGenAbGroup)
diff --git a/src/GrpAb/GrpAbFinGen.jl b/src/GrpAb/GrpAbFinGen.jl
index 52b0f0cc91..c75cde4f86 100644
--- a/src/GrpAb/GrpAbFinGen.jl
+++ b/src/GrpAb/GrpAbFinGen.jl
@@ -533,20 +533,27 @@ is_finite_gen(A::FinGenAbGroup) = isfinite(snf(A)[1])
 ################################################################################
 
 @doc raw"""
-    rank(A::FinGenAbGroup) -> Int
+    torsion_free_rank(A::FinGenAbGroup) -> Int
 
-Return the rank of $A$, that is, the dimension of the
+Return the torsion free rank of $A$, that is, the dimension of the
 $\mathbf{Q}$-vectorspace $A \otimes_{\mathbf Z} \mathbf Q$.
-"""
-rank(A::FinGenAbGroup) = is_snf(A) ? rank_snf(A) : rank_gen(A)
-
-rank_snf(A::FinGenAbGroup) = length(findall(x -> iszero(x), A.snf))
-
-rank_gen(A::FinGenAbGroup) = rank(snf(A)[1])
 
-rank(A::FinGenAbGroup, p::Union{Int, ZZRingElem}) = is_snf(A) ? rank_snf(A, p) : rank_snf(snf(A)[1], p)
+See also [`rank`](@ref).
+"""
+function torsion_free_rank(A::FinGenAbGroup)
+  if !is_snf(A)
+    A = snf(A)[1]
+  end
+  return length(findall(iszero, A.snf))
+end
 
-function rank_snf(A::FinGenAbGroup, p::Union{Int, ZZRingElem})
+# return the p-rank of A, which is the dimension of the elementary abelian
+# group A/pA, or in other words, the rank (=size of minimal generating set) of
+# the maximal p-quotient of A
+function rank(A::FinGenAbGroup, p::Union{Int, ZZRingElem})
+  if !is_snf(A)
+    A = snf(A)[1]
+  end
   if isempty(A.snf)
     return 0
   end
@@ -558,6 +565,17 @@ function rank_snf(A::FinGenAbGroup, p::Union{Int, ZZRingElem})
 end
 
 
+@doc raw"""
+    rank(A::FinGenAbGroup) -> Int
+
+Return the rank of $A$, that is, the size of a minimal generating set for $A$.
+
+See also [`torsion_free_rank`](@ref).
+"""
+rank(A::FinGenAbGroup) = error("rank(::FinGenAbGroup) has been renamed to torsion_free_rank")
+#rank(A::FinGenAbGroup) = is_snf(A) ? length(A.snf) : return rank(snf(A)[1])
+
+
 ################################################################################
 #
 #  Order
diff --git a/src/exports.jl b/src/exports.jl
index b3a2a300f1..6098be1817 100644
--- a/src/exports.jl
+++ b/src/exports.jl
@@ -876,6 +876,7 @@ export tensor_product
 export theta
 export tidy_model
 export torsion_bound
+export torsion_free_rank
 export torsion_points
 export torsion_points_division_poly
 export torsion_points_lutz_nagell
diff --git a/test/GrpAb/GrpAbFinGen.jl b/test/GrpAb/GrpAbFinGen.jl
index bcfc54c0d6..935c2aeb3c 100644
--- a/test/GrpAb/GrpAbFinGen.jl
+++ b/test/GrpAb/GrpAbFinGen.jl
@@ -130,16 +130,20 @@
 
   @testset "Rank" begin
     G = abelian_group([3, 15])
-    @test @inferred rank(G) == 0
+    @test @inferred torsion_free_rank(G) == 0
+    #@test @inferred rank(G) == 2
 
     G = abelian_group([3, 5])
-    @test @inferred rank(G) == 0
+    @test @inferred torsion_free_rank(G) == 0
+    #@test @inferred rank(G) == 1
 
     G = abelian_group([3, 15, 0])
-    @test @inferred rank(G) == 1
+    @test @inferred torsion_free_rank(G) == 1
+    #@test @inferred rank(G) == 3
 
     G = abelian_group([3, 5, 0])
-    @test @inferred rank(G) == 1
+    @test @inferred torsion_free_rank(G) == 1
+    #@test @inferred rank(G) == 2
   end
 
   @testset "Order" begin