Chaste Release Notes

Release 3.1 (changes since Release 3.0)

Release 3.1 is a minor release, which brings support for newer versions of libraries and a small number of new capabilities and bug fixes. It provides access to a release version of Chaste under the BSD licence (rather than the LGPL licence), to make it easier to use Chaste in industrial settings.

Headline features

General

• Chaste is now released under the BSD licence, this is one of the major reasons for this release: http://opensource.org/licenses/BSD-3-Clause.
• The Ubuntu package now also supports Precise Pangolin (12.04 Long-Term Support edition).
• Support for PETSc version 3.2 has been added. Some previously supported versions have been dropped so that the minimum required version of PETSc is now 2.3.2. The minimum version of Boost is now 1.34.
• Support for up to GCC 4.7.0 and Intel 12.1 compilers.

Cardiac

• Cardiac electro-mechanics now works with bidomain as well as monodomain simulations.
• Cardiac cell models in tissue can now be solved using CVODE (versions 2.5-2.7), this can provide large speed-ups for problems that are small enough to get all the Cvode solvers in memory.

Cell-based

• The global singleton CellWiseData has been replaced by a much more general CellData component in each cell.
• The cell property hierarchy is now used much more extensively throughout the code.
• A new cell population class has been introduced to enable the simulation of cellular automata with multiple site occupancy.

Major new functionality & code changes

General

• Chaste is now beginning to use the Boost Filesystem library for low-level file management. This means an extra third-party dependency; your builds will fail if the library is not installed. Updating to the latest version of the chaste-dependencies Ubuntu package will ensure the library is installed; many systems will have it anyway. Your hostconfig file may require editing to link against boost_system as well as boost_filesystem if using recent Boost versions. (Boost >= 1.34 is now required.)

Cardiac

• A CellMLLoader class is available which makes the dynamic loading of CellML files into (almost) a one line call.
• The Cmgui script that helps the user to load the simulation data has been adapted to Cmgui version 2.8 or later. It is still compatible with previous Cmgui versions 2.7 and 2.6. The name of the script is now LoadSolutions.com in both the undeformed and deformed cases.
• A CellML project has been created containing many annotated CellML files for use with Chaste. See the Chaste wiki (ChasteGuides/CodeGenerationFromCellML) for details of how to access it.

Cell-based

• The global singleton CellWiseData has been replaced by a CellData component in each cell. These data are scalable and are accessed by name rather than index. There is a helper method on cell populations for visiting all cells and setting constant data (SetDataOnAllCells()). When using nutrient-dependent cell-cycle models or PDEs the CellData name must match with the name used in the class.
• Cell-based simulations, populations, forces and cell killers can now all be templated over element dimension as well as space dimension; this currently allows for mesh-based simulations of 2D surfaces in 3D space without cell division.
• Two serious bugs fixed in Delta-Notch code (the number of times that the ODE is solved and which variables get updated in the CellData).
• A new cell-population class, MultipleCaBasedCellPopulation, has replaced CaBasedCellPopulation. This enables cellular automata to be simulated which allow multiple site occupancy (more than one cell model at each lattice site).
• Centre-based simulations now have a movement threshold in order to check for numerical stability. You will need to manually call SetAbsoluteMovementThreshold() in simulations where large cell movements are typical.

Minor new functionality and code changes, which may still require changes to user code

General

• The testoutput directory in the main trunk has been renamed test_summary to avoid confusion. For each build, it contains a generated webpage with a summary of test results and links to their console output, your actual test output goes elsewhere. This means you need to update any browser bookmarks to the test results summary.
• The method AbstractElement::SetRegion has been renamed to SetAttribute. Similarly, GetRegion has been renamed to GetAttribute.
• It is now possible to run Electromechanics problems where the electrical problem is a bidomain problem. The interface of CardiacElectroMechanicsProblem has changed. You now need to pass the electrics problem type as second parameter to the constructor (e.g., MONODOMAIN, BIDOMAIN) and the electrics problem dimension as second template (defaults to 1).
• We now pass fibre file names around using a FileFinder rather than a string, to allow loading from a wider variety of locations.
• A local.py settings file may be placed in python/hostconfig to be used in preference to any other hostconfig settings.

Cardiac

