====== Installation ======

===== Pre-built Packages =====

If you are lucky to run one of the following operating systems, you can install fimex from a package repository, please check the [[fimex:download|download]] page.

===== Dependencies =====

Fimex requires at least the following libraries to be installed for compilation:
  * c99/c++11 compiler
  * [[http://www.xmlsoft.org|libxml2]] >= 2.5.0
  * [[http://proj.maptools.org|proj-4]] >= 4.4.9
  * [[http://www.unidata.ucar.edu/packages/udunits/|udunits]] >= 2.1.x
  * [[https://github.com/metno/mi-cpptest|mi-cpptest]]
  * [[https://github.com/metno/mi-programoptions|mi-programoptions]]
  * [[https://github.com/pybind/pybind11|pybind11]]
	
To configure the different file formats or features it requires:
  * [[http://www.unidata.ucar.edu/software/netcdf/|NetCDF]] (netcdf-3 > 3.6)
  * [[https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home|ecCodes]]
  * [[http://log4cpp.sourceforge.net/|Log4cpp]]: advanced logging library
  * [[http://www.openmp.org/|OpenMP-3.0]] enable compiler: Parallelization
  * [[http://en.wikibooks.org/wiki/Fortran_2003|Fortran-2003]] compiler (tested with gfortran-4.6 and ifortran-12)

===== Build =====

See [[https://github.com/metno/fimex/blob/master/README.md|README.md]] for build instructions.

==== Optimizations with gcc ====

The following optimizations have been tried with gcc 4.4 and kd-tree interpolation.

  * **-O2** general optimizations like loop-unrolling/inline 
  * **-mfpmath=sse -msse2** on i386 computers, use math from sse-unit. The build-in FPU is not IEEE conform and performs very slowly (> factor 2) when calculating sqrt(nan). This is already the default on i386-64.
  * //-ftree-vectorize -fno-math-errno// gives tiny performance gain through auto-vecotrization. //-fno-math-errno// is required to enable vectorization of intrinsic functions like //sqrt//.
  * //-fno-trapping-math -fno-signaling-nans// fimex does not make use of trapping-math or signaling-nans, so this option can safely be switched on. Unfortunately, this does not give any performance gain.
  * //-O3// gives no visible performance gain. This should be tested again with newer compiler-versions.
  * //-fprofile-generate/-fprofile-use// gives a performance gain of ~4%. Since it complicates the build, it is not used by default.

==== Parallelization (OpenMP) ====

Fimex can be build with OpenMP parallelization support with the //configure// option //--enable-openmp//. The following operations are parallelized:

  * interpolation: fill2d (good parallelization on z-axis)
  * interpolation with coord_nearestneighbor (good parallelization in startup)

===== Test =====

  * Download the file with testdata: {{:fimex:flth00.dat.gz|}}
  * Put this file into the test-catalogue
  * gunzip the file
  * run ''make test'' (it will work even without the testdata and skip a lot of tests)

===== Known Problems =====

==== udunits1 and FMRC ====

udunits1 does not differ between a date and a timespan, e.g. 
<code>
$ ./udunits
You have: hours
You want: hours since 2010-01-01 00:00:00
    <hours since 2010-01-01 00:00:00> = <hours>*1 - 78888
    <hours since 2010-01-01 00:00:00> = <hours>/1 - 78888
</code>

Therefore, data with two time-axis, e.g. in [[http://www.unidata.ucar.edu/software/netcdf/ncml/v2.2/FmrcAggregation.html|ForecastModelRuntimeConvention]] cannot get read proberly. This results in a
test-failure:
<code>
unknown location:0: fatal error in "test_cs_slicebuilder_reftime": unknown type
testCoordinateSystemSliceBuilder.cc:69: last checkpoint

*** 1 failure detected in test suite "Master Test Suite"
FAIL: testCoordinateSystemSliceBuilder
</code>

If you don't intend to use FMRC, you can ignore this error, otherwise, you should upgrade to udunits2.


==== udunits1 and udunits2 ====

If both udunits1 and udunits2 are available on the machine, fimex might prefer udunits1 unless explicitly disabled. To explicitly disable udunits1, use:
<code>
./configure --without-udunits --with-udunits2 ...
</code>

==== MacOS X and gcc ====

Under MacOS X strings may come in different flavour for gcc, either static or fully dynamic. Libraries compiled with one type of strings don't work well with programs/libraries compiled with the other type. This might result in an segmentation fault when running ''fimex'' with the message:
<code>
 pointer being freed not allocated
</code>

boost::program_options is affected by this and must be compiled with the same compiler as fimex is compiled, e.g.
  * download boost
  * add ''using darwin : : g++-mp-4.6 ;'' in ''user-config.jam''
  * run <code>
./bootstrap.sh --prefix=/usr/local
./b2 install
</code>
For more information, see http://lists.boost.org/boost-users/2010/06/59548.php


==== AIX ====

The boost libraries (1.44) are not compatible with the AIX XL/C++ compiler V10 and we had to compile boost and fimex with gcc to get it working under AIX. This might have been improved with newer versions of the AIX compiler, but hasn't been tested: http://www-01.ibm.com/support/docview.wss?uid=swg27018656