PARAM.XML

<!-- The syntax is described by share/Scripts/CheckParam.pl and the manual -->

<commandList name="Global Ionosphere Thermosphere Model 2: UA Component">

GITM is typically run with a {\tt UAM.in} file, which resides in the
directory that you are running from. In the framework it obtains 
parameters from the PARAM.in file.

<commandgroup name="Time Variables">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

In order to run GITM, a starting time and an ending time must be
specified.  These are specified using the following commands:

<command name="TIMESTART" alias="STARTTIME" if="$_IsStandAlone">
	<parameter name="iYear"   type="integer" default="2000" />
	<parameter name="iMonth"  type="integer" min="1" max="12" default="3"/>
	<parameter name="iDay"   type="integer" min="1" max="31" default="21"/>
	<parameter name="iHour"   type="integer" min="0" max="23" default="0"/>
	<parameter name="iMinute" type="integer" min="0" max="59" default="0"/>
	<parameter name="iSecond" type="integer" min="0" max="59" default="0"/>

#TIMESTART
1999			iYear
03			iMonth
18			iDay
00			iHour
00			iMinute
00			iSecond

This command is only used in the stand alone mode.

The #STARTTIME command sets the initial date and time for the simulation.
</command>

<command name="TIMEEND" alias="ENDTIME" if="$_IsStandAlone">
	<parameter name="iYear"   type="integer" default="2000" />
	<parameter name="iMonth"  type="integer" min="1" max="12" default="3"/>
	<parameter name="iDay"   type="integer" min="1" max="31" default="21"/>
	<parameter name="iHour"   type="integer" min="0" max="23" default="0"/>
	<parameter name="iMinute" type="integer" min="0" max="59" default="0"/>
	<parameter name="iSecond" type="integer" min="0" max="59" default="0"/>

#TIMEEND
1999			iYear
03			iMonth
25			iDay
00			iHour
00			iMinute
00			iDay

This command is only used in the stand alone mode.

The #TIMEEND command sets the final date and time for the simulation.
</command>

<command name="RESTART">
	<parameter name="DoRestart" type="logical" default="F" />
        <rule expr="-f 'UA/restartIN/header.rst' or not $DoRestart">
                File UA/restartIN/header.rst should exist!
	</rule>

#RESTART
F			DoRestart

There are two commands that are typically not input by a user, but are
specified in the restart header file that is read in the exact same
way as the input file.  It is possible to set these variables, though.

</command>

<command name="ISTEP">
	<parameter name="iStep"    type="integer" default="" />

#ISTEP
1

This sets the current iStep to the read in value instead of starting at
iteration 1.

</command>

<command name="TSIMULATION">
	<parameter name="tsimulation"    type="real" default="" />

#TSIMULATION
0.0

This offsets the current start time by the read in amount.  It is simply
added to the #STARTTIME input time.

</command>

<command name="CPUTIMEMAX">
	<parameter name="CPUTimeMax" type="real" default="" />

#CPUTIMEMAX
7200.0			CPUTimeMax (seconds)

When you are running on a queue-based system, you can use this command
to set the exact amount of time that the code should run, then stop
and write a restart file.  It is good to give a small buffer so the
code has time to write files before the queue stops.  This buffer time
is quite dependent upon the system.  On fast I/O machines, I typically
give a buffer of only a couple of minutes.  On some systems, I
sometimes give a full half hour, just to make absolutely sure the code
will write all of the correct files and exit before the queue is up.

</command>

</commandgroup>

<commandgroup name="Initial Conditions">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="INITIAL">
	<parameter name="UseMSIS" type="logical" default="T" />
	<parameter name="UseIRI"  type="logical" default="T" />
	<if expr="$UseMSIS">
		<parameter name="TempBottom"   type="real"              />
		<parameter name="TempTop"      type="real"              />
		<parameter name="NumberDensity1" type="real" min="0.01" />
		<parameter name="NumberDensity2" type="real" min="0.01" />
		<parameter name="NumberDensity3" type="real" min="0.01" />
	</if>

#INITIAL
F			UseMSIS
T			UseIRI
200.0			TempBottom
1200.0			TempTop
5.0e17			NDensity1
7.0e18			NDensity2
3.0e19			NDensity3