• Most of the heart solvers and cell factories now use AbstractCardiacCellInterface, not AbstractCardiacCell (to enable the use of CVODE solvers).
• In the version 3.1 XML parameters file, the ConductivityHeterogeneities element has been moved from inside <Simulation> to inside <Physiological>. New files written to this version of the schema will need to reflect this; old files still using a previous version can still be used unchanged.
• For simulations with compressible material laws, the electro-mechanics solver should have been scaling the active tension returned by the contraction model, by the determinant of the deformation gradient. This has now been fixed. (See ChasteGuides/FiniteElementImplementations for the (corrected) equations). Results using the compressible material law in the repository have barely changed, since this material law is nearly incompressible. However, simulation results with any user-defined highly compressible law might change.
• Pseudo ECG calculations for Bidomain-with-Bath simulations have been changed, as pointed out on the mailing list, these had a bug that meant the integral was performed over the whole mesh (including bath) instead of just cardiac tissue.
• Fixed a small bug in cardiac checkpointing, when loading and running a simulation from an archive to a new output folder the voltage at the final time step in the .h5 file was spuriously reported as "0".
• FibreReader::GetNextFibreVector(vec) has been changed to FibreReader::GetFibreVector(index,vec) and GetNextFibreSheetAndNormalMatrix(mat) to GetFibreSheetAndNormalMatrix(index,mat).
• The HeartConfig class has undergone an extensive refactor internally. This shouldn't impact users (although you might notice that a ChasteDefaults.xml file is no longer written to checkpoints), but some "nonsensical" calls to Get methods may now return different or new errors.
• There have been changes the interface of the VoltageInterpolaterOntoMechanicsMesh class. Now you need to pass in the names of the electrics variables you want to interpolate onto the mechanics mesh (variable 'V' used to be hardcoded as the only one to be interpolated).

Cell-based

• Renamed the AbstractCellBasedSimulation methods PostSolve() and AfterSolve() to UpdateAtEndOfTimeStep() and UpdateAtEndOfSolve() respectively; also moved the code out of the existing AbstractCellBasedSimulation methods into the main Solve() method, so that these methods don't have to be called by every overridden version.
• Corrected the implementation of StochasticDurationGenerationBasedCellCycleModel by making use of parameters mStemCellG1Duration and mTransitCellG1Duration in the method SetG1Duration(). This won't break user projects, but may change results.
• Created a new AbstractCellPopulation method GetVolumeOfCell(), which is overridden in concrete subclasses; this method is now used in VolumeTrackedOffLatticeSimulation, which hence now works with any off-lattice cell-based population.
• Corrected initialisation of CellwiseData (now CellData; see above) in VolumeTrackedOffLatticeSimulation; it is now populated automatically when a simulation is set up, rather than having to be manually initialized.
• VTK output has been enabled for cell-based simulations that use a MultipleCaBasedCellPopulation or PottsBasedCellPopulation.
• Moved mpBoxCollection from NodeBasedCellPopulation to NodesOnlyMesh.
• Made CellId a concrete CellProperty to exploit the functionality of this class hierarchy.
• Created the class CellAncestor, which inherits from AbstractCellProperty and stores the unsigned variable associated with each ancestor. The Cell method SetAncestor() now takes a shared pointer to a CellAncestor rather than an unsigned.
• Extended the class SurfaceAreaConstraintUpdateRule and the PottsMesh method DivideElement() to work in 3D
• In node-based simulations cell radii are now inherited from parent cells; before this was hard-coded to 0.5. Also enabled updating of cells radii through CellData. This won't break user projects, but may change results.
• The HoneycombMeshGenerator was producing slightly irregular cell-cell spring lengths due to floating point truncation. This has been fixed, which means that all simulations using HoneycombMeshGenerator now give slightly different results, and monolayer simulations surrounded by layers of ghosts nodes pull the convex hull of the ghost nodes to a circle more rapidly than before. This won't break user projects, but may change results.
• We have renamed the cell killer methods TestAndLabelSingleCellForApoptosis() and TestAndLabelCellsForApoptosisOrDeath() to CheckAndLabelSingleCellForApoptosis() and CheckAndLabelCellsForApoptosisOrDeath() respectively, since it is not ideal to have a method with the prefix Test- outside a test suite.
• OxygenBasedCellKiller has been renamed ApoptoticCellKiller to more accurately reflect its functionality.
• CryptCellsGenerator now works with a PottsBasedCellPopulation.
• Refactored VertexElement and PottsElement to both inherit from a new class, MutableElement, and moved appropriate functionality up into this parent class. Also changed the order of the parameters in MutableElement::AddNode() so that rIndex can default in child classes. This will particularly affect VertexElement where users will need to change the order of the parameters, switching pNode and rIndex.
• The divisions.dat data file, if output, now includes an extra column containing the age of the parent cell just prior to division.
• Moved mCellProliferativeType from AbstractCellCycleModel back into Cell.
• Forces in node-based populations may now be made dependent on cell radii.
• Added a new force class, NagaiHondaDifferentialAdhesionForce, and associated tutorial TestRunningDifferentialAdhesionSimulationsTutorial. This class inherits from NagaiHondaForce and allows for different interaction energies depending on which (if any) of a pair of interacting cells have the property CellLabel.
• Removed an exception in NodeBasedCellPopulation that had prohibited a simulation from having a single cell.
• Added a new force class DiffusionForce to the trunk for simulating random movement.
• Added several 'removal' methods: RemoveAllUpdateRules() to MultipleCaBasedCellPopulation and PottsBasedCellPopulation; RemoveAllCellKillers() to AbstractCellBasedSimulation; RemoveAllForces() to OffLatticeSimulation; and RemoveAllMultipleCaUpdateRules() and RemoveAllPottsUpdateRules() to OnLatticeSimulation.
• The CellBasedPdeHandler method UseCoarseMesh() now takes a ChasteCuboid defining both the size and location of the coarse mesh to use, so that the user can specify the exact location of the coarse mesh rather than it defaulting to centering on the centre of the cell population. The user should either ensure this contains the population or set the extra flag to true to automatically centre this mesh on the centre of the cell population.
• In order to allow more than one cell per location index in MultipleCaBasedCellPopulation, the GetCellResults() method in AbstractCellPopulation has been modified to take in a CellPtr rather than a location index.

