matrix_props: Check if stochastic or doubly stochastic

docs/refs.bib

@@ -628,6 +628,7 @@ @article{Lupo_2008_Bipartite
 
 
 #Last name begins with M
+
 @misc{Matsumoto_2010_Reverse,
       title={Reverse test and quantum analogue of classical fidelity and generalized fidelity}, 
       author={Matsumoto, Keiji},
@@ -1122,6 +1123,13 @@ @misc{WikiDiagDom
 
 }
 
+@misc{WikiDoublyStichasticMatrix,
+  author  = "Wikipedia",
+  title   = "Doubly Stochastic Matrix",
+  howpublished = {https://en.wikipedia.org/wiki/Doubly_stochastic_matrix}
+
+}
+
 @misc{WikiFidQuant,
   author  = "Wikipedia",
   title   = "Fidelity of quantum states",
@@ -1389,6 +1397,13 @@ @misc{WikiSymMat
 
 }
 
+@misc{WikiStichasticMatrix,
+  author  = "Wikipedia",
+  title   = "Stochastic Matrix",
+  howpublished = {https://en.wikipedia.org/wiki/Stochastic_matrix}
+
+}
+
 @misc{WikiTensorProd,
   author  = "Wikipedia",
   title   = "Tensor product",

toqito/matrix_props/__init__.py

@@ -29,3 +29,6 @@
 from toqito.matrix_props.is_doubly_nonnegative import is_doubly_nonnegative
 from toqito.matrix_props.is_positive import is_positive
 from toqito.matrix_props.positive_semidefinite_rank import positive_semidefinite_rank
+from toqito.matrix_props.is_right_stochastic import is_right_stochastic
+from toqito.matrix_props.is_left_stochastic import is_left_stochastic
+from toqito.matrix_props.is_doubly_stochastic import is_doubly_stochastic

toqito/matrix_props/is_doubly_stochastic.py

@@ -0,0 +1,75 @@
+"""Check is a matrix is doubly stochastic."""
+
+import numpy as np
+
+from toqito.matrix_props import is_left_stochastic, is_right_stochastic
+
+
+def is_doubly_stochastic(mat: np.ndarray) -> bool:
+    r"""Verify matrix is doubly stochastic.
+
+    A matrix is doubky stochastic if it is also a right and left stochastic matrix.
+    :cite:`WikiStichasticMatrix, WikiDoublyStichasticMatrix`.
+
+    See Also
+    ========
+    is_right_stochastic
+    is_left_stochastic
+
+    Examples
+    ========
+    The elements an identity matrix and a Pauli X matrix are nonnegative where both the rows and columns sum up to 1.
+    The same cannot be said about a Pauli Z matrix.
+
+    .. math::
+    Id = \begin{pmatrix}
+            1 & 0 & 0 & 0 & 0\\
+            0 & 1 & 0 & 0 & 0\\
+            0 & 0 & 1 & 0 & 0\\
+            0 & 0 & 0 & 1 & 0\\
+            0 & 0 & 0 & 0 & 1\\
+        \end{pmatrix}
+
+    >>> import numpy as np
+    >>> from toqito.matrix_props import is_doubly_stochastic
+    >>> id_mat = np.eye(5)
+    >>> is_doubly_stochastic(id_mat)
+    True
+
+    .. math::
+    PauliX = \begin{pmatrix}
+            0 & 1 \\
+            1 & 0\\
+        \end{pmatrix}
+
+    >>> from toqito.matrices import pauli
+    >>> from toqito.matrix_props import is_doubly_stochastic
+    >>> x_mat = pauli("X")
+    >>> is_doubly_stochastic(x_mat)
+    True
+
+    .. math::
+    PauliY = \begin{pmatrix}
+            1 & 0 \\
+            0 & -1\\
+        \end{pmatrix}
+
+    >>> from toqito.matrices import pauli
+    >>> from toqito.matrix_props import is_doubly_stochastic
+    >>> z_mat = pauli("Z")
+    >>> is_doubly_stochastic(z_mat)
+    False
+
+
+    References
+    ==========
+    .. bibliography::
+        :filter: docname in docnames
+
+    :param rho: Matrix of interest
+
+    """
+    if is_left_stochastic(mat) and is_right_stochastic(mat):
+            return True
+
+    return False

toqito/matrix_props/is_left_stochastic.py

@@ -0,0 +1,72 @@
+"""Check is a matrix is left stochastic."""
+
+import numpy as np
+
+from toqito.matrix_props import is_nonnegative, is_square
+
+
+def is_left_stochastic(mat: np.ndarray) -> bool:
+    r"""Verify matrix is right stochastic.
+
+    A matrix is right stochastic if it is a square matrix with nonegative elements such that the columns sum up to 1
+     :cite:WikiStichasticMatrix.
+
+    Examples
+    ========
+    The elements an identity matrix and a Pauli X matrix are nonnegative and the rows sum up to 1. The same cannot be
+    said about a Pauli Z matrix.
+
+    .. math::
+     Id = \begin{pmatrix}
+               1 & 0 & 0 & 0 & 0\\
+               0 & 1 & 0 & 0 & 0\\
+               0 & 0 & 1 & 0 & 0\\
+               0 & 0 & 0 & 1 & 0\\
+               0 & 0 & 0 & 0 & 1\\
+          \end{pmatrix}
+
+     >>> import numpy as np
+     >>> from toqito.matrix_props import is_left_stochastic
+     >>> id_mat = np.eye(5)
+     >>> is_left_stochastic(id_mat)
+     True
+
+     .. math::
+     PauliX = \begin{pmatrix}
+               0 & 1 \\
+               1 & 0\\
+          \end{pmatrix}
+
+     >>> from toqito.matrices import pauli
+     >>> from toqito.matrix_props import is_left_stochastic
+     >>> x_mat = pauli("X")
+     >>> is_left_stochastic(x_mat)
+     True
+
+     .. math::
+     PauliY = \begin{pmatrix}
+               1 & 0 \\
+               0 & -1\\
+          \end{pmatrix}
+
+     >>> from toqito.matrices import pauli
+     >>> from toqito.matrix_props import is_left_stochastic
+     >>> z_mat = pauli("Z")
+     >>> is_left_stochastic(z_mat)
+     False
+
+
+
+
+    References
+    ==========
+    .. bibliography::
+          :filter: docname in docnames
+
+     :param rho: Matrix of interest
+
+    """
+    if is_square(mat) and is_nonnegative(mat) and np.all(np.sum(mat, axis=0) == 1.0):
+        return True
+
+    return False

toqito/matrix_props/is_right_stochastic.py

@@ -0,0 +1,74 @@
+"""Check is a matrix is right stochastic."""
+
+import numpy as np
+
+from toqito.matrix_props import is_nonnegative, is_square
+
+
+def is_right_stochastic(mat: np.ndarray) -> bool:
+    r"""Verify matrix is right stochastic.
+
+    A matrix is right stochastic if it is a square matrix with nonegative elements such that the rows sum up to 1
+     :cite:WikiStichasticMatrix.
+
+    Examples
+    ========
+    The elements an identity matrix and a Pauli X matrix are nonnegative and the rows sum up to 1. The same cannot be
+    said about a Pauli Z matrix.
+
+    .. math::
+     Id = \begin{pmatrix}
+               1 & 0 & 0 & 0 & 0\\
+               0 & 1 & 0 & 0 & 0\\
+               0 & 0 & 1 & 0 & 0\\
+               0 & 0 & 0 & 1 & 0\\
+               0 & 0 & 0 & 0 & 1\\
+          \end{pmatrix}
+
+     >>> import numpy as np
+     >>> from toqito.matrix_props import is_right_stochastic
+     >>> id_mat = np.eye(5)
+     >>> is_right_stochastic(id_mat)
+     True
+
+     .. math::
+     PauliX = \begin{pmatrix}
+               0 & 1 \\
+               1 & 0\\
+          \end{pmatrix}
+
+     >>> from toqito.matrices import pauli
+     >>> from toqito.matrix_props import is_right_stochastic
+     >>> x_mat = pauli("X")
+     >>> is_right_stochastic(x_mat)
+     True
+
+     .. math::
+     PauliY = \begin{pmatrix}
+               1 & 0 \\
+               0 & -1\\
+          \end{pmatrix}
+
+     >>> from toqito.matrices import pauli
+     >>> from toqito.matrix_props import is_right_stochastic
+     >>> z_mat = pauli("Z")
+     >>> is_right_stochastic(z_mat)
+     False
+
+
+
+
+    References
+    ==========
+     .. bibliography::
+          :filter: docname in docnames
+
+     :param rho: Matrix of interest
+
+    """
+    if is_square(mat) and is_nonnegative(mat) and np.all(np.sum(mat, axis=1) == 1.0):
+        return True
+
+    return False
+
+

toqito/matrix_props/tests/test_is_doubly_stochastic.py

@@ -0,0 +1,23 @@
+"""Tests for doubly stochastic matrix."""
+
+
+import numpy as np
+import pytest
+
+from toqito.matrices import cyclic_permutation_matrix, pauli
+from toqito.matrix_props import is_doubly_stochastic, is_left_stochastic, is_right_stochastic
+
+
+@pytest.mark.parametrize("test_input", [(np.identity(3)), (cyclic_permutation_matrix(4)), (pauli("X"))])
+def test_true(test_input):
+    """Check if function identifies right stochastic matrix correctly."""
+    assert is_left_stochastic(test_input)
+    assert is_right_stochastic(test_input)
+    assert is_doubly_stochastic(test_input)
+
+
+
+@pytest.mark.parametrize("test_input", [(pauli("Y")), (pauli("Z"))])
+def test_true(test_input):
+    """Check if function identifies non-right stochastic matrix correctly."""
+    assert not is_doubly_stochastic(test_input)

toqito/matrix_props/tests/test_is_left_stochastic.py

@@ -0,0 +1,23 @@
+"""Tests for left stochastic matrix."""
+
+
+import numpy as np
+import pytest
+
+from toqito.matrices import cyclic_permutation_matrix, pauli
+from toqito.matrix_props import is_left_stochastic, is_nonnegative, is_square
+
+
+@pytest.mark.parametrize("test_input", [(np.identity(3)), (cyclic_permutation_matrix(4)), (pauli("X"))])
+def test_true(test_input):
+    """Check if function identifies right stochastic matrix correctly."""
+    assert is_square(test_input)
+    assert is_nonnegative(test_input)
+    assert is_left_stochastic(test_input)
+
+
+
+@pytest.mark.parametrize("test_input", [(pauli("Y")), (pauli("Z"))])
+def test_true(test_input):
+    """Check if function identifies non-right stochastic matrix correctly."""
+    assert not is_left_stochastic(test_input)

toqito/matrix_props/tests/test_is_right_stochastic.py

@@ -0,0 +1,22 @@
+"""Tests for right stochastic matrix."""
+
+import numpy as np
+import pytest
+
+from toqito.matrices import cyclic_permutation_matrix, pauli
+from toqito.matrix_props import is_nonnegative, is_right_stochastic, is_square
+
+
+@pytest.mark.parametrize("test_input", [(np.identity(3)), (cyclic_permutation_matrix(4)), (pauli("X"))])
+def test_true(test_input):
+    """Check if function identifies right stochastic matrix correctly."""
+    assert is_square(test_input)
+    assert is_nonnegative(test_input)
+    assert is_right_stochastic(test_input)
+
+
+
+@pytest.mark.parametrize("test_input", [(pauli("Y")), (pauli("Z"))])
+def test_true(test_input):
+    """Check if function identifies non-right stochastic matrix correctly."""
+    assert not is_right_stochastic(test_input)