News

Archive

RSS Feed

Downloading and installing

Requirements

Installation instructions for 3rd party software can be found at the bottom of the page.

Minimum

A fortran, c++ compiler and cmake version 2.8.7 or higher.

Optionally

Python, Doxygen, GraphViz (Dot), MPI, METIS and PETSc

Doxygen is required to build a local copy of the documentation and GraphViz to create the uml diagrams for the documentation. MPI and METIS are required for parallel builds of hpGEM. PETSc is set of scientific routines for scientific computing. It is required by some hpGEM applications. Python is used by the test suite for comparing output files. It is not required to run hpGEM normally, but some tests will fail if you do not have it installed.

Checking what packages you have

You only have to check for cmake, as cmake will check for the other packages for you. See installation instructions below.

Downloading the code

You can download hpGEM using this link

Installation

1) Version 2 of hpGEM is installed using cmake version 2.8.7 or higher. So first check if you have cmake installed and what version by typing

cmake --version

If reports an error (i.e. you do not have cmake), or your version is older 2.8.7, please install cmake; otherwise, proceed to step 2.

Installing cmake

Download cmake from the following website.

www.cmake.org/cmake/resources/software.html

You have a choice of obtaining binaries (easy option) or building from source. Below is addition information on building from source.

a) If you have old version of cmake installed unpack and untar the downloaded file. Then change to this directory and type
cmake .
make
make install
b) If you do have any version of cmake installed.
i) For mac, linux and cygwin unpack and untar the downloaded file. Then change to this directory and type
./bootstrap
make
make install
ii) For windows download the installer from the downloads page.

Note, up-to-date installation instructions for cmake can be found at
http://www.cmake.org/cmake/help/install.html

Very important note, if you are updating scroll down to the bottom of the page and follow the update installation instructions. Do not reinstall you can use an older version of cmake to install the latest version.

2) Installing hpGEM using cmake

cmake is designed for out of source building and we do higher recommend this. So first make a directory for the build, say

mkdir hpGEM_BUILD
For the purpose of the rest of this tutorial we will use $hpGEM_SRC for your source files location and $hpGEM_BUILD for your build directory location.

There are three flavours of cmake: cmake, ccmake and cmake-gui; and, for beginners we recommend cmake-gui.

(a) Graphical cmake : cmake-gui

(i) Type
cd $hpGEM_BUILD/
cmake-gui $hpGEM_SRC

You will be presented with cmake configuration window. Confirm the source code directory is correct i.e. the field "where is the source code" and check the build directory i.e. "where to build the binaries" is also correct.
(ii) Click the configure button. From the drop-down menu you can choice whether to create file for a given IDE or 'Unix Makefiles'. We will assume you choose 'Unix Makefiles' and select use "Use default native compilers".
(iii) Click Done. In the at the bottom of the screen it will report the locations of the required compilers and other files. If you see red text you are missing a required compiler, please install the missing component and try again.
(iv) In the top box you will see two items CMAKE and hpGEM. From here you can configure/customise a lot of options. Here we will just highlight two you are likely to use
a) On the hpGEM menu you see "hpGEM_BUILD_DOCUMENTATION", select this if you want a local copy of the documentation to be available. Note this does require doxygen to be installed and GraphViz (Dot) for the UML diagrams are included as well.

b) On the CMAKE menu you will see "CMAKE_BUILD_TYPE".

  • Enter the word 'Debug' in this box if you want to build the code in debug mode. Slower version but output can be run through a debugger.
  • Enter the word 'Release' in this box for a optimised version of the code. Note, this version does not be run through a debugger but can be over four times faster.
(v) After any change click the 'Configure' button again. Some or all of the optional components might be required for the options you selected. Again, if they are missing, this will be reported in red text. Please install the missing component and try again. Note that PETSc cannot be detected fully automatically. See below for additional instructions.
(vi) Once you have it configured click 'Generate' this will create the required makefile (or kdevelop project if you choice that option etc.)
(vii) Exit cmake-gui and you will find newly created makefile in your build directory.

(b) QT : ccmake
(i) Type
cd $hpGEM_BUILD
ccmake $hpGEM_SRC

(ii) Type c to configure. Error message will be reported to the screen if you are missing packages please install them and try again.
(iii) Use the arrow keys you can navigate around and from you can configure/customise a lot of options. Here we will just highlight two you are likely to use
a) Setting "hpGEM_BUILD_DOCUMENTATION" will enable a local copy of the documentation to be built. Note this does require doxygen to be installed and GraphViz(Dot) if the UML diagrams are to be included as well.
b) Entering the word 'Debug' in the "CMAKE_BUILD_TYPE" box, will cause the code to be built in debug mode.
(iii) After any change type 'c' again to reconfigure.
(iv) Once you have it configured as you want type 'g'. This will generate the require makefiles and quit the program.

(c) make style : cmake

(i) Type

cd $hpGEM_BUILD
cmake $hpGEM_SRC

(ii) This will check you have the correct packages installed and if you have create the required makefiles.
(iii) Note you can pass many additional flags to this package to customise the installation. Here we will highlight two you are likely to use
a) Adding the flag '-DhpGEM_BUILD_DOCUMENTATION=on will enable a local copy of the documentation to be build. Note this does require doxygen to be installed and GraphViz(Dot) if the UML diagrams are to be included as well.
b) Adding the flag '-DCMAKE_BUILD_TYPE=Debug' will cause the code to be build in debug mode.

3) Building the project

make 

4) Testing the installation

make test

5) Installing a local code of the documentation (only available if you enabled this option in step 2)

make doc
firefox docs/html/index.html

Note: replace firefox with which every web browser you have installed

or on a mac

make doc
open docs/html/index.html

Obtaining the 3rd Party Packages

C++ Compiler

This should come with integrated development environments (IDEs).

  • So please download and install any IDE. On a MacOS please install the latest version of XCode.
  • If prompted to install command line links, please click 'yes'.
Fortran compiler

For all non windows operating systems we recommend gfortran which is available from

Doxygen (optional - only required to create local version of documentation)
GraphViz (optional - required for doxygen to generate UML diagrams. Highly recommended it you installed Doxygen)
MPI (optional - required for parallel computation)
  • This is already installed on most suitable systems. Contact your system administrator for usage instructions.
  • If this is not the case go to http://www.open-mpi.org/software/ompi/v1.8/
  • Download and install the binary for your operating system
Metis (optional - required for parallel computation. Required if you use MPI)
make install
PETSc (optional - required for implicit hyperbolic problems and elliptic problems)

Configuring hpGEM to use PETSc

These instructions assume you use cmake-gui.

  1. After you have clicked 'Configure' at least once, check the box 'hpGEM_USE_PETSC in the hpGEM menu.
  2. Click configure. This will likely produce some errors. This is not a problem.
  3. This created the PETSC menu. Uncheck the box 'PETSC_CURRENT'. Make sure PETSC_DIR is set to the PETSc installation directory.
  4. We also need a variable called PETSC_ARCH, if you don't see it in the PETSC menu, click 'Add Entry'.
  5. This will pop up a dialog. Enter the following: (case sensitive, without quotes)
    1. Name: 'PETSC_ARCH'
    2. Type: 'STRING'
    3. Value:
      • If you did not set PETSC_ARCH during installation of PETSc, it is the name of the folder that starts with 'arch' in your PETSc installation directory.
    4. Description:
  6. Close the dialog by clicking 'Ok'
  7. Make sure PETSC_ARCH is set to the value you used during installation of PETSc.
  8. Click 'Configure'. This time it should work without errors.
  9. Click 'Generate', close cmake-gui and continue with the installation of hpGEM at '3) Building the project'