Create parameters description in the documentation

.github/workflows/test.yml

@@ -7,26 +7,60 @@ on:
 env:
   apt_options: -o Acquire::Retries=3
   PETSC_DIR: /usr/lib/petscdir/petsc3.15/x86_64-linux-gnu-real
+  PETSC_VERSION: "3.15.1"
+  PYTHON_VERSION: "3.11"
 jobs:
   test:
     name: Build and test the contribution
     runs-on: ubuntu-latest
     steps:
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+
     - name: Setup MPI
       uses: mpi4py/setup-mpi@v1
       with:
         mpi: openmpi
+
     - name: Checkout repository
-      uses: actions/checkout@v3
-    - name: Install system packages
+      uses: actions/checkout@v4
+
+    - name: Install system packages for MPI and PETSc
       run: |
-        sudo apt-get ${{env.apt_options}} update -y
-        sudo apt-get ${{env.apt_options}} install python3-petsc4py python3-mpi4py libopenmpi-dev libpetsc-real3.15-dev
-    - name: Install test dependencies
+        sudo apt-get ${{ env.apt_options }} update -y
+        sudo apt-get ${{ env.apt_options }} install libopenmpi-dev libpetsc-real3.15-dev
+    - name: Install petsc4py and other test dependencies
       run: |
         python -m pip install --upgrade pip setuptools
         python -m pip install tox-gh-actions
+
+    - name: Cache petsc4py build
+      id: cache-petsc4py
+      uses: actions/cache@v3
+      env:
+        cache-name: cache-petsc4py
+      with:
+        path: venv
+        key: ${{ runner.os }}-build-${{ env.cache-name}}-${{ env.PETSC_VERSION }}-py${{ env.PYTHON_VERSION }}
+
+    # FIXME Once PETSc is updated to a more reasonable version, one should attempt to
+    # build a wheel instead of installing into a virtual environment.  This wheel can then
+    # be referred to directly in Tox, and we can avoid passing PYTHONPATH around.
+    - name: Build petsc4py
+      if: steps.cache-petsc4py.outputs.cache-hit != 'true'
+      run: |
+        python -m venv venv
+        . ./venv/bin/activate
+        python -m pip install --upgrade pip setuptools wheel
+        python -m pip install "cython<3" numpy
+        git clone --branch "v${{ env.PETSC_VERSION }}" --depth 1 https://gitlab.com/petsc/petsc.git
+        cd petsc/src/binding/petsc4py
+        python -m pip install .
+
     - name: Run tox
-      run: tox
+      run: |
+        tox -e py${{ env.PYTHON_VERSION }}
       env:
-        PYTHONPATH: ${{env.PETSC_DIR}}/lib/python3/dist-packages
+        PYTHONPATH: ${{ github.workspace }}/venv/lib/python${{ env.PYTHON_VERSION }}/site-packages

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
         args: ["-x", ".codespellignorelines"]
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.3.2
+    rev: v0.3.7
     hooks:
       # Run the linter.
       - id: ruff

.readthedocs.yaml

@@ -3,16 +3,11 @@ build:
   os: ubuntu-22.04
   apt_packages:
   - libopenmpi-dev
-  - libpetsc-real3.15-dev
   tools:
     python: "3.11"
 python:
   install:
-  # petsc4py doesn't explicitly declare its dependencies
-  # they need to be installed beforehand
-  - requirements: docs/requirements-petsc4py.txt
-  # astrovascpy doesn't explicitly declare its dependence on petsc4py
-  # it needs to be installed beforehand
+  # Markdown conversion requires a particular version of docutils
   - requirements: docs/requirements.txt
   - method: pip
     path: .

README.md

@@ -1,4 +1,5 @@
 ![AstroVascPy Logo](docs/source/logo/BBP-AstroVascPy-Github.jpg)
+
 # AstroVascPy
 
 AstroVascPy is a Python library for computing the blood pressure and flow through the vasculature

astrovascpy/bloodflow.py

