PARAM.XML

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

<commandList name="Control Module">

CON reads input parameters from the PARAM.in file and the files
included into PARAM.in. All commands interpreted by CON start
with the # character followed by capital letters and numbers.
The commands can have an arbitrary number of parameters, 
which are written into the lines following the command. 
Other lines are ignored, and can be used for remarks.
The general format of the parameter file is

#COMMANDNAME1
variable1
variable2

#COMMANDNAME2

#COMMANDNAME3
variable3

The #BEGIN_COMP ID and #END_COMP ID commands are exceptional in the sense 
that their parameters are written in the same line as the command itself.
This exception makes the parameter file more readable. The parameter
is the two-character component ID. There must be exactly one space
between the #BEGIN_COMP or #END_COMP string and the ID.
The lines between the #BEGIN_COMP ID and the matching 
#END_COMP ID commands are passed to the component with the
corresponding ID. For example 

#BEGIN_COMP GM

#AMR
-1

#END_COMP GM

The parameters passed to the components can be of arbitrary format.
The only restriction is that the length of the lines cannot exceed
100 characters (extra characters will be ignored).

<!-- Initial defaults which are needed for rules -->
<set name="IsTimeAccurate" type="logical" value="T" />

<commandgroup name="GENERAL COMMANDS">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!! GENERAL COMMANDS !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="INCLUDE">
        <parameter name="NameIncludeFile" type="string" 
		default="RESTART.in" length="100" />

#INCLUDE
RESTART.in		NameIncludeFile

The NameIncludeFile parameter contains the name of the file to be included.
The file name may be followed with a trailing comment if it
is separated with at least 3 spaces or one TAB character.
The #INCLUDE command can be used anywhere in the parameter file,
even in the sections which contain the component specific parameters.
For example the information in the run/GM/restartIN/restart.H 
file or parameters specific to a component can be included.
</command>

<command name="END">

#END

The #END command signals the end of the included file or the
end of the PARAM.in file. Lines following the #END command are
ignored. It is not required to use the #END command. The end
of the included file or PARAM.in file is equivalent with an 
#END command in the last line.
</command>

<command name="STRICT" multiple="T">
	<parameter name="UseStrict" type="logical" default="T" />
#STRICT
T                       UseStrict

If UseStrict is true, the SWMF does not attempt to correct problems,
but it stops after the warning message. If it is set to false, SWMF
attempts to correct the problems after the warning message is issued.
It is possible to switch back and forth between strict and non-strict mode. 
A typical use is to switch off strict mode when a component is switched off
in a session so some of the processors are idling. Once all processors are
used, it is a good idea to switch back to strict mode.

The default is strict mode.
</command>

<command name="DESCRIPTION" multiple="T">
	<parameter name="StringDescription" type="string" length="400" />

#DESCRIPTION
This is a test run for GM-IE-UA coupling.

The StringDescription string can be used to describe the simulation 
for which the parameter file is written. The #DESCRIPTION command and 
the StringDescription string are saved into the restart file, 
which helps in identifying the restart files.

The default value is "Please describe me!", which is self explanatory.
</command>

</commandgroup>

<commandgroup name="TIME AND SESSION CONTROL">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!! TIME AND SESSION CONTROL  !!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The execution of SWMF is done in consecutive sessions. Each session is
executed with a set of parameters read from the parameter file.
After the session is finished, CON reads and distributes the parameters for
the next session. Parameters from previous sessions are carried over,
so only the changes relative to the previous session need to be given.

<command name="RUN">
	 <set name="_STOP" type="logical" value="F"/>
#RUN

The #RUN command does not have any parameters. It signals the end
of the current session, and makes CON execute the session with
the current set of parameters. The parameters for the next session
start after the #RUN command. For the last session there is no
need to use the #RUN command, since the #END command or simply
the end of the PARAM.in file makes CON execute the last session.
</command>

<command name="TIMEACCURATE">
	<parameter name="IsTimeAccurate" type="logical" default="T" />

#TIMEACCURATE
F		IsTimeAccurate

If IsTimeAccurate is set to true, the SWMF is solving
a time dependent problem. If IsTimeAccurate is false, a steady-state
solution is sought for. It is possible to use steady-state mode
in the first few sessions to obtain a steady state solution,
and then to switch to time accurate mode in the following sessions.
In time accurate mode the frequency of coupling, saving restart files,
or stopping conditions are taken in simulation time, which is the
time relative to the initial time. In steady state mode the simulation
time is not advanced at all, instead the time step or iteration number
is used to control the frequencies of various actions.

