Diagnall dominant

tests/test_matrix_props/test_is_diagonally_dominant.py

@@ -0,0 +1,44 @@
+"""Test is_diagonally_dominant."""
+import numpy as np
+
+from toqito.matrix_props import is_diagonally_dominant
+
+
+def test_is_not_square():
+    """Test that non-square matrix returns False."""
+    mat = np.array([[1, 2, 3], [4, 5, 6]])
+    np.testing.assert_equal(is_diagonally_dominant(mat), False)
+
+
+def test_diagonally_dominant():
+    """Check that strict diagonally dominance.
+
+    Matrix examples from: https://en.wikipedia.org/wiki/Diagonally_dominant_matrix
+    """
+    # Diagonally dominant (but not strict)
+    mat = np.array([[3, -2, 1], [1, 3, 2], [-1, 2, 4]])
+    np.testing.assert_equal(is_diagonally_dominant(mat, is_strict=False), True)
+
+    # Non-diagonally dominant
+    mat = np.array([[-2, 2, 1], [1, 3, 2], [1, -2, 0]])
+    np.testing.assert_equal(is_diagonally_dominant(mat), False)
+
+    # Strictly diagonally dominant
+    mat = np.array([[-4, 2, 1], [1, 6, 2], [1, -2, 5]])
+    np.testing.assert_equal(is_diagonally_dominant(mat, is_strict=True), True)
+
+
+def test_is_not_diagonally_dominant():
+    """Check that diagonally dominant matrix returns False."""
+    mat = np.array([[-1, 2], [-1, -1]])
+    np.testing.assert_equal(is_diagonally_dominant(mat), False)
+
+
+def test_strict_diagonally_dominant():
+    """Check that strict diagonally dominant matrix returns False."""
+    mat = np.array([[-1, 1], [-1, -1]])
+    np.testing.assert_equal(is_diagonally_dominant(mat), False)
+
+
+if __name__ == "__main__":
+    np.testing.run_module_suite()

toqito/matrix_props/__init__.py

@@ -18,4 +18,5 @@
 from toqito.matrix_props.sk_norm import sk_operator_norm
 from toqito.matrix_props.is_block_positive import is_block_positive
 from toqito.matrix_props.is_orthonormal import is_orthonormal
-from toqito.matrix_props.trace_norm import trace_norm
+from toqito.matrix_props.trace_norm import trace_norm
+from toqito.matrix_props.is_diagonally_dominant import is_diagonally_dominant

toqito/matrix_props/is_diagonally_dominant.py

@@ -0,0 +1,65 @@
+"""Is matrix diagonally dominant."""
+import numpy as np
+from toqito.matrix_props import is_square
+
+
+def is_diagonally_dominant(mat: np.ndarray, is_strict: bool = True) -> bool:
+    r"""
+       Check if matrix is diagnal dominant (DD) [WikDD]_.
+
+        A matrix is diagonally dominant if the matrix is square
+        and if for every row of the matrix, the magnitude of the diagonal entry in a row is greater
+        than or equal to the sum of the magnitudes of all the other (non-diagonal) entries in that row.
+
+       Examples
+       ==========
+
+        The following is an example of a 3-by-3 diagonal matrix:
+
+       .. math::
+           A = \begin{pmatrix}
+                   2 & -1 & 0 \\
+                   0 & 2 & -1 \\
+                   0 & -1 & 2
+               \end{pmatrix}
+
+       our function indicates that this is indeed a diagonally dominant matrix.
+
+       >>> from toqito.matrix_props import is_diagonally_dominant
+       >>> import numpy as np
+       >>> A = np.array([[2, -1, 0], [0, 2, -1], [0, -1, 2]])
+       >>> is_diagonally_dominant(A)
+       True
+
+       Alternatively, the following example matrix :math:`B` defined as
+
+       .. math::
+           B = \begin{pmatrix}
+                   -1 & 2 \\
+                   -1 & -1
+               \end{pmatrix}
+
+       is not diagonally dominant.
+
+       >>> from toqito.matrix_props import is_diagonally_dominant
+       >>> import numpy as np
+       >>> B = np.array([[-1, 2], [-1, -1]])
+       >>> is_diagonally_dominant(B)
+       False
+
+       References
+       ==========
+       .. [WikDD] Wikipedia: Diagonally dominant matrix.
+           https://en.wikipedia.org/wiki/Diagonally_dominant_matrix
+
+       :param mat: Matrix to check.
+       :param is_strict: Whether the inequality is strict.
+       :return: Return :code:`True` if matrix is diagnally dominant, and :code:`False` otherwise.
+       """
+    if not is_square(mat):
+        return False
+
+    mat = np.abs(mat)
+    diag_coeffs = np.diag(mat)
+    row_sum = np.sum(mat, axis=1) - diag_coeffs
+    return np.all(diag_coeffs > row_sum) if is_strict else np.all(diag_coeffs >= row_sum)