---

Release 3.0 (changes since Release 2.3)

Headline features

General

• The Ubuntu package now also supports Oneiric Ocelot (11.10)
• Support for PETSc 3.1 has been added, and Chaste should also work with the latest versions of the Boost libraries.
• This is the last Chaste release that will officially support Boost 1.33.1 and PETSc 2.2.
• The mechanics (and cardiac electro-mechanics) solvers have been made significantly more flexible.
• It is relatively easy to write new solvers of coupled systems of linear PDEs, and tutorials on how to do this have been added.
• We now recommend using VTK with Chaste, and the default.py hostconfig assumes it is available; previously support for VTK input/output within Chaste defaulted to off.

Cardiac

• (Work has begun on solving fluid flow and electrophysiology with Purkinje fibres, but these features are not yet completed.)

Cell-based

• Lattice based cellular Potts models have been implemented.
• There has been a major refactor of the structure of the cell-based code to make the specification of multi-cell models (such as cell-centre, over-lapping spheres, vertex-based and cellular Potts) more consistent.
• The handling of PDEs has been improved allowing PDEs to be coupled to node-based simulations.
• More exceptions are thrown when incompatible classes are used. Exception messages give information on how to fix the problem.

Major new functionality & code changes

General

• An error is given if using Boost 1.41 due to a bug in its serialization library. Versions 1.44-1.46.1 also have a bug triggered when some tests exit, but the tests do run successfully.
• All the solid mechanics related functionality has been moved out of the pde component to a new component continuum_mechanics. These components should be considered as quite separate to each other.
• The interfaces to the solid mechanics solvers have changed considerably. They now take in a 'problem definition' object and are much more powerful. The tutorials describe the new interfaces in detail.
  • The incompressible solver is now called IncompressibleNonlinearElasticitySolver.
  • Further work has been done on the compressible solver.
  • Both the incompressible and compressible solvers take in a new class, SolidMechanicsProblemDefinition, on which the material law, body force, displacement and traction boundary conditions are defined. See the solid mechanics tutorial to see how these classes are used. They also now take in a reference to a mesh not a mesh pointer.
  • Sliding boundary conditions are now possible (i.e. displacement boundary conditions, for only some components of the displacement, at given nodes).
  • Solid mechanics problems can now use boundary conditions that specify that a particular pressure should act in the normal direction on deformed surfaces. It may not be fully optimised yet though - the Jacobian in the nonlinear solve needs altering.
