
CGRIBEX library
===============

     This directory contains the source code for the GRIB1 library from the
     Max-Planck-Institute for Meteorology.
     The interface is similar to GRIBEX from the EMOS library.

     GRIBEX is an interface for encoding and decoding WMO FM-92 GRIB edition 1
     messages and some ancillary subroutines for controlling printing and debugging.
     The GRIBEX software was developed at the European Centre for Medium-range
     Weather Forecasts (ECMWF) and is part of the EMOS library.
     EMOS is mostly written in Fortran. Therefore it has only a Fortran interface.

     CGRIBEX is lightweight version of GRIBEX written in ANSI C with a portable
     Fortran interface. For best compatibility some of the C sources were converted 
     from the Fortran GRIBEX version.

     See the AUTHORS file for the list of authors.

     CGRIBEX is licensed under the 3-clause BSD License. This License covers all files in the CGRIBEX
     repository unless stated otherwise. Read the file LICENSE in the source distribution for details.

Documentation
-------------

     A description of the gribex and pbio interface can be found in:

        http://www.ecmwf.int/publications/manuals/libraries/gribex
        http://www.ecmwf.int/publications/manuals/libraries/pbio

Notes
-----

     CGRIBEX is not a full implementation of the EMOS GRIBEX version.
     Limitation of this library:
       
       Supported coding option HOPER:  'C', 'D', 'J' and 'R'.

       Supported grids:
         - regular and quasi-regular (reduced) latitude/longitude grids
         - regular and quasi-regular (reduced) gaussian grids
         - spherical harmonic fields
         - triangular grids

     Implemented functions:

     +----------+-------------------+------------------------------------------------+
     | Fortran  | C interface       | Description                                    |
     +----------+-------------------+------------------------------------------------+
     | GRIBEX   | gribExDP          | Encode/Decode GRIB record                      |
     | GRPRS0   | gribPrintSec0     | Print section 0 (IS)                           |
     | GRPRS1   | gribPrintSec1     | Print section 1 (PDS)                          |
     | GRPRS2   | gribPrintSec2DP   | Print section 2 (GDS)                          |
     | GRPRS3   | gribPrintSec3DP   | Print section 3 (BMS)                          |
     | GRPRS4   | gribPrintSec4DP   | Print section 4 (BDS)                          |
     | GRPRS4W  | gribPrintSec4Wave | Print the wave coordinate information          |
     | GRSDBG   | gribSetDebug      | Set debug printing                             |
     | GRSRND   | gribSetRound      | Set rounding                                   |
     | GRSREF   | gribSetRefDP      | Set reference value                            |
     +----------+-------------------+------------------------------------------------+
     | PBOPEN   | gribOpen          | Open a GRIB file                               |
     | PBCLOSE  | gribClose         | Close a GRIB file                              |
     | PBREAD   | gribRead          | Read a block of bytes                          |
     | PBWRITE  | gribWrite         | Write a block of bytes                         |
     | PBSEEK   |                   | Seeks to a specified location                  |
     | PBTELL   | gribGetPos        | Tells current byte offset                      |
     | PBFLUSH  |                   | Flushes file                                   |
     | PBSIZE   | gribGetSize       | Size in bytes of the next GRIB product         |
     | PBGRIB   |                   | Read next GRIB product                         |
     +----------+-------------------+------------------------------------------------+


Building the library
--------------------

     Read INSTALL on how to configure, compile and install the library.
     The configuration script has some more environment variables.
     Type 'configure -h' to see them.

     The default floating point precision for the Fortran interface ist REAL*8.
     Configure with --enable-REAL4 for a single precision Fortran interface.

Porting
-------

     The library was designed for maximum portability. It is written entirely
     in ANSI C99, and will compile on most UNIX platforms.

     The FORTRAN 77 interface is using the cfortran.h macros from
     http://www-zeus.desy.de/~burow/cfortran/
     
Contact
-------

     Send questions, comments and bug reports to <https://code.mpimet.mpg.de/projects/cgribex>

Optimization
------------

The package can be build by using the autotools

./configure
make 
make install

Examples for different architectures on howto set the environment
for configure can be found in config/default.

To test and measure the encoding algorithm an example program is
provided in examples/grib_encode.c.

The file containing the kernels to optimize can be found in
src/gribEncode.c.  This one includes to other once, which we
found to be the final hotspots. The first one is the calculation
of the min and max value concurrently: our first attempts can be
found in:

#include "minmax_val.c"

The second kernel is the encoding itself and is provided in

#include "encode_double_array.c"

The test case example/grib_encode.c does contain a line

#define  NBITS  16 // Number of bits

which refers to the 16 bit packing scheme. Changing this to
either 8, 24, or 32 triggers the 3 other kernels. In real
applications the 16 and 24 bit test cases are the most used once.

