API reference

circulation

time_varying_elastance

circulation.time_varying_elastance.blanco_ventricle(EA: float = 1.0, EB: float = 0.1, tC: float = 0.0, TC: float = 0.4, TR: float = 0.2, RR: float = 1.0)

Time-varying elastance model for the left ventricle.

Parameters:

• EA (float, optional) – Maximum elastance, by default 1.0

• EB (float, optional) – Minimum elastance, by default 0.1

• tC (float, optional) – Time of contraction, by default 0.0 seconds

• TC (float, optional) – Duration of contraction, by default 0.4 seconds

• TR (float, optional) – Duration of relaxation, by default 0.2 seconds

• RR (float, optional) – RR interval by default 1.0

Returns:

elastance – Function that returns the elastance at time t.

Return type:

function

Notes

The elastance is defined as

\[E(t) = E_A \cdot f(t) + E_B\]

where

\[\begin{split}f(t) = \begin{cases} 0.5 \left(1 - \cos\left(\frac{\pi}{T_C} (t - t_C)\right)\right) & 0 \leq t - t_C < T_C \\ 0.5 \left(1 + \cos\left(\frac{\pi}{T_R} (t - t_R)\right)\right) & 0 \leq t - t_R < T_R \end{cases}\end{split}\]

References

Blanco, P. J., & Feijóo, R. A. (2010). A 3D-1D-0D computational model for the entire cardiovascular system. Mecánica Computacional, 29(59), 5887-5911.

log

circulation.log.log_table(rich_table)

Generate an ascii formatted presentation of a Rich table Eliminates any column styling

base

class circulation.base.CallBack(*args, **kwargs)

class circulation.base.CirculationModel(parameters: dict[str, Any] | None = None, outdir: Path = PosixPath('results'), add_units: bool = False, callback: CallBack | None = None, verbose: bool = False, comm=None, callback_save_state: CallBack | None = None, initial_state: dict[str, float] | None = None)

Base class for circulation models

Parameters:

• parameters (dict[str, Any] | None, optional) – Parameters used in the model, by default None which uses the default parameters

• add_units (bool, optional) – Add units to the parameters, by default False. Note that adding units will drastically slow down the simulation, so it is recommended to use this only for testing purposes.

• callback (base.CallBack | None, optional) – Optional callback function which is called at every time step, by default None. The callback function take three arguments: the model, the current time, and a boolean flag save which indicates if the current state should be saved.

• verbose (bool, optional) – Print additional information, by default False

• comm (mpi4py.MPI_InterComm optional) – MPI communicator, by default None

• callback_save_state (base.CallBack | None, optional) – Optional callback function called every time the state should be saved, by default None. The function should take three arguments: the model, the current time, and a boolean flag save which indicates if the current state should be saved.

• initial_state (dict[str, float] | None, optional) – Initial state of the model, by default None which uses the default initial state

abstract property HR: float

Heart rate

regazzoni

class circulation.regazzoni2020.Regazzoni2020(parameters: dict[str, Any] | None = None, p_LV_func: Callable[[float, float], float] | None = None, p_BiV_func: Callable[[float, float, float], float] | None = None, add_units=False, callback: CallBack | None = None, verbose: bool = False, comm=None, outdir: Path = PosixPath('results-regazzoni'), initial_state: dict[str, float] | None = None)

Closed loop circulation model fom Regazzoni et al. [2].

[2]

F. Regazzoni, M. Salvador, P. C. Africa, M. Fedele, L. Dede’, A. Quarteroni, “A cardiac electromechanics model coupled with a lumped parameters model for closed-loop blood circulation. Part I: model derivation”, arXiv (2020) https://arxiv.org/abs/2011.15040

Parameters:

• parameters (dict[str, Any] | None, optional) – Parameters used in the model, by default None which uses the default parameters

• p_LV_func (Callable[[float, float], float] | None, optional) – Optional function to calculate the pressure in the LV, by default None. The function should take the volume in the LV as the first argument and the time as the second argument, and return the pressure in the LV

