Skip to content

Getting Started

Prerequisites

  • Python 3.9 or newer recommended (the package requires Python ≥3.7 per pyproject.toml; use the same interpreter for the whole project).
  • Git, to clone the repository.
  • pip (usually bundled with Python).
  • MPI (optional): needed only if you run parameter identification or sensitivity analysis with multiple processes. See MPI and system libraries below.
  • Compiler / SUNDIALS (optional on Linux): Myokit’s CVODE backend may need build-essential and libsundials-dev (or your OS equivalent) so extensions can compile when first used.

Clone the repository

Clone the Circulatory Autogen project from the GitHub repository.

Note

If you have not used Git before: install Git, open a terminal, go to the folder where you want the code, then run:

  • git clone https://github.com/FinbarArgus/circulatory_autogen

To contribute via a fork:

  • git clone https://github.com/<YourUsername>/circulatory_autogen

  • git remote add upstream https://github.com/physiomelinks/circulatory_autogen

Directory layout

[project_dir] is the folder where the repository was cloned, for example:

[project_dir]: ~/Documents/git_projects/circulatory_autogen

The rest of this page assumes commands are run from a terminal and that [project_dir] is your current directory when installing.

Install Python libraries from pyproject.toml

Use the same Python you will use to run scripts and tests (check with python --version or python3 --version).

1. Create a virtual environment (recommended)

cd [project_dir]
python3 -m venv .venv
source .venv/bin/activate

cd [project_dir]
py -3 -m venv .venv
.venv\Scripts\activate.bat

cd [project_dir]
py -3 -m venv .venv
.venv\Scripts\Activate.ps1

If you prefer not to use a venv, skip the steps above and use python -m pip / python3 -m pip for the installs below.

2. Upgrade pip (recommended)

python -m pip install --upgrade pip

3. Install the project and dependencies

Dependencies are listed in pyproject.toml. Installing the package in editable mode pulls them in automatically.

  • Runtime only (autogeneration, parameter ID, solvers such as Myokit, etc.):

    cd [project_dir]
python -m pip install -e .

    When you choose solver: CVODE for CellML models, the project defaults that to the CVODE_myokit backend. Use CVODE_opencor explicitly only when you want the OpenCOR backend.

  • With development tools (pytest, formatters, linters):

    cd [project_dir]
python -m pip install -e ".[dev]"

The authoritative lists are [project.dependencies] and [project.optional-dependencies] in pyproject.toml. Highlights:

  • Autogeneration: pandas, pyyaml, rdflib, libcellml, pint, etc.

    libCellML is pinned below 0.7.0

    The requirement is libcellml>=0.6.3,<0.7.0. libCellML 0.7.0 renamed part of the API (Analyser.model() became Analyser.analyserModel(), and Generator.implementationCode() now takes the model and profile as arguments) and also changed generated-Python output and unit flattening. The renames are handled by shims in src/utilities/libcellml_helper_funcs.py, but the code-generation and unit changes are a real migration that has not been done yet, so the pin stays until it is.

    If you already have libCellML 0.7.0 installed, pip install -e ".[dev]" will silently downgrade it to the newest 0.6.x. That is intended — but if libCellML came from conda or a system package rather than pip, the resolver may instead fail with a version conflict that does not obviously point here. Installing into a fresh virtual environment avoids both. Lifting the pin is tracked in issue #271.

    • Parameter identification: mpi4py, nevergrad (CMA-ES), emcee, numdifftools, and related scientific stack.
    • Sensitivity analysis: SALib, seaborn.
    • Development: the dev extra (e.g. pytest, pytest-mpi).

4. Run scripts

With the venv activated (if you use one), run Python from [project_dir] as usual, for example:

python src/scripts/<script_name>.py

