Navigation

The namelist input file specifies user-provided run control
parameters for a model run. These parameters include the model startup
file, start and stop times, solar inputs, lower boundary files, and
several other flags and data files as necessary. This document describes
each valid namelist parameter, their valid combinations, and provides
several example input files for running the model in different modes
and resolutions.

X-component of the IMF. Can be specified as either a constant (BXIMF), or series of
time-dependent values (BXIMF_TIME). If IMF_NCFILE is set and BXIMF is not provided,
then BXIMF will be taken from the IMF data file.

Y-component of the IMF. Can be specified as either a constant (BYIMF), or series of
time-dependent values (BYIMF_TIME). If IMF_NCFILE is set and BYIMF is not provided,
then BYIMF will be taken from the IMF data file.

Z-component of the IMF. Can be specified as either a constant (BZIMF), or series of
time-dependent values (BZIMF_TIME). If IMF_NCFILE is set and BZIMF is not provided,
then BZIMF will be taken from the IMF data file.

Set CALENDAR_ADVANCE=1 to advance calendar time from START_DAY, otherwise
calendar time is not advanced. If advancing calendar time, iday (init_module)
is incremented every 24 hours, and the sun’s declination and longitude is recalculated
(see sub advance_day in advance.F and sub sunloc in magfield.F), thereby allowing
seasonal change to take place. The earth’s orbital eccentricity “sfeps” is also
updated as a 6% variation in solar output over a year.

A run with CALENDAR_ADVANCE=0 is referred to as a “steady-state” run. This is often
used to advance the model to a “steady-state” for a given date, prior to a seasonal
run with CALENDAR_ADVANCE=1.

Cross-tail (or cross-cap) potential. This is used in the auroral precipitation
parameterization. It can be provided either as a single constant (CTPOTEN), or
several time-dependent values (CTPOTEN_TIME). If GPI_NCFILE is set and CTPOTEN
is not provided, it will be calculated from 3-hourly Kp data read from GPI_NCFILE.

The time-dependent example below specifies increasing CTPOTEN from model times
80,0,0 to 80,1,0, and 80,5,0. Interpolated values will be used between these
specified model times.

Note that if POTENTIAL_MODEL=’WEIMER’ or ‘WEIMER05’, then the user is not allowed
to provide CTPOTEN because it will be calculated from the Weimer electric potential.

Daily F10.7 cm solar flux. This can be provided either as a single constant (F107), or
several time-dependent values (F107_TIME). If GPI_NCFILE is set and F107 is not set,
then F107 will be set from the data. The below example of F107_TIME increases the f10.7
flux from 120 to 150 in the first hour of model time, then to 200 by the fifth hour.
Values are linearly interpolated at each time-step.

81-day average F10.7 cm solar flux. This can be provided either as a single constant
(F107A), or several time-dependent values (F107A_TIME). If GPI_NCFILE is set and F107A
is not set, then F107A will be set from the data. The below example of F107A_TIME
increases the f10.7a flux from 120 to 130 in 12 hours of model time.

Specifies a netCDF data file containing 3-hourly Kp and daily F10.7 data to drive
high-latitude convection and the auroral precipitation oval. If GPI_NCFILE is specified,
and POTENTIAL_MODEL=’HEELIS’, then at least one of CTPOTEN,POWER,F107,F107A must not
be specified. If CTPOTEN or POWER are not specified, they are calculated from the Kp data
using empirical relationships (see source file gpi.F). If F107 or F107A are not specified,
the data will be used.

If GPI_NCFILE is specified when POTENTIAL_MODEL=’WEIMER’ and IMF_NCFILE is specified,
then the Weimer model and aurora will be driven by the IMF data, and only F107 and F107A
will be read from the GPI data file (F107 is not available on IMF data files).

If the current model time is not available on the GPI data file, the model will print
an error message to stdout, and stop.

Data Source: Ascii data is obtained from NOAA/NGDC, and an equivalent netCDF data file
is written for import to the TGCM models (see code in hao:$TGCMROOT/mkgpi).

Paths to netCDF data files containing tidal perturbations from the Global Scale Wave Model.
If provided, the files will be read and the perturbations will be added to the lower
boundary conditions of T,U,V, and Z. If provided, then TIDE and TIDE2 must be zeroed out.

Warning: As of version 1.94, the model is not tuned to use the non-migrating
GSWM tidal components. The default namelist input file specifies migrating diurnal and
semi-diurnal tides, but not the non-migrating components. In later releases, non-migrating
tides may be supported at the 2.5-deg resolution.

GSWM files must contain data compatable with the lower boundary of the model (99 km),
and the horizontal resolution of the model being run (either 5 or 2.5 degrees).
See examples below.

Hemispheric Power (GW). This is used in the auroral precipitation parameterization.
It can be provided either as a single constant (POWER), or several time-dependent
values (POWER_TIME). If GPI_NCFILE is set and POWER is not provided, it will be
calculated from 3-hourly Kp data read from GPI_NCFILE.

The time-dependent example below specifies increasing POWER from model times
80,0,0 to 80,1,0, and 80,5,0. Interpolated values will be used between these specified
model times.

Geomagnetic Activity index. If KP is specified and POWER and/or CTPOTEN are commented,
then the given KP will be used with empirical formulas to calculate POWER and/or CTPOTEN,
which are used in the Auroral parameterization.

KP can be provided as a scalar constant (KP), or as a series of time-dependent values
(KP_TIME), as in the below examples. KP cannot be set if GPI_NCFILE data file is specified.

Empirical formula used to calculate POWER from KP (see function hp_from_kp in util.F):

Specifies a netCDF data file containing hourly IMF parameters BX,BY,BZ,SWVEL, and SWDEN.
This can be set only when POTENTIAL_MODEL=’WEIMER’. The data will be used to drive
the Weimer 2005 potential model. When set, the user must not provide at least one
of the above IMF parameters. Data will be used for IMF parameters not provided by the
user. Values (scalar or time-dependent) that are provided by the user will take precedence
over the data file.

If the current model time is not available on the IMF data file, the model will print
an error message to stdout and stop.

Notes on creation of IMF OMNI data files:

IMF data is derived from 1-minute OMNI satellite data available on CDAweb
CDAweb. Our derivation is a multi-step process:

Data gaps in the raw 1-minute OMNI data are linearly interpolated. If a gap happens to occur
at the beginning or end of the time interval, it is set to the next known good data point.

Gap-filled data is used to compute a 15 minute trailing average lagged by 5 minutes.

Time averaged data is sampled at 5 minutes

A data quality flag is calculated for every 5-minute sample point. The data quality flag is
a boolean value set to “1” for all sample points derived from valid (not gap-filled) data.
The data quality flag is set to “0” for any sample point that is derived from gap-filled data
anywhere in the 15 minute trailing average lagged by 5 minutes.

LABEL may be any string up to 80 characters long, used to identify a run.
The LABEL is written to output history files as a global file attribute.
This parameter is purely a user convenience, and does not effect the model
run in any way.

Maximum number of histories to be written to primary OUTPUT files. When this many
histories have been written to the current OUTPUT file, the next OUTPUT file is created
and it receives subsequent histories. This parameter can be adjusted to control the size
of primary OUTPUT files.

Maximum number of histories to be written to secondary output files (SECOUT).
When this many histories have been written to the current SECOUT file, the next SECOUT
file is created and it receives subsequent histories. This parameter can be adjusted
to control the size of secondary OUTPUT files.

List of primary history output files. Each file may be an absolute path, or relative
to the execution directory. If an initial run (SOURCE is specified), then pre-existing
OUTPUT files will be overwritten. If a continuation run (SOURCE is not specified),
then the first OUTPUT file should contain the source history at START time. In this case,
subsequent output histories will be appended to the first OUTPUT file until it is full.
As each OUTPUT file is filled (see MXHIST_PRIM), the next OUTPUT file is created and
histories are written until it is full, and so on.

OUTPUT files are usually specified with increasing integers imbedded in the names. See
examples below. As a convenience, large sequences of files may be specified in a “short-form”,
see example 3 below specifying 20 files. By convention, primary history output files
may use the letter “p” to indicate primary file series (see all 3 examples below, and
contrast with SECOUT).

The Weimer model of high-latitude potential is the intellectual property of Daniel
Weimer and may not be extracted, distributed, or used for any purpose other
than as implemented in the TIE-GCM. For further information concerning this
model, please contact Dan Weimer (dweimer@vt.edu).

List of fields to be saved to secondary histories. These may be either fields that are
also saved on primary histories (so-called “prognostic” fields), fields that have been
requested via addfld calls in the source code, or fields available via the diagnostics
module (see example below).

Note the final size of secondary output files is affected by the number of fields specified
as well as the number of histories on the file. The file size can be controlled by setting
the number of histories allowed on a secondary file MXHIST_SECH.

List of secondary history output files. Secondary histories store diagnostic fields,
usually at a higher temporal resolution than primary files. Each file may be an
absolute path, or relative to the execution directory. Beware that SECOUT will
overwrite any pre-existing files with the same names. As each SECOUT file is filled
(see MXHIST_SECH), the next SECOUT file is created and histories are written until
it is full, and so on.

SECOUT files are usually specified with increasing integers imbedded in the names. See
examples below. As a convenience, large sequences of files may be specified in a “short-form”,
see example 3 below specifying 20 files. By convention, secondary history output files
may use the letter “s” to indicate secondary file series (see all 3 examples below).

SOURCE is the start-up history file for an initial run. SOURCE may be a full path or
relative to the execution directory. It must be a TIEGCM history with the same grid
resolution as the model being run. It does not need to be from the same model version
as that being run.

If SOURCE is specified, then SOURCE_START, the model time of the history to read on the
SOURCE file, must also be specified. The code will search the SOURCE file for the
SOURCE_START history. If SOURCE is not specified, then the run is a continuation run,
and the source history is provided in the first OUTPUT file at START time.

The SOURCE file must be on the local disk. The model will not look for the SOURCE
history on any archive file system.

This is the model time of the history to read from the SOURCE file. Model time is
specified as a 3-integer triplet: day,hour,minute. If SOURCE is specified, then
SOURCE_START must also be specified. If the SOURCE_START history is not found on the
SOURCE file, the model will stop and print an appropriate error message to stdout.

Model time for start of the run. Model time is a 3-integer triplet: day,hour, minute.
If CALENDAR_ADVANCE=0, then START day can be any number between 0 and 365.
If CALENDAR_ADVANCE=1, then START day must be the same as START_DAY. If an initial run,
START time does not have to be the same as SOURCE_START.

Model time-step in seconds. Default value is 120, although during periods of quiet
solar activity, the model will run fine at 180. During periods of intense solar
activity (e.g., F10.7 > 200, or high magnitude BZ southward), the model may become
numerically unstable. In this case, reducing the timestep to as low as 60 seconds
may help the model get through the rough period.

Solar Wind Density. Can be specified as either a constant (SWDEN), or series of
time-dependent values (SWDEN_TIME). If IMF_NCFILE is set and SWDEN is not provided,
then it SWDEN will be taken from the IMF data file.

Solar Wind Velocity. Can be specified as either a constant (SWVEL), or series of
time-dependent values (SWVEL_TIME). If IMF_NCFILE is set and SWVEL is not provided,
then it SWVEL will be taken from the IMF data file.