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.
Please refer to the following examples of namelist input files:
Note
Any part of a line in the namelist file following a semi-colon will be treated as a comment (see example files).
Example Namelist Input Files:
- The default input file: default.inp
- A continuation of the default run: continuation.inp
- Saving diagnostics on secondary history files: diags.inp
- Full year climatology with constant forcing: climatology.inp
- Seasonal control runs with constant forcing: mareqx.inp
- Heelis potential model with constant solar forcing: heelis_smax.inp
- Heelis potential model with GPI (Kp) data file: heelis_gpi.inp
- Weimer potential model with constant IMF forcing: weimer_con.inp
- Weimer potential model with IMF data file: weimer_imf.inp
- Weimer potential model with IMF+GPI data files: weimer_imf+gpi.inp
- Default double-resolution run:
- Example “storm runs”:
- December, 2006 “AGU” storm run: dec2006.inp
Following is a table of valid TIEGCM 1.94 namelist parameters, and their descriptions. Follow the parameter name links to explanations below.
| Parameter Name | Data Type and Default | Description |
|---|---|---|
| AURORA | integer: 1 | 0/1 flag for auroral parameterization |
| BXIMF or BXIMF_TIME | real or real array | X-component of the IMF |
| BYIMF or BYIMF_TIME | real or real array | Y-component of the IMF |
| BZIMF or BZIMF_TIME | real or real array | Z-component of the IMF |
| CALENDAR_ADVANCE | real: 1 | 0/1 switch to advance calendar time |
| COLFAC | real: 1.5 | O-O+ collision factor |
| CTPOTEN | real: | Cross-Tail Potential |
| CTPOTEN_TIME | real: [none] | Time-dependent Cross-Tail Potential |
| F107 or F107_TIME | real or real array | Daily F10.7 cm solar flux |
| F107A or F107A_TIME | real or real array | 81-day average F10.7 cm solar flux |
| GPI_NCFILE | string: [none] | Geophysical Indices (Kp) data file |
| GSWM data files | string: [none] | GSWM Model tidal lbc data files |
| HIST | integer(3) | Primary history write frequency |
| IMF_NCFILE | string: [none] | IMF OMNI data files |
| KP or KP_TIME | real or real array | Kp for calc of hpower and ctpoten |
| LABEL | string: | Arbitrary string identifying the run |
| MXHIST_PRIM | integer: 10 | Max histories on primary file |
| MXHIST_SECH | integer: 24 | Max histories on secondary file |
| OUTPUT | string array | Primary history output file(s) |
| POTENTIAL_MODEL | string: [HEELIS] | High-latitude Potential Model |
| POWER or POWER_TIME | real or real array | Hemispheric Power (GW) |
| SECHIST | integer(3) | Secondary history write frequency |
| SECFLDS | string array | Fields to be stored on secondary histories |
| SECOUT | string array | Secondary history output file(s) |
| SOURCE | string: [none] | Primary SOURCE (start-up) file |
| SOURCE_START | integer(3) | Model time to start on SOURCE file |
| START | integer(3) | Model start time (day,hour,minute) |
| START_YEAR | integer: 2002 | Starting year |
| START_DAY | integer: 80 | Starting day of year |
| STEP | integer: [none] | Model time step (seconds) |
| STOP | integer(3) | Model stop time (day,hour,minute) |
| SWDEN or SWDEN_TIME | real or real array | Solar Wind Density |
| SWVEL or SWVEL_TIME | real or real array | Solar Wind Velocity |
| TIDE | real(10) | Amplitudes and phases of semi-diurnal tide |
| TIDE2 | real(2) | Amplitudes and phases of diurnal tide |
If AURORA > 0 then the auroral parameterization (aurora.F) is called by dynamics (dynamics.F), otherwise it is not called.
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.
Data type: real or real array
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.
Data type: real or real array
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.
Data type: real or real array
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.
O-O+ Collision Frequency, alias the “Burnside Factor”. Default is 1.5, but there have been recommendations for 1.3. COLFAC is used in lamdas.F and oplus.F.
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.
Data type: real or real array
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.
Data type: real or real array
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).
Datatype: string
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.
Datatype: string
GSWM files for the 5-degree TIEGCM:
GSWM_MI_DI_NCFILE = '$TGCMDATA/gswm_diurn_5.0d_99km.nc'
GSWM_MI_SDI_NCFILE = '$TGCMDATA/gswm_semi_5.0d_99km.nc'
GSWM_NMI_DI_NCFILE = '$TGCMDATA/gswm_nonmig_diurn_5.0d_99km.nc'
GSWM_NMI_SDI_NCFILE = '$TGCMDATA/gswm_nonmig_semi_5.0d_99km.nc'
GSWM files for 2.5-degree TIEGCM:
GSWM_MI_DI_NCFILE = '$TGCMDATA/gswm_diurn_2.5d_99km.nc'
GSWM_MI_SDI_NCFILE = '$TGCMDATA/gswm_semi_2.5d_99km.nc'
GSWM_NMI_DI_NCFILE = '$TGCMDATA/gswm_nonmig_diurn_2.5d_99km.nc'
GSWM_NMI_SDI_NCFILE = '$TGCMDATA/gswm_nonmig_semi_2.5d_99km.nc'
Primary history write frequency, specified as a model time (day,hour,minute). HIST time must divide evenly into STOP minus START times.
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.
Data type: real or real array
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):
if (kp <=7.) hp_from_kp = 16.82*exp(0.32*kp)-4.86
if (kp > 7.) hp_from_kp = 153.13 + (kp-7.)/(9.-7.)*(300.-153.13)
Empirical formula used to calculate CTPOTEN from KP (see function ctpoten_from_kp in util.F):
ctpoten_from_kp = 15.+15.*kp + 0.8*kp**2
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.
Ascii data is obtained from NASA/OMNI (Combined 1AU IP Data), and an equivalent netCDF data file is written for import to the model.
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).
Examples:
OUTPUT = 'p_myoutput_001.nc'
OUTPUT = 'myoutput.p001.nc','myoutput.p002.nc','myoutput.p003.nc'
OUTPUT = 'myoutput_p001.nc','to','myoutput_p020.nc','by','1'
The high-latitude potential model used to calculate electric potential above a specified latitude. This string can have one of two values:
‘HEELIS’ is the Rod Heelis model (heelis.F). ‘WEIMER’ is the Dan Weimer 2005 model (wei05sc.F).
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.
Data type: one or more character strings
Examples:
;
; Example for tiegcm1.9: all fields are "prognostic" except EEX,EEY,EEZ,
; which are saved by addfld calls in sub ionvel (ionvel.F).
;
SECFLDS = 'TN','UN','VN','O1','NO','N4S','NE','TE','TI',
'O2','O2P','OMEGA','POTEN','EEX','EEY','EEZ'
;
; This example lists all diagnostic fields available via the diags module
; (it is not necessary to call addfld in the code to obtain these fields)
;
SECFLDS = 'CO2_COOL','NO_COOL','DEN','HEATING','QJOULE',
'SIGMA_PED','SIGMA_HAL','TEC','UI_ExB','VI_ExB','WI_ExB',
'LAMDA_PED','LAMDA_HAL','HMF2','NMF2','SCHT','MU_M'
Secondary history write frequency, specified as a model time (day,hour,minute). SECHIST time must divide evenly into SECSTOP minus SECSTART times.
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).
Examples:
SECOUT = 's_myoutput_001.nc'
SECOUT = 'myoutput.s001.nc','myoutput.s002.nc','myoutput.s003.nc'
SECOUT = 'myoutput_s001.nc','to','myoutput_s020.nc','by','1'
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.
Data type: 3 integers Valid range: 0-365 for day, 0-23 for hour, 0-59 for minute.
Calendar starting day.
Starting year for the run.
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.
Model stop time for the run. Model time is specified as a 3-integer triplet: day,hour,minute.
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.
Data type: real or real array
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.
Data type: real or real array
Hough mode amplitudes and phases of the semi-diurnal tide. If GSWM tidal perturbations are specified, TIDE should be set to 0.
Data type: 10 reals
Example:
TIDE= 1.9300E+04, 1.5000E+04, 2.3100E+04, 0.7700E+04, 0.1660E+04,
-2.600E+00, 0.000E+00, -3.300E+00, 4.2000E+00, 5.0000E+00
Hough mode amplitudes and phases of the diurnal tide. If GSWM tidal perturbations are specified, TIDE2 should be set to 0.
Data type: 2 floats
Example:
TIDE2 = 4.1E+4, -3.7