Introduction

GRIB API 

Enrico Fucile 

Data & Services Section 

Slide 1 

COM GRIB API, ECMWF 13-14 Feb. 2008 

Slide 1

Overview 

•GRIB 1 vs. 2 

•GRIBEX vs. GRIB API 

•Available interfaces 

•Plans 

Slide 2 


Slide 2

GRIB 1 vs. 2 

GRIB (GRIdded Binary) is a binary format to exchange and store 

general regularly-distributed information. 

Slide 3 


Slide 3

GRIB 1 vs. 2 

• Two different versions of the coding standard are available at 

the moment (edition 1 and 2). 

• The coding principles in both editions are similar, but their 

implementation is very different. 

Slide 4 


Slide 4

GRIB 1 vs. 2 

• Different structure. They both have sections (with different 

meaning). 

• GRIB 2 is more flexible because of its template/tables structure. 

• In GRIB 2 several variables are defined with more precision (e.g. 

angles are in micro-degrees) 

• In GRIB 2 the description of the data (parameter, time, 

statistics,…) is more complex and is template/table based (prone 

to became even more complex) 

Slide 5 


Slide 5

GRIB 1 vs. 2: Different Structure 

GRIB 1 

SECTION 0 Indicator 

SECTION 1 Product definition 

SECTION 2 Grid Description 

SECTION 3 Bitmap 

SECTION 4 Binary Data 

SECTION 5 End (7777) 

repeat 

Slide 6 

GRIB 2 

SECTION 0 Indicator 

SECTION 1 Identification 

SECTION 2 Local Use 

SECTION 3 Grid Definition 

SECTION 4 Product Definition 

SECTION 5 Data Representation 

SECTION 6 Bitmap 

SECTION 7 Binary Data 

SECTION 8 End (7777) 


Slide 6

GRIB 1 vs. 2: GRIB 2 Templates 

====================== SECTION 3 ( length=200, padding=0 ) ====================== 

1-4 section3Length = 200 

5 numberOfSection = 3 

6 sourceOfGridDefinition = 0 [Specified in Code table 3.1 ] 

7-10 numberOfDataPoints = 6114 

11 numberOfOctetsForOptionalListOfNumbersDefiningNumberOfPoints = 2 

12 interpretationOfListOfNumbersDefiningNumberOfPoints = 1 [Numbers 

13-14 

define number of points corresponding to full coordinate circles ] 

gridDefinitionTemplateNumber = 40 [Gaussian latitude/longitude] 

15 shapeOfTheEarth = 0 [Earth assumed spherical with radius=6,367,470 m] 

16 scaleFactorOfRadiusOfSphericalEarth = MISSING 

17-20 scaledValueOfRadiusOfSphericalEarth = MISSING 

21 scaleFactorOfMajorAxisOfOblateSpheroidEarth = MISSING 

22-25 scaledValueOfMajorAxisOfOblateSpheroidEarth = MISSING 

26 scaleFactorOfMinorAxisOfOblateSpheroidEarth = MISSING 

27-30 scaledValueOfMinorAxisOfOblateSpheroidEarth = MISSING 

31-34 numberOfPointsAlongAParallel = MISSING 

35-38 numberOfPointsAlongAMeridian = 64 

39-42 basicAngleOfTheInitialProductionDomain = 0 

43-46 subdivisionsOfBasicAngle = MISSING 

47-50 latitudeOfFirstGridPoint = 87864000 

51-54 longitudeOfFirstGridPoint = 0 

55 resolutionAndComponentFlags = 0 

56-59 latitudeOfLastGridPoint = -87864000 

60-63 longitudeOfLastGridPoint = 357188000 

64-67 iDirectionIncrement = MISSING 

68-71 numberOfParallelsBetweenAPoleAndTheEquator = 32 

72 scanningMode = 0 

73-200 pl = (64,128) {2.0000000000e+01, 2.7000000000e+01, Slide 7 ...} 

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


Slide 7

GRIB 1 vs. 2: GRIB 2 Templates 

====================== SECTION_4 ( length=770, padding=0 ) ====================== 

1-4 section4Length = 770 

5 numberOfSection = 4 

6-7 numberOfVerticalCoordinateValues = 184 

8-9 productDefinitionTemplateNumber = 0 

[Analysis or forecast at a horizontal 

level or in a horizontal layer at a point in time] 

10 parameterCategory = 0 [Temperature (grib2/4.1.0.table) ] 

11 parameterNumber = 0 [Temperature (K) (grib2/4.2.0.0.table) ] 

12 typeOfGeneratingProcess = 0 [Analysis (grib2/4.3.table) ] 

13 backgroundGeneratingProcessIdentifier = 255 

14 generatingProcessIdentifier = 130 

15-16 hoursAfterReferenceTimeOfDataCutoff = 0 

17 minutesAfterReferenceTimeOfDataCutoff = 0 

18 indicatorOfUnitOfTimeRange = 1 [Hour (grib2/4.4.table) ] 

19-22 forecastTime = 0 

23 typeOfFirstFixedSurface = 100 [Isobaric surface (Pa) (grib2/4.5.table) ] 

