This directory contains all the material related to the 'bglib_sh' library. This library contains routines used to solve variational minimization problems (3D- and 4D-var) in the spectral representation considering homogeneous and isotropic horizontal correlations of the background error covariance matrix. See Errera and Menard (see full reference below) for further details.

Contents
--------
1. Description of the package
2. Compilation
   a. Requirements
   b. Building executable
3. Running
4. Outputs
5. Documentations
6. Version
7. Citation
8. License
9. Contact

================================================================================

1. Description of the package
-----------------------------

 LICENSE      copyright notice (GPL license),
 README       this file,
 bin          an empty directory, in which the binaries generated
              during compilations will be stored,
 include      directory where the modules will be stored during compile process,
 input        provides the input data,
 output       provides the output data,
 src          provides the source code.

================================================================================

2. Compilation
--------------

2.a Requirements
----------------

Bglib_sh requires a few libraries: lapack and [eventually] shtools and fftw3.

The shtools library is used for the functions it provides for calculating the associated Legendre function and polynomials, and the Gaussian latitudes and weights. The makefile allows you to use precomputed values (see below), avoiding the need of shtools for test purposes but this has some limitations (see 3).

To tell the makefile the right locations of files to be included for fortran modules, please change variables INC_SHTOOLS and INC_LAPACK accordingly.

To tell the makefile the right locations of the shtools and lapack library and the right name for that library, please change variables LIB_SHTOOLS and LIB_LAPACK accordingly.

It is also good to note that the Intel Compilers provide a lapack implementation through the MKL. The fftw3 library is also provided but you might need to ask to your system administrator to build them for you.


2.b Building executable
-----------------------

The bglib_sh library and the associated tests have been coded in Fortran 90/95. 
Use the Makefile to perform the compilation. Several calling options are possible:

> make

create test_bglib with gfortran compiler and using SHTOOLS and LAPACK libraries.

> make FC=ifort

create test_bglib with ifort compiler.

> make PRECOMP=1

Create test_bglib with gfortran. In this case, the associated Legendre function and polynomials, Gaussian weigth, and the square root of the vertical correlation matrix are provided by input files (see input directory). This has some limitation, see 3.

Of course, both options can be combined, i.e.

> make FC=ifort PRECOMP=1

This Makefile has not been tested with other compilers than ifort and gfortran.

================================================================================

3. Running
----------

To run the code, go to bin/ and type

    > ./test_bglib [Lh] [hcorr_model] [Lv] [vcorr_model] [spectral_grid]
    
where:
- Lh            The horizontal correlation length scale, in [km]
- hcorr_model   The horizontal correlation model. Can be:
                    'soar' for second order auto-regressive
                    'gauss' for Gaussian
- Lv            The vertical correlation length scale (no units)
- vcorr_model   The vertical correlation model. Can be:
                    'identity' for uncorrelated model
                    'gauss_lev' for Gaussian correlation where Lv is in
                        level unit
- spectral_grid Type of the spectral grid:
                    'll' for equally spaced lat/lon grid
                    'gg' for non-equally spaced Gaussian grid
Example:
> ./test_bglib 600 gauss 3 gauss_lev ll


If compiled using PRECOMP=1, the program runs with several limitations:
- the resolution (nlat) must be set to 60 in var_def.mod.f90.
- the vertical correlation length scale must be '3' and the vertical correlation model must be 'gauss_lev'.
                        
================================================================================

4. Outputs
----------

The following outputs are created in the 'output' dir:
- cost_[spectral_grid].dat containing the values of the cost functions (J), the cost function due to the observations (Jo) and the background (Jb), the norm of the gradient of the cost (gnorm), and the value of the model at the observation location (H(x))
- vmr_[spectral_grid].dat containing the value of the analyses
- SPX_[spectral_grid].dat containing the power spectra of the analysis increments.

================================================================================

5. Documentations
-----------------

Additional documention can be found in:
Errera and Menard, Technical Note: Spectral representation of spatial correlations in variational assimilation with grid point models and application to the Belgian Assimilation System for Chemical ObsErvations (BASCOE), submitted to ACPD.

================================================================================

6. Version
----------

This is the first release of bglib_sh, version 01.01, subversion 
revision 1903.

================================================================================

7. Citations
------------

Any work using completely or partly the code provided in the bglib_sh.f90 library must cite: 

Errera and Menard, ...

Note that m1qn3.f90 is protected by another GNU Public Licence. For further information about the terms and use of m1qn3, visit:
http://www-roc.inria.fr/~gilbert/modulopt/optimization-routines/m1qn3/m1qn3.html

================================================================================

8. License
----------

As mentionned previously, the LICENSE files contains the license type for this 
code. As m1qn3 is provided under the GPL license, so it is the case for bglib_sh.

================================================================================

9. Contact
----------
Quentin Errera
Belgian Institute for Space Aeronomy (BIRA-IASB)
3 av. circulaire
B-1180 Bruxelles
Belgium
e-mail: quentin@oma.be


