A guide to using the new GFS history file

Mark Iredell

March 5, 2007

### Background

The vertical coordinate of the operational GFS forecast model will
become a hybrid sigma-pressure coordinate in 2007. This will affect the
file structure of the native GFS history files used by many other
applications.

In addition, the GRIB surface flux files will have several more fields.
The implementation will not affect the GFS surface files or the posted
pressure files.

The GFS restart files will be in an even newer format to accommodate
coming anticipated changes to the GFS in succeeding implementations. No
application outside of the global system needs to read GFS restart files

In the near future, the GFS will output Gaussian grid files as the
history files. Unfortunately, we are not ready yet to make them
operational, so yet another conversion will be necessary when these
files are implemented.

### Choice of strategies

There are three distinct strategies to dealing with these changes:

*Strategy 1: Generalize code to read any operational GFS history file.*

Make possibly significant changes in one's code that will allow the code
to read any operational or experimental GFS history file at least
through 2007.

*Strategy 2: Change resolution to older GFS history files.*

This strategy costs extra processing and extra interpolations. It should
be considered only as a stopgap strategy. This strategy is not
recommended.

*Strategy 3: Hardwire code to make it work for this implementation
only.*

This strategy takes probably the minimum coding changes now, but would
likely require another change in the near future. This strategy is
discouraged and will not be supported.

Which strategy to choose depends heavily on one's needs and resources.

### Strategy 1: Generalize code

Make the changes now that should not only work for old GFS history files
and new GFS history files but for GFS file changes that will occur in
the near future.

The changes involve using a module sigio_module with defined types and
methods. For those who read the GFS surface file and use sfcio_module,
the sigio_module is very similar. With the sigio_module, a lot of code
can be dropped. An early draft user's guide to sigio_module is attached
to the end of this document.

Here is the replacement code to read in the whole GFS history file:

use sigio_module

implicit none

type(sigio_head):: head

type(sigio_data):: data

real,allocatable:: ps(:),pm(:,:)

integer iret,k

