WARPXM v1.10.0
Loading...
Searching...
No Matches
Install instructions

Table of Contents

Building from source

Dependencies

Required:

Suggested:

  • Python 3: Used for the Python WAPPXM interface library warpy.
  • Python packages:
    • NumPy: Used for vectors and a number of mathimatical functions.
    • h5py: Used to interface with hdf5 data files.
    • GitPython: Used to write out git version and commit information to the simulation output directory. Automatic Git info write out can be turned off by setting write_git_info=False in the user warpy config file. See warpy documentation for details.

Optional:

  • Doxygen: for building the documentation.

Pre-install setup for Mac OS

Assuming you have a clean system, these are the pre-install steps you should take to get all the dependencies (there may be other methods for getting the required dependencies, this one was tested and should work):

  1. Open the App Store and install XCode
  2. Open XCode once (to accept the license agreement)
  3. Install homebrew (follow instructions at https://brew.sh)
  4. Install OpenMPI, CMake, and PkgConfig using homebrew:
    brew install openmpi pkg-config cmake
  5. Ensure you have Python 3 available. Note: Anaconda installs a serial version of HDF5 which interferes with the WARPXM build process. Try to install Python via some other method, or ensure that CMake doesn't link to the serial HDF5.
  6. Open up $HOME/.bash_profile and add at the end (this is assuming libraries/dependencies are going to be installed in $HOME/usr, and that WARPXM is going to be built in $HOME/code/warpxm/build):
    export PYTHONPATH=$HOME/code/warpxm/build/tools/:$PYTHONPATH
    export PATH=$HOME/usr/bin:/usr/local/bin:$PATH
    export LD_LIBRARY_PATH=$HOME/usr/lib:$LD_LIBRARY_PATH
    export PKG_CONFIG_PATH=$HOME/usr/lib/pkgconfig:$PKG_CONFIG_PATH
    # fix for TMPDIR because of bug in MPI on Mac OS
    export TMPDIR=/tmp
    IMPORTANT NOTE: If DYLD_LIBRARY_PATH is set to where WARPXM gets installed to, there is a high likelyhood that what shared library WARPXM loads at runtime will not be correct. It is highly recommended that you do NOT have this environment variable set; if you need to set any additional environment variables, you should use DYLD_FALLBACK_LIBRARY_PATH.
  7. Reload your bash profile using one of the following options:
    • Logout and back in
    • Close and re-open your terminal
  8. Create the required directories in your home directory:
    cd ~
    mkdir tools
    mkdir code
    mkdir usr

At this point you're ready to start building PETSc and WARPXM.

Pre-install setup for Ubuntu Linux desktop

Assuming you have a clean system, these are the pre-install steps you should take to get all the dependencies:

  1. Install the following using apt-get:
    sudo apt-get install openmpi-bin libopenmpi-dev gfortran g++ cmake git libblas-dev pkg-config
  2. Open up $HOME/.bashrc (or equivalent) and add at the end (this is assuming libraries/dependencies are going to be installed in $HOME/usr, and that WARPXM is going to be built in $HOME/code/warpxm/build):
    export PYTHONPATH=$HOME/code/warpxm/build/tools/:$PYTHONPATH
    export PATH=$HOME/usr/bin:/usr/local/bin:$PATH
    export LD_LIBRARY_PATH=$HOME/usr/lib:$LD_LIBRARY_PATH
    export PKG_CONFIG_PATH=$HOME/usr/lib/pkgconfig:$PKG_CONFIG_PATH
  3. Reload your bashrc using one of the following options:
    • Logout and back in
    • Close and re-open your terminal
  4. Create the required directories in your home directory:
    cd ~
    mkdir tools
    mkdir code
    mkdir usr

At this point you're ready to start building PETSc and WARPXM.

Pre-install setup for Linux HPC machines

Building on Linux HPC machines is generally specialized to the particular cluster. Here are a general sequence of steps you should take to get WARPXM working on a cluster:

  1. Add to the beginning of your .bashrc (or equivalent):
    export PYTHONPATH=$HOME/code/warpxm/build/tools/:$PYTHONPATH
    export PATH=$HOME/usr/bin:/usr/local/bin:$PATH
    export LD_LIBRARY_PATH=$HOME/usr/lib:$LD_LIBRARY_PATH
    export PKG_CONFIG_PATH=$HOME/usr/lib/pkgconfig:$PKG_CONFIG_PATH
  2. Reload your bashrc by logging out and back in
  3. Load the CMake, MPI, and C/C++/Fortran compiler suite modules (To save time in the future, you can add these to your .bashrc or equivalent to auto-load these modules on login)

At this point you're ready to start building PETSc (unless you have loaded it as a module) and WARPXM.

Details about installing WARPXM on specific HPC clusters are also available:

Building PETSc

PETSc is a required dependency of WARPXM. WARPXM uses the SNES non-linear solvers (and associated linear solvers/pre-conditioners). To build a minimal PETSC install (note: this will install PETSc to $HOME/usr. Change the prefix to install to a different directory):

cd ~/tools
git clone https://gitlab.com/petsc/petsc.git
cd petsc
git checkout release
./configure --COPTFLAGS="-O3" --CXXOPTFLAGS="-O3" --FOPTFLAGS="-O3" --download-hypre --download-superlu_dist --download-metis --download-parmetis --download-hdf5 --with-debugging=0 --prefix=$HOME/usr
# on Linux:
make PETSC_DIR=$(pwd) PETSC_ARCH=arch-linux2-c-opt all
make PETSC_DIR=$(pwd) PETSC_ARCH=arch-linux2-c-opt install
# on Mac OS:
make PETSC_DIR=$(pwd) PETSC_ARCH=arch-darwin-c-opt all
make PETSC_DIR=$(pwd) PETSC_ARCH=arch-darwin-c-opt install

Note that PETSc provides a modified version of METIS which is not ABI compatible with standard METIS. It is possible to get PETSc to build with a system installed METIS by changing --download-metis to --with-metis. It is usually easier to build WARPXM with METIS provided by PETSc rather than getting PETSc to use an existing install of METIS.

If your system does not have a provided BLAS library, you can ask PETSc to download and build one for you. In that case, for the configure step use

./configure --COPTFLAGS="-O3" --CXXOPTFLAGS="-O3" --FOPTFLAGS="-O3" --download-hypre --download-superlu_dist --download-metis --download-parmetis --download-hdf5 --download-fblaslapack=1 --with-debugging=0 --prefix=$HOME/usr

If PETSc is not installed to a "standard" location, you must modify the PKG_CONFIG_PATH. In .bashrc (or equivalent file), add:

# for PETSc installed to $HOME/usr
# you will need to modify accordingly if PETSc is not installed to /usr or /usr/local
export PKG_CONFIG_PATH=$HOME/usr/lib/pkgconfig:$PKG_CONFIG_PATH

Basic Building

It is highly recommended to build out-of-source. This project uses CMake to configure. Important parameters:

  • CMAKE_BUILD_TYPE: Which build configuration to use (Release, Debug, etc.). Defaults to Release build.
  • CMAKE_CXX_FLAGS: Additional C++ compiler flags.
  • CMAKE_INSTALL_PREFIX: Where to install project to. Defaults to /usr/local on Linux.
  • BUILD_DOCUMENTATION: Whether doxygen documentation should be built.
  • BUILD_EXAMPLES: Whether example should be built.
  • BUILD_TESTING: Whether tests should be built.
  • WARPXM_INTERNAL_DOCS: Build internal docs useful for developers.

Example configuration for Unix:

cd ~/code
# clone git repo
mkdir warpxm
cd warpxm
git clone git@github.com:UW-Computational-Plasma-Group/warpxm.git warpxm
mkdir build
cd build
# this defaults to building a Release optimized build
cmake ../warpxm -DCMAKE_INSTALL_PREFIX=$HOME/usr
make
# build documentation (requires Doxygen)
make doc
# installs into prefix directory
make install
# run tests (recommended for your first build)
make test
# Update git repo
cd ~/code/warpxm/warpxm
git pull

Additional info on using CMake can be found on their Wiki.

Advanced Build Options and Tips

The recommended method for having multiple build configurations is to create multiple build directories (only applicable to non-IDE project generator targets). For example, to create builds for a debug and release builds:

mkdir ${PROJ_ROOT}/../build/release
cd ${PROJ_ROOT}/../build/release
# configure as release build
cmake ${PROJ_ROOT} -DCMAKE_BUILD_TYPE=Release
make
# run tests
make test
mkdir ${PROJ_ROOT}/../build/debug
cd ${PROJ_ROOT}/../build/debug
# configure as debug build
cmake ${PROJ_ROOT} -DCMAKE_BUILD_TYPE=Debug
make
# run tests
make test

Troubleshooting some common problems

  • Building tests requires internet access to download GoogleTest. If you do not have internet access on the machine building WARPXM, you can disable building tests:
    cmake ${PROJ_ROOT} -DBUILD_TESTING=Off
    make
  • If a test reports a failure, you can find detailed information on the failure in the file ${PROJ_BUILD_DIR}/Testing/Temporary/LastTest.log

IDE Project Generation

CMake is capable of producing projects for various common IDE's, notably XCode (see here for tutorial) and Visual Studio (see here for tutorial).