On the Earth, empirical models exist which can be used to derive a
background atmosphere and ionosphere.  These are MSIS (thermosphere
and IRI (ionosphere).  If MSIS is used, then the all of the species
densities are set using MSIS.  There are 2 species which MSIS does not
include: [NO] and [N($^2$D)].  We have made up some formula for
setting these two species.  The neutral temperature is also set using
MSIS if UseMSIS = T.

If UseMSIS = F, then GITM reads in the temperature at the bottom
and top of the atmosphere (for the initial condition), and the number
density at the bottom of the atmosphere for all of the major species
(nSpecies, which is set in ModPlanet.f90).

It UseIRI = T, the number densities of the ion species are set
by IRI.  If it is .false., then the initial densities are set to some
very, very small value and the ionosphere is grown out of the chemistry
with the neutral atmosphere.

The variables TempMin, etc., are only read in if {\tt UseMSIS = F}.

</command>

<command name="APEX">
	<parameter name="UseApex" type="logical" default="F" />

#APEX
T			UseApex

A model of the magnetic field of the Earth can also be used.  This
variable sets whether to use a realistic magnetic field (T) or a
dipole (F). In the current framework only the dipole works.

The default value is false.

</command>

</commandgroup>

<commandgroup name="Indices">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="F107">
	<parameter name="f107"  type="real" default="" min="65"/>
	<parameter name="f107a" type="real" default="" min="65"/>

#F107
150.0			f107
150.0			f107a

The $f10.7$ is a proxy for how bright the Sun is in a given set of
wavelengths.  For a low value (70), the temperature of the atmosphere
will be low, and the ionospheric density will be small.  For a high
value (300), the temperature will be above 1500 K, and ionospheric
electron densities will be well above $10^{12} /m^3$.  This is used in
the routine {\tt calc_euv.f90} to determine the solar flux at the top
of the atmosphere.

</command>

<command name="HPI">
	<parameter name="HemisphericPower" type="real" default="" min="0.0"/>

#HPI
10.0		HPI

The hemispheric power index (HPI) describes how much power is in the
hemispherically summed precipitating electrons (in Gigawatts).  This
is a number that is typically in the 1-10 range, but during active
times can reach 300.  This is used in the {\tt get_potential.f90}
routine to get the auroral inputs at the top of the atmosphere.

</command>

<command name="KP">
	<parameter name="kp" type="real" default="" min="0.0" max="9.3"/>

#KP
1.0			kp

KP is a 3 hour index that summarizes the general activity level of the
magnetosphere.  It has a range from 0-9.  Currently, KP is not used in
GITM.

</command>

<command name="SOLARWIND">
	<parameter name="bx" type="real" default="" />
	<parameter name="by" type="real" default="" />
	<parameter name="bz" type="real" default="" />
	<parameter name="vx" type="real" default="" />

#SOLARWIND
0.0			Bx
0.0			By
-2.0			Bz
400.0			Vx

The interplanetary magnetic field (IMF) and solar wind velocity are
used by a number of empirical models of the ionospheric potential.
The IMF components typically range between $\pm 10 nT$ at Earth.  The
fields have reached values as high as 75 $nT$.  The $B_z$ component is
typically the most geoeffective at Earth, such that negative $B_z$ can
cause large ionospheric potentials.  The velocity typically ranges
between 350-600 $km/s$, although it has been known to go upwards of
1700 $km/s$.

</command>

</commandgroup>

<commandgroup name="Index Files">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Conversely, you can input time-dependent values of the solar wind and
IMF, HPI, Kp, f10.7, etc.  There are currently three methods for
inputing these quantities.

It is quite easy to incorporate other methods.  These three methods
are located in the {\tt srcIO} directory with appropriate file names.
You can simply copy one of the files, rename the subroutine, modify it
to read in the appropriate data, add it to the {\tt Makefile}, add a
flag in the {\tt set_inputs.f90} (in both the {\tt src} and {\tt
srcIO} directories), then compile it and debug it.

<command name="AMIEFILES">
	<parameter name="cAMIEFileNorth" type="string" 
		default="none" length="80"/>
	<parameter name="cAMIEFileSouth" type="string" 
		default="none" length="80"/>

#AMIEFILES
b19980504n
b19980504s

Instead of using empirical models of the ionospheric potential and
auroral precipitation, you can use model results from the assimilative
mapping of ionospheric electrodynamics (AMIE) technique.  If you do,
you have to specify a Northern hemisphere and Southern hemisphere
file.

</command>

<command name="MHD_INDICES">
	<parameter name="cFileName" type="string" 
		default="" length="80"/>

#MHD_INDICES
imf.dat

The first method only inputs the solar wind velocity, density,
temperature and IMF.


</command>

<command name="NGDC_INDICES">
	<parameter name="cFileName" type="string" length="80" />

#NGDC_INDICES
spidr.dat

The second method takes data from the NOAA SPIDR interface.  You can
download almost all of the parameters in this format.

</command>

<command name="NOAAHPI_INDICES">
	<parameter name="cFileName" type="string" 
		default="" length="80" />

#NOAAHPI_INDICES
power_1998.txt

The third method only accepts HPI data from the NOAA satellites.

</command>

</commandgroup>

<commandgroup name="Information">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="DEBUG">
	<parameter name="iDebugLevel" type="integer" default="0" />
	<parameter name="iDebugProc"  type="integer" default="0" />
	<parameter name="DtReport"    type="real" default="10.0" />
	<parameter name="UseBarriers" type="logical" default="F" />

#DEBUG
1			iDebugLevel
8			iDebugProc
60.0			DtReport
F			UseBarriers

Sometimes debugging can be a real pain.  This command makes it
slightly easier by allowing you to output more stuff.  The {\tt
iDebugLevel} variable controls the amount of information output, with
0 outputting only a time-step and a message when output files are
written, and 10 being a torrent of so much information you can't read
it all.  You can also choose which CPU is outputting the information -
remember that MPI counts from 0 (not from 1, as most people do).  The
{\tt DtReport} variable says how often the time-report is given.  The
{\tt UseBarriers} variable is supposed to stop the code fairly often
to make sure all of the processors are on the same page, but there is
a bug in this is the {\tt \#SATELLITES} are used (don't ask).

</command>

</commandgroup>

<commandgroup name="The Control of Nature">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The GITM code development has been aimed toward making the code quite versatile.  
This means that most
fundamental parameters have flags so you can turn them off and on.
Most of the time, these should be left on, since all of the being {\tt
T} means that you are running the ``physically correct'' condition.
But, if you want to turn something off to experiment with the physics,
you can do this.

Some of these are not really physically consistent yet.  For example,
the variable {\tt UseDiffusion} turns off both the Eddy and Molecular
diffusion in the neutral density calculations, but leaves the Eddy
diffusion on in the temperature equation.  Also, if you turn off {\tt
UseConduction}, the Eddy diffusion in the temperature equation is
turned off.  So, things need to be fixed a little bit.  Most of the
options really only turn off one thing, though.

This is for the neutral temperature equations and {\bf not} for the
electron and ion equations.

<command name="THERMO">
	<parameter name="UseSolarHeating"   type="logical" default="T" />
	<parameter name="UseJouleHeating"   type="logical" default="T" />
	<parameter name="UseAuroralHeating" type="logical" default="T" />
	<parameter name="UseNOCooling  "    type="logical" default="T" />
	<parameter name="UseOCooling   "    type="logical" default="T" />
	<parameter name="UseConduction "    type="logical" default="T" />

#THERMO
T		 	UseSolarHeating
T			UseJouleHeating
T		 	UseAuroralHeating
T		 	UseNOCooling
T		 	UseOCooling
T		 	UseConduction

</command>

<command name="DIFFUSION">
	<parameter name="UseDiffusion" type="logical" default="" />

#DIFFUSION
T

This only applies to the neutral densities, and includes both Eddy and
Molecular diffusion.  It should be separated shortly.

</command>

<command name="FORCING">
	<parameter name="UsePressureGradient" type="logical" default="T" />
	<parameter name="UseIonDrag      "    type="logical" default="T" />
	<parameter name="UseViscosity    "    type="logical" default="T" />
	<parameter name="UseCoriolis     "    type="logical" default="T" />
	<parameter name="UseGravity      "    type="logical" default="T" />

#FORCING
T		UsePressureGradient
T		UseIonDrag
T		UseViscosity
T		UseCoriolis
T		UseGravity

The {\tt UsePressureGradient} variable is ignored in this version of
GITM, since pressure solved for self-consistently within the solver.
Everything else works as a source term (in {\tt calc_sources.f90},
except if {\tt UseGravity = F}, gravity is zeroed in {\tt
initialize.f90}.

</command>

<command name="IONFORCING">
	<parameter name="UseExB             "    type="logical" default="T" />
	<parameter name="UseIonPressureGradient" type="logical" default="T" />
	<parameter name="UseIonGravity      "    type="logical" default="T" />
	<parameter name="UseNeutralDrag     "    type="logical" default="T" />

#IONFORCING
T		UseExB
T		UseIonPressure
T		UseGravity
T		UseNeutralDrag



All of these variables are used within {\tt calc_ion_v.f90}.

</command>

<command name="CHEMISTRY">
	<parameter name="UseIonChemistry" type="logical" default="" />
	<parameter name="UseIonAdvection" type="logical" default="" />
	<parameter name="UseNeutralChemistry" type="logical" default="" />

#CHEMISTRY
T		UseIonChemistry
T		UseIonAdvection	
T		UseNeutralChemistry

You can turn off the chemistry and the ion advection with these terms.


</command>

<command name="ELECTRODYNAMICS">
	<parameter name="DtPotential" type="real" default="60.0" />
	<parameter name="DtAurora"    type="real" default="60.0" />

#ELECTRODYNAMICS
60.0			DtPotential [s]
60.0			DtAurora    [s]

The electric potential and aurora are two of the most expensive
routines to run.  In addition, they typically don't change on a
global-scale on more than a 1-minute cadence.  So, you can set these
values to something on the order of 60 seconds.  If you are using
higher temporal resolution IMF parameters, you can set them as low as
you want.
  
</command>

</commandgroup>

<commandgroup name="Controlling the Grid">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="GRID">
	<parameter name="nBlocksLon"  type="integer" default="1" />
	<parameter name="nBlocksLat"  type="integer" default="1" />
	<parameter name="LatStart"    type="real" default="-90.0" 
		min="-91.0" max="90.0"/>
	<parameter name="LatEnd  "    type="real" default="90.0"
		min="-90.0" max="91.0" />
	<parameter name="LonStart"    type="real" default="180.0" 
		min="-180.0" max="360.0" />

#GRID
8			nBlocksLon
4			nBlocksLat
-90.0			LatStart
90.0			LatEnd
180.0			LonStart

If LatStart and LatEnd are set to less than -90 and
greater than 90, respectively, then GITM does a whole
sphere.  If not, it models between the two.
If you want to do 1-D, set nLons=1, nLats=1 in
ModSize.f90, then recompile, then set LatStart
and LonStart to the point on the Globe you want
to model.

</command>

<command name="STRETCH">
	<parameter name="ConcentrationLatitude" type="real" default="65.0" 
		min="-90.0" max="90.0"/>
	<parameter name="StretchingPercentage"  type="real" default="0.0" 
		min="0.0" max="1.0" />
	<parameter name="StretchingFactor"    type="real" default="" 
		min="0.0" max="10.0" />

#STRETCH
65.0  			ConcentrationLatitude
0.0   			StretchingPercentage
1.0  			StretchingFactor

The stretched grid is concentrated around the ConcentrationLatitude.
The stretching is controlled by StretchingPercentage: 0 means no
stretching, 1.0 means a lot. The StretchingFactor provides further control:
greater than 1 means stretch less, less than 1 means stretch more.

</command>

<command name="ALTITUDE">
	<parameter name="AltMin" type="real" default="95.0" 
		min="0.0" />
	<parameter name="AltMax" type="real" default="600.0" 
		min="$AltMin"/>
	<parameter name="UseStretchedAltitude" type="logical" default="T" />

#ALTITUDE
95.0			AltMin (km)
600.0			AltMax (km)
T			Stretched grid in altitude

</command>
</commandgroup>

<commandgroup name="Output">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="SAVEPLOT" alias="SAVEPLOTS">
	<parameter name="DtRestart" type="real"    min="-1" default="3600"/>
	<parameter name="nPlotFile" type="integer" min="0"  default="1"/>
	<for from="1" to="$nPlotFile">
		<parameter name="TypePlotFile" type="string" input="select">
			<option name="3DALL" default="T"/>
			<option name="1DALL"/>
			<option name="2DGEO"/>
			<option name="2DMAG"/>
			<option name="3DNEUTRAL"/>
			<option name="3DION"/>
		</parameter>
		<parameter name="DtPlotFile" type="real" min="0" 
							default="3600"/>
	</for>

#SAVEPLOT
3600.0			DtRestart [s]
1			nPlotFile
3DALL			TypePlotFile
900.0			DtPlotFile [s]

The DtRestart determines the frequency of saving restart files. 
If negative, no restart files are saved by GITM itself (but the SWMF can
still make GITM save its restart files). The number of plot files is
given by nPlotFile. For each plot file the type and the saving
frequency are given by the parameters TypePlotFile and DtPlotFile, 
respectively.

The default is DtRestart=-1 and nPlotFile=0
</command>

<command name="SATELLITES">
	<parameter name="nSats "    type="integer" max="20" default="0" />
	<for from="1" to="$nSats">
		<parameter name="SatFile1"  type="string" />
		<parameter name="DtPlot1"   type="real"   />
	</for>

#SATELLITES
2
guvi.2002041623.in
15.0
stfd.fpi.in
60.0

</command>

</commandgroup>

<rule expr="-d 'UA/restartOUT' or not $_IsFirstSession">
        Directory UA/restartOUT should exist!
</rule>

<rule expr="-d 'UA/data' or not $_IsFirstSession">
        Output directory UA/data should exist!
</rule>


</commandList>