24 scaleFactorOfFirstFixedSurface = 0 

25-28 scaledValueOfFirstFixedSurface = 0 

29 typeOfSecondFixedSurface = 255 [Missing (grib2/4.5.table) ] 

30 scaleFactorOfSecondFixedSurface = MISSING 

31-34 scaledValueOfSecondFixedSurface = MISSING 

35-770 pv = (184,736) {0.0000000000e+00, 2.0000400543e+00,...} 

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

Slide 8 


Slide 8

GRIB 1 vs. 2: different units 

GRIB 1 

• LatitudeOfFirstGridPoint is 

in milli-degrees 

GRIB 2 

• LatitudeOfFirstGridPoint is 

in micro-degrees 

or in an arbitrary unit 

defined by the fraction of 

two parameters: 

basicAngleOfTheInitialProductionDomain/ 

subdivisionsOfBasicAngle 

Slide 9 


Slide 9

GRIB 1 vs. 2 

HOW TOGRIB SQUARE API VIEW THE CIRCLE 

GRIB 1 

GRIB 

GRIB 2 

Slide 10 


Slide 10

GRIB 1 vs. 2 

GRIB API VIEW 

GRIB 21 

Slide 11 


Slide 11

GRIBEX vs. GRIB API 

•GRIBEX provides an array based access to the GRIB 

message. 

- ksec2(2) => Number of points along a parallel 

- Ksec2(3) => Number of points along a meridian 

- … 

•GRIB API provides a key/value based approach 

- NumberOfPointsAlongAParallel => Number of points along a 

parallel 

- NumberOfPointsAlongAMeridan => Number of points along a 

meridian 

- … 

Slide 13 


Slide 13

GRIB API - Design 

Client Software 

(C/C++, FORTRAN, Perl …) 

set and get 

key / values 

Command line tools 

GRIB 1 

GRIB_API 

Definition 

Files 

Definition files are external text files 

describing the decoding rules. 

Slide 14 

New decoding rules can be added 

without rebuilding the grib_api 

GRIB 2 


Slide 14

GRIB 1 vs. 2 

COMPUTED 

latitudeOfFirstGridPointInDegrees=40 

CODED 

latitudeOfFirstGridPoint=40000 

CODED 

latitudeOfFirstGridPoint=40000000 

Slide 15 


Slide 15

GRIB 1 vs. 2 

COMPUTED 

gridType=reduced_gg 

CODED 

CODED 

dataRepresentationType=4 

numberOfPointAlongAParallel=MISSING 

ijDirectionIncrementGiven=0 

pl ={…} 

gridDefinitionTemplateNumber=40 

numberOfPointsAlongAParallel=MISSING 

iDirectionIncrementGiven=0 

iDirectionIncrement=MISSING 

Slide 16 

pl={…} 


Slide 16

GRIB 1 vs. 2 

numberOfPoints 

numberOfValues 

numberOfMissingValues 

 

 

Slide 17 


Slide 17

GRIB API: available interfaces 

•C native interface exposes all the functionalities in an 

object oriented style. 

•Fortran 77 is maintained for compatibility reasons with 

the gribex software. 

•Fortran 90 is the Fortran suggested interface and 

provides an easy access to the main functionalities of 

the library. 

•GRIB tools provide a command line interface of the API 

•Perl is still under development and will be tested and 

verified in the next releases. 

•All the interfaces provide a way to set/get the same set of 

Slide 18 

keys. 


Slide 18

GRIB API: available interfaces ( C ) 

grib_handle* h=NULL; 

double latitudeOfFirstGridPointInDegrees; 

char* date=“20080212”; 

long centre; 

grib_context* context=grib_context_get_default(); 

in = fopen(filename,"r"); 

h = grib_handle_new_from_file(context,in,&err); 

grib_get_double(h,"latitudeOfFirstGridPointInDegrees", 

&latitudeOfFirstGridPointInDegrees); 

grib_set_long(h,"centre",centre); 