• p_BiV_func (Callable[[float, float, float], float] | None, optional) – Optional function to calculate the pressure in the LV and RV, by default None. The function should take the volume in the LV as the first argument, the volume in the RV as the second argument, and the time as the third argument, and return a tuple (plv, prv) with the pressures in the LV and RV.

• add_units (bool, optional) – Add units to the parameters, by default False. Note that adding units will drastically slow down the simulation, so it is recommended to use this only for testing purposes.

• callback (base.CallBack | None, optional) – Optional callback function, by default None. The callback function takes three arguments: the model, the current time, and a boolean flag save which indicates if the current state should be saved.

• verbose (bool, optional) – Print additional information, by default False

• comm (mpi4py.MPI_InterComm optional) – MPI communicator, by default None

• outdir (Path, optional) – Output directory, by default Path(“results-regazzoni”)

• initial_state (dict[str, float] | None, optional) – Initial state of the model, by default None which uses the default initial state

property HR: float

Heart rate

zenker

class circulation.zenker.Zenker(parameters: dict[str, float] | None = None, **kwargs)

Zenker model [1] of the circulation system to model hemorragic shock.

[1]

Zenker, S., Rubin, J., & Clermont, G. (2007). From inverse problems in mathematical physiology to quantitative differential diagnoses. PLoS computational biology, 3(11), e204. https://doi.org/10.1371/journal.pcbi.0030204

property HR

Heart rate

bestel

