LAPM.linear_autonomous_pool_model

Module for linear autonomous pool models.

Functions

create_random_compartmental_matrix(d, p)	Create a random invertible compartmental matrix.
create_random_probability_vector(d, p)	Create a random probability vector.

Classes

LinearAutonomousPoolModel(u, B[, …])

General class of linear autonomous compartment models.

Exceptions

Error	Generic error occuring in this module.
NonInvertibleCompartmentalMatrix

Detailed module content

exception LAPM.linear_autonomous_pool_model.Error

Bases: Exception

Generic error occuring in this module.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class LAPM.linear_autonomous_pool_model.LinearAutonomousPoolModel(u, B, force_numerical=False)

Bases: object

General class of linear autonomous compartment models.

\(\frac{d}{dt} x(t) = B\,x(t) + u\)

Notes

• symbolic matrix exponential Qt = \(e^{t\,B}\)

  cannot be computed automatically

• for symbolic computations it has to be given manually: model.Qt = …

• otherwise only numerical computations possible

• symbolical computations can take very long, in particular for complicated systems. An enforced purely numerical treatment could then be the right choice; choose force_numerical=True

• number of pools denoted by \(d\)

• steady state vector denoted by \(x^\ast=-B^{-1}\,u\)

• normalized steady state vector denoted by \(\eta=\frac{x^\ast}{\|x^\ast\|}\)

• norm of a vector \(v\) given by \(\|\mathbf{v}\| = \sum\limits_{i=1}^d |v_i|\)

u

The model’s external input vector.

Type

SymPy dx1-matrix

B

The model’s compartment matrix.

Type

SymPy dxd-matrix

Qt

Qt = \(e^{t\,B}\)

Type

SymPy dxd-matrix

A_cum_dist_func(age=None)

Return the cumulative distribution function of the system age.

Parameters

