TECA is designed to deliver the highest available performance on platforms ranging from Cray supercomputers to laptops. The installation procedure depends on the platform and desired use.
On a Cray Supercomputer¶
When installing TECA on a supercomputer one of the best options is the superbuild, a piece of CMake code that downloads and builds TECA and its now more than 26 dependencies. The superbuild is located in a git repository here TECA_superbuild.
Installing TECA on the Cray requires pointing the superbuild to Cray’s MPI and is sensitive to the modules loaded at compile time. You want a clean environment with only GNU compilers and CMake modules loaded. The GNU compilers are C++11 and Fortran 2008 standards compliant, while many other compilers are not. Additionally the HDF5 HL library needs to be built with thread safety enabled, which is rarely the case at the time of writing. Finally, some HPC centers have started to use Anaconda Python which can mix in incompatible builds of various libraries. The superbuild will take care of compiling and installing TECA and its dependencies. As occasionally occurs, something may go awry. If that happens it is best to start over from scratch. Starting over from scratch entails rm’ing contents of both build and install directories. This is because of CMake’s caching mechanism which will remember bad values and also because the superbuild makes use of what’s already been installed as it progresses and if you don’t clean it out you may end up referring to a broken library.
A quick overview follows. Note that step 8 is for using TECA after. This is usually put in an environment module.
- module swap PrgEnv-intel PrgEnv-gnu
- module load cmake/3.8.2
- git clone https://github.com/LBL-EESA/TECA_superbuild.git
- mkdir build && cd build
- edit install paths and potentially update library paths after NERSC upgrades OS in config-teca-sb.sh. (see below)
- run config-teca-sb.sh .. (you may need to replace .. with path to super build clone)
- make -j 32 install
- When using TECA you need to source teca_env.sh from the install’s bin dir, load the correct version of gnu programming environment, and ensure that no incompatible modules are loaded(Python, HDF5, NetCDF etc).
The configure script is a shell script that captures build settings specific to Cray environment (see steps 5 & 6 above). You will need to edit the TECA_VER and TECA_INSTALL variables before running it. Additional CMake arguments may be passed on the command line. You must pass the location of the superbuild sources(see step 3 above).
Here is the script config-teca-sb.sh use at NERSC for Cori and Edison.
# mpich is not in the pkg-config path on Cori/Edison
# I have reported this bug to NERSC. for now we
# must add it ourselves.
# set the the path where TECA is installed to.
# this must be a writable directory by the user
# who is doing the build, as install is progressive.
# Configure TECA superbuild
-DCMAKE_CXX_COMPILER=`which g++` \
-DCMAKE_C_COMPILER=`which gcc` \
On a laptop or desktop¶
On a laptop or desktop system one may use local package managers to install third-party dependencies, and then proceed with compiling and installing TECA. A simple procedure exists for those wishing to use TECA for Python scripting. See section A Python only install. For those wishing access to TECA libraries, command line applications, and Python scripting, compiling from sources is the best option. See section Compiling TECA from sources.
Note, that as with any install, post install the environment will likely need to be set to pick up the install. Specifically, PATH, LD_LIBRARY_PATH (or DYLD_LIBRRAY_PATH on Mac), and PYTHONPATH need to be set correctly. See section Post Install.
A Python only install¶
It is often convenient to install TECA locally for post processing results from runs made on a supercomputer. If one only desires access to the Python package, one may use pip. It is convenient, but not required, to do so in a virtual env.
Before attempting to install TECA, install dependencies as shown in section Installing dependencies
python3 -m venv py3k
pip3 install numpy matploptlib mpi4py teca
The install may take a few minutes as TECA compiles from sources. Errors are typically due to missing dependencies, from the corresponding message it should be obvious which dependency is missing.
Compiling TECA from sources¶
TECA depends on a number of third party libraries. Before attempting to compile TECA please install dependencies as described in section :ref;`install-deps`.
Once dependencies are installed, a typical install might proceed as follows.
git clone https://github.com/LBL-EESA/TECA.git
make -j8 install
At the end of this TECA will be installed. However, note that the install location should be added to the PYTHONPATH in order to use TECA’s Python features.
TECA was designed to be easy to install, as such when third party library dependencies are missing the build will continue with related features disabled. Carefully examine CMake output to verify that desired features are being compiled.
Apple Mac OS¶
brew tap Homebrew/homebrew-science
brew install gcc openmpi hdf5 netcdf python swig svn udunits
pip3 install numpy mpi4py matplotlib
$ apt-get update
$ apt-get install -y gcc g++ gfortran cmake swig \
libmpich-dev libhdf5-dev libnetcdf-dev \
libboost-program-options-dev python3-dev python3-pip \
libudunits2-0 libudunits2-dev zlib1g-dev libssl-dev
$ dnf update
$ dnf install -y gcc-c++ gcc-gfortran make cmake-3.11.0-1.fc28 \
swig mpich-devel hdf5-devel netcdf-devel boost-devel \
python3-devel python3-pip udunits2-devel zlib-devel openssl-devel
Some of these packages may need an environment module loaded, for instance
$ module load mpi
When installing after compiling from sources the user’s environment should be updated to use the install. One may use the following shell script as a template for this purpose by replacing @CMAKE_INSTALL_PREFIX@ and @PYTHON_VERSION@ with the value used during the install.
# for server install without graphics capability
With this shell script in hand one configures the environment for use by sourcing it.