Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 65

GITM User Manual

Version 2.1

A.J. Ridley, A.G. Burrell

March 9, 2014

Contents

1 Introduction to GITM 5

1.1 SourceTerms ............................................... 5

1.2 GhostCells ................................................ 5

1.3 CodeOutline ............................................... 6

2 Getting Started 15

2.1 Extracting the code from a tar ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.2 CheckingoutthecodewithCVS..................................... 15

2.3 ConﬁguringandMakingGITM...................................... 16

2.4 RunningtheCode............................................. 16

2.5 PostProcessing .............................................. 17

2.6 TheCodeWon’tCompile!!........................................ 18

3 Inputs 21

3.1 PrincipleInput .............................................. 21

3.1.1 RequiredInputs.......................................... 21

3.1.2 TemporalBoundaries....................................... 22

3.1.3 DeﬁningOutputs......................................... 23

3.1.4 RestartInput ........................................... 25

3.1.5 NumericalOptions........................................ 25

3.1.6 DataAssimilation ........................................ 26

3.1.7 Solar and Geomagnetic Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.1.8 PhysicalProcesses ........................................ 29

3.1.9 GeographicBoundaries...................................... 35

3.2 SettingtheGrid.............................................. 36

3.2.1 Running 3D Over the Whole Globe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.2.2 Running 3D Over the Part of the Globe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.2.3 Runningin1D .......................................... 38

3.3 AuxiliaryInputFiles ........................................... 38

3.3.1 IMFandSolarWind ....................................... 39

3.3.2 HemisphericPower........................................ 40

3.3.3 SolarIrradiance.......................................... 41

3.3.4 Satellites ............................................. 42

4 Outputs 43

4.1 IDL .................................................... 45

4.2 Python................................................... 47

Bibliography 63

4 CONTENTS

Chapter 1

Introduction to GITM

The Global Ionosphere Thermosphere Model (GITM) is a 3D model of the upper atmosphere. It runs for Earth, Mars

and Titan. A version is being worked on for Jupiter. GITM solves for the coupled continuity, momentum and energy

equations of the neutrals and ions. For the ions, the time rate of change of the velocity is ignored, so the steady-state

ion ﬂow velocity is solved for. The ion temperature is a mixture of the electron and neutral temperature.

The neutrals are solved for using the Navier Stokes Equations. The continuity equation is solved for for each major

species. One of the problems with GITM that needs to be rectiﬁed is that there are no real tracer species, so a species

is either solved for completely or is not at all. These species can still be included in the chemistry calculation. There is

only one horizontal velocity that is computed, while there are vertical velocities for each of the major species. A bulk

vertical velocity is calculated as a mass weighted average. The temperature is a bulk temperature.

1.1 Source Terms

Chemistry is the only real source term for the continuity equation. Typically, diffusion is added in the continuity

equation to allow for eddy diffusion, but this is not the case in GITM. What happens is that the vertical velocities are

solved for, then a friction term is applied to that the velocities stay very close together in the eddy diffusion part of the

code. This way, the velocities can’t differ too much from each other. Diffusion is not needed, then.

For the horizontal momentum equation, there are the following sources: (1) ion drag; (2) viscosity; and (3) gravity

wave acceleration. For the vertical velocity, the source terms are ion drag and friction between the different neutral

species.

For the neutral temperature, the following source terms are included: (1) radiative cooling; (2) EUV heating; (3)

auroral heating; (4) Joule heating; (5) conduction; and (6) chemical heating. The biggest pain for the temperature

equation is the use of a normalized temperature. This means that the temperature variable in GITM does not

contain the actual temperature, it contains the temperature multiplies by Boltzmann’s Constant divided by the mean

mass. This turns out to be a factor that is very similar to the speciﬁc heat, or roughly or order 1000. In order to get the

actual temperature, the variable has to be multiplied by temp unit.

1.2 Ghost Cells

GITM is a parallel code. It uses a 2D domain decomposition, with the altitude domain being the only thing that is not

broken up. Blocks of latitude and longitude are used. These blocks are then distributed among different processors.

In order to communicate between the processors, ghostcells are used. These are cells that essentially overlap with

the neighboring block. MPI (message passing interface) is then used to move information from one block to another,

ﬁlling in the ghostcells. The code then loops from 1-N, where the ﬂux is calculated at the boundaries from the 0-1

boundary to the N-N+1 boundary. A second order scheme is used to calculate the ﬂuxes, along with a ﬂux limiter.

Therefore, two ghost cells are needed.

6 CHAPTER 1. INTRODUCTION TO GITM

In the vertical direction, ghost cells are also used to set boundary conditions. The values in these cells are used to

calculate the ﬂuxes, just as described above. Different types of boundary conditions (constant values, constant ﬂuxes,

constant gradients, ﬂoating, zero ﬂuxes, etc) can be set by carefully choosing the right values in the ghost cells.

1.3 Code Outline

This is an outline of GITM. To produce this ﬁle, go into the src directory, and type:

cd ../src

./calling_sequence.pl > outline.tex

mv outline.tex ../srcDoc

cd ../srcDoc

main program in main.f90

•init mpi in ﬁle init mpi.f90

–MPI INIT

–MPI COMM RANK

–MPI COMM SIZE

•start timing in ﬁle timing.f90

•delete stop in ﬁle stop ﬁle.f90

–report in ﬁle library.f90

•init planet in ﬁle ModEarth.f90

–time int to real in ﬁle time routines.f90

•set defaults in ﬁle ModInputs.f90

–set strings in ﬁle ModInputs.f90

–time int to real in ﬁle time routines.f90

–set planet defaults in ﬁle Earth.f90

•read inputs in ﬁle read inputs.f90

–report in ﬁle library.f90

–stop gitm in ﬁle library.f90

–MPI Bcast

–stop gitm in ﬁle library.f90

–MPI Bcast

–stop gitm in ﬁle library.f90

•set inputs in ﬁle set inputs.f90

–report in ﬁle library.f90

–read in int in ﬁle set inputs.f90

1.3. CODE OUTLINE 7

–time int to real in ﬁle time routines.f90

–time real to int in ﬁle time routines.f90

–fix vernal time in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–time int to real in ﬁle time routines.f90

–read in time in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–time real to int in ﬁle time routines.f90

–read in real in ﬁle set inputs.f90

–IO set f107 single

–IO set f107a single

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–IO set hpi single

–read in real in ﬁle set inputs.f90

–IO set kp single

–read in real in ﬁle set inputs.f90

–IO set imf by single

8 CHAPTER 1. INTRODUCTION TO GITM

–IO set imf bz single

–IO set sw v single

–read in string in ﬁle set inputs.f90

–IO set inputs

–read MHDIMF Indices

–read in logical in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

1.3. CODE OUTLINE 9

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

10 CHAPTER 1. INTRODUCTION TO GITM

–read in logical in ﬁle set inputs.f90

–read in time in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in int in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read satellites in ﬁle satellites.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in logical in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–Set Euv in ﬁle calc euv.f90

–read in logical in ﬁle set inputs.f90

–read in real in ﬁle set inputs.f90

–read in string in ﬁle set inputs.f90

–IO set inputs

–read NGDC Indices

–read in string in ﬁle set inputs.f90

–IO set inputs

–read SWPC Indices

–read in string in ﬁle set inputs.f90

–IO set inputs

–read NOAAHPI Indices

–stop gitm in ﬁle library.f90

–time int to real in ﬁle time routines.f90

•initialize gitm in ﬁle initialize.f90

–init radcooling in ﬁle ModEarth.f90

1.3. CODE OUTLINE 11

–start timing in ﬁle timing.f90

–report in ﬁle library.f90

–time real to int in ﬁle time routines.f90

–fix vernal time in ﬁle set inputs.f90

–get f107

–get f107a

–init grid in ﬁle init grid.f90

–read inputs in ﬁle read inputs.f90

–set inputs in ﬁle set inputs.f90

–read restart in ﬁle restart.f90

–init msis in ﬁle init msis.Earth.f90

–set RrTempInd in ﬁle ModRates.Earth.f90

–init euv in ﬁle calc euv.f90

–init altitude in ﬁle init altitude.f90

–UAM gradient

–init heating efficiency in ﬁle Earth.f90

–init magheat in ﬁle ModEarth.f90

–init isochem in ﬁle Mars.f90

–init aerosol in ﬁle ModEarth.f90

–init isochem in ﬁle Mars.f90