grib_set_string(h,“date",date,&len); 

Slide 19 

grib_handle_delete(h); 


Slide 19

GRIB API: available interfaces (Fortran 90) 

integer :: ifile, igrib, iret, centre 

real(8) :: latitudeOfFirstPointInDegrees 

call grib_open_file(ifile,'regular_latlon_surface.grib1','r') 

call grib_new_from_file(ifile,igrib,iret) 

call grib_get(igrib,'latitudeOfFirstGridPointInDegrees', 

& 

latitudeOfFirstPointInDegrees) 

call grib_set(igrib,'centre',centre) 

call grib_set(igrib, ‘date',’20070212’) 

call grib_release(igrib) 

call grib_close_file(infile) 

Slide 20 


Slide 20

GRIB API: available interfaces (tools) 

grib_get –p latitudeOfFirstGridPointInDegrees regular_latlon_surface.grib1 

grib_set –s centre=ecmf,date=20070212 regular_latlon_surface.grib1 out.grib1 

Slide 21 


Slide 21

GRIB API: available interfaces (tools) 

•grib_ls, grib_get (quick listing of the content of a file) 

•grib_dump (detailed views of the grib messages) 

•grib_get_data (latitude/longitude/value list ) 

•grib_set, grib_convert (to change header values) 

•grib_copy (to copy selected messages) 

•grib_filter (to set and write to different files) 

•grib_compare (to compare two grib files) 

•grib_keys (to get a list of available keys) 

Slide 22 


Slide 22

GRIB Tools: 

options 

A set of options common to all the tools is provided. 

• -p key[:{s/d/l}],key[:{s/d/l}],... 

Declaration of keys to print. For each key a string 

(key:s) or a float (key:d) or a integer (key:l) value is 

printed. Default type is string. 

• -w key[:{s/d/l}]{=/!=}value,key[:{s/d/l}]{=/!=}value,... 

Where clause. Grib messages are processed only if 

they match all the key/value constraints. A valid 

constraint is of type key=value or key!=value. For 

each key a string (key:s) or a double (key:d) or a long 

Slide 23 

(key:l) type can be specified. Default type is string. 


Slide 23

GRIB Tools: 

options 

grib_ls –w levelType=sfc sample.grib 

grib_copy –w levelType=sfc sample.grib sfc.grib 

grib_set –w levelType=sfc –s packingType=jpeg 

sample.grib2 sfc_jpeg.grib2 

Slide 24 


Slide 24

GRIB Tools: 

options 

grib_ls –B”step,param desc,levelType”x.grib 

grib_copy –B”step,param desc,levelType”x.grib order.grib 

Slide 25 


Slide 25

GRIB TOOLS: grib_ls 

grib_ls –p step,short_name –l40/11 reduced_gg.grib 

step shortName value1 value2 value3 value4 

0 2T 291.57 291.88 291.92 291.61 

0 TP 0.00 0.00 0.00 0.00 

12 2T 292.19 292.08 292.21 291.69 

12 TP 0.00 0.00 -0.00 -0.00 

Input Point: latitude=40.00 longitude=11.00 

Grid Points 

- 1 - index=39302 latitude=39.78 longitude=11.25 distance=32.86 (Km) 


- 3 - index=38662 latitude=40.22 longitude=11.25 Slide 26 distance=32.80 (Km) 



Slide 26


grib_ls –p step,short_name –Bparam,step –l40/11 reduced_gg.grib 

step shortName value1 value2 value3 value4 

0 2T 291.57 291.88 291.92 291.61 

12 2T 292.19 292.08 292.21 291.69 

0 TP 0.00 0.00 0.00 0.00 

12 TP 0.00 0.00 -0.00 -0.00 


Grid Points 



- 3 - index=38662 latitude=40.22 longitude=11.25 Slide 27 distance=32.80 (Km) 



Slide 27


grib_ls –p step,shortName –Bparam,step –l40/11/1 reduced_gg.grib 

step shortName value 

0 2T 291.92 

12 2T 292.21 

0 TP 0.00 

12 TP -0.00 


Grid Point index=38662 latitude=40.22 longitude=11.25 distance=32.80 

(Km) 

Slide 28 


Slide 28


grib_ls –p step,shortName –Bparam,step -i 38662 reduced_gg.grib 

step shortName value(38662) 

0 2T 291.92 

12 2T 292.21 

0 TP 0.00 

12 TP -0.00 

Slide 29 


Slide 29

GRIB Tools: 

grib_filter 

grib_filter filter.rules x.grib 

filter.rules 

if ( step

Roadmap. 

•Improvement of the performance of the packing 

algorithms. At this stage the performance of the packing 

algorithm is worse than gribex of several times. It is 

planned to rewrite the packing algorithms in the next 

two/three months. 

•Memory management. Allocation/deallocation is a critical 

activity. 

•Thread safety. Not available in GRIBEX. 

•New indexing algorithms. 

•New fieldset compute. 

•New interfaces. Perl released, Matlab, Python, Java. 

Slide 31 

•Graphical User Interface. Wxwidgets 


Slide 31

GRIB API future (version 2.0) 

Fieldsets 

Fieldsets 

DB 

Order 

Compute 

Files 

Files 

Filter 

CMA 

ECMWF 

JMA 

Slide 32 


Slide 32


•Where condition 

•Order by 

•Formula 

grib_compute -s”u((shortName==u), step asc, number desc), v 

((shortName==v), step asc, number desc)”-f “sqrt( u*u+v*v)” 

Slide 33 


Slide 33


•Where condition 

•Order by 

•Formula 

grib_compute -s”tp(((centre==babj) or (centre==ecmf)) and 

(shortName==tp), step,number,centre)” 

-f freq( tp ,number,

Distribution 

•GRIB API & TOOLS: 1.0 released in April 2007, 

release 1.4 available now with new features and 

several improvements. 

•Version 2.0 will be released soon with the full set of 

compute and fieldset new features. 

•Lesser General Public License. 

•Download 

http://www.ecmwf.int/products/data/software/downlo 

ad/grib_api.html 

•Support Software.Services@ecmwf.int 

Slide 35 


Slide 35

Questions 

Slide 36 


Slide 36

Introduction

Create successful ePaper yourself

Delete template?

Save as template?