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 exclamation mark ‘!’ will be treated as a comment (see example files).
Example Namelist Input Files:
Following is a table of valid TIEGCM 2.0 namelist parameters, and their descriptions. Follow the parameter name links to explanations below.
| Parameter Name | Data Type and Default | Description |
|---|---|---|
| AMIENH,AMIESH | string: [none] | Optional AMIE data files |
| AMIE_IBKG | integer: 0 | Flag for how to read AMIE data |
| AURORA | integer: 1 | 0/1 flag for auroral parameterization |
| BGRDDATA_NCFILE | string: [none] | Data file for background lower boundary |
| 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 |
| CTMT_NCFILE | string: [none] | Lower boundary data file T,U,V,Z |
| CTPOTEN | real: | Cross-Tail Potential |
| CTPOTEN_TIME | real: [none] | Time-dependent Cross-Tail Potential |
| CURRENT_KQ | integer: 0 | Height-integrated Current Density |
| CURRENT_PG | integer: 1 | Current due to Plasma Pressure Gradient |
| CALC_HELIUM | integer: 1 | 0/1 switch for calculation of Helium |
| DYNAMO | integer: 1 | 0/1 switch for electro-dynamo |
| EDDY_DIF | integer: 0 | 0/1 switch for DOY-dependent or constant eddy diffusion |
| ENFORCE_OPFLOOR | integer: 1 | Gaussian shaped floor for O+ |
| 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 |
| JOULEFAC | real: 1.5 | Joule Heating Factor |
| 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 |
| OPDIFFCAP | real: 0 [no cap] | Impose maximum O+ diffusion |
| 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) |
| SABER_NCFILE | string: [none] | SABER data file (T,Z lower boundary condition) |
| SECSTART | integer(3) | Secondary history start time (day,hour,minute) |
| SECSTOP | integer(3) | Secondary history stop time (day,hour,minute) |
| SECHIST | integer(3) | Secondary history write frequency (day,hour,minute) |
| 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 (rarely used) |
| TIDE2 | real(2) | Amplitudes and phases of diurnal tide (rarely used) |
| TIDI_NCFILE | string: [none] | TIDI data file (U,V lower boundary condition) |
Data files containing output from the AMIE model, to be imported to the tiegcm. AMIENH contains northern hemisphere data, AMIESH contains southern hemisphere data. Contact Gang Lu (ganglu@ucar.edu) for more information.
Example:
- AMIENH = ‘$TGCMDATA/amie_apr01_10_2010_nh_ssusi.nc’
- AMIESH = ‘$TGCMDATA/amie_apr01_10_2010_sh_ssusi.nc’
See also:
Integer flag 0, 1, or 2 for reading real, first, or 24-hour averaged AMIE data
See also:
If AURORA > 0 then the auroral parameterization (aurora.F) is called by dynamics (dynamics.F), otherwise it is not called.
Data file providing zonal mean climatology of T, U, V using MSIS and HWM empirical models, or UARS data. If no input file is specified, a flat lower boundary (u=v=0, Tn=181 K, z=96.4 km) is employed by default. Other zonal mean climatologies can be used by generating and specifying a different file.
Data type: string Default: [none]
Example:
- BGRDDATA_NCFILE = ‘$TGCMDATA/bgndlbc_hwm_msis.nc’
- BGRDDATA_NCFILE = ‘$TGCMDATA/bgndlbc_saber_hrdi.nc’
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.
Tidal perturbations for lower boundary of Z, T, U, V. See this reference:
Ref. Oberheide, J., J. M. Forbes, X. Zhang, and S. L. Bruinsma
Climatology of upward propagating diurnal and semidiurnal tides in the thermosphere
J. Geophys. Res., 116, A11306, doi:10.1029/2011JA016784, 2011.
Note: This is mutually incompatible with GSWM_NCFILE
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.
If CURRENT_KQ=1, then height-integrated current density of current sheet, and upward current density at the top of the ionosphere is calculated (default=0) (ignored if DYNAMO=0) (see current.F90 to save JQR, JE13D, JE23D, KQPHI, KQLAM)
If EDDY_DIF=1, then day-of-year dependent eddy diffusion will be calculated, otherwise eddy diffusion will be set to pressure-dependent constants. See cons.F.
A double-Gaussian shaped floor (in latitude and altitude) is applied to O+ at low-to-mid latitudes in the F-region in order to keep the model stable when the ionosphere gets very low in density.
If set to 1 (the default), the floor is implemented in oplus.F as follows:
do k=lev0,lev1-1
opfloor = opmin*exp(-(glat(lat)/90.0)**2/0.3)*
| exp(-((zpmid(k)-4.25)/zpmid(nlevp1))**2/0.1)
do i=lon0,lon1
if (opout(k,i,lat) < opfloor) opout(k,i,lat) = opfloor
enddo
enddo
If CURRENT_PG=1, current due to plasma pressure gradient and gravity is calculated and included as a forcing term in the dynamo equation (default=1) (ignored if DYNAMO=0)
If calc_helium=1, helium is calculated as a major composition species. If calc_helium=0, helium is zeroed out. If calc_helium=1 and the source history does not have helium, then helium will be initialized globally to 0.1154E-5.
Integer switch for electro-dynamo. If DYNAMO=0, then dynamo (pdynamo.F) will not be called, and ion drift velocities will be zero. If DYNAMO=1, then dynamo will be called, and ion drift velocities will be calculated.
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 2.0, 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
SABER data file for lower boundary conditions of T and Z (neutral temperature and geopotential height).
TIDI data file for lower boundary conditions of U and V (zonal and meridional neutral wind).
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.
Notes on creation of IMF OMNI data files:
Joule heating factor. This factor is multiplied by the joule heating calculation (see subroutine qjoule_tn in qjoule.F).
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.
Optional cap on ambipolar diffusion coefficient for O+. This can improve model stability in the topside F-region, but it is only recommended as a last resort since it will change model results. This is a new namelist parameter for tiegcm2.0. The default is 0., i.e., no cap. If this is non-zero (provided by the user), then it is implemented in subroutine rrk of src/oplus.F.
Examples:
Tests have been made with these values:
* OPDIFFCAP = 1.5e8
* OPDIFFCAP = 3.0e8
* OPDIFFCAP = 6.0e8
* OPDIFFCAP = 8.0e8
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).
Note
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.
Data type: one or more character strings
Examples:
!
! Example list of fields to be written to secondary histories:
!
SECFLDS = 'TN' 'UN' 'VN' 'O2' 'O1' 'N2' 'NO' 'N4S' 'HE' 'NE' 'TE' 'TI'
'TEC' 'O2P' 'OP' 'OMEGA' 'POTEN' 'UI_ExB' 'VI_ExB' 'WI_ExB'
'DEN' 'QJOULE' 'Z' 'ZG'
!
! 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','QJOULE_INTEG',
'SIGMA_PED','SIGMA_HAL','TEC','UI_ExB','VI_ExB','WI_ExB',
'LAMDA_PED','LAMDA_HAL','HMF2','NMF2','SCHT','MU_M','O_N2','WN',
'BX','BY','BZ','BMAG','EX','EY','EZ','ED1','ED2','PHIM2D','N2',
'CUSP','DRIZZLE','ALFA','NFLUX','EFLUX'
Secondary history start time, specified as a model time (day,hour,minute).
Secondary history stop time, specified as a model time (day,hour,minute).
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 60 seconds for 5-degree resolution, 30 seconds for 2.5-degree resolution. During periods of quiet solar activity, the model can often be run at twice these times. 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 10 seconds may be necessary for 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 (#/cm-3). 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 (Km/s). 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.
Note
TIDE and TIDE2 should be specified only for experiments where amplitude and phases of the tides must be used. Normally, GSWM tides are specified instead of TIDE,TIDE2.
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.
Note
TIDE and TIDE2 should be specified only for experiments where amplitude and phases of the tides must be used. Normally, GSWM tides are specified instead of TIDE,TIDE2.
Data type: 2 floats
Example:
TIDE2 = 4.1E+4, -3.7