OpenCMISS-Iron Internal API Documentation
Obtaining the Code and Setting up the Development Environment

Before Start

Before the installation, you need to check if the following libraries or tools are installed, preferably to the latest or recent versions. They will be used during the installation process.

  • For Fedora
    • gcc
    • gcc-c++
    • gcc-gfortran (Optional: to compile the libraries and OpenCMISS with gfortran, Can be installed later as a tool)
    • Intel Fortran Compiler (Optional: to compile the libraries and OpenCMISS with intel)
    • subversion
    • git (Optional: Can be installed later as a tool)
    • cmake (Optional: Can be installed later as a tool)
    • python-devel
    • numpy
    • bison
    • flex
    • swig
    • openmotif-devel
    • libXmu-devel
    • tcsh
  • For Ubuntu
    • gcc
    • g++
    • gfortran (Optional: to compile the libraries and OpenCMISS with gfortran, Can be installed later as a tool)
    • Intel Fortran Compiler (Optional: to compile the libraries and OpenCMISS with intel)
    • subversion
    • git (Optional: Can be installed later as a tool)
    • cmake (Optional: Can be installed later as a tool)
    • python-dev and python-setuptools
    • python-numpy
    • bison
    • flex
    • swig
    • libmotif-dev
    • libxmu-dev
    • csh

If you don't have

  • GNU Fortran (GCC) 4.4 or 4.6 or later (you may install it later during the OpenCMISSExtras compiler build)
  • cmake
  • git installed or you do not have the right version, you can download and build them as part of the installation steps (See Step 6). To do this, you need to set the USE_OPENCMISS_xxx environment variables to true in Step 4.2.

You may also like to install additional packages for your Linux distribution to save compiling libraries later.

  • For Fedora you can install
    • blas-devel and blas-static
    • lapack-devel and lapack-static
    • omniORB-devel
    • papi-devel and papi-static
    • SuperLU-devel
    • suitesparse-devel and suitesparse-static
    • scotch-devel
    • For MPICH2 (recommended for Fedora)
      • mpich2-devel
      • blacs-mpich2-devel and blacs-mpich2-static
      • scalapack-mpich2-devel and scalapack-mpich2-static
      • hdf5-mpich2-devel and hdf5-mpich2-static
      • netcdf-cxx4-mpich2-devel and netcdf-cxx4-mpich2-static
      • netcdf-fortran-mpich2-devel and netcdf-fortran-mpich2-static
    • For OpenMPI
      • openmpi-devel
      • MUMPS-devel
      • blacs-openmpi-devel and blacs-openmpi-static
      • scalapack-openmpi-devel and scalapack-openmpi-static
      • hdf5-openmpi-devel and hdf5-openmpi-static
      • netcdf-cxx4-openmpi-devel and netcdf-cxx4-openmpi-static
      • netcdf-fortran-openmpi-devel and netcdf-fortran-openmpi-static
  • For Ubuntu you can install
    • libblas-dev
    • liblapack-dev
    • libomniorb4-dev and omniidl (omniidl4 for Ubuntu 10.04 LTS)
    • For OpenMPI as the MPI library (recommended for Ubuntu)
      • libopenmpi-dev
      • libblacs-mpi-dev
      • libscalapack-mpi-dev
      • libhdf5-openmpi-dev
      • libnetcdf-dev
    • For MPICH2 as the MPI library
      • libmpich2-dev
      • libhdf5-mpich-dev

Installations

To fully install OpenCMISS, you need to install OpenCMISSExtras and OpenCMISS. OpenCMISSExtras contains the third party libraries, compilers, tools, FieldML and CellML required for OpenCMISS. Please follow the steps for the complete installation of OpenCMISS on the linux systems.

Step 1

Create OpenCMISSExtras directory and OpenCMISS directory

mkdir OpenCMISSExtras
mkdir OpenCMISS

Step 2

cd to the OpenCMISSExtras directory

cd OpenCMISSExtras

Step 3

In the OpenCMISSExtras directory, check out the utils repository:

svn co https://svn.physiomeproject.org/svn/opencmissextras/utils/trunk/ utils

note: you may need to accept a security certificate

Step 4

Set up your shell login script to call the opencmiss_programer script, which will set environment variables used when building OpenCMISS.

  1. Set the environment variables OPENCMISS_ROOT and OPENCMISSEXTRAS_ROOT to point to the directories that are created in Step 1.

If you use the bash shell you can do this by adding the following lines to your "~/.bashrc" file:

export OPENCMISS_ROOT=<path to your OpenCMISS folder>
export OPENCMISSEXTRAS_ROOT=<path to your OpenCMISSExtras folder>

If you use C Shell or tcsh Shell you can do this by adding the following lines to your "~/.cshrc" or "~/.tcshrc" file:

setenv OPENCMISS_ROOT <path to your OpenCMISS folder>
setenv OPENCMISSEXTRAS_ROOT <path to your OpenCMISSExtras folder>
  1. Set any additional programmer script variables. The opencmiss_programmers script in $OPENCMISSEXTRAS_ROOT/utils/scripts will let you customise the setup by setting environment variables after the root sets and before executing the script. These variables are:
  • USE_OPENCMISS_GFORTRAN : if set use the gfortran in the OpenCMISSextras repository. If not set use the system gfortran.
  • USE_OPENCMISS_CMAKE : if set use the cmake in the OpenCMISSextras repository. If not set use the system cmake.
  • USE_OPENCMISS_GIT : if set use the git in the OpenCMISSextras repository. If not set use the system git.
  • COMPILER : set the compiler to be used as the default. Options are gnu, intel or ibm.
  • GNU_COMPILER_VERSION : if using the OpenCMISSextras gfortran set what version to use. Options are 4.4, 4.5, 4.6 or 4.7
  • OPENCMISSEXTRAS_RUN_CONFIG : select which configuration of the OpenCMISSextras binaries to use at runtime. Options are debug or optimised.
  • MPI : select what version of MPI to use. Options are mpich2, intel, mvapich2, openmpi, poe or cray
  • TOTALVIEW_PATH : path to your version of Totalview.
  • TOTALVIEW_VERSION : the version number of your Totalview.
  • FLEXLM_VERSION : the version number of your Flexlm for Totalview.
  • CUDA_ROOT : the path to the CUDA runtime.
  • CUDA_SDK_ROOT : the path to the CUDA Software Development Kit.

The following variables are not required if you are using Intel compiler version 11 or below:

  • INTEL_COMPILER_VERSION : if using the pre 12.0 version of the intel compilers the compiler version to use e.g., 11.1
  • INTEL_COMPILER_BUILD : if using the pre 12.0 version of the intel compilers the build version to use e.g., 072
  • INTEL_TRACE_COLLECTOR_VERSION : the version of the intel trace collector to use e.g., 8.0.1.009
  • INTEL_MPI_VERSION : the version of the intel MPI to use e.g., 4.0.1.007

You can also set which libraries are used during the building of OpenCMISS and OpenCMISSExtras. If you set the following variables to true that library will be included, or not included if false. The variables are

  • OPENCMISS_USE_CELLML
  • OPENCMISS_USE_CUDA
  • OPENCMISS_USE_FIELDML
  • OPENCMISS_USE_HDF5
  • OPENCMISS_USE_HYPRE
  • OPENCMISS_USE_MUMPS
  • OPENCMISS_USE_NETCDF
  • OPENCMISS_USE_PARMETIS
  • OPENCMISS_USE_PASTIX
  • OPENCMISS_USE_PETSC
  • OPENCMISS_USE_PLAPACK
  • OPENCMISS_USE_SLEPC
  • OPENCMISS_USE_SUNDIALS
  • OPENCMISS_USE_SUPERLU
  • OPENCMISS_USE_TAO
  • OPENCMISS_USE_TAU

If you have installed system BLAS/LAPACK, BLACS/ScaLAPACK, MPI, HDF5, NETCDF, PAPI, TAU, omniORB packages from your Linux distribution you can force the use of OpenCMISSEXtras versions of these libraries by setting these environment variables to true

  • FORCE_OCE_BLASLAPACK
  • FORCE_OCE_BLACSSCALAPACK
  • FORCE_OCE_MPI
  • FORCE_OCE_HDF5
  • FORCE_OCE_NETCDF
  • FORCE_OCE_PAPI
  • FORCE_OCE_TAU
  • FORCE_OCE_OMNIORB

If you are in doubt about any of the variables just leave them out of your login script and they will default to a sensible value.

  1. Add in the lines in the login script to run the script:

If you use the bash shell you can do this by adding the following lines to your "~/.bashrc" file:

if [ -x ${OPENCMISSEXTRAS_ROOT}/utils/scripts/opencmiss_programmer.sh ]; then
. ${OPENCMISSEXTRAS_ROOT}/utils/scripts/opencmiss_programmer.sh
fi

If you use a c to tc shell you can do this by adding the following lines to your "/.cshrc" or "~/.tcshrc" file:

if ( -r ${OPENCMISSEXTRAS_ROOT}/utils/scripts/opencmiss_programmer.csh ) then
source ${OPENCMISSEXTRAS_ROOT}/utils/scripts/opencmiss_programmer.csh
endif
  1. Run the login script by either loging out and then back in or by sourcing it. If you use the bash shell, you can execute:
    . ~/.bashrc
    If you use a c shell, you can execute:
    source ~/.cshrc
    If you use tc shell, you can execute:
    source ~/.tcshrc