@@ -86,7 +86,7 @@ def update_static_flow_pressure(
     Args:
         graph (utils.Graph): graph containing point vasculature skeleton.
         input_flow(numpy.array): input flow for each graph node.
-        params (dict): general parameters for vasculature.
+        params (typing.VasculatureParams): general parameters for vasculature.
         with_hematocrit (bool): consider hematrocrit for resistance model
 
     Concerns: This function is part of the public API. Any change of signature
@@ -97,7 +97,7 @@ def update_static_flow_pressure(
     if graph is not None:
         if not isinstance(graph, Graph):
             raise BloodFlowError("'graph' parameter must be an instance of Graph")
-        for param in VasculatureParams.__annotations__:
+        for param in VasculatureParams.__required_keys__:
             if param not in params:
                 raise BloodFlowError(f"Missing parameter '{param}'")
         blood_viscosity = params["blood_viscosity"]
@@ -426,7 +426,7 @@ def simulate_vasodilation_ou_process(graph, dt, nb_iteration, nb_iteration_noise
         dt (float): time-step.
         nb_iteration (int): number of iteration.
         nb_iteration_noise (int): number of time steps with non-zero noise.
-        params (dict): general parameters for vasculature.
+        params (typing.VasculatureParams): general parameters for vasculature.
 
 
     Returns:
@@ -436,13 +436,13 @@ def simulate_vasodilation_ou_process(graph, dt, nb_iteration, nb_iteration_noise
     radii_at_endfeet = []  # matrix: rows = number of radii, columns = time points
 
     # constant c for capillaries and arteries
-    c_cap = 2.8
-    c_art = 2.8
-
-    # Uncomment the following if we want to fit the mean value.
-    # Remark:  it is not possible to fit mean value and max value at same time
-    # c_cap = np.sqrt(2/np.pi) * (params["max_r_capill"] - 1) / (params["mean_r_capill"] - 1)
-    # c_art = np.sqrt(2/np.pi) * (params["max_r_artery"] - 1) / (params["mean_r_artery"] - 1)
+    C_CAP = params.get("c_cap", 2.8)
+    C_ART = params.get("c_art", 2.8)
+    THRESHOLD_R = params.get("threshold_r", 3)
+    MAX_R_CAPILL = params.get("max_r_capill", 1.38)
+    T_2_MAX_CAPILL = params.get("t_2_max_capill", 2.7)
+    MAX_R_ARTERY = params.get("max_r_artery", 1.23)
+    T_2_MAX_ARTERY = params.get("t_2_max_artery", 3.3)
 
     kappa_c, sigma_c = None, None
     kappa_a, sigma_a = None, None
@@ -453,17 +453,17 @@ def simulate_vasodilation_ou_process(graph, dt, nb_iteration, nb_iteration_noise
         # calibrate kappa for capillaries
         # We calibrate only for the first radius.
         try:
-            r0_c = ge[ge <= params["threshold_r"]].iloc[0]
-            x_max_c = r0_c * (params["max_r_capill"] - 1)
-            kappa_c, sigma_c = ou.compute_OU_params(params["t_2_max_capill"], x_max_c, c_cap)
+            r0_c = ge[ge <= THRESHOLD_R].iloc[0]
+            x_max_c = r0_c * (MAX_R_CAPILL - 1)
+            kappa_c, sigma_c = ou.compute_OU_params(T_2_MAX_CAPILL, x_max_c, C_CAP)
         except IndexError:
             kappa_c = None
         print("kappa for capillaries: ", kappa_c)
         # calibrate kappa for arteries
         try:
-            r0_a = ge[ge > params["threshold_r"]].iloc[0]
-            x_max_a = r0_a * (params["max_r_artery"] - 1)
-            kappa_a, sigma_a = ou.compute_OU_params(params["t_2_max_artery"], x_max_a, c_art)
+            r0_a = ge[ge > THRESHOLD_R].iloc[0]
+            x_max_a = r0_a * (MAX_R_ARTERY - 1)
+            kappa_a, sigma_a = ou.compute_OU_params(T_2_MAX_ARTERY, x_max_a, C_ART)
         except IndexError:
             kappa_a = None
         print("kappa for arteries: ", kappa_a)
@@ -490,14 +490,14 @@ def simulate_vasodilation_ou_process(graph, dt, nb_iteration, nb_iteration_noise
         if endfeet_id_ == -1:
             continue
 
-        if radius_origin_ <= params["threshold_r"]:
-            x_max = radius_origin_ * (params["max_r_capill"] - 1)
+        if radius_origin_ <= THRESHOLD_R:
+            x_max = radius_origin_ * (MAX_R_CAPILL - 1)
             kappa = kappa_c
-            sigma = x_max * sqrt_kappa_c / c_cap
+            sigma = x_max * sqrt_kappa_c / C_CAP
         else:
-            x_max = radius_origin_ * (params["max_r_artery"] - 1)
+            x_max = radius_origin_ * (MAX_R_ARTERY - 1)
             kappa = kappa_a
-            sigma = x_max * sqrt_kappa_a / c_art
+            sigma = x_max * sqrt_kappa_a / C_ART
 
         radii_process = radius_origin_ + ou.ornstein_uhlenbeck_process(
             kappa, sigma, dt, nb_iteration, nb_iteration_noise, seed
@@ -541,13 +541,12 @@ def simulate_ou_process(
 
     Args:
         graph (utils.Graph): graph containing point vasculature skeleton.
-        params (dict): general parameters for vasculature.
         entry_nodes (numpy.array:): (nb_entry_nodes,) ids of entry_nodes.
         simulation_time (float): total time of the simulation, in seconds.
         relaxation_start (float): time at which the noise is set to zero.
         time_step (float): size of the time-step.
         entry_speed (numpy.array); speed vector on the entry nodes.
-        params (dict): general parameters for vasculature.
+        params (typing.VasculatureParams): general parameters for vasculature.
 
     Returns:
         tuple of 3 elements:
@@ -641,7 +640,7 @@ def _solve_linear(laplacian, input_flow, params=None):
     Args:
         laplacian (scipy.sparse.csc_matrix): laplacian matrix associated to the graph.
         input_flow(scipy.sparse.lil_matrix): input flow for each graph node.
-        params (dict): general parameters for vasculature.
+        params (typing.VasculatureParams): general parameters for vasculature.
 
     Returns:
         scipy.sparse.csc_matrix: frequency dependent laplacian matrix

astrovascpy/typing.py

@@ -14,7 +14,7 @@
 """
 
 import enum
-import typing
+from typing import NotRequired, TypedDict
 
 
 class VasculatureAxis(enum.IntEnum):
@@ -23,9 +23,49 @@ class VasculatureAxis(enum.IntEnum):
     Z = 2
 
 
-class VasculatureParams(typing.TypedDict):
+class VasculatureParams(TypedDict):
+    """
+    Required parameters used in the model:
+
+    |  vasc_axis: vasculature axis corresponding to x, y, or z. Should be set to 0, 1, or 2.
+    |  depth_ratio: depth along the vasc_axis. This is the portion of the vasculature where there are inputs.
+    |  max_nb_inputs: maximum number of entry nodes where we inject the flow into the vasculature. Should be >= 1.
+    |  blood_viscosity: plasma viscosity in g.µm^-1.s^-1
+    |  base_pressure: reference pressure in g * um^{-1} * s^{-2}. At resting state equal to the external pressure
+
+    Stochastic simulation parameters (optional):
+
+    |  threshold_r: radius (µm) threshold. A radius smaller than the threshold is considered a capillary. A radius bigger than the threshold is considered an artery.
+
+    |  c_cap: constant used in the ROU parameter calibration for capillaries
+    |  c_art: constant used in the ROU parameter calibration for arteries
+
+    |  max_r_capill: max radius change factor for capillaries
+    |  t_2_max_capill: time (in seconds) to reach r_max from 0 for capillaries
+    |  max_r_artery: max radius change factor for arteries
+    |  t_2_max_artery: time (in seconds) to reach r_max from 0 for arteries
+
+    PETSc Linear solver parameters (optional):
+
+    |  solver: iterative linear solver used by PETSc
+    |  max_it: maximum number of solver iterations
+    |  r_tol: relative tolerance
+    """
+
     max_nb_inputs: int
     depth_ratio: float
     vasc_axis: VasculatureAxis
     blood_viscosity: float
     base_pressure: float
+
+    c_cap: NotRequired[float]
+    c_art: NotRequired[float]
+    threshold_r: NotRequired[float]
+    max_r_capill: NotRequired[float]
+    t_2_max_capill: NotRequired[float]
+    max_r_artery: NotRequired[float]
+    t_2_max_artery: NotRequired[float]
+
+    solver: NotRequired[str]
+    max_it: NotRequired[int]
+    r_tol: NotRequired[float]

astrovascpy/utils.py

@@ -322,7 +322,7 @@ def create_entry_largest_nodes(graph: Graph, params: VasculatureParams):
 
     Args:
         graph (Graph): graph containing point vasculature skeleton.
-        params (dict): general parameters for vasculature.
+        params (typing.VasculatureParams): general parameters for vasculature.
 
     Returns:
         numpy.array: (1,) Ids of the largest nodes.
@@ -336,7 +336,7 @@ def create_entry_largest_nodes(graph: Graph, params: VasculatureParams):
     if graph is not None:
         if not isinstance(graph, Graph):
             raise BloodFlowError("'graph' parameter must be an instance of Graph")
-        for param in VasculatureParams.__annotations__:
+        for param in VasculatureParams.__required_keys__:
             if param not in params:
                 raise BloodFlowError(f"Missing parameter '{param}'")
         n_nodes = params["max_nb_inputs"]

docs/requirements.txt

@@ -1 +1 @@
-petsc4py==3.15
+docutils==0.19

docs/source/api_ref.rst

@@ -15,5 +15,6 @@ This page presents the complete API documentation.
     astrovascpy.report_reader
     astrovascpy.report_writer
     astrovascpy.scipy_petsc_conversions
+    astrovascpy.typing
     astrovascpy.utils
     astrovascpy.vtk_io

docs/source/conf.py

@@ -10,14 +10,14 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
-from pkg_resources import get_distribution
+from importlib.metadata import version as get_version
 
 # -- Project information -----------------------------------------------------
 
 project = "AstroVascPy"
 
 # The short X.Y version
-version = get_distribution("AstroVascPy").version
+version = get_version(project)
 
 # The full version, including alpha/beta/rc tags
 release = version
@@ -79,6 +79,7 @@
     "members": True,
     "show-inheritance": True,
 }
+autodoc_mock_imports = ["petsc4py"]
 
 intersphinx_mapping = {
     # Uncomment these lines if you need them

docs/source/index.rst

@@ -1,13 +1,13 @@
-.. mdinclude:: ../../README.md
-
 .. image:: /logo/BBP-AstroVascPy-Github.jpg
 
-is a Python library for computing the blood pressure and flow through a large vasculature network, incorporating the effect
-of astrocytic endfeet on the blood vessels radii.
+.. mdinclude:: ../../README.md
+   :start-line: 2
+
+Contents
+------------
 
 .. toctree::
-   :hidden:
    :maxdepth: 2
 
    Home <self>
-   installation
+   api_ref

examples/data/params.yaml

@@ -18,14 +18,15 @@ threshold_r: 3  # Radius (in micro-meters) threshold.
 # A radius smaller than the threshold is considered a capillary.
 # A radius bigger than the threshold is considered an artery.
 
+c_cap: 2.8    # constant used in the ROU parameter calibration for capillaries
+c_art: 2.8    # constant used in the ROU parameter calibration for arteries
+
 # Capillaries
 max_r_capill: 1.38   # max radius change factor
-mean_r_capill: 1.09  # mean radius change factor
 t_2_max_capill: 2.7  # time (in seconds) to reach r_max from 0
 
 # Arteries
 max_r_artery: 1.23   # max radius change factor
-mean_r_artery: 1.11  # mean radius change factor
 t_2_max_artery: 3.3  # time (in seconds) to reach r_max from 0
 
 # PETSc Linear solver

setup.py

@@ -61,7 +61,7 @@
     },
     license="Apache-2",
     packages=find_namespace_packages(include=["astrovascpy*"]),
-    python_requires=">=3.10",
+    python_requires=">=3.11",
     version=VERSION,
     install_requires=reqs,
     extras_require={