The steady-state mode also allows the components to use various
acceleration techniques. For example the BATSRUS code (in the GM, IH, SC
components) can use local time stepping to accelerate convergence
to steady state. In steady state mode the various components 
are allowed to use different number of iterations per global iteration, 
thus they can converge to steady state more optimally (see the #CYCLE command).

The default value is the time accurate mode.
</command>

<command name="STARTTIME" if="$_IsFirstSession" multiple="T">
	<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"/>
	<parameter name="FracSecond" type="real" min="0" max="1"  default="0"/>

#STARTTIME
2000			iYear
   3			iMonth
  21			iDay
  10			iHour
  45			iMinute
   0			iSecond
   0.0			FracSecond

The #STARTTIME command sets the initial date and time for the
simulation in Greenwich Mean Time (GMT) or Universal Time (UT).
This time is stored in the restart files. It can be overwritten
with another #STARTTIME command if necessary.

The default values are shown above.  This is a date and time when, for
the Earth, both the rotational and the magnetic axes have
approximately zero tilt towards the Sun.
</command>

<command name="ENDTIME">
	<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"/>
	<parameter name="FracSecond" type="real" min="0" max="1"  default="0"/>
	<set name="TimeMax" type="real" value="0"/>
	<set name="_ENDTIME" type="logical" value="1"/>

#ENDTIME
2000			iYear
   3			iMonth
  22			iDay
  10			iHour
  45			iMinute
   0			iSecond
   0.0			FracSecond

This command can only be used in time accurate mode and in the final session.

The #ENDTIME command sets the date and time in Greenwich Mean Time
(GMT) or Universal Time (UT) when the simulation should be ended.
This is an alternative to the #STOP command in the final session.
This time is stored in the final restart file as the start time for
the restarted run, and the tSimulation parameter of the #TIMESIMULATION 
and the nStep parameter of the #NSTEP commands are set to zero.
This avoids accumulation of tSimulation or nStep for continuously
restarted runs.

There is no default value.
</command>

<command name="TIMESIMULATION" if="$_IsFirstSession" multiple="T">
	<parameter name="tSimulation" type="real" min="0" default="0.0" />

#TIMESIMULATION
1 hour			tSimulation [sec]

The tSimulation variable contains the simulation time in seconds
relative to the initial time set by the #STARTTIME command.
The #TIMESIMULATION command and tSimulation are saved into the restart file, 
so that the simulation can continue from the same time when the 
restart was saved.   It can be overwritten
with another #TIMESIMULATION command if necessary.
The default value is tSimulation=0.
</command>

<command name="NSTEP" if="$_IsFirstSession" multiple="T">
	<parameter name="nStep" type="integer" min="0" default="0" />

#NSTEP
100                     nStep

The nStep variable contains the number of time steps since the
beginning of the simulation (including all restarts). 
The #NSTEP command and the nStep variable  are saved into the restart file, 
so that the simulation can continue from the same time step when
the restart was saved. It can be overwritten with another #NSTEP 
command if necessary.
The default value is nStep=0.
</command>

<command name="STOP">
	<parameter name="MaxIter" type="integer" min="-1" default="-1" />
	<parameter name="TimeMax" type="real"    min="-1" default="-1" />
	<set name="_STOP" type="logical" value="1"/>

#STOP
100			MaxIter
1.5 hour                TimeMax

The MaxIteration variable contains the
maximum number of iterations {\it since the beginning of the current run}
(in case of a restart, the time steps done before the restart do not count).
If nIteration reaches this value the session is finished.
The tSimulationMax variable contains the maximum simulation time
relative to the initial time determined by the #STARTTIME command.
If tSimulation reaches this value the session is finished.

Using a negative value for either variables means that the
corresponding condition is  not checked. If TimeMax is negative
in time accurate mode or MaxIter is negative in steady state mode,
the code stops with an error message. If the values are set to zero,
the code will run and stop as normal, but not advance the solution.
The #STOP command must be used in every session. The only exception is the last
session, where the #ENDTIME command can be used instead of #STOP in
time-accurate mode.

If the code completes the last session of the run successfully, 
both the SWMF.SUCCESS and the SWMF.DONE files are created in the 
run directory.
</command>

<command name="CHECKTIMESTEP">
  <parameter name="DoCheckTimeStep" type="logical" default="T"/>
  <if expr="$DoCheckTimeStep">
    <parameter name="DnCheckTimeStep" type="integer" minimum="2" default="10"/>
    <parameter name="TimeStepMin" type="real" minimum="-1" default="-1"/>
  </if>

#CHECKTIMESTEP
T		DoCheckTimeStep (rest is read if true)
10		DnCheckTimeStep (2 or more)  
-1.0		TimeStepMin [s] (negative value means SessionTime/10,000,000)

This command is only effective in time accurate mode. The goal is to
avoid a simulation stalling with infinitesimal time steps. 

If DoCheckTimeStep is true, then check if the average time advance
over DnCheckTimeStep iterations is smaller than TimeStepMin, and if it is,
stop the simulation with an error message. The check is performed every
nCheckTimeStep iterations on all active processors of the SWMF.
A positive TimeStepMin is the minimum average time advance in units of seconds.
A negative TimeStepMin value is replaced with the simulation time of the
session divided by ten million, which assumes that a session should be
completed in less than ten million iterations. 

Default values are shown above, so the check is active by default.
</command>

<command name="CHECKKILL">
	 <parameter name="NameCompCheckKill" type="string" length="2"
	 	    default="!!"/>

#CHECKKILL
GM		NameCompCheckKill

The SWMF can check periodically if the SWMF.KILL file exists in the run
directory, and kill the execution if it does. This file gets removed
at the beginning of the run so that new runs don't get killed accidentally.
This check is done from the root processor of the
component NameCompCheckKill in the SWMF time loop. This means that
the component doing the check will not get interrupted at an arbitrary
point of execution (e.g. writing output files). The other components
sharing the same processor will also be safe. Components running on
a separate subset of processors may get interrupted at a more-or-less
arbitrary point of execution.

If NameCompCheckKill is set to the string '??' then all processors check
for the SWMF.KILL file. This makes sure that the run gets terminated
essentially immediately. If NameCompCheckKill is set to the string '!!'
then no check is performed at all. Otherwise NameCompCheckKill should
contain the component ID of a component present in the
#COMPONENTMAP command.

If the code gets killed, no SWMF.SUCCESS or SWMF.DONE files are created.

The default value is NameCompCheckKill='!!', i.e. no check is performed.
</command>

<command name="CHECKSTOP">
	<parameter name="DoCheckStop" type="logical" default="F" />
	<if expr="$DoCheckStop">
		<parameter name="DnCheckStop" type="integer" min="-1" 
							default="-1" />
		<parameter name="DtCheckStop" type="real"    min="-1" 
							default="-1" />
	</if>

#CHECKSTOP
T			DoCheckStop
-1			DnCheckStop
10.0			DtCheckStop

The DoCheckStop variable controls whether CON should
check the CPU time or the existence of the SWMF.STOP file in the
run directory. If it is set to false, there is no checking.
If it is set to true, the stop conditions are checked at the
frequencies given by the DnCheckStop and DtCheckStop variables.
The DnCheckStop variable determines the frequency in terms of
the time step number nStep, while  DtCheckStop determines the
frequency in terms of the simulation time tSimulation.
Negative values for either variable mean that the corresponding condition
is not checked. For time accurate mode DtCheckStop, for
steady-state mode DnCheckStop is the relevant frequency.

The default value is DoCheckStop=.false., because the checks require
synchronization of the components. The more frequent the checks
are the less efficient the execution.  On the other hand the
less frequent the checks are, the less control the user has to stop
the code at a given time.

If the code is stopped this way for any reason (for example the
CPU time maximum is reached or the SWMF.STOP file was used), 
an SWMF.SUCCESS file is created but no SWMF.DONE file is created.
</command>

<command name="CHECKSTOPFILE">
	<parameter name="DoCheckStopFile" type="logical" default="T" />

#CHECKSTOPFILE
T			DoCheckStopFile

If DoCheckStopFile is true (and DoCheckStop is set
to true in the #CHECKSTOP command) then the code checks if the
SWMF.STOP file exists in the run directory. This file is deleted at
the beginning of the run, so the user must explicitly create the file
with, for example, the "touch SWMF.STOP" UNIX command. 
If the file is found in the run directory,
the execution stops in a graceful manner.
Restart files and plot files are saved as required by the
appropriate parameters.

The default is DoCheckStopFile=.true. (but the default for DoCheckStop
is .false.).
</command>

<command name="CPUTIMEMAX">
	<parameter name="CpuTimeMax" type="real" min="-1" default="-1" />

#CPUTIMEMAX
7.5 hours                   CpuTimeMax [sec]

The CpuTimeMax variable contains the maximum allowed CPU time (wall clock
time) for the execution of the current run. If the CPU time reaches
this time, the execution stops in a graceful manner.
Restart files and plot files are saved as required by the
appropriate parameters.
This command is very useful when the code is submitted to a batch
queue with a limited wall clock time.

The default value is -1.0, which means that the CPU time is not checked.
To do the check the CpuTimeMax variable has to be set to a positive
value and the DoCheckStop variable also must be set to .true. 
in the #CHECKSTOP command.
</command>

</commandgroup>

<commandgroup name="TESTING AND TIMING">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!  TESTING AND TIMING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
<command name="TESTINFO">
  <parameter name="DoWriteCallSequence" type="logical" default="F"/>

#TESTINFO
T		DoWriteCallSequence

If DoWriteCallSequence is set to true, the code will attempt to produce
a call sequence from the CON_stop subroutine (which is called when the
code finds an error) by making an intentional floating point exception.
This will work only if the compiler is able to and requested to produce a
call sequence. The NAGFOR compiler combined with the -debug flag can do that.

Default is DoWriteCallSequence=F.
</command>

<command name="TEST">
  <parameter name="StringTest" type="string" length="200"/>

#TEST
do_session			StringTest

A space separated list of subroutine and function names to be tested. 
Only subroutines containing the 'call CON_set_do_test(...)' statement
can be tested. The first argument is the name of the subroutine,
usually defined as the string parameter 'NameSub'.
Default is an empty string.
</command>

<command name="TESTPROC">
  <parameter name="iProcTest" type="integer" min="0" default="0"/>

#TESTPROC
1			iProcTest

The test information will be written from iProcTest when DoTestMe is used
in the SWMF. Default value is 0.
</command>

<command name="VERBOSE">
  <parameter name="lVerbose" type="integer" input="select">
    <option name="errors and warnings only" value="0" />
    <option name="normal"                   value="1" default="T"/>
    <option name="calls on test processor"  value="10" />
    <option name="calls on all processors"  value="100" />
  </parameter>

#VERBOSE
100			lVerbose

The lVerbose variable sets the verbosity of CON.\\
If lVerbose=0 the verbose information is minimized.\\
If lVerbose=1 some verbose information is printed in CON_main and CON_io
    from processor zero.\\
If lVerbose=10, processor zero will produce a line on the standard output
    with the name of the subroutine and the iteration number 
    for all subroutines which call CON_set_do_test.\\
If lVerbose=100, all processors and all subroutines which call CON_set_do_test
    will produce a line on the standard output with the 
    name of the subroutine, the iteration number and the processor number.\\
The default value is lVerbose=1.
</command>

<command name="TIMING">
	<parameter name="UseTiming" type="logical" default="T" />
	<if expr="$UseTiming">
		<parameter name="DnTiming" type="integer" input="select">
			<option name="none"              value="-3" />
			<option name="final only"        value="-2" 
								default="T" />
	                <option name="end of sessions"   value="-1" />
			<optioninput name="every X steps" min="1" 
							default="100" />
		</parameter>
		<parameter name="nDepthTiming" type="integer" min="-1" 
							default="-1" />
		<parameter name="TypeTimingReport" type="strings" 
							min="1" max="2">
			<part name="TypeTimingStyle" type="string" required="T"
								input="select">
				<option name="cumulative" value="cumu" 
								default="T" />
				<option name="list" />
				<option name="tree" />
			</part>
			<part name="UseTimingAll" type="string" required="F"
								input="select">
				<option name="all" />
			</part>
		</parameter>
	</if>

#TIMING
T                       UseTiming        rest of parameters read if true
-2                      DnTiming         -3 none, -2 final, -1 each session
-1                      nDepthTiming     -1 for arbitrary depth
tree all		TypeTimingReport 'cumu','list','tree', +optional 'all'

If UseTiming=.true., the execution is timed by the TIMING utility.\\
If UseTiming=.false., the execution is not timed.\\

\noindent
The DnTiming parameter determines the frequency of timing reports:\\
If DnTiming is positive, a timing report is produced every DnTiming steps.\\
If DnTiming is -1, a timing report is shown at the end of each session.\\
If DnTiming is -2, a timing report is shown at the end of the whole run.\\
If DnTiming is -3, no timing report is shown.\\

\noindent
The nDepthTiming parameters defines the depth of the timing tree.\\
A negative value means unlimited depth.\\
If nDepthTiming is 1, only the total SWMF execution is timed.\\

\noindent
The TypeTimingReport parameter determines the format of the timing reports:
\begin{verbatim}
'cumu' - cumulative list sorted by timings
'list' - list based on caller and sorted by timings
'tree' - tree based on calling sequence.
\end{verbatim}
If the word 'all' is added, the timing is done on all the CPU-s.
By default only the root CPUs of the components do timings.
When all the CPU-s are timed, it is probably a good idea to 
direct the output into separate files (see the #STDOUT command).

The default values are shown above, except for the 
TimingReportStyle, which is 'cumu' by default without the 'all'.
</command>

<command name="PROGRESS">
	<parameter name="DnProgressShort" type="integer" min="-1" 
		default="10"  />
	<parameter name="DnProgressLong"  type="integer" min="-1" 
		default="100" />
#PROGRESS
10			DnProgressShort
100			DnProgressLong

The DnShowProgressShort and DnShowProgressLong variables determine
the frequency of showing short and long progress reports in terms
of the number of time steps nStep. The short progress report
consists of a single line which shows the number of time steps,
simulation time and CPU time. The long progress report also shows
a small timing report on the root processor.
Negative values indicate that no report is requested.

The default values are DnShowProgressShort=10 and DnShowProgressLong=100.
</command>

<command name="PRECISION" if="$_IsFirstSession">
	<parameter name="nByteReal" type="integer" input="select">
		<option name="single precision (4)" value="4" 
			default="$nByteReal==4"	/>
		<option name="double precision (8)" value="8"
			default="$nByteReal==8"	/>
	</parameter>
	<rule expr="$nByteReal==$_nByteReal or not $UseStrict">
		nByteReal in file must agree with _nByteReal in strict mode.
	</rule>

#PRECISION
8			nByteReal

The nByteReal variable gives the number of bytes in the default real variable. 
Possible values are 4 and 8. This command serves to check consistency with 
binary data, such as binary restart files. 
The #PRECISION command and the nByteReal variable
are saved into the restart file. If the compiled precision differs from
the one defined by nByteReal, the code stops with an error message
in strict mode. If the strict mode is switched off with the #STRICT
command, only a warning is printed.

There is no default value. If the command is not used, the precision of 
the real numbers is not checked.
</command>

<command name="VERSION" if="$_IsFirstSession">
	<parameter name="VersionSwmf" min="0" default="1.0" type="real" />

#VERSION
1.0                    VersionSwmf

The VersionSwmf variable contains the version number of SWMF. This command
serves to check consistency for restarted runs. The #VERSION command
and the Version variable are saved into the restart file.

There is no default value. If the command is not used, the version
number is not checked.
</command>

</commandgroup>

<commandgroup name="COMPONENT CONTROL">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!! COMPONENT CONTROL !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The session model allows concurrent execution of the components.
The components are synchronized only when conditions for the actions of 
coupling, saving restart files, or stopping execution are met. 
This is possible because it is known in advance by each component when 
these actions will occur. In time accurate mode the components are 
required to make a time step which does not exceed the next synchronization
time. In steady state mode there is no limit on the time step, and 
components can be called at different frequencies.
Components which are not used in a session can be switched off.

<command name="#COMPONENTMAP" multiple="F" alias="LAYOUT">
  <foreach values="$_Components">
    <parameter name="CompMap" type="strings" min="1" max="5">
      <part name="NameComp"  type="string"  length="2" required="T"/>
      <part name="ProcFirst" type="integer" default="0" required="T"/>
      <part name="ProcLast"  type="integer" default="$ProcFirst" required="T"/>
      <part name="Stride"    type="integer" default="1"          required="T"/>
      <part name="nThread"   type="integer" default="$Stride"    required="F"/>
    </parameter>
  </foreach>

ID Proc0 ProcEnd Stride nThread TAB SEPARATED comment
#COMPONENTMAP
IE  0  0  1           CompMap IE runs on PE 0
PW  1 32  4  4        CompMap PW runs on PEs 1..32 with  4 threads
GM 33 -1 16 16        CompMap GM runs on PEs 33... with 16 threads

ID Proc0 ProcEnd Stride nThread  TAB SEPARATED comment
#LAYOUT
GM  0 -3 -2 -2        CompMap GM runs on PEs ..nProc-3 with MaxThread/2 threads
PC  0 -3 -1 -1        CompMap PC runs on PEs ..nProc-3 with MaxThread threads
IM -2 -2  1           CompMap IM runs on PE  nProc-2
IE -2 -1  1           CompMap IE runs on PEs nProc-2 and nProc-1

The #COMPONENTMAP (or #LAYOUT) command lists the active components and
their processor layout including the number of OpenMP threads for
components that can run with OpenMP. To use multithreading, the code
needs to be configured with the -openmp flag.  The list of components
should be ended with an empty line.

The columns contain the component ID, the index of the first (root)
processor for the component, the last processor, the stride, and the
optional number of threads, respectively. Negative values for the
root and last processor ranks are taken as counting backwards
from the total number of processors nProc. Negative values for the
stride and number of threads are interpreted as the maximum number of
threads (MaxThread is defined by the OMP_NUM_THREADS environment
variable) divided by the absolute value of Stride or nThread,
respectively.  This allows the same layout to be used on different
nodes with different number of cores per node.  The default number of
threads is 1 and the maximum value is MaxThread.

This command is required either in the PARAM.in file or (for sake of backward
compatibility) in the now depreciated LAYOUT.in file. 
</command>

<command name="COMPONENT" multiple="T">
  <parameter name="NameComp" type="string" input="select">
    <option name="CZ" />
    <option name="EE" />
    <option name="GM" default="T"/>
    <option name="IE" />
    <option name="IH" />
    <option name="IM" />
    <option name="OH" />
    <option name="PC" />
    <option name="PS" />
    <option name="PT" />
    <option name="PW" />
    <option name="RB" />
    <option name="SC" />
    <option name="SP" />
    <option name="UA" />
  </parameter>
  <parameter name="UseComp" type="logical" default="T"/>
  <rule expr="$_Registered{$NameComp} or not $_Components">
    Component must be registered.
  </rule>
  <set name="_UsedComp{$NameComp}" type="logical" value="$UseComp"/>

#COMPONENT
IE			NameComp
F			UseComp

The NameComp variable contains the two-character component ID, 
while the UseComp variable defines if the component should be 
used in the current session or not. It is possible that in the 
initial sessions some components are not used, and they are turned on later.
Unused components should not be coupled, and they should not
be given any parameters.

The default is that all the components listed in the #COMPONENTMAP command
are used.
</command>

<command name="CYCLE" multiple="T">
  <parameter name="NameComp" type="string" input="select">
    <option name="CZ" />
    <option name="EE" />
    <option name="GM" default="T"/>
    <option name="IE" />
    <option name="IH" />
    <option name="IM" />
    <option name="OH" />
    <option name="PC" />
    <option name="PS" />
    <option name="PT" />
    <option name="PW" />
    <option name="RB" />
    <option name="SC" />
    <option name="SP" />
    <option name="UA" />
  </parameter>
  <parameter name="DnRun" type="integer" min="1" default="1"/>

#CYCLE
IH			NameComp
10			DnRun

The DnRun variable defines the frequency of calling component NameComp
during a steady state run. In the example IH will be called for 
nStep = 10, 20, 30, ... For time accurate runs this command has no effect.
The default is DnRun = 1 for all the active components.
</command>

</commandgroup>

<commandgroup name="COUPLING CONTROL">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!! COUPLING CONTROL !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

<command name="COUPLEORDER">
	<parameter name="nCouple" type="integer" min="0" max="38" 
		   default="10"/>
	<for from="1" to="$nCouple">
	    <parameter name="NameSourceTarget" type="string" length="5"/>
	</for>

#COUPLEORDER
5                       nCouple
IE GM                   NameSourceTarget
IE IM                   NameSourceTarget
GM IE                   NameSourceTarget
GM IM                   NameSourceTarget
IM GM                   NameSourceTarget

The nCouple variable determines the maximum number of couplings
among the components. The NameSourceTarget string contains the two
two-character IDs for the source and target components separated by
a space. The order of the couplings is most important for the
couplings done at the beginning of the session. Some components need
to get information from the others before they can initialize properly.
For example IM/RCM2 gets information from GM/BATSRUS. 

With respect to coupling between IE and the other components 
there are two strategies:

1. All components send information to IE first, then IE solves for 
   the potential and sends it back to all the other components.

2. IE sends information based on its current state first, then receives info
   from the other components, and solves for the potential in parallel with the
   other components.

The default coupling order follows the first strategy. In this case
IE runs in a serial mode, so it should share processors with one of the 
components that are coupled to IE. 

The example shown above follows the second strategy, which leads to 
concurrent execution IF the layout puts IE on a processor
that is NOT shared with the slowest of the components 
(typically GM, sometimes IM). 
To use the second strategy it is simplest to add the

#INCLUDE
Param/CoupleOrderFast

command into the PARAM.in file. The Param/CoupleOrderFast contains the 
coupling order that allows concurrent execution of IE.

NOTE: The #COUPLEORDER command defines only the order of the couplings, 
so it can list couplings that are not active in a run. 

NOTE: The order of the 'SC SP' and 'IH SP' couplings should not be reversed!

The default coupling order is specified by the iCompCoupleOrder_II array
initialized in the \\
CON/Coupler/src/CON_coupler.f90 file.
</command>

<command name="COUPLE1" multiple="T">
	<parameter name="NameSource" type="string"  length="2"              />
	<parameter name="NameTarget" type="string"  length="2"              />
	<parameter name="DnCouple"   type="integer" min="-1" default="-1"   />
	<parameter name="DtCouple"   type="real"    min="-1" default="-1.0" />
	<rule expr="$_UsedComp{$NameSource} or not $_Components">
		Source component must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameTarget} or not $_Components">
		Target component must be registered and ON.
	</rule>
	<rule expr="$NameSource ne $NameTarget">
		Source and target components must be different.
	</rule>

#COUPLE1
IE			NameSource
IM			NameTarget
-1			DnCouple
10.0			DtCouple

The NameSource and NameTarget variables contain the two-character 
component ID-s for the source and target components. 
The DnCouple variable determines the frequency
of couplings in terms of the number of time steps nStep for steady state
runs, while DtCouple defines the frequency in terms of the simulation
time tSimulation in seconds for time-accurate runs. Setting both
frequencies to a negative value means that there is no coupling.

The default is no coupling between the components.
</command>

<command name="COUPLE2" multiple="T">
	<parameter name="NameComp1" type="string"  length="2"              />
	<parameter name="NameComp2" type="string"  length="2"              />
	<parameter name="DnCouple"  type="integer" min="-1" default="-1"   />
	<parameter name="DtCouple"  type="real"    min="-1" default="-1.0" />
	<rule expr="$_UsedComp{$NameComp1} or not $_Components">
		Component 1 must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameComp2} or not $_Components">
		Component 2 must be registered and ON.
	</rule>
	<rule expr="$NameComp1 ne $NameComp2">
		Components 1 and 2 must be different.
	</rule>

#COUPLE2
GM			NameComp1
IE			NameComp2
-1			DnCouple
10.0			DtCouple

The NameComp1 and NameComp2
variables contain the two-character component ID-s for the two
components which are coupled both ways.
The DnCouple variable determines the frequency
of couplings in terms of the number of time steps nStep for steady state runs, 
while DtCouple defines the frequency in terms of the simulation
time tSimulation in seconds for time-accurate runs. Setting both
frequencies to a negative value means that there is no coupling.

The default is no coupling between the components.
</command>

<command name="COUPLE1SHIFT" multiple="T">
	<parameter name="NameSource" type="string"  length="2"              />
	<parameter name="NameTarget" type="string"  length="2"              />
	<parameter name="DnCouple"   type="integer" min="-1" default="-1"   />
	<parameter name="DtCouple"   type="real"    min="-1" default="-1.0" />
	<parameter name="nNext12"    type="integer" min="-1" max="$DnCouple"
							default="0.0"       />
	<parameter name="tNext12"    type="real"    min="-1" max="$DtCouple"
							default="0.0"       />
	<rule expr="$_UsedComp{$NameSource} or not $_Components">
		Source component must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameTarget} or not $_Components">
		Target component must be registered and ON.
	</rule>
	<rule expr="$NameSource ne $NameTarget">
		Source and target components must be different.
	</rule>

