BUFR/PREPBUFR Tutorial
BUFR/PREPBUFR TutorialThe BUFR On-line Tutorial provides step by step instructions to compile the BUFR processing code, and test the executables with provided samples.
Practice 1: Basic skills
Practice 1: Basic skillsIntroduction
This practice is to help first-time BUFR users to start compiling and running BUFR processing code.
Getting the Sample Codes
Please go to Examples/basic to download the first two examples and its BUFR table to a location space:
- encode_temperature.f90
- decode_temperature.f90
- bufrtable.txt
Here we assume the above files have be copied to a directory under comGSI/util/test
. So the BUFRLIB library is located at ../../lib/libbufr_i4r8.a
related to this test directory.
Encode/Write to a BUFR file
This example is to open a BUFR file called "t.bufr" and write a temperature observation 10.15 into it. We can use the following two steps to compile the code:
pgf90 -c encode_temperature.f90
pgf90 -o encodeT.exe encode_temperature.o -L../../lib -lbufr_i4r8
User may notice that these two steps are standard fortran code compiling process. The special point of the compiling BUFR code is to link the BUFRLIB library at the link step.
Also, please note we are using PGI compiler here as an example. Users should use the same compiler as used for compiling BUFRLIB or community GSI.
After got the executable encodeT.exe
. We can run it as:
./encodeT.exe
A new BUFR file called "t.bufr" will show up in the working directory. Please note that the BUFR encoding needs an existing BUFR table, which is text file bufrtable.txt we have downloaded with the code and saved in the same directory.
Decode/Read from a BUFR file
This example is to read the temperature observation 10.15 out from the BUFR file "t.bufr", which we created in the practice before. We can use the same two steps to compile the code:
pgf90 -c decode_temperature.f90
pgf90 -o decodeT.exe decode_temperature.o -L../../lib -lbufr_i4r8
After got the executable decodeT.exe
. We can run it as:
./decodeT.exe
A line will show up on screen to give the temperature observation that just reading in:
10.10000000000000
Practice 2: BUFR tools with GSI release version 3.0
Practice 2: BUFR tools with GSI release version 3.0Introduction
This practice is to learn the use of the BUFR tools within the community GSI release version 3. The practice is adopted from the similar exercise for the Summer 2011 Tutoral.
Building the Sample Codes
The source code for this exercise is contained in the community GSI package under directory: comGSI_v3/util/bufr_tools
. Or you can download the single file from: Examples. For practice, you should have already compiled the community GSI release version 3.0, which gave a BUFRLIB library. The source code for the BUFR tools should then be located in: comGSI_v3/util/bufr_tools
Now, user can following the next two steps to compile all the examples:
- Change into the
comGSI/util/bufr_tools
- Compile the source:
./make
During compiling, the following message will show up on screen and repeat for each BUFR files:
pgf90 -O2 -c bufr_encode_sample.f90
pgf90 -o bufr_encode_sample.exe -O2 bufr_encode_sample.o -L../../lib -lbufr_i4r8
rm bufr_encode_sample.o
The users can compile a single file using the above compile command.
Once compiled, you will see 10 executables, with .exe
suffixes. There are two sets of executables:
The first set ends with the _sample
suffix. These codes illustrate basic code structures of fortran code for BUFR file encoding, decoding, and appending:
bufr_encode_sample.exe
bufr_decode_sample.exe
bufr_append_sample.exe
The second set either starts with the prepbufr_
prefix or the _radiance
suffix, and is an extension of the first set to PrepBUFR and/or radiance BUFR files.
The second group of codes illustrates how to process BUFR/PrepBUFR files that GSI can use:
prepbufr_encode_upperair.exe
prepbufr_encode_surface.exe
prepbufr_decode_all.exe
bufr_decode_radiance.exe
prepbufr_append_upperair.exe
prepbufr_append_surface.exe
prepbufr_append_retrieve.exe
Running the simple examples
To illustrate the processing of BUFR/PrepBUFR files, consider the following three simple examples:
- Running
./bufr_encode_sample.exe
generates a bufr file namedsample.bufr
, which includes a single observation. - Running:
./bufr_decode_sample.exe
reads the bufr filesample.bufr
, and displays the single observation in it. when run it should display:2008120100 1 ADPUPA
1 1 75.0 30.0 -0.1 287.1
- Running the code
./bufr_append_sample.exe
appends a new observation tosample.bufr
. - Now running
./bufr_decode_sample.exe
a second time, will show that a second observation has been appended to the filesample.bufr
by running./bufr_append_sample.exe
.2008120100 1 ADPUPA
1 1 75.0 30.0 -0.1 287.1
2008120101 2 ADPSFC
1 1 85.0 50.0 0.2 300.0
Running the BUFR/PrepBUFR samples
The exact same steps can be taken with the PrepBUFR
executables.
- Running
./prepbufr_encode_upperair.exe
generates a PrepBUFR fileprepbufr
, which includes a sounding observation. - Running
./prepbufr_decode_all.exe
reads the observations from the fileprepbufr
, and displays the observation information. Please compare your standard out with that at the link. Notice that two observations have been appended to the file.
- Running
./prepbufr_append_surface.exe
appends a surface observation to the PrepBUFR fileprepbufr
. - Running
./prepbufr_decode_all.exe
reads the observations from the fileprepbufr
, and displays the observation information. Please compare your standard out with that at the link. Note that the two new surface observations have been added to the file.
- Running
./prepbufr_encode_surface.exe
will encode the PrepBUFR fileprepbufr
with a completely new surface observation, wiping out the previous observations. Check this by running./prepbufr_decode_all.exe
. - Likewise, running
./prepbufr_append_upperair.exe
will append a sounding observation to the fileprepbufr
. Once again, running./prepbufr_decode_all.exe
display the contents of PrepBufr file. Please compare your standard out with that at the link.
- To append a retrieved data to an existing PrepBUFR file, we can use
./prepbufr_append_retrieve.exe
. Once again, use./prepbufr_decode_all.exe
to check the content. The correct output is here.
Please pay attention to the the message type in the BUFR file. This indicates the observation type. Running ./prepbufr_decode_all.exe
and ./bufr_decode_radiance.exe
can be used to check the content of the real BUFR/PrepBUFR files, with the difference being that these executables dump out a greater amount of information than the sample files.
Practice 3: GSI BUFR Interfaces
Practice 3: GSI BUFR InterfacesIntroduction
This practice is to provide more detailed practices for users who need to work with GSI on observation ingesting from BUFR files.
Get the Codes and compile
Please go to the Examples/GSI BUFR Interface to download the four GSI BUFR interface files to a location space:
read_prepbufr.f90
read_gps.f90
read_bufrtovs.f90
read_airs.f90
If user put the above files in a directory called ./util/GSI_bufr_interface
under the GSI main directory of the release version 3.0. Then, please download this makefile and save it in directory: ./util/GSI_bufr_interface
. User can compile these four fortran files using:
./make
Here we assume users have compiled community GSI version 3.0.
If users use other directories other than the above suggested, the makefile needs to be modified to link to the right BUFRLIB library and GSI include files.
Once compiled, 4 executables will show up in working directory:
read_airs.exe
read_bufrtovs.exe
read_gps.exe
read_prepbufr.exe
Try with NCEP BUFR files
Users can use observation files (here (272M)) for GSI tutorial to test three interface files. After move the tar file to directory ./util/GSI_bufr_interface
and untar the file, a directory 2011060212/
will show up in the working directory.
To test read_prepbufr.exe:
ln -s 2011060212/obs/nam.t12z.prepbufr.tm00.nr.le prepbufr
./read_prepbufr.exe
To test read_gps.exe:
ln -s 2011060212/obs/gdas1.t12z.gpsro.tm00.bufr_d.le gpsbufr
./read_gps.exe
To test read_bufrtovs.exe:
ln -s 2011060212/obs/gdas1.t12z.1bmhs.tm00.bufr_d.le bufrtovs
./read_bufrtovs.exe
To check other TOVS radiance files, the observation type has to be changed to:
obstype='amsua' to run
ln -s 2011060212/obs/gdas1.t12z.1bamua.tm00.bufr_d.le bufrtovs
./read_bufrtovs.exe
or
obstype='amsub' to run
ln -s 2011060212/obs/gdas1.t12z.1bamub.tm00.bufr_d.le bufrtovs
./read_bufrtovs.exe
There is no airs BUFR file in the tutorial case. We have to download the file again from (here (308M)) to the working directory. Then test the airs decoding as:
ln -s gdas1.t12z.airsev.tm00.bufr_d.le airsbufr
./read_airs.exe
User may notice that, except for
./read_bufrtovs.exe
, these executables did not write observations or other information the screen. Users are suggested to change the code to write observations from the BUFR/PrepBUFR file to the screen for practice.
Also, please note we use little Endian BUFR files as the examples because we are running these executables on Linux machine.