Building Sasktran V3 libraries on Linux systems

Body: 

LATEST CHANGES, July 2016:

Our SVN repositories links are in the process of being replaced with Git repositories. Please bear with us while we punch through this process

Building SasktranIF on Linux (amd64). Last Updated 2015-11-13

Here are the instructions on how to build the SasktranIF code for python3 on a Linux system.   This guide outlines the software installation on a clean Linux system. We currently recommend that SasktranIF  only be used on a 64 bit platform (32 bit compilations "should" work but has not been tested).  All of the steps have been executed on a clean Linux system  running Ubuntu 14.04 LTS  using a regular user who must use sudo and a password to elevate privilege. 

Directory Organization

The build system uses 3 primary disk locations for which you have some control in selecting the appropriate locations:

  1. SOFTWAREDIR: The C++ software directory structure. This directory is only used during the build process. A regular user directory can be used for this purpose < 1GB.  An example directory is $HOME/OMPS/software 
  2. INSTALLDIR: The executable binary code and configuration information. This is a read-only directory structure used to hold the binary executable code and can be shared with multiple users < 100  MB. A simple example is $HOME/OMPS/binary
  3. CACHEDIR: A read-write directory used to  hold intermediate cached files. All users must have read/write access. Typically needs ~ 10-100 GB.. A simple example is $HOME/OMPS/Cache

System Software Tools: pre-requisistes

The Linux system should have the following software installed (note that swig has been dropped from the list of requirements),

  1. gcc, C  compiler
  2. g++, C++ compiler
  3. gfortran, fortran compiler
  4. Anaconda Scientific Python for python 3.4, Linux 64 bit (Make sure you get version 3!). We currently install it into the users local home folder. Make sure the Anaconda version of python runs when you enter the command python3
  5. Subversion (SVN). You need this to check out our software from our server.
  6. yacc and lex if you plan to build the HDF and netcdf libraries
  7. Boost C++ libraries, see www.boost.org.  Version 1.52 or higher is required. On Ubuntu 14.04 you can use sudo apt-get install libboost-all-dev.

Environment Variables

You will have to edit your environment variables after the build. Of particular importance are INCLUDE, LIBRARY_PATH and LD_LIBRARY_PATH.  Environment variable INCLUDE is a colon separated list of relevant C/C++ header directories, LIBRARY_PATH  is a colon separated list of relevant library (lib*.a) directories and LD_LIBRARY_PATH is a colon separated list of relevant shareable object (*.so)  directories. You may need to edit INCLUDE and LIBRARY_PATH before starting the build if you manually installed Boost. See the boost documentation for more details.  We installed Boost using the package manager on our system and did not need to edit any environment variables (it just worked). On our Ubuntu system we edit environment variables in file .bashrc in the $HOME directory but .profile, .bash_profile  are other choices.  On other systems it may be called something else. Note that you can either log out and log in to reload the environment variables or you can use something like  source .bashrc 

Python Wheels

The installation creates a python wheel for the sasktranif software and uses pip, the package installer for python, to install the sasktran software into your version of python3. You need to make sure your system can install Python Wheels. Please do the following

  1. $pip -V                    Ensure the version of pip is appropriate for the  target version of  python3. This may be a problem if you have multiple versions of python installed on your system.  You may have to play with your path environment variable 
  2. $pip install --upgrade pip Upgrade pip to the latest version. We use pip 7.1.2
  3. $pip install wheel         Use pip to Install the wheel installation software into python.

Stage 1: Download Software from the Repository

Body: 

Stage 1:

Create a directory (SOFTWAREDIR or whatever you want)  to hold the software that you will download from our subversion server. From the base directory create the software directory to store the downloads. 

cd SOFTWAREDIR
 

Download the required repositories from the University of Saskatchewan SVN server. You can use the (low security) username odin-osiris\odin and password hugin

svn co https://odin-osiris.usask.ca/svn/Repos_HDF/trunk Repos_HDF
svn co https://odin-osiris.usask.ca/svn/Repos_netcdf4/trunk Repos_netcdf-4.4.0
svn co https://odin-osiris.usask.ca/svn/Repos_3rdParty/trunk Repos_3rdParty
svn co https://odin-osiris.usask.ca/svn/Repos_SasktranV3LinuxBuild/trunk Repos_SasktranV3LinuxBuild

You are now ready for the next stage

 

Stage 2: Build HDF and Netcdf

Body: 

This section will build HDF4, HDF5, hdfeos, hdfeos, netcdf and a few supporting libraries, The code is built with position independent code settings (-fPIC) so the libraries can be used in a shared environment (i.e. shareable objects) . You can skip this section if your site already has these libraries installed. Otherwise, go to the software directory (SOFTWAREDIR ) created in stage 1.

cd SOFWTAREDIR/Repos_SasktranV3LinuxBuild
chmod u+x buildhdfnetcdf
./buildhdfnetcdf INSTALLDIR

edit your environment variables, INCLUDE, LD_LIBRARY_PATH and LIBRARY_PATH  in your login scripts (.bashrc) and apply the settings.

 

Stage 3. Build the BLAS and LAPACK libraries

Body: 

This section will build the BLAS and LAPACk libraries. The code is built with position independent code settings (-fPIC) so the libraries can be used in a shared environment (i.e. shareable objects) . You can skip this section if your site already has these libraries installed. Otherwise, go to the software directory (SOFTWAREDIR ) created in stage 1.

cd SOFTWAREDIR/Repos_SasktranV3LinuxBuild
chmod u+x buildblaslapack
./buildblaslapack INSTALLDIR

edit your environment variables, INCLUDE, LD_LIBRARY_PATH and LIBRARY_PATH  in your login scripts (.bashrc) and apply the settings.

 

Stage 4: Build the University Of Saskatchewan SasktranIF python library

Body: 

Build the University of Saskatchewan SasktranIF code

The SasktranIF code can only be built once the HDF, netcdf , blas and lapack code described in previous sections are built and properly installed on your system, including updating the appropriate environment variables in your login scrips and applying them to your environment (e.g. log-out then log-in). The build o fthe sasktranIF code will use a binary installation directory INSTALLDIR which is normally the same as the installation directory used for previous stages. It will also use an optional CACHEDIR where the saktranif will write cache information duuring its execution.  The CACHEDIR can be left out and a default value of INSTALLDIR/Cache will be used.

cd SOFTWAREDIR/Repos_SasktranV3LinuxBuild
chmod u+x buildsasktranif
./buildsasktranif INSTALLDIR CACHEDIR 

 

Ensure that the script executed successfully by looking for a small text box at the end of the execution looing like
 
**********************************************************
*     SasktranIF Installation Complete
*     --------------------------------
 
Read the box, update the displayed environment variables in your login script and apply. Congratulations, you are now ready to to use the python sasktranif module within python3.