From 8ace5c70adff55d0940c6df5bd11c0463e2f08e8 Mon Sep 17 00:00:00 2001
From: Travis Scrimshaw <tcscrims@gmail.com>
Date: Sun, 31 Mar 2024 16:18:39 +0900
Subject: [PATCH] Implementing an is_nilpotent() check for matrices.

---
 src/sage/matrix/matrix2.pyx | 38 +++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/src/sage/matrix/matrix2.pyx b/src/sage/matrix/matrix2.pyx
index 47a836a0952..202a8821a80 100644
--- a/src/sage/matrix/matrix2.pyx
+++ b/src/sage/matrix/matrix2.pyx
@@ -9898,6 +9898,44 @@ cdef class Matrix(Matrix1):
         self.cache(key, normal)
         return normal
 
+    def is_nilpotent(self) -> bool:
+        r"""
+        Return if ``self`` is a nilpotent matrix.
+
+        A matrix `A` is *nilpotent* if there exists a positive integer
+        `k` such that `A^k = 0`. We test this by using the Cayley-Hamilton
+        theorem to see if the characteristic polynomial is `x^n = 0`.
+
+        EXAMPLES::
+
+            sage: A = matrix([[0,2,1,6], [0,0,1,2], [0,0,0,3], [0,0,0,0]])
+            sage: A.is_nilpotent()
+            True
+            sage: B = matrix([[2,2,2,2,-4], [7,1,1,1,-5], [1,7,1,1,-5],
+            ....:             [1,1,7,1,-5], [1,1,1,7,-5]])
+            sage: B.is_nilpotent()
+            True
+            sage: C = matrix(GF(7), [[1, 2], [2, 4]])
+            sage: C.is_nilpotent()
+            False
+            sage: Z = matrix.zero(QQ, 5)
+            sage: Z.is_nilpotent()
+            True
+
+        TESTS:
+
+        Check the corner case of the `0 \times 0` matrix::
+
+            sage: Z = matrix.zero(QQ, 0); Z
+            []
+            sage: Z.charpoly()
+            1
+            sage: Z.is_nilpotent()
+            True
+        """
+        chi = self.charpoly()
+        return chi.is_monomial()
+
     def as_sum_of_permutations(self):
         r"""
         Returns the current matrix as a sum of permutation matrices