Bestel model for active stress and pressure {cite}`bestel2001biomechanical

class circulation.bestel.BestelActivation(parameters: dict[str, float] = <factory>)

Active stress model from the Bestel model [3].

Parameters:

• t_span (tuple[float, float]) – A tuple representing start and end of time

• parameters (dict[str, float]) – Parameters used in the model, see default_parameters()

• t_eval (np.ndarray, optional) – Time points to evaluate the solution, by default None. If not provided, the default points from scipy.integrate.solve_ivp will be used

Returns:

An array of activation points

Return type:

np.ndarray

Notes

The active stress is taken from Bestel et al. [3], characterized through a time-dependent stress function \(\tau\) solution to the evolution equation

\[\dot{\tau}(t) = -|a(t)|\tau(t) + \sigma_0|a(t)|_+\]

with \(a(\cdot)\) being the activation function and sigma_0 contractility, where each remaining term is described below:

\[\begin{split}|a(t)|_+ =& \mathrm{max}\{a(t), 0\} \\ a(t) :=& \alpha_{\mathrm{max}} \cdot f(t) + \alpha_{\mathrm{min}} \cdot (1 - f(t)) \\ f(t) =& S^+(t - t_{\mathrm{sys}}) \cdot S^-(t - t_{\mathrm{dias}}) \\ S^{\pm}(\Delta t) =& \frac{1}{2}(1 \pm \mathrm{tanh}(\frac{\Delta t}{\gamma}))\end{split}\]

[3] (1,2,3)

J. Bestel, F. Clement, and M. Sorine. “A Biomechanical Model of Muscle Contraction. In: Medical Image Computing and Computer-Assisted Intervention - MICCAI 2001. Springer Berlin Heidelberg, 2001, pp. 1159{1161.

static default_parameters() → dict[str, float]

Default parameters for the activation model

Returns:

Default parameters

Return type:

dict[str, float]

Notes

The default parameters are

\[\begin{split}t_{\mathrm{sys}} &= 0.16 \\ t_{\mathrm{dias}} &= 0.484 \\ \gamma &= 0.005 \\ a_{\mathrm{max}} &= 5.0 \\ a_{\mathrm{min}} &= -30.0 \\ \sigma_0 &= 150e3 \\\end{split}\]

class circulation.bestel.BestelPressure(parameters: dict[str, float] = <factory>)

Time-dependent pressure derived from the Bestel model [3].

Parameters:

• t_span (tuple[float, float]) – A tuple representing start and end of time

• parameters (dict[str, float]) – Parameters used in the model, see default_parameters()

• t_eval (np.ndarray, optional) – Time points to evaluate the solution, by default None. If not provided, the default points from scipy.integrate.solve_ivp will be used

Returns:

An array of pressure points

Return type:

np.ndarray

Notes

We consider a time-dependent pressure derived from the Bestel model. The solution \(p = p(t)\) is characterized as solution to the evolution equation

\[\dot{p}(t) = -|b(t)|p(t) + \sigma_{\mathrm{mid}}|b(t)|_+ + \sigma_{\mathrm{pre}}|g_{\mathrm{pre}}(t)|\]

with \(b(\cdot)\) being the activation function described below:

\[\begin{split}b(t) =& a_{\mathrm{pre}}(t) + \alpha_{\mathrm{pre}}g_{\mathrm{pre}}(t) + \alpha_{\mathrm{mid}} \\ a_{\mathrm{pre}}(t) :=& \alpha_{\mathrm{max}} \cdot f_{\mathrm{pre}}(t) + \alpha_{\mathrm{min}} \cdot (1 - f_{\mathrm{pre}}(t)) \\ f_{\mathrm{pre}}(t) =& S^+(t - t_{\mathrm{sys}-\mathrm{pre}}) \cdot S^-(t t_{\mathrm{dias} - \mathrm{pre}}) \\ g_{\mathrm{pre}}(t) =& S^-(t - t_{\mathrm{dias} - \mathrm{pre}})\end{split}\]

with \(S^{\pm}\) given by

\[S^{\pm}(\Delta t) = \frac{1}{2}(1 \pm \mathrm{tanh}(\frac{\Delta t}{\gamma}))\]

static default_lv_parameters() → dict[str, float]

Default parameters for the LV pressure model in BiV model

Returns:

Default parameters

Return type:

dict[str, float]

Notes

The default parameters are

\[\begin{split}t_{\mathrm{sys} - \mathrm{pre}} &= 0.17 \\ t_{\mathrm{dias} - \mathrm{pre}} &= 0.484 \\ \gamma &= 0.005 \\ a_{\mathrm{max}} &= 5.0 \\ a_{\mathrm{min}} &= -30.0 \\ \alpha_{\mathrm{pre}} &= 5.0 \\ \alpha_{\mathrm{mid}} &= 15.0 \\ \sigma_{\mathrm{pre}} &= 12000.0 \\ \sigma_{\mathrm{mid}} &= 16000.0 \\\end{split}\]

static default_parameters() → dict[str, float]

Default parameters for the pressure model for LV only

Returns:

Default parameters

Return type:

dict[str, float]

Notes

The default parameters are

\[\begin{split}t_{\mathrm{sys} - \mathrm{pre}} &= 0.17 \\ t_{\mathrm{dias} - \mathrm{pre}} &= 0.484 \\ \gamma &= 0.005 \\ a_{\mathrm{max}} &= 5.0 \\ a_{\mathrm{min}} &= -30.0 \\ \alpha_{\mathrm{pre}} &= 5.0 \\ \alpha_{\mathrm{mid}} &= 1.0 \\ \sigma_{\mathrm{pre}} &= 7000.0 \\ \sigma_{\mathrm{mid}} &= 16000.0 \\\end{split}\]

static default_rv_parameters() → dict[str, float]

Default parameters for the RV pressure model in BiV model

Returns:

Default parameters

Return type:

Dict[str, float]

Notes

The default parameters are

\[\begin{split}t_{\mathrm{sys} - \mathrm{pre}} &= 0.17 \\ t_{\mathrm{dias} - \mathrm{pre}} &= 0.484 \\ \gamma &= 0.005 \\ a_{\mathrm{max}} &= 5.0 \\ a_{\mathrm{min}} &= -30.0 \\ \alpha_{\mathrm{pre}} &= 5.0 \\ \alpha_{\mathrm{mid}} &= 10.0 \\ \sigma_{\mathrm{pre}} &= 3000.0 \\ \sigma_{\mathrm{mid}} &= 4000.0 \\\end{split}\]