-
To support ongoing extensions to the executable functionality, the Chaste parameters file now uses an XML
namespace to indicate which version of Chaste it is for.
This means that there are now multiple schemas in heart/src/io, one for release 1.1 and one for release 2.0.
To update your parameters XML files, simply add a namespace declaration by adding the following attributes to the root
ChasteParameters element:
xmlns="https://chaste.comlab.ox.ac.uk/nss/parameters/2_0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://chaste.comlab.ox.ac.uk/nss/parameters/2_0 ChasteParameters_2_0.xsd"
See ChasteParameters.xml in the Chaste source folder for an example. Make sure to use the correct path to the
ChasteParameters_2_0.xsd file.
Chaste should still be able to read old parameters files, but you will need to use the new version to take advantage of new features
(such as post-processing and checkpointing).
-
The cardiac executable has gained the ability to automatically load cell models encoded as CellML files at run-time, rather than needing
them to be incorporated within Chaste when it is compiled. In order to take advantage of this, you need (at present) to have built the
executable from source yourself, as it uses your Chaste source tree to convert the CellML file into runnable code.
This change means that the definition of ionic models within the parameters file has changed. To specify one of the models
included within Chaste, you now need to wrap it in a <Hardcoded> element, e.g.
<Hardcoded>FaberRudy2000</Hardcoded>
Specify a dynamically loaded model using the <Dynamic> element instead, e.g.
<Dynamic>
<Path relative_to="chaste_source_root">heart/dynamic/libDynamicallyLoadableLr91.so</Path>
</Dynamic>
The path may either point to a pre-compiled shared library (as in the example), or a CellML file. If the latter, a shared library will
be created in the same folder as the CellML file, and loaded by the executable at run-time.
See heart/test/data/xml/ChasteParametersFullFormat.xml for a full example parameters file.
Another side effect of this
is that the continuous test pack now requires the prerequisites for PyCml to be installed in order for the tests of this new functionality
to pass. See InstallPyCml for installation instructions.
-
Checkpointing functionality has now been added to the cardiac executable. This is activated by including a CheckpointSimulation
element within the Simulation element, e.g.
<CheckpointSimulation timestep="0.2" unit="ms" max_checkpoints_on_disk="3"/>
The timestep specifies how frequently to checkpoint, and must be a multiple of the printing timestep. You can, optionally,
specify the maximum number of checkpoints to keep on disk; when this limit is reached, the oldest checkpoint will be deleted before a new
checkpoint is made.
Note that making a checkpoint does add a significant overhead at present, in particular because the mesh is written out to disk at
each checkpoint. This is to ensure that each checkpoint directory contains everything needed to resume the simulation. In particular,
the mesh written out will be in permuted form if it was partitioned for a parallel simulation.
Meshes written in checkpoints use a binary form of the Triangle/Tetgen mesh format. This makes checkpoints significantly smaller but
will cause portability problems if checkpoints are moved between little-endian systems (e.g. x86) and big-endian systems (e.g. PowerPC).
Checkpoints will be written to a tree of folders adjacent to the main test output, as shown here (where <OutputDirectory> is
the folder specified by the <OutputDirectory> element):
CHASTE_TEST_OUTPUT
<OutputDirectory>
<OutputDirectory>_checkpoints
0.2ms (or whatever the timestep is set to)
<OutputDirectory> (a copy of the simulation output so far)
<OutputDirectory>_0.2ms (the checkpoint data itself)
ResumeParameters.xml (a parameters file for easy resuming from this checkpoint)
0.4ms
...
To resume from a checkpoint, copy the contents of the relevant folder (e.g. 0.2ms) into the CHASTE_TEST_OUTPUT folder,
edit the ResumeParameters.xml file to set the ArchiveDirectory correctly, and run the executable with that parameters
file.
Checkpoints may be resumed on any number of processes — you are not restricted to the number on which it was saved. However,
the mesh will not be re-partitioned if loaded on a different number of processes, so the parallel efficiency of the simulation may
be significantly reduced in this case.
Resuming a checkpoint will attempt to extend the original results h5 file, if present, so that the file contains the complete
simulation results. If this file does not exist, a new file will be created to contain just the results from the resume point.
-
What format to convert HDF5 output to can now be specified in the XML configuration file (using the OutputVisualizer element),
and hence via HeartConfig. As part of this change, the default behaviour has also changed to outputting meshalyzer data;
if you don't want this you have to explicitly turn it off. There is an unfortunate conflict between visualizer output and outputting
cell model state variables - you can't do both! Calling SetOutputVariables on HeartConfig will automatically turn off
visualizer output. If you specify OutputVariables in the XML configuration file, however, you are responsible for also including
an <OutputVisualizer meshalyzer="no"/> element.
-
Some post-processing functionality may now be specified in the XML file, using the PostProcessing element within
ChasteParameters. Four post-processing outputs are possible, corresponding to 4 child elements:
- ActionPotentialDurationMap
- UpstrokeTimeMap
- MaxUpstrokeVelocityMap
- ConductionVelocityMap
See the XML Schema documentation for more information on each of these.
-
The cardiac executable has gained the ability to specify cellular transmural heterogeneities in 3D cardiac geometries as an alternative to the heterogeneity definition with cuboids (note that the two methods cannot be used simultaneously at the moment). To take advantage of this feature the user must provide three files defining left ventricular surface (LV), right ventricular surface (RV) and epicardial surface (EPI). These three files must have the same base name as the mesh in use and must contain a list of those node indices belonging to each surface. See documentation on file formats and the XML Schema documentation for more information.
Within the CellHeterogeneities element, the user has now the ability to specify three CellHeterogeneity elements, one for the epicardial layer, one for the midmyocardial layer and one for the endocardial layer. For each layer, it is possible to define the relative thickness of it (summation of the three relative thicknesses must be one) as well as a set of three scale factors for ionic conductances (Gks, Ito and Gkr). This feature is currently supported for the following cell models: tenTusscher2006, Maleckar2009 and FaberRudy2000.
-
Chaste can optionally use the CVODE library of ODE solvers for performing single cell cardiac simulations, and also more generally
for solving ODEs. This requires a change to your hostconfig file to specify the location of the CVODE libraries; see default.py for
an example. The CvodeAdaptor class presents the same interface as other Chaste ODE solvers, but uses CVODE.
There is also a specialised cardiac cell base class AbstractCvodeCell which uses CVODE's vector type natively for better
performance. Due to this it cannot be used in tissue simulations. PyCml can generate subclasses of this class; use the --cvode option
to the helper script (python/ConvertCellModel.py) in order to do so.
-
Region attributes can be added to Triangle/Tetgen element and face/edge files.
These should be non-negative and can be retrieved with mesh.GetBoundaryElement(i)->GetRegion()
or similar. Note that (due to the default behaviour of Triangle) edges with a region attribute of zero
are ignored.
-
The majority of the output files now include a comment detailing the
version of Chaste that produced them.