Note: you may get a warning about the OpenCMISS examples directory not existing. Ignore this until step 10.

Step 5

cd to the $OPENCMISSEXTRAS_ROOT/utils dir

cd $OPENCMISSEXTRAS_ROOT/utils

Step 6

Now you are ready to build the gcc and gfortran compiler (if required). If you do want to build gfortran from the OpenCMISSExtras repository, you need to define the USE_OPENCMISS_GFORTRAN environment variable described in Step 4.2.

  1. Build or update the required libraries from the repositories. If there is no previous compiler directories, you may use:
    make compiler_checkout
    If you have checked out or built the libraries before, or you want to update to the latest version, use:
    make compiler_update
  2. Clean the build (Optional). If you want to clean the previous build and do a fresh build, you may use:
    make compiler_clean
  3. Build the OpenCMISSExtras compiler. To build the OpenCMISSExtras compiler, use:
    make compiler
    You may specify the following options to the build:
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • (DEBUG=|OPT=): compile the libraries to the debug version or optimised (release) version

For example, to build the optimised version of the compiler:

make compiler OPT=true
  1. To ensure that the environment variables are set to ensure this compiler is used please log out and then log back in again.

Step 7

Now you are ready to build the OpenCMISSExtras tools - cmake and git (if required). If you want to build cmake and git from the OpenCMISSExtras repository, you need to define the relevant USE_OPENCMISS_xxx environment variables described in Step 4.2.

  1. Checkout or update the required libraries from the repositories. If there is no previous checkout, you may use:
    make tools_checkout
    If you have checked out or built the libraries before, or you want to update to the latest version, use:
    make tools_update
  2. Clean the builds (Optional). If you want to clean the previous build and do a fresh build, you may use:
    make tools_clean
  3. Build the OpenCMISSExtras tools. To build the OpenCMISSExtras tools, use:
    make tools
    You may specify the following options to the build:
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • COMPILER=(intel|gnu|ibm|cray): to use the fortran and c compiler as specified
  • (DEBUG=|OPT=): compiler the libraries to the debug version or optimised (release) version

For example, to build the optimised version of libraries using the Intel compiler:

make tools COMPILER=intel OPT=true
  1. To ensure that the environment variables are set to ensure these tools are used please log out and then log back in again.

Step 8

Now you are ready to build the OpenCMISSExtras libraries via the make script. If you want to include or exclude various libraries from the OpenCMISSExtras repository, you need to define the relevant USE_OPENCMISS_xxx environment variables described in Step 4.2.

  1. Checkout or update the required libraries from the repositories. If there is no previous checkout, you may use:
    make checkout
    If you have checked out or built the libraries before, or you want to update to the latest version, use:
    make update
  2. Clean the builds (Optional). If you want to clean the previous build and do a fresh build, you may use:
    make clean
  3. Build the OpenCMISSExtras libraries. To build the OpenCMISSExtras libraries, use:
    make
    You may specify the following options to the build:
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • COMPILER=(intel|gnu|ibm|cray): to use the fortran and c compiler as specified
  • (DEBUG=|OPT=): compiler the libraries to the debug version or optimised (release) version
  • MPI=(mpich2|intel|openmpi|mvapich2|cray): to use the mpi as specified
  • PROF=(true|): to do a profile build
  • MPIPROF=(true|): to do a profile build with mpi

For example, to build the optimised version of libraries using the Intel compiler:

make COMPILER=intel OPT=true
  1. To ensure that the environment variables are set to ensure these libraries are used please log back out and then log in again.

Step 9

cd to the OpenCMISS folder that is created in Step 1.

cd $OPENCMISS_ROOT

Step 10

To obtain the OpenCMISS source you need to clone the Git repository. There are three parts of OpenCMISS to obtain - OpenCMISS itself, the OpenCMISS examples, and OpenCMISS CellML.

