Chaste Release Notes

• We have a new algorithm for random samples from the normal distribution in the RandomNumberGenerator, for increased stability at very large numbers of calls. Any results dependent on this will change, even with the same seed.
• "Infrastructure tests" such as checking copyright notices and for duplicate file names are now not run by default (i.e. do_inf_tests=0 is now the default setting), unless you have do_inf_tests=1 in your hostconfig file.
• Some new helper methods have been added to OutputFileHandler and FileFinder:
  • OutputFileHandler::FindFile - get a FileFinder for a file in the output directory
  • OutputFileHandler::CopyFileTo - copy a file to the output directory
  • FileFinder::GetLeafName - get the leaf name of a file
• Support has been added for Boost version 1.44. However, note that due to a bug in this Boost version, many tests will crash after they have finished running (with the message "pure virtual method called. terminate called without an active exception")!
• A new header SmartPointers.hpp has been added containing a few helpful macros for working with boost::shared_ptr.
• Created new helper classes PetscVecTools and PetscMatTools in linalg that encapsulate many of the PETSc functions we use related to vectors and matrices. This isolates much of the PETSc-version-specific code within these classes, enabling cleaner user code. If new PETSc-version-specific code is written, suitable methods should be added to these classes in preference to using PETSc directly.
• Added named attribute functionality to AbstractParameterisedSystem, allowing arbitrary real-valued attributes to be attached to ODE classes. This is used by PyCml to support named attributes on CellML models. Also added Has... methods to ODE system information, to avoid the need for try...catch statements in generic code.
• Changed the event handler classes to use MPI_Wtime rather than std::clock as underlying timer. This will give a more accurate wall clock time.
• Time adaptivity can now be implemented for PDE solvers by writing an AbstractTimeAdaptivityController subclass. TestMonodomainWithTimeAdaptivity does some very simple adaptivity to demonstrate this.
• Reduced parallel overhead associated with assembling PETSc objects. Since Chaste (almost always) ensures that data is generated only on the local process (and the helper methods in PetscVecTools and PetscMatTools enforce this), no data migration is required. We therefore by default set the PETSc option not to check whether migration is needed ({VEC,MAT}_IGNORE_OFF_PROC_ENTRIES).
• ODE solvers now inherit from Identifiable in order to provide reflection, so that the solver used can be written to results files by OdeSolution. Unfortunately, this means that on older Boost versions (<1.37) you need to include CheckpointArchiveTypes.hpp in any test which solves an ODE system to obtain an OdeSolution object, or you'll experience a segfault!

Cardiac

• New options in the XML parameters file:
  • A user may now specify a list of node indices where time traces of output variables are requested. See ChasteParametersFullFormat.xml for an example of usage and the documentation of PostProcessingWriter::WriteVariablesOverTimeAtNodes for further information. The output files (one file per output variable) will have the nodal time traces arranged in columns (gnuplot-friendly), one column per requested node. The node numbers that the user requests are referred to the original (unpermuted) node numbering (hence it may differ from what the user sees - for example - when visualizing the output of a previous parallel simulation). No matter what permutation is used in the simulation, the output of the requested nodes will be the same.
  • A new post-processing step to calculate pseudo-ECGs has been added to the Chaste parameters file: the PseudoEcgElectrodePosition element, which specifies where the virtual probe electrode should be placed. This element may occur multiple times to calculate ECGs from different probe locations. Note that probe electrodes must be located outside the heart tissue!
  • A MeshPartitioning element has been added in the Numerical parameters section, allowing you to specify how a mesh gets partitioned in parallel (dumb/metis/parmetis/petsc). This maps to the HeartConfig methods Set/GetMeshPartitioning.
  • Stimuli section can use ellipsoid regions.
