Merge pull request #64 from alan-turing-institute/58-separate-out-tested-models

58 separate out tested models

Author: LevanBokeria

README.md

@@ -9,14 +9,11 @@ The scope of this package is to provide a framework for building **0D models** a
 2. **Valves**
 3. **Vessels**
 
-## Clone the ModularCirc GitHub repo locally
+The current version of the published package contains two models:
+1. Naghavi model.
+2. Korakianitis Mixed model.
 
-Run:
-
-```
-git clone https://github.com/alan-turing-institute/ModularCirc
-cd ModularCirc
-```
+For other models currently under development, see the `dev` branch.
 
 ## Setup Conda or python virtual environment
 
@@ -43,15 +40,26 @@ Activate the python environment: `source venv/bin/activate`
 
 Proceed to installing the ModularCirc package.
 
-## Installation
+## Installing ModularCirc
+
+### pip install
 
 To install the pip package:
 
 ```bash
-python -m pip install ModularCirc_LevanBokeria
+python -m pip install ModularCirc
 ```
 
-From source:
+### 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:
 
@@ -122,14 +130,6 @@ p_lv = solver.model.components['lv'].P_i.values
 ## Example values pv loops for all 4 chambers:
 ![Example PV loops!](Figures/PV_loops.png)
 
-## Run tests
-
-You can run locally the tests by running the following command:
-```bash
-  python -m unittest discover -s tests
-```
-there is also a autamtated test pipeline that runs the tests on every push to the repository (see [here](.github/workflows/ci.yml)).
-
 <!-- prettier-ignore-start -->
 [actions-badge]:            https://github.com/alan-turing-institute/ModularCirc/workflows/CI/badge.svg
 [actions-link]:             https://github.com/alan-turing-institute/ModularCirc/actions

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ModularCirc"
-version = "0.1.3"
+version = "0.2.0"
 authors = [
     {name = "Maximilian Balmus", email = "mbalmus@turing.ac.uk"}
 ]

src/ModularCirc/Models/README.md

@@ -1,14 +1,14 @@
 # Models directory
-This file contains the description of the model and model parameter classes defined in this module.
+This folder contains the description of the model and model parameter classes defined in this module.
 The models presented here are made of three types of components:
 - *arteries*: RLC components (complex) and R components (simple)
 - *chamber*: linear elatic (simple) and mixed (complex, linear active and exponential passive behaviour)
 - *valves*: non-ideal diodes (simple), simple Bernoulli (medium), Maynard valves (complex, where the motion the valves is modelled).
 
 ## 1. Naghavi et al. model
 Relevant files and classes:
-- `ModularCirc/Models/NaghaviModel.py`, where the `NaghaviModel` class is defined
-- `ModularCirc/Models/NaghaviModelParameters.py`, where the `NaghaviModelParameters` class is defined.
+- `src/ModularCirc/Models/NaghaviModel.py`, where the `NaghaviModel` class is defined
+- `src/ModularCirc/Models/NaghaviModelParameters.py`, where the `NaghaviModelParameters` class is defined.
 
 A CV model described in Rapid Estimation of Left Ventricular Contractility with a Physics-Informed Neural Network Inverse Modeling Approach (https://arxiv.org/html/2401.07331v1).
 The model is comprised of the following components:
@@ -24,21 +24,21 @@ The model is comprised of the following components:
 
 [<img src='Figures/NaghavidModel_circut.png'>]()
 
-## 2. Korakianitis and Shi model (V1)
+## 2. Korakianitis and Shi model
 Relevant files and classes:
-- `ModularCirc/Models/KorakianitisModel.py`, where the `KorakianitisModel` class is defined
-- `ModularCirc/Models/KorakianitisModel_parameters.py`, where the `KorakianitisModel_parameters` class is defined
+- `src/ModularCirc/Models/KorakianitisMixedModel.py`, where the `KorakianitisMixedModel` class is defined
+- `src/ModularCirc/Models/KorakianitisMixedModel_parameters.py`, where the `KorakianitisMixedModel_parameters` class is defined
 
 A simplified CV model described in A concentrated parameter model for the human cardiovascular system
 including heart valve dynamics and atrioventricular interaction (https://www.sciencedirect.com/science/article/pii/S1350453305002195?via%3Dihub).
-**Here, we simplified the model by eliminating (1) the motion of the annulus fibrosus and (2) the motion of the leaflets, replaced with a simple Bernoulli model.**
+**In KorakianitisMixedModel, we simplified the model by eliminating (1) the motion of the annulus fibrosus, (2) the motion of the leaflets, replaced with a simple Bernoulli model and (3) the cardiac chamber laws are replaced with mixed law (exponential for the passive filling and linear for contraction).**
 This model is comprised of the following components:
-- left atrium: linear time-varying elastance model
-    - **6 parameters**
+- left atrium: time-varying elastance model, based on weighted sum of passive (exponential) and active (linear) laws
+    - **7 parameters**
 - mitral valve: simple Bernoulli model
     - **2 parameters**
-- left ventricle: linear time-varying elastance model
-    - **5 parameters**
+- left ventricle: time-varying elastance model, based on weighted sum of passive (exponential) and active (linear) laws
+    - **6 parameters**
 - aortic valve: simple Bernoulli model
     - **2 parameters**
 - aortic sinus (RLC 3 component windkessel)
@@ -48,12 +48,12 @@ This model is comprised of the following components:
     - **4 parameters**
 -  systemic venous system (RLC 3 component windkessel)
     - **3 parameters** (assume that venous impedance is zero)
-- right atrium: linear time-varying elastance model
-    - **6 parameters**
+- right atrium: time-varying elastance model, based on weighted sum of passive (exponential) and active (linear) laws
+    - **7 parameters**
 - tricuspid valve: simple Bernoulli model
     - **2 parameters**
-- right ventricle: linear time-varying elastance model
-    - **5 parameters**
+- right ventricle: time-varying elastance model, based on weighted sum of passive (exponential) and active (linear) laws
+    - **6 parameters**
 - pulmonary valve: simple Bernoulli model
     - **2 parameters**
 - pulmonary artery sinus (RLC 3 component windkessel)
@@ -63,50 +63,6 @@ This model is comprised of the following components:
 - pulmonary venous system (RLC 3 component windessel)
     - **3 parameters** (assume that venous impedance is zero)
 
-**Total set of parameters sums up to 55.**
+**Total set of parameters sums up to 57.**
 
 [<img src=Figures/KorakianitisModel_circuit.png>]()
-
-
-## 3. Korakianitis and Shi model (V2)
-Relevant files and classes:
-- `ModularCirc/Models/KorakianitisMaynardModel.py`, where the `KorakianitisMaynardModel` class is defined
-- `ModularCirc/Models/KorakianitisMaynardModel_parameters.py`, where the `KorakianitisMaynardModel_parameters` class is defined
-
-This model follow the same strucutre as **Korakianitis and Shi model (V1)**, however the valves are replaced with Maynard type valves which are more similar to the ones used in the original paper.
-**This introduces 2 additional parameters per valve (one for the valve closing rate and one for the opening rate).**
-
-Components used:
-- arteries: RLC with sinuses being represented as a separate RLC component. (3/4 components)
-- valves: **Maynard** valves (4 parameters)
-- chambers: **linear models** (5/6 parameters of ventricles/arteries)
-
-**Total set of parameters sums up to 60.**
-
-
-## 4. Korakianitis and Shi model (V3)
-Relevant files and classes:
-- `ModularCirc/Models/KorakianitisMixedMaynardModel.py`, where the `KorakianitisMixedMaynardModel` class is defined
-- `ModularCirc/Models/KorakianitisMixedMaynardModel_parameters.py`, where the `KorakianitisMixedMaynardModel_parameters` class is defined.
-
-This model is again based on the orinal structure of **Korakianitis and Shi model (V1)**.
-Here, the following components were used:
-- chambers: **mixed models** (6/7 parameters of ventricles/arteries)
-- valves: **Maynard** valves (4 parameters)
-- arteries: RLC with sinuses being represented as a separate RLC component. (3/4 parameters)
-
-**Total parameter count: 64**
-
-
-## 5. Simplified Korakianitis and Shi model (V1)
-Relevant files and classes:
-- `ModularCirc/Models/MixedHeartMaynard4eWindkessel.py`, where the `MixedHeartMaynard4eWindkessel` class is defined
-- `ModularCirc/Models/MixedHeartMaynard4eWindkessel_parameters.py`, where the `MixedHeartMaynard4eWindkessel` class is defined.
-
-This model is again based on the orinal structure of **Korakianitis and Shi model (V1)**.
-Here, the following components were used:
-- chambers: **mixed models** (6/7 parameters of ventricles/arteries)
-- valves: **Maynard** valves (4 parameters)
-- arteries: RLC with sinuses represented as a separate R component and capilaries similarly by R. This equivalent to the systemic and pulmonary arterial system being simulated as 2 4-component Windkessels in series with one another.  (7/8 parameters systemic + 7/8 parameters pulmonary)
-
-**Total parameter count: 58 or 56 (if you choose to add the capilary resistance to the resistance of the previous component)**