#COUPLE1SHIFT
IH			NameSource
GM			NameTarget
-1			DnCouple
10.0			DtCouple
-1			nNext12
3.0			tNext12

The NameSource and NameTarget
variables contain the two-character component ID-s for the source
and target components. The DnCouple variable determines the frequency
of couplings in terms of the number of time steps nStep for steady state
runs, while DtCouple defines the frequency in terms of the simulation
time tSimulation in seconds for time-accurate runs.

For steady-state simulations the nNext12 variable determines in which time
step the first coupling occurs after the initial coupling, namely
when mod(nStep,DnCouple) equals nNext12. For time accurate
simulations the tNext12 variable determines at what simulation
time the first coupling occurs after the initial coupling, namely
when mod(tSimulation,DtCouple) equals tNext12.

The above example will couple IH to GM at simulation times 3, 13, 23, etc.

The default is no shifting.
</command>

<command name="COUPLE2SHIFT" multiple="T">
	<parameter name="NameComp1" type="string"  length="2"              />
	<parameter name="NameComp2" type="string"  length="2"              />
	<parameter name="DnCouple"  type="integer" min="-1" default="-1"   />
	<parameter name="DtCouple"  type="real"    min="-1" default="-1.0" />
	<parameter name="nNext12"   type="integer" min="-1" max="$DnCouple"
							default="0.0"       />
	<parameter name="tNext12"   type="real"    min="-1" max="$DtCouple"
							default="0.0"       />
	<parameter name="nNext21"   type="integer" min="-1" max="$DnCouple"
							default="0.0"       />
	<parameter name="tNext21"   type="real"    min="-1" max="$DtCouple"
							default="0.0"       />
	<rule expr="$_UsedComp{$NameComp1} or not $_Components">
		Component 1 must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameComp2} or not $_Components">
		Component 2 must be registered and ON.
	</rule>
	<rule expr="$NameComp1 ne $NameComp2">
		Components 1 and 2 must be different.
	</rule>

