Merge pull request #37 from ankushaggarwal/examples

Added examples for the documentation

Examples/layered-tube.ipynb

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "958f0ccc-707d-483c-acde-858f8d91bc41",
+   "metadata": {},
+   "source": [
+    "# Simulating inflation of a three-layered artery"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -12,6 +20,22 @@
     "import numpy as np"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8fa2632e-9962-4cc0-aa18-3e2ed76f2782",
+   "metadata": {},
+   "source": [
+    "## Creating three separate layers"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24724252-d94d-4a0b-8bf9-3b36e7906311",
+   "metadata": {},
+   "source": [
+    "It is well-documented that arteries are made up of three layers: intima, media, and adventitia. These layers have distinct material properties with different fiber directions.  So, we start by creating materials for three layers with defined material parameters (taken from https://doi.org/10.1016/j.jmbbm.2020.104070) and defining the three fiber angles."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
@@ -49,6 +73,14 @@
     "adventitia.parameters = params\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8ffb2395-0af2-4f1a-9949-e73d0b6bb334",
+   "metadata": {},
+   "source": [
+    "Next, we create a tube for the intima using the intima material and specify the fiber angles."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -84,6 +116,14 @@
     "print(params_tube1)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "66365501-f10c-4a86-815e-c9b402ad7412",
+   "metadata": {},
+   "source": [
+    "The default geometric values (radius, thickness, and opening angle) need to be changed to the actual ones. Length and longitudinal stretch are kept as default. The reference (open) radius is calculated from the closed radius and the opening angle (which is assumed to be 90 degrees). Lastly, we calculate the radius at pressures of 0, 10 and 15 (load-free, diastolic, and systolic). However, this is only intima on its own. Of more interest is when the three layers will be put together."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 4,
@@ -144,6 +184,14 @@
     "tube1.parameters"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3567599b-7958-42ca-b0a9-91bdbb2b8d1c",
+   "metadata": {},
+   "source": [
+    "Similarly, we create the tube for media. The radius and opening angle are assumed to be the same, but the thickness is higher than intima."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 6,
@@ -192,6 +240,14 @@
     "tube2.parameters"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "28f78af3-1b88-4388-9ca5-988868119493",
+   "metadata": {},
+   "source": [
+    "Again, we can calculate the radius at the three pressures if the adventitia was on its own. Note that since the `disp_measure` is radius, which will expect to take at a value of around 6 at zero pressure, we specify the initial guess to be 6 to speed up (and ensure) the convergence. Otherwise, a default initial guess of 1 will be used, which might be too far to converge."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 7,
@@ -213,6 +269,14 @@
     "tube2.force_controlled([0,10,15],params_tube1,x0=6)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "99bec8a9-0ebb-4fd3-94a1-169ff056e778",
+   "metadata": {},
+   "source": [
+    "Lastly, we create a tube of the adventitia, assuming the radius and opening angle to be the same."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 9,
@@ -261,6 +325,22 @@
     "tube3.parameters"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "5236a719-d176-4802-9af9-28eaf52bff39",
+   "metadata": {},
+   "source": [
+    "## Simulating combined layers"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4a4515d7-f4cf-45aa-949e-a0d54933ea8a",
+   "metadata": {},
+   "source": [
+    "Now, we put the three tubes into a `LayeredTube` with a simple interface to create a complete artery. When we check the parameters of the `artery` we see that it contains that of each layer with a subscript `_layer*`."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 10,
@@ -313,6 +393,14 @@
     "artery.parameters"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "42a8ae03-21d8-42da-a5dc-fdcc9add21b0",
+   "metadata": {},
+   "source": [
+    "On this layered-structure, we can do the simulation just like the regular one, either with a `disp_controlled` or a `force_controlled`."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 11,
@@ -334,6 +422,14 @@
     "artery.force_controlled(np.array([0,10,15]),x0=6)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "0ad5e38f-64e1-49bd-8cc2-f38e861a8bee",
+   "metadata": {},
+   "source": [
+    "Lastly, we can calculate the Cauchy stress tensor through the thickness of the artery at a given internal radius (which is equal to the value we calculated at a pressure of 15). It returns a tuple of normalized thickness `xi` and a list of stresses `stress`."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 12,
@@ -344,6 +440,14 @@
     "xi,stress = artery.cauchy_stress(6.97341844)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "dfdfc126-a173-4a5e-a471-6196733a5650",
+   "metadata": {},
+   "source": [
+    "To visualize the results, we calculate the von-Mises stress for each tensor in the list `stress` and then plot it. We note the jump in stress at the interface, which is because of the incompatible reference states of the three layers. Note that here the reference state of each layer is the same (same radius and opening angle), however they are still incompatible, since for compatibility, the outer radius of innermost layer should be equal to the inner radius of the next layer, and so on."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -374,14 +478,6 @@
     "ax.set_ylabel('von-Mises stress (kPa)')\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "bf6e4c6b-9039-41ab-81e6-96e08924153f",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {