wiki:Installation

Installation of the ORAC source code

History

23-May-2011, Andy Smith
13-Dec-2011, Matthias Jerg
12-Jan-2012, Gareth Thomas
14-Jun-2012, Caroline Poulsen
08-Nov-2013, Adam Povey
25-Jul-2016, Adam Povey
26-Jul-2016, Greg McGarragh
16-Oct-2016, Caroline Poulsen
24-Mar-2017, Simon Proud


Prerequisites

A Fortran 2003 compiler is required. The ORAC code is developed and tested on GNU/Linux platforms using newer versions of gfortran (version 4.0 and greater), which is part of the free gcc package, and using the Intel ifort compiler (versions 8.1, 12.1, and 15.0). We expect that other compilers will work with minimal effort and the code is also known to compile and run on MacOS using gfortran.

The bison and flex tools are required, both of which are standard development tools available on GNU/Linux. Version 3 of bison is preferred. Version 2 will work, but you must comment line 17 and uncomment line 22 here.

Numerous libraries are required by the ORAC code. An example script to install them is attached to this page, but this should not be taken as definitive instructions for installation. The exact flags and patches required appear to be highly dependent on your machine architecture. If you are having difficulty, please email the ORAC Developer list (DEVORAC@…) for advice.

EMOS library

The ECMWF EMOS library is currently required but has proven to be difficult to install (recommendations for an alternative happily accepted). It can be found at  https://software.ecmwf.int/wiki/display/EMOS/Releases. You should download emos_000392.tar.gz, as later versions of the library have proven impossible to compile (or have changed the call syntax).

As is, this library conflicts with the HDF library as both contain a routine called init. This can be repaired with the following,

mv $PROG/gribex/handleLocalDefinitions.c $PROG/gribex/handleLocalDefinitions.c.in
cat $PROG/gribex/handleLocalDefinitions.c.in | sed 's/init\([E(,:]\)/initemos\1/' \
            > $PROG/gribex/handleLocalDefinitions.c
mv $PROG/gribex/handleLocalDefinitions.h $PROG/gribex/handleLocalDefinitions.h.in
cat $PROG/gribex/handleLocalDefinitions.h.in | sed 's/init;/initemos;/' \
            > $PROG/gribex/handleLocalDefinitions.h

The default configuration for ifort is incorrect. The LARGE_FILE flag should be set to -D_LARGEFILE64_SOURCE, -Vaxlib has been depreciated, the DEBUG flag should be set to -O2, and you may wish to use the icc compiler rather than gcc. (See the attached script.)

The default configuration for gfortran is partially incorrect. The FFLAGS variable should be set to -ffixed-line-length-0. (See the attached script.)

After that, the provided installation scripts (./build_library followed by ./install) should do the rest of the work. Warning: That script will build a library even if it doesn't compile all features. You need to search the output for "Error" to see if anything went wrong.

NetCDF

The NetCDF library is required to read/write input/output files. The code has been successfully compiled with NetCDF versions 3 and 4 although NetCDF 4 is recommended. The core NetCDF C library and API is required along with the NetCDF Fortran API which is shipped separately. They can be downloaded from the unidata website:  http://www.unidata.ucar.edu/downloads/netcdf/index.jsp

The library should be compiled from source with Fortran support enabled. If ORAC is to be run on a GNU/Linux machine, using the gfortran compiler, a pre-compiled version the NetCDF library can usually be installed directly using the distributions package manager. Both the NetCDF library and the associated development package, a.k.a "dev" package, should be installed.

The libraries can usually be found in /usr/lib, while the include files (e.g. netcdf.mod) are usually in /usr/include. Warning: The dev package may cause problems if you attempt to build a different version of NetCDF from source. In this case, NetCDF Fortran, HDF and ORAC must be compiled by pointing the compiler to the include directory of the preferred NetCDF source (usually the -I flag).

RTTOV

RTTOV is used to calculate the clear-sky transmittances and radiances and can be downloaded from  http://nwpsaf.eu/site/software/rttov/downloads. The current version of ORAC requires versions 12.0 or 12.1. We recommend installing version 12.1.

You will need to edit Makefile.local to point to your netCDF4 or HDF5 library directory. We recommend using HDF5 rather than netCDF4. The rttov_compile.sh script can be used to simplify compilation, we recommend compiling with OpenMP support (if appropriate to your architecture) as this enables a significant improvement in execution time.

You will also require the emissivity and BRDF atlases along with the RT coefficient files for any sensors you wish to process. At the time of writing, these could be found (at the same website) in:

  • uw_ir_emis_atlas_hdf5.tar
  • uw_ir_emis_atlas_covariances_hdf5.tar

The RT coefficient files for ORAC-supported sensors are included as part of the RTTOV distribution. Any future coefficient updates will be available from  https://nwpsaf.eu/site/software/rttov/download/coefficients/coefficient-download/

Other Dependencies

No issues have yet been encountered installing the following libraries with their default settings:

Optional Dependencies

The following libraries are optional, but recommended, in the current ORAC code:



Building the code

All parts of ORAC are compiled using Makefiles. This is controlled by two files:

  • The archfile, which sets the Fortran and C compilers to be used and the settings for those compilers. It is specified by the environment variable ORAC_ARCH.
  • The libfile, which lists the paths to all the libraries required by the compilers. It is specified by the environment variable ORAC_LIB.

Examples can be found in http://proj.badc.rl.ac.uk/orac/trunk/config.

The OBJS variable controls where the compiled object and module files are stored. We recommend setting OBJS=obj and, when checking out a fresh copy from the repository, execute the following,

mkdir common/obj
mkdir pre_processing/obj
mkdir src/obj
mkdir post_processing/obj
mkdir derived_products/broadband_fluxes/obj
mkdir derived_products/broadband_fluxes/obj/bugsrad
mkdir derived_products/broadband_fluxes/obj/fu_liou

You can also set OBJS to a full path and all object and module files will be stored in a single folder.

Calling make from the trunk folder should compile all of ORAC. A single part may be compiled by calling make from within it's folder, though all parts of ORAC are dependent on the contents of the trunk/common folder. To remove the compilation, call make clean. The command make depend is available to automatically generate file dependencies.

Note that ORAC responds very well to compiler optimisations, so if you are planing to do extensive processing with the code, you should consider using the appropriate flags (e.g. -O2 or -O3 will work wonders on most compilers). ORAC is parallelized using the OpenMP API for parralele execution on multiple cores and recommend turning this on with the appropriate compiler flag. The flags are -openmp on ifort and -fopenmp on gfortran.

The -cpp compiler flag is used to enable preprocessing via the C preprocessor. This flag may vary depending on your compiler and version.

Optional modes

A number of optional features are included within the ORAC code. These are implimented using C-preprocessor ifdef statements and can be activated by adding -D<> to the FFLAGS variable defined in your archfile, where <> is the desired macro.

  • DEBUG) Debug mode, which prints additional warning messages and text outputs.
  • BKP) Breakpoint mode, where details of most mathematical calculations are printed to stdout. While not depreciated, this feature is poorly maintained. In order to re-build with breakpoints you must re-compile the main program as well as the routine whose breakpoint outputs you require, otherwise the breakpoint file will not be opened and cleared at the start of execution. Note that breakpoint output from different routines within ORAC can be switched in and out by changing the breakpoint level set in ECPConstants.F90 or setting the breakpoint level in the driver file. Only run in the breakpoints configuration for a small number of pixels as the code runs slowly and produces substantial output.
  • WRAPPER) The default installation of ORAC creates three executables. Wrapper mode compiles these programs as subroutines that can be called from a single executable.
  • USE_TIMING) Prints details of how long each step of the main processor took to execute.
  • NEW_RTTOV) Compile RTTOV for versions after 11.2.
  • INCLUDE_SEVIRI_SUPPORT) Compile the SEVIRI module.
  • INCLUDE_HIMARAWI_SUPPORT) Compile the Himawari module.


Running the code

By default ORAC is compiled to use dynamic linking for HDF, HDF5, NetCDF and EPR-API and therefore the LD_LIBRARY_PATH must contain paths to these libraries. The following python one-liner may be of use (where $ORAC_PATH is the path to your ORAC repository):

LD_LIBRARY_PATH=$(cd $ORAC_PATH/trunk/tools; python -c "import os; import orac_utils as ou; print(ou.build_orac_library_path(ou.read_orac_libraries(os.environ['\''ORAC_LIB'\''])))")

The code expects all Static Application Data (SAD) files to be in place in the SAD directory (pointed to by the driver file). These are stored at http://proj.badc.rl.ac.uk/orac/sad_dir and include:

  • instrument channel characteristics, one file per instrument channel
  • cloud radiative properties for each supported cloud class in each instrument channel (Look Up Tables).

Attachments

  • INSTALL.sh Download (22.7 KB) - added by acpovey 17 months ago. Example installation script for the ORAC library dependencies