#COUPLE2SHIFT
GM                 NameComp1
IE                 NameComp2
-1                 DnCouple
10.0               DtCouple
-1                  nNext12
3.0                tNext12
-1                 nNext21
6.0                tNext21

The NameComp1 and NameComp2
variables contain the two-character component ID-s for the two
components which are coupled both ways.
The DnCouple variable determines the frequency
of couplings in terms of the number of time steps nStep for steady state
runs, while DtCouple defines the frequency in terms of the simulation
time tSimulation in seconds for time-accurate runs.

For steady-state simulations the nNext12 variable determines in which time
step the first coupling occurs from NameComp1 to NameComp2
after the initial coupling, namely
when mod(nStep,DnCouple) equals nNext12. For time accurate
simulations the tNext12 variable determines at what simulation
time the first coupling occurs from NameComp1 to NameComp2
after the initial coupling, namely
when mod(tSimulation,DtCouple) equatls tNext12.

The first coupling step and time for the NameComp2 to NameComp1
coupling is determined by the nNext21 and tNext21 variables
in a similar fashion. This command allows to shift the couplings
relative to each other. 

The above example will couple GM to IE at simulation times 
3, 13, 23, etc, while IE will be coupled to GM at simulation times 
6, 16, 26 etc. 
This way IE can solve the potential problem while GM advances by 3 seconds.
That can improve the parallelization and efficiency.

