Skip to content

Installation

Jump to bottom
bwvdnbro edited this page Feb 23, 2016 · 2 revisions

Installation instructions

Shadowfax uses the CMake build system, that normally does a good job locating the necessary dependencies. These dependencies are:

If all of these have been installed on standard locations, the installation process simply consists of

  • Obtaining the latest version of Shadowfax from github using git clone
  • Creating a build directory and running cmake
  • Running make

For all cases where this simple procedure somehow fails, or for users new to git and CMake, detailed instructions for different operating systems are provided below:

No installation instructions for Windows are or will ever be provided.

Linux

To install the necessary dependencies, install the following packages using your favourite package manager:

  • git
  • cmake
  • openmpi-bin, libopenmpi-dev
  • libhdf5-serial-dev or libhdf5-openmpi-dev
  • libboost-dev
  • doxygen

On e.g. Ubuntu 12.04, the default Boost version is too old. In this case, or in case you experience problems with the standard Boost library, you need to manually install Boost.

It is also possible to use another MPI library than Open MPI and it might be necessary to install the corresponding HDF5 library (although libhdf5-serial-dev will do fine).

Once the dependencies have been installed, you can get the latest version of the code from the repository by typing the following command into a terminal window:

git clone https://github.com/AstroUGent/shadowfax

This downloads the entire repository into a new folder shadowfax inside the current folder. We will call the path to the main folder SHADOWFAX_PATH below. If you e.g. call the git command from /home/username/Programs/, SHADOWFAX_PATH will be /home/username/Programs/shadowfax.

Now create a build folder where you want the compiled program to reside. This can be any arbitrary folder in your system, but usually this is a subfolder of SHADOWFAX_PATH, e.g. SHADOWFAX_PATH/build. From this newly created folder, execute the following command

cmake -DCMAKE_BUILD_TYPE=Release SHADOWFAX_PATH/

where you replace SHADOWFAX_PATH by the appropriate path. The CMAKE_BUILD_TYPE=Release option tells cmake to generate build files with compiler optimizations and without debugger symbols that will slow down the code. This is recommended for normal users. More info on CMake options can be found on a dedicated page. CMake now locates all dependencies and generates build files that can be used to compile the code. It throws errors if dependencies cannot be found.

Once CMake successfully finishes, you can compile shadowfax using

make

This takes a while.

If the compilation process succeeds, 6 executables are created in SHADOWFAX_PATH/build/rundir/: the main simulation programs shadowfax2d and shadowfax3d, the initial condition generating programs icmaker2d and icmaker3d, and the programs that convert snapshots to VTK files, vtkmaker2d and vtkmaker3d. CMake should also have copied the testsuite to SHADOWFAX_PATH/build/rundir/. If you are new to shadowfax, running the test problems is a good place to start.

Code documentation can be generated using

make doc

This creates Doxygen documentation based on the comments in the source code files. shadowfax is fully documented.

If you want to use h5py to easily create and read HDF5 files from Python, you need to install the python-h5py package, as well as python and python-numpy.

Mac OSX

In Mac OSX, you need to install XCode, which gives you git and the necessary C++ compilers.

The other dependencies need to be manually installed:

The rest of the installation process is similar to that on Linux systems. To obtain the latest version of the code, type the following command from a terminal window:

git clone https://github.com/AstroUGent/shadowfax

This downloads the entire repository into a new folder shadowfax inside the current folder. We will call the path to the main folder SHADOWFAX_PATH below. If you e.g. call the git command from /home/username/Programs/, SHADOWFAX_PATH will be /home/username/Programs/shadowfax.

Now create a build folder where you want the compiled program to reside. This can be any arbitrary folder in your system, but usually this is a subfolder of SHADOWFAX_PATH, e.g. SHADOWFAX_PATH/build. From this newly created folder, execute the following command

cmake -DCMAKE_BUILD_TYPE=Release SHADOWFAX_PATH/ -DBOOST_ROOT=BOOST_BUILD_FOLDER

where you replace SHADOWFAX_PATH and BOOST_BUILD_FOLDER by the appropriate paths (more info on manually installing Boost). The CMAKE_BUILD_TYPE=Release option tells cmake to generate build files with compiler optimizations and without debugger symbols that will slow down the code. This is recommended for normal users. More info on CMake options can be found on a dedicated page. CMake now locates all dependencies and generates build files that can be used to compile the code. It throws errors if dependencies cannot be found.

Once CMake successfully finishes, you can compile shadowfax using

make

This takes a while.

If the compilation process succeeds, 6 executables are created in SHADOWFAX_PATH/build/rundir/: the main simulation programs shadowfax2d and shadowfax3d, the initial condition generating programs icmaker2d and icmaker3d, and the programs that convert snapshots to VTK files, vtkmaker2d and vtkmaker3d. CMake should also have copied the testsuite to SHADOWFAX_PATH/build/rundir/. If you are new to shadowfax, running the test problems is a good place to start.

Code documentation can be generated using

make doc

This creates Doxygen documentation based on the comments in the source code files. shadowfax is fully documented.

If you want to use h5py to easily create and read HDF5 files from Python, you need to install it. More information can be found on the h5py website.

Clone this wiki locally