–init msis in ﬁle init msis.Earth.f90

–get temperature in ﬁle init altitude.f90

–init iri in ﬁle init iri.Earth.f90

–read waccm tides in ﬁle tides.f90

–update waccm tides in ﬁle tides.f90

–read tides in ﬁle tides.f90

–update tides in ﬁle tides.f90

–init b0 in ﬁle init b0.f90

–init energy deposition in ﬁle init energy deposition.f90

–report in ﬁle library.f90

–SUBSOLR

–exchange messages sphere in ﬁle exchange messages sphere.f90

–calc pressure in ﬁle calc pressure.f90

–UA calc electrodynamics in ﬁle calc electrodynamics.f90

–calc eddy diffusion coefficient in ﬁle Earth.f90

–calc rates in ﬁle calc rates.Earth.f90

–calc viscosity in ﬁle calc rates.Earth.f90

–calc rates in ﬁle calc rates.Earth.f90

–end timing in ﬁle timing.f90

12 CHAPTER 1. INTRODUCTION TO GITM

–calc vtec in ﬁle calc tec.f90

–calc single vtec in ﬁle calc tec.f90

•write output in ﬁle write output.f90

–output in ﬁle output common.f90

–move satellites in ﬁle satellites.f90

–write restart in ﬁle restart.f90

–logfile in ﬁle logﬁle.f90

•report in ﬁle library.f90

•Loop Start

–calc pressure in ﬁle calc pressure.f90

∗report in ﬁle library.f90

–calc timestep vertical in ﬁle calc timestep.f90

∗report in ﬁle library.f90

∗MPI AllREDUCE

∗stop gitm in ﬁle library.f90

–calc timestep horizontal in ﬁle calc timestep.f90

∗report in ﬁle library.f90

∗MPI AllREDUCE

–advance in ﬁle advance.f90

∗report in ﬁle library.f90

∗start timing in ﬁle timing.f90

∗update tides in ﬁle tides.f90

∗update waccm tides in ﬁle tides.f90

∗advance vertical all in ﬁle advance.f90

∗add sources in ﬁle add sources.f90

∗advance horizontal all in ﬁle advance.f90

∗time real to int in ﬁle time routines.f90

∗get f107

∗stop gitm in ﬁle library.f90

∗get f107a

∗stop gitm in ﬁle library.f90

∗init msis in ﬁle init msis.Earth.f90

∗init iri in ﬁle init iri.Earth.f90

∗init b0 in ﬁle init b0.f90

∗end timing in ﬁle timing.f90

∗report in ﬁle library.f90

∗start timing in ﬁle timing.f90

∗calc rates in ﬁle calc rates.Earth.f90

∗calc viscosity in ﬁle calc rates.Earth.f90

∗advance vertical in ﬁle advance vertical.f90

∗end timing in ﬁle timing.f90

1.3. CODE OUTLINE 13

∗report in ﬁle library.f90

∗start timing in ﬁle timing.f90

∗exchange messages sphere in ﬁle exchange messages sphere.f90

∗calc rates in ﬁle calc rates.Earth.f90

∗calc physics in ﬁle calc physics.f90

∗advance horizontal in ﬁle advance horizontal.f90

∗calc physics in ﬁle calc physics.f90

∗calc rates in ﬁle calc rates.Earth.f90

∗advance horizontal in ﬁle advance horizontal.f90

∗exchange messages sphere in ﬁle exchange messages sphere.f90

∗end timing in ﬁle timing.f90

–check stop in ﬁle stop ﬁle.f90

∗report in ﬁle library.f90

∗start timing in ﬁle timing.f90

∗MPI AllREDUCE

∗check start in ﬁle stop ﬁle.f90

∗end timing in ﬁle timing.f90

–write output in ﬁle write output.f90

∗output in ﬁle output common.f90

∗move satellites in ﬁle satellites.f90

∗write restart in ﬁle restart.f90

∗logfile in ﬁle logﬁle.f90

•Loop End

•finalize gitm in ﬁle ﬁnalize.f90

–UA calc electrodynamics in ﬁle calc electrodynamics.f90

–output in ﬁle output common.f90

–write restart in ﬁle restart.f90

–end timing in ﬁle timing.f90

–report timing in ﬁle timing.f90

–UAM XFER destroy in ﬁle ModSphereInterface.f90

–UAM write error in ﬁle ModSphereInterface.f90

–stop gitm in ﬁle library.f90

–MPI FINALIZE

•stop gitm in ﬁle library.f90

–CON stop in ﬁle main.f90

–MPI abort

14 CHAPTER 1. INTRODUCTION TO GITM

Chapter 2

Getting Started

2.1 Extracting the code from a tar ﬁle

Create a new and empty directory, and open the tar ﬁle you received, e.g.:

mkdir Gitm

cd Gitm

mv ../gitm.tgz .

tar -xvzf gitm.tgz

2.2 Checking out the code with CVS

If CVS (Concurrent Versions System) is available on your computer and you have an account on the CVS server

machine herot.engin.umich.edu, you can use CVS to install the current or a particular version of the code. First of all

have the following environment variables:

setenv CVSROOT UserName@herot.engin.umich.edu:/CVS/FRAMEWORK

setenv CVS_RSH ssh

where UserName is your user name on herot. Here it is assumed that you use csh or tcsh. Also put these settings into

your .cshrc ﬁle so it is automatically executed at login. Alternatively, use

CVSROOT=UserName@herot.engin.umich.edu:/CVS/FRAMEWORK

export CVSROOT

CVS_RSH=ssh

export CVS_RSH

under sh, ksh and bash shells, and also put these commands into your .bashrc or .proﬁle ﬁle so it is automatically

executed at login.

Once the CVS environment variables are set, you can download the current (HEAD) version of the GITM distri-

bution with

cvs checkout GITM2

If you want a particular version, use

cvs checkout -r v2_0 GITM2

where v2 0 is the it tag associated with the version. To download bug ﬁxes or new features, the

16 CHAPTER 2. GETTING STARTED

cvs update

command can be used. See man cvs for more information.

A lot of times, you don’t really want the GITM2 directory to stay that name, since you might download a couple

different version (maybe one for development and one for runs). Therefore, typically you will:

mv GITM2 GITM2.Development

2.3 Conﬁguring and Making GITM

In order to compile GITM, you have to conﬁgure it ﬁrst. The conﬁgure script is inherited from the Space Weather

Modeling Framework. There are two primary reasons you need to do the conﬁgure: (1) put the right Makefile in

the right place, specifying the compiler and the version of MPI that you will use to link the code; (2) put the right MPI

header in the right place. It also does some things like hard-codes the path of the source code into the Makefile.

Currently the conﬁgure script is not capable of detecting the system and compilers available. Some examples for

commonly used set-ups are shown below. Make sure that your .cshrc or .bashrc ﬁle is set up to detect the appropriate

compilers before attempting to install GITM.

Installing on Nyx:

./Config.pl -install -compiler=ifortmpif90 -earth

Installing with an Intel compiler and OpenMPI (such as Pleiades):

./Config.pl -install -compiler=ifort -earth

Installing a computer with gfortran and OpenMPI:

./Config.pl -install -compiler=gfortran -earth

Installing on a computer with gfortran and not using MPI:

./Config.pl -install -compiler=gfortran -earth -nompi

Sometimes people have a hard time with the ModUtilities.F90 ﬁle. If you have errors with this ﬁle, try (for

example):

./Config.pl -uninstall

./Config.pl -install -compiler=gfortran -earth -noflush

Don’t forget, after conﬁguring the Makeﬁles, you must still compile the code!

make

make test_earth

make install

2.4 Running the Code

GITM requires a bunch of ﬁles to be in the right place in order to run. Therefore, it is best to use the makeﬁle to create

a run directory:

make rundir

mv run myrun

where myrun can be whatever you want. I will use myrun as an example. You can actually put this directory where

ever you want. On many systems (such as nyx), there is a nobackup scratch disk that you are supposed to use for

runs, instead of your home directory. If you need to ensure that your home directory doesn’t use too much space,

moving the run directory onto a disk with more free space can solve the problem:

2.5. POST PROCESSING 17

make rundir

mv run /nobackup/myaccount/gitm/myrun

ln -s /nobackup/myaccount/gitm/myrun .

This creates a shortcut to the myrun directory location on nobackup in your GITM working directory. It allows

