diff --git a/CMakeLists.txt b/CMakeLists.txt
index ba2639af321dec5eb9ca1e7495a3b2ed1680e65b..f91e332eecdd77b327846951ed9271d740e926df 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -20,15 +20,15 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 
 # TBB support
-set(WITH_TBB "ON" CACHE BOOL "use TBB for on-node threading")
-if("${WITH_TBB}" STREQUAL "ON")
+set(WITH_TBB OFF CACHE BOOL "use TBB for on-node threading" )
+if(WITH_TBB)
     find_package(TBB REQUIRED)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DWITH_TBB ${TBB_DEFINITIONS}")
 endif()
 
 # MPI support
-set(WITH_MPI "ON" CACHE BOOL "use MPI for distributed processing")
-if("${WITH_MPI}" STREQUAL "ON")
+set(WITH_MPI OFF CACHE BOOL "use MPI for distrubuted parallelism")
+if(WITH_MPI)
     find_package(MPI REQUIRED)
     include_directories(SYSTEM ${MPI_C_INCLUDE_PATH})
     add_definitions(-DWITH_MPI)
@@ -37,6 +37,12 @@ if("${WITH_MPI}" STREQUAL "ON")
     set_property(DIRECTORY APPEND_STRING PROPERTY COMPILE_OPTIONS "${MPI_C_COMPILE_FLAGS}")
 endif()
 
+# Cray systems
+set(SYSTEM_CRAY OFF CACHE BOOL "add flags for compilation on Cray systems")
+if(SYSTEM_CRAY)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -dynamic")
+endif()
+
 # targets for extermal dependencies
 include(ExternalProject)
 externalproject_add(modparser
diff --git a/README.md b/README.md
index 0cb0c0d8dd27b41cf9358aebb5761cf221c72bef..dc2e7d720fa5452c15f2db6b2e7ad6001928cb85 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,9 @@ git submodule init
 git submodule update
 
 # setup environment
-module load gcc 
+# on a desktop system this might not be required
+# on a cluster this could be required
+module load gcc
 module load cmake
 export CC=`which gcc`
 export CXX=`which g++`
@@ -25,3 +27,53 @@ make -j
 cd tests
 ./test.exe
 ```
+
+## MPI
+
+Set the `WITH_MPI` option either via the ccmake interface, or via the command line as shown below.
+For the time being our CMake configuration does not try to detect MPI.
+Instead, it relies on the user specifying an MPI wrapper for the compiler by setting the `CXX` and `CC` environment variables.
+
+```
+export CXX=mpicxx
+export CC=mpicc
+cmake <path to CMakeLists.txt> -DWITH_MPI=ON
+
+```
+
+## TBB
+
+Support for multi-threading requires Intel Threading Building Blocks (TBB).
+When TBB is installed, it comes with some scripts that can be run to set up the user environment.
+The scripts set the `TBB_ROOT` environment variable, which is used by the CMake configuration to find TBB.
+
+
+```
+source <path to TBB installation>/tbbvars.sh
+cmake <path to CMakeLists.txt> -DWITH_TBB=ON
+```
+
+### TBB on Cray systems
+
+To compile with TBB on Cray systems, load the intel module, which will automatically configure the environment.
+
+```
+# load the gnu environment for compiling the application
+module load PrgEnv-gnu
+# gcc 5.x does not work with the version of TBB installed on Cray
+# requires at least version 4.4 of TBB
+module swap gcc/4.9.3
+# load the intel programming module
+# on Cray systems this automatically sets `TBB_ROOT` environment variable
+module load intel
+module load cmake
+export CXX=`which CC`
+export CC=`which cc`
+
+# multithreading only
+cmake <path to CMakeLists.txt> -DWITH_TBB=ON -DSYSTEM_CRAY=ON
+
+# multithreading and MPI
+cmake <path to CMakeLists.txt> -DWITH_TBB=ON -DWITH_MPI=ON -DSYSTEM_CRAY=ON
+
+```