• PDE-related changes:
  • When solving general time-dependent PDEs the solution can now be written to file at a specified sampling interval, in a variety of formats (HDF5, cmgui, text). See UserTutorials/SolvingLinearPdes for more details.
  • Renamed AbstractFeObjectAssembler to AbstractFeVolumeIntegralAssembler, moved the surface integral functionality from this class to AbstractSurfaceIntegralAssembler, and created a natural Neumann concrete child of AbstractSurfaceIntegralAssembler to be used in PDE solvers.
  • These changes allow solvers of systems of PDEs to be set up relatively easily (for PDEs for which it is appropriate to use linear basis functions, e.g. systems of coupled heat or diffusion equations). Tutorials on writing your own PDE solvers have been added: start with UserTutorials/WritingPdeSolvers.
  • Added new classes AbstractLinearParabolicPdeSystemForCoupledOdeSystem and LinearParabolicPdeSystemWithCoupledOdeSystemSolver for the numerical solution of coupled systems of reaction-diffusion PDEs and ODEs. See the associated tutorial UserTutorials/SolvingLinearParabolicPdeSystemsWithCoupledOdeSystems.
  • The efficiency of PetscMatTools::ZeroRowsAndColumnsWithValueOnDiagonal has been significantly improved, which should improve performance when using Dirichlet boundary conditions.
• Due to floating point error, it was previously possible for TimeStepper to occasionally take a very small step in long simulations, when all steps should have been the same size, and hence break code that assumed a constant time-step. The tests and calculations have now been made much more robust, by being based on machine precision rather than magic numbers.
  • Any time-stepping object will throw if stepped past its end time. (Previously (i) the core/heart TimeStepper class silently remained at the end time and (ii) the cell_based SimulationTime singleton class silently stepped past the end time.)
• Mesh-related changes:
  • GenericMeshReader has been changed from a class to a function. If you use it directly, you must now do something like "std::auto_ptr<AbstractMeshReader<2,2> > p_reader = GenericMeshReader<2,2>(mesh_path);". The returned smart pointer will automatically destroy the reader when it goes out of scope, so any other changes to your code should be limited to replacing reader with *p_reader.
  • Some mixed dimension meshes may now be read in to Chaste, i.e. 1d elements embedded in a 2d or 3d mesh. The 1d elements are defined in a separate .cable file, with the same format as the .edge file.
• Other new functionality:
  • Various additions to CommandLineArguments make it possible to pass in lists of arguments for a particular option. An option is now defined as starting with '-' followed by any non-numeric character to avoid confusion with negative numbers. Various helper methods have been added to avoid having to use char* and atoi etc.
  • There's a new class CompareDoubles in MathsCustomFunctions with static methods for comparing floating point numbers to absolute or relative tolerances. This is now used in NumericFileComparison so that files can be compared to the looser of an absolute or relative tolerance. The default is still to use just absolute as before.
  • Added methods PetscMatTools::CheckSymmetry and PetscMatTools::CheckEquality.
  • Where work can be split between isolated processes, it would be nice to be able to do so easily without worrying about collective calls made inside classes such as OutputFileHandler leading to deadlock. A new method PetscTools::IsolateProcesses has been added to facilitate this. Note that it doesn't guarantee safety - collective calls not resulting from the 3 methods affected will still cause deadlock.

Cardiac

• Changes accessible via the XML parameters file:
  • Allowed the precision with which Meshalyzer and Cmgui visualisation output is written to be specified from the XML configuration file and via HeartConfig. (Thanks to Megan Marsh.)
  • Added the ability to specify paths relative to the XML configuration file for elements with type path_type (e.g. ArchiveDirectory and cell model paths). Use the attribute relative_to="this_file".
