The hostconfig system

The source release of Chaste relies on many libraries for core functionality. These can be found in different locations on different systems, and several different versions are supported. The hostconfig system, consisting of the files in python/hostconfig, is used to specify the settings for the current system.

The file used by the build system is hostconfig.py. This is not intended for user editing however, but loads a settings file. For core developers, it will try loading stored settings from the machines folder (see below). For other users, it will first try to find settings for your Linux distribution (currently only Ubuntu is supported, for the benefit of users installing the Ubuntu package), and if that fails, will use the file default.py. These choices may be overridden by supplying a file python/hostconfig/local.py with your settings.

NB: If you're not seeing expected behaviour from your hostconfig, it's worth running scons with hostconfig debugging turned on to see what settings Chaste is actually picking up. Use (e.g.) "scons debug=1" to do this. This will output which hostconfig file is being used, and the settings it contains.

Configuring the hostconfig system

The configuration file is actually a small Python program providing certain variables specifying where to find libraries and tools, along with some additional settings.

Several variables are used to specify which PETSc installation to use. Four variables give paths to different versions of PETSc:

• petsc_2_2_path - path to PETSc 2.2 install
• petsc_2_3_path - path to PETSc 2.3 install
• petsc_3_0_path - path to PETSc 3.0 install

OR both of these:

• petsc_path - path to PETSc install of a different (newer) version, given by
• petsc_ver - the version number e.g. "3.1", "3.2", "3.3" etc.

At least one of these must be defined. If you specify more than one, Chaste will by default attempt to use the newest version of PETSc it can find. If none of these variables specifies a usable PETSc installation, an error message will be given.

A particular PETSc installation may support multiple architectures/settings, by setting the PETSC_ARCH environment variable when compiling PETSc. You must tell Chaste which architecture to use by setting the petsc_build_name variables. There are 4 of these variables, allowing the use of different PETSc compilation options for different Chaste build types:

• petsc_build_name_production - for the IntelProduction build
• petsc_build_name_optimized - for GccOpt and Intel (and other optimized builds)
• petsc_build_name_profile - for Profile and GoogleProfile
• petsc_build_name - for other builds. This variable is also used as a default if any of the above variables are not specified.

The following variables are flags which indicate whether to use certain optional external libraries. If the variable is not present, it will default to False. If the variable is set to True, then the appropriate include and library paths (see below) should be specified, too.

• use_cvode - whether to use CVODE
• use_vtk - whether to use VTK development libraries
• use_adaptivity - whether to use the adaptivity library

For all libraries used except for PETSc and MPI, the paths to the folders containing the compiled libraries, and their header files, must be set, and the names of the libraries. The default.py file included with Chaste should give an indication of which libraries to use, but some systems will require additional libraries; consult your system administrator. These should be given in the following variables:

• other_includepaths - list of paths containing other header files
• other_libpaths - list of paths containing other libraries, including parmetis, xsd, and boost
• other_libraries - list of other libraries to link against

The blas and lapack library names are set separately, in the blas_lapack variable. Lapack must appear before blas in this list.

Other variables that may be set include:

• ccflags - any extra compiler flags needed, as a string.
• ldflags - any extra linked flags needed, as a string.
• tools - a dictionary mapping executable names to their full absolute paths, for tools not found on the PATH environment variable.

Particularly important tools that may need to be given here are mpicxx, mpirun and xsd.

Chaste can make use of the Intel compilers if they are available. There are a few variables that affect this.

• intel_path - path to Intel compiler installation (the folder containing lib and bin subfolders)
• icpc - this allows you to change the Intel compiler command, e.g. to add flags specific to 64-bit machines or specify the gcc libraries that the compiler should use.
• blas_lapack_production - the names of blas & lapack to use in an IntelProduction build. We use blas_lapack_production = ['mkl_lapack', 'mkl', 'svml'] to link against Intel's MKL libraries which provide the same functionality.

Any non-absolute paths will be considered relative to the root of the Chaste install.

Advanced usage

Since the settings file is a Python program, it may define functions. Three functions in particular have special meaning to the build system, and will allow advanced functionality if they are defined.

The first is ModifyBuild, which if defined will be called at the end of the configuration step. It is passed a single argument: the BuildType instance (see source:trunk/python/BuildTypes.py) for this build. This allows arbitrary modification of that object.

The other two functions allow easy switching between different versions of the libraries Chaste uses. As described briefly here, a hostconfig option may be appended to the build type, something like build=default_hostconfig,boost=1-37,petsc=3-0,hdf5=1-8,xsd=3-2,use-cvode=1,use-vtk=0.

For this build type option to work, one of the functions Configure or SetPreferedVersions must be defined in the hostconfig settings file. They differ in their signature and when they are called, but have a very similar purpose, and typically at most one will be defined. Both, if defined, will be called before attempting to read any of the variables described above, and thus can set those variables to appropriate values.

• Configure(prefs, build) is called regardless of whether the hostconfig build option was used, and is passed a prefs dictionary (described below) and BuildType instance.
• SetPreferedVersions(prefs) is called only if the hostconfig build option was used, and is passed a prefs dictionary.

The prefs dictionary contains the settings specified in the hostconfig build option. The option must follow the form hostconfig,name1=value1,name2=value2, and the name/value pairs are stored in the prefs dictionary. Due to restrictions on the allowed characters in build type names, the option string cannot include the '.' character, and so '-' is used instead; any dashes in the values will be converted to dots before being passed to the functions above.

Several functions are also pre-defined (in hostconfig.py) and made available to the settings program for use by the above functions if desired:

• ConfigError(message) - print an error message and quit
• CheckPathExists(path, component) - check that a path exists, and quit if not
• RemoveFromPath(pathList, searchString) - remove path entries from pathList that contain searchString
• TryRemove(pathGlob) - try to remove files matching the given glob pattern, ignoring errors
• Also a family of functions for adding library details to the other_* variables:
  • AddBoost(basePath, version)
  • AddHdf5(basePath)
  • AddXerces(basePath)
  • AddParMetis(basePath)
  • AddXsd(basePath)

There is a public example of using these functions at InstallGuides/TestingMultipleVersions.

The machines folder

The file source:trunk/python/hostconfig/machines/__init__.py determines which configuration file to use based on the hostname of the machine running Chaste, and so must be edited if adding a new settings file.

If you want to maintain local settings not committed to the repository, place them in a file python/hostconfig/local.py. (The older location of python/hostconfig/machines/local.py is also supported.)