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, theta: float = 0.5, reset_callback: CallBack | 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

circulation.regazzoni2020.ODE_FILE = PosixPath('/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/circulation/regazzoni2020.ode')

The same model written in gotranx’s .ode language. Kept in step with the implementation below by tests/test_regazzoni_ode_equivalence.py.

class circulation.regazzoni2020.Regazzoni2020(parameters: dict[str, Any] | None = None, p_LV: Callable[[float, float], float] | None = None, p_RV: Callable[[float, float], float] | None = None, p_BiV: Callable[[float, float, float], tuple[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, reset_callback: CallBack | 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

jac(t, y)

Returns the Jacobian of the system of equations. The Jacobian is a 2D numpy array with shape (12, 12).

circulation.regazzoni2020.VALVE_STEEPNESS = 200.0

Steepness of the smooth diode in circulation.base.smooth_heavyside(), which hard-codes it. The .ode file exposes it as a parameter, so it has to be repeated here to keep the two descriptions of the model identical.

circulation.regazzoni2020.flat_ode_parameters(parameters: dict[str, Any] | None = None) → dict[str, float]

Translate the nested parameter dictionary into .ode parameter names.

The .ode file needs a flat namespace, so parameters["circulation"]["SYS"] ["C_AR"] becomes C_AR_SYS and parameters["chambers"]["LV"]["EA"] becomes EA_LV.

Two entries are computed rather than copied. The activation offsets tC_eff_* and tR_eff_* are the contraction and relaxation onsets reduced modulo the beat length. The .ode file applies each chamber’s offset to the beat phase with a single wrap, which is exact only if both lie in [0, RR) – and the published offsets do not (tC for the atria is 0.9 s against a 0.8 s beat at the default heart rate). Reducing them here is what makes the wrap correct.

Parameters:

parameters (dict[str, Any] | None) – Nested parameters as returned by Regazzoni2020.default_parameters(), with units already removed. Defaults to the model’s own defaults.

Returns:

Keyword arguments for the generated init_parameter_values.

Return type:

dict[str, float]

zenker

class circulation.zenker.Zenker(parameters: dict[str, float | int] | 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}\]