• Electro-mechanics: See the cardiac electro-mechanics tutorials for examples/usage of the following changes:
  • Cardiac electro-mechanics solvers can now use compressible elasticity as well as incompressible elasticity.
  • The interface to CardiacElectroMechanicsProblem has completely changed, and the interface to CardiacElectroMechProblemRegularGeom has slightly changed. CardiacElectroMechanicsProblem now takes in a problem definition object (c.f. the mechanics solvers) which means it is now much more flexible. Anything that can be done in a mechanics simulation can now immediately be done in a electro-mechanics simulation.
  • For both CardiacElectroMechanicsProblem and CardiacElectroMechProblemRegularGeom: electrics PDE timestep if different to 0.01, and simulation end time, should be set using HeartConfig, and not in the constructor of the problem class.
  • CardiacElectroMechProblemRegularGeom constructor parameters are in a slightly different order, and it also can't be used with mechano-electric feedback or fibre files any longer (use CardiacElectroMechanicsProblem instead).
  • Some new tutorial tests have been added.
• Added functionality to solve extended bidomain problems (with two cell types at each control volume). This functionality is not yet available for the executable users.
• The ability to perform non-matrix-based assembly (of the RHS vector) has been removed; matrix-based assembly is now always used. The option SetUseMatrixBasedRhsAssembly no longer exists.
• The convenience method GetAllOrtho used to do VTK visualisation of ortho files was incorrect. It was returning the rows of the conductivity tensor which represent a transpose of the original fibre data.
• Various cardiac post-processing operations scale poorly with the number of nodes. This has been significantly improved, although dramatic slowdown will still be observed with very large simulations. (Technical detail: the reason for this is that the output data is written to the HDF5 file at each printing time-step, and so the file layout is optimised for reading/writing every node at one time-step. However, post-processing needs to read every time-step for a single node or subset of nodes, and so cannot access disk as efficiently.)
• Implemented calculating fibre orientations (Streeter) in a wedge preparation, for either left or right ventricle. Previously both LV and RV endocardial surfaces were required.

Cell-based

• A major refactor of the cell population and cell-based simulation class hierarchies has taken place, based upon a distinction between on- and off-lattice models. This was done to integrate the code more thoroughly as on-lattice population and simulation classes were introduced, and to ensure that the use of update rules and forces is more consistent.
  • The CellBasedSimulation class has been split up into a hierarchy, with OffLatticeSimulation and OnLatticeSimulation inheriting from AbstractCellBasedSimulation.
  • All cell populations now inherit from either AbstractOffLatticeCellPopulation or AbstractOnLatticeCellPopulation the former are used by OffLatticeSimulation and the later are used by OnLatticeSimulation.
• Cellular Potts models have been implemented in Chaste
  • The PottsBasedCellPopulation has been created with associated PottsMesh and PottsElement classes to store spatial information.
  • The AbstractPottsBasedUpdateRule hierarchy is used to define the dynamics of the simulation.
  • Simulations make use of the existing cell-cycle model and cell-killer hierarchies.
  • Added functionality for visualizing Potts-based cell simulations either using the visualizer Visualize2dVertexCells.java or using Paraview with VTK output.
• We have moved much of the cell-based code to use boost::shared_ptrs rather than plain pointers. This makes memory handling much more straightforward.
  • The CellBasedSimulation class and its subclasses now store collections of cell killers, boundary conditions, forces or update rules as boost::shared_ptrs. These are passed to cell-based simulations as (e.g.) std::vector<boost::shared_ptr<AbstractForce<DIM>>> instead of std::vector<AbstractForce<DIM>*>.
  • We also use helper macros such as MAKE_PTR a lot more in tests; these are defined in the header SmartPointers.hpp.
• A new overlapping spheres based force law, used by Buske et al. in their 2011 model of the crypt based on previous work by Galle et al., has been implemented.
  • Added OdeLinearSystemSolver for solving large systems of ODEs of the form M dr/dt = f(t,r), where M is large and sparse.
  • Added two new force classes, BuskeInteractionForce and BuskeCompressionForce, to implement the model of cell-cell mechanical interactions used by Buske.
  • Added the ability to set/get cell radii in NodeBasedCellPopulation (via a member of NodesOnlyMesh), and allowed these to be updated when cell division/death occurs. Cell radii may also be written to VTK output.
• We have generalised the way that PDEs, coupled to cell-based simulations, are handled:
  • Altered the input arguments to the method CellBasedSimulationWithPdes::UseCoarsePdeMesh and allowed output of the PDE solution on the coarse mesh.
  • Enabled the numerical solution of one or more (steady) reaction-diffusion PDEs coupled to a NodeBasedCellPopulation, by introducing a "coarse" PDE mesh associated with the population.
  • Extended CellBasedEventHandler so that it also records the time spent solving any coupled PDEs, for use in CellBasedSimulationWithPdes.
  • Created an AbstractCellBasedPde class which contains the PDE, the solver, the boundary conditions and an interface to an AbstractCellPopulation. This class can be passed to a concrete instantiation of an AbstractCellBasedSimulation just as forces or update rules are; this change avoids having to implement PDEs in each of OffLatticeSimulation and OnLatticeSimulation.
