ModularCirc

The scope of this package is to provide a framework for building 0D models and simulating cardiovascular flow and mechanics. Conceptually, the models can be split into three types of components:

1. Heart chambers
2. Valves
3. Vessels

The current version of the published package contains two models:

1. Naghavi model.
2. Korakianitis Mixed model.

For other models currently under development, see the dev branch.

Setup Conda or python virtual environment

Before installation of the ModularCirc package, please setup a virtual environment using either Conda or python virtual environment.

Conda setup

Install Conda from https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html

Run:

conda create --name <yourenvname>
conda activate <yourenvname>

Proceed to installing the ModularCirc package.

Python virtual environment setup

Run python3 -m venv venv. This creates a virtual environment called venv in your base directory.

Activate the python environment: source venv/bin/activate

Proceed to installing the ModularCirc package.

Installing ModularCirc

pip install

To install the pip package:

python -m pip install ModularCirc

Installation from source:

Clone the ModularCirc GitHub repo locally.

Run:

git clone https://github.com/alan-turing-institute/ModularCirc
cd ModularCirc

After downloading the GitHub repository, from the repo directory run:

pip install ./

This will install the package based on the pyproject.toml file specifications.

Steps for running basic models

1. Load the classes for the model of interest and the parameter object used to paramterise the said model:

from ModularCirc.Models.NaghaviModel import NaghaviModel, NaghaviModelParameters

2. Load the ODE system solver class object:

from ModularCirc.Solver import Solver

3. Define a dictionary for parameterising the temporal discretization:

TEMPLATE_TIME_SETUP_DICT = {
    'name'       :  'TimeTest',
    'ncycles'    :  40,
    'tcycle'     :  1.0,
    'dt'         :  0.001,
    'export_min' :  1
 }

Here, ncycles indicates the maximum number of heart cycles to run, before the simulation finishes. If the simulation reaches steady state faster than that, the simulation will end provided the number of cycles is higher than export_min. tcycle indicates the duration of the heart beat and dt represent the time step size used in the temporal discretization. These measurements assume that time is measured in seconds. If the units used are different, ensure this is done consistently in line with other parameters.

4. Create an instance of the parameter object and used it to change the default values:

parobj = NaghaviModelParameters()

Note 4.1: the model and parameter object classes are usually defined in pairs and, as such using mismatched types may cause the simulation to behave unexpectedly or may result in a crash.

Note 4.2: the method used to parameterise components is typically dependent on the component type, see for example: set_chamber_comp, set_rc_comp or set_activation_function.

5. Create an instance of the model:

model = NaghaviModel(time_setup_dict=TEMPLATE_TIME_SETUP_DICT, parobj=parobj)

6. Create an instace of the solver used to peform the simulation:

solver = Solver(model=model)
solver.setup()

7. Run the simulation

solver.solve()

8. Extract the state variable values of interest.

v_lv = solver.model.components['lv'].V.values
p_lv = solver.model.components['lv'].P_i.values

Example values pv loops for all 4 chambers: