INTRODUCTION
The COLA AGCM requires several files in order to run. The model operates in one of two modes: initial run and restart run. Each mode uses a somewhat different configuration of files while still using many files in common. Many of these files have Gaussian grid data fields which in version 2 of the AGCM are oriented as follows: the first value location is centered on the Prime (Greenwich) Meridian at the first Gaussian latitude located just north of the South Pole. The next values are located at the same Gaussian latitude and proceed eastward until the entire Gaussian latitude is encompassed. The next values are found at the next Gaussian latitude northward in the same order. This process continues to the northernmost Gaussian latitude.
Data representation varies from machine to machine. Typically IEEE standards
are used, but size and byte order may vary. Most of the time big endian
byte order is used because of greater portability and 4 bytes are used
for integers. Real values may be represented by 4 bytes or more often 8
bytes. Output files used as input to subsequently restart the model are
always written in native binary form to assure reproducibility.
INITIAL RUN - INPUT FILES
This section describes files related to INPUT used in the INITIAL RUN
of GCM. The INPUT files can be divided into 4 categories: CONTROL FILES,
INITIAL CONDITIONS and INITIALIZING FILES, BOUNDARY CONDITIONS FILES and
INTERNAL TABLES. Whenever applicable, a subroutine name is given for referring
to more details about the file in question.
A) CONTROL FILES
On some machines, the physical files are associated to the logical files
in the program through script files. On these machines, the Namelist file
is always read in from unit 5. The document GCM PROGRAM NAMELIST can be
referred to for more details on the Namelist parameters.
On other machines, a filename file has been designed to be read in by
optional subroutine OPNFI. This file contains the names of the physical
files and some optional attributes, such as direct access I/O. This file
is read in by the program, and then the listed files are FORTRAN opened
to their logical counterparts, which includes the Namelist file opened
from file units 15. The filename file can be edited by the user. The other
files described below are included in this file.
B) INITIAL CONDITIONS AND INITIALIZING FILES
1) INITIAL CONDITIONS
UNFORMATTED and read in from NFIN0
This file has a complicated structure and has several records.
1st Record: IFDAY, TOD, IDATE, IDATEC, SIGA, SIGB
where IFDAY is INTEGER forecast day, TOD is the forecast time-of-day in seconds relative to starting time of the forecast day, IDATE is INTEGER array of dimension 4 that contains initial date (hour, month, day, year) at which initial conditions apply, IDATEC is INTEGER array of dimension 4 that contains the current date (hour, month, day, year) which will be the same as IDATE. Arrays SIGA and SIGB with 2×KMAX+1 levels each arranged top to bottom contain the hybrid vertical coordinate level information. The pure pressure based values in SIGA at the layer interfaces (odd indexes from 1 to 2×KMAX+1) and layer mid-points (even indexes from 2 to 2×KMAX) correspond to the HYAI and HYAM arrays in the AGCM. Since in this version the COLA physics cannot process hybrid coordinate levels, these are normally all set to zero except for the first top-most interface value which must be set non-zero (usually 1 Pa) when using semi-Lagrange moisture transport. The pure sigma based values in SIGB are indexed the same as SIGA and correspond to the HYBI and HYBM arrays in the AGCM. These are subsequently passed to the COLA physics.
Records 2 to JMAX+1 are individual Gaussian latitude records beginning at the southernmost latitude and progressing to the northernmost latitude with 2+4×KMAX levels or slots of data each with IMAX values indexed eastward from the Prime Meridian arranged as follows:
| 1st level or slot: | surface pressure (Pa) |
| 2nd level or slot: | surface topography geopotential (not height) (m2/s2) |
| 1st set of KMAX levels: (slots 3 to KMAX+2) | zonal wind (m/s) indexed from the top of the atmosphere to the bottom. |
| 2nd set of KMAX levels: | meridional wind (m/s) indexed as above |
| 3rd set of KMAX levels: | air temperature (K) indexed as above |
| 4th set of KMAX levels: | specific humidity (kg/kg) indexed as above |
REFERENCE: Subroutines INITAL, INITCOM, HYCOEF, INIDAT and EXTIC
2) INITIAL SOIL TEMPERATURE AND ROUGHNESS LENGTH
UNFORMATTED and read in from NFTGZ0
Single read of 4 Gaussian grids: TG1, TG2, TG3, ZORL. In this model,
only roughness length (ZORL) is still used.
REFERENCE: preparation programs intzorln.f, inttg3n.f and mktg3z.f
3) INITIAL SNOW MASS
UNFORMATTED and read in from NFSNW
Single Gaussian grid indicating initial snow mass in kg/m2.
NOTE:- Permanent ice points are normally set to 3000 kg/m2.
Other points are set proportional to climatological surface albedo.
REFERENCE: preparation programs snojob.f or snowic.scr.
4) INITIAL SOIL WETNESS
UNFORMATTED and read in from NFSLM
12 months of soil moisture which are interpolated linearly to initial
conditions date.
5) INITIAL CLOUD DISTRIBUTION (Optional File)
UNFORMATTED and read in from NFCNV0
| 1st Record: | IFDAY,TOD,IDATE,IDATEC
See 1st record of Initial Conditions for description. |
| 2nd Record: | CONVC,CONVT,CONVB,PRCP1,PRCP2,PRCP3,PRCPT,TOPLV,BOTLV |
6) SiB PROGNOSTIC FIELDS (Optional File)
UNFORMATTED and read in from NFSIBI
| 1st Record: | IFDAY,TOD,IDATE,IDATEC
See 1st record of Initial Conditions for description. |
|
| 2nd Record: | 2 arrays of 2 time levels of soil temperature
Arrays are of dimension (IMAX, 3, JMAX) where IMAX is the Gaussian longitude, 3 is the number of soil layers and JMAX is the Gaussian latitude |
|
| 3rd Record: | 2 Gaussian Grids of 2 time levels of ground temperature | |
| 4th Record: | 2 Gaussian Grids of 2 time levels of canopy temperature | |
| 5th Record: | 2 arrays of 2 time levels of soil moisture
Arrays are of dimension (IMAX, 3, JMAX) where IMAX is the Gaussian longitude, 3 is the number of soil layers and JMAX is the Gaussian latitude |
|
| 6th Record: | 2 arrays of 2 time levels of liquid water storage
Arrays are of dimension (IMAX, 2, JMAX) where IMAX is the Gaussian longitude, 2 refers to canopy and ground levels and JMAX is the Gaussian latitude |
|
| 7th Record: | 2 Gaussian Grids of last computed convective and large scale precipitations | |
| 8th Record: | 4 Gaussian Grids: | |
| 1st Gaussian Grid - | maximum mixing length | |
| 2nd Gaussian Grid - | roughness | |
| 3rd & 4th Gaussian Grids - | 2 time levels of sea-ice temperature | |
NOTE:- The data in each Gaussian latitude are left compressed to only
contain land points for records 2 thru 6.
C) BOUNDARY CONDITIONS FILES
1) HEIGHT VARIANCE
UNFORMATTED and read in from NFVAR
Single Gaussian grid - units m2
Used for gravity wave drag
2) SEA-SURFACE TEMPERATURE
UNFORMATTED and read in from NFSST
Cyclical monthly SST form (using sequential data set):
13 Gaussian grid records - Units are KELVIN
1st Record: surface drag (no longer used - it is skipped)
The next 12 records refer to 12 months of height corrected SST over
the ocean and a negative value over land. The values of sea-ice points,
typically 270.16K, are set 1 degree below sea-ice freezing point (TSICE)
. Data are treated as calendar months and can either be climatological
or observed SST.
Example for observed SST: To allow for sufficient overlap for time interpolation
an integration beginning on 1 July must have observed SST beginning in
June so that records 7 to 13 are June to December of initial condition
year and records 2 to 6 are January to May of the following year. If integration
continues, a new data set containing April to December (records 5 to 13)
of the following year and January to March (records 2 to 4) of the year
after that should be used beginning 1 May of the following year. If integration
still continues, data sets should be changed every ten months.
Continuous SST form (usually direct access weekly or monthly records)
in one of two types:
The first type (IFSST=4) has an arbitrary number of Gaussian grid records each containing height corrected SST over the ocean and a negative value over land. As long as the time interpolated values are below TSICE (sea ice freezing), the point is treated as a sea ice point. To assure that the sea ice freezing temperature is crossed, data records with sea ice are set either to 1 degree below TSICE or as far below TSICE as the preceding or succeeding record is above TSICE.
The second type (IFSST=5) also has an arbitrary number of Gaussian grid records each containing a negative value over land, but with ordinary (non-height adjusted) SST over ocean. Here the model adjusts the SST value by height internally using the surface topography height data set (see below).
Sea ice points are determined separately by the sea ice concentration data set. This permits height adjusted values of SST to be below TSICE but still be treated as open water points. In this data set the values of SST over points with sea ice are set either to 1 degree below TSICE or weighted by the sea ice concentration so that when sea ice concentration interpolates to 0.5, the SST interpolates to TSICE.
For both types the data record time interval and starting times are indicated by namelist parameters. See IFSST, INTSST, TSICE and SSTLAG in the GCM PROGRAM NAMELIST document for usage.
3) SEA ICE CONCENTRATION
UNFORMATTED and read in from NFICE
This direct access data set is only read when using the second type
of continuous sea surface temperature (SST) data set (IFSST=5). The interval,
starting, and ending dates must match the corresponding SST data set. Points
with sea ice concentration after time interpolation at or above 0.5 are
assumed to be sea ice points. Units are fraction of concentration or coverage.
4) VEGETATION MASK
UNFORMATTED and read in from NFSIBT
Gaussian Grid INTEGER vegetation type over all the land points.
5) SOIL DATA AND MASK
UNFORMATTED and read in from NFSOIL.
Five Gaussian grid REAL records of soil data and soil type (5th record).
REFERENCE: Subroutine VEGIN
6) HETEROGENEOUS SPATIAL AND TEMPORAL VEGETATION VALUES
UNFORMATTED and read in from NFVEG
Climatological data containing 12 months of Gaussian grid data each
with 3 records: leaf area index, fraction of photosynthetically active
radiation (FPAR), and greenness.
Read in and time interpolated in subroutine GETSBC.
7) PLANETARY EPHEMERIDES
UNFORMATTED and read in from NFASTR
A complex data set containing sets of Chebyshev polynomial coefficients
for each planet, the sun and the moon at 32-day intervals. See CTR#93 for
further discussion. Used only when NOVAS/JPL astronomy is requested. (IAST='nova').
Read in subroutines INIASTRO and STATE.
8) ASTRONOMY DT TABLE
FORMATTED and read in from NFDELT
An optional table (TDT=.FALSE.) used only by the NOVAS/JPL astronomy
(IAST='nova') to correct for time shifts caused by changes in the Earth's
rotation. See CTR#93 for further discussion.
Read in subroutine INIASTRO.
D) INTERNAL TABLES
1) UNITS CONVERSION
FORMATTED - Not User Settable
These files are subject to expansion. The unit numbers are fixed. Six
tables (files with units 34 thru 39) are used to convert model output to
the units that the user wants.
2) AVAILABLE DIAGNOSTICS
FORMATTED - Not User Settable
The contents vary with model version as well as with model vertical
resolution. All the information is fixed to the model version and it contains
all diagnostics that the specific model version can compute. Unit number
is fixed to 48. See Diagnostics System Version
2 for further discussion.
5) DESIRED DIAGNOSTICS
FORMATTED - User Settable
The contents are based on the available table used for the specific
model version. Unit number is fixed to 49. See Diagnostics
System Version 2 for further discussion.
6) VEGETATION AND SOIL PROPERTIES DATA
FORMATTED and read in from NFSIBD
It contains numerous parameters for each vegetation type and each soil
type.
REFERENCE: Subroutine VEGIN
7) AERODYNAMIC PROPERTIES DATA
FORMATTED and read in from NFAERO
Contains additional parameters dependent on vegetation type.
REFERENCE: Subroutine VEGIN
INITIAL RUN - INTERMEDIATE FILE
This section describes the intermediate file used in the initial run
of the GCM.
INITIAL CLOUD RADIATION STATISTICS
UNFORMATTED and written to/read in from NFCLDR
This file is used to save the initial cloud radiation statistics from
the first radiation call for saving into the diagnostic accumulators after
the accumulators have been flushed during initial start up procedures (diabatic
heating, normal mode or smooth start). This permits the statistics to be
retained in 2-dimensional vertical slab arrays in subsequent non-initial
calls without requiring additional memory for each latitude.
REFERENCE: Subroutine GPHYS
INITIAL RUN - OUTPUT FILES
This section describes the output files used in the initial run of the
GCM. The output files can be divided into 3 categories: FILES USED FOR
SUBSEQUENT RESTART, SYNOPTIC DIAGNOSTICS, and optional SUB-SAMPLED DIAGNOSTICS.
A) FILES USED FOR SUBSEQUENT RESTART
1) ATMOSPHERIC RESTART FILE
UNFORMATTED and written out to NRG1(1,...,nnrg1). For all currently
used resolutions nnrg1=1 and NRG1(1)=43.
A very complex data set containing both time levels of the complete atmospheric state and several intermediate product partial summations. Content and size also depend on whether running with spectral moisture transport (DOSLT=.FALSE.) or semi-Lagrange moisture transport (DOSLT=.TRUE.).
1st Record: IFDAY, TOD, IDATE, IDATEC, SIGA, SIGB, FIXMAS
The values of IFDAY, TOD, IDATE, IDATEC, SIGA, and SIGB have the same meaning as the atmospheric initial condition file (NFIN0). IFDAY, TOD, and IDATEC are set to their current values. FIXMAS is the initial dry atmospheric mass.
Most other records contain of a set of several data record groups. Each set is written out for each increasing latitude index. The set consists of: b1 derived type; b2 derived type; current time level of u, v, t and q; previous time level of u, v, t, and q. For semi-Largrange moisture transport the set also includes: lambda, phi and sigma mid-point trajectory values, and moisture and other constituent forecast values. For either moisture transport method the set ends with the two time levels of surface pressure. After all latitudes have been written, a single record set of global integral values is also written when using semi-Lagrange moisture transport. See the module PMGRID for the definitions of the b1 and b2 derived types which also depend on the moisture transport method used.
REFERENCE: Subroutines INITAL, LUNITS, RESUME, SPLITF, STEPON and WRTRS1
2) SiB RESTART FILE
UNFORMATTED and written out to NFSIBO
This file has the same structure as the INITIAL RUN INPUT FILE SiB PROGNOSTIC FIELDS (NFSIBI).
IFDAY, TOD, and IDATEC are set to their current values.
REFERENCE: Subroutine WRCOLA
3) CLOUD AND RADIATIVE RESTART DATA
UNFORMATTED and written out to NFCNV1
| 1st Record: | IFDAY,TOD,IDATE,IDATEC as described in Initial Condition (NFCNV0) 1st record with IFDAY, TOD, and IDATEC set to their current values. |
| 2nd Record: | cloud record (same structure of NFCNV0) |
| 3rd Record: | 9 Gaussian grid fields indicating state of the radiation and a scalar variable indicating initial total dry air mass (not currently in use) |
| 4th Record: | The upward longwave radiation accumulated at the bottom and a scalar integer with the number of time steps between longwave radiation calls. |
REFERENCE: Subroutine WRCOLA
B) SYNOPTIC DIAGNOSTICS AND SUB-SAMPLED DIAGNOSTICS
Description appears in Diagnostics System
Version 2 document.
RESTART RUN - INPUT FILES
This section describes files related to INPUT used in the RESTART RUN
of GCM. The INPUT files can be divided into 4 categories: CONTROL FILES,
BOUNDARY CONDITIONS FILES and INTERNAL TABLES, INITIAL FILES. Whenever
applicable, a subroutine name is given for referring to more details about
the file in question.
A) CONTROL FILES
These files are the same described in the INITIAL RUN.
B) BOUNDARY CONDITIONS FILES
These files are the same described in the INITIAL RUN.
C) INTERNAL TABLES
These tables are the same described in the INITIAL RUN.
D) INITIAL FILES
1) ATMOSPHERIC RESTART FILE
UNFORMATTED and read in from NRG1(1,...,nnrg1). For currently used resolutions,
nnrg1=1 and NRG1(1)=41. This is the same file described in INITIAL RUN
- OUTPUT FILES: FILES FOR SUBSEQUENT RESTART.
2) SiB RESTART FILE
UNFORMATTED and read in from unit NFSIBI. This has the same file described
previously in the INITIAL RUN INPUT FILES SiB PROGNOSTIC FIELDS.
3) CLOUD AND RADIATION RESTART FILE
UNFORMATTED and read in from unit NFCNV0. It has the same structure
as CLOUD AND RADIATION RESTART FILE (unit NFCNV1) described in the INITIAL
RUN - OUTPUT FILES: FILES FOR SUBSEQUENT RESTART.
RESTART RUN - INTERMEDIATE FILE
The intermediate file is not used for RESTART RUN..
RESTART RUN - OUTPUT FILES
All these files are the same described in the INITIAL RUN OUTPUT FILES.