you to treat the run directory as if it were a local directory, but it isn’t! It also means that you don’t have to compile

and install GITM on the scratch disk, where program storage may not be allowed.

Once you have created the run directory, you can run the default simulation, by:

cd myrun

mpirun -np 4 GITM.exe

Or, if your system uses Mpiexec:

cd myrun

mpiexec ./GITM.exe

This, hopefully should run GITM for Earth for 5 minutes. If it doesn’t work, then you might have mpi set up

incorrectly. The default is to allow you to run 4 blocks per processor, and the default UAM.in ﬁle is set up for 4

blocks, so you could try just running GITM without mpi, just to see if it works at all:

./GITM.exe

If that doesn’t work, then it probably didn’t compile correctly. Hopefully, it just worked!

2.5 Post Processing

GITM, by default, produces one ﬁle per block per output. If you are outputting often and you are running with many

blocks, you can produce a huge number of ﬁles. To post process all of these ﬁles, simply:

cd UA

./pGITM

This merges all of the ﬁles for one time period, for one ﬁle type into the same ﬁle. You can actually running

this while the code is running, since GITM doesn’t use old ﬁles, unless you are using the APPENDFILE option. As

implied by the option’s name, APPENDFILE opens an existing ﬁle and appends the most recent data to it. This feature

is typically used only when running a satellite track though GITM. More information on the APPENDFILE option is

located in Chapter 3 Section 3.1.3.

If you are NOT using satellites and NOT using APPENDFILE, then you are free and clear to use pGITM as often

as you want during a run. To avoid deleting a ﬁle that GITM is currently writing to, it is recommended that pGITM be

run as part of a script in which there is a ﬁve minute pause between executions.

Another useful script, when running GITM on another system, is given in the block below. It occasionally executes

an rsync between the computer that you run GITM on and your home computer. This allows you to bring over and

evaluate the output ﬁles as they become available. To do this, execute pGITM at a set cadence (60 seconds in the

example) while GITM is running and then rsync the remote and home directories (excluding all unprocessed ﬁles).

Finally, remove the processed and rsynced ﬁles to prevent the remote directory from ﬁlling up. Be sure to replace

yourname@home.computer with your user and computer names! This is a very simple, but very useful script.

#!/bin/csh

rm -f stop

set LOC=$1

if (-f remoteloc) set LOC=‘cat remoteloc‘

18 CHAPTER 2. GETTING STARTED

while (!(-f stop))

rsync -vrae ssh log.*UAM.*imf*yourname@home.computer:$LOC

cd UA ; ./pGITM ; rsync --exclude ’*.[bsh][0123ae][0123456789at]*’ -vrae ssh d

ata yourname@home.computer:$LOC ; cd ..

sleep 60

end

2.6 The Code Won’t Compile!!

I’m sorry. I tried to make this work on many different platforms, but sometimes machines are very speciﬁc, and it just

doesn’t work out of the box. Here are some ideas on how to quickly get this thing compiling.

Can’t ﬁnd the right Makeﬁle.whatever

If make does not work, then there is probably a problem with not ﬁnding the FORTRAN 90 compiler. The platform

and machine speciﬁc Makeﬁles are in srcMake. If you type:

uname

ls srcMake

If you don’t see a ﬁle named something like Makeﬁle.uname (where uname is the output of the uname command),

then you will have to build a proper general Makeﬁle.

You will need a little a little information about your computer, like what the mpif90 compiler is called and where

it is located. Take a look at srcMake/Makeﬁle.Linux, and try to ﬁgure out what all of the ﬂags are for your system.

Then create a srcMake/Makeﬁle.uname with the correct information in it.

The compiler doesn’t recognize ﬂag -x

You have an operating system that is recognized, but probably a different compiler. In the srcMake/Makeﬁle.uname

ﬁle (where uname is the output of the uname command), there is a line:

OSFLAGS = -w -dusty

You need to change this line to something more appropriate for your compiler. Try deleting the ﬂags and compile.

If that doesn’t work, you will have to check the man pages of your compiler.

src/ModHwm.90 doesn’t compile

Certain versions of gfortran (4.6 and later) may give the following error:

src/ModHwm.f90:168.22:

call HWMupdate(input,last,gfs,gfl,gfm,gvbar,gwbar,gbz,gbm,gzwght,glev,u

Error: Dummy argument ’ebz’ of procedure ’hwmupdate’ at (1) has an attribute

that requires an explicit interface for this procedure

src/ModHwm.f90:168.22:

call HWMupdate(input,last,gfs,gfl,gfm,gvbar,gwbar,gbz,gbm,gzwght,glev,u

Error: Dummy argument ’ebz’ of procedure ’hwmupdate’ at (1) has an attribute

that requires an explicit interface for this procedure

2.6. THE CODE WON’T COMPILE!! 19

This is caused by the inputs in HWM. The latest incarnations of gfortran don’t allow optional inputs that are not

declared. More information about this can be found at:

http://cosmocoffee.info/viewtopic.php?p=5136

A solution to this problem is currently being sought.

20 CHAPTER 2. GETTING STARTED

Chapter 3

Inputs

3.1 Principle Input

UAM.in contains the majority of the variables that can be changed in a GITM run. Very few of these input options

are required as input, all other options will default to values speciﬁed by the ModInputs.f90 subroutine, which can

be found in the src directory. Example UAM.in ﬁles for various types of runs are made available in the srcData

directory.

This input ﬁle can be altered at will without the need to recompile the code either “by hand” or using a script

such as makerun.pl. This script, which is located on harot.engin.umich.edu:/bigdisk1/bin, takes

command line input to create a UAM.in ﬁle and any desired auxiliary ﬁles, discussed in more detail in section 3.3,

using locally stored data.

The following sections present the GITM input options grouped by type. This is not the order you will ﬁnd

them in a typical UAM.in ﬁle or the order you will ﬁnd the input processed in ModInputs.f90. This reinforces

the ﬂexibility of the input ﬁle, which doesn’t care what order the input options are speciﬁed with one exception.

The starting and ending times (discussed in section 3.1.1) must be deﬁned before any solar or geomagnetic indices

(discussed in section 3.1.7). It is probably a good practice to begin any UAM.in ﬁle either with the output options

(discussed in section 3.1.3) or the starting and ending times.

3.1.1 Required Inputs

The only inputs that must be speciﬁed are the starting and ending times. These times are speciﬁed using universal time

blocks that specify the date (A.D.) and time of day. Remember, these two blocks must be speciﬁed before any of the

solar or geomagnetic index blocks, outlined in section 3.1.7.

TIMESTART

This input block sets the starting time of the simulation. Although the input time can be deﬁned down to the second,

construction scripts will ignore temporal units smaller than a day since a lead time of a day is typically desired for any

model run. Shorter runs should only used to test the model compilation.

GITM can be set to restart after pausing. This has no effect on TIMESTART, these values should always contain

the real starting time, not the restart time.

#TIMESTART

(integer) year

(integer) month

(integer) day

(integer) hour

22 CHAPTER 3. INPUTS

(integer) minute

(integer) second

TIMEEND

This input block sets the ending time of the simulation. As mentioned above, GITM runs typically last a minimum

of two days (with one day as start-up to allow the processes to settle into equilibrium) and so the hour, minute, and

second options are commonly ignored.

#TIMEEND

(integer) year

(integer) month

(integer) day

(integer) hour

(integer) minute

(integer) second

END

The inclusion of this keyword will cause GITM to stop reading the UAM.in ﬁle. This can allow one to save typical

input options not used in one particular run for another run by moving them after this key.

#END

3.1.2 Temporal Boundaries

The input options described here are optional and used to set the temporal boundaries in GITM, including the process-

ing times.

PAUSETIME

This input option sets a time for the code to pause. There is no good reason to use this option.

#PAUSETIME

(integer) year

(integer) month

(integer) day

(integer) hour

(integer) minute

(integer) second

CPUTIMEMAX

This sets the maximum CPU time that the code should run before it starts to write a restart ﬁle and end the simulation.

It is very useful on systems that have a queueing system and has limited time runs. Typically, set it for a couple of

minutes short of the maximum wall clock, since it needs some time to write the restart ﬁles.

#CPUTIMEMAX

(real) CPUTimeMax

3.1. PRINCIPLE INPUT 23

CFL

The CFL option deﬁnes how large a time step GITM will take. This is set as a fraction of the maximum time step, so

1.0 is the maximum value, while 0.75 is a typical value. If instabilities form during a model run, lowering this option

is a good ﬁrst step to take.

#CFL

(real) cfl

3.1.3 Deﬁning Outputs

The input option blocks described here are used to specify the level and type of verboseness.

LOGFILE

Log ﬁles are very important and the LOGFILE input option allows the user to control how much information the

GITM logﬁle will contain. This logﬁle is output into the UA/data/ directory in a ﬁle following a naming convention

like log*.dat. Although you can output the log ﬁle at whatever frequency you would like, setting the time-step to

some very small value will allow GITM to produce a log output every iteration, which is a good thing. DtLogFile

speciﬁes this time-step in seconds.

#LOGFILE

(real) DtLogFile

DEBUG

This will set the level of GITM’s verboseness. Set the iDebugLevel to 0 for minimal output and to 10 to retrieve

everything. You can also limit output to a speciﬁc processor using iDebugProc. The processors are named PE x, where

PE indicates that you are tagging a processor and x is the zero offset integer indicating the processor number. So “PE

0” would indicate that output from the ﬁrst processor is desired.

If you set the iDebugLevel to 0 (the default), you can set the debug report time step using DtReport. This time step

is given in seconds. The ﬁnal keyword in this input option, UseBarriers, forces the different nodes running the GITM

code to sync up with each other frequently when employed.

#DEBUG

(integer) iDebugLevel

(integer) iDebugProc

(real) DtReport

(logical) UseBarriers

SATELLITES

To improve model-data studies, GITM can output model results along the satellite paths. Any number of satellites

may be ﬂown through a GITM simulation. Output from the satellite paths is provided at the speciﬁed universal time,

geographic latitude and longitude. Instead of conﬁning the model output to the satellite altitude, simulated output is

provided over the entire GITM altitude range. If RCMR is being run, the validity of the satellite index speciﬁed in that

input block will be tested here.

#SATELLITES

(integer) nSats

(string) SatFile(n)

(real) DtPlot(n)

24 CHAPTER 3. INPUTS

To ﬂy several satellites through GITM, the user must set nSats, SatFile(n), and DtPlot(n) for each satellite. nSats

speciﬁes the number of satellites, SatFile(n) gives the name of the satellite ﬂight path ﬁle (discussed in more detail in

section 3.3.4), and DtPlot(n) speciﬁes the time-step for the GITM satellite output in seconds. The following verbatim

block shows the arrangement for two satellites.

#SATELLITES

2 nSats

grace.sat SatFile1

1 DtPlot1

champ.sat SatFile2

1 DtPlot2

APPENDFILES

GITM defaults to creating many output ﬁles for satellite runs, but this option tells GITM to create just one single ﬁle

per satellite. This makes GITM output signiﬁcantly less ﬁles. In the future, this option may be available for other

types of output as well.

#APPENDFILES

(logical) DoAppendFiles

SAVEPLOT

This input option speciﬁes the types of ﬁles GITM will output. The most common type is 3DALL, which outputs all

primary state variables. Types (speciﬁed in OutputType) include : 3DALL, 3DMAG, 3DNEU, 3DION, 3DTHM,

3DCHM, 3DUSR, 3DGLO, 2DGEL, 2DMEL, 2DUSR, 2DTEC, 1DALL, 1DGLO, 1DTHM, 1DNEW, 1DCHM,

1DCMS, and 1DUSR. These ﬁle types specify the number of dimensions (3D, 2D, 1D) in which GITM may be

run and the different primary state variables that are included in the output (NEU stands for neutrals, ION stands for

ionosphere, MAG stands for magnetic ﬁeld, THM stands for thermosphere, CHM stands for chemistry, USR stands

for BLAH, GLO stands for day glow, TEC stands for total electron content, GEL stands for global electric BLAH,

and MEL stands for BLAH). Any number of output ﬁles greater than zero may be produced, but nOutputTypes must

be used to specify the number of types to be created and an OutputType and DtPlot must be provided for each output

just as was done for multiple satellites. DtRestart and DtPlot specify the time-step in seconds for producing restart and

output ﬁles, respectively. If no output ﬁles are speciﬁed, GITM will crash when attempting to ﬁnalize all procedures.

#SAVEPLOT

(real) DtRestart

(integer) nOutputTypes

(string) OutputType

(real) DtPlot

CCMCFILENAME

The Community Coordinated Modeling Center (CCMC), located at ccmc.gsfc.nasa.gov, provides access to

space research models to the scientiﬁc community. GITM provides the option to have the GITM output ﬁles use the

CCMC naming convention: TYPE GITM YYYY-MM-DDThh-mm-ss.bin, where TYPE is one of the GITM output

types such as 3DALL described in the previous subsection.

#CCMCFILENAME

(logical) Use CCMC naming convention

3.1. PRINCIPLE INPUT 25

PLOTTIMECHANGE

This option allows you to change the output cadence of the ﬁles for a limited time. If you have a short event, such as

a solar ﬂare or an eclipse, this options lets you output much more often during the event than during the quiet periods

preceding and succeeding the event.

#PLOTTIMECHANGE

(yyyy mm dd hh mm ss ms) PlotTimeChangeStart

(yyyy mm dd hh mm ss ms) PlotTimeChangeEnd

3.1.4 Restart Input

This section deals with options typically only speciﬁed in a restart header. These options can be used in the principle

input ﬁle but have very little use if a run does not need to be restarted from a speciﬁed point in a previous run. Apart

from setting the ﬂag in the UAM.in ﬁle, several steps must be taken. First, you need to put the restart ﬁles that GITM

writes into the correct location. These ﬁles are located in subdirectories (named restartIN and restartOUT)

within the run/UA directory. To preserve the past GITM restart information and enable a new start from the end of

the previous run, prepare these directories as directed below. This code snippit can also be added to a PBS job ﬁle, but

should only be performed after GITM has ﬁnished executing and if the GITM.DONE ﬁle exists.

cd UA

mv restartOUT restartOUT.runname.XX

mkdir restartOUT

./pGITM

rm -f restartIN; ln -s restartOUT.runname.XX

cd ..

RESTART

Setting this input option to T (true) allows the model to restart from a previous run.

#RESTART

(logical) DoRestart

ISTEP

This input should not be speciﬁed by the user, but is used by the computer to restart after a run has been interrupted. It

gives the iteration number that the model run stopped at.

#ISTEP

(integer) iStep

TSIMULATION

This options sets the offset from the starting time (speciﬁed using TIMESTART) to the current simulation time in

seconds. Like ISTEP, this option should really only be used by the computer to restart after a run has been interrupted.

#TSIMULATION

(real) tsimulation

3.1.5 Numerical Options

The optional inputs in this section allow the user to modify how GITM handles computational scenarios.

26 CHAPTER 3. INPUTS

LIMITER

The ﬂux limiter speciﬁes the balance between the model’s ability to run robustly and provide realistic gradients. A

realistic atmosphere will occasionally experience sharp changes in characteristics such as electron density. When

GITM attempts to model these variations, the high resolution of the temporal and spatial grids allows the numerical

schemes that solve the equations of state to oscillate about the actual value. One solution to the problem is to err on the

side of robustness and require more gradual changes. This can be done by setting TypeLimiter to minmod or setting

TypeLimiter to beta and BetaLimiter to 1.0 (both of these options are the same and the default). The other solution is to

allow sharp changes to occur, realizing that the model will likely overshoot and undershoot and that if an atmospheric

characteristic shoots to an unrealistic value the model may crash.

Although there are many different limiter types (see the wikipedia article for a decent introduction:

http://en.wikipedia.org/wiki/Flux limiter) GITM uses the Osher function [Chakravarthy and Os-

her, 1983], given below in equation 3.1.

φos(r) = max[0, min(r, β)],(1 ≤β≤2); lim

r→∞ φos(r) = β(3.1)

In this function, βis speciﬁed by BetaLimiter, and so defaults to the minmod ﬂux limiter function when β=

1[Roe, 1986] and to the monotonized central (MC) ﬂux limiter function when β= 2 [?].

#LIMITER

(string) TypeLimiter

(real) BetaLimiter

3.1.6 Data Assimilation

This section contains the input options that allow GITM to perform data assimilation.

RCMR

RCMR stands for Retrospective Cost Model Reference, and is a Retrospective Cost Adaptive Control (RCAC) method

of data assimilation. RCMR is useful when dealing with nonlinear systems [Ali et al., 2012]. To use this system,

Markov parameters need to be set. These parameters will vary based on the type and number of data sources being

assimilated and the driver being estimated. Markov parameters for the assimilation of a single satellite providing

neutral density to drive the F10.7are currently available. Other parameters are currently being developed.

The use of RCMR changes how the possible driving parameters and satellite data are treated within GITM. Because

of this, the RCMR block should be included before the SATELLITE, F107, and PHOTOELECTRON block in the

UAM.in ﬁle. The initial guess of the parameter being driven should not be close to the ﬁnal value, as a perturbed

location allows the assimilation to better account for model error. Choosing a value within realistic physical boundaries

but away from an intuitive guess as to the actual value is the best way to chose the initial guess.

#RCMR

(string) Input data type (RHO/VTEC)

(string) Output variable to drive (F107/PHOTOELECTRON)

(real) Initial output estimate

(integer) Number of satellites to include in data assimilation

(integer) Index number of satellite to assimilate

DART

DART stands for Data Assimilation Research Testbed, and is a community facility that provides software tools for data

assimilation [Anderson et al., 2009]. Within the space physics community, DART has been coupled with TIE-GCM

and GITM. More information about using DART with GITM is available in the DART manual in the GITM2/srcDoc

directory.

3.1. PRINCIPLE INPUT 27

#DART

(integer) Method to use DART

3.1.7 Solar and Geomagnetic Indices

This section contains the input options that speciﬁes the level of solar and geomagnetic activity. Recall that these

input options must be speciﬁed after the starting and ending times (refer to section 3.1.1) are deﬁned. Also, note that

several of these indices may be speciﬁed in different ways. If you use more than one method to deﬁne an index, the

last deﬁnition will be used. It is better to just use one method in your UAM.in ﬁle to avoid confusion.

F107

Sets the F10.7and 81 day average of F10.7(commonly denoted as F10.7aor F10.7). This is used to set the range of the

initial altitude grid and drive the lower boundary conditions. It is also used as input into several of the models called

by GITM. If RCMR is being used to drive the F10.7, then the values provided here are used to initialize MSIS and

should be as close to the real F10.7as possible.

The F10.7is a measure of the solar 10.7 cm ﬂux [Covington, 1948] and is measured in solar ﬂux units (1 sfu =

10−22 W m−2Hz−1= 10,000 jansky). The F10.7is commonly used as a proxy for the solar EUV output.

#F107

(real) f107

(real) f107a

NGDC INDICES

This input option allows GITM to use an appropriate F10.7for each day that the assimilation runs, instead of a ﬁxed

value. This is accomplished by providing an input ﬁle that contains the F10.7values for the entire GITM simulation

period and the preceding 81 days. This allows GITM to compute the appropriate daily F10.7aas well. Typically,

users simply make a ﬁle including all F10.7values from 1980 onward, so they never have to worry about missing any

preceding days.

#NGDC_INDICES

(string) filename

SME INDICES

This option is not well described in set inputs.f90.

#SME_INDICES

(string) Mystery input number one

(string) Mystery input number two

ACE DATA

This option is not well described in set inputs.f90.

#ACE_INDICES

(string) Mystery input number one

(string) Mystery input number two

28 CHAPTER 3. INPUTS

SWPC DATA

This option is not well described in set inputs.f90.

#SWPC_INDICES

(string) Mystery input number one

(string) Mystery input number two

NOAAHPI INDICES

#NOAAHPI_INDICES

(string) NOAA HPI filename

The Kp index is not used by GITM, but several models that GITM calls utilize it. The Kp index is a measure of

mid-latitude geomagnetic disturbance and can be obtained from:

ftp://ftp.ngdc.noaa.gov/STP/GEOMAGNETIC DATA/INDICES/KP AP/

while a description of the index can be found at:

http://www-app3.gfz-potsdam.de/kp index/description.html

#KP

(real) kp

HEMISPHERICPOWER

This option sets the hemispheric power of the aurora. Typical values range from 1−1000, with 20 being a nominal,

quiet time value.

#HPI

(real) HemisphericPower

SOLARWIND

This option is one way to set the driving conditions for the high-latitude electric ﬁeld models. Because this op-

tion is static and will not change during the run, it is usually better to use the MHD INDICES option instead, as

MHD INDICES provides a dynamic driving environment.

#SOLARWIND

(real) bx

(real) by

(real) bz

(real) vx

MHD INDICES

Use this option to provide GITM with dynamic IMF and solar wind conditions. This option can either be omitted

entirely; if it is desired a ﬁlename whose contents will be discussed in more detail in section 3.3.1 must be speciﬁed.

This ﬁle should be located in the same directory as the UAM.in ﬁle.

#MHD_INDICES

(string) filename

3.1. PRINCIPLE INPUT 29

EUV DATA

This input option allows the user to specify the extreme ultraviolet (EUV) ﬂux using solar spectra from any model or

data source. A FISM ﬁle [Chamberlin et al., 2007, 2008] is used as an example in section 3.3.3.

#EUV_DATA

(logical) UseEUVData

(string) cEUVFile

3.1.8 Physical Processes

The following options let the user specify how GITM treats different physical boundaries and processes.

INITIAL

This option speciﬁes the initial conditions and the lower boundary conditions. For Earth, we typically just use MSIS

and IRI for initial conditions. For other planets, the vertical temperature parameters can be set here. TempMin

and TempMax specify the initial temperatures at the bottom and top of the thermosphere in Kelvin, respectively.

TempHeight speciﬁes the height (in kilometers from the surface of the planet) of the midpoint of the temperature

gradient. TempWidth speciﬁes the vertical width (in kilometers) of the temperature gradient.

#INITIAL

(logical) UseMSIS

(logical) UseIRI

If UseMSIS is false (F) then:

(real) TempMin

(real) TempMax

(real) TempHeight

(real) TempWidth

STATISTICALMODELSONLY

There can be beneﬁts to running a simpler ionosphere and thermosphere models. GITM can be used as a shell to run

MSIS and IRI without any coupling. This input option bypasses GITM and only outputs results from MSIS and IRI.

This option allows the user who is familiar with GITM to get MSIS and IRI output without having to install or know

how to run these models independently. The UseStatisticalModelsOnly ﬂag can be set to Tor F(true or false) and the

DtStatisticalModels options lets you specify the time-step (in seconds) used in MSIS and IRI.

#STATISTICALMODELSONLY

(logical) UseStatisticalModelsOnly

(real) DtStatisticalModels

TIDES

This option uses a series of logical ﬂags to tell GITM how to use tides. The ﬁrst ﬂag (UseMSISFlat) tells GITM to use

MSIS without tides. The second ﬂag (UseMSISTides) is using MSIS with full up tides. One of these two ﬂags should

be true. The remaining ﬂags should only be true if UseMSISTides is false, and then only one should be true. The third

ﬂag (UseGSWMTides) uses GSWM tides, while the forth ﬂag (UseWACCMTides) sets GITM to use the WACCM

tides. Essentially, only one tidal model should be used per GITM run. Information about GSWM can be found at:

http://www.hao.ucar.edu/modeling/gswm/gswm.html and information about WACCM can be found

at:

http://www.cesm.ucar.edu/working groups/WACCM/.

30 CHAPTER 3. INPUTS

When running with the MSIS or WACCM tides, no additional input ﬁles are needed. However, when using

GSWM additional ﬁles must be made accessible to GITM in the run/UA/DataIn directory. These ﬁles are

stored in the Tides directory within GITM. You can check these ﬁles out using CVS (as described in Chap-

ter 2.2) and then create links or copy them into your run directory by using: ln -s /GITM/Tides/*bin

/GITM/run/UA/DataIn/.

#TIDES

(logical) UseMSISFlat

(logical) UseMSISTides

(logical) UseGSWMTides

(logical) UseWACCMTides

DUSTDATA

#DUSTDATA

(logical) UseDustDistribution

(string) cDustFile

(string) cConrathFile

DUST

#DUST

(real) Total $\tau$

(real) Conrnu

GSWMCOMP

If you decided to use GSWM tides by selecting UseGSWMTides in the TIDES option, you can specify which diurnal

and semidiurnal tidal components to include.

#GSWMCOMP

(logical) GSWMdiurnal(1)

(logical) GSWMdiurnal(2)

(logical) GSWMsemidiurnal(1)

(logical) GSWMsemidiurnal(2)

USEPERTURBATION

#USEPERTURBATION

(logical) UsePerturbation

DAMPING

This option speciﬁes whether or not to allow damping of the vertical wind oscillations that can occur in the lower

atmosphere.

#DAMPING

(logical) UseDamping

3.1. PRINCIPLE INPUT 31

GRAVITYWAVE

A switch to add heating to the atmosphere. This was primarily used to explore gravity waves on Titan and has little to

no effect on the terrestrial atmosphere. This options defaults to false.

#GRAVITYWAVE

(logical) UseGravityWave

AURORAMODS

#AURORAMODS

(logical) Normalize Aurora to Hemispheric Power

(real) Auroral Height Factor

NEWELLAURORA

This input option provides several logical ﬂags that allow GITM to use Pat Newell’s aurora model, Ovation [Newell

et al., 2002].

#NEWELLAURORA

(logical) UseNewellAurora

(logical) UseNewellAveraged

(logical) UseNewellMono

(logical) UseNewellWave

(logical) UseNewellRemoveSpikes

(logical) UseNewellAverage

OVATION

This input option provides several logical ﬂags that allow GITM to use the SME Ovation model.

#OVATION

(logical) UseOvationSME

(logical) UseOvationSMEMono

(logical) UseOvationSMEWave

(logical) UseOvationSMEIon

AMIEFILES

This option allows the user to specify the electrodynamic state of the polar regions using the Assimilative Mapping

of Ionospheric Electrodynamics (AMIE) model [Ridley and Kihn, 2004]. Input ﬁles separately specify the conditions

at the northern and southern polar caps, and should be in the MIE binary format. Contact Aaron Ridley for more

information about using AMIE with GITM.

#AMIEFILES

(string) cAMIEFileNorth

(string) cAMIEFileSouth

THERMO

This input option sets ﬂags that allow the user to turn various thermospheric processes on and off. For a realistic run,

all three heating ﬂags (for solar, Joule, and auroral heating) should be set to true, along with both cooling ﬂags (for

nitrous-oxide, NO, and oxygen, O). UseConduction, UseUpdatedTurbulentCond, and UseTurbulentCond ﬂag should

also all be set to true. UseDiffusion, however, defaults to false and should not be used for a realistic run.

32 CHAPTER 3. INPUTS

The only keyword that is not a ﬂag is EddyScaling. This allows the user to control the Eddy diffusion by applying

a multiplicative to the model’s Eddy diffusion value.

#THERMO

(logical) UseSolarHeating

(logical) UseJouleHeating

(logical) UseAuroralHeating

(logical) UseNOCooling

(logical) UseOCooling

(logical) UseConduction

(logical) UseTurbulentCond

(logical) UseUpdatedTurbulentCond

(logical) UseDiffusions

(real) EddyScaling

THERMALDIFFUSION

This keyword sets the thermal conductivity. KappaTemp0 should be set to the desired value of the thermal conductivity

in MKS units.

#THERMALDIFFUSION

(real) KappaTemp0

VERTICALSOURCES

This input option provides ﬂags and limits for the vertical thermospheric sources. The UseEddyInSolver turns the

Eddy diffusion on and off, the UseNeutralFrictionInSolver turns the vertical neutral friction on and off, and the Maxi-

mumVerticalVelocity sets the limit for vertical neutral winds in meters per second.

#VERTICALSOURCES

(logical) UseEddyInSolver

(logical) UseNeutralFrictionInSolver

(real) MaximumVerticalVelocity

EDDYVELOCITY

This input option further allows the user to specify how Eddy diffusion is treated by providing an ﬂag to use the method

presented by ?, which was developed for the Martian atmosphere. The UseEddyCorrection ﬂag is another option that

is useful for certain extraterrestrial atmospheres.

#EDDYVELOCITY

(logical) UseBoquehoAndBlelly

(logical) UseEddyCorrection

DIFFUSION

If you use Eddy diffusion, as indicated by the UseDiffusion ﬂag, you must specify two pressure levels in units of

UNITS using EddyDiffusionPressure[0,1]. Below the ﬁrst pressure level, the Eddy diffusion will be constant. Between

the ﬁrst and the second pressure levels, the Eddy diffusion coefﬁcient will drop-off linearly. Thus, the ﬁrst pressure

must be larger than the second! The Eddy diffusion coefﬁcient may also be speciﬁed using EddyDiffusionCoef.

3.1. PRINCIPLE INPUT 33

#DIFFUSION

(logical) UseDiffusion

(real) EddyDiffusionCoef

(real) EddyDiffusionPressure0

(real) EddyDiffusionPressure1

WAVEDRAG

This input option allows stress heating to be applied in GITM, providing an additional source of drag in the thermo-

sphere.

#WAVEDRAG

(logical) UseStressHeating

FORCING

This input option provides ﬂags for physical processes that drive the thermosphere.

#FORCING

(logical) UsePressureGradient

(logical) UseIonDrag

(logical) UseNeutralFriction

(logical) UseViscosity

(logical) UseCoriolis

(logical) UseGravity

IONFORCING

This input option turns several ionospheric transport processes on and off. UseExB turns the E×Bplasma drift on and

off, UseIonGravity allows the user to determine whether or not to allow the ions to respond to gravity, UseNeutralDrag

relegates the forcing from ion-neutral collisions on the ionosphere, and UseIonPressureGradient deals with the ion

motions resulting from changes to the plasma pressure gradient. All of these processes should be on for a realistic

simulation.

#IONFORCING

(logical) UseExB

(logical) UseIonPressureGradient

(logical) UseIonGravity

(logical) UseNeutralDrag

CHEMISTRY

Turn certain chemical processes on or off. All processes are included by default.

#CHEMISTRY

(logical) UseIonChemistry

(logical) UseIonAdvection

(logical) UseNeutralChemistry

34 CHAPTER 3. INPUTS

PHOTOELECTRON

The photoelectron heating efﬁciency describes the energy input to the electron gas per electron-ion pair formed by the

photoionization of a neutral [Hanson and Cohen, 1968]. GITM deﬁnes the photoelectron heating efﬁciency as a scalar

that multiplies the sum of the photoionization rate and the neutral density for each neutral species. The speciﬁed value

should lie between 0.02 and 0.20, though the default value is zero. If RCMR is being used to drive the photoelectron

heating efﬁciency, this block is ignored.

#PHOTOELECTRON

(real) Photoelectron heating efficiency

DYNAMO

This input option provides ﬂags for the ionospheric dynamo. The UseDynamo ﬂag turns on a model to calcu-

late the ionospheric electric ﬁelds. DynamoHighLatBoundary sets the polar latitude limit (65◦or 70◦is a realistic

limit), nItersMax sets the maximum number of iterations for the Dynamo convergence (typically set at 500), and

the MaxResidual sets the maximum difference, in Volts, to allow between iterations before the value is said to have

converged (typically set to 1 V). The Dynamo currently uses a static high-latitude boundary, though a dynamical one

would be ideal. To get around this, input from AMIE, run using the SuperMag data network, can be used instead of

the UseDynamo process. The use of AMIE input is discussed in section 3.1.8.

#DYNAMO

(logical) UseDynamo

(real) DynamoHighLatBoundary

(integer) nItersMax

(real) MaxResidual

ELECTRODYNAMICS

Sets the time-step (in seconds) for updating the high-latitude (and low-latitude) electrodynamic drivers, such as the

potential and the aurora.

#ELECTRODYNAMICS

(real) DtPotential

(real) DtAurora

IONPRECIPITATION

This is a highly speciﬁc input option for experienced users. Most users should set this option to false. This is only for

people wishing to do very speciﬁc runs in high altitude regions. IonIonizationFilename and IonHeatingRateFilename

allow the advanced user to specify the ionization and ion heating rates due to precipitation using auxiliary input ﬁles.

#IONPRECIPITATION

(logical) UseIonPrecipitation

(string) IonIonizationFilename

(string) IonHeatingRateFilename

LTERADIATION

LTERadiation allows the user to specify the time-step for the local thermodynamic equilibrium radiation process in

seconds. This option is typically only used by the Mars GITM. It may be set for other versions of GITM, but each

planet treats this input option differently. Versions not compiled for Mars will either modify or ignore input from

LTERadiation.

3.1. PRINCIPLE INPUT 35

#LTERadiation

(real) DtLTERadiation

DIPOLE

This input option allows the user to specify the parameters the geomagnetic ﬁeld within the limits of a dipole conﬁgu-

ration so that any conﬁguration (centered, tilted, or off-center and tilted) may be used. x,y,zDipoleCenter specify the

origin of the dipole ﬁeld in ECI coordinates, MagneticPoleTilt gives the angle (in degrees) between the dipole axis

and the terrestrial rotation axis, and MagneticPoleRotation gives the constant angular rate (in degrees) at which the

geomagnetic dipole ﬁeld rotates.

#DIPOLE

(real) MagneticPoleRotation

(real) MagneticPoleTilt

(real) xDipoleCenter

(real) yDipoleCenter

(real) zDipoleCenter

APEX

This input option indicates whether or not GITM should use the more realistic Apex geomagnetic ﬁeld [Richmond,

1995]. If this option is set to false, the dipole ﬁeld speciﬁed in the previous subsection will be used.

#APEX

(logical) UseApex

3.1.9 Geographic Boundaries

TOPOGRAPHY

This input option, which is defaults to false, uses topography to provide a variable vertical grid in GITM. You can

also specify the minimum altitude at which the vertical grid for the thermosphere and ionosphere become consistent

(AltMinUniform and AltMinIono, respectively). As with all other inputs the altitudes should be given in kilometers

from the surface of the planet.

#TOPOGRAPHY

(logical) UseTopography

(real) AltMinUniform

(real) AltMinIono

ALTITUDE

The upper and lower altitude limits (in kilometers) may be speciﬁed here. These values default to 500 km and 95 km,

respectively. Setting the altitude limits above or below these values may result in unstable model runs.

UseStretchedAltitude may also be turned on and off here. This ﬂag defaults to true, as it allows the altitudes with

rapidly changing pressure levels to be treated in more detail than those where the atmosphere changes slowly with

altitude.

#ALTITUDE

(real) AltMin

(real) AltMax

(logical) UseStretchedAltitude

36 CHAPTER 3. INPUTS

GRID

This input option sets the grid resolution in GITM. Although this process is straightforward, it deserves some thought

and discussion. This is provided in section 3.2. For new GITM users, learning how to alter the grid is a good place to

start moving beyond the test run shown in Chapter 1.2.

#GRID

(integer) nBlocksLon

(integer) nBlocksLat

(real) LatStart

(real) LatEnd

(real) LonStart

(real) LonEnd

STRETCH

You can stretch the grid in GITM in the latitudinal direction. It takes some practice to get the stretching just the way

that you might like. To do this, you need to specify the geographic latitude (in degrees) that the stretching will center at

(ConcentrationLatitude), the fraction of stretch (StretchingPercentage) where 0 means that there will be no stretching

and 1 means that the latitude will be stretched by 100%, and a multiplicative factor (StretchingFactor) that helps scale

the stretching. The StretchingFactor should range between 0 and 1, erring closer to 1 to provide more control.

#STRETCH

(real) ConcentrationLatitude

(real) StretchingPercentage

(real) StretchingFactor

Here is an example for stretching near the equator:

#STRETCH

0.0 ! Equator

0.7 ! Amount of stretching is great

0.8 ! more control

Here is another example for no stretching near the auroral oval:

#STRETCH

65.0 ! Location of minimum grid spacing

0.0 ! There is no streching here

1.0 ! For control

NEWSTRETCH

An alternative way to stretch the grid.

#NEWSTRETCH

(real) Poleward edge of the stretch region (degrees)

(real) Stretching width (degrees)

(real) Stretching percentage (0.0-1.0)

Here is an example for stretching near the auroral zone:

#NEWSTRETCH

65.0 ! Auroral oval

5.0 ! Width of the stretched region

0.6 ! Amount of stretch (0 = none, 1 = lots)

3.2. SETTING THE GRID 37

3.2 Setting the Grid

Setting the grid resolution in GITM is not very complicated, but it does involve some thought. There are a few variables

that control this. In ModSize.f90, the following variables are deﬁned:

integer, parameter :: nLons = 9

integer, parameter :: nLats = 9

integer, parameter :: nAlts = 50

integer, parameter :: nBlocksMax = 4

The ﬁrst three variables (nLons, nLats and nAlts) deﬁne the size of a single block. In the example above, there are

9 cells in latitude, 9 cells in longitude and 50 cells in altitude. The latitude and longitude resolution in GITM is deﬁned

by the cell numbers speciﬁed here and the block numbers discussed in the following section. The size of the altitude

cells are measured in scale heights instead of kilometers, as certain regions require higher resolutions than others based

on the dominating chemical and dynamical processes. Each altitude cell contains 1

3of a scale height, starting at 80

km and typically reaching up to 500 km. Increasing the number of altitude blocks will increase the altitude range,

but if this value is increased too much the model becomes unstable. This altitude limit makes it problematic to model

the equatorial region during storms, where increased vertical plasma transport requires the model consider altitudes of

2000 km and higher.

The ﬁnal variable (nBlocksMax) deﬁnes the maximum number of blocks you can have on a single processor.

Most people run with one single block per processor, as this is faster. So setting this to “1” is usually preferred, and

is necessary when running with the Dynamo option on. This is a necessity because the Dynamo routine does not

correctly transfer the geomagnetically oriented data into the geographic coordinates used in the ghost cells. Hopefully

this will be updated in future versions, as allowing multiple blocks per node can, in theory, save memory.

Don’t forget, if you change any of these parameters you will need to recompile the code (run the Makeﬁle again)

so that a new executable using the newly deﬁned variables can be produced.

3.2.1 Running 3D Over the Whole Globe

Once the number of cells is deﬁned, then the number of blocks in latitude and longitude need to be deﬁned. This is

done in the UAM.in ﬁle, as shown in section 3.1. For example, the initial settings have 8 blocks in latitude and 8 in

longitude:

#GRID

8 lons

8 lats

-90.0 minimum latitude to model

90.0 maximum latitude to model

0.0 minimum longitude to model

0.0 maximum longitude to model

The number of cells in the simulation domain will then be 72 in longitude, 72 in latitude, and 50 in altitude. Given

that there are 360◦in longitude and 180◦in latitude, the resolution would be 360◦/72 = 5.0◦and 180◦/72 = 2.5◦in

latitude. If one block were put on each processor, 64 processors would be required.

If one desired to run without the Dynamo turned on, the problem could also be run with multiple blocks per node.

This grid ﬁts quite nicely on either four- or eight-core processors. However, on 12-core processors this would not

work very well at all. We have started to run simulations of 1◦in latitude and 5◦in longitude, which can ﬁt nicely on

a 12-core processor machine. For example, in ModSize.f90:

integer, parameter :: nLons = 9

integer, parameter :: nLats = 15

38 CHAPTER 3. INPUTS

and in UAM.in:

#GRID

8 lons

12 lats

This can then run on 96 cores, which is nicely divisible by 12. Essentially, an inﬁnite combination of cells per block

and number of blocks can be utilized. Typically, the number of blocks in latitude and longitude are even numbers.

3.2.2 Running 3D Over the Part of the Globe

GITM can be run over part of the globe - both in latitude and in longitude. It can be run over a single polar region

(by setting either the minimum or maximum latitude to be greater (or less) than ±90◦). If this is selected, mes-

sage passing over the poles is implemented. If the pole is not selected, then boundary conditions have to be set in

set horizontal bcs.f90. By default, a continuous gradient boundary condition is used on the densities and

temperatures, while a continuous value is used on the velocity. This is true in both latitude and longitude. In longitude,

message passing is implemented all of the time, but the values are over-written by the boundary conditions if the

maximum and minimum longitude are not equal to each other.

The longitudinal resolution (∆φ) is set by:

∆φ=φend −φstart

nBlocksLon ×nCellsLon (3.2)

while, the latitudinal resolution (∆θ) is set by:

∆θ=θend −θstart

nBlocksLat ×nCellsLat (3.3)

3.2.3 Running in 1D

GITM can run in 1D mode, in which the call to advance horizontal is not completed. This means that GITM runs

exactly the same way, but ignoring all of the horizontal advection terms. You have to do two things to make GITM run

in 1D. First, in ModSize.f90:

integer, parameter :: nLons = 1

integer, parameter :: nLats = 1

integer, parameter :: nAlts = 50

integer, parameter :: nBlocksMax = 1

This tells the code that you only want one single latitude and longitude location. To specify the exact location, in

UAM.in:

#GRID

1 lons

1 lats

41.75 minimum latitude to model

41.75 maximum latitude to model

275.0 minimum longitude to model

275.0 maximum longitude to model

This is pretty close to some place in Michigan. GITM will model this exact point for as long as you specify. One thing

to keep in mind with running in 1D is that the Earth still rotates, so the spot will have a strong day to night variation in

temperature. In 3D, the winds decrease some of the variability between day and night, but in 1D, this doesn’t happen.

So, the results are going to be perfect. But, 1D is great for debugging.

3.3. AUXILIARY INPUT FILES 39

3.3 Auxiliary Input Files

If you have access to the University of Michigan Atmospheric, Oceanic, and Space Science resources, the data needed

for these auxiliary input ﬁles are on herot.engin.umich.edu. The following descriptions will allow you down-

load to create your own auxiliary input ﬁles yourself, but this process is much more simple if you have access to the

resources on herot. Recall that makerun.pl, previously mentioned at the beginning of section 3.1, will create

many of the following input ﬁles when it builds a UAM.in ﬁle. All of these auxiliary input ﬁles should be kept in the

same directory as the GITM executable and the UAM.in ﬁle.

3.3.1 IMF and Solar Wind

This ﬁle controls the high-latitude electric ﬁeld and aurora when using models that depend on the solar wind and

interplanetary magnetic ﬁeld (IMF). It allows GITM to dynamically control these quantities. You can create either

realistic IMF ﬁles or hypothetical ones.

For realistic IMF ﬁles, we typically use CDF ﬁles downloaded from the CDAWEB ftp site, located at:

http://cdaweb.gsfc.nasa.gov/cdaweb anonymousftp.htm.

On herot, an IDL code (called cdf to mhd.pro) merges the solar wind and IMF ﬁles to create one sin-

gle ﬁle. This IDL code also propagates the solar wind and IMF from L1 to 32 Re upstream of the Earth. You

can use the DELAY statement to shift the time more (e.g. in the example below, it shifts by an additional 15 min-

utes). cdf to mhd.pro requires both a solar wind ﬁle and an IMF ﬁle. For example, the IMF ﬁle would be

ac h0 mfi 20011231 v04.cdf and the solar wind ﬁle would be ac h0 swe 20011231 v06.cdf. The code

assumes that the data starts at #START, and ends when it encounters an error. This can mean that if there is an error

in the data somewhere, the code will only read up to that point. To validate that the solar wind and IMF is what you

think it is, it is recommended that you use the IDL code imf plot.pro to check the output before using it to run

GITM. Here is an example ﬁle:

This file was created by Aaron Ridley to do some wicked cool science thing.

The format is:

Year MM DD HH Mi SS mS Bx By Bz Vx Vy Vz N T

Year=year

MM = Month

DD = Day

HH = Hour

Mi = Minute

SS = Second

mS = Millisecond

Bx = IMF Bx GSM Component (nT)

By = IMF By GSM Component (nT)

Bz = IMF Bz GSM Component (nT)

Vx = Solar Wind Vx (km/s)

Vy = Solar Wind Vy (km/s)

Vz = Solar Wind Vz (km/s)

N = Solar Wind Density (/cm3)

T = Solar Wind Temperature (K)

#DELAY

900.0

40 CHAPTER 3. INPUTS

#START

2000 3 20 2 53 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 54 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 55 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 56 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 57 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 58 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 2 59 0 0 0.0 0.0 2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 3 0 0 0 0.0 0.0 -2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 3 1 0 0 0.0 0.0 -2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 3 2 0 0 0.0 0.0 -2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 3 3 0 0 0.0 0.0 -2.0 -400.0 0.0 0.0 5.0 50000.0

2000 3 20 3 4 0 0 0.0 0.0 -2.0 -400.0 0.0 0.0 5.0 50000.0

To actually read in this ﬁle, in UAM.in, use the input option MHD INDICES described in section 3.1.7.

3.3.2 Hemispheric Power

The hemispheric power ﬁles describe the dynamic variation of the auroral power going into each hemisphere. Models

such as Fuller-Rowell and Evans [1987] use the Hemispheric Power to determine which level of the model it should

use. The Hemispheric Power is converted to a Hemispheric Power Index using the formula shown in equation 3.4.

HP I = 2.09 log(HP )1.0475 (3.4)

The National Oceanic and Atmospheric Administration (NOAA) provides these hemispheric power ﬁles for public

use online at http://www.swpc.noaa.gov/ftpmenu/lists/hpi.html. There are two types of formats

used for hemispheric power ﬁles (due to a change in the NOAA output format in 2007). Both ﬁle formats can be used

by GITM, and are shown in the examples below.

Example ﬁle 1 for data prior to 2007:

# Prepared by the U.S. Dept. of Commerce, NOAA, Space Environment Center.

# Please send comments and suggestions to sec@sec.noaa.gov

# Source: NOAA POES (Whatever is aloft)

# Units: gigawatts

# Format:

# The first line of data contains the four-digit year of the data.

# Each following line is formatted as in this example:

# NOAA-12(S) 10031 9.0 4 .914

# Please note that if the first line of data in the file has a

# day-of-year of 365 (or 366) and a HHMM of greater than 2300,

# that polar pass started at the end of the previous year and

# ended on day-of-year 001 of the current year.

# A7 NOAA POES Satellite number

# A3 (S) or (N) - hemisphere

# I3 Day of year

# I4 UT hour and minute

3.3. AUXILIARY INPUT FILES 41

# F8.1 Estimated Hemispheric Power in gigawatts

# I3 Hemispheric Power Index (activity level)

# F8.3 Normalizing factor

2000

NOAA-15(N) 10023 35.5 7 1.085

NOAA-14(S) 10044 25.3 7 .843

NOAA-15(S) 10114 29.0 7 .676

NOAA-14(N) 10135 108.7 10 1.682

NOAA-15(N) 10204 36.4 7 1.311

Example ﬁle 2 for data in and after 2007:

:Data_list: power_2010.txt

:Created: Sun Jan 2 10:12:58 UTC 2011

# Prepared by the U.S. Dept. of Commerce, NOAA, Space Environment Center.

# Please send comments and suggestions to sec@sec.noaa.gov

# Source: NOAA POES (Whatever is aloft)

# Units: gigawatts

# Format:

# Each line is formatted as in this example:

# 2006-09-05 00:54:25 NOAA-16 (S) 7 29.67 0.82

# A19 Date and UT at the center of the polar pass as YYYY-MM-DD hh:mm:ss

# 1X (Space)

# A7 NOAA POES Satellite number

# 1X (Space)

# A3 (S) or (N) - hemisphere

# I3 Hemispheric Power Index (activity level)

# F7.2 Estimated Hemispheric Power in gigawatts

# F7.2 Normalizing factor

2010-01-01 00:14:37 NOAA-17 (N) 1 1.45 1.16

2010-01-01 00:44:33 NOAA-19 (N) 1 1.45 1.17

This ﬁle is not speciﬁed in UAM.in, instead different subroutines within GITM will use it as needed.

3.3.3 Solar Irradiance

To provide GITM with realistic solar irradiance, the solar EUV must be speciﬁed. This can be done through a ﬁle

containing modeled or observed solar irradiance data. An example from the FISM model is shown below.

42 CHAPTER 3. INPUTS

#START

2009 3 20 0 0 0 0.00389548 0.00235693

0.00127776 0.000907677 0.000652528 0.000372993 0.000250124 0.000194781

0.000389686 0.000118650 0.00642058 0.00618358 0.000133490 7.67560e-05

7.80045e-05 0.000145722 5.92577e-05 5.95070e-05 0.000102437 6.48526e-05

8.94509e-05 0.000101928 5.94333e-05 5.36012e-05 1.51744e-05 1.10265e-05

1.26937e-05 2.16591e-05 9.57055e-06 1.82608e-05 7.07992e-05 2.55451e-05

1.12451e-05 6.89255e-05 3.03882e-05 2.33862e-05 2.98026e-05 4.44682e-05

1.50847e-05 3.00909e-05 8.18379e-05 3.52176e-05 0.000416491 0.000269080

0.000269080 0.000275734 6.60872e-05 4.46671e-05 0.000220697 0.000512933

3.85239e-05 9.30928e-05 2.71239e-05 1.23011e-05 1.05722e-05 9.30876e-06

7.08442e-07 3.54221e-07 1.77110e-07

2009 3 20 0 1 0 0.00389548 0.00235693