The default is no shifting.
</command>

<command name="COUPLE1TIGHT" multiple="T">
	<parameter name="NameMaster" type="string"  length="2"    />
	<parameter name="NameSlave"  type="string"  length="2"    />
	<parameter name="DoCouple"   type="logical" default="T"   />
	<rule expr="$_UsedComp{$NameMaster} or not $_Components">
		Master component must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameSlave} or not $_Components">
		Slave component must be registered and ON.
	</rule>
	<rule expr="$NameMaster ne $NameSlave">
		Master and slave components must be different.
	</rule>

#COUPLE1TIGHT
GM			NameMaster
PT			NameSlave
T			DoCouple

Couple two components tightly one-way. Tight coupling means that the
two components must take identical time steps, and they are coupled 
every time step.

The NameMaster and NameSlave parameters contain the two-character 
component ID-s for the master and slave components. 
The tight coupling can be switched on or off with the DoCouple parameter.
Use the COUPLE2TIGHT command for two-way coupling.

The default is no coupling between the components.
</command>

<command name="COUPLE2TIGHT" multiple="T">
	<parameter name="NameMaster" type="string"  length="2"    />
	<parameter name="NameSlave"  type="string"  length="2"    />
	<parameter name="DoCouple"   type="logical" default="T"   />
	<rule expr="$_UsedComp{$NameMaster} or not $_Components">
		Master component must be registered and ON.
	</rule>
	<rule expr="$_UsedComp{$NameSlave} or not $_Components">
		Slave component must be registered and ON.
	</rule>
	<rule expr="$NameMaster ne $NameSlave">
		Master and slave components must be different.
	</rule>

#COUPLE2TIGHT
GM			NameMaster
PC			NameSlave
T			DoCouple

Couple two components tightly two-way. Tight coupling means that the
two components must take identical time steps, and they are coupled 
every time step.

The NameMaster and NameSlave parameters contain the two-character 
component ID-s for the master and slave components. 
The tight coupling can be switched on or off with the DoCouple parameter.
Use the COUPLE1TIGHT command for one-way coupling.

The default is no coupling between the components.
</command>

<command name="COUPLETIME" multiple="T">
  <parameter name="NameComp" type="string" input="select">
    <option name="CZ" />
    <option name="EE" />
    <option name="GM" default="T"/>
    <option name="IE" />
    <option name="IH" />
    <option name="IM" />
    <option name="OH" />
    <option name="PC" />
    <option name="PS" />
    <option name="PT" />
    <option name="PW" />
    <option name="RB" />
    <option name="SC" />
    <option name="SP" />
    <option name="UA" />
  </parameter>
  <parameter name="DoCoupleOnTime" type="logical" default="T"/>

#COUPLETIME
GM			NameComp
F			DoCoupleOnTime

The NameComp variable contains the two-character component ID, 
while the DoCoupleOnTime parameter defines if the time step of the
component should be limited such that it does not exceed the next 
coupling time. If DoCoupleOnTime is true, the component will limit the
time step for couplings, if it is false, the time step is only limited
by the final time, the time of saving restarts and the time of checking
stop conditions. 

The default is that all components limit their time steps to match
the coupling time.
</command>

<command name="FIELDLINE" multiple="F">
  <parameter name="NameTarget" type="string"  length="2" input="select">
    <option name="SP" />
    <option name="PT" />
  </parameter>
  <parameter name="nSource"   type="integer" min="0" max="3"   />
  <for from="1" to="$nSource">
    <parameter name="NameSource" type="string" length="2" input="select">
      <option name="SC" />
      <option name="IH" />
      <option name="OH" />
    </parameter> 
    <if expr="$NameSource =~ /SC/">
      <parameter name="RScMin"   type="real"    min="0" default="0" />
      <parameter name="RScMax"   type="real"    min="0" default="0" />
    </if>
    <if expr="$NameSource =~ /IH/">
      <parameter name="RIhMin"   type="real"    min="0" default="0" />
      <parameter name="RIhMax"   type="real"    min="0" default="0" />
    </if>
     <if expr="$NameSource =~ /OH/">
      <parameter name="ROhMin"   type="real"    min="0" default="0" />
      <parameter name="ROhMax"   type="real"    min="0" default="0" />
    </if>
  </for>


#FIELDLINE
SP			NameTarget
3                       nSource
SC			NameSource
1.05			RScMin
21			RScMax
IH			NameSource
19.7			RIhMin
230.0			RIhMax
OH			NameSource
220.0			RIhMin
1500.0			RIhMax
                   

The NameSource and NameTarget variables contain the two-character 
component ID-s for the source and target components coupled via
MFLAMPA. RScMin and RScMax radii for SC componet, and
RIhMin and RIhMax for IH component, and ROhMin and ROhMax for
OH component bound the domains in SC, IH, and OH corrrespondingly,
coupled to SP or PT particle-treated components.

</command>

<command name="COUPLEFIELDLINE" multiple="T">
	<parameter name="DnCouple"   type="integer" min="-1" default="-1"   />
	<parameter name="DtCouple"   type="real"    min="-1" default="-1.0" />


#COUPLEFIELDLINE
-1			DnCouple
10.0			DtCouple

For all components coupled via 'field lines' via command '#FIELDLINE' 
the DnCouple variable determines the frequency of couplings in terms
of the number of time steps nStep for steady state runs, while DtCouple
defines the frequency in terms of the simulation time tSimulation in
seconds for time-accurate runs. Setting both frequencies to a negative value
means that there is no coupling.

The default is no coupling.
</command>