call sigio_srohdc(11,\'sigf00.gfs.2005082400\',head,data,iret)

allocate (ps(360\*181),pm(360\*181,head%levs))

call sptez(0,head%jcap,0,360,181,data%ps,ps,+1)

ps=1000\*exp(ps)

call sigio_modpr(360\*181,360\*181,head%levs,head%nvcoord, &

head%idvc,head%idsl,head%vcoord,iret,ps=ps,pm=pm)

Note that the GFS history file is opened, read, and closed in one call,
with the data all allocated the proper dimension. In fact, this code
will work no matter what resolution or vertical coordinate or file
format is read. (Of course, if the GFS ever goes to look like a
gridpoint model from the outside, then the I/O will need to be changed
again at that time.)

### Strategy 2: Change resolution

Initially, all GFS history files will be automatically available in
sigma form. However, these files will not be on the next CCS. Then users
may want to create these files for themselves in advance of running
their legacy scripts.

Here is how to run the change resolution script to create a legacy sigma
file. In this case, a T382L64 sigma file is created.

export SIGINP=input_gfs_history_file

export SIGOUT=output_gfs_sigma_file

export OROGRAPHY=/dev/null

export JCAP=382

export LEVS=64

export LONB=768

export LATB=384

export IDVC=1

export SIGLEVEL=/nwprod/fix/global_siglevel.l64.txt

/nwprod/ush/global_chgres.sh

### Strategy 3: Hardwire code

For now, the GFS history files use words 6-206 of the second record for
the hybrid definition arrays AK(LEVS+1) and BK(LEVS+1) (plus
201-2\*LEVS-2 dummy words)jj. The interface pressures are
AK(k)+BK(k)\*PS, where both pressures are in pascals. The midlayer
pressures are computed using the Phillips method. For more information,
consult the sigio source code.

### Location of test files

At this writing, the parallel sigio and chgres are only in /nwpara/. To
access these temporarily in strategies 1 and 2, please respectively
refer to:

Source /nwpara/lib/sorc/sigio/\*.f

Library -L/nwpara/lib -lsigio_4

Include -I/nwpara/lib/incmod

export CHGRESEXEC=/nwpara/exec/global_chgres

/nwpara/ush/global_chgres.sh

Test history files from a current parallel run can be found here:

/com/gfs/para/

This document can be found here:

ftp://ftp.emc.ncep.noaa.gov/gmb/misc_mi/guidehistory3.doc

Appendix.

GFS SIGIO User's Guide

Draft Version March 15, 2006

Introduction

SIGIO is a F90 module to read and write the GFS "sigma" file. The GFS
sigma file is a binary file for restart and history purposes, containing
all the upper-air data from the GFS atmospheric model. In all, there are
9 datatypes and 54 subroutines in SIGIO.

History

SIGIO was written by Mark Iredell in 1999 during the IBM transition. It
is currently used by several global codes: CHGRES, POSTGP (with parallel
I/O), SIGHDR, and SS2GG. Moorthi has installed SIGIO in the latest GSM
which will be implemented in 2006.

Advantages

SIGIO is a single I/O code reusable for multiple needs and multiple
programs. There is support for multiple file formats and multiple
defined types with SIGIO, giving flexibility and minimizing user code
complexity. SIGIO should make future transitions easier, such as going
to MPI I/O.

File formats

Here is the list of file format versions supported in SIGIO.

ivs=198410 original GFS sigma file

ivs=200509 future GFS sigma file

Both the GFS history output file or model restart file are supported.
The original sigma file version (version 198410) and the future sigma
file version (version 200509) are supported. Version 200509 has new
options for real(4) or real(8) data, any number of levels, any number of
vertical coordinate profiles, or any number of real scalars. None of
these new options are required operationally for GFS history files in
2006, so the output history files will remain version 198410 for now.
However, the operational GFS may output version 200509 by 2007.

Defined types

Here is the list of defined types supported in SIGIO.

sigio_head header metadata

sigio_data real(4) full model state

sigio_dbta real(8) full model state

sigio_dats real(4) surface fields only

sigio_dbts real(8) surface fields only

sigio_datm real(4) multilevel fields between 2 levels

sigio_dbtm real(8) multilevel fields between 2 levels

sigio_dati real(4) single spectral or grid 2D field

sigio_dbti real(8) single spectral or grid 2D field

Subroutines

A list of subroutines can be found in the source code docblock.

Public Variables

A list of public variables can be found in the source code docblock.

Full documentation

Full documentation can be found in the source code docblock.

Use Cases

1.  Read the entire sigma file \'sigf24\' and print out the global mean
    temperature profile.

use sigio_module

type(sigio_head):: head

type(sigio_data):: data

call sigio_srohdc(11,\'sigf24\',head,data,iret)

print \'(f8.2)\',data%t(1,head%levs:1:-1)/sqrt(2.)

2.  Read the entire sigma file \'sigf24\' and compute 3D pressures.

use sigio_module

implicit none

integer,parameter:: im=360,jm=181,ijm=im\*jm

type(sigio_head):: head

type(sigio_data):: data

integer iret

real(4),allocatable:: ps(:),pm(:,:)

call sigio_srohdc(11,\'sigf24\',head,data,iret)

allocate(ps(ijm),pm(ijm,head%levs))

call sptez(0,head%jcap,0,im,jm,data%ps,ps,+1)

ps=1.e3\*exp(ps)

call sigio_modpr(ijm,ijm,head%levs,&

head%nvcoord,head%idvc,head%idsl,head%vcoord,&

iret,ps=ps,pm=pm)

Location

Operational

Source /nwprod/lib/sorc/sigio/\*.f

Library -L/nwprod/lib -lsigio_4

Include -I/nwprod/lib/incmod