Edit lll docstrings

src/flint/fmpz_mat.jl

@@ -885,13 +885,17 @@ mutable struct lll_ctx
    end
 end
 
-
 @doc raw"""
     lll_with_transform(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
 
-Compute a tuple $(L, T)$ where $L$ is the LLL reduction of $a$ and $T$ is a
-transformation matrix so that $L = Ta$. All the default parameters can be
-overridden by supplying an optional context object.
+Return a tuple $(L, T)$ where the rows of $L$ form an LLL-reduced basis of the
+$\mathbb{Z}$-lattice generated by the rows of $x$ and $T$ is a transformation
+matrix so that $L = Tx$. $L$ may contain additional zero rows.
+See [`lll`](@ref) for the used default parameters which can be overridden by
+supplying an optional context object.
+
+See [`lll_gram_with_transform`](@ref) for a function taking the gram matrix as
+input.
 """
 function lll_with_transform(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
    z = deepcopy(x)
@@ -907,30 +911,32 @@ end
 @doc raw"""
     lll(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
 
-Return the LLL reduction of the matrix $x$. By default the matrix $x$ is a
-$\mathbb{Z}$-basis and the Gram matrix is maintained throughout in
-approximate form. The LLL is performed with reduction parameters
-$\delta = 0.99$ and $\eta = 0.51$. All of these defaults can be overridden by
-specifying an optional context object.
+Return a matrix $L$ whose rows form an LLL-reduced basis of the
+$\mathbb{Z}$-lattice generated by the rows of $x$. $L$ may contain additional
+zero rows.
+
+By default, the Gram matrix is maintained throughout in approximate form and
+the LLL is performed with reduction parameters $\delta = 0.99$ and $\eta = 0.51$.
+All of these defaults can be overridden by specifying an optional context object.
+
+See [`lll_gram`](@ref) for a function taking the gram matrix as input.
 """
 function lll(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
    z = deepcopy(x)
-   if nrows(z) == 0
-     return z
-   end
-   ccall((:fmpz_lll, libflint), Nothing,
-         (Ref{ZZMatrix}, Ptr{nothing}, Ref{lll_ctx}), z, C_NULL, ctx)
-   return z
+   return lll!(z)
 end
 
 @doc raw"""
     lll!(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
 
-Perform the LLL reduction of the matrix $x$ inplace. By default the matrix
-$x$ is a > $\mathbb{Z}$-basis and the Gram matrix is maintained throughout in
-approximate form. The LLL is performed with reduction parameters
-$\delta = 0.99$ and $\eta = 0.51$. All of these defaults can be overridden by
-specifying an optional context object.
+Compute an LLL-reduced basis of the $\mathbb{Z}$-lattice generated by the rows
+of $x$ inplace.
+
+By default, the Gram matrix is maintained throughout in approximate form and
+the LLL is performed with reduction parameters $\delta = 0.99$ and $\eta = 0.51$.
+All of these defaults can be overridden by specifying an optional context object.
+
+See [`lll_gram!`](@ref) for a function taking the gram matrix as input.
 """
 function lll!(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51))
    if nrows(x) == 0
@@ -944,9 +950,13 @@ end
 @doc raw"""
     lll_gram_with_transform(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
 
-Given the Gram matrix $x$ of a matrix $M$, compute a tuple $(L, T)$ where
-$L$ is the gram matrix of the LLL reduction of the matrix and $T$ is a
-transformation matrix so that $L = TM$.
+Return a tuple $(L, T)$ where $L$ is the Gram matrix of an LLL-reduced basis of
+the lattice given by the Gram matrix $x$ and $T$ is a transformation matrix with
+$L = T^\top x T$.
+The matrix $x$ must be symmetric and non-singular.
+
+See [`lll_gram`](@ref) for the used default parameters which can be overridden by
+supplying an optional context object.
 """
 function lll_gram_with_transform(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
    z = deepcopy(x)
@@ -962,29 +972,36 @@ end
 @doc raw"""
     lll_gram(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
 
-Given the Gram matrix $x$ of a matrix, compute the Gram matrix of its LLL
-reduction.
+Return the Gram matrix $L$ of an LLL-reduced basis of the lattice given by the
+Gram matrix $x$.
+The matrix $x$ must be symmetric and non-singular.
+
+By default, the LLL is performed with reduction parameters $\delta = 0.99$ and
+$\eta = 0.51$. These defaults can be overridden by specifying an optional context
+object.
 """
 function lll_gram(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
    z = deepcopy(x)
-   ccall((:fmpz_lll, libflint), Nothing,
-         (Ref{ZZMatrix}, Ptr{nothing}, Ref{lll_ctx}), z, C_NULL, ctx)
-   return z
+   return lll_gram!(z)
 end
 
 @doc raw"""
     lll_gram!(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
 
-Given the Gram matrix $x$ of a matrix, compute the Gram matrix of its LLL
-reduction inplace.
+Compute the Gram matrix of an LLL-reduced basis of the lattice given by the
+Gram matrix $x$ inplace.
+The matrix $x$ must be symmetric and non-singular.
+
+By default, the LLL is performed with reduction parameters $\delta = 0.99$ and
+$\eta = 0.51$. These defaults can be overridden by specifying an optional context
+object.
 """
 function lll_gram!(x::ZZMatrix, ctx::lll_ctx = lll_ctx(0.99, 0.51, :gram))
    ccall((:fmpz_lll, libflint), Nothing,
          (Ref{ZZMatrix}, Ptr{Nothing}, Ref{lll_ctx}), x, C_NULL, ctx)
    return x
 end
 
-
 @doc raw"""
     lll_with_removal_transform(x::ZZMatrix, b::ZZRingElem, ctx::lll_ctx = lll_ctx(0.99, 0.51))