• We have introduced a new method of imposing boundary conditions (such as restricted geometries) on cell-based simulations:
  • The CellBasedSimulation method ApplyCellPopulationBoundaryConditions has been removed.
  • Boundary conditions must now be implemented using the CellPopulationBoundaryCondition hierarchy. This change allows the use of multiple boundary conditions in a cell-based simulation, just as multiple force laws may be used.
• An example cell-cycle model class ContactInhibitionCellCycleModel has been added. This class may be used to simulate contact inhibition of cell division and assumes that the volume of each cell is stored in the singleton CellwiseData.
  • The simulation class VolumeTrackedOffLatticeSimulation has been created to be used with the contact inhibition cell cycle model.
• Cell cycle phases can now be written to file for visualization if required, in the file results.vizcellphases.

Minor new functionality and code changes, which may still require changes to user code

General

• Mesh-related changes:
  • The mesh reader now throws an Exception if attributes are declared in the header line but missing in the mesh files.
  • Added AbstractTetrahedralElement::CalculateNormal and AbstractTetrahedralMesh::CheckOutwardNormals to obtain normal vectors to boundary elements, and check they all face outwards, respectively.
  • Altered perimeter edges created in TetrahedralMesh::ConstructRectangularMesh and DistributedTetrahedralMesh::ConstructRectangularMesh so that they are all oriented anticlockwise. This makes sure that the normals are pointing outward.
  • Previously a QuadraticMesh had to read a tetrahedral mesh from file using a special converter (i.e. with the method ConstructFromLinearMeshReader). Now the usual method (ConstructFromMeshReader) may also be used. It warns that extra work is done, since a mesher library has to be used to construct the extra nodes.
• Build system changes:
  • You can now do a coverage build for a single test in a project (e.g. scons b=Coverage ts=projects/...).
  • We have worked around an SCons issue that causes parallel builds (e.g. -j3) with cl=0 to fail in parallel. However, it uses undocumented internal functionality in SCons, so please report an issue if it fails for you, and tell us what version of SCons you are using.
  • Removed broken support for the SPECIAL_SERIAL #define. This is unlikely to break anything, since it would have already been broken...
• Miscellaneous other changes:
  • The TERMINATE and NEVER_REACHED macros have been moved into Exception.hpp (from PetscTools.hpp), and various includes tidied up. Some macros have also been renamed for clarity and readability: EXPECTNON0 -> EXPECT_NON0, MPIABORTIFNON0 -> ABORT_IF_NON0. (The latter macro now works correctly in non-MPI-using tests.) Note also, if you are using PetscTools::Terminate directly rather than via a macro, that this method no longer exists - use Exception::Terminate instead.
  • The EXCEPTION and WARNING macros now allow 'streaming' within their message argument, so that you can write (for example)

    EXCEPTION("Number of nodes " << num_nodes << " does not match expected value of " << ELEMENT_DIM+1);

  • Exception subclasses may now change the error message after the base class is constructed.
  • A GetParent method has been added to FileFinder. A FileFinder can also now be created relative to some existing file or directory.
  • Functions CreateEmptyVector and IsEmptyVector have been added to VectorHelperFunctions.hpp
  • Moved the functions SmallPow and Divides from the linalg component into a new header MathsCustomFunctions.hpp.
  • A new class AbstractCvodeSystem has been created between AbstractCvodeCell and AbstractParameterisedSystem, analogously to AbstractOdeSystem.
    • AbstractCvodeSystem has a new method SetAutoReset. If this is turned on then CVODE will not have its internal state reset between calls to Solve (unless the state variables or simulation time are changed by external code in the meantime). A method ResetSolver has been added to force a reset if other changes are made externally that may require this (e.g. changing the RHS function by modifying a parameter).
  • Moved all methods of AbstractParameterisedSystem which don't require the vector type up into a new base class AbstractUntemplatedParameterisedSystem. This should not affect other code.
  • Renamed PetscMatTools::AssembleFinal to PetscMatTools::Finalise, PetscMatTools::AssembleIntermediate to PetscMatTools::SwitchWriteMode, and PetscVecTools::Assemble to PetscVecTools::Finalise. Similar name changes happened to the analogous LinearSystem convenience methods.
  • Changed AbstractLinearEllipticPde::ComputeConstantInUSourceTerm(rX) to AbstractLinearEllipticPde::ComputeConstantInUSourceTerm(rX, pElement) so it can take in an element containing rX to make it consistent with ComputeLinearInUCoeffInSourceTerm. You can pass in a NULL pointer for pElement. Changed all associated classes.
  • Method for writing strain per element added to AbstractNonlinearElasticitySolver. There is as yet no interface to it: to use it you must call it from the main output method.

