Skip to content

is_stochastic

Checks if the matrix is stochastic.

is_stochastic 

is_stochastic(mat: ndarray, mat_type: str) -> bool

Verify matrix is doubly, right or left stochastic.

When the nonnegative elements in a row of a square matrix sum up to 1, the matrix is right stochastic and if the columns sum up to 1, the matrix is left stochastic 1.

When a matrix is right and left stochastic, it is a doubly stochastic matrix 2.

Parameters:

  • mat (ndarray) –

    Matrix of interest.

  • mat_type (str) –

    Type of stochastic matrix. "left" for left stochastic matrix, "right" for right stochastic matrix, and "doubly" for a doubly stochastic matrix.

Returns:

  • bool –

    Returns True if the matrix is doubly, right or left stochastic, False otherwise.

Raises:

  • ValueError –

    If something other than "doubly", "left", or "right" is used for mat_type.

Examples:

The elements of an identity matrix and a Pauli-X matrix are nonnegative such that the rows and columns sum up to 1. We expect these matrices to be left and right stochastic. The same cannot be said about a Pauli-Z or a Pauli-Y matrix.

import numpy as np
from toqito.matrix_props import is_stochastic

print(is_stochastic(np.eye(5), "right"))
print(is_stochastic(np.eye(5), "left"))
print(is_stochastic(np.eye(5), "doubly"))

True
True
True

from toqito.matrices import pauli
from toqito.matrix_props import is_stochastic

print(is_stochastic(pauli("X"), "left"))
print(is_stochastic(pauli("X"), "right"))
print(is_stochastic(pauli("X"), "doubly"))

True
True
True

from toqito.matrices import pauli
from toqito.matrix_props import is_stochastic

print(is_stochastic(pauli("Z"), "right"))
print(is_stochastic(pauli("Z"), "left"))
print(is_stochastic(pauli("Z"), "doubly"))

False
False
False

See

is_stochastic() — use mat_type="doubly" for doubly stochastic check

References

1 Wikipedia. Stochastic Matrix. link.
2 Wikipedia. Doubly Stochastic Matrix. link.

Source code in toqito/matrix_props/is_stochastic.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def is_stochastic(mat: np.ndarray, mat_type: str) -> bool:
    r"""Verify matrix is doubly, right or left stochastic.

    When the nonnegative elements in a row of a square matrix sum up to 1, the matrix is right stochastic and if the
    columns sum up to 1, the matrix is left stochastic [@wikipediastochastic].

    When a matrix is right and left stochastic, it is a doubly stochastic matrix [@wikipediadoublystochastic].

    Args:
        mat: Matrix of interest.
        mat_type: Type of stochastic matrix. `"left"` for left stochastic matrix, `"right"` for right stochastic
            matrix, and `"doubly"` for a doubly stochastic matrix.

    Returns:
        Returns `True` if the matrix is doubly, right or left stochastic, `False` otherwise.

    Raises:
        ValueError: If something other than `"doubly"`, `"left"`, or `"right"` is used for `mat_type`.

    Examples:
        The elements of an identity matrix and a Pauli-X matrix are nonnegative such that the rows and columns
        sum up to 1.
        We expect these matrices to be left and right stochastic. The same cannot be said about a Pauli-Z or a Pauli-Y
        matrix.

        ```python exec="1" source="above" result="text"
        import numpy as np
        from toqito.matrix_props import is_stochastic

        print(is_stochastic(np.eye(5), "right"))
        print(is_stochastic(np.eye(5), "left"))
        print(is_stochastic(np.eye(5), "doubly"))
        ```

        ```python exec="1" source="above" result="text"
        from toqito.matrices import pauli
        from toqito.matrix_props import is_stochastic

        print(is_stochastic(pauli("X"), "left"))
        print(is_stochastic(pauli("X"), "right"))
        print(is_stochastic(pauli("X"), "doubly"))
        ```

        ```python exec="1" source="above" result="text"
        from toqito.matrices import pauli
        from toqito.matrix_props import is_stochastic

        print(is_stochastic(pauli("Z"), "right"))
        print(is_stochastic(pauli("Z"), "left"))
        print(is_stochastic(pauli("Z"), "doubly"))
        ```

        !!! See Also
            [`is_stochastic()`][toqito.matrix_props.is_stochastic.is_stochastic]
            — use `mat_type="doubly"` for doubly stochastic check

    """
    if mat_type not in {"left", "right", "doubly"}:
        raise ValueError("Allowed stochastic matrix types are: left, right, and doubly.")

    if not (is_square(mat) and is_nonnegative(mat)):
        return False

    checks = []

    if mat_type in {"left", "doubly"}:
        col_sums = np.sum(mat, axis=0)
        checks.append(np.allclose(col_sums, 1.0))

    if mat_type in {"right", "doubly"}:
        row_sums = np.sum(mat, axis=1)
        checks.append(np.allclose(row_sums, 1.0))

    return all(checks)