<command name="LOOKUPTABLE" multiple="T">
  <parameter name="StringCompTable" type="string" length="100"/>
    <parameter name="NameTable" type="string" length="$lLine"/>
  <parameter name="NameCommand" type="string" case="lower" input="select">
    <option name="load" default="T"/>
    <option name="use"/>
    <option name="use param"/>
    <option name="save"/>
    <option name="save param"/>
    <option name="make"/>
    <option name="make param"/>
    <option name="param"/>
  </parameter>
  <parameter name="NameFile" type="string" length="$lLine"
	     if="$NameCommand =~ /load|save|use/" />
  <parameter name="TypeFile" type="string" input="select"
	     if="$NameCommand ne 'param'">
    <option name="real8"/>
    <option name="real4" default="T"/>
    <option name="ascii"/>
    <option name="log/sat"/>
  </parameter>
  <if expr="$NameCommand =~ /param/">
    <parameter name="NameTableParam" type="string" length="$lLine"/>
    <for from="1" to="count_split($NameTableParam)">
      <parameter name="TableParam" type="real"/>
    </for>
  </if>
  <if expr="$NameCommand =~ /make|save|use/">
    <parameter name="StringDescription" type="string" length="$lLine"/>
    <parameter name="NameVar"           type="string" length="$lLine"/>
    <parameter name="nIndex"            type="integer" min="1"/>
    <for name="i" from="1" to="$nIndex">
      <parameter name="nIndex$i" type="integer" min="2"/>
      <parameter name="Index${i}Min" type="real"/>
      <parameter name="Index${i}Max" type="real"/>
    </for>
  </if>

#LOOKUPTABLE
PT GM			StringCompTable
ChargeExchange		NameTable
load			NameCommand
OH/Param/ER.dat		NameFile
ascii			TypeFile

The first parameters contains a space separated list of comoponents
that need this particular lookup table. "CON" refers to the control
module, so all processors read in the lookup table.
The example shows loading the ExchangeRate lookup table for two
components GM and PT from an ASCII file OH/Param/ExchangeRate.dat. 
For more complete description, see the #LOOKUPTABLE command description
in GM/BATSRUS/PARAM.XML.

This command can occur multiple times. By default no lookup tables are used.
</command>

</commandgroup>

<commandgroup name="RESTART CONTROL">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!! RESTART CONTROL !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

CON needs to coordinate the saving of restart information for itself
and all the components. It is important that all components save
the necessary information at the same simulation time.

<command name="SAVERESTART">
	<parameter name="DoSaveRestart" type="logical" default="T" />
	<if expr="$DoSaveRestart">
		<parameter name="DnSaveRestart" type="integer" min="-1" 
							default="-1" />
		<parameter name="DtSaveRestart" type="real"    min="-1" 
							default="-1" />
	</if>

#SAVERESTART
T			DoSaveRestart (Rest of parameters read if true)
1000			DnSaveRestart
-1.			DtSaveRestart

The DoSaveRestart variable determines whether restart information 
should be saved or not. The rest of the parameters are read only 
if DoSaveRestart is true.
For steady state runs the frequency of saving restart information is given by
the DnSaveRestart variable in terms of the number of time steps nStep,
while for time accurate run, the DtSaveRestart variable determines
the frequency in terms of the simulation time tSimulation in seconds.
The code stops with an error message if DoSaveRestart is true but 
DnSaveRestart is negative in steady state mode or DtSaveRestart is negative
in time accurate mode. 

Irrespective of the frequencies, final restart files are always saved if
DoSaveRestart is true.

Defaults are DoSaveRestart=true, DnSaveRestart=100000 and DtSaveRestart=1e30.
For typical runs this means that only a final restart file is saved.
It is a good idea, however, to save restart files multiple times during
long runs.
</command>

<command name="RESTARTOUTDIR">
	 <parameter name="NameRestartOutDir" type="string" length="100"
	 	    			     default="" />

#RESTARTOUTDIR
SWMF_RESTART.YYYYMMDD_HHMMSS		NameRestartOutDir

The main purpose of this command is to allow saving multiple restart trees
in time accurate mode without running the Restart.pl script in the background.