If you wish to make changes to OpenCMISS it is recommended that you fork the repositories on GitHub so that your changes can be pulled into the central repository from your GitHub account. The process of forking the OpenCMISS repositories and the workflow to use with Git is described in a page on the OpenCMISS wiki (https://sourceforge.net/apps/mediawiki/opencmiss/index.php?title=Proposed_Workflow).

The OpenCMISS cm repository is at https://github.com/OpenCMISS/cm.

The OpenCMISS examples repository is at https://github.com/OpenCMISS/examples/.

The OpenCMISS cellml repository is at https://github.com/OpenCMISS/cellml/.

Once you have forked the OpenCMISS cm, examples and cellml repositories on GitHub, you can clone them to your local machine by issuing the following commands in the OpenCMISS directory, where <username> should be replaced with your GitHub username:

git clone https://github.com/<username>/cm.git cm
git clone https://github.com/<username>/examples.git examples
git clone https://github.com/<username>/cellml.git cellml

If you know you will not need to make changes to one or more of the repositories you can clone them directly from https://github.com/OpenCMISS/.

You can also clone example repository to a location other than $OPENCMISS_ROOT/examples directory. To do this, you need to specify the OPENCMISSEXAMPLES_ROOT variable in your login script:

export OPENCMISSEXAMPLES_ROOT=<path to your examples folder>

If you use C Shell or tcsh Shell you can do this by adding the following lines to your "~/.cshrc" or "~/.tcshrc" file:

setenv OPENCMISSEXAMPLES_ROOT <path to your examples folder>

Once the cm, examples and cellml repositories have been cloned you should set the git upstream repositories

cd cm
git remote add upstream https://github.com/OpenCMISS/cm.git
cd ../examples
git remote add upstream https://github.com/OpenCMISS/examples.git
cd ../cellml
git remote add upstream https://github.com/OpenCMISS/cellml.git

Additional information on git can be found at http://sourceforge.net/apps/mediawiki/opencmiss/index.php?title=Git_Workflow

Step 11

Build the OpenCMISS celllml.

  1. cd to the cellml directory.
    cd $OPENCMISS_ROOT/cellml
  2. Build the OpenCMISS cellml
    make
    You may specify the following options to the build:
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • COMPILER=(intel|gnu|ibm|cray): to use the fortran and c compiler as specified
  • (DEBUG=|OPT=): compiler the libraries to the debug version or optimised (release) version

Step 12

Build OpenCMISS.

  1. cd to the cm directory.
    cd $OPENCMISS_ROOT/cm
  2. Build the OpenCMISS.
    make
    You may specify the following options to the build:
  • (DEBUG=|OPT=): compiler the libraries to the debug version or optimised (release) version
  • MPI=(mpich2|intel|openmpi|mvapich2|cray): to use the mpi as specified
  • PROF=(true|): to do a profile build
  • MPIPROF=(true|): to do a profile build with mpi
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • COMPILER=(intel|gnu|ibm|cray): to use the fortran and c compiler as specified
  • USECELLML=(false|true): to use CellML or not
  • USEFIELDML=(false|true): to use FieldML or not

For example, to build the optimised version of libraries using the Intel compiler and FieldML:

make COMPILER=intel OPT=true USEFIELDML=true
  1. Build OpenCMISS with Python binding. You may build OpenCMISS with python binding by
    make python

Step 13

Build an example.

  1. cd to an example directory, e.g the Laplace example
    cd $OPENCMISSEXAMPLES_ROOT/ClassicalField/Laplace/Laplace/Fortran
  2. Build the example
    make
    You may specify the following options to the build:
  • (DEBUG=|OPT=): compiler the libraries to the debug version or optimised (release) version
  • MPI=(mpich2|intel|openmpi|mvapich2|cray): to use the mpi as specified
  • PROF=(true|): to do a profile build
  • MPIPROF=(true|): to do a profile build with mpi
  • ABI=(32|64): to build 32 bit or 64 bit libraries
  • COMPILER=(intel|gnu|ibm|cray): to use the fortran and c compiler as specified
  • USECELLML=(false|true): to use CellML or not
  • USEFIELDML=(false|true): to use FieldML or not
  1. Execute the example: You may specify the arguments to execute the example, e.g. For a 64-bit linux using MPICH2 and GNU 4.4 compilers you could type
    ./bin/x86_64-linux/mpich2/gnu_4.4/FortranExample-debug 4 4 4 1
    For other versions of MPI or compiler please adjust the path to the FortranExample-debug example appropriately.
  2. Execute the example with mpi: To execute the example with mpi running on two computational nodes:
    mpiexec -2 ./bin/x86_64-linux/mpich2/gnu_4.4/LaplaceExample-debug 4 4 4 2
  3. Build and execute examples with python binding, e.g.
    cd $OPENCMISSEXAMPLES_ROOT/ClassicalField/Laplace/Laplace/Python
    and
    python ./LaplaceExample.py

Additional Notes

If you are using totalview, after installation you will also need to add

export LM_LICENSE_FILES=<path-to-the-flex-directory>

respectively,

setenv LM_LICENSE_FILES <path-to-the-flex-directory>

Details of totalview installation can be found here.

-For ABI users, you may use totalview installed in hpc3. It is installed in /usr/toolwork. Please make sure that you have set LM_LICENSE_FILES

export LM_LICENSE_FILES=/usr/toolworks/flexlm-10.8.0-3/

respectively,

setenv LM_LICENSE_FILES /usr/toolworks/flexlm-10.8.0-3/

Obtaining the Code and Libraries