The shell helpers under user_run_files/*.sh may still assume a particular interpreter; if a script fails, run the matching Python module or script directly with your venv’s python.

For a notebook-oriented walkthrough, see tutorial/interactive/generate_and_calibrate.ipynb.

Optional third-party backends (not part of Circulatory Autogen)

Circulatory Autogen itself is fully open source (Apache License 2.0) and everything described in this documentation works without installing anything below.

This section describes optional, third-party software that is not part of Circulatory Autogen. It is not bundled with it, not installed by pip install -e ., not required by any feature, and not distributed under Circulatory Autogen's license. It is developed and licensed by other parties, on their terms. Circulatory Autogen merely provides an optional adapter so that users who already have a licence for such a product can plug it in. If you install one, you are entering a licensing relationship with that third party, not with this project.

AADC (Matlogica) — proprietary, optional, not included

AADC is third-party proprietary software and is NOT part of Circulatory Autogen

  • Not included, not required. AADC is not shipped with Circulatory Autogen and no feature of Circulatory Autogen depends on it. The project is fully functional, and fully open source, without it. Nothing installs it for you.
  • Not open source. AADC is a commercial product of Matlogica, distributed under Matlogica's own proprietary licence — not under Circulatory Autogen's Apache-2.0 licence, and not under any open-source licence. Its terms restrict it to academic / non-commercial use.
  • You must obtain your own licence. The Circulatory Autogen maintainers do not supply, sublicense, or broker AADC licences, and cannot support licensing issues. Read and accept Matlogica's licence terms yourself, directly with Matlogica, before installing or using it.
  • Its gradients are licence-gated at runtime. Forward simulation may run with a bare pip install aadc, but anything that records a tape — the automatic-differentiation gradients, and the on-tape damping in semi_implicit — raises RuntimeError: AADC License check failed without a valid licence.
  • Use CasADi if you want a fully open-source pipeline. CasADi (LGPL) is the default and supported AD backend and requires no proprietary licence — see model_type: casadi_python in Parameter Identification. AADC is only an optional alternative for licensed academic users; you never need it.

If, and only if, you hold a Matlogica licence and accept their terms, the optional adapter is enabled by installing the package:

python -m pip install aadc

(Into OpenCOR's Python if you run the test suite that way — see the legacy section below, e.g. [OpenCOR_dir]/pythonshell -m pip install aadc.)

and then selecting it in your user_inputs.yaml:

model_type: aadc_python
solver: aadc_semi_implicit
solver_info:
  method: adaptive_rk45   # non-stiff forward solve; see the gradient caveat below

Available solver_info.method values for the AADC adapter are adaptive_rk45 (adaptive, so accurate for a forward solve but untapeable — its step sequence depends on the parameters, so it cannot produce an AD gradient), and the fixed-step implicit_euler_ift, semi_implicit, and rk4 (the only methods that can be recorded on a tape for an AD gradient).

method: bdf was removed from the AADC adapter

AADC previously offered a bdf method. It ran the solve inside scipy.solve_ivp with AADC supplying only the RHS and its Jacobian, so the trajectory never reached the tape — and the AD tape had no bdf branch, so do_ad: true silently recorded rk4 instead, making the cost and the gradient different functions. Its RHS kernel was also taped once at t=0 with the integrator discarding t, so a time-dependent model would have been integrated with its t=0 right-hand side throughout. Setting method: bdf on an aadc_python model now raises. Use semi_implicit for stiff models — subject to the accuracy warning below — or model_type: casadi_python with method: bdf for a differentiable symbolic BDF.

AADC gradients do not work on stiff models

Only the fixed-step methods can be taped, and fixed-step schemes are inaccurate or unstable on stiff models: on the 3compartment cardiovascular model semi_implicit deviates from the CVODE reference by ~35% and implicit_euler_ift by orders of magnitude. Reducing dt does not help — semi_implicit diverges under step refinement (~35% at dt=1e-3 rising to ~280% at dt=1e-4), because its damping factor 1/(1+dt*lam) tends to 1 as dt shrinks and the scheme degenerates into explicit forward Euler on a very stiff system. The AADC backend probes the first second of dynamics and warns loudly when it detects a stiff model. For gradient-based calibration of a stiff model, use CasADi bdf or Myokit CVODES forward sensitivity instead — see Parameter Identification. AADC's tape gradient is appropriate only for non-stiff, state-observable, single-experiment problems.

MPI and system libraries

Warning

mpi4py needs an MPI implementation on the machine. On Linux you may need:

sudo apt install libopenmpi-dev openmpi-bin

On macOS, for example: brew install openmpi. On Windows, install MS MPI and the SDK, and ensure the MPI bin paths are on your PATH (see Microsoft’s documentation).

Myokit (CVODE) on Linux often needs a compiler and SUNDIALS headers, for example:

sudo apt install build-essential libsundials-dev

Expected outcome

You should now have:

  • A clone of the repository at [project_dir].
  • A Python environment (venv or global) with dependencies installed from pyproject.toml via pip install -e . or pip install -e ".[dev]".
  • The ability to run python and import the project after cd [project_dir] with your chosen interpreter.

Deprecated: OpenCOR-based setup

This section documents the older workflow that used OpenCOR’s bundled Python and python_path.sh. It is not required for the default Myokit-based path described above. Keep it only if you maintain legacy scripts or environments that still call OpenCOR’s interpreter.

OpenCOR’s pythonshell is deprecated — it will be replaced by pip install libopencor

Do not build new workflows on OpenCOR’s bundled interpreter. Once libOpenCOR is available on PyPI, the OpenCOR functionality will be obtained with a plain pip install libopencor into a normal Python environment, and pythonshell / python_path.sh / opencor_pythonshell_path.sh will be removed.

Prefer the standard pip install -e . setup above. Relying on the bundled interpreter pins you to whatever OpenCOR ships, which causes real problems — e.g. OpenCOR bundles a dual-ABI mpi4py (both an MPI.mpich.*.so and an MPI.openmpi.*.so), and the variant chosen at import time may not match the system mpiexec, aborting MPI runs with unsupported PMI version PMIx. Pin it with MPI4PY_MPIABI=openmpi (or mpich) to match your installed launcher. A pip-installed mpi4py builds against the one system MPI and has no such ambiguity.

Install OpenCOR (legacy)

Download OpenCOR (e.g. version 0.8.1) from the OpenCOR downloads page. A zip/tarball install in a directory you control (e.g. ~/Desktop) is typical.

Note

New to OpenCOR? See the OpenCOR Tutorial (PDF).

Legacy directory names

  • [OpenCOR_dir]: folder where OpenCOR is installed, e.g. ~/Desktop/OpenCOR-0-8-1-Linux/.

Info

On some HPC systems an OpenCOR tree may already exist (example path used historically: /hpc/farg967/OpenCOR-0-8-1-Linux/). Use your site’s path if applicable. See also running on hpc.

Installing packages with OpenCOR’s pip (legacy)

From [OpenCOR_dir], use OpenCOR’s pip interface instead of system Python:

Note

./pip install <packagename>

./pythonshell -m pip install <packagename>

./pythonshell.bat -m pip install <packagename>

To install this project from pyproject.toml into OpenCOR’s Python (editable):

cd [project_dir]
[OpenCOR_dir]/pip install -e .

(Use ./pythonshell -m pip / ./pythonshell.bat -m pip on Mac/Windows as above.) For development tools: pip install -e ".[dev]".

python_path.sh (legacy)

Shell scripts under user_run_files/ may read [project_dir]/user_run_files/python_path.sh. Set python_path to your OpenCOR pythonshell:

Note

python_path=<OpenCOR_dir>/pythonshell


python_path=C:\<OpenCOR_dir>\pythonshell.bat
Use Windows path conventions (C:\, backslashes).

This tutorial’s primary path no longer depends on this file if you use a normal venv and python -m pip install -e ..

OpenCOR versions before 0.8 and SSL (legacy)

Warning

In OpenCOR versions before 0.8 you may need:

cd [OpenCOR_dir]/python/bin
./python -m pip install <packagename>

Warning

If you see SSL errors with OpenCOR before version 0.8 on Linux:

cd [OpenCOR_dir]/python/bin
export LD_LIBRARY_PATH=[OpenCOR_dir]/lib

Then retry pip so libcrypto can be found.