source:read_grib1.F90

Read_grib1 is a subroutine. It handles the reading of Grib files for model1, as does read_cosmo1 for NetCDF files. In turn, the application programming interface (API) of ecCodes handles the reading for read_grib1 on a lower level.

All subroutine of ecCodes optionally produce error codes. If they are not caught, they crash the whole program and output their error to some standard output of some processor. Therefore, the subroutine eccodes_handler catches and handles the error.

There is no read_grib2, which would be the counterpart for read_cosmo2.

Header commentary

Apart from a usual header with author information, it also inlcudes a list of arguments:

! filename  :   The directory of the grib file. May be relative or absolute.
!           But no funny business with wildcards like *. Better even
!           abstain from .. .
! varname       :   The name of the variable to be read. A status output at 
!           the end repeats it. If the file is to be indexed (judged 
!           by the intrinsic idxcase), varname is put to a proper
!           use, as a selector for the indexed shortName.
! vshape        :   read_grib1 can only read rectangular fields
!           in the sense that they have two starting coordinates,
!           vshape(1) and vshape(3) (usually 1)
!           and two end coordinates, vshape(2) and vshape(4), and
!           not in the sense of map projections.
! il_offset :   starting points, for cropping a supercomputing share.
! klevel        :   specifies the desired layer in read_cosmo1.F90. Forced to
!           be <0 (the only layer/ the first one in the file) with a 
!           warning, except if the file is to be indexed.
!           Then, klevel selects the layer, counting from 51 downwards,
!           which in modeled terms means increasing the distance to 
!           Earth's surface.
! varoup        :   The returned array, provided by a Grib file. It is a matrix.
! w_unit        :   What output unit to write the status to after reading.
!           If w_unit .eq. 6, this subroutine will write it to stdout
!           using WRITE(*,*).

Some advice for internet research is also included:

! Uses ecCodes (http://download.ecmwf.int/test-data/eccodes/html/,
! https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home)
! ecCodes replaced grib-api as the ECMWF-endorsed way to access GRIB files.
! The process involved namechanges, so search the internet carefully.
! Or just follow the link and search there.

Structure

Read_grib1 is a long subroutine, separated in 4 broad sections without overlap, but with gaps.

Section L: Selecting the correct layer and variable

The core of section L is the selection of 1 horizontal field by means of their [[naming-schemes#Grib-keys|Grib key]]. To avoid cycling through all Grib messages for an indefinite time, read_grib1 creates an index, or re-uses one from an earlier run. The indices are saved in the run directory of [[Model1|model1]], commonly source:scratch.
One index applies to the coarse external parameters, extern.read_grib1.idx. The other ones deal with the layered temperature files. Their names also end in ‘read_grib1.idx’, but are preceded by their corresponding file names.

Section F: Finding the shape of the field

This section retrieves the horizontal size of the field with the subroutine codes_get. After this and before the following section, read_grib1 retrieves the values.

Section S: Shaping and cropping

Section S uses the dimensions which section F obtained to allocate a dump variable varact2D. Only a small index box from varact2D is used at all, and the box is distributed among the parallel computing nodes. A more elegant way to do this would be to supply model1 only with a priori cropped data.

Section W: Writer

To mark its conclusion, read_grib1 writes, ‘Read COSMO GRIB varoup : [here be the variable’s name]’
After this section, there is only some de-allocation.