Documentation for Release 2024.2

User tutorials

Note

If you are viewing this on the Chaste website, the tutorials here are automatically updated to work with the latest development version of Chaste. They are not guaranteed to work with any release version, in fact they are unlikely to! If you are working with a release version of the code then this page is archived upon releases; the tutorials corresponding to each release version of Chaste can be found on the releases page.

The basics

These tutorials assume prior knowledge or understanding of various C++ language features and some libraries, including (at least): std::vectors, c_vectors, and object-oriented inheritance including abstract classes and virtual methods.

If you don’t know anything about these we recommend a first course in C++, there are plenty online (here is one from cplusplus.com). There is also a Scientific Computing in C++ book by some of our team available too.

To run any of these tutorials, it is assumed you have first configured Chaste using CMake:

cmake /path/to/chaste/src

Then, run

make <NAME_OF_TUTORIAL_FILE>

(without the .hpp on the end) to compile the tutorial source code, and

ctest -V -R <NAME_OF_TUTORIAL_FILE>

to run it. The -V is a flag to give verbose output, i.e. show the full output from the test on screen. The -R allows you to run all tests matching a ‘regular expression’, if you don’t know what that means don’t worry, if you just write the full tutorial class name it tells ctest to run that one in particular.

For instance:

make TestSolvingOdesTutorial
ctest -V -R TestSolvingOdesTutorial

Where’s my file output?

By default, Chaste will attempt to write any file output from tests and tutorials to the subdirectory testoutput of the build directory (the directory that you run cmake from).

It is recommended to redirect the output to a more permanent folder of your choosing. To do this you set an environment variable called CHASTE_TEST_OUTPUT in the terminal. We also recommend that you set this automatically and globally whenever you log in by adding a line like

export CHASTE_TEST_OUTPUT=/path/where/I/want/Chaste/to/write/files

to the bottom of your terminal login script (this should be in the file ~/.bashrc if you are using a bash terminal, e.g. on Ubuntu or the Chaste Docker based on ubuntu. It could be ~/.zshrc on a Mac). The Chaste docker has CHASTE_TEST_OUTPUT set by default to a sensible output location.

The tutorials below will refer to $CHASTE_TEST_OUTPUT whether or not it is set. So if you aren’t sure where test output is, just type

echo $CHASTE_TEST_OUTPUT

in a terminal and it will return either a directory path or nothing – in which case look in the subdirectory testoutput of the build directory.

Before you do anything else

Core functionality

Solving ODEs

Solving PDEs

Writing new PDE solvers (advanced)

Solid Mechanics

Command line functionality

Cardiac

Executable users

The cardiac executable is a compiled CardiacSimulation object that uses an XML file to specify the settings that C++ users would do via HeartConfig. It is therefore a bit easier to use but less flexible than using Chaste classes via C++.

  • UserTutorials/CardiacExecutable - a submenu with links to various tutorials for users of the cardiac executable binary where settings are specified via an XML file (not the source code).

Single Cardiac Cell Simulations

Mono/Biodomain Simulations

Checkpointing (saving/loading)

Electro-mechanics

Cell-based

Where to start with cell-based simulations:

Running basic simulation types:

Running crypt-specific simulations:

More advanced examples:

Adding new functionality:

To do new things in Chaste that haven’t been coded before you’ll often have to add your own new C++ classes. Here are a set of examples to use as a basis for that.

Lung

Generation and manipulation of airway geometries

Simulating ventilation and impedance