Cardiac

• Changes to CellML support:
  • The cell model converter class is now more robust to certain errors, and gives more helpful error messages. Temporary files are now saved when an error occurs during the conversion of a cell model from CellML.
  • Various performance improvements have been made to the cell model code generation in PyCml.
  • PyCml now includes support for generating cell models that can be solved using the Rush-Larsen method. These are not available 'by default' but must be generated manually or loaded dynamically. See source:trunk/heart/test/ionicmodels/TestRushLarsen.hpp for some examples.
• A binary format has now been defined for fibre files, to enable random access into the file.

Cell-based

• Moved an uncaught exception (from the element Jacobian code) and turned it into a higher-level exception in MeshBasedCellPopulation, which is thrown when any element has zero area/volume.
• Added a method to perform vertex intersection swaps in the VertexMesh class.
• Resolved bug which prevented VTK or cell volume data at time-step zero being written to file.
• Calling GetCircularMesh on a HoneycombMeshGenerator that contains ghost nodes now throws an exception; previously the generator created a corrupt mesh.
• HoneycombMeshGenerator now defaults to not use ghost nodes.
• Moved the method GetNeighbouringNodeIndices from DiscreteSystemForceCalculator into AbstractCellPopulation, where it is pure virtual and hence overridden in subclasses.
• Added an overridden WriteCellVolumeResultsToFile method in all cell population subclasses.
• Added the SerializableSingleton class to allow for singleton classes and subclasses of AbstractCellBasedSimulation to be serialized more easily. This removed the need for the CryptSimulationArchiver class, which has been removed: simply use CellBasedSimulationArchiver instead.
• Added methods to get the centre of mass and dimensions of a cell population to CellBasedSimulationWithPdes.
• Added methods to NodesOnlyMesh to allow removal of nodes.

---

Release 2.3 (changes since Release 2.2)

Headline features

General

• Support for the latest version of CVODE (2.6.0)
• Reduced source download size (mainly through a reduction in the amount of data distributed with tests)

Cardiac

• A simple model of drug conductance block is now available in the standalone executable.
• A sequential implementation of adaptive mesh refinement has been added, using a library developed in collaboration with Imperial College London to reduce the computational load and memory footprint of large simulations. This is not available within the standalone executable however. Instructions for installing the required library are available on the Chaste wiki at InstallAdaptivityLibrary, and you will need to edit your hostconfig file to turn on support in Chaste (by setting use_adaptivity = True and adding appropriate paths etc.).

New functionality & major code changes

General

• Archiving of ODE systems with parameters has been improved. You can now add parameters without breaking archive backwards compatibility.
• A mixed-dimension mesh format has been defined and implemented (see the MixedDimensionMesh class) as the first step towards incorporating a Purkinje model in Chaste.
• Further improvements to the compressible elasticity solver (although this is still in the process of being implemented).

Cardiac

• Added an optional ApplyDrug element to the Physiological section of the XML parameters file. This applies conductance block model to as many channels as required. Note that conductances to block must be annotated in the CellML file with oxmeta names and as modifiable parameters. This has been done for the LR91 model as an example. If a channel is not found in the CellML file, a warning will be generated (once per node...).
  • NB This means that the parameter already in the LR91 model has changed name, which breaks archive backwards compatibility. Run the archive_convert.sed script on your archives to make them usable again. e.g. "find . -name *arch.? -print | xargs sed -i -f archive_convert.sed"
• The cardiac post-processing performance has been improved through greater use of caching.
• Alternative material laws for mechanics can now be set from a test (see the tutorials for an example).

