SANGOMA data assimilation tools (version 1.0)

This software package from the SANGOMA project provides several utilities that are used in connection with data assimilation problems. Tools have been adapted to follow a common data model.

List of functions

The software is organized in the following sub-directories:

• Fortran/ - Tools coded in Fortran
  • diagnostics/ functions to compute statistics to assess the performance of an assimilation system
    • sangoma_ComputeEnsStats.F90: Compute ensemble rank histograms
    • sangoma_ComputeHistogram.F90: Compute ensemble statistics
    • sangoma_ComputeMutInf.F90: Compute mutual information
    • sangoma_ComputeRE.F90: Compute relative entropy
    • sangoma_ComputeSensitivity.F90: Compute ensemble sensitivity
    • sangoma_ComputeSensitivity_op.F90: Compute ensemble sensitivity with observation operator given as a subroutine
    • sangoma_arm.F90: Calculate array modes and associated quantities
    • sangoma_computeBRIER.F90: Compute the Brier skill score and its decompostion, and the entropy
    • sangoma_computeCRPS.F90: Compute the CRPS and its decomposition
    • sangoma_computeRCRV.F90: Compute the CRPS and its de- composition (Source File: sangoma_computeCRPS.F90) Compute the bias and the dispersion of the RCRV
  • perturbations: methods to generate ensemble perturbations
    • sangoma_EOFCovar.F90: Initialize covariance matrix from EOF decomposition
    • sangoma_MVNormalize.F90: Perform multivariate normalization
    • mod_sangoma_pseudornd.F90: Generate correlated random field
  • transformations/
  • utilities/
    • sangoma_computepod.F90: Compute dominant POD modes from an ensemble of snapshots.
    • sangoma_costgrad.F90: Compute the values of Objective function and Gradient using reduced state dimensions.
• Matlab/ - Tools coded for Matlab and Octave
  • diagnostics/ functions to compute statistics to assess the performance of an assimilation system
    • mutual_information.m: Compute mutual information in a particle filter
    • relative_entropy.m: Compute relative entropy in a particle filter
    • sensitivity.m: Compute sensitivity of posterior mean to observations in a particle filter
  • perturbations: various methods to generate ensemble perturbations
    • WCE: Weakly constrained ensemble perturbations. Create ensemble perturbations that have to satisfy an a priori linear constraint
  • transformations:
    • Anam: Empirical Gaussian Anamorphosis. Determine the empirical transformation function such that a transformed variable follows a Gaussian distribution
  • utilities:
    • HFRadarExtract: Observation operator for HF radar surface currents

Requirements

• GNU make and a Fortran compiler (such as gfortran, ifort,...). Under Linux, make and gfortran can be installed by the package manager. For example under Debian/Ubuntu, gfortran and make are installed by:

  sudo apt-get install make gfortran libfftw3-dev

  For Red Hat/Fedora/Centos, these packages can be installed by:

  yum install make gcc-gfortran fftw-devel

  For Windows and Mac OS, pre-compiled binaries of gfortran are available at http://gcc.gnu.org/wiki/GFortran.
• LAPACK and BLAS. Reference versions of those libraries are available at http://www.netlib.org/lapack/ and http://www.netlib.org/blas/. An optimized version of BLAS should be preferred.
• FFTW for computing the Fast Fourier Transform available at http://www.fftw.org for the tool sangoma_pseudornd2D.
• GNU octave or MATLAB. GNU octave is an open-source clone of MATLAB available at http://www.gnu.org/software/octave/.
• Some tools use also the data assimilation framework OpenDA available at http://www.openda.org/. OpenDA is based on Java (version 1.6 or higher) available at http://www.java.com. Only the Java version from ORACLE is tested.

Installation instructions

Download the file http://sourceforge.net/projects/sangoma/files/sangoma-_VERSION_.tar.gz from the Sourceforge site and decompress it. The decompressed files will be in a folder named sangoma-_VERSION_

wget http://sourceforge.net/projects/sangoma/files/sangoma-_VERSION_.tar.gz
tar -xvzf sangoma-_VERSION_.tar.gz

Fortran tools

The Fortran tools can be compiled by issuing make in subdirectory Fortran/ of the sangoma-_VERSION_ directory:

$ make
gfortran -O3 -fdefault-real-8  -I/usr/include  -c sangoma_base.F90 -o sangoma_base.o
...
gfortran -O3 -fdefault-real-8  -I/usr/include  -c perturbations/mod_sangoma_pseudornd.F90 -o perturbations/mod_sangoma_pseudornd.o
ar -r  libsangoma_tools.a  diagnostics/sangoma_ComputeEnsStats.o diagnostics/sangoma_ComputeHistogram.o diagnostics/sangoma_ComputeMutInf.o diagnostics/sangoma_ComputeSensitivity.o diagnostics/sangoma_ComputeSensitivity_op.o diagnostics/sangoma_ComputeRE.o diagnostics/sangoma_computeCRPS.o diagnostics/sangoma_computeRCRV.o diagnostics/sangoma_computeBRIER.o diagnostics/sangoma_arm.o perturbations/sangoma_EOFCovar.o perturbations/sangoma_MVNormalize.o perturbations/mod_sangoma_pseudornd.o
ar: creating libsangoma_tools.a
ranlib  libsangoma_tools.a

This creates a library called libsangoma_tools.a and the module files mod_sangoma_pseudornd.mod and sangoma_base.mod (possibly in uppercase depending on the compiler). The sangoma tools can be used from a Fortran or C program. A Fortran program must be compiled by using the option -I (indicating the path to the module files) and the option -L (the path of the library) and the name of the library -lsangoma_tools. For example:

gfortran -I$HOME/src/sangoma/tools/trunk myprogram.f90 -L$HOME/src/sangoma/tools/trunk -lsangoma_tools

For a C program, only the options -L$HOME/src/sangoma/tools/trunk and -lsangoma_tools must be specified.

If a different Fortran compiler is used instead of gfortran, then the variables FC and FFLAGS in the Makefile need to be adapted.

MATLAB/GNU octave tools

The MATLAB/GNU octave tools in the sub-directories of the directory Matlab/ can be used by including the corresponding directory in your MATLAB/GNU octave search path by using the script sangoma_addpath for including all tools. Individual tools can be added by using:

addpath('/path/to/subfolder');

The tools WCE, Anam and HFRadarExtract include test scripts named wce_demo, anam_test and test_hfradar_extractf respectively that verifies the correct functioning of the packages.

Examples

Examples for the tools are provided in the subdirectory examples/ that is include in each category-directory. In case of theh Fortran codes, there is a Makefile in the directory that compiles all examples.

Documentation

Documentation of the tools is available at http://www.data-assimilation.net/Documents/sangomaDL2.4.pdf.

License

This software release includes code distributed under the terms of the GNU Lesser General Public License (version 3 or later) and the GNU General Public License (version 2 or later). The source code file contains a reference to the applicable license and the copyright holder.

Acknowledgment