age (nonnegative, optional) – age at which \(F_A\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

cumulative distribution function of PH(\(\eta\), \(B\)) (evaluated at age)

Return type

SymPy expression or numerical value

See also

phase_type.cum_dist_func(): Return the (symbolic) cumulative distribution function of phase-type.

A_density(age=None)

Return the probability density function of the system age.

Parameters

age (nonnegative, optional) – age at which \(f_A\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

probability density function of PH(\(\eta\), \(B\)) (evaluated at age)

Return type

SymPy expression or numerical value

See also

phase_type.density(): Return the (symbolic) probability density function of the phase-type distribution.

property A_expected_value

Return the (symbolic) expected value of the system age.

Returns

expected value of PH(\(\eta\), \(B\))

Return type

SymPy expression or numerical value

See also

phase_type.expected_value: Return the (symbolic) expected value of the phase-type distribution.

property A_laplace

Return the symbolic Laplacian of the system age.

Returns

Laplace transform of the probability density of PH(\(\eta\), \(B\))

Return type

SymPy expression

See also

phase_type.laplace: Return the symbolic Laplacian of the phase-type distribtion.

A_nth_moment(n)

Return the (symbolic) n th moment of the system age.

Parameters

n (positive int) – order of the moment

Returns

n th moment of PH(\(\eta\), \(B\))

Return type

SymPy expression or numerical value

See also

phase_type.nth_moment(): Return the (symbolic) n th moment of the phase-type distribution.

A_quantile(q, tol=1e-08)

Return a numerical quantile of the system age distribution.

The quantile is computed by a numerical inversion of the cumulative distribution function.

Parameters

• q (between 0 and 1) – probability mass to be left to the quantile q = 1/2 computes the median

• tol (float) – tolerance for brentq algorithm of numerical root search, defaults to 1e-8

Raises

Error – if attempt is made to compute quantiles symbolically

Returns

smallest \(y\) such that \(F_A(y)\geq q\)

Return type

float

See also

A_cum_dist_func(): Return the cumulative distribution function of the system age.

property A_standard_deviation

Return the (symbolic) standard deviation of the system age.

Returns

standard deviation of PH(\(\eta\), \(B\))

Return type

SymPy expression or numerical value

See also

phase_type.standard_deviation(): Return the (symbolic) standard deviation of the phase-type distribution.

property A_variance

Return the (symbolic) variance of the system age.

Returns

variance of PH(\(\eta\), \(B\))

Return type

SymPy expression or numerical value

See also

func:.phase_type.variance: Return the (symbolic) variance of the phase-type distribution.

T_cum_dist_func(time=None)

Return the cumulative distribution function of the transit time.

Parameters

time (nonnegative, optional) – time at which \(F_T\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

cumulative distribution function of the transit time (evaluated at time)

Return type

SymPy expression or numerical value

See also

phase_type.cum_dist_func(): Return the (symbolic) cumulative distribution function of phase-type.

T_density(time=None)

Return the probability density function of the transit time.

Parameters

time (nonnegative, optional) – time at which \(f_T\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

probability density function of the transit time (evaluated at time)

Return type

SymPy expression or numerical value

See also

phase_type.density(): Return the (symbolic) probability density function of the phase-type distribution.

property T_expected_value

Return the (symbolic) expected value of the transit time.

See also

phase_type.expected_value(): Return the (symbolic) expected value of the phase-type distribution.

property T_laplace

Return the symbolic Laplacian of the transit time.

Returns

Laplace transform of the probability density of PH(\(\beta\), \(B\))

Return type

SymPy expression

See also

phase_type.laplace: Return the symbolic Laplacian of the phase-type distribtion.

T_nth_moment(n)

Return the (symbolic) n th moment of the transit time.

Parameters

n (positive int) – order of the moment

Returns

\(\mathbb{E}[T^n]\)

Return type

SymPy expression or numerical value

See also

phase_type.nth_moment(): Return the (symbolic) n th moment of the phase-type distribution.

T_quantile(q, tol=1e-08)

Return a numerical quantile of the transit time distribution.

The quantile is computed by a numerical inversion of the cumulative distribution function.

Parameters

• q (between 0 and 1) – probability mass to be left to the quantile q = 1/2 computes the median

• tol (float) – tolerance for brentq algorithm of numerical root search, defaults to 1e-8

Returns

The smallest \(y\) such that \(F_T(y)\geq q\)

Return type

float

See also

T_cum_dist_func(): Return the cumulative distribution function of the transit time.

property T_standard_deviation

Return the (symbolic) standard deviation of the transit time.

See also

phase_type.standard_deviation(): Return the (symbolic) standard deviation of the phase-type distribution.

property T_variance

Return the (symbolic) variance of the transit time.

See also

phase_type.variance(): Return the (symbolic) variance of the phase-type distribution.

a_cum_dist_func(age=None)

Return the cumulative distribution function vector of the compartment ages.

Parameters

age (nonnegative, optional) – age at which \(F_a\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

\(F_a\) (evaluated at age)

\(F_a(y) = (X^\ast)^{-1}\,B^{-1}\,\) \((e^{y\,B}-I)\,u\)

Return type

SymPy or numerical dx1-matrix

a_density(age=None)

Return the probability density function vector of the compartment ages.

Parameters

age (nonnegative, optional) – age at which \(f_a\) is to be evaluated, defaults to None: purely symbolic treatment

Returns

\(f_a\) (evaluated at age)

\(f_a(y) = (X^\ast)^{-1}\,\) \(e^{y\,B}\,u\)

Return type

SymPy or numerical dx1-matrix

property a_expected_value

Return the (symbolic) vector of expected values of the compartment ages.

Returns

\(\mathbb{E}[a] = -(X^\ast)^{-1}\,\) \(B^{-1}\,x^\ast\)

Return type

SymPy dx1-matrix

a_nth_moment(n)

Return the (symbolic) vector of the n th moments of the compartment ages.

Parameters

n (positive int) – order of the moment

Returns

\(\mathbb{E}[a^n] = (-1)^n\,n!\,(X^\ast)^{-1}\) \(\ ,B^{-n}\,x^\ast\)

Return type

SymPy or numerical dx1-matrix

a_quantile(q, tol=1e-08)

Return a vector of numerical quantiles of the pool age distributions.

The quantiles is computed by a numerical inversion of the cumulative distribution functions.

Parameters

• q (between 0 and 1) – probability mass to be left to the quantile q = 1/2 computes the median

• tol (float) – tolerance for brentq algorithm of numerical root search, defaults to 1e-8

Returns

vector \(y=(y_1,\ldots,y_d)\) with \(y_i\) smallest value such that \(F_{a_i}(y_i)\geq q\)

Return type

numpy.array

See also

a_cum_dist_func(): Return the cumulative distribution function vector of the compartment ages.

property a_standard_deviation

Return the (symbolic) vector of standard deviations of the compartment ages.

Returns

\(\sigma(a) = \sqrt{\sigma^2(a)}\) component-wise

Return type

SymPy dx1-matrix

property a_variance

Return the (symbolic) vector of variances of the compartment ages.

Returns

\(\sigma^2(a) = \mathbb{E}[a^2]\) \(- (\mathbb{E}[a])^2\) component-wise

Return type

SymPy dx1-matrix

property absorbing_jump_chain

Return the absorbing jump chain as a discrete-time Markov chain.

The generator of the absorbing chain is just given by \(B\), which allows the computation of the transition probability matrix \(P\) from \(B=(P-I)\,D\) with \(D\) being the diagonal matrix with diagonal entries taken from \(-B\).

Returns

DTMC (beta, P)

Return type

DTMC

property beta

Return the initial distribution of the according Markov chain.

Returns

\(\beta = \frac{u}{\|u\|}\)

Return type

SymPy or numerical dx1-matrix

property entropy_per_cycle

Return the entropy per cycle.

Returns

entropy per jump \(\times\) expected number of jumps per cycle

Return type

SymPy expression or float

See also

entropy_per_jump: Return the entropy per jump.

expected_number_of_jumps: Return the (symbolic) expected number of jumps before absorption.

property entropy_per_jump

Return the entropy per jump.

Returns

\(\theta_J=\) \(\sum\limits_{j=1}^{d+1} \pi_j\) \(\sum\limits_{i=1}^{d+1}-p_{ij}\,\log p_{ij}\) \(+\sum\limits_{j=1}^d \pi_j\,(1-\log -b_{jj})\) \(+\pi_{d+1}\,\sum\limits_{i=1}^d\) \(-\beta_i\,\log\beta_i\)

Return type

SymPy expression or float

Notes

• \(\pi\) is the stationary distribution of the ergodic jump chain.

• \(\theta_J=\) entropy of ergodic jump chain + entropy of sojourn times (no stay in environmental compartment \(d+1\))

See also

stationary_distribution: Return the (symbolic) stationary distribution.

property entropy_rate

Return the entropy rate (entropy per unit time).

Returns

entropy per cycle \(\cdot\frac{1}{\mathbb{E}T}\)

Return type

SymPy expression or float

See also

entropy_per_cycle: Return the entropy per cylce.

T_expected_value: Return the (symbolic) expected value of the transit time.

property ergodic_jump_chain

Return the ergodic jump chain as a discrete-time Markov chain.

The generator is given by

\[\begin{split}Q = \begin{pmatrix} B & \beta \\ z^T & -1 \end{pmatrix}\end{split}\]

and the corresponding transition probability matrix \(P_Q\) can then be obtained from \(Q=(P_Q-I)\,D_Q\), where \(D_Q\) is the diagonal matrix with entries from the diagonal of \(-Q\).

Returns

DTMC (beta_ext, Q) with beta_ext = (beta, 0)

Return type

DTMC

property eta

Return the initial distribution of the Markov chain according to system age.

Returns

\(\eta = \frac{x^\ast}{\|x^\ast\|}\)

Return type

SymPy or numerical dx1-matrix

classmethod from_random(d: int, p: float)

Create a random compartmental system.

Parameters

• d – dimension of the matrix (number of pools)

• p – probability of having a connection between two pools and of nonzero value in input vector

Returns

randomly generated compartmental system

• beta: from create_random_probability_vector()

• B: from :func:`~create_random_compartmental_matrix

property r_compartments

Return the (symbolic) release vector of the system in steady state.

Returns

\(r_j = z_j \, x^\ast_j\)

Return type

SymPy or numerical dx1-matrix

See also

phase_type.z(): Return the (symbolic) vector of rates toward absorbing state.

xss: Return the (symbolic) steady state vector.

property r_total

Return the (symbolic) total system release in steady state.

Returns

\(r = \sum\limits_{j=1}^d r_j\)

Return type

SymPy expression or numerical value

See also

r_compartments: Return the (symbolic) release vector of the system in steady state.

property xss

Return the (symbolic) steady state vector.

Returns

\(x^\ast = -B^{-1}\,u\)

Return type

SymPy or numerical dx1-matrix

exception LAPM.linear_autonomous_pool_model.NonInvertibleCompartmentalMatrix

Bases: Exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

LAPM.linear_autonomous_pool_model.create_random_compartmental_matrix(d: int, p: float) → numpy.ndarray

Create a random invertible compartmental matrix.

Parameters

• d – dimension of the matrix (number of pools)

• p – probability of existence of non-necessary connections

Returns

random invertible compartmental matrix B s.t.

• all diagonal entries are nonpositive

• all off-diagonal entries are nonnegative

• all column sums are nonpositive

• \(B\) is invertible

• \(-B_{ii} <= 1\)

• \(\mathbb{P}(B_{ij}>0) = p\) for \(i \neq j\)

• \(\mathbb{P}(z_j)>0) = p\), where \(z_j = -\sum_i B_{ij}\)

LAPM.linear_autonomous_pool_model.create_random_probability_vector(d: int, p: float) → numpy.ndarray

Create a random probability vector.

Parameters

• d – dimension of the random vector

• p – probability of setting elements to nonzero value

Returns

random probability vector v s.t. - \(v_i \geq 0\) - \(\mathbb{P}(v_i>0) = p\) - \(\sum_i v_i=1\)