• Explicit instantiation is now used for CardiacSimulationArchiver, allowing this class and CardiacSimulation to be split into .hpp and .cpp files. This improves compile times (especially for the Intel compiler) but may break some projects or tests which use checkpointing when run with older Boost versions (<1.37).
• Various improvements to cell model generation from CellML:
  • Lookup table settings (table bounds and step size) can now be modified at run-time, not just code generation time. There is a new AbstractLookupTableCollection base class for lookup tables that provides this functionality, with a get method on AbstractCardiacCellInterface that is overridden by subclasses providing tables.
  • There have been some improvements to the performance of various cell model optimisations. Some are not yet enabled by default (PyCml flags --include-dt-in-tables, --combine-commutative-tables, --no-member-vars, --pe-convert-power) and others are "unsafe in general" (PyCml flag --no-check-lt-bounds).
  • Conversion issues between cardiac cell models and Chaste are now handled in a more generic fashion within PyCml by creating an interface component. This ensures that all quantities read or written by the Chaste tissue model, including ionic currents, are in the correct units.
  • There is now a constructor options which allows the cell model converter (CellMLToSharedLibraryConverter) to save generated C++ source files for inspection.
  • A new option --expose-annotated-variables has been added to PyCml, which exposes all oxmeta-annotated variables to the GetAnyVariable functionality, i.e. it annotates non-state variables as parameters or derived quantities, as appropriate. There is also an --expose-all-variables option, which annotates every variable in the model.
  • Allowed certain computed variables (those which can be determined not to vary at run-time) to be metadata annotated constants. In particular, this allows the default stimulus current amplitude to be calculated within the cell model, rather than given as a fixed constant number.
  • Used the new named attribute functionality on AbstractParameterisedSystem to support named attributes on CellML models.
• Dedicated S1-S2 and dynamic restitution stimuli classes (mainly for single cell work) have been brought into the main trunk from a user project.
• Added Has... methods to cardiac modifiers, to avoid the need for try...catch statements in generic code.
• Implemented SolveAndUpdateState for backward Euler cells.
• The interface for CardiacElectroMechanicsProblem (and CardiacElectroMechProbRegularGeom) has changed slightly, instead of taking in the number of electrics solves per mechanics solve, it takes in the mechanics solve timestep (which should be a multiple of the electrics PDE solve).

Cell-based

• See above under "Headline features".

Code interface changes that may require changes to user code

General

• The interface to the SimpleLinearParabolicSolver has changed: instead of calling SetTimes(t0,t1,dt), you have to call two methods SetTimes(t0,t1) and SetTimeStep(dt).
• DistributedVectorFactory now always sets mpOriginalFactory when loaded from an archive.
• Moved the partitioning type into its own header file, rather than being nested in DistributedTetrahedralMesh. You just need to change (e.g.) DistributedTetrahedralMesh<1,1>::DUMB to DistributedTetrahedralMeshPartitionType::DUMB.

Cardiac

• VerifyStateVariables is now not called in NDEBUG builds, which may lead to tests not 'failing' in optimised builds.
• Added an optional parameter pStateVariables to GetIIonic, which gives the state at which to evaluate the current. This will require a change to any manually written cell model to match the new interface.

Cell-based

• Every cell cycle model now needs an OutputCellCycleModelParameters method. See existing models for what it should include.

Release 2.1 (changes since Release 2.0)

Headline changes

General

• The user documentation has been significantly extended, and tutorials written for the cardiac executable. Static versions of user guides and tutorials are available for this release here.
• External calls to the TetGen binary for MutableMesh::ReMesh() and for constructing instances of QuadraticMesh have been replaced by library calls. There is thus no longer a need to install TetGen, and the TetGen source version 1.4.2 is now included with the release. These changes will affect the results of 3D cell based simulations (slightly).

Cardiac