Code interface changes, which may require changes to user code

General

• The interface of AbstractCvodeCell has been changed to be more like AbstractCardiacCell.
  • Moved SetStateVariables to AbstractParameterisedSystem. This means that its behaviour for AbstractCvodeCell has changed: it just copies the contents now, rather than handing over ownership of the vector. So callers must now delete the vector they pass to this method.
    • Hence removed AbstractCvodeCell::SetStateVariablesUsingACopyOfThisVector - use SetStateVariables instead.
  • Moved initial conditions methods (GetInitialConditions, SetDefaultInitialConditions, SetDefaultInitialCondition, and ResetToInitialConditions) to AbstractParameterisedSystem.
  • Added helper functions CreateVectorIfEmpty, CopyToStdVector, and CopyFromStdVector to VectorHelperFunctions.hpp.
• Made CalculateOnElement public in AbstractFunctionalCalculator so users can compute contributions to integrals on each element.

Cell-based

• NodeBasedCellPopulation constructors now take in a NodesOnlyMesh instead of a vector of nodes.

---

Release 2.2 (changes since Release 2.1)

Headline features

General

• Full default test pack should now pass on more configurations.
• Smarter chunking in HDF5 should reduce the time spent on I/O significantly for simulations with many output time steps.
• Mesh load is scalable in parallel only with our binary mesh format. A conversion utility is provided. Please refer to the MeshConvert tutorial.
• Performance of checkpointing with large meshes has been improved. We now archive permuted meshes without writing from memory to disc; instead the original files are copied.
• Further improvements to tutorials (including the addition of solid mechanics tutorials), and user documentation. Executable tutorials (as well as tutorial tests) are now routinely tested automatically.

Cardiac

• Added support for the definition of multiple bath/tissue regions. Based on whichever convention you followed in the elements file, you can inform Chaste of your choice of region identifiers with HeartConfig::SetTissueIdentifiers(std::set<unsigned> ) and HeartConfig::SetBathIdentifiers(std::set<unsigned> ). One can also assign different conductivities to different bath regions with HeartConfig::SetBathMultipleConductivities(std::map<unsigned, double> ).
• State variable interpolation may now be used for cardiac simulations. This can lead to improved conduction velocity accuracy on meshes with spatial resolutions typically used in simulation studies, and has been implemented in an efficient manner. See ChasteGuides/StateVariableInterpolation for more details.
• It is now possible to output visualisation in parallel VTK (.pvtu) format. To do this you need to set the parallel_vtk attribute to "yes" in the OutputVisualizer element in the parameters file.
• Fixed bug in fibre direction heterogeneities: when running in parallel some fibre directions were permuted between elements. (This bug did not exist prior to release 2.1.)
• Fixed bug with conductivity heterogeneities in 1D and 2D causing a 'boost::numeric::ublas::bad_size' error.
• User may now specify a list of node indices where time traces of output variables are requested (see below for details).
• A (Strang) operator splitting solver has been implemented for monodomain. This is mainly for comparison of numerical methods — it is neither the default solver nor optimised. It can be switched on using the HeartConfig class: HeartConfig::Instance()->SetUseDiffusionReactionOperatorSplitting().

Cell-based

• A new class CylindricalHoneycombMeshGenerator has been created and the existing HoneycombMeshGenerator class simplified. This included changing the arguments in the HoneycombMeshGenerator constructor. Also the class HoneycombMutableVertexMeshGenerator has been merged into HoneycombVertexMeshGenerator and the associated method GetMutableMesh renamed to GetMesh for consistency with the cell-centre code. These changes will break user projects.
• A new cell population boundary condition class hierarchy has been handled, to deal with boundary conditions for cell movement. Such objects are passed to and stored in a CellBasedSimulation object in a similar way to forces and cell killers.
• We have extended VTK functionality to allow for point data output from node- and mesh-based cell simulations for visualization in Paraview.
• We have updated user tutorials and added new tutorial on using cell population boundary condition objects.
• It has been made clear what code is needed in concrete CreateCellCycleModel methods.

New functionality & major code changes

General
• 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

We have improved Chaste compatibility with its library dependencies:
• 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.cs.ox.ac.uk/nss/parameters/2_0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://chaste.cs.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.
• 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.