def hitting_probability(T, target):
r"""
Computes the hitting probabilities for all states to the target states.
The hitting probability of state i to the target set A is defined as the minimal,
non-negative solution of:
.. math::
h_i^A &= 1 \:\:\:\: i\in A \\
h_i^A &= \sum_j p_{ij} h_i^A \:\:\:\: i \notin A
Parameters
----------
T : (M, M) ndarray or scipy.sparse matrix
Transition matrix
target: array_like
List of integer state labels for the target set
Returns
-------
h : ndarray(n)
a vector with hitting probabilities
"""
T = ensure_number_array(T, ndim=2)
target = ensure_integer_array(target, ndim=1)
if _issparse(T):
_showSparseConversionWarning() # currently no sparse implementation!
return dense.hitting_probability.hitting_probability(T.toarray(), target)
else:
return dense.hitting_probability.hitting_probability(T, target)
def expectation_sensitivity(T, a):
r"""Sensitivity of expectation value of observable A=(a_i).
Parameters
----------
T : (M, M) ndarray
Transition matrix
a : (M,) ndarray
Observable, a[i] is the value of the observable at state i.
Returns
-------
S : (M, M) ndarray
Sensitivity matrix of the expectation value.
"""
# check input
T = ensure_number_array(T, ndim=2)
a = ensure_floating_array(a, ndim=1)
# go
if _issparse(T):
_showSparseConversionWarning()
return dense.sensitivity.expectation_sensitivity(T.toarray(), a)
else:
return dense.sensitivity.expectation_sensitivity(T, a)
def mfpt_sensitivity(T, target, i):
r"""Sensitivity matrix of the mean first-passage time from specified state.
Parameters
----------
T : (M, M) ndarray
Transition matrix
target : int or list
Target state or set for mfpt computation
i : int
Compute the sensitivity for state `i`
Returns
-------
S : (M, M) ndarray
Sensitivity matrix for specified state
"""
# check input
T = ensure_number_array(T, ndim=2)
target = ensure_integer_array(target, ndim=1)
# go
if _issparse(T):
_showSparseConversionWarning()
mfpt_sensitivity(T.todense(), target, i)
else:
return dense.sensitivity.mfpt_sensitivity(T, target, i)
def stationary_distribution_sensitivity(T, j):
r"""Sensitivity matrix of a stationary distribution element.
Parameters
----------
T : (M, M) ndarray
Transition matrix (stochastic matrix).
j : int
Index of stationary distribution element
for which sensitivity matrix is computed.
Returns
-------
S : (M, M) ndarray
Sensitivity matrix for the specified element
of the stationary distribution.
"""
T = ensure_number_array(T, ndim=2)
if _issparse(T):
_showSparseConversionWarning()
stationary_distribution_sensitivity(T.todense(), j)
else:
return dense.sensitivity.stationary_distribution_sensitivity(T, j)
def eigenvector_sensitivity(T, k, j, right=True):
r"""Sensitivity matrix of a selected eigenvector element.
Parameters
----------
T : (M, M) ndarray
Transition matrix (stochastic matrix).
k : int
Eigenvector index
j : int
Element index
right : bool
If True compute for right eigenvector, otherwise compute for left eigenvector.
Returns
-------
S : (M, M) ndarray
Sensitivity matrix for the j-th element of the k-th eigenvector.
"""
T = ensure_number_array(T, ndim=2)
if _issparse(T):
_showSparseConversionWarning()
eigenvector_sensitivity(T.todense(), k, j, right=right)
else:
return dense.sensitivity.eigenvector_sensitivity(T, k, j, right=right)
def _check_k(T, k):
# ensure k is not exceeding shape of transition matrix
if k is None:
return
n = T.shape[0]
if _issparse(T):
# for sparse matrices we can compute an eigendecomposition of n - 1
new_k = min(n - 1, k)
else:
new_k = min(n, k)
if new_k < k:
warnings.warn('truncated eigendecomposition to contain %s components' % new_k, category=UserWarning)
return new_k
def _pcca_object(T, m):
"""
Constructs the pcca object from dense or sparse
Parameters
----------
T : (n, n) ndarray or scipy.sparse matrix
Transition matrix
m : int
Number of metastable sets
Returns
-------
pcca : PCCA
PCCA object
"""
if _issparse(T):
_showSparseConversionWarning()
T = T.toarray()
T = ensure_number_array(T, ndim=2, accept_sparse=False)
return dense.pcca.PCCA(T, m)
def timescale_sensitivity(T, k):
r"""Sensitivity matrix of a specified time-scale.
Parameters
----------
T : (M, M) ndarray
Transition matrix
k : int
Compute sensitivity matrix for the k-th time-scale.
Returns
-------
S : (M, M) ndarray
Sensitivity matrix for the k-th time-scale.
"""
T = ensure_number_array(T, ndim=2)
if _issparse(T):
_showSparseConversionWarning()
timescale_sensitivity(T.todense(), k)
else:
return dense.sensitivity.timescale_sensitivity(T, k)
def eigenvalue_sensitivity(T, k):
r"""Sensitivity matrix of a specified eigenvalue.
Parameters
----------
T : (M, M) ndarray
Transition matrix
k : int
Compute sensitivity matrix for k-th eigenvalue
Returns
-------
S : (M, M) ndarray
Sensitivity matrix for k-th eigenvalue.
"""
T = ensure_number_array(T, ndim=2)
if _issparse(T):
_showSparseConversionWarning()
eigenvalue_sensitivity(T.todense(), k)
else:
return dense.sensitivity.eigenvalue_sensitivity(T, k)
def committor_sensitivity(T, A, B, i, forward=True):
r"""Sensitivity matrix of a specified committor entry.
Parameters
----------
T : (M, M) ndarray
Transition matrix
A : array_like
List of integer state labels for set A
B : array_like
List of integer state labels for set B
i : int
Compute the sensitivity for committor entry `i`
forward : bool (optional)
Compute the forward committor. If forward
is False compute the backward committor.
Returns
-------
S : (M, M) ndarray
Sensitivity matrix of the specified committor entry.
"""
# check inputs
T = ensure_number_array(T, ndim=2)
A = ensure_integer_array(A, ndim=1)
B = ensure_integer_array(B, ndim=1)
if _issparse(T):
_showSparseConversionWarning()
committor_sensitivity(T.todense(), A, B, i, forward)
else:
if forward:
return dense.sensitivity.forward_committor_sensitivity(T, A, B, i)
else:
return dense.sensitivity.backward_committor_sensitivity(T, A, B, i)