• The standalone binary now has a folder of dependency libraries and a wrapper script Chaste.sh which ensures that these libraries are linked when the program is run. The binary used to be a single monolithic file with all the dependencies compiled into it but this was known to cause run-time problems for some Linux distributions.
• The integration of CellML models of cardiac cells has been significantly improved. Code for all cell models shipped with Chaste is now generated on-the-fly from CellML, leading to some naming changes which will affect users of the source distribution (see below for details). The process is highly configurable; see our guide page for details. In particular, variables within the model may be annotated as modifiable parameters or derived quantities, and are then made available for access by name, both in the source release and via the executable. There is also improved support for units conversions, so that models can use any convention for the ionic currents and stimulus.
• Various simulation parameters can now be changed via the XML file when resuming from a checkpoint. These include cell model parameters, stimuli definitions, numerical parameters, and post-processing specifications.
• Cardiac PDE classes (which no longer contain PDE information) have now been renamed to be tissues, e.g. BidomainPde is now BidomainTissue. This change means that archives that used to contain such a class must also change, and so are not backwards compatible (an "unregistered class" error will be generated). A script archive_convert.sed is provided in both the source and executable releases of Chaste to migrate archives to the new naming. You can run it as follows:

      sed -i -f archive_convert.sed path_to_checkpoint_data_folder/*.arch*
  

Library compatibility

• PyCml can now use RDFLib as the RDF library, which is a lot easier to install than the Redland library.
• Chaste should now work with Boost versions 1.41 and above, although it does not yet receive as thorough testing on these.

Code changes

New functionality and major changes

• General:
  • A new Warnings class has been introduced to keep track of issues that don't prevent the simulation completing but may need investigation to verify the results. All unexpected warnings are printed at the end of the simulation or test-suite. If logging is switched on, then warnings appear in the log file as they happen.
  • The finite element assembler hierarchy has been completely changed and replaced with new assemblers and new solvers. See ChasteGuides/FiniteElementAssemblersAndSolvers for details.
  • Some SCons synonyms for common developer options have been provided (e.g. scons cl=1 b=_2 up=0 ts=mesh/test/TestDistributedTetrahedralMesh.hpp). See the build guide for details.
  • The DistanceMapCalculator calculates in-mesh path distances along mesh edges rather than Euclidean distances. The underlying algorithm is Dijkstra/A* which produces partition-dependent solutions to the Euclidean distance problem but reliable solutions to the edge-based distance problem.
  • There have been several changes to the ODE system hierarchy, primarily related to providing information about the ODE system. As well as information about state variables, we now support named parameters and derived quantities.
    • A new base class AbstractParameterisedSystem has been created for AbstractOdeSystem and AbstractCvodeCell to contain the system information state and methods.
    • Renamed various methods on AbstractOdeSystem (now moved to AbstractParameterisedSystem) and AbstractOdeSystemInformation for clarity and consistency:
      • rGetVariableNames/Units -> rGetStateVariableNames/Units
      • SetInitialConditionsComponent -> SetInitialCondition
      • GetStateVariableNumberByName -> GetStateVariableIndex
      • GetStateVariableValueByNumber -> GetStateVariable
      • GetStateVariableUnitsByNumber -> GetStateVariableUnits
    • For named parameters, added methods GetParameterIndex, GetParameterUnits, rGetParameterNames, and rGetParameterUnits on AbstractParameterisedSystem and AbstractOdeSystemInformation, and also methods Get/SetParameter and GetNumberOfParameters on AbstractParameterisedSystem.
    • For derived quantities, added methods GetDerivedQuantityIndex, GetDerivedQuantityUnits, rGetDerivedQuantityNames, and rGetDerivedQuantityUnits on AbstractParameterisedSystem and AbstractOdeSystemInformation. AbstractParameterisedSystem also has GetNumberOfDerivedQuantities, ComputeDerivedQuantities, and ComputeDerivedQuantitiesFromCurrentState. Note that these latter methods require the current time as input (in case the derived quantity was function of time) and may not be very efficient. Concrete ODE system classes should define ComputeDerivedQuantities if they provide any derived quantities. The OdeSolution class also has support for writing derived quantities to disk.
    • Finally, there is also "any variable" functionality, with similarly named methods (e.g. GetAnyVariableIndex) which try first state variables, then parameters, then derived quantities, until a matching name is found. To support derived quantities, GetAnyVariable can optionally take the current time as a second parameter (it defaults to zero).
  • A new class FileFinder has been created to specify file locations (particularly for input) throughout the code (and in the XML cardiac parameters file) allowing for greater flexibility. Various locations that used to use plain strings now use this class instead, which may require small changes to code using these.
  • In order to compare files with provenance data NumericFileComparison now ignores lines which begin with "# ".
• Cardiac:
  • Numerical and post-processing parameters can now be changed when resuming a simulation from a checkpoint. See UserTutorials/CardiacExecutable/CheckpointingAndRestarting for details.
  • The OutputVariables functionality has been fixed to actually output the variables requested! It can now output any state variable, or any variable annotated as a parameter or derived quantity in the cell model.
  • The use of multiple lookup tables should now work. The LuoRudy1991 model uses both V and Ca_i as table keys as an example. This leads to slight changes to results when using an optimised LR91 model.
  • Backward Euler cell models are now also optimised using partial evaluation and lookup tables, and the latter optimisations have also been improved. This has lead to slight changes in results when using optimised models.
  • APD calculation has changed so that it detects the resting potential, and therefore upstroke, more accurately. APDs will change slightly when run with the new version of the code.
  • A new class AbstractCardiacCellInterface has been introduced as a common parent of AbstractCardiacCell and AbstractCvodeCell. This shouldn't have any impact on existing code, but will make it easier to switch between the two.
  The deprecated ScaleFactor* elements are now optional in the XML schema. Use of SetParameter is preferred.
  • The DistanceMapCalculator calculates in-mesh path distances along mesh edges rather than Euclidean distances. The underlying algorithm is Dijkstra/A* which produces partition-dependent solutions to the Euclidean distance problem but reliable solutions to the edge-based distance problem. This change affects:
    • Calculation of conduction velocities - distances might now be overestimated, but will preserve detours around cavities.
    • Calculation of transmural Epi/Mid/Endo layers - relative position in wall may vary from previous.
    • Algorithmic generation of fibre directions (Streeter method) - relative position in wall may vary from previous.
• Cell-based:
  • If writing cell mutation states to the file cellmutationstates.dat in a TissueSimulation, the name of each mutation state present is now taken from its extended type ID info using a new method Identifiable::GetIdentifier.
  • Work is in progress on restructuring how model parameters are accessed in the cell-based code. As part of this, all of the TissueConfig members have been moved into the classes in which they are used. Simulations will now output a file containing the parameters used for that simulation. In order to implement this:
    • All CellKiller classes now require a OutputCellKillerParameters method.
    • All tissue classes now require a OutputTissueParameters method.
    • All force classes now require a OutputForceParameters method.
    • All such classes (and simulation subclasses) must have an archiving export key defined correctly.
    See the tutorials for more information on how to write these.
  • The principles behind the cell mutation state refactor have now been applied more generally to cell properties, enabling the creation of arbitrary properties that can be attached to cells. There are new classes AbstractCellProperty and CellPropertyCollection, and CellMutationStateRegistry has been replaced by CellPropertyRegistry. A TissueCell now has a CellPropertyCollection member, in which it stores its mutation state as well as any other cell property the user chooses. Cell properties can be passed into the TissueCell constructor or by using the new method AddCellProperty. Similarly there are new methods RemoveCellProperty and rGetCellPropertyCollection on TissueCell. Also,
    • The mutation state LabelledCellMutationState has been replaced with a new cell property class CellLabel.
    • APOPTOTIC is no longer a CellProliferativeType but has been replaced with a new class ApoptoticCellProperty.
    • The output of some Tissue methods, such as GetCellMutationStateCount, have been changed.
    • The classes Alarcon2004OxygenBasedCellCycleOdeSystem and Alarcon2004OxygenBasedCellCycleModel have been modified, so that instead of storing a cell's mutation state, now they just store whether it has the cell property CellLabel.
    • Removed unused Alarcon2004OxygenBasedCellCycleModel member variable mIsLabelled.
  • The creation of ODE-based cell cycle models has been eased. There is now a wrapper around ODE solvers, AbstractCellCycleModelOdeSolver (with concrete singleton implementation CellCycleModelOdeSolver) and ODE-based cell cycle model constructors now take an optional shared_ptr<AbstractCellCycleModelOdeSolver> allowing the user to specify what solver to use. A mixin base class for cell cycle models, CellCycleModelOdeHandler, has been created which cell cycle models that solve a system of ODEs to determine progress through the cell cycle can inherit from.

Interface changes that may require changes to user code

• General:
  • In AbstractLinearParabolicPde, ComputeLinearSourceTerm(x) and ComputeNonlinearSourceTerm(x,u) have been merged into one method ComputeSourceTerm(x,u).
  • The macro NEVER_REACHED has become a termination error and will always terminate (sequential/parallel and debug/NDEBUG). This is a level 4 error according to our exception strategy. NEVER_REACHED now relies on PetscTools (so that it can either exit or abort in parallel) -- compilation may fail if you are missing #include "PetscTools.hpp".
  • Providing an estimate of the maximum number of nonzero entries expected on any row is now compulsory and is done via an additional argument to PetscTools::SetupMat, rather than by a call to PetscTools::SetMaxNumNonzerosIfMatMpiAij. PetscTools::SetupMat no longer has a MatType argument. Code that uses the old method in the problem class will no longer compile or may interpret extra arguments incorrectly. Instead, changes must be made to the InitializeForSolve method of the assembler. Instead of instantiating the linear system by this->mpLinearSystem = new LinearSystem(template_vec);, we must add an extra argument: this->mpLinearSystem = new LinearSystem(template_vec, *NNZ*);.
  • Replaced all mesh functionality for getting extremes of meshes with AbstractMesh::CalculateBoundingBox returning a ChasteCuboid. The parallel specialisation in DistributedTetrahedralMesh gets the bounding box of the global mesh.
  • Renamed various methods on AbstractOdeSystem and AbstractOdeSystemInformation for clarity. We want to stress that these methods do not change the state variables of the instance of an ODE on which they are called, but the values considered default.
    • SetInitialConditions -> SetDefaultInitialConditions
    • SetInitialCondition -> SetDefaultInitialCondition
  • PetscTools::CreateVec(int size, double value) method renamed to CreateAndSetVec. The removal of this overload allows for the new interface method PetscTools::CreateVec(int size, int localSize).
  • Distributed mesh GetAnyNode method renamed to GetNodeOrHaloNode.
• Cardiac:
  • All cell models are generated on the fly from CellML, which will break code previously using these. Please update the following:
    • #include directives:
      • luo_rudy_1991.hpp -> LuoRudy1991.hpp, luo_rudy_1991Opt.hpp -> LuoRudy1991Opt.hpp, luo_rudy_1991BackwardEuler.hpp and BackwardEulerLuoRudyIModel1991.hpp -> LuoRudy1991BackwardEuler.hpp, luo_rudy_1991Cvode.hpp -> LuoRudy1991Cvode.hpp, luo_rudy_1991CvodeOpt.hpp -> LuoRudy1991CvodeOpt.hpp
      • noble_varghese_kohl_noble_1998_a.hpp -> NobleVargheseKohlNoble1998a.hpp, noble_varghese_kohl_noble_1998_aOpt.hpp -> NobleVargheseKohlNoble1998aOpt.hpp
      • tentusscher_model_2006_epi_corrected_flooristim.hpp -> TenTusscher2006Epi.hpp, tentusscher_model_2006_epi_corrected_flooristimOpt.hpp -> TenTusscher2006EpiOpt.hpp, tentusscher_model_2006_epi_corrected_flooristimBackwardEuler.hpp and BackwardEulerTenTusscher2006.hpp -> TenTusscher2006EpiBackwardEuler.hpp
    • Class names: New names all take the form "Cell<FileBaseName>FromCellML<Modifiers>", e.g. CellLuoRudy1991FromCellML, CellTenTusscher2006EpiFromCellMLOpt, CellLuoRudy1991FromCellMLCvodeOpt, CellTenTusscher2006EpiFromCellMLBackwardEuler.
    See the guide page for more details.
  • #include "Maleckar2009OdeSystem.hpp" should be replaced with #include "Maleckar2008.hpp" to reflect year of publication.
• Cell-based:
  • To reflect the general nature of the classes, we have renamed TissueCell to Cell, Tissue to CellPopulation and TissueSimulation to CellBasedSimulation.
  • We now create and access Cell objects via Boost shared pointers, and disallow copying of Cells, since this doesn't make biological sense and is inefficient. The type alias CellPtr is available to ease transition and save typing! Many methods that previously took in or returned Cells now deal with CellPtrs. Copying of cell cycle models has also been disallowed.
  • CellBasedSimulation and inherited classes now do not take in a force collection. To set the mechanics system call the AddForce method.
  • The mesh classes Face, VoronoiCell, VoronoiTessellation and InventorVoronoiWriter have been deleted. This is because they are no longer used in the code. Now, when a MeshBasedTissue is required to construct the Voronoi tessellation that is dual to its mesh, this is stored as a VertexMesh. The main difference is how the MeshBasedTissue then accesses information about the Voronoi tessellation. Users should replace MeshBasedTissue calls to rGetVoronoiTessellation.GetFaceArea with GetAreaOfVoronoiElement, calls to rGetVoronoiTessellation.GetFacePerimeter with GetPerimeterOfVoronoiElement, and calls to rGetVoronoiTessellation.GetEdgeLength with GetVoronoiEdgeLength.
  • Changed MeshBasedTissue method rGetVoronoiTessellation to GetVoronoiTessellation (i.e. return a pointer rather than a reference) in order to avoid memory issues.
  • Various renamings have occurred:
    • MeshBasedTissue methods SetOutputTissueAreas, WriteTissueAreaResultsToFile, WriteCellAreaResultsToFile renamed to use Volume instead of Area. Similarly merged the VertexMesh method GetPerimeterOfVoronoiElement into GetSurfaceAreaOfVoronoiElement and GetAreaOfVoronoiElement into GetVolumeOfVoronoiElement.
    • VertexMesh method SolveVoronoiElementIndexMapping renamed to GetVoronoiElementIndexCorrespondingToDelaunayNodeIndex.
  • When a MeshBasedTissue creates a Voronoi tessellation, this is constructed out of all nodes in the mesh, including ghost nodes.
  • CellwiseData has been generalised to cope with vertex-based tissues; some of its methods have changed names or arguments.

Release 2.0 (changes since Release 1.1)

Headline features

• Dynamic loading of cell models defined in CellML (using a source release of Chaste).
• Checkpointing of cardiac simulations now supported.
• Support for open-source visualisation of cardiac simulations via VTK or cmgui.
• More cardiac simulation post-processing functionality now available in the executable.
• Support for transmural cellular heterogeneities definition in the XML parameters file.
• Support for more versions of our library dependencies.
• Improved documentation of the parameters file XML schema.
• Use of a distributed mesh in the cardiac executable.
• Use of parMETIS for partitioning in parallel cardiac simulations.
• Introduction of binary form of Triangle/Tetgen mesh format.
• Cancer component renamed to cell_based to reflect the increasing generality of the code.

Library compatibility

• MPI - Chaste is known to work with MPICH1 (mpich-1.2.7p1), MPICH2 (mpich2-1.1.1p1) and OpenMPI (1.2.7). mpich-1.2.7p1 is recommended. Note that PETSc and HDF5 must be compiled with the same MPI that is used in the Chaste configuration.
• HDF5 - Chaste is known to work with version 1.6.6 (recommended) and version 1.8.3.
• PETSc - Chaste is known to work with version 2.2.1, version 2.3.2 (recommended), version 2.3.3 and version 3.0.
• Boost - Chaste is regularly tested with Boost 1.33.1, Boost 1.34 (recommended), Boost 1.37 and Boost 1.40. Chaste also supports Boost 1.36, 1.38 and 1.39, although these versions are not regularly tested. Chaste DOES NOT WORK with Boost 1.35 (due to a known bug in that version of Boost) nor with version 1.41 and above (due to changes in the serialization library API).

Code changes

New functionality

• 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:
  1. ActionPotentialDurationMap
  2. UpstrokeTimeMap
  3. MaxUpstrokeVelocityMap
  4. 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.

Some behaviour corrections

• An indexing error in previous release meant that mesh produced by Chaste on the fly (slab/cuboid meshes) were not conforming. That is, the faces did not meet correctly and the finite element approximation was discontinuous. This behaviour has been fixed.

Interface changes that may require changes to user code

• General:
  • LinearSystem::ZeroMatrixRow is deprecated due to inefficiency. Use LinearSystem::ZeroMatrixRowsWithValueOnDiagonal to modify multiple rows instead.
  • In the AssemblerTraits struct, the typenames 'CVT_CLS', 'CMT_CLS' and 'INTERPOLATE_CLS' have been renamed to 'CVT_CLASS', 'CMT_CLASS' and 'INTERPOLATE_CLASS'. These stand for 'ComputeVectorTerm class', 'ComputeMatrixTerm class' and 'Interpolate class' in case you are wondering, and the AssemblerTraits struct is used to state which classes these methods are implemented in.
  • Changed OdeSolution::WriteToFile() so that it no longer takes the AbstractOdeSystem as an argument.
  • If you were implementing serialization for classes, note that the interface has changed, in order to better support different Boost versions. You should include ChasteSerialization.hpp rather than boost/serialization/access.hpp. Also, the file TemplatedExport.hpp has been replaced with two files: SerializationExportWrapper.hpp and SerializationExportWrapperForCpp.hpp. You should include the first in .hpp files, after the class definition. The second should be included in .cpp files, after any other includes (I suggest putting it at the end of the file for consistency). In both cases, a suitable CHASTE_CLASS_EXPORT line should be used, the same in both .hpp and .cpp. (There are also the usual variant macros for common cases of templated classes.) See BoostSerialization for more info.
  • The dependency on the METIS library has been replaced by one on parMETIS. This will require a small edit of the hostconfig file (see INSTALLATION.txt for details).
  • ParallelTetrahedralMesh has been renamed to DistributedTetrahedralMesh.
  • The logic for project SConscript files has been moved into python/SConsTools.py. This allows project SConscript files to be very short, and makes it easier to enhance or modify the build system logic in the future. See the template project's SConscript file for an example; you will need to update your SConscript file, since the logic has changed since release 1.1.
• Cardiac:
  • The boundary conditions container in cardiac problem classes is now accessed via a boost::shared_ptr (rather than a raw pointer). The PDE assembler hierarchy is still using normal pointers, however, so this should only affect people creating cardiac problem subclasses, or setting their own boundary conditions for cardiac problems: if you do these, you'll need to use a shared pointer now.
  • The methods ConvertOutputToMeshalyzerFormat, ConvertOutputToCmguiFormat and ConvertOutputToVtkFormat have been removed from AbstractCardiacProblem. Code using these should change to use the methods SetVisualizeWithMeshalyzer, SetVisualizeWithCmgui or SetVisualizeWithVtk on HeartConfig.
• Cancer:
  • The cancer folder has been renamed to cell_based to reflect the more general nature of the code. There is a subfolder called crypt containing crypt-specific functionality. If you have a user project using the cancer code, a search & replace from cancer to cell_based should suffice, especially in your project SConscript file.
  • TissueConfig::Get/SetTopOfLinearWntGradient() have been renamed to Get/SetWntConcentrationParameter(), so that an exponential Wnt concentration could be added.
  • The CryptCellMutationState enumeration has been replaced by a hierarchy of classes inheriting from AbstractCellMutationState. TissueCells now have a shared pointer to a mutation state. To ensure proper counting of cells with each mutation, make sure that you give a cell a mutation state from its tissue's registry (AbstractTissue::GetMutationRegistry). Also, when passing a vector of cells to a tissue constructor, the passed-in vector is now cleared, to emphasize that these cells become owned by the tissue. Also removed AbstractTissue::mCellMutationStateCount and, as a result, changed rGetCellMutationStateCount() to GetCellMutationStateCount().
  • The CellsGenerator class hierarchy has been refactored to reduce code duplication. There is now a base class CellsGenerator, which is templated over cell cycle model classes and dimension, and comprises GenerateBasic() and GenerateGivenLocationIndices() methods; and a subclass CryptCellsGenerator, which has an additional method Generate() that sets up cells for a crypt simulation.
  • To reduce the number of calls to CreateCellPair, the MeshBasedTissue methods IsMarkedSpring, MarkSpring and UnmarkSpring no longer call the CreateCellPair method, and now take in a reference to a std::set<TissueCell*> instead of two TissueCell references.
  • The mesh component now contains an extra folder vertex, which includes classes for the construction and reading/writing of 'vertex meshes' (these are meshes in which the number of nodes per element is unrestricted) as well as associated tests.
  • AbstractCryptStatistics::GetWhetherCryptSectionCellsAreLabelled has been renamed to AreCryptSectionCellsLabelled.
  • Changes to the archive format mean that checkpoint archives created with earlier versions of Chaste will not load in the new version.

Release 1.1 (changes since Release 1.0)

General

• Parts of the Chaste developers wiki have now been opened to the general public. For a guest login, use the username "anonymous", and your email address as the password.
• Improved doxygen documentation.
• PyCml is now included in the main Chaste trunk (python/pycml). This means that you no longer need to download it separately. Note that the PyCml distributed with release 1 will not generate code compatible with Chaste release 1.1 (see also below).

Code changes

• Improved code portability.
  • (Some of) Chaste can now be run under Cygwin; see the InstallGuides/Cygwin wiki page for details.
  • Chaste now uses version 3.2.0 of XSD (although versions 2.3.1 and 3.1.1a3 are also supported for now). This should hopefully make Chaste easier to install on Macs
• Some behaviour corrections.
  • For a dynamic assembler, if the matrix is constant you must now call this->SetMatrixIsConstant() in the constructor otherwise the matrix will now be assembled each timestep. If your matrix is not constant in time, you were getting wrong answers before!
  • Bidomain problems with Neumann intracellular stimuli shouldn't have a solution, and there was an implementation error before which allowed them to be solved. This has been fixed, so any test with Neumann stimuli will not work. The stimulus has to be changed to a (standard) volume stimulus.
  • For ELEMENT_DIM == 1 (in any SPACE_DIM) MeshalyzerMeshWriter will now output a .cnnx file rather than a .tri file for element connections.
• New functionality.
  • MonodomainProblem is now templated on both ELEMENT_DIM and SPACE_DIM. It will default to using ELEMENT_DIM = SPACE_DIM if only one is supplied.
  • Several helper macros have been written for debugging, see global/Debug.hpp.
  • Added a CombinedOdeSystem class for simple coupling of ODE systems.
• Work in progress.
  • Checkpointing of cardiac simulations is on the way. Most of the components of cardiac simulations now have their own archiving methods. Unfortunately full checkpoint and restart functionality did not make it into this release.
  • There is functionality in the code and the XML for post-processing physiological quantities such as action potential duration and activation maps. This functionality may only be used at the developer level. If you are running the executable then requests in the XML file for post-processing will be ignored.

Interface changes that may require changes to user code

• General:
  • Triangle and tetgen binaries are no longer included with the code and must be installed and set in the PATH. Most re-meshing still works since 2D re-mesh compiles Triangle code from source (which is included).
  • The #include policy has changed. It might be the case that tests that used to compile are unable to find certain header files now. Please #include such headers explicitly as needed.
  • It is now impossible to create vectors (either PETSc Vecs or DistributedVectors) directly from a DistributedVector. This must now be done via a DistributedVectorFactory. If you have a mesh, a factory can be obtained using the GetDistributedVectorFactory method. The cardiac PDEs also store a factory.
  • Static iterators are not available anymore in DistributedVector. You can access the iterator from a DistributedVector object. If there isn't one in scope, use GetLow() and GetHigh() in DistributedVectorFactory (accessible via any mesh object).
  • For a dynamic assembler, if the matrix is constant you must now call this->SetMatrixIsConstant() in the constructor otherwise the matrix will now be assembled each timestep. If your matrix is not constant in time, you were getting wrong answers before!
  • Renamed PetscTools::NumProcs to PetscTools::GetNumProcs.
  • Renamed AbstractMesh to AbstractTetrahedralMesh, there is a new AbstractMesh class, which will handle non-tetrahedral meshes.
• Heart:
  • this->mpMesh is no longer directly available to cell factories, as it can be used accidentally while unset. Use the GetMesh() method instead.
  • Cardiac cell models are now constructed using boost::shared_ptr<> instead of normal pointers for the 'stimulus' and 'ode solver' arguments. This will require changes to cell factories too. See files heart/test/ionicmodels/TestIonicModels.hpp and heart/src/problem/PlaneStimulusCellFactory.hpp for examples of the new usage.
• Cancer:
  • WntConcentration is now templated over dimension. You will have to pass in the dimension when constructing any Wnt-dependent cell cycle model.
  • SloughingCellKiller is also now templated over dimension.
  • FixedCellCycleModel, StochasticCellCycleModel, and the two corresponding CellGenerators have been renamed (to FixedDurationGenerationBasedCellCycleModel and StochasticDurationGenerationBasedCellCycleModel respectively).
  • The CancerParameters singleton class has been renamed TissueConfig (to match the heart code).
  • cancer/src/tissue/MeshArchiveInfo has been replaced by global/src/ArchiveLocationInfo, which has slightly different usage.

Also, xsd should be defined in your hostconfig file (if it isn't on your PATH) in the form tools = {'xsd':'FILL_IN_PATH_TO_XSD_BINARY'} as it regenerates ChasteParameters.hpp/cpp during the build process.