NameRestartOutDir sets the name of the output restart directory tree
for the SWMF. If the YYYYMMDD_HHMMSS string is part of NameRestartOutDir, 
it will be replaced with the date-time information corresponding to the 
restart data, for example "SWMF_RESTART.20150209_124900/".
The SWMF output restart file (see #RESTARTFILE) will be written into this 
directory. The components should also write their restart information into a 
subdirectory named by the component ID, for example \\
"SWMF_RESTART.20150209_124900/GM/". 
This feature is currently only implemented for BATSRUS and IM/RCM2.

The default value is an empty string, so the SWMF restart file is written
into the run directory and all components write into their respective
output restart directories. The Restart.pl script can be used to move
this information into a restart tree. The Restart.pl script works for
all the components.
</command>

<command name="RESTARTFILE">
	<parameter name="NameRestartFile" type="string" length="100"
				default="RESTART.out" />

#RESTARTFILE
RESTART.out

The NameRestartFile variable contains the name of the SWMF restart file.
This file contains information such as initial date and time, simulation time,
time step, version number, description of the simulation, name of the planet, 
etc. This file is usually written into the main run directory, but this can be
changed with the #RESTARTOUTDIR command. The Restart.pl script can be used 
to link this file to the RESTART.in, which is normally included into 
PARAM.in with the #INCLUDE command for restarts.

The default value for NameRestartFile is "RESTART.out".
</command>

</commandgroup>

<commandgroup name="OUTPUT CONTROL">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!! OUTPUT CONTROL !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
<command name="ECHO">
	<parameter name="DoEcho" type="logical" default="F"/>

#ECHO
T			DoEcho

If the DoEcho variable is true, the input parameters are echoed back.
The echoing either goes to the standard output or into the log files
depending on the UseStdout variable, which can be set in the
#STDOUT command.

The default value for DoEcho is true and it is a good idea
to leave it that way.
</command>

<command name="FLUSH">
	<parameter name="DoFlush" type="logical" default="T"/>

#FLUSH
F			DoFlush

If the DoFlush variable is true, the output is flushed when
subroutine ModUtility::flush_unit is called. This is typically
used in log files. The flush is useful to see the output immediately, 
but on some systems it may be very slow. 

The default is to flush the output, i.e. DoFlush=T.
</command>

<command name="MAKEDIR">
	<parameter name="DoMakeDir" type="logical" default="T"/>

#MAKEDIR
F			DoMakeDir

If the DoMakeDir variable is true, the code will make directories
as needed. On some machines (Pleiades), however, this can fail,
so it is better to create all directories in advance and not trying
to do it from the code. This is, of course, incompatible with a 
dynamic restart directory name in #RESTARTOUTDIR.

The default is DoMakeDir=T.
</command>

<command name="STDOUT">
	<parameter name="UseStdout" type="logical" default="T"/>

#STDOUT
F			UseStdout

If the UseStdout variable is true, the echoed input parameters and other
verbose information produced by the components are written to the
standard output. To distinguish between the output produced by the
various components, a prefix string is written at the beginning
of the lines. Usually the prefix string contains the component ID, the
processor number if the line is written by a processor which
is not the root processor of the component, and a colon 
(for example "GM0001:").
Even with the prefix, it may be difficult to collect the output
from the various components and processors. The order of the output
depends on how the MPI library buffers that, which is platform
dependent.

If the UseStdout variable is false, the echoed input parameters and other
verbose information produced by the components are written
into separate files in the STDOUT directory (the name of
this directory can be changed by the #STDOUTDIR command).
The files are named similarly to the prefix string:
the component ID is followed by the global processor number
and a ".log" extension is added. For example the root processor
of GM may write into "STDOUT/GM0014.log" if GM's root processor
has global rank 14.

Note that warnings and error messages should always be written to
the standard output, and they should always have a prefix which
identifies the component issuing the warning or error.
CON itself always writes to the standard output and it does not
use a string prefix.

The default value for UseStdout is true.
</command>

<command name="STDOUTDIR">
	<parameter name="NameStdoutDir" type="string" length="100"/>

#STDOUTDIR
STDOUT/Test		NameStdoutDir

The NameStdoutDir variable contains the name of the directory where 
the log files with the redirected standard output of the components 
are written if UseStdout is set to .false. in the #STDOUT command.
The directory must exist before the run is started.

The default value of NameStdoutDir is "STDOUT".
</command>
</commandgroup>

<commandgroup name="SOLAR COORDINATE COMMANDS">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!! SOLAR COORDINATE COMMANDS !!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

We allow an offset for the HGR and HGI/HGC systems so that the
interesting features are aligned with the primary axis.
One common option is to have the planet in the -X,Z plane.
Another option would be to move an active region into an appropriate plane.

<command name="ROTATEHGR"  if="$_IsFirstSession">
	<parameter name="dLongitudeHgr" type="real" min="-360" max="360"
							default="0"/>
#ROTATEHGR
145.6			dLongitudeHgr [deg]

Rotate the HGR system by dLongitudeHgr degrees around the Z axis.
A negative value is interpreted as an offset angle which moves the
planet into the -X, Z plane (so roughly towards the -X axis).
Default value is 0, i.e. the true HGR system is used.
</command>

<command name="ROTATEHGI" if="$_IsFirstSession">
	<parameter name="dLongitudeHgi" type="real" min="-360" max="360"
							default="0"/>
#ROTATEHGI
-1.0			dLongitudeHgi [deg]

Rotate the HGI and the related rotating HGC systems by 
dLongitudeHgi degrees around the Z axis.
A negative value is interpreted as an offset angle which moves the
planet into the -X, Z plane (so roughly towards the -X axis).
Default value is 0, i.e. the true HGI system is used.
</command>

</commandgroup>

<commandgroup name="PLANET COMMANDS">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!! PLANET COMMANDS !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Several components share information about the planet for which the
simulation is done. It is important that the various components
use compatible information about the planet. It is also useful
for the couplers that they can globally access this information,
such as radius and orientation of the planet, or its magnetic
field. The SWMF is designed to work for an arbitrary planet.
It also allows to change some parameters of the planet relative
to the real values.

By default the SWMF works with Earth and its real parameters.
Another planet can be selected with the #PLANET command.
The real planet parameters can be modified and simplified
with the other planet commands listed in this subsection.
These modifier commands cannot proceed the #PLANET command!

<command name="PLANET" if="$_IsFirstSession">
	<parameter name="NamePlanet" type="string" case="upper" input="select">
		<option name="NONE"			/>
		<option name="NEW" 			/>
		<option name="MERCURY"			/>
		<option name="VENUS"			/>
		<option name="EARTH" default="T"	/>
		<option name="MARS"			/>
		<option name="JUPITER"			/>
		<option name="SATURN"			/>
		<option name="URANUS"			/>
		<option name="NEPTUNE" 			/>
		<option name="PLUTO" 			/>
		<option name="MOON"			/>
		<option name="IO"			/>
		<option name="EUROPA"			/>
		<option name="TITAN"			/>
		<option name="ENCELADUS"		/>
		<option name="HALLEY"			/>
		<option name="COMET1P"			/>
		<option name="BORRELLY"			/>
		<option name="COMET19P"			/>
		<option name="CHURYUMOVGERASIMENKO"	/>
		<option name="COMET67P"			/>
		<option name="HALEBOPP"			/>
	</parameter>
	<if expr="$NamePlanet eq 'New'">
		<parameter name="RadiusPlanet" type="real" min="0" />
		<parameter name="MassPlanet"   type="real" min="0" />
		<parameter name="OmegaPlanet"  type="real" min="0" />
		<parameter name="TiltRotation" type="real" min="0" />
		<parameter name="TypeBField"   type="string" input="select">
			<option name="NONE" />
			<option name="DIPOLE" default="T" />
		</parameter>
	</if>
	<if expr="$TypeBField eq 'DIPOLE'">
		<parameter name="MagAxisThetaGeo" type="real" 
						min="0" max="180"/>
		<parameter name="MagAxisPhiGeo"   type="real"
						min="0" max="360"/>
		<parameter name="DipoleStrength"  type="real"    />
	</if>
	<rule expr="not $PlanetCommand">
		PLANET should precede $PlanetCommand
	</rule>

#PLANET
New			NamePlanet (rest of parameters read for unknown planet)
6300000.0		RadiusPlanet [m]
5.976E+24		MassPlanet   [kg]
0.000000199		OmegaPlanet  [radian/s]
23.5			TiltRotation [degree]
DIPOLE			TypeBField
11.0			MagAxisThetaGeo [degree]
289.1			MagAxisPhiGeo   [degree]
-31100.0E-9		DipoleStrength  [T]

The NamePlanet parameter contains the name of the planet
with arbitrary capitalization. In case the name of the planet
is not recognized, the following variables are read:
RadiusPlanet is the radius of the planet,
MassPlanet is the mass of the planet, 
OmegaPlanet is the angular speed relative to an inertial frame,
TiltRotation is the tilt of the rotation axis relative to ecliptic North,
TypeBField, which can be "NONE" or "DIPOLE". 
TypeBField="NONE" means that the planet does not have magnetic field. 
It TypeBField is set to "DIPOLE" than the following variables are read:
MagAxisThetaGeo and MagAxisPhiGeo are the colatitude and longitude
of the north magnetic pole in corotating planetocentric coordinates.
Finally DipoleStrength is the equatorial strength of the magnetic dipole
field. The units are indicated in the above example, which shows the
Earth values approximately.

The default value is NamePlanet="Earth", which is currently
the only recognized planet.
</command>

<command name="ROTATIONAXIS" if="$_IsFirstSession">
	<parameter name="IsRotAxisPrimary" type="logical" default="T" />
	<if expr="$IsRotAxisPrimary">
		<parameter name="RotAxisTheta" type="real" min="0" max="180"/>
		<parameter name="RotAxisPhi"   type="real" min="0" max="360"/>
	</if>
	<set name="PlanetCommand" type="string" value="ROTATIONAXIS" />

#ROTATIONAXIS
T			IsRotAxisPrimary (rest of parameters read if true)
23.5			RotAxisTheta
198.3			RotAxisPhi

If the IsRotAxisPrimary variable is false, the rotational axis
is aligned with the magnetic axis. If it is true, the other two variables
are read, which give the position of the rotational axis at the
initial time in the GSE coordinate system. Both angles are read in degrees
and stored internally in radians.

The default is to use the true rotational axis determined by the
date and time given by #STARTTIME.
</command>

<command name="ROTATION" if="$_IsFirstSession">
	<parameter name="UseRotation" type="logical" default="T" />
	<if expr="$UseRotation">
		<parameter name="RotationPeriod" type="real" />
	</if>
	<set name="PlanetCommand" type="string" value="ROTATION" />

#ROTATION
T			UseRotation
24.06575		RotationPeriod [hour] (read if UseRotation is true)

If UseRotation is false, the planet is assumed to stand still, 
and the OmegaPlanet variable is set to zero. 
If UseRotation is true, the RotationPeriod variable is read in hours, 
and it is converted to the angular speed OmegaPlanet given in radians/second.
Note that OmegaPlanet is relative to an inertial coordinate system,
so the RotationPeriod is not 24 hours for the Earth, but the
length of the astronomical day.

The default is to use rotation with the real rotation period of the planet.
</command>

<command name="MAGNETICAXIS"  if="$_IsFirstSession">
	<parameter name="IsMagAxisPrimary" type="logical" default="T" />
	<if expr="$IsMagAxisPrimary">
		<parameter name="MagAxisTheta" type="real" min="0" max="180"/>
		<parameter name="MagAxisPhi"   type="real" min="0" max="360"/>
	</if>
	<set name="PlanetCommand" type="string" value="MAGNETICAXIS" />

#MAGNETICAXIS
T			IsMagAxisPrimary (rest of parameters read if true)
34.5			MagAxisTheta [degree]
0.0			MagAxisPhi   [degree]

If the IsMagAxisPrimary variable is false, the magnetic axis
is aligned with the rotational axis. If it is true, the other two variables
are read, which give the position of the magnetic axis at the
initial time in the GSE coordinate system. Both angles are read in degrees
and stored internally in radians.

The default is to use the true magnetic axis determined by the
date and time given by #STARTTIME.
</command>

<command name="MAGNETICCENTER" if="$_IsStandAlone">
	<parameter name="MagCenterX" type="real" default="0.0" />
	<parameter name="MagCenterY" type="real" default="0.0" />
	<parameter name="MagCenterZ" type="real" default="0.0" />
	<set name="PlanetCommand" type="string" value="MAGNETICCENTER" />

#MAGNETICCENTER
0.1			MagCenterX
-0.02			MagCenterY
0.0			MagCenterZ

Shifts the magnetic center (e.g. the center of the dipole) to the location
given by the three parameters. The default is no shift 
(at least for most planets).
</command>

<command name="DIPOLE" if="$_IsFirstSession">
	<parameter name="DipoleStrength" type="real" />
	<set name="PlanetCommand" type="string" value="DIPOLE" />

#DIPOLE
-3.11e-5		DipoleStrength [Tesla]

The DipoleStrength variable contains the
magnetic equatorial strength of the dipole magnetic field in Tesla.

The default value is the real dipole strength for the planet.
For the Earth the default is taken to be -31100 nT.
The sign is taken to be negative so that the magnetic axis can
point northward as usual.
</command>

<command name="UPDATEB0">
	<parameter name="DtUpdateB0" type="real" min="-1" default="0.0001" />

The DtUpdateB0 variable determines how often the position of
the magnetic axis is recalculated. A negative value indicates that
the motion of the magnetic axis during the course of the simulation
is neglected. This is an optimization parameter, since recalculating
the values which depend on the orientation of the magnetic
field can be costly. Since the magnetic field moves relatively
slowly as the planet rotates around, it may not be necessary
to continuously update the magnetic field orientation.

The default value is 0.0001, which means that the magnetic axis
is continuously followed.
</command>

<command name="IDEALAXES" if="$_IsFirstSession">
	<set name="PlanetCommand" type="string" value="IDEALAXES" />

#IDEALAXES

The #IDEALAXES command has no parameters. It sets both the rotational
and magnetic axes parallel with the ecliptic North direction. In fact
it is identical with
\begin{verbatim}
#ROTATIONAXIS
T               IsRotAxisPrimary
0.0             RotAxisTheta
0.0             RotAxisPhi

#MAGNETICAXIS
F               IsMagAxisPrimary
\end{verbatim}
but much shorter.
</command>

<command name="ORBIT" if="$_IsFirstSession">
        <parameter name="OrbitalPeriodPlanet" type="real" min="0" />
        <parameter name="rOrbitPlanet" type="real" min="0" />
	<parameter name="Excentricity"   type="real" min="0" />
	<parameter name="RightAscension"  type="real" min="0" />
	<parameter name="Inclination" type="real" min="0" />
	<parameter name="ArgPeriapsis" type="real" min="0" />
	

#ORBIT
3.14e7          OrbitalPeriodPlanet [s]	
1.49e11         rOrbitPlanet [m]
0.016           Excentricity
174.9           RightAscension [deg]
7.155           Inclination    [deg]
288.9           ArgPeriapsis   [deg]

</command>

<command name="TIMEEQUINOX" if="$_IsFirstSession">
  <parameter name="iYear" type="integer" minimum="1965" default="2000"/>
  <parameter name="iMonth" type="integer" minimum="1" default="1"/>
  <parameter name="iDay" type="integer" minimum="1" default="1"/>
  <parameter name="iHour" type="integer" minimum="0" default="0"/>
  <parameter name="iMinute" type="integer" minimum="0" default="0"/>

#TIMEEQUINOX
2000                    iYear
1                       iMonth
1                       iDay
0                       iHour
0                       iMinute

Reset the time of eqinox for any planet
</command>


</commandgroup>

<commandgroup name="STAR COMMANDS">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!! STAR COMMANDS !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Several components share information about the star for which the
simulation is done. It is important that the various components
use compatible information about the star. It is also useful
for the couplers that they can globally access this information,
such as radius and rotation period. The SWMF is designed to work for
an arbitrary star.

By default the SWMF works with the Sun and its real parameters.
Another star can be selected with the #STAR command.

<command name="STAR" if="$_IsFirstSession">
  <parameter name="NameStar" type="string" case="upper" default="SUN"/>
  <parameter name="RadiusStar" type="real" minimum="0" default="1"/>
  <parameter name="MassStar"   type="real" minimum="0" default="1"/>
  <parameter name="RotationPeriodStar" type="real"/>

#STAR
SUN                     NameStar (upper case, up to 3 letters) 
1.0                     RadiusStar (in solar radii)
1.0                     MassStar   (in solar masses)
0.0                     RotationPeriodStar (in days)


Modify the parameters of the central star (when SWMF or BATSRUS is running
in corona/heliospheric mode). Setting zero for the rotation period will
switch off the rotation as shown by the example.

By default the Sun is the central star.
</command>

<command name="HGRALIGNMENTTIME" if="$_IsFirstSession">
  <parameter name="iYear" type="integer" minimum="1965" default="1965"/>
  <parameter name="iMonth" type="integer" minimum="1" default="1"/>
  <parameter name="iDay" type="integer" minimum="1" default="1"/>
  <parameter name="iHour" type="integer" minimum="0" default="0"/>
  <parameter name="iMinute" type="integer" minimum="0" default="0"/>

#HGRALIGNMENTTIME
1965                    iYear
1                       iMonth
1                       iDay
0                       iHour
0                       iMinute

Reset the time at which HGR and HGI are aligned. In application to stars
it may be needed to match the magnetogram (in HGR coords) to the
exoplanet orbital elements (in HGI coords) 

</command>



</commandgroup>


<commandgroup name="STUB COMPONENTS">
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!! STUB COMPONENTS !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
If SWMF is compiled with the interface in srcCON/Stubs,
the stub components recognize only one command #TIMESTEP.

<command name="TIMESTEP">
	<parameter name="DtRun" type="real" min="0" />
	<parameter name="DtCpu" type="real" min="0" />

#TIMESTEP
0.01       DtRun (the typical time step of the component)
0.12       DtCpu (the CPU time needed for 1 time step)

The DtRun variable defines the typical time step of
the component in terms of simulation time. The DtCpu variable
determines the CPU time needed to execute one time step for the component.
Both variables are given in seconds.

Of course it is not necessary to put in the actual CPU times.
One can take the same fraction for all components to accelerate
the run.
</command>

</commandgroup>

<!--
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!! GLOBAL RULES !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-->
<rule expr="$IsTimeAccurate or not $_ENDTIME">
  The #ENDTIME command can only be used in time-accurate mode
</rule>

<rule expr="$_STOP or $_ENDTIME">
  Either #STOP or #ENDTIME in final session must be used
</rule>

<rule expr="not ($IsTimeAccurate and $TimeMax &lt; 0)">
  In time-accurate mode TimeMax cannot be negative
</rule>

<rule expr="$IsTimeAccurate or $MaxIter &gt;= 0">
  In steady state mode MaxIter cannot be negative
</rule>

</commandList>