Space Weather Modeling Framework User Manual Code Version 2.4

Transcription

Space Weather Modeling Framework User Manual
r Space Environment Model
ing
ter fo
Cen
S pa
rk
ce We
ather Modeling Framewo
Code Version 2.4
Center for Space Environment Modeling
The University of Michigan
October 5, 2014
2
This code is a copyright protected software. (c) 2002- University of Michigan
Contents
1 Introduction
1.1 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 The SWMF in a Few Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
8
9
10
2 Quick Start
2.1 A Brief Description of the SWMF Distribution . .
2.2 General Hints . . . . . . . . . . . . . . . . . . . . .
2.3 Installation . . . . . . . . . . . . . . . . . . . . . .
2.4 Platform specific information . . . . . . . . . . . .
2.4.1 Pleiades machine at NASA Ames . . . . . .
2.4.2 Nyx and Flux at the University of Michigan
2.5 Building and Running an Executable . . . . . . . .
2.6 Post-Processing the Output Files . . . . . . . . . .
2.7 Restarting a Run . . . . . . . . . . . . . . . . . . .
2.8 What’s next? . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
15
18
18
18
18
21
21
22
3 The Basics
3.1 Configuration of SWMF . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Scripts/Configure.pl . . . . . . . . . . . . . . . . . . . .
3.1.2 Selecting component versions to compile with Config.pl
3.1.3 Selecting Empty component versions with Config.pl . .
3.1.4 Registering components using LAYOUT.in . . . . . . .
3.1.5 Controlling physics components with PARAM.in . . . .
3.1.6 Setting compiler flags . . . . . . . . . . . . . . . . . . .
3.1.7 Configuration of individual components . . . . . . . . .
3.1.8 Using stubs for all components . . . . . . . . . . . . . .
3.2 PARAM.in . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Included Files, #INCLUDE . . . . . . . . . . . . . . . . .
3.2.2 Commands, Parameters, and Comments . . . . . . . .
3.2.3 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 The Order of Commands . . . . . . . . . . . . . . . . .
3.2.5 Iterations, Time Steps and Time . . . . . . . . . . . . .
3.3 Execution and Coupling Control . . . . . . . . . . . . . . . . .
3.3.1 Processor Layout: LAYOUT.in . . . . . . . . . . . . . .
3.3.2 Steady State vs. Time Accurate Execution . . . . . . .
3.3.3 Coupling order . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
23
23
23
24
24
25
25
26
26
26
27
28
28
29
29
32
35
35
37
39
3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4
CONTENTS
4 Example Runs
4.1 Configuration and Compilation for the Examples . . . . . . . . . . . . . . . . .
4.2 Example 1: Create Steady State for the Solar Corona . . . . . . . . . . . . . .
4.3 Example 2: Create SC-IH Steady State . . . . . . . . . . . . . . . . . . . . . .
4.4 Example 3: Create Initial Conditions for the Global Magnetosphere . . . . . .
4.5 Example 4: Create Initial Conditions for the GM, IM, IE and UA Components
4.6 Example 5: Time Accurate Run with SC, IH and SP Components . . . . . . .
4.7 Example 6: Time Accurate Run with All Eight Components . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
41
41
42
44
45
45
47
48
5 Complete List of Input Commands
5.1 Input Commands for the Control Module . . . . . . . . . . . . . . . . . . .
5.1.1 General commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 Time and session control . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.3 Testing and timing . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.4 Component control . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.5 Coupling control . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.6 Restart control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.7 Output control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.8 Solar coordinate commands . . . . . . . . . . . . . . . . . . . . . . .
5.1.9 Planet commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.10 Stub components . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Input Commands for the BATSRUS: GM, EE, SC, IH and OH Components
5.2.1 Stand alone mode . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2 Planet parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.3 User defined input . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.4 Testing and timing . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.5 Initial and boundary conditions . . . . . . . . . . . . . . . . . . . . .
5.2.6 Grid geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.7 Initial time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.8 Time integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.9 Implicit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.10 Stopping criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.11 Output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.12 Amr parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.13 Scheme parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.14 Physics parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.15 Corona specific commands . . . . . . . . . . . . . . . . . . . . . . . .
5.2.16 Heliosphere specific commands . . . . . . . . . . . . . . . . . . . . .
5.2.17 Wave specific commands . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.18 Script commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 Input Commands for the Ridley Ionosphere Model: IE Component . . . . .
5.3.1 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.3 Physical parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.4 Scheme parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4 Input Commands for the CRCM: IM Component . . . . . . . . . . . . . . .
5.4.1 Numerical scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2 Input/output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5 Input Commands for the Hot Electron Ion Drift Integrator: IM Component
5.5.1 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6 Input Commands for the Rice Convection Model 2: IM Component . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
51
51
52
52
55
57
58
61
62
63
63
65
67
67
69
71
72
75
80
83
84
87
92
93
106
115
130
142
146
147
147
148
148
148
149
152
153
153
153
155
155
161
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
CONTENTS
5.6.1 Testing . . . . . . . . . . . . . . . . . . . . . .
5.6.2 Output . . . . . . . . . . . . . . . . . . . . . .
5.6.3 Time integration . . . . . . . . . . . . . . . . .
5.6.4 Physics parameters . . . . . . . . . . . . . . . .
5.7 Input Commands for the DGCPM: PS Component . .
5.7.1 Stand alone mode . . . . . . . . . . . . . . . .
5.7.2 Numerical scheme . . . . . . . . . . . . . . . .
5.7.3 Physical parameters . . . . . . . . . . . . . . .
5.7.4 Output parameters . . . . . . . . . . . . . . . .
5.8 Input Commands for the PWOM: PW Component . .
5.8.2 Input/output . . . . . . . . . . . . . . . . . . .
5.9 Input Commands for the RBE: RB Component . . . .
5.9.2 Input/output . . . . . . . . . . . . . . . . . . .
5.10 Input Commands for the Kota Solar Energetic Particle
5.10.1 Testing . . . . . . . . . . . . . . . . . . . . . .
5.10.2 Output . . . . . . . . . . . . . . . . . . . . . .
5.10.3 Magnetic field lines . . . . . . . . . . . . . . . .
5.10.4 Control . . . . . . . . . . . . . . . . . . . . . .
5.10.5 Shock wave sensor . . . . . . . . . . . . . . . .
Index of Input Commands
5
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
Model: SP Component
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
161
161
162
162
165
165
165
165
165
166
166
167
171
171
172
174
174
174
174
174
175
176
6
CONTENTS
Chapter 1
Introduction
This document describes a working prototype of the Space Weather Modeling Framework (SWMF). The
SWMF was developed to provide a flexible tool serving the Sun-Earth modeling community. In its current
form the SWMF contains many domains extending from the surface of the Sun to the upper atmosphere of
the Earth:
1. EE – Eruptive Event generator (currently empirical models only)
2. GM – Global Magnetosphere
3. IE – Ionosphere Electrodynamics
4. IM – Inner Magnetosphere
5. IH – Inner Heliosphere
6. LA – Lower Atmosphere (under development)
7. LC – Lower Corona
8. OH – Outer Heliosphere
9. PS – Plasma Sphere (under development)
10. PW – Polar Wind
11. RB – Radiation Belts
12. SC – Solar Corona
13. SP – Solar Energetic Particles
14. UA – Upper Atmosphere
The core of the SWMF and most of the models are implemented in Fortran 90. The parallel communications
use the Message Passing Interface (MPI) library. The SWMF creates a single executable. Note, however,
that the models in the SWMF can still be compiled into stand-alone executables. This means that the
models preserve their individuality while being compatible with the SWMF.
7
8
CHAPTER 1. INTRODUCTION
1.1
Acknowledgments
The first version of the SWMF was developed at the Center for Space Environment Modeling (CSEM)
of the University of Michigan under the NASA Earth Science Technology Office (ESTO) Computational
Technologies (CT) Project (NASA CAN NCC5-614). The project was entitled as “A High-Performance
Adaptive Simulation Framework for Space-Weather Modeling (SWMF)”. The Project Director was Professor
Tamas Gombosi, and the Co-Principal Investigators are Professors Quentin Stout and Kenneth Powell.
The first version of the SWMF and many of the physics components were developed at CSEM by the
following individuals (in alphabetical order): David Chesney, Yue Deng, Darren DeZeeuw, Tamas Gombosi,
Kenneth Hansen, Kevin Kane, Ward (Chip) Manchester, Robert Oehmke, Kenneth Powell, Aaron Ridley,
Ilia Roussev, Quentin Stout, Igor Sokolov, Gábor Tóth and Ovsei Volberg.
The core design and code development was done by Gábor Tóth, Igor Sokolov and Ovsei Volberg:
• Component registration and layout was designed and implemented by Ovsei Volberg and Gábor Tóth.
• The session and time management support as well as the various configuration scripts and the parameter
editor GUI were designed and implemented by Gábor Tóth.
• The SWMF coupling toolkit was developed by Igor Sokolov.
• The SWMF GUI was designed and implemented by Darren De Zeeuw.
The SWMF has undergone major improvements over the years. The current version has a fully automated
test suite designed by Gabor Toth. Empirical models were added in a systematic way. The shared libraries
and utilities have been greatly extended. The SWMF has been coupled to the Earth System Modeling
Framework (ESMF).
The current physics models were developed by the following research groups and individuals:
• The Lower Corona (LC), Solar Corona (SC), Inner Heliosphere (IH), Outer Heliosphere (OH), and the
Global Magnetosphere (GM) components are based on BATS-R-US MHD code developed at CSEM.
BATS-R-US is highly parallel up to 3-dimensional block-adaptive hydrodynamic and MHD code. Currently the main developers of BATS-R-US are Gabor Toth, Bart van der Holst, Igor Sokolov, and
Darren De Zeeuw. The Lower Corona specific part was developed by Cooper Downs and Ilia Roussev
at the University of Hawaii. The current version of the Solar Corona model was developed by Bart
van der Holst, Chip Manchester, Igor Sokolov, and Ofer Cohen. The Inner Heliosphere model was
mostly developed by Chip Manchester. The Outer Heliosphere model was developed by Merav Opher
and Gabor Toth. The Global Magnetosphere model was developed by Darren De Zeeuw, Gabor Toth,
Aaron Ridley and many others. The physics based Eruptive Even Generator model is also based on
BATS-R-US. It is developed by Fang Fang, Chip Manchester and Bart van der Holst. The EE model
alrady works as a stand-alone code, and it will by coupled to the SWMF in the future.
• The Ionospheric Electrodynamics (IE) model is the Ridley Ionosphere Model developed by Aaron
Ridley, Darren De Zeeuw and Gabor Toth at CSEM. RIM is a 2-dimensional spherical electric potential
solver. It has two versions. The Ridley serial version can run on up to 2 processors, the RIM version
is fully parallel with many new options, however it is still being developed, and it is not yet fully
functional.
• The first Inner Magnetosphere (IM) component in the SWMF was the Rice Convection Model (RCM)
developed Dick Wolf, Stan Sazykin and others at Rice University, also modified by Darren De Zeeuw
at the University of Michigan. The current version of the model with oxygen and loss is named
RCM2. The RCM code is 2-dimensional in space (plus one dimension for energy) and serial. There
are 3 more IM models. The CRCM model was developed by Mei-Ching Fok, Natasha Buzulukova
and Alex Glocer at the NASA Goddard Space Flight Center. The HEIDI model was developed by
Mike Liemohn and Raluca Ilie at the University of Michigan. The RAM-SCB model was developed
1.2. THE SWMF IN A FEW PARAGRAPHS
9
by Vania Jordanova, Sorin Zaharia and Dan Welling. RAM-SCB is currently only available at Los
Alamos National Laboratory. The CRCM, HEIDI and RAM-SCB models are also 2 dimensional in
space, but they resolve energy as well as pitch angle. Currently only the RCM and CRCM models are
2-way coupled with the GM component.
• The Polar Wind (PW) component is the Polar Wind Outflow Model (PWOM) developed by Alex
Glocer, Gabor Toth and Tamas Gombosi at the University of Michigan. This code solves the multifluid
equations along multiple field lines and it is fully parallel.
• The Radiation Belt Environment (RBE) model is developed by Meiching Fok and Alex Glocer at NASA
Goddard. It is a spatially 2-dimensional code with extra two dimensions for pitch angle and energy.
• The Solar Energetic Particle (SP) component is the Kóta’s SEP model which was developed by Joseph
Kota at the University of Arizona. It solves the equations for the advection and acceleration of energetic
particles along a magnetic field line in a 3D phase space.
• The Upper Atmosphere (UA) model is the Global Ionosphere-Thermosphere Model (GITM) developed
by Aaron Ridley, Yue Deng, and Gabor Toth at CSEM. GITM is 3-dimensional spherical fully parallel
hydrodynamic model with ions, neutrals, chemistry etc. The current version is the GITM2 model.
The following empirical models are available:
EEE The Gibbson-Low and the Titov-Demoulin flux rope models can be used to initiate CME-s. The
breakout model is also available.
EGM The Tsyganenko 1996 and 2004 models.
EIE The Weimer 1996 and 2000 models, and many more empirical ionospheric electrodynamics models.
EUA The MSIS and IRI models for the upper atmospher and the ionosphere, respectively.
1.2
The SWMF in a Few Paragraphs
The SWMF is a structured collection of software building blocks that can be used or customized to develop
Sun-Earth system modeling components, and to assemble them into applications. The SWMF consists of
utilities and data structures for coupling model components. The SWMF contains a Control Module (CON),
which is responsible for component registration, processor layout for each component and coupling schedules.
It controls initialization and execution of the components. A component is adapted from user-supplied physics
codes, (for example BATS-R-US or RCM), by adding two relatively small units of code:
• A wrapper, which provides the control functions, and
• A coupling interface to perform the data exchange with other components.
Both the wrapper and coupling interface are constructed from the building blocks provided by the framework.
From component software technology perspective both the wrapper and coupling interface are component
interfaces: the wrapper is an interface with CON, and the coupling interface is an interface with another
component. A physics model code and its wrapper, which comprise a component, share the communication
group. The coupling interface uses the union communicator of the two components that it links together.
An SWMF component is compiled into a separate library that resides in the directory lib, which is
created as part of the installation process described later in this document. Currently the component
libraries are static libraries. The executable image is created in the directory bin, which is created during
the compilation. If a user does not want to build some particular component, this component should be
substituted by an empty version of the component.
10
An important feature of the SWMF is the component registration. A component to be included in the
run should be registered by the framework. Currently entering the line for the component in the input file
called LAYOUT.in does the registration. Thus the SWMF performs the run-time registration of components.
The framework controls the initialization, execution, coupling and finalization of components. The execution is done in sessions. In each session the parameters of the framework and the components can be
changed. The parameters are read from the PARAM.in file, which may contain further included parameter
files. These parameters are read and broadcast by CON and the component specific parameters are sent to
the components. The structure of the parameter file will be described in detail.
If two components reside on different sets of processing elements (PE-s) they can execute in an efficient
concurrent manner. This is possible, because the coupling times (in terms of the simulation time or number
of iterations) are known in advance. The components advance to the time of coupling and only the processors
involved in the coupling need to communicate with each other. The components are also allowed to share
some processing elements. The execution is sequential for the components with overlapping layouts. This
can be useful when the execution time of the components vary a lot during the run, or when a component
needs a lot of processors for memory storage, but it requires little CPU time. Of course this still allows the
individual components to execute in parallel. For steady state calculations the components are allowed to
progress at different rates towards steady state. Each component can be called at different frequencies by
the control module.
The coupling of the components is realized either with plain MPI calls, or via the SWMF coupling toolkit,
which can couple components based on the following types of parallel distributed grids:
• 3D block adaptive (AMR) parallel grid
• 2D spherical grid
• Logically Cartesian uniform grid
• Logically Cartesian non-uniform grid
The SWMF coupling toolkit performs an efficient N to M parallel coupling based on a router. The router is
calculated in advance using the domain decomposition and grid description obtained from the components.
The router is updated only when the domain decompositions or the grids of the components change, or when
the mapping geometry changes. The coupling toolkit takes care of linear interpolation in space based on the
grid descriptor. Temporal interpolation is not supported by the current implementation.
The framework has been ported to many platforms using many different compilers and MPI libraries.
The list of compilers includes Absoft, gfortran, ifort, Lahey, NAG, PGF90, and XLF90. The MPI libraries
used so far include many versions of MPICH, MVAPICH and OpenMpi.
1.3
System Requirements
In order to install and run the SMWF the following minimum system requirements apply.
• The SWMF runs only under the UNIX/Linux operating systems. This now includes Macintosh system
10.x because it is based on BSD UNIX. The SWMF does not run under any Microsoft Windows
operating system.
• A FORTRAN 77 and FORTRAN 90 compiler must be installed.
• The Perl interpreter must be installed.
• A version of the Message Passing Interface (MPI) library must be installed for parallel execution.
• You may be able to compile the code and do very small test runs on 1 or 2 processor machines.
However, to do most physically meaningful runs the SWMF requires a parallel processor machine with
a minimum of 8 processors and a minimum of 8GB of memory.
1.3. SYSTEM REQUIREMENTS
11
• Very large runs require many more processors.
• In order to generate the documentation you must have LaTex installed on your system. The PDF
generation requires the dvips and ps2pdf utilities. To generate the HTML version you also must
install the latex2html package.
In addition to the above requirements, the SWMF output is designed to be visualized using either IDL
or Tecplot. You may be able to visualize the output with other packages, but formats and scripts have been
designed for only these two visualization softwares.
12
Chapter 2
Quick Start
2.1
A Brief Description of the SWMF Distribution
The distribution in the form of the compressed tar image includes the SWMF source code. The top level
directory contains the following subdirectories:
• CON - the source code for the control module of the SWMF
• Copyrights - copyright files
• ESMF - the ESMF wrapper for the SWMF
• GM, IE, ...
UA - component directories
• Param - description of CON parameters, parameter and layout files
• Scripts - shell and Perl scripts
• doc - the documentation directory
• gui - the SWMF graphical user interface
• output - reference test results for the SWMF tests
• share - shared scripts and source code
• util - utilities such as TIMING, NOMPI, empirical models, etc.
and the following files
• README - a short instruction on installation and usage
• Makefile - the main makefile
• Makefile.test - the makefile containing the tests
• Config.pl - Perl script for (un)installation and configuration
2.2
General Hints
Getting help with scripts and the Makefile
Most of the Perl and shell scripts that are distributed with the SWMF provide help which can be accessed
as follows using the -h flag. For example,
Config.pl -h
13
14
CHAPTER 2. QUICK START
will provide a detailed listing of the options and capabilities of the Config.pl script. In addition, you can
find all the possible targets that can be built by typing
make help
Input commands: PARAM.XML
A very useful set of files to become familiar with are the PARAM.XML files. Such a file exists for the SWMF
itself and for each of the physics components. The file for the SWMF is found at
Param/PARAM.XML
while the files for the physics components are found in the component’s subdirectory. For example, the file
for the GM/BATSRUS component can be found at
GM/BATSRUS/PARAM.XML
This file contains a complete list of all input commands for the component as well as the type, the allowed
ranges and default values for each of the input parameters. Although the XML format makes the files a
little hard to read, they are extremely useful. A typical usage is to cut and paste commands out of the
PARAM.XML file into the PARAM.in file for a run.
An alternative approach is to use the web browser based parameter editor to edit the PARAM.in file for
the SWMF (also for the stand-alone models that have PARAM.XML files). The editor GUI can be started
as
share/Scripts/ParamEditor.pl
This editor allows constructing PARAM.in files with pull down menus, shows the manual for the edited
commands, and checks the correctness of the parameter file and highlights the errors. All this functionality
is based on the PARAM.XML files.
Have the working directory in your path
In order to run executable files in the UNIX environment you must have the current working directory either
your path or in the filename you want to execute. In UNIX the current working directory is represented by
the period (.). For example
./Config.pl -s
will execute the Config.pl script if it is in your current directory. If you add the ‘.’ to your path using for
example
set path = (${path} .)
then you can simply type
Config.pl -s
Setting the path is best done in the .cshrc or equivalent Unix shell customization file located in the user’s
home directory.
2.3. INSTALLATION
2.3
15
Installation
The installation instructions are described in the README file. To keep this user manual more up-to-date
and consistent, the README file is quoted verbatim below.
#
#
#
Copyright (C) 2002 Regents of the University of Michigan,
portions used with permission
For more information, see http://csem.engin.umich.edu/tools/swmf
This document outlines how to install the SWMF on your system and how to
create and access the documentation. To learn more about the SWMF, including
how to compile and run the code, please consult the user manual. To install
the SWMF and create the user manual please follow the instructions below.
###############
# Obtain SWMF #
###############
# Get the source code from CVS (UM only) or from the tar balls.
# The minimim requirement is the SWMF repository.
# You may also need the SWMF_data repository that contains large data files.
# At the UofM the SWMF_data may already be available through a shared disk as
/csem1/SWMF_data
# If it is not availble through the shared disk, the SWMF_data repository
# can be put into the home directory or into the SWMF directory.
# Some data files used by the Center for Radiative Shock Hydrodynamics (CRASH)
# are in the CRASH_data repository. On many machines at the UofM this is
# already available through a shared disk as
/csem1/CRASH_data
# Otherwise it has to be placed into the home directory.
# !!! Getting SWMF from CVS (requires CVS access) !!!
# Set the CVS environment variables (with your user name)
setenv CVSROOT [email protected]:/FRAMEWORK
setenv CVS_RSH ssh
# Check out the SWMF distribution
cd {where_you_want_to_have_the_swmf}
cvs checkout SWMF
# Check out the SWMF_data distribution into the home directory if needed
cd
cvs checkout SWMF_data
16
# Check out the CRASH_data distribution into the home directory if needed
cd
cvs checkout CRASH_data
# !!! Opening tar balls !!!
# Open SWMF tar ball
cd {where_you_want_to_have_the_swmf}
tar -xzf {path_to_file}/SWMF_v{version_number}.tgz
# If needed, open the SWMF_data tar ball into the home directory
cd
tar -xzf {path_to_file}/SWMF_data.tgz
# If needed, open the CRASH_data tar ball into the home directory
cd
tar -xzf {path_to_file}/CRASH_data.tgz
################
# Install SWMF #
################
#
#
#
#
Many machines used by UofM are already recognized by the
share/Scripts/Config.pl script which is called by all other
Config.pl scripts in the SWMF.
For these platform/compiler combinations installation is very simple:
Config.pl -install
# On other platforms the Fortan compiler should be explicitly given.
# To see available choices, type
Config.pl -compiler
# Then install the code with the selected Fortran compiler, e.g.
Config.pl -install -compiler=ifort
# A non-default C compiler can be added after a comma, e.g.
Config.pl -install -compiler=mpxlf90,mpxlc
# For machines with no MPI library, use
Config.pl -install -nompi -compiler=....
# This will only allow serial execution, of course.
######################
# Create the manuals #
######################
2.3. INSTALLATION
# Please note that creating both the PDF and HTML versions require
# that LaTex and ps2pdf be installed on your system.
# In addition, creating the HTML version requires the latex2html utility
# To create the PDF versions of the manuals type
make PDF
# in the SWMF directory. The manuals will be in the doc/ directory.
# To create the HTML version of the manuals type
make HTML
# in the SWMF directory. The HTML manuals will be in the doc/HTML directory.
# Cleaning the documentation
cd doc/Tex
make clean
# To remove all the created documentation type
cd doc/Tex
make cleanall
####################
# Read the manuals #
####################
# All manuals can be accessed by opening the top index file
open doc/index.html
# You may also read the PDF files directly with a PDF reader.
# The most important document is the user manual in
doc/SWMF.pdf
#################
# Running tests #
#################
# You can try running the standard test suite by typing
make test
# in the main directory. This requires a machine where mpirun is available.
# The tests run on 2 CPU cores by default. To run on (up to 4) cores use
make test MPIRUN=’mpirun -np 4’
# the results of the tests are summarized in test_swmf.res
# Successful passing of the test is indicated by empty *.diff files.
17
18
2.4
Platform specific information
2.4.1
Pleiades machine at NASA Ames
Currently on pleiades you should load the following modules (includes modules for optional HDF5 output
and IDL for visualization)
module
module
module
module
module
load
load
load
load
load
comp-intel/11.1.072
mpi-sgi/mpt.2.04.10789
hdf5/1.8.3/intel/mpt
hdfeos/5.1.12
idl
It is best adding the above statements into the .cshrc file in the home directory. Note that ifort 12.0 cannot
compile the SWMF code. The module versions keep changing. Use
module avail
to see the list of all available modules.
2.4.2
Nyx and Flux at the University of Michigan
Note that on nyx/flux the tcsh shell has to be started manually after login by typing ’tcsh’. You can either
use the pgf90, NAG or ifort compilers. For the pgf90 compiler use
Config.pl -install -compiler=pgf90
module load pgi
module swap openmpi openmpi/1.3.2-pgi
For the NAG compiler use
Config.pl -install -compiler=f95
module load nag/5.1
module swap openmpi/1.3.2-nag
For the Intel ifort compiler use
Config.pl -install -compiler=ifort
module load intel-comp
module swap openmpi openmpi/1.4.3/intel/11.0
Currently the most reliable compiler on nyx/flux is pgf90, but this may change. The ifort compiler often gives
better performance. The NAG compiler is recommended for debugging. Note that gfortran 4.1.2 (current
version on nyx/flux) does not work properly with the SWMF. The module versions keep changing. Use
module avail
to see the list of all available modules.
2.5
Building and Running an Executable
At compile time, the user can select which physics components should be compiled. Any component not
compiled will not be available for use at run time. The physics components can be selected with the -v flag
of the Config.pl script. For example typing
Config.pl -v=Empty,SC/BATSRUS,IH/BATSRUS,SP/Kota
2.5. BUILDING AND RUNNING AN EXECUTABLE
19
will select BATSRUS for the SC and IH components and Kóta’s model for the SP component and the other
components are set to Empty versions that contain empty subroutines for compilation, but cannot be used.
The default configuration includes a working version for all components, which takes up more memory, but
is the most general. The only exception is SC, which requires configuration, so the default version is Empty
for the Solar Corona component.
The grid size of several components can also be set with the -g flag of the Config.pl script. For example
the
Config.pl -g=GM:8,8,8,400,100
command sets the block size for the GM component to 8 × 8 × 8 cells, the maximum number of blocks
per processor to 400, and the maximum number of implicit blocks per processor to 100. The main SWMF
Config.pl script actually runs the individual Config.pl scripts in the component versions. These scripts can
be run directly, For example try
cd GM/BATSRUS
Config.pl -show
Compilation rules, library definitions, debugging flags, and optimization level are stored in Makefile.conf.
This file is created during installation of the SWMF and contains default settings for production runs. The
compiler flags can be modified with
Config.pl -debug -O0
to debug the code with 0 optimization level, and
Config.pl -nodebug -O4
to run the code at maximum optimization level and without the debugging flags.
Before compiling SWMF it is always a good idea to check its configuration with
Config.pl -show
To build the executable bin/SWMF.exe, type:
make
Depending on the configuration, the compiler settings and the machine that you are compiling on, this can
take from 2 to up to 30 minutes. In addition, you may want to make the post processing codes (for BATSRUS
only) also:
make PSPH
make PIDL
These two commands will create the codes bin/PostSPH.exe, for post processing spherical Tecplot files, and
bin/PostIDL.exe for post processing IDL files.
The SWMF.exe executable should be run in a sub-directory, since a large number of files are created in
each run. To create this directory use the command:
make rundir
This command creates a directory called run. You can either leave this directory as named, or mv it to a
different name. It is best to leave it in the same SWMF directory, since keeping track of the code version
associated with each run is quite important. On some platforms, however, the runs should be done on
a parallel file system (often called scratch or nobackup), while the source code is better kept in the home
directory. In this case move the run directory to the scratch disk and create a symbolic link to it, for example
20
mv rundir /p/scratch/MYNAME/SWMF/run_halloween2
ln -s /p/scratch/MYNAME/SWMF/run_halloween2 .
The run directory will contain links to the codes which were created in the previous step as well as subdirectories where input and output of the different components will reside. On some systems the compute
nodes cannot access symbolic links accross different file systems. In this case the executable should be copied
instead of linked, so in our example the following commands should be done every time after the SWMF has
been (re)compiled:
rm -f run_halloween2/SWMF.exe
cp bin/SWMF.exe run_halloween2/
To run the SWMF change directory into the run directory (or the symbolic link to it):
cd run_halloween2
In order to run the SWMF you must have two input files: LAYOUT.in and PARAM.in. The LAYOUT.in
file defines the processor layout for the components involved in the future run. The PARAM.in file contains
the detailed commands for controlling what you want the code to do during the run. The Param directory
contains many example input files. Many of these are used by the nightly test suite.
An example processor map file LAYOUT.in to run the executable with five components on 16 processors
is:
#COMPONENTMAP
GM
0
4
IE
5
6
IH
7
10
IM
11
11
UA
12
15
#END
1
1
1
1
1
The file syntax is simple. It must start with the directive #COMPONENTMAP and end with another
directive #END. Each line between these directives specifies the label for component, i.e. IE, GM and etc.,
its first and last processor, all relatively to the world communicator, and the stride. Thus GM will run on
5 processors from 0 to 4, and IM will run on only 1 processor, the processor 11. If stride is not equal to 1,
the processors for the component will not be neighboring processors.
It is strongly recommended to check the validity of the PARAM.in and LAYOUT.in files before running the
code. If the code will be run on 16 processors, type
Scripts/TestParam.pl -n=16 run_halloween2/PARAM.in
in the main SWMF directory. The Perl script reports inconsistencies and errors. If no errors are found, the
script finishes silently. Now you are ready to run the executable through submitting a batch job or, if it is
possible on your computer, you can run the code interactively. For example, to run the SWMF interactively:
cd run_halloween2
mpirun -np 16 SWMF.exe
The SWMF provides example job scripts for several machines. These job scripts are found in
share/JobScripts
in the subdirectories named after the operating system. If the name of the file in the appropriate subdirectory
matches the name of the machine, the job script is copied into the run directory when it is created. These
job scripts serve as a starting point only, they must be customized before they can be used for submitting a
job.
To recompile the executable with different compiler settings you have to use the command
2.6. POST-PROCESSING THE OUTPUT FILES
21
make clean
before recompiling the executables. It is possible to recompile only a component or just one subdirectory if
the make clean command is issued in the appropriate directory.
2.6
Post-Processing the Output Files
Several components produce output files (plot files) that require some post-processing before they can be
visualized. The post-processing collects data written out by different processors, and it can also process and
transform the data.
The PostProc.pl script greatly simplifies the post-processing and it also helps to collect the run results in
a well contained directory tree. The script can also be used to do post-processing while the code is running.
Usually the processed output files are much smaller than the raw output file, so post-processing during the
run can limit the amount of disk space used by the raw data files. It also avoids the need to wait for a long
time for the post-processing after the run is done.
The PostProc.pl script is copied into the run directory and it should be executed from the run directory.
To demonstrate the use of the script, here are a few simple examples. After or during a run, you may simply
type
cd run_halloween2
./PostProc.pl
to post-process the available output files. The series of individual IDL plot files can be concatenated into
single movie files with
./PostProc.pl -M
Repeat the post-processing every 360 seconds during the run, and gzip large ASCII files:
./PostProc.pl -r=360 -g >& PostProc.log &
After the run is finished, create IDL movie files and concatenate various log and satellite files (for restarted
runs), and create a directory tree with the output of all the components, the input parameter file and the
’runlog’ file (if present)
./PostProc.pl -M -cat -o RESULTS/NewRun
The RESULTS/NewRun directory will contain the PARAM.in file, the runlog file (the standard output
should be piped into that file), and the output files for each component in a subdirectory named accordingly
(eg. RESULTS/NewRun/GM/). The output directories of the components (e.g. GM/IO2/) will be empty.
To see all the options of the script, including parallel processing and syncing results to a remote computer,
type
./PostProc.pl -h
2.7
Restarting a Run
There are several reasons for restarting a run. A run may fail due to a run time error, due to hardware
failure, due to software failure (e.g. the machine crashes) or because the queue limits are exceeded. In such
a case the run can be continued from the last saved state of SWMF.
It is also possible that one builds up a complex simulation from multiple runs. For example the first run
creates a steady state for the SC component. The second run includes both the SC and IH components and
it restarts from the results of the first run and creates a steady state for both components. A third run may
restart from this solution and include the GM component, etc.
22
The restart files are saved at the frequency determined in the PARAM.in file. Normally the restart files
are saved into the output restart directories of the individual components and subsequent saves overwrite
the previous ones (to reduce the required disk space). A restart requires the modification of the PARAM.in
file: one needs to include the restart file for the control module of SWMF as well as ask for restart by all
the components.
The Restart.pl script simplifies the work of the restart in several ways:
1. The SWMF restart file and the individual output restart directories of the components are collected
into a single directory tree, the restart tree.
2. The default input restart file of SWMF and the default input directories of the components can be
linked to an existing restart tree.
3. The script can run continuously in the background and create multiple restart trees while SWMF is
running.
4. The script does extensive checking of the consistency of the restart files.
The Restart.pl script is copied into the run directory and it should be executed in the run directory. Note
that the PARAM.in file is not modified by the script: it has to be modified with an editor as needed.
To demonstrate the use of the script, here are a few simple examples. After a successful or failed run
which should be continued, simply type
cd run_halloween2
./Restart.pl
to create a restart tree from the final output and to link to the tree for the next run. The default name of the
restart tree is based on the simulation time for time accurate runs, or the time step for non-time accurate
runs. But you can also specify a name explicitly, for example
./Restart.pl RESTART_SC_steady_state
If you wish to continue the run in another run directory, or on another machine, transfer the restart tree as
a whole into the new run directory and type
./Restart.pl -i=RESTART_SC_steady_state
where the -i stands for “input only”, i.e. the script links to the tree, but it does not attempt to create the
restart tree.
To save multiple restart trees repeatedly at an hourly frequency of wall clock time while the SWMF is
running, type
./Restart.pl -r=3600 &
To see all the options of the script type
./Restart.pl -h
2.8
What’s next?
Hopefully this section has guided you through installing the SWMF and given you a basic knowledge of how
to run it. However it has probably also convinced you that the SWMF is quite a complex tool and that
there are many more things for you to learn. So, what next?
We suggest that you read all of chapter 3, which outlines the basic features of the SWMF as well as
some things you really must know in order to use the SWMF. Once you have done this you are ready to
experiment. Chapter 4 gives several examples which are intended to make you familiar with the use of the
SWMF. We suggest that you try them!
Chapter 3
The Basics
3.1
Configuration of SWMF
Configuration refers to several different ways of controlling how the SWMF is compiled and run. The most
obvious is the setting of compiler flags specific to the machine and version of FORTRAN compiler. The other
methods refer to ways in which different physics components are chosen to participate in or not participate
in a run. Inclusion of components can be controlled using one of several methods:
• The source code can modified so that all references to a subset of the components is removed. This
method uses the Scripts/Configure.pl script. In a similar way, some physics components can be individually configured.
• The user may select which version of a physics component, including the Empty version, should be
compiled. This is controlled using the Config.pl script.
• When submitting a run, a subset of the non-empty (compiled) components can be registered to participate in the run in the LAYOUT.in file.
• Registered components can be turned off and on with the #COMPONENT command in the PARAM.in
file.
Each of these options have their useful application.
Finally, each physics component may have some settings which need to (or can) be individually configured,
such as selecting user routines for the IH/BATSRUS or GM/BATSRUS components.
3.1.1
Scripts/Configure.pl
The Scripts/Configure.pl script can build a new software package which contains only a subset of the components. It is a simple interface for the general share/Scripts/Configure.pl script. The configuration can
remove a whole component directory and all references to the component in the source code, in the scripts
and the Makefiles. This type of configuration results in a smaller software package. The main use of this type
of configuration is to distribute a part of SWMF to users. For example one can create a software distribution
which includes GM, IE and UA only by typing
Scripts/Configure.pl -on=GM,IE,UA -off=SC,IH,SP,IM,PW,RB
The configured package will be in the Build directory. Type
Scripts/Configure.pl -h
to get complete usage information or read about this script in the reference manual.
23
24
3.1.2
CHAPTER 3. THE BASICS
Selecting component versions to compile with Config.pl
The physics component versions reside in the directories GM, IE, IH, IM, RB, PW, SC, SP and UA. Most
components have only one working version and one empty version. The empty version consists of a single
wrapper file, which contains empty subroutines required by CON wrapper and the couplers. These empty
subroutines are needed for the compilation of the code, and they also show the interface of the working
versions.
The appropriate version can be selected with the -v flag of the Config.pl script, which edits the
Makefile.def
file. The IH/BATSRUS and SC/BATSRUS components are special, since they use the same source code
as GM/BATSRUS. The IH component has three versions: the empty version, the BATSRUS share version,
and the BATSRUS version. The BATSRUS share version contains a working wrapper file but otherwise it
shares the source code with the GM/BATSRUS component. Since the source codes are shared, the IH and
GM components cannot run on the same PE-s, and they cannot be configured separately. On the other hand
they use the same variables, so no compilation time and memory are wasted.
The IH/BATSRUS version is also based on the GM/BATSRUS version, however the source code is copied
over and all modules, common blocks, and external subroutines and functions are renamed. These steps are
all automated and can be performed by typing
Config.pl -v=IH/BATSRUS
in the main directory. With the renamed IH/BATSRUS version it is allowed to run IH and GM on the
same PE, and they can be configured differently. The SC/BATSRUS component is also derived from the
GM/BATSRUS source code, but it is configured differently so the source code is always copied and renamed.
This can be achieved by
Config.pl -v=SC/BATSRUS
The copied and renamed source code is removed fully when SWMF is uninstalled with the
Config.pl -uninstall
command. If the SC/BATSRUS or IH/BATSRUS source codes need to be refreshed, the following steps
should be done
cd SC/BATSRUS
make distclean
cd ../..
make SCBATSRUS
and similarly
cd IH/BATSRUS
make distclean
cd ../..
make IHBATSRUS
3.1.3
Selecting Empty component versions with Config.pl
If a physics component is not needed for run, an Empty version of the component can be compiled. Selecting
the Empty version for unused components reduces compilation time and memory usage during run time. It
may also improve performance slightly. This is achieved with the -v flag of the Config.pl script. For example
the Empty UA component can be selected with
3.1. CONFIGURATION OF SWMF
25
Config.pl -v=UA/Empty
It is also possuble to select the Empty version for all components with a few exceptions. For example
Config.pl -v=Empty,GM/BATSRUS,IE/Ridley_serial
will select the empty version for all components except for GM and IE. Note that the ’Empty’ item has to
be the first one.
3.1.4
Registering components using LAYOUT.in
Components can also be excluded from a run by omitting them from the LAYOUT.in file, which means that
the component is not ’registered’ at run time. Note that empty component versions cannot be registered
at all. Component registration allows to run the same executable with different subsets of the components.
For example the GM and IE components can be selected with the following LAYOUT.in file
ID
proc0 last
#COMPONENTMAP
GM
0
999
IE
0
1
#END
stride
1
1
The first column contains the component ID, the second is the root processor for the component, the third
column is the last processor and the last column contains the stride. In the example GM will run on all
available PE-s, while IE will run on the first 2 PE-s. Changing the file to
ID
proc0 last
#COMPONENTMAP
GM
0
999
#END
stride
1
will still use the same executable, but will not allow the IE physics component to participate in the run.
3.1.5
Controlling physics components with PARAM.in
Finally components can be switched on and off during a run with the #COMPONENT command in the
PARAM.in file. This approach allows the component to be switched on in a later ’session’ of the run. For
example, in the first session only GM is running, while in the second session it is coupled to IE. In this
example the IE component can be switched off with the
#COMPONENT
IE
F
NameComp
UseComp
in the first session and it can be switched on with the
#COMPONENT
IE
T
NameComp
UseComp
command in the second session.
26
3.1.6
Setting compiler flags
The debugging flags can be switched on and off with
Config.pl -debug
and
Config.pl -nodebug
respectively. The maximum optimization level can be set to -O2 with
Config.pl -O2
The minimum level is 0, the maximum is 5. Note that not all compilers support level 5 optimization.
Note that not all the components take into account the selected compiler flags. For example the IM/RCM2
component has to be compiled with the -save (or similar) flag, thus it uses the flags defined in the CFLAGS
variable. Also some of the compiler produce incorrect code if they compile certain source files with high
optimization level. Such exceptions are described in the
Makefile.RULES.all
files in the source code directories. The content of this file is processed by Config.pl into Makefile.RULES
(according to the selected compiler and other parameters), which is then included into the main Makefile.
3.1.7
Configuration of individual components
Some of the components can be configured individually. The GM/BATSRUS code, for example, can be configure
to use specific equation and user modules. For example
cd GM/BATSRUS
Config.pl -e=MhdIonsPe
will select the equation module for multiple ion fluids and separate electron pressure. The same can be done
with the Config.pl script in the main SWMF directory
Config.pl -o=GM:e=MhdIonsPe
The grid sizes of the various components can be set with the -g flag of the Config.pl script. For example
the
Config.pl -g=UA:36,36,50,16
will set the blocks size to 36 × 36 × 50 and the number of blocks to 16 for the UA/GITM2 component. This
command runs the Config.pl script of the selected UA component. On machines with limited memory it
is especially important to set the number of blocks correctly.
Of course, the SWMF code has to be recompiled after any of these changes.
3.1.8
Using stubs for all components
It is possible to compile and run SWMF without the physics components but with place holders (stubs) for
them that mimic their behavior. This can be used as a test tool for the CON component, but it may also
serve as an inexpensive testbed for getting the optimal layout and coupling schedule for a simulation. To
configure SWMF with stub components, select the Empty version for all physics components (with Config.pl
-v=...) and edit the Makefile.def file to contain
#INT_VERSION = Interface
INT_VERSION = Stubs
3.2. PARAM.IN
27
for the interface so that the real interface in CON/Interface is replaced with CON/Stubs. The resulting
executable will run CON with the stubs for the physics components. For the stubs one can specify the time
step size in terms of simulation time and the CPU time needed for the time step. The stub components communicate at the coupling time, so the PE-s need to synchronize, but (at least in the current implementation)
there is no net time taken for the coupling itself.
The stub components help development of the SWMF core, but it also allows an efficient optimization
of the LAYOUT and coupling schedules for an actual run, where the physical time steps and the CPU time
needed by the components is approximately known. In the test runs with the Stubs, one can reduce the
CPU times by a fixed factor, so it takes less CPU time to see the efficiency of the SWMF for a given layout
and coupling scheme.
An alternative way to test performance with different configurations is to use the Scripts/Performance.pl
script.
3.2
PARAM.in
The input parameters for the SWMF are read from the PARAM.in file which must be located in the run
directory. This file, together with the LAYOUT.in file, controls the SWMF and its components. There are
many include files in the Param directory. These can be included into the PARAM.in files, or they can serve
as examples.
In the PARAM.in file, the parameters specific to a component are given between the #BEGIN COMP
ID and #END COMP ID commands, where the ID is the two character identifier of the component. For
example the GM parameters are enclosed between the
#BEGIN_COMP GM
...
#END_COMP GM
commands. We refer to the lines starting with a # character as commands.
For example if the command string
#END
is present, it indicates the end of the run and lines following this command are ignored. If the #END
command is not present, the end of the file indicates the end of the run.
There are several features of the input parameter file syntax that allow the user to easily run the code in
a variety of modes while at the same time being able to keep a library of useful parameter files that can be
used again and again.
The syntax and the content of the input parameter files is defined in the PARAM.XML files. The
commands controlling the whole SWMF are described in the
Param/PARAM.XML
file. The component parameters are described by the PARAM.XML file in the component version directory.
For example the input parameters for the GM/BATSRUS component are described in
GM/BATSRUS/PARAM.XML
These files can be read (and edited) in a normal editor. The same files are used to produce much of this
manual with the aid of the share/Scripts/XmlToTex.pl script. The Scripts/TestParam.pl script also
uses these files to check the PARAM.in file. Copying small segments of the PARAM.XML files into PARAM.in
can speed up the creation or modification of a parameter file.
28
3.2.1
Included Files, #INCLUDE
The PARAM.in file can include other parameter files with the command
#INCLUDE
include_parameter_filename
The include files serve two purposes: (i) they help to group the parameters; (ii) the included files can be
reused for other parameter files. An include file can include another file itself. Up to 10 include files can be
nested. The include files have exactly the same structure as PARAM.in. The only difference is that the
#END
command in an included file means only the end of the include file, and not the end of the run, as it does in
PARAM.in.
The user can place his/her included parameter files into the main run directory or in any subdirectory
as long as the correct path to the file from the run directory is included in the #INCLUDE command.
3.2.2
Commands, Parameters, and Comments
As can be seen from the above examples, the parameters are entered with a combination of a command
followed by specific parameter(s), if any. The command must start with a hashmark (#), which is
followed by capital letters and underscores without space in between. Any characters behind the first space
or TAB character are ignored (the #BEGIN COMP and #END COMP commands are the only exception,
but these are markers rather than commands). The parameters, which follow, must conform to requirements
of the command. They can be of four types: logical, integer, real, or character string. Logical parameters
can be entered as .true. or .false. or simply T or F. Integers and reals can be in any of the usual Fortran
formats. In addition, real numbers can be entered as fractions (5/3 for example). All these can be followed
by arbitrary comments, typically separated by space or TAB characters. In case of the character type input
parameters (which may contain spaces themselves), the comments must be separated by a TAB or by at
least 3 consecutive space characters. Comments can be freely put anywhere between two commands as long
as they don’t start with a hashmark.
Here are some examples of valid commands, parameters, and comments:
#TIMEACCURATE
F
DoTimeAccurate
Here is a comment between two commands...
#DESCRIPTION
My first run
#STOP
-1.
100
StringDescription (3 spaces or TAB before the comment)
tSimulationMax
MaxIteration
#RUN ------------ last command of this session ----------------#TIMEACCURATE
T
DoTimeAccurate
#STOP
10.0
tSimulationMax
3.2. PARAM.IN
-1
29
MaxIteration
#BEGIN_COMP IH
#GAMMA
5/3
Gamma
#END_COMP IH
3.2.3
Sessions
A single parameter file can control consecutive sessions of the run. Each session looks like
#SOME_COMMAND
param1
param2
...
#STOP
max_simulation_time_for_this_session
max_iter_for_this_session
#RUN
while the final session ends like
#STOP
max_simulation_time_for_final_session
max_iter_for_final_session
#END
The purpose of using multiple sessions is to be able to change parameters during the run. For example one
can use only a subset of the components in the first session, and add more components in the later session.
Or one can obtain a coarse steady state solution on a coarse grid with a component in one session, and
improve on the solution with a finer grid in the next session. Or one can switch from steady state mode to
time accurate mode. The SWMF remembers parameter settings from all previous sessions, so in each session
one should only set those parameters which change relative to the previous session. Note that the maximum
number of iterations given in the #STOP command is meant for the entire run, and not for the individual
sessions. On the other hand, when a restart file is read, the iterations prior to the current run do not count.
The PARAM.in file and all included parameter files are read into a buffer at the beginning of the run, so
even for multi-session runs, changes in the parameter files have no effect once PARAM.in has been read.
3.2.4
The Order of Commands
In essence, the order of parameter commands within a session is arbitrary, but there are some important
restrictions. We should note that the order of the parameters following the command is not arbitrary and
must exactly match what the code requires. Here we restrict ourselves to the restrictions on the commands
read by the control module of SWMF. There may be (and are) restrictions for the commands read by the
components, but those are described in the documentation of the components.
30
The only strict restriction on the SWMF commands is related to the ’planet’ commands. The default
values of the planet parameters are defined by the #PLANET command. For example the parameters of
Earth can be selected with the
#PLANET
Earth
NamePlanet
command. The true parameters of Earth can be modified or simplified with a number of other commands
which must occur after the #PLANET command. These commands are (without showing their
parameters)
#IDEALAXES
#ROTATIONAXIS
#MAGNETICAXIS
#ROTATION
#DIPOLE
Other than this strict rule, it makes sense to follow a ’natural’ order of commands. This will help in
interpreting, maintaining and reusing parameter files.
If you want all the input parameters to be echoed back, the first command in PARAM.in should be
#ECHO
T
DoEcho
If the code starts from restart files, it usually reads in a file which was saved by SWMF. The default name
of the saved file is RESTART.out and it is written into the run directory. It should be renamed, for example
to RESTART.in, so that it does not get overwritten during the run. It can be included as
#INCLUDE
RESTART.in
The SWMF will read the following commands (the parameter values are examples only) from the included
file:
#DESCRIPTION
Create startup for GM-IM-IE-UA from GM steady state.
#PLANET
EARTH
NamePlanet
#STARTTIME
1998
5
1
0
0
0
0.000000000000
iYear
iMonth
iDay
iHour
iMinute
iSecond
FracSecond
#NSTEP
4000
nStep
#TIMESIMULATION
0.00000000E+00
tSimulation
3.2. PARAM.IN
#VERSION
2.00
#PRECISION
8
31
VersionSwmf
nByteReal
The #PLANET command defines the selected planet. The #STARTTIME command defines the starting
date and time of the whole simulation. The current simulation time (which is relative to the starting date and
time) and the step number are given by the #TIMESIMULATION and #NSTEP commands. Finally the
#VERSION and #PRECISION commands check the consistency of the current version and real precision
with the run which is being continued. As it was explained above, all modifications of the planet parameters
should follow the #PLANET command, i.e. they should be after the #INCLUDE RESTART.in command.
In case the description is changed it should also follow, e.g.
#INCLUDE
RESTART.in
#DESCRIPTION
We continue the run for another 2 hours
#IDEALAXES
When the run starts from scratch, the PARAM.in file should start similarly with the
#DESCRIPTION
This is the start up run
#PLANET
SATURN
#STARTTIME
2004
8
15
1
25
0
0.000000000000
iYear
iMonth
iDay
iHour
iMinute
iSecond
FracSecond
commands (the parameters are examples only). These commands are typically followed by the planet
parameter modifying commands, if any, and setting time accurate mode (if changed from default true to
false or relative to the previous session). For example:
! Align the rotation and magnetic axes with Z_GSE
#IDEALAXES
#TIMEACCURATE
F
DoTimeAccurate
All the commands which are written into the RESTART.out file and all the planet modifying commands can
only occur in the first session. These commands contain parameters which should not change during a run.
In the Param/PARAM.XML file these commands are marked with an if="$ IsFirstSession" conditional.
32
If any of these parameters are attempted to be changed in later sessions, a warning is printed on the screen
and the code stops running (except when the code is in non-strict mode).
Most command parameters have sensible default values. These are described in the PARAM.XML files,
and in chapter 5 (which was produced from them). The PARAM.XML file also defines which commands are
required with the required="T" attribute of the <command...> tag. For the control module the only required
command is the #STOP command, which defines the final time step or the final time of the run.
3.2.5
Iterations, Time Steps and Time
In several commands the frequency or ‘time’ of some action has to be defined. This is usually done with a
pair of parameters. The first defines the frequency or time in terms of the number of time steps, and the
second in terms of the simulation time. A negative value for the frequency means that it should not be taken
into account. For example, in time accurate mode,
#SAVERESTART
T
DoSaveRestart
2000
DnSaveRestart
-1.
DtSaveRestart
means that a restart file should be saved after every 2000th time step, while
#SAVERESTART
T
DoSaveRestart
-1
DnSaveRestart
100.0
DtSaveRestart
means that it should be saved every 100 seconds in terms of physical time. Defining positive values for both
frequencies might be useful when switching from steady state mode to time accurate mode. In the steady
state mode the DnSaveRestart parameter is used, while in time accurate mode the DtSaveRestart if it is
positive. But it is more typical and more intuitive to explicitly repeat the command in the first time accurate
session with the time frequency set.
The purpose of this subsection is to try to help the user understand the difference between the iteration
number used for stopping the code and the time step which is used to define the frequencies of various
actions. After using BATS-R-US over several years, it is clear to the authors that this distinction is useful
and the most reasonable implementation. The SWMF has inherited these features from the BATS-R-US
code.
We begin by defining several different quantities and the variables that represent them in the code. The
variable nIteration, represents the number of “iterations” that the simulation has taken since it began
running. This number starts at zero every time the code is run, even if beginning from a restart file. This
is reasonable since most users know how many iterations the code can take in a certain amount of CPU
time and it is this number that is needed when running in a queue. The quantity nStep is a number of
“time steps” that the code has taken in total. This number starts at zero when the code is started from
scratch, but when started from a restart file, this number will start with the time step at which the restart
file was written. This implementation lets the user output data files at a regular interval, even when a restart
happens at an odd number of iterations. The quantity tSimulation is the amount of simulated, or physical,
time that the code has run. This time starts when time accurate time stepping begins. When restarting,
it starts from the physical time for the restart. Of course the time should be cumulative since it is the
physically meaningful quantity. We will use these three phrases( “iteration”, “time step”, “time”) with the
meanings outlined above.
Now, what happens when the user has more than one session and he or she changes the frequencies. Let
us examine what would happen in the following sample of part of a PARAM.in file. For the following example
we will assume that when in time accurate mode, 1 iteration simulates 1 second of time. Columns to the
right indicate the values of nITER, n step and time simulation at which restart files will be written in each
session.
3.2. PARAM.IN
==SESSION 1
#TIMEACCURATE
F
DoTimeAccurate
#SAVERESTART
T
DoSaveRestart
200
DnSaveRestart
-1.0
DtSaveRestart
#STOP
400
-1.
33
Session
--------
Restart Files Written at:
nITER
nStep
time_simulation
------ ------- --------------
1
1
200
400
200
400
0.0
0.0
2
2
600
900
600
900
0.0
0.0
3
3
3
1100
1200
1300
1100
1200
1300
100.0
200.0
300.0
4
4
4
1400
1800
2000
1400
1800
2000
400.0
800.0
1000.0
MaxIteration
tSimulationMax
#RUN ==END OF SESSION 1==
#SAVERESTART
T
DoSaveRestart
300
DnSaveRestart
-1.0
DtSaveRestart
#STOP
1000
-1.
MaxIteration
tSimulationMax
#TIMEACCURATE
T
DoTimeAccurate
#SAVERESTART
T
DoSaveRestart
-1
DnSaveRestart
100.0
DtSaveRestart
#STOP
-1
300.0
MaxIteration
tSimulationMax
#SAVERESTART
T
DoSaveRestart
-1
DnSaveRestart
400.0
DtSaveRestart
#STOP
-1
1000.0
#END
MaxIteration
tSimulationMax
==END OF SESSION 4==
34
Now the question is how many iterations will be taken and when will restart file be written out. In session 1
the code will make 400 iterations and will write a restart file at time steps 200 and 400. Since the iterations
in the #STOP command are cumulative, the #STOP command in the second session will have the code make
600 more iterations for a total of 1000. Since the timing of output is also cumulative, a restart file will be
written at time step 600 and at 900. After session 2, the code is switched to time accurate mode. Since
we have not run in this mode yet the simulated (or physical) time is cumulatively 0. The third session will
run for 300.0 simulated seconds (which for the sake of this example is 300 iterations). The restart file will
be written after every 100.0 simulated seconds. The #STOP command in Session 4 tells the code to simulate
700.0 more seconds for a total of 1000.0 seconds. The code will make a restart file when the time is a multiple
of 400.0 seconds or at 400.0 and 800.0 seconds. Note that a restart file will also be written at time 1000.0
seconds since this is the end of a run.
In the next example we want to restart from 1000.0 seconds and continue with a time accurate run.
==SESSION 1
Session
-------1
#INCLUDE
RESTART.in
Restart Files Written at:
nITER
nStep
time_simulation
------ ------- -------------0
2000
1000.0
#TIMEACCURATE
T
DoTimeAccurate
#SAVERESTART
T
DoSaveRestart
-1
DnSaveRestart
600.0
DtSaveRestart
#STOP
-1
1400.0
1
200
2200
1200.0
2
2
700
1000
2700
3000
1500.0
2000.0
MaxIteration
tSimulationMax
#SAVERESTART
T
DoSaveRestart
-1
DnSaveRestart
750.0
DtSaveRestart
#STOP
-1
2000.0
MaxIteration
tSimulationMax
#END ==END OF SESSION 2 =
In this example, we see that in time accurate mode the simulated, or physical, time is always cumulative.
To make 400.0 seconds more simulation, the original 1000.0 seconds must be taken into account. The final
output at 2000.0 seconds is written because the run ended.
Throughout this subsection, we have used the frequency of writing restart files as an example. The
frequencies of coupling components and checking stop files work similarly. In the SWMF, and potentially in
any of the components, the frequencies are handled by the general
share/Library/src/ModFreq
3.3. EXECUTION AND COUPLING CONTROL
35
module which is described in the reference manual.
3.3
Execution and Coupling Control
The control module of SWMF controls the execution and coupling of components. The control module is controlled by the user through the component layout file LAYOUT.in and the input parameter file PARAM.in.
Defining the most efficient layout, execution and coupling control is not an obvious task. In the current
version of SWMF the processor layout of the components is static. This restriction is somewhat mitigated
by the possibility of restart, which allows to change the processor layout from one run to another.
3.3.1
Processor Layout: LAYOUT.in
Within one run the layout is determined by the #COMPONENTMAP command in the LAYOUT.in file.
The exact syntax of this file is documented in the reference manual of the CON world class. Here we provide
several examples which will help to develop a sense of using optimal layouts. An optimal layout is one that
maximizes the use of all processors and does not leave processors with nothing do while waiting for other
processors to finish their work.
First of all we have to define the processor rank: it is a number ranging from 0 to N − 1, where N is the
total number of processors in the run. A component can run on a subset of the processors, which is defined
by the rank of the first (root) processor, the rank of the last processor, and the stride. For example if the
root processor has rank 4, the last processor has rank 8, and the stride is 2 than the component will run on
3 processors with ranks 4, 6 and 8.
One component
In the simplest case a single component, say the Global Magnetosphere (GM) is running. The LAYOUT.in
file should be the following
ID
proc0 last stride
#COMPONENTMAP
GM
0
999
1
#END
If the SWMF is run on less than 999 processors (which is likely), the rank of the last processor will be
reduced to the maximum rank of the processors, which is N − 1 if the SWMF is running on N processors.
One serial and one parallel component
When two components are used, their layouts may or may not overlap. An example for overlapping the
layouts of the GM and the Inner Magnetosphere (IM) components is
ID
proc0 last stride
#COMPONENTMAP
IM
0
0
1
GM
0
999
1
#END
When the component layouts overlap, the two components can run sequentially only. Since IM is using a
single processor only (because it is not a parallel code), all the other processors will be idling while IM is
running. This can be rather inefficient, especially if the CPU time required by IM is not negligible. A more
efficient execution can be achieved with a non-overlapping layout:
36
ID
proc0 last stride
#COMPONENTMAP
IM
0
0
1
GM
1
999
1
#END
Note that this layout file will work for any number of processors from 2 and up.
Two parallel components with different speeds
It is not always possible, or even efficient to use non-overlapping layouts. For example both the SC and IH
components require a lot of memory, but the IH component runs much faster (say 100 times faster) in terms
of cpu time than the SC component (this is due to the larger cells and smaller wave speeds in IH). If we tried
to use concurrent execution on 101 processors, SC should run on 100 and IH on 1 processors to get good load
balancing. However the IH component needs much more memory than available on a single processor. It is
therefore not possible to use a non-overlapping layout for SC and IH on a reasonable number of processors.
Fortunately both the Solar Corona (SC) and Inner Heliosphere (IH) components are modeled by BATSR-US, which is a highly parallel code with good scaling. The following layout can be optimal:
ID
proc0 last stride
#COMPONENTMAP
IH
0
999
1
SC
0
999
1
#END
Although IH and SC will execute sequentially, they both use all the available CPU-s, so no CPU is left
waiting for the others.
Two parallel components with similar speeds
If two parallel components need about the same CPU time/real time on the same number of processors, the
optimal layout can be
ID
proc0 last stride
#COMPONENTMAP
GM
0
999
2
SC
1
999
2
#END
Here GM is running on the processors with even rank, while SC is running on the processors with odd ranks.
By using the processor stride, this layout works on an arbitrary number of processors.
When more serial and parallel codes are executing together, finding the optimal layout may not be trivial.
It may take some experimentation to see which component is running slower or faster, how much time is
spent on coupling two components, etc. It may be a good idea to test the components separately or in
smaller groups to see how fast they can execute.
A complex example with four components
Here is an example with 4 components: the Ionospheric Electrodynamics (IE) component can run on 2
processors and runs about 3 times faster than real time. The serial Inner Magnetosphere (IM) component
runs even faster, on the other hand the coupling of GM and IM is rather computationally expensive. The
Upper Atmosphere (UA) component can run on up to 32 processors, and it runs twice as fast as real time.
The Global Magnetosphere model (GM) needs at least 32 processor to run faster than real time. If we have
a lot of CPU-s, we may simply create a non-overlapping layout. Since GM has no restriction on the number
of processors, it can be the last component in the map
37
ID
proc0 last stride
#COMPONENTMAP
IM
0
0
1
IE
0
1
1
UA
2
33
1
GM
34
999
1
#END
This layout will be optimal in terms of speed for a large (more than 100) number of PE-s, and actually the
maximum speed is going to be limited by the components which do not scale. On a more modest number of
PE-s one can try to overlap UA and GM:
ID
proc0 last stride
#COMPONENTMAP
IM
0
0
1
IE
1
2
1
UA
0
31
1
GM
3
999
1
#END
3.3.2
Steady State vs. Time Accurate Execution
The SWMF can run both in time accurate (default) and steady state mode. This sounds surprising first,
since many of the components can run in time accurate mode only. Nevertheless, the SWMF can improve the
convergence towards a steady state by allowing the different components to run at different speeds in terms
of the physical time. In BATS-R-US the same idea is used on a much smaller scale: local time stepping
allows each cell to converge towards steady state as fast as possible, limited only by the local numerical
stability limit.
Steady state session
The steady state mode should be signaled with the
#TIMEACCURATE
F
DoTimeAccurate
command, usually placed somewhere at the beginning of the session. Since the SWMF runs in time accurate
mode by default, this command is required in the first steady state session of the run.
When SWMF runs in steady state mode, the SWMF time is not advanced and tSimulation usually
keeps its default initial value, which is zero. The components may or may not advance their own internal
times. The execution is controlled by the step number nStep, which goes from its initial value to the final
step allowed by the MaxIteration parameter of the #STOP command. The components are called at the
frequency defined by the #CYCLE command. For example
#CYCLE
GM
1
#END
NameComp
DnRun
#CYCLE
IM
2
#END
NameComp
DnRun
38
means that IM runs in every second time step of the SWMF. By defining the DnRun parameter for all
the components, an arbitrary relative calling frequency can be obtained, which can optimize the global
convergence rate to steady state. The default frequency is DnRun=1, i.e. the component is run in every
SWMF time step.
The relative frequency can be important for numerical stability too. When GM and IM are to be relaxed
to a steady state, the GM/BATSRUS code is running in local time stepping mode, while IM/RCM runs in
time accurate mode internally. Since GM and IM are coupled both ways, an instability can occur if both
GM and IM are run every time step, because the GM physical time step is very small, and the MHD solution
cannot relax while being continuously pushed by the IM coupling. This unphysical instability can be avoided
by calling the IM component less frequently.
The coupling frequencies should be set to be optimal for reaching the steady state. If the components are
coupled too frequently, a lot of CPU time is spent on the couplings. If they are coupled very infrequently,
the solution may become oscillatory instead of relaxing into a (quasi-)steady state solution. For example we
used the
#COUPLE2
IMNameComp1
GMNameComp2
10
-1.
DnCouple
DtCouple
command to couple the GM and IM components in both directions in every 10-th SWMF iteration. Note
that according to the above #CYCLE commands, GM and IM do 10 and 5 steps between two couplings,
respectively. GM/BATSRUS uses 10 local time steps, while IM advances by 5 five-second time steps.
Another example is the relaxation of SC and IH components. Under usual conditions the solar wind is
supersonic at the inner boundary of the IH component, thus the steady state SC solution can be obtained
first, and then IH can converge to a steady state using the SC solution as the inner boundary condition. In
this second stage SC does not need to run (assuming that it has reached a good steady state solution), it is
only needed for providing the inner boundary condition for IH. This can be achieved by
! No need to run SC too often, it is already in steady state
#CYCLE
SC
NameComp
1000
DnRun
! No need to couple SC too often
#COUPLE2
SC
NameSource
IH
NameTarget
1000
DnCouple
-1.0
DtCouple
Since SC and IH are always coupled at the beginning of the session, further couplings are not necessary.
Time accurate session
The SWMF runs in time accurate mode by default. The
#TIMEACCURATE
T
DoTimeAccurate
command is only needed in a time accurate session following a steady state session. In time accurate mode the
components advance in time at approximately the same rate. The component times are only synchronized
when necessary, i.e. when they are coupled, when restart files are written, or at the end of session and
39
execution. Since the time steps (in terms of physical and/or CPU time) of the components can be vastly
different, this minimal synchronization provides the most possibilities for efficient concurrent execution.
By default the component time steps are limited by the time of couplings. This means that if GM can
take 4 second times steps, and it is coupled with IE every 5 seconds, then every second GM time step will
be truncated to 1 second. There are two ways to avoid this. One is to choose the coupling frequencies to be
round multiples of the time steps of the two components involved. This works well if both components have
fixed time steps and/or much smaller time steps than the coupling frequency.
In certain cases the efficiency can be improved with the #COUPLETIME command, which can allow a
component to step through the coupling time. For example
#CYCLE
GM
F
NameComp
DoCoupleOnTime
will allow the GM component to use 4 second time steps even if it is coupled at every 5 seconds. Of course
this will make the data transferred during the coupling be first order accurate in time.
3.3.3
Coupling order
The default coupling order is usually optimal for accuracy and consistency, but it may not be optimal for
speed. In particular, the IE/Ridley serial component solves a Poisson type equation for the data received
from the other components (GM and UA). For sake of accuracy IE always uses the latest data received from
the other components. If GM, UA and IE are coupled in the default order
#COUPLEORDER
4
nCouple
GM IE
NameSourceTarget
UA IE
NameSourceTarget
IE UA
NameSourceTarget
IE GM
NameSourceTarget
and the to-IE and from-IE coupling times coincide, e.g.
#COUPLE2
GM
IE
10.0
-1
NameComp1
NameComp2
DtCouple
DnCouple
#COUPLE2
UA
IE
10.0
-1
NameComp1
NameComp2
DtCouple
DnCouple
then GM and UA will have to wait until IE solves the Poisson equation, because IE receives new data and
it is required to produce results immediately. With the reversed coupling order
#COUPLEORDER
4
nCouple
IE UA
NameSourceTarget
IE GM
NameSourceTarget
GM IE
NameSourceTarget
UA IE
NameSourceTarget
40
IE will provide the solution from the previously received data, and it will have time to work on the new
data while GM and UA are working on their time steps. The reversed coupling order allows the concurrent
execution of IE with other components. The temporal accuracy, on the other hand, will be somewhat worse.
To demonstrate that the coupling order is important, here is a very inefficient coupling order
#COUPLEORDER
4
GM IE
IE GM
UA IE
IE UA
nCouple
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
in case the coupling times with GM and UA coincide (always at the beginning of a the sessions). With
this coupling order, IE first receives information from GM, then solves the Poisson equation and returns the
information based on the solution to GM while GM is waiting. Then IE receives extra information from UA,
solves the Poisson equation again, and sends back information to UA, while UA is waiting.
An alternative way to achieve concurrent execution is to stagger the coupling times. For example the
#COUPLE2SHIFT
GM
IE
-1
10.0
-1
0.0
-1
5.0
NameComp1
NameComp2
DnCouple
DtCouple
nNext12
tNext12
nNext21
tNext21
will schedule a GM to IE coupling at 0, 10, 20, 30, . . . seconds, and the IE to GM coupling at 5, 15, 25,
. . . seconds. This provides IE half the GM time to solve the Poisson equations. If IE runs at least twice
as fast as GM, this solution will produce concurrent execution. The temporal accuracy is somewhat better
than in the reversed coupling case. Note that GM and IE will be synchronized at 0, 5, 10, . . . seconds, which
works best if the GM time step is an integer fraction of 5 seconds.
Chapter 4
Example Runs
The examples in this chapter are intended to make you familiar with the use of the SWMF. By carefully
following the steps you should be able to do the tests as described. It is a good idea to read the provided
PARAM.in and LAYOUT.in files and try to understand how the examples work. You may also experiment
by changing these files after copied from the originals. These examples should help you in setting up your
own runs.
For sake of simplicity we describe how to do all the example runs with the same executable. In actual
runs one would streamline the configuration of the SWMF to reduce compilation time and memory use. If
you work on a machine with limited resources, you may wish to configure SWMF differently. For example,
you may set the Empty version for the unused components. If the number of processors is limited, you will
have to change the LAYOUT.in file and overlap the components. You may also have to increase the allowed
grid size per processor, or you can run the problem with a coarser grid resolution. To reduce the CPU time,
you may shorten the run by changing the number of iterations or the final time in the PARAM.in file.
4.1
Configuration and Compilation for the Examples
Select the SC/BATSRUS component version. When this is done the first time after installation, the
SC/BATSRUS source code is created from the GM/BATSRUS source code, which takes a few minutes:
Config.pl -v=SC/BATSRUS -g=SC:4,4,4,1000
Set the grid size for the GM/BATSRUS and IH/BATSRUS share components:
Config.pl -g=GM:8,8,8,200,40
You can select either the UA/GITM version with
Config.pl -v=UA/GITM -g=UA:9,9,25,2,2
or the new (default) UA/GITM2 version with
Config.pl -v=UA/GITM2 -g=UA:9,9,25,4
Note the difference in the grid size parameters. You should also take care of using the parameter files
appropriate for the selected UA component version. GITM2 is the default UA module currently in the
SWMF and is the most up to date.
Check the current settings with
Config.pl -show
41
42
CHAPTER 4. EXAMPLE RUNS
You should see the current directory, the operating system, the name of the compiler and the following
settings
The default precision for reals is double precision.
The selected component versions and grid sizes are:
GM/BATSRUS
grid: 8,8,8,200,40
IE/Ridley_serial
IH/BATSRUS
grid: 8,8,8,200,40
IM/RCM
RB/RiceV5
SC/BATSRUS
grid: 4,4,4,1000
SP/Kota
grid: 1000,10,150
UA/GITM2
grid: 9,9,25,4
In case you selected the UA/GITM version, the last line will read
UA/GITM
grid: 9,9,25,2,2
If the settings differ you can change them with the Config.pl script.
Compile the main executable code bin/SWMF.exe. With the above settings this may take an hour, but
if you select Empty versions for the unused components, it will take much less. You should also compile the
post processing code bin/PostIDL.exe, and finally create a run directory and change to that directory
make
make PIDL
make rundir
cd run
Note that the run directory contains subdirectories for all the non-empty components. There is also a link
to the Param directory in the main SWMF directory. The Param directory contains all the parameter and
layout files used in the example runs.
4.2
Example 1: Create Steady State for the Solar Corona
This example involves the SC component only. It demonstrates how a steady state solar corona can be
obtained from a magnetogram. The convergence to steady state is accelerated by a gradual grid refinement
and a gradual application of the more-and-more accurate numerical schemes. The final state is a steady
state to high accuracy.
You can use the SWMF with the settings recommended above but you only need the SC component and
all other component versions can be Empty.
Copy the PARAM.in and LAYOUT.in files
rm -f PARAM.in LAYOUT.in
cp Param/PARAM.in.test.start.SC.AMR8 PARAM.in
cp Param/LAYOUT.in.test.start.SC LAYOUT.in
We recommend the AMR8 version of the parameter file because it creates a smaller grid and reaches steady
state in smaller number of iterations than the higher resolution version (AMR9). For the milestone problem
we used the higher resolution.
Check the parameter and layout files with the TestParam.pl script. This script should be run from the
main directory. Define the number of CPU-s you plan to use with the -n=NUMBER flag. For example
cd ..
Scripts/TestParam.pl -n=32
4.2. EXAMPLE 1: CREATE STEADY STATE FOR THE SOLAR CORONA
43
The script should return without any warnings and error messages. If there are error messages, fix them. For
example if the grid is not large enough there will be an error message from the command #CHECKGRIDSIZE
with respect to the parameter MinBlockALL, which contains the minimum number of blocks required. To
fix the problem, you have to increase the number of CPU-s or increase the grid size for the SC component
with the Config.pl script. For example set
Config.pl -g=SC:4,4,4,1500
Keep fixing the problems until the Scripts/TestParam.pl runs silently. Remember to recompile SWMF.exe
if you change the grid size.
Run the code by submitting a job or do it interactively
cd run
mpirun -np 32 SWMF.exe | tee runlog.SC
Here ’tee’ is a Unix command which splits the output to the screen as well as pipes it to the file ’runlog.SC’.
Depending on the number of processors and the speed of the machine, this run should take a few to
several hours to complete. You may check the progress on the screen, or look at the runlog.SC file, or look
at the log file written by the code
tail SC/IO2/log*
This file contains information determined by the #SAVELOGFILE command in the PARAM.in file. In this
case the file contains the time step, the time (which is zero, because this is a steady state run) and the
magnetic, kinetic and thermal energies integrated over the surface of two spheres of radii 4 and 10. As the
code approaches steady state, the integrated energies will change less and less.
When the run finishes successfully (or even while the code is running), you can postprocess the plot files
cd SC
pIDL
pTEC p r
cd ..
The ’p’ and ’r’ flags for the pTEC script mean that the raw ASCII data files are preprocessed with preplot
into .plt files and the ASCII data files are removed. If the machine does not have the ’preplot’ code installed
(preplot is a script that comes with the Tecplot software), you can gzip the .dat files to save disk space and
transfer time
pTEC g
You can visualize the output files in run/SC/IO2 with your favored visualization software. For visualization
with IDL you should read the chapter on “IDL visualization” in the user manual in GM/BATSRUS/Doc.
The restart files were saved into RESTART.SC and the SC/restartIN directory. These are not the default
names, they were set in the PARAM.in file with the #RESTARTFILE command for the control module of
the SWMF and with the #RESTARTOUTDIR command for the SC/BATSRUS component. This makes it
easier to use the run in the following example run.
The alternative and more typical approach would be to write into the default restart file RESTART.out
and the default directory SC/restartOUT, and use the Restart.pl script to create a restart tree, e.g.
Restart.pl RESTART_SC
44
4.3
Example 2: Create SC-IH Steady State
This example run is built on the previous example. We restart SC from the steady state created in the
previous run and start the IH component from scratch and run the two components coupled until the IH
component reaches a steady state.
First copy in the prepared parameter and layout files
cp Param/PARAM.in.test.restart.SCIH PARAM.in
cp Param/LAYOUT.in.test.restart.SCIH LAYOUT.in
Look at the PARAM.in file to see how the convergence to steady state is accelerated. First of all the SC
component only provides the boundary conditions for IH, so it only runs in every 100th iteration (see the
#CYCLE command in the PARAM.in file). Second, the IH grid is built up with a gradual grid refinement,
and third the more-and-more accurate and expensive numerical schemes are applied in an optimal sequence.
The final state is a steady state for SC and IH to high accuracy.
You can use the SWMF with the settings recommended for all the examples, but you only need the SC
and IH components so all other component versions can be Empty.
As usual, check the input parameters and the layout for the number of CPU-s you plan to use, for example
cd ..
If there are error messages, fix them until the script runs silently.
Run the code by submitting a job, or interactively
cd run
mpirun -np 32 SWMF.exe | tee runlog.SCIH
When the run finishes, postprocess the plot files for both components
cd SC
pIDL
pTEC
cd ../IH
pIDL
pTEC p r
cd ..
Due to the commands #RESTARTFILE and #RESTARTOUTDIR (in the IH section) the output restart
file is saved into RESTART.SCIH and the IH component saved the restart state into the IH/restartIN. The
SC component saved the restart state into the default SC/restartOUT. For a continuation run one could
move and link the directories in SC with the following Unix commands
cd SC
mv restartIN restart_SConly
mv restartOUT restart_SCIH
mkdir restartOUT
ln -s restart_SCIH restartIN
cd ..
As you can see this is a rather cumbersome and error prone procedure. It is better to save the restart state
into their default file and directories and use the Restart.pl script to collect them into a restart tree and to
link the input file and directories to them.
4.4. EXAMPLE 3: CREATE INITIAL CONDITIONS FOR THE GLOBAL
MAGNETOSPHERE
4.4
45
Example 3: Create Initial Conditions for the Global Magnetosphere
This example involves the GM component only. It demonstrates how a reasonable global magnetosphere can
be obtained. The upwind boundary conditions are based on the solution obtained for the IH component in
the 2nd example run, but they are intentionally modified to contain a discontinuity. This is for demonstration
purposes only to make a subsequent GM-IH coupled run more dynamic. In a more typical run one would
use the upwind boundary condition based on satellite measurements or by coupling to the IH code.
The convergence to steady state is accelerated by a gradual grid refinement, and a gradual application
of the more-and-more accurate numerical schemes. The final state is a reasonable global magnetosphere
solution, but it is not a perfect steady state (that would require many more iterations).
First copy in the prepared parameter and layout files and check them
cp Param/PARAM.in.test.start.GM PARAM.in
cp Param/LAYOUT.in.test.start.GM LAYOUT.in
The parameters of the #SOLARWIND command were obtained from the result of the SC-IH steady state.
Otherwise this test can be run independently, no restart files are read. You can use the SWMF with the
settings recommended for all the tests, but you only need the GM component, so all other component versions
can be set to Empty.
Check the parameters and layout before running the SWMF
cd ..
If there are error messages, fix them until the script reports no errors. Run the code by submitting a job, or
interactively
cd run
mpirun -np 16 SWMF.exe | tee runlog.GM
Postprocess the plot files
cd GM
pIDL
pTEC p r
cd ..
The output restart file is RESTART.GM and the GM component saved its restart files into GM/restart.IN
as determined by the PARAM.in file.
4.5
Example 4: Create Initial Conditions for the GM, IM, IE and
UA Components
This example involves the GM, IM, IE and UA components. It demonstrates how to obtain a reasonable
solution for the coupled global/inner magnetosphere, ionosphere and upper atmosphere. The initial global
magnetosphere solution is taken from Example 3.
Copy the layout file into the run directory
cp Param/LAYOUT.in.test.restart.GMIMIEUA LAYOUT.in
If you are using the UA/GITM2 component version, copy this parameter file:
46
cp Param/PARAM.in.test.restart.GMIMIEUA.GITM2 PARAM.in
If you are using the UA/GITM component version, copy this parameter file:
cp Param/PARAM.in.test.restart.GMIMIEUA PARAM.in
Have a look at the PARAM.in file. The convergence to steady state is accelerated by component subcycling
(see the #CYCLE commands in PARAM.in). The components are called at different frequencies, which
allows the components to reach a reasonable solution approximately at the same rate. Another optimization
trick is the changing of the coupling order such that the IE component sends information before it would
receive it (see the #COUPLEORDER command in PARAM.in), so that IE component can solve for the
electric potential concurrently with the other components running. To reduce the time spent on field line
tracing, which is needed for the IM to GM coupling, the #RAYTRACE command in the GM section limits
the frequency of traces to every 80th iteration.
Now have a look at the LAYOUT file:
#COMPONENTMAP
UA
0
31
IM
32
32
IE
33
34
GM
35 999
#END
1
1
1
1
As you can see all the components are running concurrently. Unless you have access to at least 64 processors,
you probably want to modify the layout file. For example for 32 processors you can overlap the UA component
with the other components and run IE on a single processor:
#COMPONENTMAP
UA
0
31
IE
0
0
IM
1
1
GM
2
31
#END
1
1
1
1
You can use the SWMF with the settings recommended for all the tests, but you only need the GM, IM, IE
and UA components, all other component versions can be Empty.
Check the parameters and layout for the number of processors you plan to use
cd ..
If there are error messages, fix them. Run the code by submitting a job, or interactively
cd run
mpirun -np 32 SWMF.exe | tee runlog.GMIMIEUA
This run should take an hour or so on 32 processors. After the run postprocess the plot files
cd GM
pIDL
pTEC p r
cd ../IE
pION
cd ..
The pION script concatenates the northern and southern output files produced by the component IE/Ridley serial.
In this run all output restart information is saved into the default file (RESTART.out) and default
directories. You can use the RESTART.pl script to collect them into a restart tree. For example
Restart.pl -o RESTART_GMIMIEUA
4.6. EXAMPLE 5: TIME ACCURATE RUN WITH SC, IH AND SP COMPONENTS
4.6
47
Example 5: Time Accurate Run with SC, IH and SP Components
This example involves the Solar Corona, Inner Heliosphere and Solar Energetic Particles components. The
run starts from a steady state of the SC and IH components which was obtained in Example 2.
Copy in the prepared parameter and layout files
cp Param/PARAM.in.test.restart.SCIHSP PARAM.in
cp Param/LAYOUT.in.test.restart.SCIHSP LAYOUT.in
At the beginning of this time accurate run a CME is generated in the SC component. This demonstrates the
use of an Eruptive Event generator. The SP component is coupled, and during the 4 hour evolution of the
CME, substantial particle acceleration is observed. By the end of the run the CME reaches the boundary
between the SC and IH components, and partially enters the IH domain. The test demonstrates the coupling
between the SC-IH and SP components in a challenging simulation.
In case you have limited computational resources, you can shorten the run by editing the PARAM.in file
and changing the #STOP command at the end of the file. For example
#STOP
-1
1800.0
MaxIteration
tSimulationMax
will reduce the final simulation time to 30 minutes.
Also have a look at the layout file:
#COMPONENTMAP
SC
1 999
1
IH
1 999
1
SP
0
0
1
#END
The SC and IH components are overlapped while the SP component runs concurrently. This is probably the
optimal layout for any number of CPU-s.
You can use the SWMF with the settings for all the tests, but you only need the SC, IH and SP
components, all other component versions can be Empty.
Check the parameters and layout before running the SWMF
cd ..
If there are error messages, fix them, then run the SWMF by submitting a job or interactively
cd run
mpirun -np 32 SWMF.exe | tee runlog.SCIHSP
This run may take a long time if run all the way to 4 hours. After the run finishes, postprocess the plot files
cd SC
pIDL
pTEC p r
cd ../IH
pIDL
pTEC p r
cd ..
48
The restart files can be collected into a restart tree with the Restart.pl script. For the full 4 hour run you
could use
Restart.pl -o RESTART_SCIHSP_4hr
4.7
Example 6: Time Accurate Run with All Eight Components
This run is described in the TESTING manual. The initial conditions were created with the runs described
in this chapter using the higher resolution SC grid (AMR9) and the full 4 hour time accurate run with the
SC-IH and SP components.
For sake of learning SWMF you can do this example with lower SC resolution (AMR8) and do a shorter
time accurate run with the SC, IH and SP components.
Copy the layout file into the run directory
cp Param/LAYOUT.in.test.restart.8comp LAYOUT.in
If you are using the UA/GITM2 component version, copy this parameter file:
cp Param/PARAM.in.test.restart.8comp.GITM2 PARAM.in
If you are using the UA/GITM component version, copy this parameter file:
cp Param/PARAM.in.test.restart.8comp PARAM.in
This example is desinged to run for 600 seconds only. It is assumed that the input restart file RESTART.in
contains the simulation time corresponding to 4 hours (14400 seconds), so the final time in the #STOP
command is 15000 seconds in the PARAM.in file. In case you are restarting from a different simulation
time and/or you wish to change the length of the run, edit the maximum simulation time in the #STOP
command in the PARAM.in file.
To simplify this example run, you can remove some of the components. To remove a component you need
to edit the LAYOUT.in file and remove the appropriate line, and edit the PARAM.in file, and remove the
section belonging to the component and all the couplings with the component. In fact, in some cases it may
not be necessary to remove anything from the PARAM.in file. You may simply add an #END command
after the section belonging to the last included component, since the lines following the #END command
are ignored. For example to run with the SC and IH components only, you can put an #END command
after the #END COMP IH command but before the coupling with the SP component:
#END_COMP IH --------------------------------------#END
#COUPLE1
SC
SP
-1
60.0
...
NameSource
NameTarget
DnCouple
DtCouple
Test the parameters and the layout as usual
cd ..
4.7. EXAMPLE 6: TIME ACCURATE RUN WITH ALL EIGHT COMPONENTS
and run the code
cd run
mpirun -np 32 SWMF.exe | tee runlog.8comp
After the run finishes, postprocess the plot files
cd SC
pIDL
pTEC p r
cd ../IH
pIDL
pTEC p r
cd ..
cd ../GM
pIDL
pTEC p r
cd ../IE
pION
cd ..
Since this example run is very short, no restart files are saved (see the #SAVERESTART command).
49
50
Chapter 5
Complete List of Input Commands
The content of this chapter is generated from the Param/PARAM.XML file of the CON module and the
PARAM.XML files in the component version directories (e.g. UA/GITM2/PARAM.XML). These XML files
can be read with an editor and they can be used for creating PARAM.in files by copying small parts from
them.
The XML files have been written by several developers at the Center of Space Environment Modeling.
The transformation of the XML format into LaTex is done with the share/Scripts/XmlToTex.pl script. This
script generates index terms for all commands, which are used to create an alphabetical index at the end of
this chapter.
5.1
Input Commands for the 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).
51
52
5.1.1
CHAPTER 5. COMPLETE LIST OF INPUT COMMANDS
General commands
#INCLUDE command
#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.
#END command
#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.
#STRICT command
#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. The default is strict mode.
#DESCRIPTION command
#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.
5.1.2
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.
#RUN command
#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.
5.1. INPUT COMMANDS FOR THE CONTROL MODULE
53
#TIMEACCURATE command
#TIMEACCURATE
F
DoTimeAccurate
If DoTimeAccurate is set to true, the SWMF is solving a time dependent problem. If DoTimeAccurate 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. It is also envisioned that in steady state mode the various components will be allowed to
use different number of iterations per global iteration, thus they can converge to steady state at the same
rate and an optimal global convergence can be achieved.
The default value is the time accurate mode.
#STARTTIME command
#STARTTIME
2000
3
21
10
45
0
0.0
iYear
iMonth
iDay
iHour
iMinute
iSecond
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.
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.
#ENDTIME command
#ENDTIME
2000
3
22
10
45
0
0.0
iYear
iMonth
iDay
iHour
iMinute
iSecond
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 tSimulation
is set to zero.
There is no default value.
54
#TIMESIMULATION command
#TIMESIMULATION
3600.0
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. The default value
is tSimulation=0.
#NSTEP command
#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. The default value is nStep=0.
#STOP command
#STOP
100
10.0
MaxIteration
tSimulationMax [sec]
The MaxIteration variable contains the maximum number of iterations 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. The
default values are MaxIteration=0 and tSimulationMax = 0.0, so the #STOP command must be used in
every session.
#CHECKSTOP command
#CHECKSTOP
T
-1
10.0
DoCheckStop
DnCheckStop
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.
55
#CHECKSTOPFILE command
#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.).
#CPUTIMEMAX command
#CPUTIMEMAX
3600.0
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.
5.1.3
Testing and timing
#TEST command
#TEST
CON_session::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.
#TESTPROC command
#TESTPROC
1
iProcTest
The test information will be written from iProcTest when DoTestMe is used in the SWMF. Default value is
0.
#TESTTIME command
#TESTTIME
10
5.0
nIterStartTest
tStartTest
The test information will be written if the number of iterations exceed nIterStartTest or time exceeds
tStarTest (in time accurate mode). Default value is -1 for both.
56
#VERBOSE command
#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.
#TIMING command
#TIMING
T
-2
-1
tree all
UseTiming
DnTiming
nDepthTiming
TypeTimingReport
rest of parameters read if true
-3 none, -2 final, -1 each session
-1 for arbitrary depth
’cumu’,’list’,’tree’, +optional ’all’
If UseTiming=.true., the execution is timed by the TIMING utility.
If UseTiming=.false., the execution is not timed.
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.
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.
The TypeTimingReport parameter determines the format of the timing reports:
’cumu’ - cumulative list sorted by timings
’list’ - list based on caller and sorted by timings
’tree’ - tree based on calling sequence.
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’.
#PROGRESS command
#PROGRESS
10
100
DnProgressShort
DnProgressLong
57
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.
#PRECISION command
#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.
#VERSION command
#VERSION
1.0
Version
The Version 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.
5.1.4
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.
#COMPONENT command
#COMPONENT
IE
F
NameComp
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 registered in the LAYOUT.in file are used.
#CYCLE command
#CYCLE
IH
10
NameComp
DnRun
58
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.
5.1.5
Coupling control
#COUPLEORDER command
#COUPLEORDER
25
LC SC
SC LC
SC IH
IH SC
SC SP
IH SP
IH GM
GM IE
GM IM
GM PW
GM RB
UA IE
UA LA
LA UA
IM GM
IM IE
PW GM
IE GM
IE IM
IE PW
IE PS
IE RB
IE UA
IH OH
OH IH
nCouple
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
NameSourceTarget
The nCouple variable determines the maximum number of couplings among the components. The NameSourceTarget string contains the two-character ID for the source and target components separated by spaces.
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 gets
information from GM.
With respect 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 info 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 shown above 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 second strategy leads to parallel 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
59
#INCLUDE
Param/CoupleOrderFast
command into the PARAM.in file. The Param/CoupleOrderFast contains the coupling order that allows
parallel 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 shown above.
#COUPLE1 command
#COUPLE1
IE
IM
-1
10.0
NameSource
NameTarget
DnCouple
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.
#COUPLE2 command
#COUPLE2
GM
IE
-1
10.0
NameComp1
NameComp2
DnCouple
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.
#COUPLE1SHIFT command
#COUPLE1SHIFT
IH
GM
-1
10.0
-1
3.0
NameSource
NameTarget
DnCouple
DtCouple
nNext12
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
60
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.
#COUPLE2SHIFT command
#COUPLE2SHIFT
GM
IE
-1
10.0
-1
3.0
-1
6.0
NameComp1
NameComp2
DnCouple
DtCouple
nNext12
tNext12
nNext21
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.
#COUPLE1TIGHT command
#COUPLE1TIGHT
GM
PT
T
NameMaster
NameSlave
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.
61
#COUPLE2TIGHT command
#COUPLE2TIGHT
GM
PC
T
NameMaster
NameSlave
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.
#COUPLETIME command
#COUPLETIME
GM
F
NameComp
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.
5.1.6
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.
#SAVERESTART command
#SAVERESTART
T
1000
-1.
DoSaveRestart (Rest of parameters read if true)
DnSaveRestart
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.
#RESTARTFILE command
#RESTARTFILE
RESTART_test.in
62
The NameRestartFile variable contains the file name for the restart file for CON itself. This file contains
information such as initial time, simulation time and time step, version number, description of the simulation,
name of the planet, etc. The file is in the same format as PARAM.in, so it can be simply included with the
#INCLUDE command. To avoid unpleasant surprises, do not include the file which is being written.
The default value for NameRestartFile is ”RESTART.out”.
5.1.7
Output control
#ECHO command
#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 .false., but it is a good idea to set it to true at the beginning of the
PARAM.in file.
#FLUSH command
#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.
#STDOUT command
#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.
63
#STDOUTDIR command
#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”.
5.1.8
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.
#ROTATEHGR command
#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.
#ROTATEHGI command
#ROTATEHGI
-1.0
dLongitudeHgi [deg]
Rotate the HGI and the related rotating HGC systems 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 HGI system is used.
5.1.9
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!
#PLANET command
#PLANET
New
6300000.0
5.976E+24
0.000000199
23.5
NamePlanet (rest of parameters read for unknown planet)
RadiusPlanet [m]
MassPlanet
[kg]
OmegaPlanet [radian/s]
TiltRotation [degree]
64
DIPOLE
11.0
289.1
-31100.0E-9
TypeBField
MagAxisThetaGeo [degree]
MagAxisPhiGeo
[degree]
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.
#ROTATIONAXIS command
#ROTATIONAXIS
T
23.5
198.3
IsRotAxisPrimary (rest of parameters read if true)
RotAxisTheta
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.
#ROTATION command
#ROTATION
T
24.06575
UseRotation
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.
#MAGNETICAXIS command
#MAGNETICAXIS
T
34.5
0.0
IsMagAxisPrimary (rest of parameters read if true)
MagAxisTheta [degree]
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
The default is to use the true magnetic axis determined by the date and time given by #STARTTIME.
65
#MAGNETICCENTER command
#MAGNETICCENTER
0.1
-0.02
0.0
MagCenterX
MagCenterY
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).
#DIPOLE command
#DIPOLE
-3.11e-4
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.
#UPDATEB0 command
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.
#IDEALAXES command
#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
#ROTATIONAXIS
T
0.0
0.0
IsRotAxisPrimary
RotAxisTheta
RotAxisPhi
#MAGNETICAXIS
F
IsMagAxisPrimary
but much shorter.
5.1.10
Stub components
If SWMF is compiled with the interface in srcCON/Stubs, the stub components recognize only one command
#TIMESTEP.
66
#TIMESTEP command
#TIMESTEP
0.01
0.12
DtRun (the typical time step of the component)
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.
5.2. INPUT COMMANDS FOR THE BATSRUS: GM, EE, SC, IH AND OH
COMPONENTS
5.2
67
Input Commands for the BATSRUS: GM, EE, SC, IH and
OH Components
List of MH (GM, EE, SC, IH, and OH) commands used in the PARAM.in file
5.2.1
Stand alone mode
#COMPONENT command
#COMPONENT
GM
NameComp
This command can be used in the stand-alone mode to make BATSRUS behave as if it was the Global
Magnetosphere (GM), Eruptive Event (EE), Solar Corona (SC), Inner Heliosphere (IH) or Outer Heliosphere
(OH) component of the SWMF. The NameComp variable contains the two-character component ID of the
selected component. If NameComp is different from the default component value, then the default values
for all parameters (including the component dependent defaults, like coordinate system) are reset, therefore
it should occur as the first command if it is used to change the behavior of BATSRUS. The default behavior
is Global Magnetosphere (GM) for the stand-alone BATSRUS.
The command is also saved into the restart header files.
In the SWMF the BATSRUS codes are configured to the appropriate components, so the default components should not be changed by this command.
#DESCRIPTION command
#DESCRIPTION
This is a test run for Jupiter with no rotation.
This command is only used in the stand alone mode.
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.
#ECHO command
#ECHO
T
DoEcho
This command is only used in the stand alone mode.
If the DoEcho variable is true, the input parameters are echoed back. The default value for DoEcho is
.false., but it is a good idea to set it to true at the beginning of the PARAM.in file.
#PROGRESS command
#PROGRESS
10
100
DnProgressShort
DnProgressLong
The frequency of short and long progress reports for BATSRUS in stand alone mode. These are the defaults.
Set -1-s for no progress reports.
68
#TIMEACCURATE
F
DoTimeAccurate
This command is only used in stand alone mode.
If DoTimeAccurate is set to true, BATSRUS solves a time dependent problem. If DoTimeAccurate 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 saving plot files, log files and 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.
In steady-state mode BATSRUS uses different time steps in different grid cells (limited only by the local
stability conditions) to accelerate the convergence towards steady state.
The default is time accurate mode.
#LOCALTIMESTEP command
#LOCALTIMESTEP
T
UseLocalTimeStep
This command controls how the time stepping works in time accurate mode.
If UseLocalTimeStep is true, the time step in each grid block will depend on the AMR level in explicit
time accurate mode. This algorithm is sometimes called ”subcycling” because the blocks at a finer AMR
level will do several small time steps during a single global time step. This should not be confused with the
”steady state” mode (see the TIMEACCURATE command) where each grid cell takes different time steps
and the result is only valid if a steady state is reached.
For Cartesian grids the time step will be proportional to the physical cell size, which is optimal if the
wave speeds are roughly constant in the whole domain. Note that the stability conditions will hold in every
grid block.
This is a fairly new algorithm that requires more testing. Currently the algorithm is always second order
accurate in time. A conservative flux correction is applied at the resolution changes. On the other hand, the
normal velocity, normal magnetic/electric field etc. used in some source terms are not ”corrected”, which is
different from the default uniform time step algorithm.
The default is using a uniform time step for the whole domain.
#BEGIN COMP command
This command is allowed in stand alone mode only for the sake of the test suite, which contains these
commands when the framework is tested.
#END COMP command
This command is allowed in stand alone mode only for the sake of the test suite, which contains these
commands when the framework is tested.
#RUN command
#RUN
The #RUN command does not have any parameters. It signals the end of the current session, and makes
BATSRUS 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 BATSRUS execute the last session.
COMPONENTS
69
#END command
#END
5.2.2
Planet parameters
The planet commands can only be used in stand alone mode. The commands allow to work with an arbitrary
planet. It is also possible to change some parameters of the planet relative to the real values.
By default Earth is assumed with its real parameters. Another planet (moon, comet) can be selected
with the #PLANET (#MOON, #COMET) command. The real planet parameters can be modified and
simplified with the other planet commands listed in this subsection. These modified commands cannot
precede the #PLANET command!
#PLANET command
#PLANET
NEW
6300000.0
5.976E+24
0.000000199
23.5
DIPOLE
11.0
289.1
-31100.0E-9
NamePlanet (rest of parameters read for unknown planet)
RadiusPlanet [m]
MassPlanet
[kg]
OmegaPlanet [radian/s]
TiltRotation [degree]
TypeBField
MagAxisThetaGeo [degree]
MagAxisPhiGeo
[degree]
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, and
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. If TypeBField
is set to ”DIPOLE” then 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”. Although many other planets and some of the moons are
recognized, some of the parameters, like the equinox time are not yet properly set.
#ROTATIONAXIS command
#ROTATIONAXIS
T
23.5
198.3
IsRotAxisPrimary (rest of parameters read if true)
RotAxisTheta
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
The default is to use the true rotational axis determined by the date and time given by #STARTTIME.
70
#ROTATION command
#ROTATION
T
24.06575
UseRotation
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.
#MAGNETICAXIS command
#MAGNETICAXIS
T
34.5
0.0
IsMagAxisPrimary (rest of parameters read if true)
MagAxisTheta [degree]
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
The default is to use the true magnetic axis determined by the date and time given by #STARTTIME.
#MAGNETICCENTER command
#MAGNETICCENTER
0.1
-0.02
0.0
MagCenterX
MagCenterY
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).
#DIPOLE command
#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.
#UPDATEB0 command
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.
COMPONENTS
71
#IDEALAXES command
#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 the commands:
#ROTATIONAXIS
T
0.0
0.0
IsRotAxisPrimary
RotAxisTheta
RotAxisPhi
#MAGNETICAXIS
F
IsMagAxisPrimary
but much shorter.
5.2.3
User defined input
#USERFLAGS command
#USERFLAGS
F
F
F
F
F
F
F
F
F
F
F
F
F
UseUserInnerBcs
UseUserSource
UseUserPerturbation
UseUserOuterBcs
UseUserICs
UseUserSpecifyRefinement
UseUserLogFiles
UseUserWritePlot
UseUserAMR
UseUserEchoInput
UseUserB0
UseUserInitSession
UseUserUpdateStates
This command controls the use of user defined routines in ModUser.f90. For each flag that is set, an
associated routine will be called in the user module. Default is .false. for all flags.
#USERINPUTBEGIN command
#USERINPUTBEGIN
This command signals the beginning of the section of the file which is read by the subroutine user read inputs
in the ModUser.f90 file. The section ends with the #USERINPUTEND command. There is no XML based
parameter checking in the user section.
#USERINPUTEND command
#USERINPUTEND
This command signals the end of the section of the file which is read by the subroutine user read inputs
in the ModUser.f90 file. The section begins with the #USERINPUTBEGIN command. There is no XML
based parameter checking in the user section.
72
5.2.4
Testing and timing
#TEST command
#TEST
read_inputs
A space separated list of subroutine names. Default is empty string.
Examples:
read inputs - echo the input parameters following the #TEST line
project B - info on projection scheme
implicit - info on implicit scheme
krylov - info on the Krylov solver
message count- count messages
initial refinement
...
Check the subroutines for call setoktest(”...”,oktest,oktest me) to see the appropriate strings.
#TESTIJK command
#TESTIJK
1
1
1
1
0
iTest
jTest
kTest
iBlockTest
iProcTest
(cell index for testing)
(block index for testing)
(processor index for testing)
The location of test info in terms of indices, block and processor number. Note that the user should set
#TESTIJK or #TESTXYZ, not both. If both are set, the final one in the session will set the test point.
#TESTXYZ command
#TESTXYZ
1.5
-10.5
-10.
xTest
yTest
zTest
(X coordinate of cell for testing)
(Y coordinate of cell for testing)
(Z coordinate of cell for testing)
The location of test info in terms of coordinates. Note that the user should set #TESTIJK or #TESTXYZ,
not both. If both are set, the final one in the session will set the test point.
#TESTTIME command
#TESTTIME
-1
10.5
nIterTest
TimeTest
(iteration number to start testing)
(time to start testing in seconds)
The time step and physical time to start testing.
#TESTVAR command
#TESTVAR
1
iVarTest
Index of variable to be tested. Default is rho =”1”, i.e. density.
COMPONENTS
73
#TESTDIM command
#TESTDIM
1
iDimTest
Index of dimension/direction to be tested. Default is X dimension.
#STRICT command
#STRICT
T
UseStrict
If true then stop when parameters are incompatible. If false, try to correct parameters and continue. Default
is true, i.e. strict mode
#VERBOSE command
#VERBOSE
-1
lVerbose
Verbosity level controls the amount of output to STDOUT. Default level is 1.
lVerbose ≤ −1 only warnings and error messages are shown.
lVerbose ≥ 0 start and end of sessions is shown.
lVerbose ≤ 1 a lot of extra information is given.
lVerbose ≤ 10 all calls of set oktest are shown for the test processor.
lVerbose ≤ 100 all calls of set oktest are shown for all processors.
#DEBUG command
#DEBUG
F
F
DoDebug
DoDebugGhost
(use it as if(okdebug.and.oktest)...)
(parameter for show_BLK in library.f90)
Excessive debug output can be controlled by the global okdebug parameter
#CODEVERSION command
#CODEVERSION
7.50
CodeVersion
Checks CodeVersion. Prints a WARNING if it differs from the CodeVersion defined in ModMain.f90.
#USERMODULE command
#USERMODULE
TEST PROBLEM Smith
1.3
VersionUserModule
Checks the selected user module. If the name or the version number differs from that of the compiled user
module, a warning is written, and the code stops in strict mode (see #STRICT command). This command
and its parameters are written into the restart header file too, so the user module is checked when a restart
is done. There are no default values. If the command is not present, the user module is not checked.
74
#EQUATION command
#EQUATION
MHD
8
NameEquation
nVar
Define the equation name and the number of variables. If any of these do not agree with the values determined
by the code, BATSRUS stops with an error. Used in restart header files and can be given in PARAM.in as
a check and as a description.
#PRECISION command
#PRECISION
8
nByteReal
Define the number of bytes in a real number. If it does not agree with the value determined by the code,
BATSRUS stops with an error unless the strict mode is switched off. This is used in restart header files to
store (and check) the precision of the restart files. It is now possible to read restart files with a precision
that differs from the precision the code is compiled with, but strict mode has to be switched off with the
#STRICT command. The #PRECISION command may also be used to enforce a certain precision.
#CHECKGRIDSIZE command
#CHECKGRIDSIZE
4
4
4
576
nI
nJ
nK
MinBlockALL
Checks block size and number of blocks. Stops with an error message, if nI, nJ, or nK differ from those set in
ModSize. Also stops if number of blocks exceeds nBLK*numprocs, where nBLK is defined in ModSize and
numprocs is the number of processors. This command is used in the restart headerfile to check consistency,
and it is also useful to check if the executable is consistent with the requirements of the problem described
in the PARAM.in file.
#BLOCKLEVELSRELOADED command
#BLOCKLEVELSRELOADED
This command means that the restart file contains the information about the minimum and maximum
allowed refinement levels for each block. This command is only used in the restart header file.
#TIMING command
#TIMING
T
-2
-1
cumu
UseTiming
(rest of parameters read if true)
DnTiming
(-3 none, -2 final, -1 each session)
nDepthTiming
(-1 for arbitrary depth)
TypeTimingReport (’cumu’, ’list’, or ’tree’)
This command can only be used in stand alone mode. In the SWMF the #TIMING command should be
issued for CON.
If UseTiming=.true., the TIMING module must be on. If UseTiming=.false., the execution is not timed.
COMPONENTS
75
Dntiming determines the frequency of timing reports. If DnTiming .ge. 1, a timing report is produced
every dn timing step. If DnTiming .eq. -1, a timing report is shown at the end of each session. If DnTiming
.eq. -2, a timing report is shown at the end of the whole run. If DnTiming .eq. -3, no timing report is shown.
nDepthTiming determines the depth of the timing tree. A negative number means unlimited depth. If
TimingDepth is 1, only the full BATSRUS execution is timed.
TypeTimingReport determines the format of the timing reports: ’cumu’ - cumulative list sorted by
timings ’list’ - list based on caller and sorted by timings ’tree’ - tree based on calling sequence
The default values are shown above.
5.2.5
Initial and boundary conditions
#NORMALIZATION command
#NORMALIZATION
READ
1000.0
1000.0
1.0e-6
TypeNormalization
No2SiUnitX
(only read if TypeNormalization=READ)
No2SiUnitU
(only read if TypeNormalization=READ)
No2SiUnitRho (only read if TypeNormalization=READ)
This command determines what units are used internally in BATSRUS. The units are normalized so that
several physical constants become unity (e.g. the permeability of vacuum), so the equations are simpler in
the code. The normalization also helps to keep the various quantities within reasonable ranges. For example
density of space plasma is very small in SI units, so it is better to use some normalization, like amu/cm3 .
Also note that distances and positions (like grid size, grid resolution, plotting resolution, radius of the inner
body etc) are always read in normalized units from the PARAM.in file. Other quantities are read in I/O
units (see the #IOUNITS command).
The normalization of the distance, velocity and density are determined by the TypeNormalization parameter. The normalization of all other quantities are derived from these three values. It is important to
note that the normalization of number density (defined as the density normalization divided by the proton
mass) is usually not consistent with the inverse cube of the normalization of distance.
Possible values for TypeNormalization are NONE, PLANETARY, SOLARWIND, USER and READ.
If TypeNormalization=”NONE” then the distance, velocity and density units are the SI units, i.e. meter,
meter/sec, and kg/m3 . Note that the magnetic field and the temperature are still normalized differently
√
from SI units so that the Alfven speed is B/ ρ and the ion temperature is simply p/(ρ/AverageIonM ass),
where the AverageIonMass is given relative to the mass of proton.
If TypeNormalization=”PLANETARY” then the distance unit is the radius of the central body (moon,
planet, or the Sun). If there is no central body, the length normalization is 1km. The velocity unit is km/s,
and the density unit is amu/cm3.
If TypeNormalization=”SOLARWIND” then the distance unit is the same as for PLANETARY units,
but the velocity and density are normalized to the density and the sound speed of the solar wind. This
normalization is very impractical, because it depends on the solar wind values that are variable, and may
not even make sense (e.g. for a shock tube test or a Tokamak problem). This normalization is only kept for
sake of backwards compatibility.
If TypeNormalization=”USER” the normalization is set in the user module. This may be useful if the
normalization depends on some input parameters.
Finally TypeNormalization=”READ” reads the three basic normalization units from the PARAM.in file
as shown in the example. This allows arbitrary normalization.
The restart header file saves the normalization with TypeNormalization=”READ” and the actual values
of the distance, velocity and density normalization factors. This avoids the problem of continuing the run with
inconsistent normalization (e.g. if the SOLARWIND normalization is used and the solar wind parameters
have been changed). It also allows other programs to read the data saved in the restart files and convert
them to appropriate units.
76
The default normalization is PLANETARY for GM and SOLARWIND for all other components.
#IOUNITS command
#IOUNITS
PLANETARY
TypeIoUnit
This command determines the physical units of various parameters read from the PARAM.in file and written
out into log files and plot files (if they are dimensional. The units are determined by the TypeIoUnit string.
Note that distances and positions are always read in normalized units from PARAM.in but they are written
out in I/O units. In most cases the two coincides.
Also note that the I/O units are NOT necessarily physically consistent units. For example one cannot
divide distance with time and compare it with the velocity because they may be in inconsistent units. One
needs to convert into some consistent units before the various quantities can be combined.
If TypeIoUnits=”SI” the input and output values are taken in SI units (m, s, kg, etc).
The PLANETARY units use the radius of the planet for distance, seconds for time, amu/cm3 for mass
density, cm− 3 for number denisty, km/s for speed, nPa for pressure, nT for magnetic field, micro Amper/m2
for current density, mV/m for electric field, nT/planet radius for div B, and degrees for angles. For any
other quantity SI units are used. If there is no planet (see the #PLANET command) then the distance unit
is 1 km.
The HELIOSPHERIC units use the solar radius for distance, seconds for time, km/s for velocity, degrees
for angle, and CGS units for mass density, number density, pressure, magnetic field, momentum, energy
density, current, and div B.
When TypeIoUnit=”NONE” the input and output units are the same as the normalized units (see the
#NORMALIZATION command).
Finally when TypeIoUnit=”USER”, the user can modify the I/O units (Io2Si V) and the names of the
units (NameTecUnit V and NameIdlUnit V) in the subroutine user io units of the user module. Initially the
values are set to SI units.
The #IOUNITS command and the value of TypeIoUnits is saved into the restart header file so that one
continues with the same I/O units after restart.
The default is ”PLANETARY” unit if BATSRUS is used as the GM component and ”HELIOSPHERIC”
otherwise (EE, SC, IH or OH).
#RESTARTINDIR command
#RESTARTINDIR
GM/restart_n5000
NameRestartInDir
The NameRestartInDir variable contains the name of the directory where restart files are saved relative to
the run directory. The directory should be inside the subdirectory with the name of the component.
Default value is ”GM/restartIN”.
#RESTARTINFILE command
#RESTARTINFILE
one series
TypeRestartInFile
This command is saved in the restart header file which is included during restart, so normally the user does
not have to use this command at all. The TypeRestartInFile parameter describes how the restart data was
saved: into separate files for each processor (’proc’), into separate files for each grid block (’block’) or into
a single direct access file (’one’). The optional ’series’ string means that a series of restart files were saved
with the iteration number added to the beginning of the file names.
The default value is ’block’ for sake of backwards compatibility.
COMPONENTS
77
#NEWRESTART command
#NEWRESTART
T
DoRestartBFace
The RESTARTINDIR/restart.H file always contains the #NEWRESTART command. This command is
really used only in the restart headerfile. Generally it is not inserted in a PARAM.in file by the user.
The #NEWRESTART command sets the following global variables: DoRestart=.true. (read restart
files), DoRestartGhost=.false. (no ghost cells are saved into restart file) DoRestartReals=.true. (only real
numbers are saved in blk*.rst files).
The DoRestartBFace parameter tells if the face centered magnetic field is saved into the restart files.
These values are used by the Constrained Transport scheme.
#OUTERBOUNDARY command
#OUTERBOUNDARY
outflow
inflow
float
float
float
float
TypeBcEast
TypeBcWest
TypeBcSouth
TypeBcNorth
TypeBcBottom
TypeBcTop
Default depends on problem type.
Possible values:
coupled
fixed
fixedB1
float/outflow
heliofloat
linetied
raeder
reflect
periodic
vary/inflow
shear
arcadetop
arcadebot
arcadebotcont
user
-
GM coupled to the IH component (at the ’west’ boundary)
fixed solarwind values
fixed solarwind values without correction for the dipole B0
zero gradient
floating for the SC component (requires #FACEOUTERBC)
float P, rho, and B, reflect all components of U
Jimmy Raeder’s BC
reflective
periodic
time dependent BC (same as fixed for non time_accurate)
sheared (intended for shock tube problem only)
intended for arcade problem only
user defined
#OUTFLOWPRESSURE command
#OUTFLOWPRESSUURE
T
1e5
UseOutflowPressure
pOutflowSi (read if UseOutflowPressure is true)
Set pressure for ”outflow” boundary condition. This matters for subsonic outflow. Default is UseOutflowPressure=.false.
78
#INNERBOUNDARY command
#INNERBOUNDARY
ionosphere
ionosphere
TypeBcInner
TypeBcBody2
!read only if UseBody2=T
This command should appear after the #SECONDBODY command when using two bodies. Note: for the
second body COROTATION AND AN IONOSPHERIC BOUNDARY DO NOT WORK.
Default value for TypeBcBody2 is ’reflect’.
Possible values for TypeBcInner are:
’reflect’
- reflect Vr, reflect Vphi to rotation, float Vtheta,
reflect Br, float Bphi, float Btheta, float rho, float P
’float’
- float Vr, reflect Vphi to rotation, float Vtheta,
float B, float rho, float P
’fixed’
- Vr=0, Vphi=rotation, Vtheta=0
B=B0 (ie B1=0), fix rho, fix P
’ionosphere’
- set V as if ionosphere gave V_iono=0
float B, fix rho, float P
’ionospherefloat’ - set V as if ionosphere gave V_iono=0
float B, float rho, float P
’buffergrid’
- IH(OH) component obtains inner boundary from the SC(IH)
component, through a buffer grid. The buffer grid is set
by the #BUFFERGRID or #HELIOBUFFERGRID commands.
’polarwind’
- GM component obtains the inner boundary from PW component
’ionosphereoutflow’ - empirical inner boundary setup in (Hp,Op,All) multifluid
’user’
- user defined
For ’ionosphere’ and ’ionospherefloat’ types and a coupled GM-IE run, the velocity at the inner boundary is
determined by the ionosphere model.
The boundary condition on Br can be changed with the #MAGNETICINNERBOUNDARY command.
Default value for TypeBcInner is ’ionosphere’ for the GM component, and ’unknown’ for the EE, SC, IH
and OH components, so the inner boundary must be set for these components.
#MAGNETICINNERBOUNDARY command
#MAGNETICINNERBOUNDARY
T
DoReflectInnerB1
If DoReflectInnerB1 is true, the B1 part of the magnetic field is reflected for the ionosphere type inner
boundary conditions, i.e. the radial component of the total magnetic field is forced to coincide with the B0
value.
The default value is DoReflectInnerB1 false, which makes B1 float.
#BUFFERGRID command
#BUFFERGRID
2
nRBuff
90
nPhiBuff
45
nThetaBuff
19.0
rBuffMin
21
rBuffMax
0.0
PhiBuffMin
COMPONENTS
360.0
-90.0
90.0
79
PhiBuffMax
LatBuffMin
LatBuffMax
Define the radius, angular extent and the grid resolution of the uniform spherical buffer grid used to pass
information between two coupled components running BATSRUS.
The parameters nRBuff, nPhiBuff and nThetaBuff determine the number of points in the radial, azimuthal and latitudinal directions, respectively.
The parameters rBuffMin and rBuffMax determine the inner and outer radii of the spherical shell.
PhiBuffMin, PhiBuffMax, LatBuffMin and LatBuffMax determine the limits (in degrees) of the buffer
grid in the azimuthal and latitudinal directions.
When used to pass information from the SC(IH) component to the IH(OH) component, the entire shperical shell should be used (alternativly, use the #HELIOBUFFERGRID command), but in certain application
only a part of the shell may be needed. The buffer should be placed in a region where the two components
overlap, and the grid resolution should be similar to the grid resolution of the coarser of the two component
grids. This command can only be used in the first session by the IH(OH) component. The buffer grid will
only be used if ’buffergrid’ is chosen for TypeBcInner in the #INNERBOUNDARY command of the target
component. Default values are shown above.
#EXTRABOUNDARY command
#EXTRABOUNDARY
T
UseExtraBoundary
user
TypeExtraBoundary
If UseExtraBoundary is true, the user can define an extra boundary condition in the user files. The TypeExtraBoundary parameter can be used to select from multiple boundary conditions implemented in the user
module.
#FACEBOUNDARY command
#FACEBOUNDARY
6
-2
MinFaceBoundary
MaxFaceBoundary
General notes: face based boundary conditions are 1st order accurate in general, while cell based boundary
conditions can be 2nd order accurate. Sometimes, however, it is easier to define a face value than the state
of the ghost cells that are outside the computational domain. Depending on the shape of the boundary it
can also happen that the same ghost cell is used by multiple physical cells and this may be a problem. In
our current implementation cell based boundaries can be used only when the physical boundary coincides
with the boundary of the grid blocks.
Face based boundaries are allowed even when the physical boundary cuts through the grid blocks. In this
case each cell center is marked as either physical or boundary cell, and the boundary conditions are applied
at cell faces between a physical and a boundary cell center.
For Cartesian coordinates the inner (body2=-2 and body1=-1) and extra (0) boundaries have to be face
based because these are not aligned with the block boundaries. The outer boundaries (east=1 to top=6) are
cell based by default, but they can also be face based if desired.
For spherical and cylindircal grids the default is face based boundaries everywhere. The outer boundaries
have to be face based if a brick-shaped computational domain is cut out from the sphere/cylinder (see the
#LIMITRADIUS and #GRID commands) because the boundary is not aligned with the block boundaries.
If the computational domain is the full sphere/cylinder, then cell based boundaries can be used (by applying
this command). For spherical grids the ’inner boundary’ is simply at the minimum radius that normally
coincides with the body radius, therefore it can be cell or face based.
80
This command allows setting the first and the last boundaries that are handled as faces. It also allows
switching off the face boundary conditions for generalized coordinate grids (as shown by the example).
#POLARBOUNDARY command
#POLARBOUNDARY
20.0
100000.0
1.0
2.0
20000.0
1.5
75.0
PolarNDim [amu/cc] for
PolarTDim [K]
for
PolarUDim [km/s]
for
PolarTDim [K]
for
PolarUDim [km/s]
for
PolarLatitude [deg]
fluid
fluid
fluid
fluid
fluid
fluid
1
1
1
2
2
2
This command defines the boundary conditions in the polar region. The number density, temperature and
velocity can be given (for all fluids in multifluid calculations). This mimics polar wind like inner boundary
conditions when GM is not coupled with the PW component. The PolarLatitude parameter determines the
latitudinal extent of the polar boundary where the outflow is defined.
#CPCPBOUNDARY command
#CPCPBOUNDARY
T
28.0
0.1
UseCpcpBc (rest is read if true)
Rho0Cpcp
[amu/cc]
RhoPerCpcp [amu/cc / kV]
This command only works for single fluid MHD. The inner boundary type has to be ”ionosphere” and the
GM and IE components have to be coupled together.
If UseCpcpBc is true, the density at the inner boundary will depend on the cross polar cap potential
(CPCP) in a linear fashion:
RhoBc = Rho0Cpcp + RhoPerCpcp * Cpcp
where RhoBc and Rho0Cpcp are in I/O units (typically amu/cc), the Cpcp is given in [kV], and the
RhoPerCpcp factor is in density units per kV. The Cpcp is the average of the northern and southern
CPCPs. The example shows some reasonable values. For CPCP = 0 kV RhoBc = 28 amu/cc, while for
CPCP = 400 kV RhoBc = 68 amu/cc.
By default the density at the inner boundary is determined by the body density given in the #BODY
(same as #MAGNETOSPHERE) command.
#IMCOUPLINGSMOOTH command
#IMCOUPLINGSMOOTH
10.0
dLatSmoothIm [deg]
Smooth out the pressure nudging at the edge of the RCM boundary. Default is -1.0, which means no
smoothing.
5.2.6
Grid geometry
#GRID command
#GRID
2
1
nRootBlock1
nRootBlock2
COMPONENTS
1
-224.
32.
-64.
64.
-64.
64.
81
nRootBlock3
xMin
xMax
yMin
yMax
zMin
zMax
The nRootBlock1, nRootBlock2 and nRootBlock3 parameters define the number of blocks of the base grid,
i.e. the roots of the octree. By varying these parameters, one can setup a grid which is elongated in
some direction. The xMin, ..., zMax parameters define a brick shaped computational domain. An inner
boundary may be cut out from the domain with the #BODY and/or #LIMITRADIUS commands. It is
also possible to define a shperical, cylindrical computational domain using the #GRIDGEOMETRY and the
#LIMITRADIUS commands.
There are no default values, the grid size must always be given in the first session (even if the component
is switched off in the first session!).
#GRIDSYMMETRY command
#GRIDSYMMETRY
F
T
T
IsMirrorX
IsMirrorY
IsMirrorZ
For symmetric test problems one can model only a part of the computational domain. Providing the symmetry directions with this command allows the proper calculation of line-of-sight plots.
#COORDSYSTEM command
#COORDSYSTEM
GSM
TypeCoordSystem
TypeCoordSystem defines the coordinate system for the component. The coordinate systems are defined in
share/Library/src/CON axes. Here we provide general suggestions.
For GM (Global Magnetopshere) the default coordinate system is ”GSM” with the X axis pointing towards
the Sun, and the (moving) magnetic axis contained in the X-Z plane. The inertial forces are neglected. The
essentially inertial ”GSE” system is also available, but it is not fully tested.
For SC (Solar Corona) one should always use the corotating HGR system to get an accurate solution
even for complicated active regions. Using an inertial frame would result in huge numerical errors near the
Sun.
For time accurate IH solutions (e.g. CME propagation) one should use the inertial HGI system so the grid
can be refined along the Sun-Earth line. To obtain a steady state initial condition, the corotating HGC system
can be used which is aligned with the HGI system for the initial time of the simuation (see #STARTTIME
command). When the run is switched to time accurate mode, the coordinate system should be switched
to HGI. The necessary transformation of the velocity (adding the corotating velocity) is automatically
performed.
For quiet steady state IH solutions the HGR system can be used. Note however that the corotating
systems may not work well if the IH domain is extended way beyond 1AU, becasue the boundary condition
can become inflow type at the corners of a Cartesian domain. In this case the inertial HGI system should
be used in time accurate mode even for obtaining the initial state.
For OH one should always use the inertial HGI system. A rotating frame would have extremeley fast
rotational speeds.
82
Note that the HGR and HGI systems can be rotated with a fixed angle using the #ROTATEHGR and
#ROTATEHGI commands of the SWMF. This can be used to align the interesting plane of the simulation
with the grid.
The default is component dependent: ”GSM” for GM, ”HGR” for SC, and ”HGI” for IH and OH.
#GRIDGEOMETRY command
#GRIDGEOMETRY
spherical_lnr
TypeGeometry
This command determines the geometry of the grid. Possible values are Cartesian, rotated Cartesian, RZ
geometry, cylindrical and spherical. The cylindrical and spherical grids can have logarithmic (cylindrical lnr
and spherical lnr) or arbitrarily stretched (spherical genr, cylindrical genr) radial coordinates.
The ”RZ” geometry is a 2D grid with axial symmetry. In our particular implementation the ”X” axis is
the axis of symmetry, and the ”Y” axis is used for the radial direction.
The spherical coordinates are ordered as r, longitude, latitude. The longitude is between 0 and 360
degrees, the latitude is between -90 and 90 degrees. The cylindrical coordinates are r, phi, z with phi
between 0 and 360 degrees.
The rotated Cartesian geometry can be used for debugging the generalized coordinate code. It allows
setting up a Cartesian test on a rotated generalized coordinate grid. The rotation is around the Z axis with
an angle alpha that has sin(alpha)=0.6 and cos(alpha)=0.8 for sake of getting nice rational numbers. The
PostIDL code unrotates the grid and the vector variables so it can be directly compared with a Cartesian
simulation. The initial conditions and the boundary conditions, however, are not rotated automatically
(yet), so they require some attention.
The default is Cartesian geometry.
#LIMITRADIUS command
#LIMITRADIUS
10.0
100.0
rMin
rMax
Note: for the #LIMITRADIUS command the linear radii can and should be given even if TypeGeometry is
’spherical lnr’ with a logarithmic radius (see command #GRIDGEOMETRY).
This command allows setting the mimimum and maximum values for the first generalized coordinate
(usually the radius). Setting rMin to a positive value excludes the origin of a spherical grid, or the axis of
the cylindrical grid.
The rMax parameter can be used to choose a spherical or cylinrical domain instead of the brick defined
by the #GRID. To achieve this, rMax has to be set to a radius that fits inside the brick defined by #GRID.
By default the inner radius is set to the radius of the inner body (if it is present, see the #BODY
command) and the outer radius is set to the largest radial distance of the eight corners of the domain defined
by the #GRID command. If there is no inner body, the default inner radius is set to 0.0 for spherical and
cylindrical grids, and to 1.0 for logarithmic spherical grid.
#UNIFORMAXIS command
#UNIFORMAXIS
T
UseUniformAxis
This command can only be used in the first session. If UseUniformAxis is true, there can be no resolution
change AROUND the axis of a spherical or cylindrical grid. This is required by the supercell algorithm that
can be activated by the #FIXAXIS command. Note that there can still be resolution changes ALONG the
axis.
COMPONENTS
83
If UseUniformAxis is false, the AMR can produce resolution changes around the axis of the grid. The
super-cell algorithm cannot be used. For restarted runs the false setting has to be repeated in the PARAM.in
file used for the restart.
The default is UseUniformAxis=T.
#FIXAXIS command
#FIXAXIS
F
T
5.0
1.5
UsePoleDiffusion
DoFixAxis
rFixAxis
r2FixAxis
The computational cells become very small near the symmetry axis of a spherical or cylindrical grid. When
UsePoleDiffusion is true, some numerical diffusion applied between the cells on the opposite side of the axis.
This diffusion may smooth out some artifacts that show up when a discontinuity crosses the axis.
When DoFixAxis is true, the cells around the pole are merged into one ’supercell’ for the blocks that are
(partially) inside radius rFixAxis. For blocks within r2FixAxis, the radius of the supercell is 2 normal cells.
Merging the small cells allows larger time steps in time accurate runs: about a factor of 2 if only rFixAxis
is used, and around factor of 3 if r2FixAxis is also used.
Note that the super-cell algorithm requires that there is no resolution change around the axis in the phi
direction. See the #UNIFORMAXIS command for more discussion.
Default is false for both UsePoleDiffusion and DoFixAxis.
5.2.7
Initial time
#STARTTIME command
#STARTTIME
2000
3
21
10
45
0
iYear
iMonth
iDay
iHour
iMinute
iSecond
(GMT) or Universal Time (UT) in stand alone mode. In the SWMF this command checks start times against
the SWMF start time and warns if the difference exceeds 1 millisecond. This time is stored in the BATSRUS
restart header file.
The default values are shown above. This is a date and time when both the rotational and the magnetic
axes have approximately zero tilt towards the Sun.
#TIMESIMULATION
3600.0
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
header file, which provides human readable information about the restart state.
84
In SWMF the command is ignored (SWMF has its own #TIMESIMULATION command). In stand
alone mode time simulation is set, but in case of a restart, it gets overwritten by the binary value saved into
the .rst binary files.
The default value is tSimulation=0.
#NSTEP command
#NSTEP
100
nStep
Set nStep for the component. Typically used in the restart.H header file. Generally it is not inserted in a
PARAM.in file by the user.
The default is nStep=0 as the starting time step with no restart.
#NPREVIOUS command
#NPREVIOUS
100
1.5
nPrev
DtPrev
This command should only occur in the restart.H header file. If it is present, it indicates that the restart
file contains the state variables for the previous time step. nPrev is the time step number and DtPrev is
the length of the previous time step in seconds. The previous time step is needed for a second order in time
restart with the implicit scheme.
The default is that the command is not present and no previous time step is saved into the restart files.
5.2.8
Time integration
#TIMESTEPPING command
#TIMESTEPPING
1
0.4
nStage
CflExpl
#RUNGEKUTTA
2
0.8
nStage
CflExpl
#RK
4
1.3
nStage
CflExpl
These commands set the parameters for time integration. For explicit time integration nStage is the number
of stages. Setting nStage=1 selects a temporally first order forward Euler scheme. The nStage=2 corresponds
to a temporally second order scheme. The #TIMESTEPPING command uses half time step for the first
stage, and full time step for the second stage. The #RUNGEKUTTA or #RK commands select a TVD
Runge-Kutta scheme that employs full time step in both stages and then takes their average. The nStage=3
selects a 3rd order TVD Runge-Kutta scheme. The nStage=4 selects the classical 4th order Runge-Kutta
scheme. These temporally high order options are useful in combination with spatially higher order schemes
(to be implemented).
For implicit time stepping nStage=2 corresponds to the BDF2 (Backward Differene Formula 2) scheme
that uses the previous time step to make the scheme 2nd order accurate in time.
For explicit time stepping the CPU time is proportional to the number of stages. In time accurate runs
the 1-stage explicit time stepping scheme may work reasonably well with second order spatial discretization,
COMPONENTS
85
especially if the time step is limited to a very small value. Using a one stage scheme can speed up the code
by a factor of two with little compromise in accuracy.
For local time stepping (steady state mode) one should always use the 2-stage scheme with 2-nd order
spatial accuracy to avoid oscillations (or use the 1-stage scheme with CflExpl=0.4).
For implicit scheme the second order BDF2 scheme is more accurate but not more expensive than the
first order backward Euler scheme, so it is a good idea to use nStage=nOrder (or at least nStage=3 for high
order schemes).
To achieve consistency between the spatial and temporal orders of accuracy, the #SCHEME command
always sets nStage to be the same as nOrder except for 5th order scheme, which sets nStage=3. The
#TIMESTEPPING (or #RUNGEKUTTA or #RK) command can be used AFTER the #SCHEME command to overwrite nStage if required.
If the #SCHEME command is not used, then the defaults are nStage=2 with the half-step predictor and
CflExpl=0.8.
#FIXEDTIMESTEP command
#FIXEDTIMESTEP
T
10.
UseDtFixed
DtFixedDim [sec] (read if UseDtFixed is true)
Default is UseDtFixed=.false. Effective only if DoTimeAccurate is true. If UseDtFixed is true, the time
step is fixed to DtFixedDim.
This is useful for debugging explicit schemes.
The real application is, however, for implicit and partially implicit/local schemes. The time step is set
to DtFixedDim unless the update checking decides to reduce the time step for the sake of robustness.
#PARTSTEADY command
#PARTSTEADY
T
UsePartSteady
If UsePartSteady is true, the partially steady state algorithm is used. Only blocks which are changing or
next to changing blocks are evolved. This scheme can speed up the calculation if part of the domain is in
a numerical steady state. In steady state runs the code stops when a full steady state is achieved. The
conditions for checking the numerical steady state are set by the #PARTSTEADYCRITERIA command.
Default value is UsePartSteady = .false.
#PARTSTEADYCRITERIA command
#PARTSTEADYCRITERIA
5
MinCheckVar
8
MaxCheckVar
0.001
RelativeEps(bx)
0.0001
AbsoluteEps(bx)
0.001
RelativeEps(by)
0.0001
AbsoluteEps(by)
0.001
RelativeEps(bz)
0.0001
AbsoluteEps(bz)
0.001
RelativeEps(p)
0.0001
AbsoluteEps(p)
The part steady scheme only evolves blocks which are changing, or neighbors of changing blocks. The scheme
checks the neighbor blocks every time step if their state variable has changed significantly. This command
86
allows the user to select the variables to be checked, and to set the relative and absolute limits for each
variable. Only the state variables indexed from MinCheckVar to MaxCheckVar are checked. The change in
the block is significant if
max(abs(State - StateOld)) / (RelativeEps*abs(State) + AbsoluteEps)
exceeds 1.0 for any of the checked variables in any cells of the block. (including body cells but excluding
ghost cells). The RelativeEps variable determines the maximum ratio of the change and the norm of the old
state. The AbsoluteEps variable is only needed if the old state is very close to zero. It should be set to a
positive value which is much smaller than the typical significantly non-zero value of the variable.
Default values are such that all variables are checked with relative error 0.001 and absolute error 0.0001.
#POINTIMPLICIT command
#POINTIMPLICIT
T
0.5
T
T
UsePointImplicit
BetaPointImplicit (read if UsePointImplicit is true)
IsAsymmetric
DoNormalizeCell
Switches on or off the point implicit scheme. The BetaPointImplicit parameter (in the 0.5 to 1.0 range)
determines the order of accuracy for a 2-stage scheme. If BetaPointImplicit=0.5 the point implicit scheme is
second order accurate in time when used in a 2-stage scheme. Larger values may be more robust, but only
first order accurate in time. For a 1-stage scheme or for local timestepping the BetaPointImplicit parameter
is ignored and the coefficient is set to 1.
If the IsAsymmetric parameter is true, the numerical Jacobian is calculated with a one-sided (asymmetric)
difference formula. Otherwise a two-sided symmetric difference is used. The latter is slower somewhat but
more accurate.
If DoNormalizeCell is true, the normalization of variables (this is needed to make small perturbations for
the calculation of numerical derivatives) is done cell-by-cell. The default is false, so normalization is done
on a block-by-block basis.
For single-ion MHD the default is UsePointImplicit=.false. For multi-ion MHD the default values are
UsePointImplicit=.true., BetaPointImplicit=1.0 and IsAsymmetric=.true.
#IMPLICIT command
#IMPLICIT
F
F
T
100.0
UsePointImplicit
UsePartImplicit
UseFullImplicit
CflImpl (read if UsePartImplicit or UseFullImplicit is true)
If UsePointImplicit=T is set, the source terms defined in the user module are evaluated with a point implicit
scheme. See the #POINTIMPLICIT command for additional parameters (and another way of switching the
point implicit scheme on).
If UsePartImplicit=T is set, the code uses the explicit/implicit scheme. This means that some of the grid
blocks are advanced with explicit time stepping, while the rest is advance with implicit time stepping. See
the #FIXEDTIMESTEP and #IMPLICITCRITERIA command on how the explicit and implicit blocks get
selected.
If UseFullImplicit=T is set, the code uses a fully implicit time stepping scheme. This is usually more costly
than the explicit/implicit scheme unless the whole computational domain requires implicit time stepping.
Note 1: If UseFullImplicit is true, UsePartImplicit and UsePointImplicit must be false.
COMPONENTS
87
Note 2: UsePartImplicit=T and UsePointImplicit=T may be used together: source terms are point
implicit in the explicit blocks.
The ImplCFL parameter determines the CFL number used in the implicit blocks of the fully or partially
implicit schemes. This is ignored if UseDtFixed=T is set in the #FIXEDTIMESTEP command.
Default is false for all logicals.
#SEMIIMPLICIT command
#SEMIIMPLICIT
T
radiation
UseSemiImplicit
TypeSemiImplicit (read if UseSemiImplicit is true)
If UseSemiImplicit is true then most of the terms are evaluated explicitly, but some of them are evaluated
implicitly.
The TypeSemiImplicit parameter determines which terms and corresponding variables are done semiimplicitly. The ”radiation” option solves for the gray or multigroup diffusion energy density. For gray
diffusion the internal energy and pressure is calculated in a point implicit manner.
The ”radiationsplit” option solves each radiation group separately. The energy exchange term is calculated point-implicitly. The internal energy is updated in a conservative way.
The ”radcond” option solves implicitly the radiation diffusion and electron heat conduction together with
the radiation and internal energy densities being the unknowns. To use gray diffusion configure BATSRUS
with the default: Config.pl -nWave=1 To use the multi-group radiation select nWave larger than one.
The ”radcondsplit” option will solve each radiation group and the electrons separately...
The ”parcond” option solves for field aligned electron heat conduction only.
The ”cond” option solves for electron heat conduction only.
The ”resistivity” option solves for the magnetic field with dissipative and/or Hall Resistivity.
The default is UseSemiImplicit false.
5.2.9
Implicit parameters
#IMPLICITENERGY command
#IMPLICITENERGY
F
UseImplicitEnergy
If UseImplicitEnergy is true, use the energy variable(s) as unknown(s) in the implicit scheme, otherwise use
the pressure variables(s). Note that the explicit scheme that provides the right hand side of the implicit
scheme may still be conservative, and thus the overall scheme can provide correct jump conditions across
standing (or slowly moving) shocks. Away from shocks, using pressure as an implicit variable provides a
more accurate and robust scheme than using the energy variable.
The default is UseImplicitEnergy=T for sake of backwards compatibility.
#IMPLICITCRITERIA command
#IMPLICITCRITERIA
r
TypeImplCrit (dt or r or test)
10.0
rImplicit
(only read for TypeImplCrit = r)
Both #IMPLICITCRITERIA and #STEPPINGCRITERIA are acceptable. Only effective if PartImplicit
is true in a time accurate run. Default value is ImplCritType=’dt’.
The options are
88
if
(TypeImplCrit ==’dt’ ) then blocks with DtBLK .lt. DtFixed
elseif (TypeImplCrit ==’r’
) then blocks with rMinBLK .lt. rImplicit
elseif (TypeImplCrit ==’test’) then block iBlockTest on processor iProcTest
are handled with the implicit scheme. Here DtBlock is the time step allowed by the CFL condition for a
given block, while rMinBLK is the smallest radial distance for all the cells in the block.
The iBlockTest and iProcTest can be defined in the #TESTIJK command.
DtFixed must be defined in the #FIXEDTIMESTEP command.
#PARTIMPL command
#PARTIMPLICIT
T
UsePartImplicit2
If UsePartImplicit2 is set to true, the explicit scheme is executed in all blocks before the implicit scheme
is applied in the implicit blocks. This way the fluxes at the explicit/implicit interface are second order
accurate, and the overall part implicit scheme will be fully second order in time. When this switch is false,
the explicit/implicit interface fluxes are only first order accurate in time. A potential drawback of the second
order scheme is that the explicit scheme may crash in the implicit blocks. This could be avoided with a
more sophisticated implementation. There may also be a slight speed penalty, because the explicit scheme
is applied in more blocks.
The default is UsePartImplicit2 = false for now, which is safe and backward compatible.
#IMPLSTEP command
#IMPLSTEP
0.5
F
F
ImplCoeff
UseBdf2
UseSourceImpl
The ImplCoeff is the beta coefficient in front of the implicit terms for the two-level implicit scheme. The
UseBdf2 parameter decides if the 3 level BDF2 scheme is used or a 2 level scheme. UseSourceImpl true
means that the preconditioner should take point source terms into account.
For steady state run the default is the backward Euler scheme, which corresponds to ImplCoeff=1.0 and
UsedBdf2=F. For second order time accurate run the default is UseBdf2=T, since BDF2 is a 3 level second
order in time and stable implicit scheme. In both cases the default value for UseSourceImpl is false.
The default values can be overwritten with #IMPLSTEP, but only after the #TIMESTEPPING command! For example one could use the 2-level trapezoid scheme with ImplCoeff=0.5 and UseBDF2=F as
shown in the example above. The BDF2 scheme determines the coefficient for the implicit terms itself, but
ImplCoeff is still used in the first time step and after AMR-s, when the code switches back to the two-level
scheme for one time step.
#SEMICOEFF command
#SEMICOEFF
0.5
SemiImplCoeff
The SemiImplCoeff is the coefficient in front of the implicit part of the semi-implicit terms. The value should
be in the range 0.5 to 1. The 0.5 value will make the semi-implicit term 2nd order accurate in time, but
currently the operator splitting still renders the full scheme first order in time only. Using 1.0 is the most
robust option, as it makes the semi-implicit term to be evaluated fully implicitly, but it is first order accurate
in time only. The default value is 1.
COMPONENTS
89
#IMPLSCHEME command
#IMPLSCHEME
1
Rusanov
nOrderImpl
TypeFluxImpl
This command defines the scheme used in the implicit part (’left hand side’). The default order is first order.
The default scheme is the same as the scheme selected for the explicit part.
#IMPLCHECK command
#IMPLCHECK
0.3
0.5
0.6
0.95
0.8
1.05
RejectStepLevel
RejectStepFactor
ReduceStepLevel
ReduceStepFactor
IncreaseStepLevel
IncreaseStepFactor
The update checking of the implicit scheme can be tuned with this command. Update checking is done
unless it is switched off (see UPDATECHECK command). After each (partially) implicit time step, the
code computes pRhoRelMin, which is the minimum of the relative pressure and density drops over the whole
computational domain. The algorithm is the following:
If pRhoRelMin is less than RejectStepLevel, the step is rejected, and the time step is reduced by RejectStepFactor; else if pRhoRelMin is less than ReduceStepLevel, the step is accepted, but the next time step is
reduced by ReduceStepFactor; else if pRhoRelMin is greater than IncreaseStepFactor, the step is accepted
and the next time step is increased by IncreaseStepFactor, but it is never increased above the value given in
the FIXEDTIMESTEP command.
Assigning ReduceStepFactor=1.0 means that the time step is not reduced unless the step is rejected.
Assigning IncreaseStepFactor=1.0 means that the time step is never increased, only reduced.
Default values are shown.
#NEWTON command
#NEWTON
T
F
10
UseNewton (rest of parameters read if true)
UseConservativeImplicit
MaxIterNewton
If UseNewton is true a full non-linear Newton iteration is performed. If UseConservativeImplicit is true,
the Newton iteration is finished with a conservative fix (back substitution of the solution into the non-linear
implicit equations). MaxIterNewton is the maximum number of Newton iterations before giving up.
Default is UseNewton=F, i.e. we do a single ”Newton” iteration, which is the linearized implicit scheme.
In most cases that is the best choice.
#JACOBIAN command
#JACOBIAN
T
1.E-12
DoPrecond
JacobianEps
The Jacobian matrix is always calculated with a matrix free approach, however it can be preconditioned if
DoPrecond is set to true. JacobianEps contains the machine round off error for numerical derivatives. The
default value is 1.E-12 for 8 byte reals and 1.E-6 for 4 byte reals.
The default values are shown by the example.
90
#PRECONDITIONER command
#PRECONDITIONER
symmetric
TypePrecondSide (left, symmetric, right)
MBILU
TypePrecond (JACOBI, BLOCKJACOBI, GS, BILU, MBILU)
0.5
GustafssonPar (0 to 1, read for MBILU preconditioner only)
TypePrecondSide can be left, right or symmetric. There seems to be little difference between these in terms
of performance. Right preconditioning does not affect the normalization of the residual. The JACOBI and
BLOCKJACOBI preconditioners are implemented to always use left preconditioning.
The TypePrecond parameter can be set to JACOBI, GAUSS-SEIDEL, BLOCKJACOBI, BILU, MBILU.
The simplest Jacobi preconditioner is mainly useful for code development purposes. It uses the inverse
of the diagonal elements of the approximate Jacobian matrix. The block-Jacobi preconditioner uses the
invese of the diagonal blocks of the Jacobian matrix. It coincides with the Jacobi preconditioner for a scalar
equation. The Gauss-Seidel (GS) preconditioner gives better performance than Jacobi, however, the BILU
and MBILU preconditioners are usually more efficient. The Modified BILU (MBILU) preconditioner allows
a Gustafsson modification relative to BILU. In some cases the modification improves the preconditioner, but
sometimes it makes it worse.
The GustafssonPar parameter is only read for the MBILU preconditioner. If it is 0, the standard block
(BILU) preconditioning is done. This seems to be optimal for diffusion+relaxation type problems. Setting a
positive GustafssonPar up to 1 results in the modified (MBILU) preconditioner. The maximum 1 corresponds
to the full Gustafsson modification. The default 0.5 value seems to be optimal for matrices resulting from
hyperbolic (advection) type problems.
Default parameters are shown by the first example.
#SEMIPRECONDITIONER command
#SEMIPRECONDITIONER
T
DoPrecond (rest of parameters are read if true)
MBILU
TypePrecond (MBILU, BILU, DILU, GS, BLOCKJACOBI, JACOBI, HYPRE)
0.5
GustafssonPar (0 to 1, read for MBILU preconditioner only)
#SEMIPRECOND
T
HYPRE
DoPrecond
TypePrecond
Similar to the #PRECONDITIONER command but for the semi-implicit scheme.
If DoPrecond is false, no preconditioner is used. This will result in slower convergence. It is almost
always preferable to use a preconditioner. The semi-implicit scheme always uses left side preconditioning.
The TypePrecond parameter can be set to the following values: JACOBI, BLOCKJACOBI, GS, DILU,
BILU, MBILU or HYPRE. Most of these options are described in some detail for the #PRECONDITIONER
command.
The Diagonal Incomplete Lower-Upper (DILU) preconditioner assumes that the off-diagonal blocks are
diagonal matrices, and it gives the same result but faster performance than BILU in that case. This assumption holds if the derivative of a variable in the semi-implicit terms only affects the same variable (true
for heat conduction, radiative diffusion, dissipative resistivity, but not for Hall resistivity).
The HYPRE preconditioner can only be used if the HYPRE library has been checked out into the util/
directory and Config.pl -hypre has been set. The HYPRE preconditioning only works if the semi-implicit
scheme solves for 1 variable at a time (split semi-implicit scheme).
Default values are shown by the first example.
COMPONENTS
91
#KRYLOV command
#KRYLOV
GMRES
nul
0.001
100
TypeKrylov (GMRES, BICGSTAB, CG)
TypeInitKrylov (nul, old, explicit, scaled)
ErrorMaxKrylov
MaxMatvecKrylov
The TypeKrylov parameter selects the iterative Krylov solver. The GMRES solver is the most robust
and it converges the fastest among all Krylov solvers. It uses one matrix-vector product per iteration.
On the other hand it needs to store one copy of the vector of the unknowns per iteration. GMRES also
has to invert an NxN matrix in the N-th iteration. This means that GMRES is the optimal choice if the
number of iterations is relatively small, typically less than 100. This is almost always true when the HYPRE
preconditioner is used (see the #PRECONDITIONER command).
BICGSTAB is a robust Krylov scheme that only uses 4 copies of the unknown vector, and it uses
two matrix-vector products per iteration. It usually requires somewhat more matrix-vector products than
GMRES to achieve the same accuracy (defined by the tolerance ErrorMaxKrylov). On the other hand all
iterations have the same computational cost.
The preconditioned Conjugate Gradient (CG) scheme only works for symmetric matrices. It only uses
two copies of the unknown vector. For symmetric matrices it is more efficient than BiCGSTAB. In case many
iterations are needed, it is more efficient than GMRES. The CG scheme currently does not work together
with the HYPRE preconditioner.
Initial guess for the Krylov type iterative scheme can be 0 (’nul’), the previous solution (’old’), the
explicit solution (’explicit’), or the scaled explicit solution (’scaled’). The iterative scheme stops if the
required accuracy is achieved or the maximum number of matrix-vector multiplications is exceeded.
The ErrorMaxKrylov parameter defines the relative accuracy of the solution. The iteration stops when
the residual (measured in the second norm) drops below the initial residual times ErrorMaxKrylov.
The MaxMatvecKrylov parameter limits the number of Krylov iterations. It also defines the maximum
number of copies of the unknown vector for the GMRES solver, although this can be overwritten with the
#KRYLOVSIZE command (see the description for more detail). If the Krylov solver does not succeed in
achieving the desired accuracy within the maximum number of iterations, an error message is printed.
#SEMIKRYLOV command
#SEMIKRYLOV
GMRES
0.001
100
TypeKrylov (GMRES, BICGSTAB, CG)
ErrorMaxKrylov
MaxMatvecKrylov
Same as the #KRYLOV command, but for the semi-implicit scheme. The initial guess is always zero, so
there are only 3 parameters.
#KRYLOVSIZE command
#KRYLOVSIZE
10
nKrylovVector
The number of Krylov vectors only matters for GMRES (TypeKrylov=’gmres’). If GMRES does not converge within nKrylovVector iterations, it needs a restart, which usually degrades its convergence rate and
robustness. So nKrylovVector should exceed the number of iterations, but it should not exceed the maximum number of iterations MaxMatvecKrylov. On the other hand the dynamically allocated memory is also
92
proportional to nKrylovVector. The default is nKrylovVector=MaxMatvecKrylov (in #KRYLOV) which
can be overwritten by #KRYLOVSIZE after the #KRYLOV command (if any).
#SEMIKRYLOVSIZE command
#SEMIKRYLOVSIZE
10
nKrylovVector
Same as #KRYLOVSIZE but for the semi-implicit scheme.
#SEMIKRYLOV command (if present).
5.2.10
This command should be used after the
Stopping criteria
The commands in this group only work in stand alone mode.
#STOP command
#STOP
100
10.0
MaxIteration
The MaxIteration variable contains the maximum number of iterations 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. The
default values are MaxIteration=0 and tSimulationMax = 0.0, so the #STOP command must be used in
every session.
#CHECKSTOPFILE command
#CHECKSTOPFILE
T
DoCheckStopFile
If DoCheckStopFile is true then the code checks if the BATSRUS.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 e.g. the ”touch
BATSRUS.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.
#CPUTIMEMAX command
#CPUTIMEMAX
3600
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.
COMPONENTS
5.2.11
93
Output parameters
#RESTARTOUTDIR command
#RESTARTOUTDIR
GM/restart_n5000
NameRestartOutDir
The NameRestartOutDir variable contains the name of the directory where restart files are saved relative to
the run directory. The directory should be inside the subdirectory with the name of the component.
Default value is ”GM/restartOUT”.
#RESTARTOUTFILE command
#RESTARTOUTFILE
one series
TypeRestartOutFile
This command determines if the restart information is saved as an individual file for each block (block), as
direct access files for each processor (proc) or into a single direct access file containing all blocks (one).
Normally saving restart files overwrites the previous files. Adding ’series’ after the type results in a series
of restart files with names starting as nITERATION . This will be used by the adjoint method.
The most reliable format is ’proc’. If there is any issue with restarting with the ’one’ format (some
machines write empty records into the file), the ’proc’ should be used. The ’block’ format can fail due to
too many files.
The default value is ’proc’.
#SAVERESTART
T
100
-1.
DoSaveRestart Rest of parameters read if true
DnSaveRestart
DtSaveRestart [seconds]
Default is DoSaveRestart=.true. with DnSaveRestart=-1 and DtSaveRestart=-1. This results in the
restart file being saved only at the end. A binary restart file is produced for every block and named as
RESTARTOUTDIR/blkGLOBALBLKNUMBER.rst. In addition the grid is described by RESTARTOUTDIR/octree.rst and an ASCII header file is produced with timestep and time info: RESTARTOUTDIR/restart.H
The restart files are overwritten every time a new restart is done, but one can change the name of the
RESTARTOUTDIR with the #RESTARTOUTDIR command from session to session. The default directory
name is ’restartOUT’.
#PLOTDIR command
The NamePlotDir variable contains the name of the directory where plot files and logfiles are saved relative
to the run directory. The directory should be inside the subdirectory with the name of the component.
Default value is ”GM/IO2”.
#SAVELOGFILE command
min=”1” max=”10” length=”100”
#SAVELOGFILE
T
VAR step date
100
DoSaveLogfile, rest of parameters read if true
StringLog
DnSaveLogfile
94
-1.
rho p rhoflx
4.0 10.0
DtSaveLogfile [sec]
NameLogVars (read if StrigLog is ’var’ or ’VAR’)
rLog (radii for the flux. Read if vars include ’flx’)
Default is DoSaveLogfile=.false. The logfile can contain averages or point values and other scalar quantities.
It is written into an ASCII file named as
NAMEPLOTDIR/log TIMESTEP.log
where NAMEPLOTDIR can be defined with the #PLOTDIR command (default is IO2).
The StringLog can contain two groups of information in arbitrary order. The first is LogVar which is a single
3 character string that indicates the type of variables that are to be written. The second group indicates the
type of time/iteration output format to use. This second group is not required and defaults to something
standard for each logvar case.
Any of the identifiers for the timetype can be included in arbitrary order.
logvar
= ’mhd’, ’raw’, ’flx’ or ’var’ - unitless output
logvar
= ’MHD’, ’RAW’, ’FLX’ or ’VAR’ - dimensional output
timetype = ’none’, ’step’, ’time’, ’date’
The logvar string is not optional and must be found on the line. The timetype is optional - when not
specified a logical choice is made by the code.
The log var string defines the variables to print in the log file It also controls whether or not the variables
will come out in dimensional or non-dimensional form by the capitalization of the log var string.
ALL CAPS - dimensional
all lower - dimensionless
’raw’ ’mhd’ ’flx’ ’var’ -
vars:
time:
vars:
time:
vars:
time:
vars:
time:
dt rho rhoUx rhoUy rhoUz Bx By Bz E Pmin Pmax
step time
rho rhoUx rhoUy rhoUz Bx By Bz E Pmin Pmax
step date time
rho Pmin Pmax rhoflx pvecflx e2dflx
step date time
READ FROM PARAMETER FILE
step time
log vars is read only when the log string contains var or VAR. The choices for variables are currently:
Average value on grid:
rho rhoUx rhoUy rhoUz Ux Uy Uz Bx By Bz P E
Value at the test point: rhopnt rhoUxpnt rhoUypnt rhoUxpnt Uxpnt Uypnt Uzpnt
Bxpnt Bypnt Bzpnt B1xpnt B1ypnt B1zpnt
Epnt Ppnt Jxpnt Jypnt Jzpnt
theta1pnt theta2pnt phi1pnt phi2pnt statuspnt
Ionosphere values:
cpcpn cpcps
Max or Min on grid:
Flux values:
Other variables:
Pmin Pmax
Aflx rhoflx Bflx B2flx pvecflx e2dflx
dt
timetype values mean the following:
none
= there will be no indication of time in the logfile (not even an
# of steps)
COMPONENTS
step
date
time
95
= # of time steps (n_steps)
= time is given as an array of 7 integers: year mo dy hr mn sc msc
= time is given as a real number - elapsed time since the start of
the run. Units are determined by log_var and unitUSER_t
these can be listed in any combination in the log string line.
R log is read only when one of the variables used is a ’flx’ variable. R log is a list of radii at which to
calculate the flux through a sphere.
#SATELLITE command
#SATELLITE
2
MHD ray
100
-1.
satellite1.dat
VAR step date
100
-1.
satellite2.dat
rho p
nSatellite
StringSatellite (variables and optional ray tracing)
DnOutput
DtOutput [sec]
NameTrajectoryFile
StringSatellite
DnOutput
DtOutput [sec]
NameTrajectoryFile
NameSatelliteVars ! Read if StringSatellite
! contains ’var’ or ’VAR’
The numerical solution can be extracted along one or more satellite
trajectories. The number of satellites is defined by the
nSatellite parameter (default is 0).
For each satellite the StringSatellite parameter determines what is saved into the satellite file(s). The
StringSatellite can contain the following parts in arbitrary order
satellitevar
optionalvar
= ’mhd’, ’ful’ or ’var’ (unitless output)
’MHD’, ’FUL’ or ’VAR’ (dimensional output)
= ’ray’, ’none’, ’step’, ’time’, and/or ’date’
The ’satellitevar’ part is required and determines the list of variables to be saved along the satellite trajectory.
It also controls whether or not the variables will come out in dimensional or non-dimensional form by the
capitalization of the satellitevars string: ALL CAPS means dimensional, all lower means dimensionless.
If ’satellitevar’ is set to ’mhd’, the variables ’rho ux uy uz bx by bz p jx jy jz’ will be saved, while ’ful’
implies ’rho ux uy uz bx by bz b1x b1y b1z p jx jy jz’.
If satellitevar is set to ’var’ then the list of variables is read from the NameSatelliteVar parameter as a
space separated list. The choices for variables are currently:
rho, rho, rhouy, rhouz, ux, uy, uz,Bx, By, Bz, B1x, B1y, B1z,
E, P, Jx, Jy, Jz, theta1, theta2, phi1, phi2, status.
If the optional ’optionalvar’ part contains ’ray’ then the ray variables ’theta1 phi1 theta2 phi2 status’
are saved as well. The strings ’step’, ’time’ and ’date’ define the corresponding time information. The value
’none’ means that no time information is saved.
none
step
date
time
= there will be no indication of time in the logfile
(not even the number of steps),
= number of time steps,
= time is given as an array of 7 integers: year mo dy hr mn sc msc,
= time is given as a real number - elapsed time since the start of
96
the run.
ray
Units are determined by satellitevar and unitUSER_t.
= theta1 phi1 theta2 phi2 status
More than one ’optionalvar’ can be listed. They can be put together in any combination.
The DnOutput and DtOutput parameters determine the frequency of extracting values along the satellite
trajectories.
The extracted satellite information is saved into the files named
PLOTDIR/sat_TRAJECTORYNAME_nTIMESTEP.sat
where TIMESTEP is the number of time steps (e.g. 000925), and TRAJECTORYNAME is the name of the
trajectory file.
The default is nSatellite=0, i.e. no satellite data is saved.
Satellite input files contain the trajectory of the satellite. They should have to following format:
#COOR
GSM
#START
2004 6
2004 6
24
24
0
0
0
1
58
58
0
0
2.9
2.8
-3.1 - 3.7
-3.2 - 3.6
The #COOR command is optional. It indicates which coordinate system the data represents. The
default is GSM, but others are possible.
The file containing the satellite trajectory should include data in the following order:
yr mn dy hr min sec msec x y z
with the position variables in units of the body radii or the length scale normalization.
The maximum number of lines of data allowed in the input file is 50,000. However, this can be modified
by changing the variable Max Satellite Npts in the file GM/BATSRUS/ModIO.f90.
#STEADYSTATESATELLITE command
#STEADYSTATESATELLITE
-86400.0
86400.0
-3600.0
3600.0
SatelliteTimeStart
SatelliteTimeEnd
SatelliteTimeStart
SatelliteTimeEnd
[sec]
[sec]
[sec]
[sec]
In the non-time-accurate mode the numerical simulation result converges to a steady-state solution. In the
course of this simulation mode, the progress in the iteration number is not associated with an increase in the
physical time, and the ultimate solution is a ”snapshot” of the parameter distribution at the time instant
set by the #STARTTIME command. Since time does not run, a satellite position cannot be determined in
terms of the simulation time. Instead, the parameters along a cut of the satellite trajectory can be saved on
file for a given iteration number. The trajectory points can be naturally parameterized by time, so that the
cut can be specified with the choice of the start time, end time, and time interval.
The command #STEADYSTATESATELLITE is required for a steady-state simulation. For each of the
satellites, the SatelliteTimeStart is a real value that sets the start of trajectory cut, while SatelliteTimeEnd
sets the end of the trajectory cut. Both are in seconds with respect to the time given in #STARTTIME. A
negative value means the is time prior to the #STARTTIME.
COMPONENTS
97
The DtOutput from the #SATELLITE command specifies the frequency of the points along the satellite
trajectory for the non-time-accurate mode, while DnOutput keeps to control the iteration number at which
the data at the trajectory cut are written to the satellite output file.
For more than one satellite (two satellites in the above given example), the start and end times should
be set for all of them.
#GEOMAGINDICES command
#GEOMAGINDICES
180
60.0
nSizeKpWindow [min]
DtOutput
[sec]
BATS-R-US can create synthetic geomagnetic indices by first simulating ground based measurements then
processing these data into indices. This allows for an apples-to-apples comparison of indices created by
the simulation against indices created from observations. It is also useful in an operational setting, where
quick-look activity indices are paramount. #GEOMAGINDICES activates the calculation of such indices.
Results are written at a time cadence of DtOutput to the file geoindex n[iteration].log
At present, only a synthetic version of Kp is available. nSizeKpWindow, set in minutes and defaulting
to 180 (3 hours), sets the size of the time-history window used in the calculation of Kp. Standard Kp uses
a 3-hour window; versions of Kp used as operational products use a window as short as 15-minutes. Note
that altering this window requires a re-scaling of the K-index conversion tables inside of the code. As Kp is
written to file, so are the individual K-indices used in the calculation. Offical Kp averages 13 K values from
13 mid-latitude magnetometer stations around the globe. Synthetic Kp from BATS-R-US uses 24 stations
at fixed local time positions and 50 degrees magnetic latitude.
Because Kp requires a time history of geomagnetic activity, special restart files are saved when #GEOMAGINDICES is used. If nSizeKpWindow changes between restarts, however, the files will be rendered
unuseable because the time history will no longer be valid for the calculation.
#GEOMAGINDICES should be used with the IE command of the same name. This activates magnetometers in the IE component that are key for properly capturing the magnetic pertubation from all current
systems.
#MAGNETOMETER command
#MAGNETOMETER
magin.dat
-1
60.0
NameMagInputFile
DnOutput
DtOutput
The #MAGNETOMETER command is used for the calculation of the ground perturbations caused by two
current systems: field aligned currents in the ’gap’ region and magnetopsheric currents. No ionospheric
currents are considered here. To calculate the ionospheric current effect, use the same command in the IE
section, which will output the perturbation results in IE.
The NameMagInputFile parameter gives the file name that contains the locations on the Earth where
the user is interested in calculating the ground magnetic perturbations. The file has the following format:
#COORD
MAG
#START
abc
def
ghi
The coordinate system for the latitude/longitude below
20.0
-30.0
85.0
120.0
230.0
-80.0
The name of the station, latitude, longitude
98
The coordinate system accepts MAG (geomagnetic coordinate) or SMG (solar magnetic coordinate) so
far. The station name can have maximum 3 characters. The name, latitude, and longitude should be
sperated with space in between.
The DnOutput and DtOutput parameters determine the frequency of writing out the calculated perturbations in number of time steps and time interval, respectively.
The output of the ground-based magnetic perturbations is in GM/IO2/mag n*.dat, in which the location
of each station in GSM cartisian coordinates, the 3 components (northward, eastward, and downward in SM
coordiantes) of the magnetic perturbations by magnetospheric currents, and the 3 components (northward,
eastward, and downward in SM coordiantes) of the magnetic perturbations by field-aligned currents are
written out. The unit of the pertrubation output is nT.
#SAVEPLOT command
default=”-1.0”
#SAVEPLOT
16
3d MHD tec
100
-1.
2d FUL hdf
100
-1.
y=0 VAR idl
-1
100.
0.25
jx jy jz
g rbody
cut ray idl_real8
1
-1.
-10.
10.
-10.
10.
-10.
10.
-1.
sph flx idl_ascii
-1
100.
4.
los tbl idl_real4
-1
100.
-215.
0.
0.
0.
32.
0.
nPlotfile
StringPlot !
DnSavePlot
DtSavePlot
StringPlot !
DnSavePlot
DtSavePlot
StringPlot !
DnSavePlot
DtSavePlot
DxSavePlot !
NameVars
NamePars
StringPlot !
DnSavePlot
DtSavePlot
xMinCut
xMaxCut
yMinCut
yMaxCut
zMinCut
zMaxCut
DxSavePlot !
StringPlot !
DnSavePlot
DtSavePlot
Radius
!
StringPlot !
DnSavePlot
DtSavePlot
ObsPosX
ObsPosY
ObsPosZ
OffsetAngle
rSizeImage
xOffset
3d plot with MHD data
2d HDF plot with a lot of data
y=0 plane plot with listed variables
resolution (for IDL plots)
3D cut IDL (ONLY!) plot with raytrace info
unstructured grid (for IDL plots)
spherical plot
of spherical surface
line of sight plot using table
COMPONENTS
0.
3.
0.5
300
AiaXrt
lin mhd
-1
10.
B
F
2
-2.0
0.0
3.5
F
-1.0
1.0
-3.5
T
dpl MHD
-1
10.
-10.
10.
-10.
10.
-10.
10.
slc MHD
-1
10.
-10.
10.
-10.
10.
-10.
10.
0.
0.
0.
0.
0.
1.
blk MHD
-1
10.
5.
1.
1.
1d BBK
1000
idl
tec
tec
tec
tec
yOffset
rOccult
MuLimbDarkening
nPix
NameLosTable
StringPlot ! field line plot
DnSavePlot
DtSavePlot
NameLine ! B - magnetic field line, U - stream line
IsSingleLine
nLine
xStartLine
yStartLine
zStartLine
IsParallel
xStartLine
yStartLine
zStartLine
IsParallel
StringPlot ! dipole slice Tecplot (ONLY!) plot
DnSavePlot
DtSavePlot
xMinCut
xMaxCut
yMinCut
yMaxCut
zMinCut
zMaxCut
StringPlot ! general slice Tecplot (ONLY!) plot
DnSavePlot
DtSavePlot
xMinCut
xMaxCut
yMinCut
yMaxCut
zMinCut
zMaxCut
xPoint
yPoint
zPoint
xNormal
yNormal
zNormal
StringPlot ! general block Tecplot (ONLY!) plot
DnSavePlot
DtSavePlot
xPoint
yPoint
zPoint
StringPlot ! 1d plot with BLK data, Tecplot (ONLY!)
DnSavePlot
99
100
-1.
rfr rwi tec
10
-1.0
150.0
145.7
50.0
10MHz, 42.3MHz, 100MHz
20.0
20.0
200
200
eqr eqr idl
1000
-1.
20
25
3.0
10.0
ieb nul tec
1000
-1.
lcb nul tec
1000
-1.
6.
36
lcb int tec
1000
-1.
6.
36
DtSavePlot
StringPlot
DnSavePlot
DtSavePlot
ObsPosX
ObsPosY
ObsPosZ
StringRadioFrequency
X_Size_Image
Y_Size_Image
n_Pix_X
n_Pix_Y
StringPlot
DnSavePlot
DtSavePlot
nRadius
nLon
RadiusMin
RadiusMax
StringPlot !IE grid field line plots
DnSavePlot
DtSavePlot
StringPlot !last closed field line plots
DnSavePlot
DtSavePlot
Radius
nLon
StringPlot !last closed field line plots with integrals stored
DnSavePlot
DtSavePlot
Radius
nLon
Default is nPlotFile=0.
StringPlot must contain the following 3 parts in the following order
plotform plotarea plotvar
plotform
plotarea
plotvar
plotvar
=
=
=
=
’tec’, ’hdf’, ’idl’, ’idl_real4’, ’idl_real8’, ’idl_ascii’
’1d’, ’2d’, ’3d’ , ’x=0’, ’y=0’, ’z=0’, ’cut’, ’dpl’, ’slc’, ’sph’, ’los’, ’lin’, ’blk’, ’rfr
’mhd’, ’hd’, ’ful’, ’raw’, ’ray’, ’flx’, ’sol’, ’euv’, ’sxr’, ’tbl’, ’pos’, ’var’, ’bbk’ ’rwi
’MHD’, ’hd’, ’FUL’, ’RAW’, ’RAY’, ’FLX’, ’SOL’, ’EUV’, ’SXR’, ’TBL’, ’pos’, ’VAR’, ’BBK’ ’RWI
NOTES: The plotvar option ’sol’ is only valid for plotarea ’los’; The plotvar option ’euv’ is only valid for
plotarea ’los’; The plotvar option ’sxr’ is only valid for plotarea ’los’; The plotvar option ’tbl’ is only valid
for plotarea ’los’; the plotvar option ’pos’ is only valid for plotarea ’lin’. the plotvar option ’rwi’ is only valid
for plotarea ’rfr’.
The plotform string selects the output to be usable for Tecplot (tec), VISIT (hdf), or IDL (idl*) visualization
software. The HDF output works only if the HDF library is installed, the appropriate parallel HDF module
is loaded and BATSRUS is configured with the -hdf flag. The IDL output can be written as single precision
COMPONENTS
101
binary (idl real4), double precision binary (idl real8) or ASCII file (idl ascii). The default is ’idl real4’ that
can also be written simply as ’idl’.
The plotarea string defines the 1, 2, or 3D volume of the plotting area:
1d
2d
3d
x=0
y=0
z=0
cut
dpl
slc
sph
los
lin
blk
rfr
eqr
ieb
lcb
-
1D cut along the X axis (saves tree file)
2D cut (like Z=0)
(saves tree file)
full 3D volume
(saves tree file)
full x=0 plane: average for symmetry plane
full y=0 plane: average for symmetry plane
full z=0 plane: average for symmetry plane
3D, 2D or 1D rectangular cut (IDL)/ a 2D rectangular cut (Tecplot)
cut at dipole ’equator’, uses PLOTRANGE to clip plot
2D slice defined with a point and normal, uses PLOTRANGE to clip plot
spherical surface cut at the given radius
line of sight integrated plot
one dimensional plot along a field or stream or current line
3D single block cell centered data, block specified point location
radiotelescope pixel image plot
field lines traced from the magnetic equatorial plane
field lines traced from a subset of the IE coupled grid
last closed field lines
The 1d, 2d and 3d cuts save the AMR tree information into a .tree file. This can be used for reconstructing
the full grid and use the data with the READAMR library, for example.
The plotvar string defines the plot variables and the equation parameters. It also controls whether or
not the variables will be plotted in dimensional values or as non-dimensional values:
ALL CAPS - dimensional
all lower - dimensionless
’mhd’ - vars:
pars:
’hd’ - vars:
pars:
’ful’ - vars:
pars:
’raw’ - vars:
pars:
’ray’ - vars:
pars:
’flx’ - vars:
pars:
’var’ - vars:
pars:
’sol’ - vars:
pars:
’euv’ - vars:
pars:
’sxr’ - vars:
pars:
’tbl’ - vars:
pars:
rho Ux Uy Uz E Bx By Bz P Jx Jy Jz
g rbody
rho Ux Uy Uz E P
g rbody
rho Ux Uy Uz E Bx By Bz B1x B1y B1z P Jx Jy Jz
g rbody
rho rhoUx rhoUy rhoUz E Bx By Bz P b1x b1y b1z divb
g rbody
bx by bz theta1 phi1 theta2 phi2 status blk
R_ray
rho rhoUr Br jr pvecr
g eta
wl pb
mu
euv171 euv195 euv284
sxr
listed in the LOS table file
102
’bbk’ - vars: dx pe blk blkall
pars:
’rwi’ - vars: Intensity
pars:
’int’ - vars: 1/B n/B p/B
pars:
’nul’ - vars:
pars:
The plot string is always followed by the plotting frequencies DnSavePlot and DtSavePlot.
Depending on StringPlot, further information is read from the parameter file in this order:
PlotRange
Point
Normal
DxSavePlot
Radius
NameVars
NamePars
if
if
if
if
if
if
if
plotarea
plotarea
plotarea
plotform
plotarea
plotform
plotform
is
is
is
is
is
is
is
’cut’, ’dpl’, or ’slc’
’slc’, or ’blk’
’slc’
’idl’ and plotarea is not sph, ion, los
’sph’
’var’
’var’
The PlotRange is described by 6 coordinates. For IDL plots, if the width in one or two dimensions is less than
the smallest cell size within the plotarea, then the plot file will be 2 or 1 dimensional, respectively. If the range
is thin but symmetric about one of the x=0, y=0, or z=0 planes, data will be averaged in the postprocessing.
For Tecplot (tec) file and ’cut’, Plotrange is read but only 1 dimension is used. Cuts are entire x, y, or z
= constant planes (2D only, 1D or 3D cuts are not implemented. For x=constant, for example, the y and z
ranges do not matter as long at they are ”wider” than the x range. The slice will be located at the average
of the two x ranges. So, for example to save a plot in a x=-5 constant plane cut in tec. The following would
work for the plot range:
-5.01
-4.99
-10.
10.
-10.
10.
xMinCut
xMaxCut
yMinCut
yMaxCut
zMinCut
zMaxCut
The ’dpl’ and ’slc’ Tecplot plots use Plotrange like the IDL plots, and will clip the cut plane when it exits
the defined box.
Point is described by the coordinate of any point on the cut plane, often the origin, or inside of a 3D block.
Normal is the coordinate of a vector normal to the plane. If the normal in any given coordinate direction is
less than 0.01, then no cuts are computed for cell edges parallel to that coordinate direction. For example,
the following would result in only computing cuts on cell edges parallel to the Z axis.
0.0
0.0
1.0
xNormal
yNormal
zNormal
Possible values for DxSavePlot (for IDL files):
any positive value
- fixed resolution
0.
- fixed resolution based on the smallest cell in the plotting area
-1.
- unstructured grid will be produced by PostIDL.exe
COMPONENTS
103
Radius is the radius of the spherical cut for plotarea=’sph’
The line-of-sight (plotarea ’los’) plots calculate integrals along the lines of sight of some quantity and
create a 2D Cartesian square shaped grid of the integrated values. Only the circle enclosed in the square is
actually calculated and the corners are filled in with zeros. The image plane always contains the origin of
the computational domain (usually the center of the Sun). By default the image plane is orthogonal to the
observers position relative to the origin. The image plane can be rotated around the Z axis with an offset
angle. By default the center of the image is the observer projected onto the image plane, but the center of
the image can be offset. Since the central object (the Sun) contains extremely large values, an occultational
disk is used to block the lines of sight going through the Sun. The variables which control the direction of
the lines of sight and the grid position and resolution are the following:
ObsPosX,ObsPosY,ObsPosZ - the position of the observer in (rotated)
HGI coordinates (SC,IH and OH) or the GM coordinates
rSizeImage
- the radius of the LOS image
xOffset, yOffset
- offset relative to the observer projected onto
the image plane
rOccult
- the radius of the occulting disk
MuLimbDarkening
- the limb darkening parameter for the ’wl’
(white light) and ’pb’ (polarization brightness)
plot variables.
nPix
- the number of pixels in each direction
For line-of-site Extreme Ultraviolet (EUV) and Soft X-Ray (SXR) plots, the same parametes are read as
for the wl and pb plots (above) but now the integration is carried out to the surface of the sun so rOccult
should be set to zero. MuLimbDarkening has no effect but needs to be included.
Additionally, because EUV and SXR plots are configured to read in a response table specific to the EUV
or SXR instument (e.g. SOHO EIT, STEREO EUVI, Yohkoh SXT) the tables for the response need to be
read in by additional lines in the PARAM.in file. This follows the #LOOKUPTABLE command syntax e.g:
#LOOKUPTABLE
euv
load
SC/Param/los_Eit.dat
ascii
NameTable
NameCommand
NameFile
TypeFile
#LOOKUPTABLE
sxr
load
SC/Param/los_Sxt.dat
ascii
NameTable
NameCommand
NameFile
TypeFile
The possible values for NameVars with plotarea ’los’ are listed in subroutine set plotvar los in write plot los.f90.
The radiotelescope pixel image (plotarea ’rfr’) plots present the plasma emissivity integrals along the ray
trajectories within a 2D Cartesian square shaped grid. The radiowave rays with the frequencies on the order
of tens of MegaHertz undergo significant refraction when travelling through non-uniform space plasmas;
hence the name ’rfr’. The radio wave raytracing is performed by a modification of the Boris’s algorithm.
The image plane center coincides with the origin of the computational domain (usually the center of the
Sun). The observer’s position is specified at an arbitrary point of the solar system. The image plane is
always orthogonal to the straight line connecting the observer with the center of the sun. The following
variables specify the observer’s position, the image plane size, the resolution, and the radio frequencies at
which the plasma emissivity is integrated:
104
ObsPosX,ObsPosY,ObsPosZ - the position of the observer in (rotated)
HGI coordinates (SC, IH and OH) or the GM coordinates
StringRadioFrequency
- set of frequencies. The number of frequencies
determines the number of plots, one for each
frequency. A frequency is specified as a number
followed by a frequency unit. The units are
Hz, kHz, MHz, GHz, or THz.
X_Size_Image, Y_Size_Image - X and Y dimensions of the image plane in
solar radii
n_Pix_X, n_Pix_Y
- the number of pixels in X and Y directions
The only possible values for NameVars with plotarea ’rfr’ is ’rwi’.
The possible values for NameVars for other plot areas are listed in subroutine set plotvar in write plot common.f90.
The possible values for NamePars are listed in subroutine set eqpar in write plot common.f90
A plot file is produced by each processor. This file is ASCII in ’tec’ format and can be either binary or
ASCII in ’idl’ format as chosen under the #SAVEBINARY flag. The name of the files are
IO2/plotarea_plotvar_plotnumber_timeinfo_PEnumber.extension
where extension is ’tec’ for the TEC and ’idl’ for the IDL file formats. The plotnumber goes from 1 to nplot
in the order of the files in PARAM.in. The ’timeinfo’ contains simulation time as hours-minutes-seconds (for
time accurate runs only), and time step number. Spherical plot area ’sph’ creates two files per processor
starting with ’spN’ and ’spS’ for the northern and southern hemispheres, respectively.
After all processors wrote their plot files, processor 0 writes a small ASCII header file named as
IO2/plotarea_plotvar_plotnumber_timestep.headextension
where headextension is:
’T’ for TEC file format
’S’ for TEC and plot_area ’sph’
’h’ for IDL file format
The line of sight integration produces TecPlot and IDL files directly:
IO2/los_plotvar_plotnumber_timestep.extension
where extension is ’dat’ for TecPlot and ’out’ for IDL file formats. The IDL output from line of sight
integration is always in ASCII format.
#SAVEPLOTNAME command
#SAVEPLOTNAME
T
T
F
IsPlotName_n
IsPlotName_t
IsPlotName_e
Plot files are named with the preferred set of substrings. n is interation number, ie.
simulation time, ie. t00000010 e is event time, ie. e20000321-104510-000
n0000127 t is
COMPONENTS
105
#SAVELOGNAME command
#SAVELOGNAME
T
F
IsLogName_n
IsLogName_e
Log files are named with the preferred set of substrings. n is interation number, ie. n000000 e is event
time, ie. e20000321-104500
#SAVEBINARY command
#SAVEBINARY
T
DoSaveBinary
used only for ’idl’ plot file
Default is .true. Saves unformatted IO2/*.idl files if true. This is the recommended method, because it is
fast and accurate. The only advantage of saving IO2/*.idl in formatted text files is that it can be processed
on another machine or with a different (lower) precision. For example PostIDL.exe may be compiled with
single precision to make IO2/*.out files smaller, while BATSRUS.exe is compiled in double precision to make
results more accurate.
#PLOTFILENAME command
#PLOTFILENAME
hour
NameMaxTimeUnit
For time accurate runs the plot filenames contain an 8-charcter timestamp string. The NameMaxTimeUnit
string determines the content of this string.
If the longest time unit is hours or shorter, the string contains the simulation time. If the time unit is days
or longer the string contains the physical date (set by the #STARTTIME command) and time information.
For NameMaxTimeUnit=’hour’ the string contains the simulation time described by a 4-character string
for hours, and two 2-character strings for minutes and seconds, respectively. For NameMaxTimeUnit=’hr’
the string contains the simulation time described by a 2-character strings for hours, minutes, and seconds
with a decimal point and one decimal digit. For NameMaxTimeUnit=’minute’ the first 2 characters describe
the minutes, and the rest is seconds including 3 decimal digits. NameMaxTimeUnit=’second’ gives the
simulation time up to 100 seconds with 5 decimal digits. NameMaxTimeUnit=’millisecond’ (’microsecond’,
’nanosecond’) give the simulation time up to 1000 milliseconds (microseconds, nanoseconds) with 4 decimal
digits.
For time unit ’date’ the full 14-character date-time string (YYYYMMDDHHMMSS) is used. For time
units ’day’, ’month’, ’yr’ and ’year’ an 8-character-long substring of the date-time string is used. For
NameMaxTimeUnit=’year’ the time stamp will contain the four digit year, and the two-digit month and
day. For NameMaxTimeUnit=’yr’ the last two digits of the year, and the month, day and hour are used. For
NameMaxTimeUnit=’month’ the month, day, hour, and minute are used. For NameMaxTimeUnit=’day’
the day, hour, minute and seconds are used. For NameMaxTimeUnit=’timestep’ only the timestep is used.
The #PLOTFILENAME command and the NameMaxTimeUnit parameter are saved into the restart
header file so that the #PLOTFILENAME command does not have to be repeated in restarted runs (unless
the unit is changed).
The default value is NameMaxTimeUnit=’hour’.
#SAVEINITIAL command
#SAVEINITIAL
T
DoSaveIntial
Save plots and log/satellite files at the beggining of the session. Default is DoSaveInitial=.false. except for
the first time accurate session (when simulation time is zero) when the initial state is always saved.
106
#SAVEPLOTSAMR command
#SAVEPLOTSAMR
F
DoSavePlotsAmr
Save plots before each AMR. Default is DoSavePlotsAMR=.false.
#FLUSH command
#FLUSH
F
DoFlush
If the DoFlush variable is true, the output is flushed when subroutine ModUtility::flush unit is called. This
is used in the log and satellite files. The flush is useful to see the output immediately, and to avoid truncated
files when the code crashes, but on some systems the flush may be very slow.
The default is to flush the output, i.e. DoFlush=T.
5.2.12
Amr parameters
#AMRINITPHYSICS command
#AMRINITPHYSICS
3
nRefineLevelIC
Defines number of physics (initial condition) based AMR-s AFTER the geometry based grid refinement was
finished. Only useful if the initial condition has a non-trivial analytic form.
#AMRREGION command
required=”F” required=”F”
#AMRREGION
tailbox
box
-64.0
-16.0
-16.0
-32.0
16.0
0.0
NameRegion
NameArea
xMinBox
yMinBox
zMinBox
xMaxBox
yMaxBox
zMaxBox
#AMRREGION
tailbox
brick
-48.0
0.0
-8.0
32.0
32.0
16.0
NameRegion
NameArea
xCenter
yCenter
zCenter
xSizeBrick
ySizeBrick
zSizeBrick
#AMRREGION
tailbox
shell0
3.5
4.5
NameRegion
NameArea
Radius1
Radius2
COMPONENTS
#AMRREGION
tailbox
sphere
-10.0
10.0
0.0
20.0
NameRegion
NameArea
xCenterSphere
yCenterSphere
zCenterSphere
rSphere
#AMRREGION
tailbox
cylinderx
-30.0
0.0
0.0
60.0
20.0
NameRegion
NameArea
xCenter
yCenter
zCenter
LengthCylinder
rCylinder
#AMRREGION
tailbox
ringz0 rotated
5.0
20.0
25.0
10.0
10.0
0.0
NameRegion
NameArea
HeightRing
Radius1
Radius2
xRotate
yRotate
zRotate
#AMRREGION
tailbox
sphere0 stretched
10.0
1.0
3.0
2.0
NameRegion
NameArea
rSphere
xStretch
yStretch
zStretch
#AMRREGION
tailbox
user
NameRegion
NameArea
107
The #AMRREGION comand allow us to make a library of areas in the simulation domain idenifed by a
unique NameRegion to be used with the #AMRCRITERIALEVEL or #AMRCRITERIARESOLUTION
comand to define where a criteria geometricly will be evaluated or not.
For other values of NameArea, the command specifies the shape of the area. where the blocks are to be
refined. If the desired grid resolution is finer than the initial resolution, then initially the grid will be refined
to the initial resolution only, but the area will be further refined in subsequent pre-specified adaptive mesh
refinements (AMRs) during the run (see the #AMR command). Once the resolution reaches the desired
level, the AMR-s will not do further refinement. If a grid block is covered by more than one areas, the area
with the finest resolution determines the desired grid resolution.
All computational blocks that intersect the area and have a coarser resolution than the resolution set
for the area are selected for refinement. There are the following basic shapes: ’all’, ’box’, ’box gen’, ’brick’,
’brick gen’, ’sphere’, ’shell’, ’cylinderx’, ’cylindery’, ’cylinderz’, ’ringx’, ’ringy’ and ’ringz’.
The area ’all’ refers to the whole computational domain, and it can be used to set the overall minimum
resolution. The area ’box’ is a box aligned with the X, Y and Z axes, and it is given with the coordinates
108
of two diagonally opposite corners. The area ’brick’ has the same shape as ’box’, but it is defined with
the center of the brick and the size of the brick. The ’box gen’ and ’brick gen’ areas can be used for nonCartesian grids to define a box in the generalized coordinates. For example a sphere around the origin can
be described as a box in generalized coordinates with radius going from 0 to R, phi going from 0 to 360
degrees and latitude going from -90 to +90 degrees. Note that angles are given in degrees, and radius is
given even if the generalized coordinates use its logarithm.
The area ’sphere’ is a sphere around an arbitrary point, which is defined with the center point and the
radius of the sphere. The area ’shell’ consists of the volume between two concentric spherical surfaces, which
is given with the center point and the two radii. The area ’cylinderx’ is a cylinder with an axis parallel
with the X axis, and it is given with the center, the length of the axis and the radius, The areas ’cylindery’
and ’cylinderz’ are cylinders parallel with the Y and Z axes, respectively, and are defined analogously as
’cylinderx’. The area ’ringx’, ’ringy’ and ’ringz’ are the volumes between two cylindrical surfaces parallel
with the X, Y and Z axes, respectively. The ring area is given with the center, the height and the two radii.
Note that all these round shapes can be made elliptical with the ”stretched” option (see below).
If the area name contains the number ’0’, the center is taken to be at the origin and the center coordinates
are not read. Note that the areas ’box’ and ’box gen’ are defined with the corners so the ’0’ cannot be used
for these.
If the word ’stretched’ is added after the area name, the area can be stretched in the X, Y and Z directions.
This allows making an ellipsoid from a sphere, or an elliptical slab from a cylinder. Also useful to distort
shells and rings.
If the word ’rotated’ is added after the area name, the area can be rotated by 3 angles around the X, Y
and Z axes in this order. Only the areas ’box’, ’brick’, ’cylinder*’ and ’ring*’ can be rotated.
The ’currentsheet’ area is defined as the blocks containing a reversal of the radial magnetic field. This
is mostly useful for the solar corona and heliosphere. This special area type cannot be stretched, rotated or
centered.
The ’user’ area results in a call of the subroutine user specify refinement defined in the user module. The
user can define an arbitrary set of criteria for refinement. Again, stretching, rotation and centering cannot
be applied to the ’user’ area.
#GRIDRESOLUTION command
required=”F” required=”F”
#GRIDRESOLUTION
2.0
initial
Resolution
NameArea
#GRIDLEVEL
3
all
nLevel
NameArea
#GRIDLEVEL
4
box
-64.0
-16.0
-16.0
-32.0
16.0
0.0
nLevel
NameArea
xMinBox
yMinBox
zMinBox
xMaxBox
yMaxBox
zMaxBox
#GRIDLEVEL
COMPONENTS
4
brick
-48.0
0.0
-8.0
32.0
32.0
16.0
nLevel
NameArea
xCenter
yCenter
zCenter
xSizeBrick
ySizeBrick
zSizeBrick
#GRIDRESOLUTION
1/8
shell0
3.5
4.5
Resolution
NameArea
Radius1
Radius2
#GRIDRESOLUTION
0.5
sphere
-10.0
10.0
0.0
20.0
Resolution
NameArea
xCenterSphere
yCenterSphere
zCenterSphere
rSphere
#GRIDRESOLUTION
1/8
cylinderx
-30.0
0.0
0.0
60.0
20.0
Resolution
NameArea
xCenter
yCenter
zCenter
LengthCylinder
rCylinder
#GRIDRESOLUTION
1/8
ringz0 rotated
5.0
20.0
25.0
10.0
10.0
0.0
Resolution
NameArea
HeightRing
Radius1
Radius2
xRotate
yRotate
zRotate
#GRIDRESOLUTION
1/4
sphere0 stretched
10.0
1.0
3.0
2.0
Resolution
NameArea
rSphere
xStretch
yStretch
zStretch
#GRIDRESOLUTION
0.15
currentsheet
Resolution
NameArea
109
110
#GRIDRESOLUTION
1/8
user
Resolution
NameArea
The #GRIDRESOLUTION and #GRIDLEVEL commands allow to set the grid resolution or refinement
level, respectively, in a given area. The Resolution parameter refers to the size of the cell in the first direction
(Dx or Dr). The nLevel parameter is an integer with level 0 meaning no refinement relative to the root block,
while level N is a refinement by 2 to the power N.
If NameArea is set to ’initial’, it determines the number of grid adaptations used to initialize the grid.
The grid adaptations are done according to the other GRIDLEVEL and GRIDESOLUTION commands.
The default is no refinement initially, which means that the grid is uniform at the beginning, and it is refined
during the run according to the #AMR or #DOAMR commands.
For other values of NameArea, the command specifies the shape of the area. where the blocks are to be
refined. If the desired grid resolution is finer than the initial resolution, then initially the grid will be refined
to the initial resolution only, but the area will be further refined in subsequent pre-specified adaptive mesh
refinements (AMRs) during the run (see the #AMR command). Once the resolution reaches the desired
level, the AMR-s will not do further refinement. If a grid block is covered by more than one areas, the area
with the finest resolution determines the desired grid resolution.
All computational blocks that intersect the area and have a coarser resolution than the resolution set
for the area are selected for refinement. There are the following basic shapes: ’all’, ’box’, ’box gen’, ’brick’,
’brick gen’, ’sphere’, ’shell’, ’cylinderx’, ’cylindery’, ’cylinderz’, ’ringx’, ’ringy’ and ’ringz’.
The area ’all’ refers to the whole computational domain, and it can be used to set the overall minimum
resolution. The area ’box’ is a box aligned with the X, Y and Z axes, and it is given with the coordinates
of two diagonally opposite corners. The area ’brick’ has the same shape as ’box’, but it is defined with
the center of the brick and the size of the brick. The ’box gen’ and ’brick gen’ areas can be used for nonCartesian grids to define a box in the generalized coordinates. For example a sphere around the origin can
be described as a box in generalized coordinates with radius going from 0 to R, phi going from 0 to 360
degrees and latitude going from -90 to +90 degrees. Note that angles are given in degrees, and radius is
given even if the generalized coordinates use its logarithm.
The area ’sphere’ is a sphere around an arbitrary point, which is defined with the center point and the
radius of the sphere. The area ’shell’ consists of the volume between two concentric spherical surfaces, which
is given with the center point and the two radii. The area ’cylinderx’ is a cylinder with an axis parallel
with the X axis, and it is given with the center, the length of the axis and the radius, The areas ’cylindery’
and ’cylinderz’ are cylinders parallel with the Y and Z axes, respectively, and are defined analogously as
’cylinderx’. The area ’ringx’, ’ringy’ and ’ringz’ are the volumes between two cylindrical surfaces parallel
with the X, Y and Z axes, respectively. The ring area is given with the center, the height and the two radii.
Note that all these round shapes can be made elliptical with the ”stretched” option (see below).
If the area name contains the number ’0’, the center is taken to be at the origin and the center coordinates
are not read. Note that the areas ’box’ and ’box gen’ are defined with the corners so the ’0’ cannot be used
for these.
If the word ’stretched’ is added after the area name, the area can be stretched in the X, Y and Z directions.
This allows making an ellipsoid from a sphere, or an elliptical slab from a cylinder. Also useful to distort
shells and rings.
If the word ’rotated’ is added after the area name, the area can be rotated by 3 angles around the X, Y
and Z axes in this order. Only the areas ’box’, ’brick’, ’cylinder*’ and ’ring*’ can be rotated.
The ’currentsheet’ area is defined as the blocks containing a reversal of the radial magnetic field. This
is mostly useful for the solar corona and heliosphere. This special area type cannot be stretched, rotated or
centered.
The ’user’ area results in a call of the subroutine user specify refinement defined in the user module. The
user can define an arbitrary set of criteria for refinement. Again, stretching, rotation and centering cannot
be applied to the ’user’ area.
COMPONENTS
111
#AMRLEVELS command
#AMRLEVELS
0
99
MinBlockLevel
MaxBlockLevel
Set the minimum/maximum levels that can be affected by AMR. The usage is as follows:
MinBlockLevel .ge.0 Cells can be coarsened up to the listed level but not
further.
MinBlockLevel .lt.0 The current grid is ‘‘frozen’’ for coarsening such that
blocks are not allowed to be coarsened to a size
larger than their current one.
MaxBlockLevel .ge.0 Any cell at a level greater than or equal to
MaxBlockLevel is unaffected by AMR (cannot be coarsened
or refined).
MaxBlockLevel .lt.0 The current grid is ‘‘frozen’’ for refinement such that
blocks are not allowed to be refined to a size
smaller than their current one.
This command has no effect when DoAutoRefine is .false. in the #AMR command.
Note that the user can set either #AMRLEVELS or #AMRRESOLUTION but not both. If both are
set, the final one in the session will set the values for AMR.
#AMRRESOLUTION command
#AMRRESOLUTION
0.
99999.
DxCellMin
DxCellMax
Serves the same function as AMRLEVELS. The DxCellMin and DxCellMmax parameters are converted into
MinBlockLevel and MaxBlockLevel when they are read. Note that MinBlockLevel corresponds to DxCellMax
and MaxBlockLevel corresponds to DxCellMin. See details above.
This command has no effect when DoAutoRefine is .false. in the #AMR command.
Note that the user can set either #AMRLEVELS or #AMRRESOLUTION but not both. If both are
set, the final one in the session will set the values for AMR.
#DOAMR command
#DOAMR
T
1
-1.0
T
DoAmr (the rest is only read if true)
DnAmr
DtAmr
IsStrictAmr
DoAmr is telling if you do AMR based on geometrical description or AMR criteria decided during the
simulation every DnAmr step or DtAmr intervals. NOTE: DtAmr is not implemented by 7 Aug 2011. For
both DtAmr and DnAmr negative numbers will be ignored. If IsStrictAmr is true, we demand that the
number of cells indicated by criteria or percentage should be refined or coarsened, otherwise the code stops.
If IsStrictAmr is false, the code will continue with the maximum of available blocks.
For pure geometry based AMR the IsStrictAmr=F will causes the code to skip the complete AMR if
there are not enough blocsk.
Default is DoAmr false and IsStrictAmr true.
112
#AMRLIMIT command
#AMRLIMIT
40.
30.
999999
1e-8
PercentCoarsen
PercentRefine
MaxBlockAll
DiffCriteriaLevel
Setting up percentage refinement and coarsening using the criteria given by AMRCRITERIA or AMRCRITERIALEVEL. MaxBlockAll set max for total number of blocks if both nProc and MaxBlock are set.
DiffCriteriaLevel give the deviation of the criteria that should have the same AMR treatment.
#AMR command
#AMR
2001
T
0.
0.
99999
DnRefine
DoAutoRefine
PercentCoarsen
PercentRefine
MaxTotalBlocks
!
!
!
!
read
read
read
read
if
if
if
if
DnRefine is positive
DoAutoRefine is true
This command is kept for backwards compatibility. The #DOAMR and #AMRLIMIT commands offer more
control.
The DnRefine parameter determines the frequency of adaptive mesh refinements in terms of total steps
nStep.
When DoAutoRefine is false, the grid is refined by one more level based on the areas and resolutions
defined by the #GRIDLEVEL and #GRIDRESOLUTION commands. If the number of blocks is not
sufficient for this pre-specified refinement, the code stops with an error.
When DoAutoRefine is true, the grid is refined or coarsened based on the criteria given in the #AMRCRITERIA command. The number of blocks to be refined or coarsened are determined by the PercentRefine
and PercentCoarsen parameters. These percentages are approximate only, because the constraints of the
block adaptive grid may result in more or fewer blocks than prescribed. The total number of blocks will
not exceed the smaller of the MaxTotalBlocks parameter and the total number of blocks available on all the
PE-s (which is determined by the number of PE-s and the MaxBlocks parameter in ModSize.f90).
Default for DnRefine is -1, i.e. no run time refinement.
#AMRCRITERIA command
#AMRCRITERIA
3
gradP
0.2
0.8
user
0.5
0.5
Transient
Rho_dot
T
0.00E+00
2.56E+02
0.00E+00
5.00E-01
nRefineCrit (1 to3)
TypeRefine
CoarsenLimit
RefineLimit
TypeRefine
CoarsenLimit
RefineLimit
TypeRefine
TypeTransient ! Only
UseSunEarth
! Only
xEarth
! Only
yEarth
! Only
zEarth
! Only
InvD2Ray
! Only
if
if
if
if
if
if
’Transient’ or ’transient’
’Transient’
UseSunEarth
UseSunEarth
UseSunEarth
UseSunEarth
COMPONENTS
113
Note: ”#AMRCRITERIALEVEL” gives even more control.
This command defines the criteria to select blocks for refinement or coarsening when the #AMR command
is used with DoAutoRefine=T parameter. Up to 3 criteria can be used. Refinement is done if ANY of the
criteria demand it, and the block can be refined (a block cannot be refined if the refinement level would
exceed the maximum level or too many blocks would be created.
Coarsening is done if ALL the criteria allow it and the block can be coarsened (a block cannot be
coarsened if the block level is already at the minimum level, or too many blocks would be coarsened).
The CoarsenLimit and RefineLimit parameters set the coarsening and refinement thresholds for the
NORMALIZED (divided by the largest value) criteria. When the BATL library is not used the criteria are
sorted by their value and a certain per cent of the blocks with the largest/lowest criteria get refined/coarsened,
as determined by the PercentCoarsen and PercentRefine parameters of the #AMR command.
The default settings currently depend on the component used, but it is best to set the criteria explicitly
if the #AMR command is used with DoAutoRefine=T, because the defaults may change, and they are not
optimal for most applications.
If nRefineCrit is set to zero, the blocks are not ordered. This can be used to refine or coarsen all the
blocks limited by the minimum and maximum levels only (see commands #AMRLEVELS and #AMRRESOLUTION). If nRefineCrit is 1, 2, or 3 then the criteria can be chosen from the following list:
’gradT’
’gradP’
’gradlogrho’
’gradlogP’
’gradE’
’curlV’,’curlU’
’curlB’
’divU’, ’divV’
’divB’
’Rcurrents’
’user’
-
gradient of temperature
gradient of pressure
gradient of log(rho)
gradient of log(P)
gradient of electric field magnitude
magnitude of curl of velocity
magnitude of current
divergence of velocity
div B
refinement near Rcurrents value
criteria defined in the user module
All the names can also be spelled with all small case letters.
The possible choices for TypeTransient:
’P_dot’
’T_dot’
’Rho_dot’
’RhoU_dot’
’B_dot’
’Rho_2nd_1’
’Rho_2nd_2’
Also, (xEarth,yEarth,zEarth) are the coordinates of the Earth. InvD2Ray is a factor that defines how close
to the ray Sun-Earth to refine the grid. Note that the AMR occurs in a cylinder around the ray. Example
for InvD2Ray =
1 - refine_profile = 0.3679 at distance Rsun/10 from the ray
#AMRCRITERIALEVEL command
#AMRCRITERIALEVEL
114
4
J2 +tail -nearbody
0.1
0.75
1
J2 +teail -nearbody
1.0
2.0
2
Level
2
3
dx +nearbody
0.5
0.25
error Bx -nearbody
0.025
0.1
2
transient P_dot
1.0
2.0
1
1.0e-2
T
0.00E+00
2.56E+02
0.00E+00
5.00E-01
nCriteria
TypeCriteria
CoarsenLimit
RefineLimit
MaxLevel
TypeCriteria
CoarsenLimit
RefineLimit
MaxLevel
TypeCriteria
RefineTo
CoursenFrom
TypeCriteria
RefineTo
CoursenFrom
TypeCriteria
CoarsenLimit
RefineLimit
MaxLevel
TypeCriteria
CoarsenLimit
RefineLimit
MaxLevel
SmallError
! Only
UseSunEarth
! Only
xEarth
! Only
yEarth
! Only
zEarth
! Only
InvD2Ray
! Only
if
if
if
if
if
if
there are any ’error’ crit
there are any ’transient’ crit
UseSunEarth is true
UseSunEarth is true
UseSunEarth is true
UseSunEarth is true
The #AMRCRITERIALEVEL or #AMRCRITERIARESOLUTION command defines the criteria to select
blocks for refinement or coarsening when the #DOAMR command is used with DoAmr=T parameter. In
one seesion youu can only have one #AMRCRITERIALEVE or #AMRCRITERIARESOLUTION. #AMRCRITERIARESOLUTION is equvilent to #AMRCRITERIALEVE but works on cell resolution (dx) instead
of levels.
The number of criteria is given by the nCriteria parameter. Up to 3 different types of criteria (given by
TypeCriteria) can be used. But there can be multiple criteria for the same TypeCriteria.
The various criteria types define a positive real number for every grid block. This number is compared
with the CoarsenLimit and RefineLimit values. The MaxLevel parameter defines the maximum grid level to
which a given criterion can refine to.
Refinement is done if ANY of the criteria demand it, and the block can be refined. A block cannot be
refined if the refinement level would exceed the maximum grid level or too many blocks would be created.
Coarsening is done if ALL the criteria allow it and the block can be coarsened. A block cannot be
coarsened if the block level is already at the minimum level or it has a neighbor block that is and remains
finer.
TypeCriteria can be chosen from the following list:
’gradT’
’gradP’
’gradlogrho’
’gradlogP’
’gradE’
-
gradient
gradient
gradient
gradient
gradient
of
of
of
of
of
temperature
pressure
log(rho)
log(P)
electric field magnitude
COMPONENTS
’curlV’,’curlU’
’curlB’
’J2’
’divU’, ’divV’
’divB’
’Rcurrents’
’user’
’dx’
’Level’
-
115
magnitude of curl of velocity
magnitude of current
square of current
divergence of velocity
div B
refinement near Rcurrents value
criteria defined in the user module
refinment based on max dx in a block
refinment based on the level of a block
For TypeRefine ”transient TypeTransient” there are the following posibileties for TypeTransient:
’P_dot’
’T_dot’
’Rho_dot’
’RhoU_dot’
’B_dot’
’Rho_2nd_1’
’Rho_2nd_2’
’meanUB’
-
time
time
time
time
time
derivative
derivative
derivative
derivative
derivative
of
of
of
of
of
pressure
temperature
density
momentum
magnetic field
After the Typcriteria we can define which area we want the criteria to act on, minus(-) exclude the area
to be evaluated and positiv(+) tell that a criteria will only evaluated in that area. If you start with a negativ
area, its asumed that you want the criteria to act upon all areas but the negative one.The areas can be
list of multiple areas. The ares is defined by the #AMRREGION comand. If no area is spesified all of the
simulation domain is asumed (all).
The UseSunEarth logical is only read if there are any ”transient” type criteria. If UseSunEarth is set
to true then the xEarth, yEarth, zEarth parameters are read, and these define the coordinates of the Earth
in the heliocentric coordinate system. The InvD2Ray parameter is a factor that defines how close to the
Sun-Earth line the grid is refined. Note that the AMR occurs in a cylinder around the ray.
For TypeRefine ”error StateVarName” the criteria is a numerical error estimate for the state varable
StateVarName. The error estimation is based on the second and first derivatives:
E
=
d^2 U
------dx^2
---------------------------------------1
dU
SmallError
--- ------ + ---------- *U + Epsilon
DX
dx
DX^2
The SmallError parameter gives a relative error with respect to the mean value of the state variable.
The default setting is nCriteria = 0. This can be used to refine or coarsen all the blocks limited by the
minimum and maximum levels only (see commands #AMRLEVELS and #AMRRESOLUTION).
5.2.13
Scheme parameters
#SCHEME command
#SCHEME
4
Rusanov
1.2
nOrder (1, 2, 4 or 5)
TypeFlux
LimiterBeta ! Only read if TypeLimiter is NOT ’minmod’
116
The nOrder parameter determines the spatial and temporal accuracy of the scheme. The spatially first
order scheme uses a one-stage time integration, while the spatially second order MUSCL scheme either uses
an explicit two-stage Runge-Kutta or an implicit three-level BDF2 time discretization. The 4th order finite
volume scheme (FIVOL4) uses the classical 4th order Runge-Kutta scheme for time integration. The spatially
5th order MP5 scheme uses the 3rd order Runge-Kutta scheme. Note that the time discretization scheme
can be modified with the #TIMESTEPPING, #RUNGEKUTTA or #RK commands after the #SCHEME
command. Possible values for TypeFlux:
’Rusanov’
’Linde’
’Sokolov’
’Roe’
’RoeOld’
’HLLD’
’Godunov’
’Simple’
-
Rusanov or Lax-Friedrichs flux
Linde’s HLLEL flux
Sokolov’s Local Artificial Wind flux
Roe’s approximate Riemann flux (new)
Roe’s approximate Riemann flux (old)
Miyoshi and Kusano’s HLLD flux
Godunov flux with exact Riemann solver
Physical fluxes are applied without any Riemann solver.
The Godunov flux is only implemented for (multi-material) hydrodynamics. The Roe and HLLD schemes are
implemented for ideal MHD only (single fluid, non-relativistic, no Hall term). The new and old Roe schemes
differ in some details of the algorithm, the new Roe scheme is somewhat more robust in magnetospheric
applications. The Simple solver is for testing purposes only at this point.
No limiter is used by the 1st order scheme. The second order TVD scheme uses a TVD limiter everywhere.
The FIVOL4 and MP5 schemes use the second order TVD scheme at resolution changes, but in the uniform
part of the grid they use their own limiter. Possible values for TypeLimiter:
’minmod’
’mc’
’mc3’
’beta’
-
minmod limiter is the most robust and diffusive limiter
monotonized central limiter with a beta parameter
Koren’s third order limiter with a beta parameter
beta limiter is less robust than the mc limiter for
the same beta value
Possible values for LimiterBeta (for limiters othen than minmod) are between 1.0 and 2.0:
LimiterBeta
LimiterBeta
LimiterBeta
LimiterBeta
=
=
=
=
1.0
1.5
1.2
2.0
is the same as the minmod limiter
is a typical value for the mc/mc3 limiters
is the recommended value for the beta limiter
for the beta limiter is the same as the superbee limiter
IMPORTANT: the number of ghost cell layers have to be sufficient for the selected scheme! The 1st and
2nd order schemes work with 2 layers. The MP5 scheme needs 3 layers. The FIVOL4 scheme needs 3 to 5
layers (see the #SCHEME4 command).
The default is the second order Rusanov scheme with the minmod limiter.
#SCHEME4 command
#SCHEME4
F
F
F
UseVolumeIntegral4
UseFaceIntegral4
UseLimiter4
This command has to be used in the first session, because it determines the size of various arrays that are
allocated at the beginning of the run. The command reads three parameters used by the 4th order finite
volume scheme FIVOL4, which can be activated in any session by setting nOrder=4 in the #SCHEME
command.
COMPONENTS
117
If UseVolumeIntegral4 is true then the cell averaged variables are converted into cell centered variables
and back as needed. This requires an extra ghost cell layer. Currently this option only works for Cartesian
grids and with cell based boundary conditions (no inner body).
If UseFaceIntegral4 is true, then the face averaged face values and face fluxes are converted to face
centered variables and back as needed. This option can only be used on 2D and 3D Cartesian grids and with
cell based boundary conditions (no inner body).
If UseLimiter4 is true then the truely 4th order limiter is used, however this requires an extra ghost cell
layer, and the improvement is marginal at best.
If all 3 logicals are true and nOrder is set to 4 in the #SCHEME command then the fully 4th order accurate
FIVOL4 scheme is used. This, however, requires extra ghost cell layers and extra face flux calculations. In
practice the fully 4th order FIVOL4 scheme is much more expensive but not much more accurate than the
simplified shceme with all three logicals set to false.
IMPORTANT: the number of ghost cell layers set with Config.pl -ng=.. has to be sufficient for the
selected scheme! The FIVOL4 scheme needs 3 to 5 layers. The minimum 3 layers are needed if both
UseVolumeIntegral4 and UseLimiter4 are false. If one of these logicals is true, 4 layers are required. If both
are true then the maximum 5 ghost cells layers are needed.
The default is false for all 3 logicals.
#FLATTENING command
#FLATTENING
T
F
0.33
0.75
0.85
UseFlattening (rest of parameters are read if true)
UseDuFlat
FlatDelta
FlatRatioMin
FlatRatioMax
This command controls the parameters of Phil Collela’s flattening algorithm used by the 4th order scheme
(nOrder=4 in the #SCHEME command). The flattening scheme uses a linear combination of the first order
and the 4th order accurate face values. Near strong shocks it switches to the first order scheme, elsewhere
it uses the 4th order accurate face value.
If the UseFlattening parameter is true, the flattening scheme is switched on.
The UseDuFlat parameter determines if the velocity gradient is used as a condition for flattening. The
”official” algorithm uses this check, in some cases it seems to be better not to use it, and it is not clear if
there is any advantage using it.
The FlatDelta parameter determines the threshold for the relative pressure jump. If pR and pL are
the pressures in the i+1 and i-1 cells, then the flattening is applied only if abs(pR - pL) is greater than
FlatDelta*min(pR, pL).
The FlatRatioMin parameter determines the lower threshold for the shock width ratio = abs(p(i+2) p(i-2))/abs(pR - pL). If the ratio is less than FlatRatioMin, no flattening is applied.
The FlatRatioMax parameter determines the upper threshold for the shock width ratio. If the ratio
is above FlatRatioMax, the first order scheme is used. If the ratio is between the FlatRatioMin and FlatRatioMax values, the 1st order and 4th order face values are linearly combined with a weight (Ratio FlatRatioMin)/(FlatRatioMax - FlatRatioMin).
In the actual scheme, the flattening parameters are calculated for all dimensions and all cells first, and
then the minimum is taken over a 3 point stencil in each dimension, and then a minimum is taken over the
dimensions. See Miller and Colella 2005, APJS, 160, 199.
The default values are shown in the example.
#NONCONSERVATIVE command
#NONCONSERVATIVE
118
T
UseNonConservative
For Earth the default is using non-conservative equations (close to the body).
#CONSERVATIVECRITERIA command
#CONSERVATIVECRITERIA
3
nConservCrit
r
TypeConservCrit
6.
rConserv
parabola
TypeConservCrit
6.
xParabolaConserv
36.
yParabolaConserv
p
TypeConservCrit
0.05
pCoeffConserv
GradP
TypeConservCrit
0.1
GradPCoeffConserv
! read if TypeConservCrit is ’r’
! read if TypeConservCrit is ’parabola’
! read if TypeConservCrit is ’parabola’
! read if TypeConservCrit is ’p’
! read if TypeConservCrit is ’GradP’
Select the parts of the grid where the conservative vs. non-conservative schemes are applied. The number
of criteria is arbitrary, although there is no point applying the same criterion more than once.
If no criteria is used, the whole domain will use conservative or non-conservative equations depending on
UseNonConservative set in command #NONCONSERVATIVE.
The physics based conservative criteria (’p’ and ’GradP’) select cells which use the non-conservative
scheme if ALL of them are true:
’p’
’GradP’
- the pressure is smaller than fraction pCoeffConserv of the energy
- the relative gradient of pressure is less than GradPCoeffConserv
The geometry based criteria are applied after the physics based criteria (if any) and they select the nonconservative scheme if ANY of them is true:
’r’
- radial distance of the cell is less than rConserv
’parabola’ - x less than xParabolaConserv - (y**2+z**2)/yParabolaConserv
For the GM component with a planet the default values are nConservCrit = 1 with TypeConservCrit = ’r’
and rConserv=6. If there is no planet (PLANET=”NONE”) or for the EE, SC, IH and OH components,
the default is to have no conservative criteria: nConservCrit = 0.
#UPDATECHECK command
#UPDATECHECK
T
40.
400.
40.
400.
UseUpdateCheck
RhoMinPercent
RhoMaxPercent
pMinPercent
pMaxPercent
Note that the ”update-check” algorithm controlled by this command does not work together with high order
Runge-Kutta schemes (see the #RK command) because the RK method combines the intermediate stages for
the final update. Use the time step control method (see #TIMESTEPCONTROL and related commands) in
combination with RK time stepping. In general, for time accurate simulations the time step control method
has more flexibility and it is likely to be more effective and efficient than this update-check method.
If UseUpdateCheck is true, the local or global time step will be adjusted so that the density and pressure
does not decrease or increase by more than the given percentages in a single timestep. For example with the
COMPONENTS
119
default settings, if density is 1.0 initially and it would change below 0.6 or above 5.0, the (local) time step
will be reduced so that the final density remains inside the prescribed bounds.
Default values are shown for the non-Runge-Kutta time integration schemes. For Runge-Kutta schemes
UseUpdateCheck is forced to be false.
#CONTROLTIMESTEP command
#CONTROLTIMESTEP
T
UseTimeStepControl
#TIMESTEPCONTROL
T
UseTimeStepControl
Setting UseTimeStepControl=T switches on the new time step control scheme that controls the time step
based on the relative change in selected set of variables. The variables can be selected with the #CONTROLVAR command. The various thresholds in the relative increase and decrease of these variables can be
set by the #CONTROLINCREASE and #CONTROLDECREASE commands. The #CONTROLFACTOR
command determines how much the time step changes when the various thresholds are reached.
Currently this scheme only works in time accurate mode.
The default is UseTimeStepControl false.
#CONTROLINIT command
#CONTROLINIT
0.01
TimeStepControlInit
Set the initial reduction factor applied to the time step or Cfl number. The factor should be positive and it
should typically not more than 1.
The default value is 1, i.e. there is no initial reduction applied.
#CONTROLVAR command
#CONTROLVAR
rho p
NameVarControl
The NameVarControl string contains the list of variables that are monitored to control the time step. The
variable names, separated by spaces, should be chosen from the NameVar V(1:nVar) array in the equation
module. The names are not case sensitive. Typically only the positive variables, like density and pressure,
should be monitored.
Note that this command is only effective if the time step control is switched on by th #CONTROLTIMESTEP
command.
The default is the control density and pressure as shown by the example.
#CONTROLDECREASE command
#CONTROLDECREASE
0.3
0.6
0.8
RejectStepLevel
ReduceStepLevel
IncreaseStepLevel
This command sets thresholds for the relative decrease in the control variables in the time step control
scheme. The relative decrease is defined as D = min(VarNew/VarOld) where the minimum is taken over all
cells in the computational domain and all the control variables.
120
If D is below the RejectStepLevel threshold, the time step is rejected, and it will be redone with a smaller
time step/CFL number.
If D is above RejectStepLevel but below the ReduceStepLevel then the time step is accepted, but the
next time step/CFL number will be reduced.
If D is above RejectStepLevel but below IncreaseStepLevel, the time step is accepted and there is no
change in the time step/CFL number.
If is above the IncreaseStepLevel threshold, then the time step/CFL number is increased, but it will
never exceed the original value.
This command is only effective if the time step control is switched on with the #CONTROLTIMESTEP
command. The control variables are selected by the #CONTROLVAR command, the factors that change
the time step or the CFL number are set by the #CONTROLFACTOR command.
#CONTROLINCREASE command
#CONTROLINCREASE
3.0
1.5
1.2
RejectStepLevel
ReduceStepLevel
IncreaseStepLevel
This command sets thresholds for the relative increase in the control variables in the time step control
scheme. The relative increase is defined as I = max(VarNew/VarOld) where the maximum is taken over all
cells in the computational domain and all the control variables.
If I is above the RejectStepLevel threshold, the time step is rejected, and it will be redone with a smaller
time step/CFL number.
If I is below RejectStepLevel but above the ReduceStepLevel then the time step is accepted, but the next
time step/CFL number will be reduced.
If I is below ReduceStepLevel but above IncreaseStepLevel, the time step is accepted and there is no
change in the time step/CFL number.
If I is below the IncreaseStepLevel threshold, then the time step/CFL number is increased, but it will
never exceed the original value.
command. The control variables are selected by the #CONTROLVAR command, and the factors that change
the time step or the CFL number are set by the #CONTROLFACTOR command.
#CONTROLFACTOR command
#CONTROLFACTOR
0.5
0.95
1.05
RejectStepFactor
ReduceStepFactor
IncreaseStepFactor
This command sets how much the time step/CFL number is changed by the time step control scheme.
If the update is rejected then the next time step/CFL factor is multiplied by RejectStepFactor.
If the update is accepted but the time step needs to be reduced, then the next time step/CFL factor is
multiplied by ReduceStepFactor.
If the update is accepted and the relative changes in the control variables are within the range determined
by the IncreaseStepLevel parameters of the #CONTROLDECREASE and #CONTROLINCREASE commands, then the time step/CFL number is multiplied by IncreaseStepFactor, but the original values cannot
be exceeded.
COMPONENTS
121
command. The control variables are selected by the #CONTROLVAR command.
#MULTISPECIES command
#MULTISPECIES
T
1.0
DoReplaceDensity
SpeciesPercentCheck
This command is only useful for multispecies equations. If the DoReplaceDensity is true, the total density is
replaced with the sum of the species densities. The SpeciesPercentCheck parameter determines if a certain
species density should or should not be checked for large changes. If SpeciesPercentCheck is 0, all species
are checked, if it is 1, then only species with densities reaching or exceeding 1 per cent are checked for large
changes (see the #UPDATECHECK command).
#NEUTRALFLUID command
#NEUTRALFLUID
F
Linde
DoConserveNeutrals
TypeFluxNeutral (default, Rusanov or Linde)
If DoConserveNeutrals is false, the pressure equation is used for neutrals even where the energy equation
is used for the ions. If DoConserveNeutrals is true, the neutrals do the same as ions. The neutral fluid
uses the flux function set by TypeFluxNeutral. The default is to use the same as the ion fluid if possible.
Currently only the Rusanov and Linde schemes are available for the neutrals. If the ion fluid uses any other
flux function, the neutrals will use the Linde scheme.
Default values are DoConserveNeutrals=T and TypeFluxNeutral=default.
#MULTIION command
#MULTIION
0.0001
1e-10
T
3.0
30.0
LowDensityRatio
LowPressureRatio
DoRestrictMultiIon
MachNumberMultiIon (read if DoRestrictMultiIon)
ParabolaWidthMultiIon (read if DoRestrictMultiIon)
This command is useful for multiion simulations. Since the numerical schemes cannot handle zero densities or
temperatures, it is necessary to have all the ions present in the whole computational domain. The parameters
of this command determine how the code behaves in regions where one of the ions is dominant.
The LowDensityRatio parameter determines the relative density of the minor ion fluids in regions where
essentially only one ion fluid is present.
The LowPressureRatio parameter is used to keep the pressures of the minor fluids above a fraction of
the total pressure.
If DoRestrictMultiIon is true, the first ion fluid is set to be dominant in the region determined by the
MachNumberMultiIon and ParabolaWidthMultiIon parameters. The current parametrization tries to find
the region occupied by the solar wind outside the bow shock. The region is identified as the velocity being
negative and the hydrodynamic Mach number in the X direction is being larger than MachNumberMultiIon
and the point being outside the paraboloid determined by the y 2 + z 2 + x ∗ P arabolaW idthM ultiIon = 0
equation.
The defaults are LowDensityRatio=0.0001, LowPressureRatio=1e-10, and DoRestrictMultiIon=false.
122
#MHDIONS command
#MHDIONS
F
T
DoAddRho
DoAddRhoU
This command determines how the total MHD fluid and the individual ion fluids are reconciled after each
time step. If both DoAddRho and DoAddRhoU are true, then the density and momentum of individual ion
fluids are added up and the MHD solution is overwritten. This is mostly useful for testing purposes, because
in this case it is better not to solve for the total fluid at all.
If DoAddRho is false then the density obtained by the MHD scheme is used to adjust the densities of
the ion fluids. They are scaled such that their sum matches the total fluid.
If DoAddRhoU is false, the same scaling is done for the three components of the ion momenta as long as
all ion velocities have the same signs! If the signs are mixed, the total momentum is replaced by the sum of
the ion momenta. The procedure is done separately for the X, Y and Z components of the momenta.
#MULTIIONSTATE command
#MULTIIONSTATE
T
F
UseSingleIonVelocity
UseSingleIonTemperature
This command allows to enforce uniform ion velocities and/or temperatures in multi-ion simulations. When
both logicals are true, the multi-ion simulation should become equivalient with a singlefluid multi-species
simulation. This is useful for testing.
is true, the ion velocities are set to the velocity of the total fluid u =
P
P When UseSingleIonVelocity
s(ρ su s)/
sρ s as if there was an infinitely strong friction force between the ion fluids.
WhenPUseSingleIonTemperature
is true, the ion temperatures are set to the temperature of the total fluid
P
sp s/
s(ρ s/M s) as if there was an infinitely fast energy exchange between the ion fluids.
k BT =
Default values are false for both parameters.
#COLLISION command
#COLLISION
-1.0
1.0e3
100.0
2
CollisionCoefDim
TauCutOffDim [s]
uCutOffDim [km/s] read if TauCutOffDim positive
nPowerCutOff read if TauCutOffDim positive
This command is only useful for multiion simulations. It determines the parameters for physical collisions
and artificial friction.
If the CollisionCoefDim parameter is negative the ion-ion collisions are neglected. This is typically a very
good approximation in the low density plasma of space physics. The collisions may be important in the ionosphere of unmagnetized planets. For positive value the collision rate is taken to be CollisionCoefDim∗n/T 1.5
where T is the temperature measured in Kelvin, n is the number density measured in /cm−3 and the resulting
rate is in units of 1/s. Note that this feature is implemented but it has not been tested yet.
If the TauCutOffDim parameter is negative the relative velocity of the ion fluids (especially parallel to
the magnetic field) can become very large. In reality the streaming instability limits the relative speed.
Instead of trying to model the effect of the streaming instability, in the current implementation we apply a
simple friction term. If TauCutOffDim is positive, it gives the time rate of the friction.
The uCutOffDim determines the speed difference (in input units, typically km/s), at which the friction
term becomes large. Setting uCutoffDim = -1.0 switches to a physics based cut-off velocity which is defined
COMPONENTS
123
as B/sqrt[rho1*rho2/(rho1+rho2)] where B is the magnetic field magnitude, and rho1 and rho2 are the
densities of the two ion fluids in normalized units.
The nPowerCutOff is the exponent applied to the square of the velocity difference. The friction force is
applied between all pairs of ion fluids, and it is
(1/T auCutOf f Dim) min(ρ i, ρ j)(u j − u i)[(u i − u j)2 /uCutOf f Dim2]nP owerCutOf f .
where i and j are the indexes of two different ion fluids and u is the velocity vector. Note that the friction
force is proportional to the smaller of the two densities so that the acceleration of the minor ion fluid is
independent of the density of the major ion fluid.
The default values are CollisionCoefDim=-1 and TauCutOffDim=-1, ie. neither collision, nor friction are
applied.
#MESSAGEPASS command
#MESSAGEPASS
all
TypeMessagePass
Possible values for TypeMessagePass:
’all’
’opt’
- fill in all ghost cells (corners, edges and faces)
- fill in face ghost cells only
The default value is ’all’, because there are many schemes that require the ghost cells at the edges and corners
(viscosity, resistivity, Hall MHD, radiative diffusion, accurate resolution change algorithm, etc.). These will
automatically change to the ’all’ option even if the user sets ”opt”, which is only recommended for advanced
users.
#RESOLUTIONCHANGE command
#RESOLUTIONCHANGE
F
UseAccurateResChange
T
UseTvdResChange
2.0
BetaLimiterResChange
2
nFaceLimiterResChange
If UseAccurateResChange is true, then a second order accurate, upwind and oscillation free scheme is used
at the resolution changes. It requires message passing edge ghost cells (this is switched on automatically)
which may effect the performance slightly.
If UseTvdResChange is true, then an almost second order and partially downwinded TVD limited scheme
is used at the resolution changes. This scheme does not require message passing of the edge ghost cells. Only
one of UseAccurateResChange and UseTvdResChange can be true.
If BetaLimiterResChange is set to a value smaller than the BetaLimiter parameter in the #SCHEME command, then the limiter will use this BetaLimiterResChange parameter at and near grid resolution changes.
The smallest value is 1.0 that corresponds to the minmod limiter, the maximum value is 2.0 that means that
the same limiter is applied at the resolution change as anywhere else. Recommended values are 1.0 to 1.2
combined with BetaLimiter=1.5 in the #SCHEME command.
The nFaceLimiterResChange determines how many faces around the resolution change itself are affected.
If nFaceLimiterResChange is 0, the limiter using BetaLimiterResChange is applied at the face at the resolution change itself. If nFaceLimiterResChange is 1 or 2, the limiter is applied at 3 or 5 faces altogether. The
recommended value is 2.
Default values are shown, ie. the TVD reschange algorithm is used, and the limiter applied at the
resolution changes is the same as everywhere else, because BetaLimiterResChange is set to 2.
124
#RESCHANGE command
#RESCHANGE
T
UseAccurateResChange
This command is kept for backwards compatibility. See description at the #RESOLUTIONCHANGE command.
#TVDRESCHANGE command
#TVDRESCHANGE
T
UseTvdResChange
This command is kept for backwards compatibility. See description at the #RESOLUTIONCHANGE command.
#LIMITER command
#LIMITER
F
F
T
Xe Be Pl
UseLogRhoLimiter
UseLogPLimiter
UseRhoRatioLimiter
NameVarLimitRatio (read if UseRhoRatioLimiter)
The spatially second order scheme uses a limited reconstruction to obtain face values from the cell center
values. The order of the scheme and the type of the limiter can be set in the #SCHEME command. This
command provides additional options to the limiting procedure.
If UseLogRhoLimiter is true, the logarithm of the density is limited instead of the density itself. This
can reduce numerical diffusion in regions where the density changes exponentially with distance (e.g. in the
solar corona).
If UseLogPLimiter is true, the logarithm of pressure is limited instead of the pressure itself.
If UseRhoRatioLimiter is true, then parameter NameVarLimitRatio is read and the variables listed in
NameVarLimitRatio (the variable names are defined in ModEquation) are divided by the total density before
the limiter is applied and then multiplied back by the density at the face after the limiting is completed.
This modification is useful for the high energy density simulations of the CRASH project for the level set
functions or for the internal energy associated with ionization.
Default values are false for all variables, which results in the limited reconstruction procedure directly
applied to the original primitive variables (velocity and pressure).
#CLIMIT command
#CLIMIT
T
3000.0
6.0
UseClimit (rest of parameters are read if true)
ClimitDim [km/s]
rClimit
If UseClimit is true, the wave speeds used in the numerical diffusive fluxes are limited by the value of
ClimitDim (in I/O units, typically km/s) within the sphere of radius rClimit (typically in units of planetery
radii). This scheme cannot be used with a fully explicit time integration, because it will not be stable! One
should use the fully or part implicit scheme (see the #IMPLICIT command). In contrast with the Boris
correction (see the #BORIS command), this scheme is fully consistent with the governing equations in time
accurate mode as well. It can be combined with the Roe scheme too unlike the Boris correction. The limiting
scheme cannot be combined with the HLLD scheme (neither can be the Boris correction at this point).
COMPONENTS
125
A reasonable set of values are shown above. Much smaller velocity limit will result in slow convergence
for the implicit solver. The radial limit is not very crucial, but it should be set large enough to cover the
whole region where the wave speed may exceed it and the reduced diffusion is important.
Default is UseClimit false.
#BORIS command
#BORIS
T
1.0
UseBorisCorrection
BorisClightFactor !Only if UseBorisCorrection is true
Default is boris correction=.false. Use semi-relativistic MHD equations with speed of light reduced by the
BorisClightFactor. Set BorisClightFactor=1.0 for true semi-relativistic MHD. Gives the same steady state
as normal MHD analytically, but there can be differences due to discretization errors. You can use either
Boris or BorisSimple but not both.
#BORISSIMPLE command
#BORISSIMPLE
T
0.05
UseBorisSimple
BorisClightFactor !Only if UseBorisSimple is true
Default is UseBorisSimple=.false. Use simplified semi-relativistic MHD with speed of light reduced by the
BorisClightFactor. This is only useful with BorisClightFactor less than 1. Should give the same steady state
as normal MHD, but there can be a difference due to discretization errors. You can use either Boris or
BorisSimple but not both.
#USEB0 command
#USEB0
F
UseB0
If UseB0 is true, the magnetic field is split into an analytic B0 and a numerical B1 field. The B0 field may
be a (rotating) dipole of a planet, or the potentialf field solution for the corona. B1 is not small relative to
B0 in general. The default value depends on the application.
#USECURLB0 command
#USECURLB0
T
2.5
UseCurlB0
rCurrentFreeB0 (read if UseCurlB0 is true)
If UseCurlB0 is true then the B0 field has non-zero curl. The B0 field of planets has zero curl, but the
potential field source surface model (PFSS) for the corona has a finite curl beyond the source surface, where
the field is forced to become radial.
The rCurrentFreeB0 parameter is set to the radius within which the B0 field has no curl (i.e. it is current
free).
The default is UseCurlB0 false.
126
#DIVB command
#DIVB
T
F
F
F
UseDivbSource
UseDivbDiffusion
UseProjection
UseConstrainB
Default values are shown above. If UseProjection is true, all others should be false. If UseConstrainB is
true, all others should be false. At least one of the options should be true unless the hyperbolic cleaning is
used. The hyperbolic cleaning can be combined with UseDivbSource only.
#DIVBSOURCE command
#DIVBSOURCE
T
UseB0Source
Add extra source terms related to the non-zero divergence and curl of B0. Default is true.
#HYPERBOLICDIVB command
#HYPERBOLICDIVB
T
400.0
0.1
UseHyperbolicDivb
SpeedHypDim
HypDecay
This command sets the parameters for hyperbolic/parabolic cleaning. The command (and the hyperbolic
cleaning method) can only be used of there is a hyperbolic scalar named Hyp in the equation module. The
SpeedHypDim parameter sets the propagation speed for div B errors in dimensional units. Do not use a
speed that limits the time step (ie. exceeds the fastest wave speed). The HypDecay parameter is for the
parabolic cleaning. If HypDecay is less than zero, no parabolic cleaning is applied. If it is positive, the
scalar field is modified as Hyp=Hyp*(1-HypDecay) after every update. This corresponds to a point implicit
evaluation of a parabolic diffusion of the Hyp scalar.
Default values are UseHyperbolicDivb true, the speed SpeedHyp is 1.0 in the normalized units, and
HypDecay=0.1.
#PROJECTION command
#PROJECTION
cg
rel
0.1
0.0
50
TypeProjectIter:’cg’ or ’bicgstab’ for iterative scheme
TypeProjectStop:’rel’ or ’max’ error for stop condition
RelativeLimit
AbsoluteLimit
MaxMatvec (upper limit on matrix.vector multipl.)
Default values are shown above.
For symmetric Laplacian matrix TypeProjectIter=’cg’ (Conjugate Gradients) should be used, as it is faster
than BiCGSTAB. In current applications the Laplacian matrix is always symmetric.
The iterative scheme stops when the stopping condition is fulfilled:
COMPONENTS
TypeProjectStop = ’rel’:
stop if ||div B||
<
TypeProjectStop = ’max’ and
stop if max(|div B|) <
TypeProjectStop = ’max’ and
stop if max(|div B|) <
127
RelativeLimit*||div B0||
RelativeLimit is positive:
RelativeLimit*max(|div B0|)
RelativeLimit is negative:
AbsoluteLimit
where ||.|| is the second norm, and B0 is the magnetic field before projection. In words ’rel’ means
that the norm of the error should be decreased by a factor of RelativeLimit, while ’max’ means that the
maximum error should be less than either a fraction of the maximum error in div B0, or less than the
constant AbsoluteLimit.
Finally the iterations stop if the number of matrix vector multiplications exceed MaxMatvec. For the
CG iterative scheme there is 1 matvec per iteration, while for BiCGSTAB there are 2/iteration.
In practice reducing the norm of the error by a factor of 10 to 100 in every iteration works well.
Projection is also used when the scheme switches to constrained transport. It is probably a good idea to
allow many iterations and require an accurate projection, because it is only done once, and the constrained
transport will carry along the remaining errors in div B. An example is
#PROJECTION
cg
rel
0.0001
0.0
500
TypeProjIter
TypeProjStop
RelativeLimit
AbsoluteLimit
MaxMatvec
#CORRECTP command
#CORRECTP
0.01
0.1
pRatioLow
pRatioHigh
The purpose of the correctP subroutine is to remove any discrepancies between pressure stored as the
primitive variable P and the pressure calculated from the total energy E. Such discrepancies can be caused
by the constrained transport scheme and by the projection scheme which modify the magnetic energy. The
algorithm is the following:
Define the rato of thermal and total energies q = eThermal/e and
If
q < pRatioLow
If pRatioLow < q < pRatioHigh
If pratioHigh < q
then E is recalculated from P
then both P and E are modified depending on q
then P is recalculated from E
The second case is a linear interpolation between the first and third cases.
#RAYTRACE command
#RAYTRACE
T
T
0.1
1
UseRaytrace (rest is read if true)
UseAccurateTrace
DtExchangeRay [sec]
DnRaytrace
128
Raytracing (field-line tracing) is needed to couple the GM with the IM or RB components. It can also be
used to create plot files with open-closed field line information. There are two algorithms implemented for
integrating rays and for tracing rays.
By default UseRaytrace oarameter is true if there is magnetic field in the equation module. The parameter
can be set to false to save memory allocation.
If UseAccurateTrace is false (default), the block-wise algorithm is used, which interpolates at block faces.
This algorithm is fast, but less accurate than the other algorithm. If UseAccurateTrace is true, the field
lines are followed all the way. It is more accurate but potentially slower than the other algorithm.
In the accurate tracing algorithms, when the ray exits the domain that belongs to the PE, its information
is sent to the other PE where the ray continues. The information is buffered for sake of efficiency and to
synchronize communication. The frequency of the information exchanges (in terms of CPU seconds) is
given by the DtExchangeRay parameter. This is an optimization parameter for speed. Very small values
of DtExchangeRay result in many exchanges with few rays, while very large values result in infrequent
exchanges thus some PE-s may become idle (no more work to do). The optimal value is problem dependent.
A typically acceptable value is DtExchangeRay = 0.1 seconds (default).
The DnRaytrace parameter contains the minimum number of iterations between two ray tracings. The
default value 1 means that every new step requires a new trace (since the magnetic field is changing). A
larger value implies that the field does not change significantly in that many time steps. The ray tracing is
always redone if the grid changes due to an AMR.
Default values are UseAccurateIntegral = .true. (if there is magnetic field), UseAccurateTrace = .false.,
DtExchangeRay = 0.1 and DnRaytrace=1.
#RAYTRACELIMIT command
#RAYTRACELIMIT
50
RayLengthMax
RayLengthMax provides the maximum length in planet radius for tracing a ray. This avoid tracing extremely
long field lines that are not used later. The default is 100 planet radius.
#IE command
#IE
T
DoTraceIE
DoTraceIE will activate accurate ray tracing on closed fieldlines for coupling with the IE module. If not set,
then only Jr is sent. If set, then Jr as well as 1/B, average rho, and average p on closed fieldlines are passed.
#IECOUPLING command
#IECOUPLING
T
4.0
10.0
UseIonoVelocity (rest of parameters read if true)
rCoupleUiono
TauCoupleUiono
This command sets parameters for a new experimental coupling of the velocity from IE to GM.
The rCoupleUiono paramter determines the radius within which the GM velocity is effected. The TauCoupleUiono parameter determine how fast the GM velocity should be nudged towards the E x B drift plus
corotation.
coupling occurs, but the nudging towards the velocity is done in every GM time step. When GM is not
run in time accurate mode, the orthogonal (to B) velocity is set as
uOrth’ = uOrth + (uIonoOrth - uOrth)/(TauCoupleUiono+1)
COMPONENTS
129
Therefore the larger TauCoupleUiono is the slower the adjustment will be. It takes approximately
2*TauCoupleUiono time steps to get the orthogonal velocity close to what the ionosphere would prescribe.
In time accurate mode, the nudging is based on physical time:
uOrth’ = uOrth + min(1.0, dt/TauCoupleUiono)*(uIonoOrth - uOrth)
where dt is the time step. It takes about 2*TauCoupleUiono seconds to get uOrth close to uIonoOrth.
If the time step dt exceeds TauCoupleIm, uOrth is set in a single step.
By default the coupling is switched off.
#IM command
#IM
20.0
F
TauCoupleIm
DoImSatTracing
Same as command IMCOUPLING, except it only reads the first and second parameters of #IMCOUPLING.
The default value is TauCoupleIm=20.0, which corresponds to typical nudging and DoImSatTrace false.
#MULTIFLUIDIM command
#MULTIFLUIDIM
F
DoMultiFluidIMCoupling
If DoMultiFluidIMCoupling is true, the information exchanged between GM and IM is in multi-fluid mode:
GM gives IM four more variables (density Hp, density Op, pressure Hp, pressure Op) in addition to one-fluid
MHD paramters, and IM passes GM the same four more variables.
The default value is DoMultiFluidIMCoupling = false, MHD variables are exchanged between GM and
IM.
#IMCOUPLING command
#IMCOUPLING
20.0
F
T
F
T
5.0
20.0
100000.0
2.0
20000.0
TauCoupleIm
DoImSatTrace
DoCoupleImPressure
DoCoupleImDensity
DoFixPolarRegion (rest
rFixPolarRegion
PolarTDim [K]
for
PolarTDim [K]
for
read if true)
fluid
fluid
fluid
fluid
1
1
2
2
This command sets various parameters for the GM-IM coupling.
The TauCoupleIm parameter determine how fast the GM pressure p (and possibly density rho) should
be nudged towards the IM pressure pIm (and density dIM). but the nudging towards these values is done in
every GM time step. When GM is not run in time accurate mode, the pressure is set as
p’ = (p*TauCoupleIm + pIm)/(TauCoupleIm+1)
Therefore the larger TauCoupleIm is the slower the adjustment will be. It takes approximately 2*TauCoupleIm time steps to get p close to pIm. In time accurate mode, the nudging is based on physical time:
p’ = p + min(1.0, dt/TauCoupleIm)*(pIm - p)
where dt is the time step. It takes about 2*TauCoupleIm seconds to get p close to pIm. If the time step
dt exceeds TauCoupleIm, p’ = pIm is set in a single step. The default value is TauCoupleIm=20.0, which
corresponds to typical nudging.
130
The DoImSatTrace logical sets whether the IM component receives the locations of the satellites in GM
mapped down along the magnetic field lines. The IM component then can produce satellite output files with
IM data.
The DoCoupleImPressure logical sets whether GM pressure is driven by IM pressure. Default is true,
and it should always be true (except for testing), because pressure is the dominant variable in the IM to GM
coupling.
The DoCoupleImDensity logical sets whether the GM density is driven by IM density. The default value
is false. This is a new feature in the IM-GM coupling, which is not fully tested.
The DoFixPolarRegion logical decides if we try to fix the pressure (and density) values in the open field
line region. The pressure/density tends to diffuse numerically from the closed field line region (nudged by
IM) into the polar region that should not be affected by IM. This can cause unphysically fast outflow from
the polar region. If DoFixPolarRegion is set to true, the pressure (and density) are nudged toward the
values given in the #POLARBOUNDARY command in the open field line region within radius defined by
rFixPolarRegion and where the flow points outward. This is a very new feature that hasn’t been tested in
real runs yet.
If DoFixPolarRegion is true then the following parameters are also read:
The rFixPolarRegion radius (given in planetary radii) sets the outer limit for nudging the pressure
(density) in the open field line region towards the PolarNDim and PolarTDim values. For multi-fluid MHD,
the PolarNDim and PolarTDim parameters are read for each fluid.
The default is to couple the IM pressure only and no fix is applied in the polar region.
5.2.14
Physics parameters
#GAMMA command
#GAMMA
1.6666666667
Gamma
The adiabatic index (ratio of the specific heats for fixed pressure and volume. The default value is 5.0/3.0,
which is valid for monoatomic gas or plasma.
#PLASMA command
#PLASMA
1.0
1.0
0.0
FluidMass [amu]
IonCharge [e]
ElectronTemperatureRatio
For single fluid, single species MHD the FluidMass parameter determines the average mass of ions (and
strongly coupled neutrals) in atomic mass units (amu). This parameter is only used if there are no species
(UseMultiSpecies=.false. in ModEquation). The number density is n=rho/FluidMass. For a pure hydrogen
plasma FluidMass=1.0, while for a mix of 90 per cent hydrogen and 10 per cent helium FluidMass=1.4.
The IonCharge parameter gives the average ion charge in units of the proton charge. For a fully ionized
hydrogen plasma AverageIonCharge=1.0, for a fully ionized helium plasma IonCharge=2.0, while for a 10
per cent ionized hydrogene plasma IonCharge=0.1.
For multifluid MHD/HD the command reads the mass of all fluids (ions and neutrals), and the charges
of all ion fluids. For example for proton and double ionized helium and neutral oxygen molecule fluids:
#PLASMA
1.0
4.0
32.0
1.0
FluidMass
FluidMass
FluidMass
IonCharge
H+ [amu]
He++ [amu]
O2 [amu]
H+ [e]
COMPONENTS
2.0
0.2
131
IonCharge He++ [e]
ElectronTemperatureRatio
The ElectronTemperatureRatio determines the ratio of electron and ion temperatures. The ion temperature Te = T * ElectronTemperatureRatio where T is the ion temperature. The total pressure p = n*k*T
+ ne*k*Te, so T = p/(n*k+ne*k*ElectronTemperatureRatio). If the electrons and ions are in temperature equilibrium, ElectronTemperatureRatio=1.0. For multi-fluid MHD the ElectronTemperatureRatio is
interpreted as electron pressure ratio. The electron pressure is taken as pE = ElectronTemperatureRatio*sum(pIon I). Note that one can also solve the electron pressure equation if ’Pe’ is present in the equation
module.
In a real plasma all these values can vary in space and time, but in a single fluid/species MHD description
using these constants is the best one can do. In multispecies MHD the number density can be determined
accurately as n = sum(RhoSpecies V/(ProtonMass*MassSpecies V)).
The default ion/molecular masses are given in the equation module. The default ion charges are always 1.
The default electron temperature ratio is zero, i.e. the electron pressure is assumed to be negligible relative
to the (total) ion pressure. This default is backwards compatible with previous versions of the code.
#LOOKUPTABLE command
#LOOKUPTABLE
p(rho,e)
use param
table1.out
ascii
zXe zBe nPl
54.0
4.0
4.0
p(rho,e) for ionized plasma
logrho logp pXe pBe pPl
100
1e-6
1e+6
50
0.001
100.0
NameTable
NameCommand (use, load, save, make, param)
NameFile (read this unless "make")
TypeFile (read this unless "make")
NameTableParam (if NameCommand has "param")
TableParam number of protons in Xenon
TableParam number of protons in Beryllium
TableParam number of elements in plastic
Description (read this and rest unless "load")
NameVar
nIndex1
Index1Min
Index1Max
nIndex2
Index2Min
Index2Max
Tables are identified by the NameTable string that should be unique for the table and must agree with the
name used in the ModUser module. The NameCommand tells if we should ”load” the table from a file,
”make” the table using some algorithm defined in the ModUser module, or make the table and then ”save”
it into a file. The ”use” option is the same as ”load” if the table file already exists, otherwise it is the same
as ”save”.
If NameCommand contains ”param” and the table is not loaded from a file, then the NameTableParam
variable and the TableParam values of table parameters are read from the input file and stored into the
table.
The file name and file type (”ascii”, ”real4” or ”real8”) of the table are read when NameCommand
contains ”load”, ”save”, or ”use”.
The rest of the parameters are read for commands ”make”, ”save” or ”use”. The NameVar string contains
the space separated list of the names of the two indexes and the one or more returned value(s). If the index
name starts with a ”log”, a logarithmic index is assumed (ie. the table will be uniform in the logarithm of
the index value). The nIndex1 defines the number of columns in the table, Index1Min and Index1Max the
132
smallest and largest values for the first index, respectively. The nIndex2, Index2Min, Index2Max define the
number and range of the second index.
This command can occur multiple times. By default no lookup tables are used.
#UNIFORMSTATE command
#UNIFORMSTATE
0.125
1.0
-0.5
0.0
1.0
Var1
Var2
...
The #UNIFORMSTATE command sets up a uniform initial state. This uniform state can be perturbed or
modified by the user module. The command sets the primitive variables in the order defined in the equation
module.
#SHOCKTUBE command
#SHOCKTUBE
1.
0.
0.
0.
0.75
1.
0.
1.
0.125
0.
0.
0.
0.75
-1.
0.
0.1
Var1Left
Var2Left
...
Var1Right
Var2Right
...
The #SHOCKTUBE command can be used to set up a shocktube problem. The left and right state values
are given in terms of the primitive variables as defined in the equation module. The shock can be shifted
and rotated by the #SHOCKPOSITION command.
By default the initial condition is uniform, and the values are determined by the #SOLARWIND command. The user module can be used to set up more complicated initial conditions.
#SHOCKPOSITION command
#SHOCKPOSITION
5.0
1/2
ShockPosition
ShockSlope
The ShockPosition parameter sets the position where the shock, ie. the interface between the left and right
states given by the #SHOCKTUBE command, intersects the X axis. When ShockSlope is 0, the shock
normal points in the X direction. Otherwise the shock is rotated around the Z axis, and the tangent of the
rotation angle is given by ShockSlope. Possible values are
COMPONENTS
133
ShockSlope = 0., 1/4, 1/3, 1/2, 1., 2., 3., 4.
because these angles can be accurately represented on the grid. The default values are zero, ie. the shock is
in the X=0 plane.
#SOLARWIND command
#SOLARWIND
5.0
100000.0
-400.0
0.0
0.0
0.0
0.0
-5.0
SwNDim
SwTDim
SwUxDim
SwUyDim
SwUzDim
SwBxDim
SwByDim
SwBzDim
[n/cc]
[K]
[km/s]
[km/s]
[km/s]
[nT]
[nT]
[nT]
This command defines the solar wind parameters for the GM component. The default values are all 0.0-s.
#SOLARWINDFILE command
#SOLARWINDFILE
T
IMF.dat
UseSolarWindFile (rest of parameters read if true)
NameSolarWindFile
Default is UseSolarWindFile = .false.
Read IMF data from file NameSolarWindFile if UseSolarWindFile is true. The data file contains all
information required for setting the upstream boundary conditions. Parameter TypeBcWest should be set
to ’vary’ for the time dependent boundary condition.
If the #SOLARWIND command is not provided then the first time read from the solar wind file will set
the normalization of all variables in the GM component. Consequently either the #SOLARWIND command
or the #SOLARWINDFILE command with UseSolarWindFile=.true. is required by the GM component.
The input files are strutured similar to the PARAM.in file. There are #commands that can be inserted as
well as the data. The file containing the upstream conditions should include data in the following order:
yr mn dy hr min sec msec bx by bz vx vy vz dens temp
The units of the variables should be:
Magnetic field (b)
Velocity (v)
Number Density (dens)
Temperature (Temp)
nT
km/s
cm^-3
K
The input files can have the following optional commands at the beginning
#REREAD
Reread the file if the simulation runs beyond the final time
#COOR
GSM
The coordinate system of the data: GSM (default) or GSE
#VAR
rho ux uy uz bx by bz p pe
134
#PLANE
20.0
15.0
The input data represents values on a tilted plane
Angle to rotate in the XY plane [deg]
Angle to rotate in the XZ plane [deg]
#POSITION
20.0
30.0
Y-Z Position of the satellite (also origin of plane rotation)
Y location
Z location
#SATELLITEXYZ
65.0
X
0.0
Y
0.0
Z
3D Position of the satellite
location
location
location
#ZEROBX
T
Bx is ignored and set to zero if true
#TIMEDELAY
3600.0
A constant delay added to the time in the file [s]
The #REREAD command tells BATS-R-US to reread the solarwind file when the simulation goes past the
time of the last data in the current file. The default behavior is to keep using the last data point.
The #VAR command allows reading an extended set of variables, e.g. densities of multiple species,
electron pressure, etc.
Finally, the data should be preceded by a #START. The beginning of a typical solar wind input file might
look like:
#COOR
GSM
#START
2004 6
2004 6
24
24
0
0
0
1
58
58
0
0
2.9
3.0
-3.1 - 3.7
-3.2 - 3.6
-300.0
-305.0
0.0
0.0
0.0
0.0
5.3
5.4
2.00E+04
2.01E+04
The maximum number of lines of data allowed in the input file is 50,000. However, this can be modified
by changing the variable Max Upstream Npts in the file GM/BATSRUS/get solar wind point.f90.
#BODY command
#BODY
T
3.0
4.0
1.0
10000.0
0.01
300.0
UseBody (rest of parameters read if true)
rBody (user units)
rCurrents (only read for GM component)
BodyNDim (/cc) for fluid 1
BodyTDim (K)
for fluid 1
BodyNDim (/cc) for fluid 2
BodyTDim (K)
for fluid 2
If UseBody is true, the inner boundary is a spherical surface with radius rBody. The rBody is defined in
units of the planet/solar radius. It can be 1.0, in which case the simulation extends all the way to the surface
of the central body. In many cases it is more economic to use an rBody larger than 1.0.
The rCurrents parameter defines where the currents are calculated for the GM-IE coupling. This only
matters if BATSRUS is running as GM and it is coupled to IE.
COMPONENTS
135
The BodyNDim and BodyTDim parameters define the number density and temperature inside the body.
For multifluid MHD the number density and temperature are given for all the fluids. The exact effect of
these parameters depends on the settings in the #INNERBOUNDARY command.
The default values depend on the component: For GM rBody=3, rCurrents=4, BodyNDim = 5/cc and
BodyTDim = 25000 K. For SC/IH/OH: rBody=1, BodyNDim = 1.5e8/cc, BodyTDim = 2.8e6 K. The rBody
and rCurrents are given in normalized units (usually planetary or solar radii).
#GRAVITY command
#GRAVITY
T
3
10.0
UseGravity (rest of parameters read if true)
iDirGravity(0 - central, 1 - X, 2 - Y, 3 - Z direction)
GravitySi [m/s^2] (read if iDirGravity is not 0)
If UseGravity is false, the gravitational force of the central body is neglected. If UseGravity is true and
iDirGravity is 0, the gravity points towards the origin and the gravitational force is determined by the mass
of the central body. If iDirGravity is 1, 2 or 3, the gravitational force is parallel with the X, Y or Z axes,
respectively, and the gravitational acceleration is given by the GravitySi parameter.
Default values depend on problem type.
When a second body is used the gravity direction for the second body is independent of the GravityDir
value. Gravity due to the second body is radially inward toward the second body.
#RESISTIVITY command
#RESISTIVITY
T
anomalous
1.0E+9
2.0E+9
2.0E+10
1.0E-9
UseResistivity (rest of parameters read only if set to true)
TypeResistivity
Eta0Si
[m2/s] (read except for Spitzer resistivity)
Eta0AnomSi
[m2/s] (read for anomalous resistivity only)
EtaMaxAnomSi [m2/s] (read for anomalous resistivity only)
jCritAnomSi [A/m2] (read for anomalous resistivity only)
The true SI units of resistivity are Ohm m = N m2 /(A2 s). In BATSRUS, however, we use ”normalized”
units, so that the magnetic permeability [N/A2 ] disappers from the equations. So what is described here as
”resistivity”, is really eta/mu 0 which has units of [m2 /s], same as (magnetic) diffusion. Since the normalized
current is defined as curl B (instead of curl B/mu0), the electric field is E = -u x B + eta * J in the normalized
units.
If UseResistitivy is false, no resistivity is included. If UseResistivity is true, then one can select a
constant resistivity, the classical Spitzer resistivity, anomalous resistivity with a critical current, or a user
defined resistivity.
For TypeResistivity=’Spitzer’ the resistivity is very low in space plasma. The only parameter read is the
CoulombLogarithm parameter with typical values in the range of 10 to 30.
For TypeResistivity=’constant’ the resistivity is uniformly set to the parameter Eta0Si.
For TypeResistivity=’anomalous’ the anomalous resistivity is Eta0Si + Eta0AnomSi*(j/jCritAnomSi-1)
limited by 0 and EtaMaxAnomSi. Here j is the absolute value of the current density in SI units. See the
example for the order of the parameters.
For TypeResistivity=’user’ only the Eta0Si parameter is read and it can be used to scale the resistivity set
in subroutine user set resistivity in the ModUser module. Other parameters should be read with subroutine
user read inputs of the ModUser file.
The default is UseResistivity=.false.
136
#RESISTIVITYOPTIONS command
#RESISTIVITYOPTIONS
T
T
F
UseResistiveFlux
UseJouleHeating
UseHeatExchange
Switch off negligible resistivity effects for sake of computational speed. If UseResistiveFlux is false, the resistive terms in the induction equation are neglected. If UseJouleHeating is false and non-conservative equations
are used then the Joule heating is neglected in the electron/ion pressure equation. If UseHeatExchange is
false, the heat exchange between electron and ion pressures is neglected.
The defaults are true for all three logicals.
#RESISTIVEREGION command
#RESISTIVEREGION
4.0
rZeroResist
5.0
rFullResist
Mask the resistivity (set by the #RESISTIVITY command) depending on the radial coordinate r. For r less
than rZeroResist the resistivity is zero. For r greater than rFullResist the full value of resistivity is used.
Between these two value the resistivity is linearly ramped up from zero to the full value. This command can
be used to reduce resistivity where the field aligned currents are calculated (set by the rCurrents parameter
of the #BODY command), but still apply resistivity where reconnection happens.
The default values are rZeroResist=-1 and rFullResist=1e30, so there is no masking applied.
#HALLRESISTIVITY command
#HALLRESISTIVITY
T
UseHallResist (rest of parameters read only if true)
1.0
HallFactorMax
0.5
HallCmaxFactor
If UseHallResist is true the Hall resistivity is used.
The off-diagonal Hall elements of the resistivity tensor are multiplied by HallFactorMax. If HallFactorMax
is 1 then the physical Hall resistivity is used (but also see the #HALLREGION command). Note that a
physically consistent way of changing the strength of the Hall effect is changing the ion mass and/or charge
with the #PLASMA command.
If HallCmaxFactor is 1.0, the maximum propagation speed takes into account the full whistler wave
speed. If it is 0, the wave speed is not modified. For values betwen 1 and 0 a fraction of the whistler wave
speed is added. The full speed is needed for the stability of the one or two-stage explicit scheme (unless the
whistler speed is very small and/or the diagonal part of the resistivity tensor is dominant). For 3 and 4-stage
explicit schemes (see the #RK command) and also for the implicit time stepping the HallCmaxFactor can
be reduced, possibly all the way to zero to minimize the discretization errors.
Default is UseHallResist false.
#HALLREGION command
#HALLREGION
box
10.0
0.0
0.0
NameHallRegion
x0Hall
(only read for region sphere or box)
y0Hall
z0Hall
COMPONENTS
8.0
1.0
6.0
1.0
4.0
1.0
xSizeBoxHall
DxSizeBoxHall
ySizeBoxHall
DySizeBoxHall
zSizeBoxHall
DzSizeBoxHall
(only
(only
(only
(only
(only
(only
read
read
read
read
read
read
for
for
for
for
for
for
region
region
region
region
region
region
137
box)
box)
box)
box)
box)
box)
The NameHallRegion parameter determines the region where the Hall effect is taken into account. Possible
values are ”all”, ”box”, ”sphere”, ”box0” and ”sphere0”.
For value ”all” the Hall effect is used everywhere in the computational domain. For ”box” and ”sphere”
the region is inside a box or sphere, respectivrly, centered around the X0Hall, Y0Hall, Z0Hall. If NameHallRegion = ”box0” or ”sphere0”, the region is centered around the origin.
For NameHallRegion ”sphere” or ”sphere0” the rSphereHall and DrSphereHall parameters are read. The
first determines the radius of the sphere, the second the thickness of the shell where the hall effect increases
from 0 to its full value linearly. This smoothing is useful to avoid artifacts due to a sudden change in the
Hall coefficient.
For NameHallRegion ”box” or ”box0” the 3 sizes and 3 smoothing widths are read as shown in the
example.
The default value is ”all”, ie. the Hall effect is applied everywhere if the Hall effect is switched on in the
#HALLRESISTIVITY command.
#BIERMANNBATTERY command
#BIERMANNBATTERY
T
UseBiermannBattery
If UseBiermannBattery is true then the Biermann battery term in the generalized Ohm’s law is used, otherwise it is switched off.
If the Hall term is used in combination with the electron pressure equation then the Biermann battery
term is switched on by default. In that case the BIERMANNBATTERY command is not needed.
Default is UseBiermannBattery false.
#MINIMUMDENSITY command
#MINIMUMDENSITY
0.001
RhoMinDim [amu/cc] for fluid 1
-1.0
RhoMinDim [amu/cc] for fluid 2
Provide minimum density(s) for the ion/neutral fluid(s). If the minimum density is positive, the density is
kept above this limit for that fluid. The minimum density is given in the input/output units for density,
which varies from application to application. A negative value indicates that no minimum density is applied
for that fluid.
By default no minimum density limit is applied.
#MINIMUMPRESSURE command
#MINIMUMPRESSURE
0.001
pMinDim [nPa] for fluid 1
-1.0
pMinDim [nPa] for fluid 2
0.01
PeMinDim [nPa] for electron pressure (if used)
Provide minimum pressure(s) for the ion/neutral fluid(s) and electrons. If the minimum pressure is positive,
the pressure is kept above this limit. The minimum pressure is given in the input/output units for pressure,
138
which varies from application to application. A negative value indicates that no minimum pressure is applied
for that fluid.
By default no minimum pressure limit is applied.
#ELECTRONPRESSURE command
#ELECTRONPRESSURE
1.1e5
PeMinSi
Provide the minimum electron pressure threshold in SI units. Currently the minimum electron pressure is
only used in ModRadDiffusion. The default value is -1, i.e. no threshold is applied.
#ANISOTROPICPRESSURE command
#ANISOTROPICPRESSURE
T
10
100
UseConstantTau
TauInstabilitySi (only read if UseConstantTau is true)
TauGlobalSi
Set parameters for the pressure relaxation term.
If UseConstantTau is set to false, use the growth-rate based relaxation time. This is the default and also
recommended.
If UseConstantTau is set to true, TauInstabilitySi provides the relaxation time in seconds to restrict the
pressure anisotropy in unstable regions. Within the time, the parallel pressure is pushed towards plasma
instability limits. The default value is -1, i.e, do not apply the pressure relaxation due to instabilities. If
applied, a typical value for magnetospheric simulations is 10 seconds.
TauGlobalSi provides the global pressure relaxation time in seconds applied in the whole domain. Within
the time, the parallel pressure is pushed towards the total scalar pressure. In the presence of both the
instability and global relaxation, the one that changes pressure more will be used for the pressure relaxation
term. The default value for TauGlobalSi is -1, i.e. do not apply the global relaxation. The example shows a
recommended value for magnetospheric simulations.
When UseConstantTau = T and TauInstabilitySi = -1, the pressure relaxation term is not applied, thus
TauGlobalSi is meaningless in this case.
#EXTRAINTERNALENERGY command
#EXTRAINTERNALENERGY
-1e3
ExtraEintMinSi
Provide the minimum extra internal energy density threshold in SI units. The extra internal energy density
is the difference between true internal energy density and the p/(gamma-1) of the ideal gas. Using a large
enough gamma (e.g. 5/3) can guarantee that the difference is always non-negative. The default value is
zero.
#RADIATION command
#RADIATION
T
T
larsen
300.0
UseRadDiffusion
(rest of parameters read only if true)
UseRadFluxLimiter
TypeRadFluxLimiter (read only if UseRadFluxLimiter is true)
TradMinSi
COMPONENTS
139
If UseRadDiffusion is true the radiation hydrodynamics with radiation nonequilibrium diffusion approximation is used.
If the UseRadDiffusion is set to true, then optionally a non-linear flux limiter can be invoked via UseRadFluxLimiter set to true. This limits the radiation diffusion flux so that it does not exceed the optically thin
streaming limit, the speed of light. The type of flux limiter can be selected by setting TypeRadFluxLimiter.
If TypeRadFluxLimiter=”sum”, then Wilson’s sum flux limiter is used. If TypeRadFluxLimiter=”max”,
then Wilson’s max flux limiter is used. For TypeRadFluxLimiter=”larsen” the square-root flux limiter of
Larsen is used.
The TradMinSi parameter sets a minimum temperature in Kelvins for the radiation. This helps avoiding
negative radiation temperature due to numerical errors. A recommended value is 300K.
The default for UseRadFluxLimiter is false.
#HEATFLUXLIMITER command
#HEATLUXLIMITER
T
0.06
UseHeatFluxLimiter
HeatFluxLimiter
If UseHeatFluxLimiter is set to false, the original Spitzer-Harm formulation for the collisional isotropic
electron thermal heat conduction is used as set by the #SEMIIMPLICIT command.
If UseHeatFluxLimiter is set to true, this isotropic heat conduction is modified to correct the heat
conduction coefficient if the electron temperature length scale is only a few collisonal mean free paths of the
electrons or smaller. The flux limited heat conduction that is used in this case is the threshold model.
If we define the free streaming flux as F fs = n e*k B*T e*v th, where v th = sqrt(k B*T e/m e) is a characteristic thermal velocity, then the threshold model limits the heat conduction flux F = -kappa*grad(Te),
with heat conduction coefficient kappa, by F = -min(kappa, f*F fs / —grad(Te)—) * grad(Te) Here, f is the
heat flux limiter.
A possible application of interest for the heat flux limiter is laser-irradiated plasmas. For this limiter
to work properly, the thermodynamic quanties in the user material properties subroutine in the ModUser
module need to be defined (see ModUserCrash for an example).
The default for UseHeatFluxLimiter is false.
#LASERPULSE command
#LASERPULSE
T
3.8e10
1.0e-10
1.0e-11
1.0e-11
UseLaserHeating (rest of parameters are read if true)
IrradianceSI [J/s]
tPulse [s]
tRaise [s]
tDecay [s]
This command is used for CRASH applications and it requires a CRASH related user file.
Read parameters for the laser pulse. The irradiance determines the energy per second. The length, rise,
and decay times are given by the other three parameters. The laser heating is switched off by default.
#LASERBEAMS command
#LASERBEAMS
rz
30
438.0
-290.0
TypeBeam
nRayPerBeam
rBeam
xBeam
140
This command is used for CRASH applications and it requires a CRASH related user file. This command
should be used together with the #LASERPULSE command.
The TypeBeam determines the geometry of the beams. Currently all beam definition are only available
for rz-geoemrty.
For TypeBeam=rz, each beam consists of 2*nRayPerBeam+1 rays. The rays are parallel and are up to
1.5 rBeam away from the central ray. The xBeam determines the starting X position of the rays.
For TypeBeam=3d in rz-geometry there is the option for a beam definition on a polar or cartesian grid
(The grid is defined orthogonal to the initial ray propagation direction). On a polar grid the rays locations
are defined on a uniform grid with nRayR rays in the radial direction from 0 to 1.5*rBeam and nRayPhi+1
rays in the angle direction from 0 to pi. Due to symmetry properties in the laser beams the angle from pi
to 2*pi are not needed. On a cartesian grid the ray locations are defined on a 2*nRayY+1 by nRayZ+1
uniform grid. The y-direction ranges from -1.5*rBeam to 1.5*rBeam. Due to symmetry in each beam the
z-direction is limited between 0 and 1.5*rBeam.
#LASERBEAM command
#LASERBEAM
10.0
0.0
1.0
SlopeDeg
yBeam
AmplitudeRel
The SlopeDeg parameter determines the direction of the beam relative to the X axis. The yBeam has to
do with the Y coordinate of the initial positions. The AmplitudeRel gives the relative intensity of the beam.
#LASERBEAMPROFILE command
#LASERBEAMPROFILE
4.2
SuperGaussianOrder
The SuperGaussianOrder parameter determines the profile of each laser beam. The irradiance profile
of the beam is of the form exp[ - (r / rBeam)**SuperGaussianOrder], where r is the distance to the tilted
central ray of the beam and rBeam is defined by the #LASERBEAMS command. The default value for
SuperGaussianOrder is 4.2
#MASSLOADING command
#MASSLOADING
F
F
UseMassLoading
DoAccelerateMassLoading
#HEATCONDUCTION command
#HEATCONDUCTION
T
spitzer
UseHeatConduction
TypeHeatConduction
If UseHeatConduction is false, no heat conduction is included. If UseHeatConduction is true, then one can
select the collisional heat conduction of Spitzer or a user defined heat conduction. Both heat conduction
formulations are field-aligned and are only applied to the electrons.
COMPONENTS
141
For TypeHeatConduction=’spitzer’ a spatially uniform Coulomb logarithm of 20 is assumed, resulting in
a heat conduction coefficient of
9.2e-12 W m^-1 K^-7/2.
Fully ionized hydrogen plasma is assumed.
For TypeHeatConduction=’user’ the heat conduction coefficient of the field-aligned heat conduction is
read from the user material properties subroutine in the ModUser module. Optional parameters should be
read with subroutine user read inputs of the ModUser file.
The default is UseHeatConduction=.false.
#IONHEATCONDUCTION command
#IONHEATCONDUCTION
T
spitzer
UseIonHeatConduction
TypeIonHeatConduction
If UseIonHeatConduction is false, no proton heat conduction is included. If UseIonHeatConduction is true,
then one can select the classical Coulomb-mediated ion heat conduction or a user defined heat conduction.
Both heat conduction formulations are field-aligned and are only applied to the protons.
For TypeIonHeatConduction=’spitzer’ a spatially uniform Coulomb logarithm of 20 is assumed, resulting
in a heat conduction coefficient of
2.6e-13 W m^-1 K^-7/2
for protons.
For TypeIonHeatConduction=’user’ the heat conduction coefficient of the field-aligned heat conduction
is read from the user material properties subroutine in the ModUser module. Optional parameters should
be read with subroutine user read inputs of the ModUser file.
The default is UseIonHeatConduction=.false.
#HEATFLUXREGION command
#HEATFLUXREGION
T
5.0
10.0
UseHeatFluxRegion
rCollisional
rCollisionless
If UseHeatFluxRegion is false, both the electron and ion heat conduction (as set by the #HEATCONDUCTION and #IONHEATCONDUCTION commands), are applied everywhere.
If UseHeatFluxRegion is true, both the electron and ion heat conduction are applied between the inner
boundary (either Sun or planet) and rCollisional. Beyond r=rCollisional, both the electron and ion heat
conduction coefficients are multiplied by
exp(-((r-rCollisional)/(rCollisionless-rCollisional))**2)
The default is UseHeatFluxRegion=.false.
#SECONDBODY command
#SECONDBODY
T
0.01
-40.
0.
UseBody2
rBody2
xBody2
yBody2
! Rest of the parameters read if .true.
142
0.
0.011
5.0
25000.0
T
365.25
zBody2
rCurrents2 !This is unused currently
RhoDimBody2 (/ccm) density for fixed BC for rho_BLK
TDimBody2 (K) temperature for fixed BC for P_BLK
UseOrbit
OrbitPeriod [days]
Defines the radius, (initial) position, surface density and temperature, and orbit period (if any) of a second
body. The second body may also have magnetic field given by the #DIPOLEBODY2 command. This
command should appear before the #INNERBOUNDARY command when using a second body. Default is
UseBody2=.false.
#DIPOLEBODY2 command
#DIPOLEBODY2
0.0
0.0
-1000.0
BdpDimBody2x [nT]
BdpDimBody2y [nT]
BdpDimBody2z [nT]
The BdpDimBody2x, BdpDimBody2y and BdpDimBody2z variables contain the 3 components of the dipole
vector in the GSE frame. The absolute value of the dipole vector is the equatorial field strength in nano
Tesla.
Default is no dipole field for the second body.
5.2.15
Corona specific commands
#MAGNETOGRAM command
#MAGNETOGRAM
T
UseMagnetogram (rest of parameters read if true)
1.0
rMagnetogram
2.5
rSourceSurface
0.0
HeightInnerBc
Param/CORONA/CR1935_WSO.dat
NameHarmonicsFile
12
nHeaderLine
-1.0
PhiShift
0.01
UnitB
If UseMagnetogram=T then read the harmonics file for the coronal magnetic field and use it to set B0 to
the potential field solution.
rMagnetogram and rSourceSurface are the photosphere and source surface heliocentric radii, respectively.
B0 becomes radial at rSourceSurface (typically taken to be 2.5 solar radii).
HeightInnerBc is the height above the photosphere of the boundary surface, non-zero values for this
parameter are not recommended to unexperienced users.
NameHarmonicsFile is the name of the file containing the harmonics. nHeaderLine is the number of
header lines in the harmonics file.
PhiShift is the offset in the longitude (calculated as the diffference in lonigitude of the magnetogram
central meridian and 180 degrees. PhiShift=0 means that the synoptic map is averaged over the whole
Carrington rotation. With PhiShift = -1.0 the code calculates the actual value for PhiShift by exctracting
the central meridian coordinate from the harmonics file.
UnitB may be used both as a fudge-factor to upscale the (usually reduced) observational data and to
accomodate data measured in the units different from Gauss. Wilcox data (in micro-Tesla) may be only
used with UnitB=0.01-0.03.
Default is UseMagnetogram=F.
COMPONENTS
143
#READPOTENTIALFIELD command
#READPOTENTIALFIELD
T
potentialfield.out
0.0
3.0
UseMagnetogram (rest of parameters are read if true)
NamePotentialFieldFile
HeightInnerBc
UnitB
If UseMagnetogram=T then read the potential field from a file.
NamePotentialFieldFile provides the name of the file containing the 3D potential field solution, typically
produced by the FDIPS code.
HeightInnerBc is the height above the photosphere of the boundary surface, non-zero values for this
parameter are not recommended to unexperienced users.
UnitB may be used both as a fudge-factor to upscale the (usually reduced) observational data and to
accomodate data measured in the units different from Gauss. Wilcox data (in micro-Tesla) may be only
used with UnitB=0.01-0.03.
#LDEM command
#LDEM
F
LDEM_moments.out
1
UseLdem (rest of parameters read if true)
NameLdemFile
iRadiusLdem
If UseLdem=T then read the LDEM moments file for the coronal density and temperature.
NameLdemFile is the name of the file containing the Ldem moments.
iRadiusLdem gives the index of the desired radius at which data is extracted. The Ldem moments data is
ordered into concentric spherical shells of increasing radius, ranging from 1.035Rs to 1.255Rs, in increaments
of 0.01Rs. The user can select the desired radius by varying the iRadiusLdem parameter. The minimal
accepted value of iRadiusLdem is 1, corresponding to 1.035Rs. iRadiusLdem=2 corresponds to 1.045Rs, and
so forth.
Default is UseLdem=F, iRadiusLdem=1
#EMPIRICALSW command
#EMPIRICALSW
WSA
NameModelSW
Depending on the expansion factors, calculated using the magnetogram field, for NameModelSW=WSA the
spatial distribution of varied gamma is calculated. Through the Bernoulli integral the solar wind at 1AU
should fit the WSA solar wind semi-empirical model, with the prescribed distribution of the varied gamma.
Default value is NameModelSW=none.
#WSACOEFF command
#WSACOEFF
240.0
675.0
4.5
1.0
0.8
2.8
1.25
ConstantSpeed [km/s]
ModulationSpeed [km/s]
PowerIndex1
Coeff1
Coeff2
Angle [deg]
PowerIndex2
144
3.0
0.0
9999.0
PowerIndex3
LowerBound
UpperBound
Read in various parameters for the Wang-Sheely-Arge model. The exact meaning of the parameters should
be obtained from publications on the WSA model. Default values are show.
#CORONALHEATING command
#CORONALHEATING
exponential
TypeCoronalHeating
0.0575
DecayLengthEXP
[Rsun]
(read for exp heating only)
7.285E-05
HeatingAmplitudeCgs [ergs/cm^3/s] (read for exp heating only)
#CORONALHEATING
unsignedflux
TypeCoronalHeating
0.0575
DecayLength
[Rsun] (read for unsignedflux heating only)
1.0
HeatNormalization [none] (read for unsignedflux heating only)
#CORONALHEATING
alfvenwavedissipation
7.5E4
0.04
TypeCoronalHeating
LperpTimesSqrtBSi (read for alfvenwavedissipation only)
Crefl
(read for alfvenwavedissipation only)
If UseCoronalHeating is false, no CoronalHeating is included. If UseCoronalHeating is true, then one
can select a simple exponential scale height heating model or B weighted heating model normalized to the
amount of unsigned flux measured at the soalr surface (Abbett 2007). Each model applies a cell based source
term to the Energy equation.
For TypeCoronalHeating=’exponential’ coronal heating is applied using an exponential scale height
model. DecayLengthExp is the e-folding length in units of Solar Radii and HeatingAmplitudeCgs is the
heating rate at r=1.0
For TypeCoronalHeating=’unsignedflux’ the coronal heating term is calculated using the unsigned flux
model presented in (Abbett 2007). DecayLengthExp is the e-folding length in units of Solar Radii to limit
the range of influence of this function. Because the total power in X-Ray emission is not well constrained
to total heating power in the corona, the term HeatNormalization is used to uniformly multiply the heating
rate by this factor (default 1.0).
For TypeCoronalHeating=’NonWKB’ coronal heating is applied using the wave dissapation model of
Cranmer 2010. No additional input parameters are needed.
For TypeCoronalHeating=’alfvenwavedissipation’ coronal heating is applied using an anisotropic formulation of the Kolmogorov-type dissipation.
The default is TypeCoronalHeating=”none”
#LONGSCALEHEATING command
#LONGSCALEHEATING
T
DoChHeat (rest of parameters read only if set to true)
7.285E-05
HeatChCgs
[ergs/cm^3/s]
0.0575
DecayLengthCh
[Rsun]
If DoChHeat is false, no long scale height heating is included. If DoChHeat is true, one supplies parameters for
a simple exponential scale height heating model like that in the CORONALHEATING command. HeatChCgs
sets the base heating rate ar r=1.0 [Rsun] and DecayLengthCh is the e-folding length in units of Solar Radii.
The idea is to use this commmand in conjunction with any short scale height heating model selected by the
CORONALHEATING command.
The default is DoChHeat=.false.
COMPONENTS
145
#ACTIVEREGIONHEATING command
#ACTIVEREGIONHEATING
T
UseArComponent (rest of parameters read only if set to true)
4.03E-05
ArHeatFactorCgs [ergs/cm^3/s]
30.0
ArHeatB0
[Gauss]
5.0
DeltaArHeatB0
[Gauss]
If UseArComponent is false, no ActiveRegion heating component is used. If UseArComponent is true,
one supplies parameters for a linear B weighted heating model used to supply strong heating to regions of
high magnetic field strength. This model multiplies ArHeatFactorCgs by the cell magnetic field strength in
gauss to determine a heating rate. ArHeatB0 is the central field strength for the tanh transition function
that selects between the exponential heating model supplied by the CORONALHEATING command and
the ArHeating term. DeltaArHeatB0 is the width of this transition function. This transition function has
values: approx 0.1 at b0-deltab0, 0.5 at b0, and approx 0.9 at b0+deltab0.
This heating is ONLY applied when CORONALHEATING is set to the exponential heating model at
the moment.
The default is UseArComponent=.false.
#OPENCLOSEDHEAT command
#OPENCLOSEDHEAT
T
DoOpenClosedField
If DoOpenClosedHeat=.true., then the heating function or the turbulent heating rate are modulated from
closed to open magnetic field. Exponential heating function as well as the unsigned flux model function are
switched off in the open field region. With the Cranmer heating function, the reflection coefficient in the
closed field region is set to one, intensifying the heating.
Default is DoOpenClosedField = .false.
#RADIATIVECOOLING command
#RADIATIVECOOLING
T
UseRadCooling
Switches the radiation cooling on and off. For coronal solar plasma the emissivity calculated in the ”coronal”
approximation (optically thin plasma with no radiation-induced excitations and ionization). The radiation
loss rate is approximated using CHIANTI tables or approximate interpolation formula (see comments in
src/ModRadiativeCooling.f90). Default value for UseRadCooling is .false.
#TRANSITIONREGION command
#TRANSITIONREGION
T
3.0E+5
1.0E+4
DoExpandTransitionRegion
TeTransitionRegionSi
DeltaTeSi (read if DoExtendTransitionRegion is true)
The artificial expansion of the transition region is needed to resolve the Transition Region (TR) which is an
extremely thin region in reality. To achieve the expansion, at temperatures below TeTransitionRegionSi the
heat conduction coefficient is artificially enhanced and the radiation loss rate is modified accordingly. The
profile of temperature and density in this case are maintained to be the same as in the actual transition
region, however, the spatial scale becomes much longer, so that the TR may be modelled with feasible grid
resolution.
146
If DoExpandTransitionRegion is false, the #TRANSITIONREGION command can be used to set the
temperature of the top of the transition region. Then the special boundary condition (REB - radiation
energy balance) is used at the ”coronal base”, while the temperature is fixed at Te=TeTopTransitionRegion.
Default value is DoExpandTransitionRegion = .false.
5.2.16
Heliosphere specific commands
#THINCURRENTSHEET command
#THINCURRENTSHEET
F
DoThinCurrentSheet
The thin current sheet option is based on the thin current sheet method of the ENLIL code. Numerical
reconnection of magnetic field about the heliospheric current sheet is avoided by reversing the field direction
in one hemisphere (the hemisphere for which the radial magnetic is negative). This method assumes that
there is no guide field, which would otherwise start to reconnection. It is only intended for inner and outer
heliosphere simulations, assuming no coronal mass ejections are present.
This method requires an equation model that contains the SignB variable. This variable is used to track
where the field is reversed and where the current sheet is located by using a level set method for the sign.
Default value is DoThinCurrentSheet = .false.
#HELIOUPDATEB0 command
#HELIOUPDATEB0
-1.0
DtUpdateB0 [s]
Set the frequency of updating the B0 field for the solar corona. A negative value means that the B0 field is
not updated.
#HELIODIPOLE command
#HELIODIPOLE
-3.0
0.0
HelioDipoleStrength [G]
HelioDipoleTilt
[deg]
Variable HelioDipoleStrength defines the equatorial field strength in Gauss, while HelioDipoleTilt is the tilt
relative to the ecliptic North (negative sign means towards the planet) in degrees.
Default value is HelioDipoleStrength = 0.0.
#HELIOBUFFERGRID command
#HELIOBUFFERGRID
19.0
rBuffMin
21.0
rBuffMax
45
nThetaBuff
90
nPhiBuff
Define the radius and the grid resolution for the uniform spherical buffer grid which passes information from
the SC(IH) component to the IH(OH) component. The resolution should be similar to the grid resolution
of the coarser of the SC(IH) and IH(OH) grids. The buffer grid will only be used if ’buffergrid’ is chosed for
TypeBcInner in the #INNERBOUNDARY command of the target (IH or OH) component. This command
can only be used in the first session by the IH(OH) component. Default values are shown above.
COMPONENTS
5.2.17
147
Wave specific commands
#ADVECTWAVES command
#ADVECTWAVES
T
DoAdvectWaves
If DoAdvectWaves = .true. the waves are advected in the energy dimension. This term may be very small
and it can be switched off for purposes of testing or comaparison with other codes that do not have this
term.
The default is false.
#ALFVENWAVES command
#ALFVENWAVES
T
UseAlfvenWaves
If UseAlfvenWaves = .true. the waves are separated into two sets, one of them (’plus’) propagate parallel
to the magnetic field, the second one (’minus’) is for waves propagating anti-parallel to the field. The
propagation speed with respect to the background
5.2.18
Script commands
#INCLUDE command
#INCLUDE
Param/SSS_3000
NameIncludeFile
Include a library file from Param/ or any file from anywhere else.
148
5.3
Input Commands for the Ridley Ionosphere Model: IE Component
5.3.1
Testing
#STRICT command
#STRICT
T
UseStrict
is true, i.e. strict mode.
#DEBUG command
#DEBUG
2
3
iDebugLevel
iDebugProc
The iDebugLevel variable sets the level of debug information for the processor selected by iDebugProc.
Default is iDebugLevel=-1 which is no debug info on any and iDebugProc=0.
5.3.2
Output
#IONODIR command
#IONODIR
IE/Plots
NameIonoDir
The NameIonoDir variable contains the name of the directory to store output files.
”IE/ionosphere”.
Default value is
#SAVEPLOT command
#SAVEPLOT
2
min idl
-1
10.0
max tec
-1
20.0
nFile
StringPlot
DnOuput
DtOutput [sec]
StringPlot
DnOuput
DtOutput [sec]
The StringPlot variable consists of two string parts: the TypePlotVar string can be ’min’, ’max’, ’uam’ or
’aur’ corresponding to a minimum, maximum, upper atmosphere or auroral set of plot variables. The other
part TypePlotForm can be ’idl’ or ’tec’ corresponding to plot files for IDL or TecPlot. The DnOuput and
DtOutput variables determine the frequency of saves in terms of time step or physical time.
The default is that no plotfiles are saved.
The ’min’ variable set includes: Theta [deg], Psi [deg], SigmaH [mhos], SigmaP [mhos], Jr [mA/m2 ],
Phi [kV] The ’max’ variable set includes: X [Re], Y [Re], Z [Re], Theta [deg], Psi [deg], SigmaH [mhos],
SigmaP [mhos], E-Flux [W/m2 ], Ave-E [eV], Jr [mA/m2 ], Phi [kV], Ex [mV/m], Ey [mV/m], Ez [mV/m],
Jx [microA/m2 ], Jy [microA/m2 ], Jz [microA/m2 ], Ux [km/s], Uy [km/s], Uz [km/s], JouleHeat [mW/m2 ],
IonNumFlux [/cm2 /s], RT 1/B [1/T], RT Rho [amu/cm3 ], RT P [Pa], conjugate dLat [deg], conjugate dLon
5.3. INPUT COMMANDS FOR THE RIDLEY IONOSPHERE MODEL: IE
COMPONENT
149
[deg] The ’uam’ variable set includes: Theta [deg], Psi [deg], SigmaH [mhos], SigmaP [mhos], Jr [mA/m2 ],
Jr(NW) [mA/m2 ], E-Flux [W/m2 ], Ave-E [eV], Phi [kV] The ’aur’ variable set includes: Theta [deg], Psi
[deg], SigmaH [mhos], SigmaP [mhos], Jr [mA/m2 ], Phi [kV], E-Flux [W/m2 ], Ave-E [eV], RT 1/B [1/T],
RT Rho [amu/cm3 ], RT P [Pa], JouleHeat [mW/m2 ], IonNumFlux [/cm2 /s], conjugate dLat [deg], conjugate
dLon [deg]
#SAVEPLOTNAME
F
IsPlotName_e
Plot files are named with the new substring including full year, ie. e20000321-104510-000
#SAVELOGNAME command
#SAVELOGNAME
F
IsLogName_e
Log files are named with the new substring including full year, ie. e20000321-104500-000
#SAVELOGFILE command
#SAVELOGFILE
F
DoSaveIELogfile
If true, every time that iono solve is called, iteration, time, and soltution information is written to a logfile.
5.3.3
Physical parameters
#IONOSPHERE command
#IONOSPHERE
5
F
F
150.0
0.25
0.25
iConductanceModel
UseFullCurrent
UseFakeRegion2
F107Flux
StarLightPedConductance
PolarCapPedConductance
The iConductanceModel variable determines which ionosphere model is used:
0 - uses a constant Pedersen conductance which is set by StarLightPedConductance
1 - uses a constant Pedersen conductance which is set by StarLightPedConductance, and a constant Hall
conductance which is set by PolarCapPedConductance
2 - uses a solar EUV combined with a nightside conductance, so it uses F107Flux and StarLightPedConductance
3 - uses solar EUV, nightside, and crude oval, so uses F107Flux, StarLightPedConductance, and PolarCapPedConductance, since a polar cap is defined with the oval.
4 - restricted oval, uses same variables as 3.
5 - more realistic oval, uses same variables as 3.
Model 4 and 5 differ in the way the conductances are limited to the fitted oval. Model 4 is more restrictive,
while model 5 is somewhat more relaxed.
The UseFullCurrent and UseFakeRegion2 logicals were used in the past to test various algorithmic choices.
They should have a false value now. The default values are shown by the example above.
150
#GEOMAGINDICES command
#GEOMAGINDICES
This command activates the ionospheric contribution to GM’s calculation of geomagnetic indices, activated
by the GM command of the same name. While it is possible to run the GM version without an IE contribution, it is not recommended. This command currently has no parameters associated with it.
#MAGNETOMETER command
#MAGNETOMETER
magin.dat
-1
60.0
NameMagInputFile
DnOutput
DtOutput
The #MAGNETOMETER command is used for the calculation of the ground perturbations caused by two
current systems: Hall and Pedersen currents.
The NameMagInputFile parameter gives the file name that contains the locations on the Earth where
the user is interested in calculating the ground magnetic perturbations. The file has the following format:
#COORD
MAG
#START
abc
def
ghi
The coordinate system for the latitude/longitude below
20.0
-30.0
85.0
120.0
230.0
-80.0
The name of the station, latitude,longitude
The coordinate system accepts MAG (geomagnetic coordinate) or SMG (solar magnetic coordinate) so
far. The station name can have maximum 3 characters. The name, latitude, and longitude should be
sperated with space in between.
The DnOutput and DtOutput parameters determine the frequency of writing out the calculated perturbations in number of time steps and time interval, respectively.
The output of the ground-based magnetic perturbations is in GM/IO2/mag n*.dat, in which the location
of each station in GSM cartisian coordinates, the 3 components (northward, eastward, and downward in SM
coordiantes) of the magnetic perturbations by magnetospheric currents, and the 3 components (northward,
eastward, and downward in SM coordiantes) of the magnetic perturbations by field-aligned currents are
written out. The unit of the pertrubation output is nT.
#IM command
#IM
average
0.5
TypeImCouple
FractionImJr
The TypeImCouple parameter determines which hemisphere the IM component is coupled to. If the value is
’north’ or ’south’, the potential and radial current are sent from the corresponding magnetic hemisphere. For
’cpcpmin’ the hemisphere with the lower cross polar cap potential is selected. For TypeImCouple=’average’
the potential and radial current are averaged for the north and south hemispheres.
The FractionImJr parameter multiplies the field aligned currents received from IM (when the IM to IE
coupling is swithed on) so they do not shield completely the weaker GM field aligned currents.
The default values are ’north’ and 1.0 (full strength IM currents), which is backward compatible, and it
requires no communication between the IE processors.
5.3. INPUT COMMANDS FOR THE RIDLEY IONOSPHERE MODEL: IE
COMPONENT
151
#UA command
#UA
T
45.0
DoCoupleUaCurrent
LatBoundary [deg] (only read if DoCoupleUaCurrent is true)
The DoCoupleUaCurrent parameter determines if the field aligned current calculated by the UA component
should be used. Usually the currents are dominated by the field aligned currents provided by the GM
component. The coupling with the UA currents is still experimental. If DoCoupleUaCurrent is set to true,
the lower latitude boundary for the potential solver should be given with the LatBoundary paramter.
The default value is DoCoupleUaCurrent=.false, i.e. the UA currents are not included.
#AMIEFILES command
#AMIEFILES
IE/amie.north
IE/amie.south
Set the files to read the AMIE data from.
Default is not reading AMIE files.
#SPS command
#SPS
T
UseSPS
The UseSPS parameter indicates if the serial potential solver is used. This is the default in the SWMF and
it cannot be modified in the SWMF.
#BACKGROUND command
#BACKGROUND
dir
weimer96
ihp
xyz
NameOfModelDir
NameOfEFieldModel
NameOfAuroralModel
NameOfSolarModel
This command cannot be used in the SWMF.
#CONDUCTANCE command
#CONDUCTANCE
1.0
1.7
OvalWidthFactor
OvalStrengthFactor
Modifies the conductance by adjusting the oval width/strength. Only works for conductance model 4!
#BOUNDARY command
#BOUNDARY
10.0
LatBoundary
Define the low latitude boundary for the potential solver. The default is set dynamically by the boundary
of the closed field line region.
152
5.3.4
Scheme parameters
#SOLVER command
#SOLVER
bicgstab
NameSolver (gmres or bicgstab)
Select which solver to use. Default is bicgstab since it is faster.
#KRYLOV command
#KRYLOV
T
T
0.01
100
UsePreconditioner
UseInitialGuess
Tolerance
MaxIteration
This command controls the parameters for the Krylov solver used to solve the Poisson type equation for the
electric potential. If UsePreconditioner is true the solver uses a preconditioner. If UseInitialGuess is true,
the previous solution is used as an initial guess. The Tolerance parameter sets the second norm of the final
(preconditioned) residual. The MaxIteration parameter sets the maximum number of iterations before the
linear solver gives up. In most cases the default values should work fine.
The default values are shown above.
5.4. INPUT COMMANDS FOR THE CRCM: IM COMPONENT
5.4
153
Input Commands for the CRCM: IM Component
List of IM commands used in the PARAM.in file
5.4.1
Numerical scheme
#LIMITER command
#LIMITER
F
2
UseMcLimiter
BetaLimiter
Set whether or not the MC limiter is used. If it is not, the super bee limiter is used. Also set the Beta
parameter for the MC limiter. The default value is shown.
#TIMESIMULATION
0.0
TimeSimulation
This command specifies the simulation time.
5.4.2
Input/output
#SAVEPLOT command
#SAVEPLOT
2
F
F
DtSavePlot
DoSaveFlux
UseSeparatePlotFiles
Define frequency of plots. When DoSaveFlux is false, only integrated values such as species pressure density
etc is saved. When DoSaveFlux is true, then another file containing information needed to make plots of
species flux in each energy bin is saved. Use SeparatePlotFiles defines if each time is saved in the same file
or if a separate file is used for each time.
#SAVELOG command
#SAVELOG
10
DtSaveLog
When this command is set, a log file for CRCM is written out. The log file saves the change in ring current
energy content for each species resulting from each operator. A new entry in the log is written out every
DtSaveLog seconds of simulation time.
#TYPEBOUNDARY command
#TYPEBOUNDARY
Ellipse
TypeBoundary
Determines if the IM outer boundary is an ellipse of circle.
154
#MINIMUMPRESSURETOGM command
#MINIMUMPRESSURETOGM
1e-2
MinimumPressureToGM
Sets minimum pressure passed to GM.
#RESTART command
#RESTART
F
IsRestart
Determine whether or not to continue a previous run.
#INITIALF2 command
#INITIALF2
F
T
F
IsEmptyF2
IsGmInitial
IsDataInitial
Determines whether to fill the fluxes in the simulation domain based on a Maxwellian determined from MHD
quantities (IsGmInitial=T) or to set the initial fluxes in the simulation domain to zero (IsEmptyF2=T, not
recommended) or to set the initial fluxes in the simulation to values from AMPTE/CCE data (IsDataInitial=T). The default is shown.
#END command
#END
5.5. INPUT COMMANDS FOR THE HOT ELECTRON ION DRIFT INTEGRATOR: IM
COMPONENT
155
5.5
5.5.1
Input Commands for the Hot Electron Ion Drift Integrator:
IM Component
Testing
#STARTTIME command
#STARTTIME
2002
4
17
0
0
0
iYear
iMonth
iDay
iHour
iMinute
iSecond
(GMT) or Universal Time (UT) in stand alone mode. In the SWMF this command checks start times against
the SWMF start time and warns if the difference exceeds 1 millisecond. This time is stored in the BATSRUS
restart header file.
The default values are shown above. To be used only in standalone mode within the IM domain.
#STOP command
#STOP
3600.0
The tSimulationMax variable contains the simulation time in seconds relative to the initial time set by the
#STARTTIME command.
The default value is tSimulationMax=0.
#TIMESTEP command
#TIMESTEP
20.
TimeStep [sec]
TimeStep should be multiple of 2, since HEIDI uses Time Splitting scheme. The default value of the time
step is dt = 20.
#GRID command
#GRID
20
24
42
71
24
nRadialGrid
nPhiGrid
nEnergyGrid
nPitchGrid
nPointFieldLine
The #GRID command allows to set the grid resolution The Resolution parameter refers to the number of
grid points within the domain.
nRadialGrid
nPhiGrid
nEnergyGrid
nPitchGrid
nPointFieldLine
-
number
number
number
number
number
of
of
of
of
of
radial grid points
azimuthal grid points
energy grid points
pitch angle grid points
grid points along the magnetic field line
156
#STORM command
#STORM
major
TypeStorm
The TypeStorm parameter allows to set the storm: major, moderate, test.
#INNERBOUNDARY command
#INNERBOUNDARY
1e6
Height [m]
The Height parameter sets the altitude of the ionosphere-plasmashere boundary.
#ENERGYSETUP command
#ENERGYSETUP
0.1
0.006
1.26
EnergyLowerBoundary[keV]
LowestEnergyCellWidth [keV]
rw
The #ENERGYSETUP command allows to set the lower energy boundary (EnergyLowerBoundary), the
growth multiplier (GrowthMultiplier) of energy cell width ( WE(k+1)=WE(k)*rw), and the width of the
lowest energy cell (LowestEnergyCellWidth).
#SPECIES command
#SPECIES
T
T
T
T
T
F
F
UseElectron
UseHPlus
UseHePlus
UseOPlus
UseIon
UsePhotoelElectron
UsePlasmaSheetElectron
The #SPECIES command allows to set which species to be included into the simulation. PhotoelElectron
and PlasmaSheetElectron allow extra calculation for photo-electrons and plasma sheet electrons runs.
#INDICES command
#INDICES
1
0
15
154
WhichKp
Kp
ApIndex
SunspotAverage
The #KpINDEX command allows to set the Kp Index.
iKp
iKP
iKP
iKP
iKP
=
=
=
=
=
0
1
2
3
4
for Kp constant.
for Kp-DKP.
for Kp read from a table.
for A = 0.
Kp read from a file.
Or just set Kp to some value. ApIndex is the ApIndex index and SunspotAverage indicates the 13 month
sunspot average.
COMPONENT
157
#BOUNDARY command
#BOUNDARY
0
TypeBoundary
The #BOUNDARY command indicates which boundary conditions to use (to match to initial boundary
conditions)
0
1
2
3
4
5
6
7
9
-
Initialized to zero everywhere
Maxwellian distribution
Read FI and NI from file
Read FI and NI from file
Quiet ring current, constant with SunspotAverage, phi and pitch angle.
Read FI from file
Nightside injection
Read from .unff file. Use to reastart. No SOPA data.
Injection everywhere
#INITIAL command
#INITIAL
0
0.0
0.03
TypeInitial
MaxwellianScallingFactor
CharacteristicEnergy
The TypeInitial parameter indicates which initial conditions to use (to match to initial boundary conditions)for each species.
0
1
2
3
4
5
6
7
-
Initialized to zero everywhere
Loss Cone Distribution. Maxwellian distribution
Gaussian distribution in azimuth (phi) and SunspotAverage about some location.
Read distribution function from input file.
Quiet ring current, constant with SunspotAverage, phi and pitch angle.
Read distribution function from file (restart.bcf).
Nightside plasma sheet injection.
Read from .unff file. Use to reastart.
MaxwellianScallingFactor is the scalling factor for Maxwellian initial distribution. CharacteristicEnergy
is the characteristic energy for Initial*=1 (keV)
#OUTPUT command
#OUTPUT
T
F
T
F
F
F
T
F
T
F
F
DoSaveDistributionFunctionEverywhere
DoSaveEquatorialDistributionFunction
DoSaveEnergyDeposition
DoSaveTotalPrecipitationFlux
DoSaveDifferentialPrecipitationFlux
DoSaveParticleEnergyLosses
DoSaveThermalPlasmaDensity
DoSaveCflForAdvection
DoSaveDriftVelocities
DoSaveEvsLDistributions
DoSaveParticleLifetimes
158
T
T
T
T
F
DoSavePressureDensityDst
DoSaveUnformatted
DoSaveContinuousSourcesLosses
DoSaveNightsideBCDistribution
DoSaveDifferentialNumberFlux
The #OUTPUT command indicates the output options flag arrays:
DoSaveDistributionFunctionEverywhere
DoSaveEquatorialDistributionFunction
DoSaveEnergyDeposition
DoSaveTotalPrecipitationFlux
DoSaveDifferentialPrecipitationFlux
DoSaveParticleEnergyLosses
DoSaveThermalPlasmaDensity
DoSaveCflForAdvection
DoSaveDriftVelocities
DoSaveEvsLDistributions
DoSaveParticleLifetimes
DoSavePressureDensityDst
DoSaveUnformatted
DoSaveContinuousSourcesLosses
DoSaveNightsideBCDistribution
-
F throughout magnetosphere
Equ. trapped F throughout magnetosphere
Flux tube energy deposition
Total precipitation flux (3 E ranges)
Differential precipitation flux
Particle and energy losses
Thermal plasma densities
CFL numbers for advection operators
Drift velocities for advection
E vs. L distributions at given MLT and PA
Particle lifetimes
Pressures, densities, and Dst
Unformatted output of all Fs
Continuous sources and losses of number/energy
Nightside boundary condition distribution
Set DoSaveDifferentialNumberFlux to false to save the distribution function as opposed to the differenti
#OUTPUTINFO command
#OUTPUTINFO
99266
1800.
NameRun
nFrequency [sec]
The #OUTPUTFREQUENCY indicates the time interval between printouts. NameRun sets the prefix
of the output files. oFrequency represents the frequency the output is saved.
#INJECTIONFREQUENCY command
#INJECTIONFREQUENCY
120.
iFrequency [sec]
The #INJECTIONFREQUENCY indicates the time interval between injection BC updates (inject if
greater than 0)
#CONVECTION command
#CONVECTION
w96
TypeConvection
The TypeConvection parameter indicates how the magnetospheric convection strength is calculated. The
default value is shown. Other possibilities are
NoConvection
KpVSMaynardChen
MBIVS
- No convection field
- Kp driven V-S with Maynard and Chen activity dependence
- MBI driven V-S, acitivity from force balance at dusk
COMPONENT
159
McIlwain
McIlwainPlusCPCP
KpVSPlusBurkeWygant
McIlwainPlusBurkeWygant
McIlwainCPCPBurkeWygant
KpVSSelfConsintent
McIlwainSelfConsistent
McIlwainCPCPSelfConsistent
UnshieldedVSwithPen
UnshieldedVSnoPen
W96SC
W96
AMIESC
AMIE
ReadFromFile
AMIEPot
W96Pot
Foster
-
McIlwain field
McIlwain field, Eo driven by Cross Polar Cap Potential
Kp V-S field plus Burke-Wygant penetration field
McIlwain field plus Burke-Wygant penetration field
McIlwain(CPCP) field plus B-W penetration field
Kp V-S field plus self-consistent penetration field
McIlwain field plus self-consistent penetration field
McIlwain(CPCP) field plus S-C penetration field
Unshielded V-S(CPCP) field plus penetration field
Unshielded VS(CPCP) field (no Epen)
W96 field plus S-C penetration field
W96 field everywhere (done in S-C field block)
AMIE field plus S-C penetration field
AMIE field everywhere (done in S-C field block)
Read in electric field from a file
AMIE potentials everywhere
Weimer-96 potentials everywhere
Foster potentials everywhere
#INITIALTHERMALPLASMA command
#INITIALTHERMALPLASMA
F
DoReadDGCPM
If DoReadDGCPM set to false, is the thermal plasma is initialized by using 48hr of low activity. Needs to
be set to T for restart runs and the last dgcpm file moved to dgcpm.in.
#SOLARWIND command
#SOLARWIND
T
DoReadSolarWind
If set to ’True’, read solar wind input file.
#PITCHANGLE command
#PITCHANGLE
F
UseConstantStepPA
Only one of the options can be true at the same time. UseConstantStepPA sets constant steps in pitch
angle.Set to false, uses exact loss cone points.
#INCLUDEWAVES command
#INCLUDEWAVES
F
UseWaves
Set to true if self-consistent wave-particle interactions are to be included.
#BFIELD command
#BFIELD
analytic
uniform
TypeBField
TypeBFieldGrid
160
The TypeBField parameter sets up the magnetic field. If analytic, all numerical integrals are solved using
analytical approximations. If numerical, numerical integrals are performed. The TypeBFieldGrid parameter
sets up the kind of field line grid. For uniform grid, all point are evenly ditributed along the field line. For
non-uniform grid, the grid is more refined in the equatorial region.
#SAVERESTART
T
40.0
ascii
DoSaveRestart
DtSaveRestart
TypeFile
Default is DoSaveRestart=.true. with DtSaveRestart=-1. This results in the restart file being saved only at
the end. An ascii restart file is produced for every DtSaveRestart. Needs to be multiple of the time step. The
restart files are overwritten every time a new restart is done. The default directory name is ’restartOUT’.
5.6. INPUT COMMANDS FOR THE RICE CONVECTION MODEL 2: IM
COMPONENT
5.6
161
Input Commands for the Rice Convection Model 2: IM Component
5.6.1
Testing
#STRICT command
#STRICT
T
UseStrict
is true, ie. strict mode.
5.6.2
Output
#ASCII command
#ASCII
T
IsAscii
The input and output files for RCM can be either ascii or binary. Default value is true for ascii.
#RCMDIR command
#RCMDIR
IM
NameRcmDir
The NameRcmDir variable contains the name of the directory to store output files. Default value is ”IM”.
Don’t change this unless you know what you are doing.
#SAVEPLOTNAME
T
UseEvenPlotName
If UseEventPlotName is true, the names of the plot files will contain the event date and time in the YearMoDy HrMnSc format. If it is false, the simulation time is used in the HourMnSc format.
The default value is false.
#SAVEPLOT command
#SAVEPLOT
4
2d min idl
100
-1
3d max tec
-1
60
2d mc1 idl
100
-1
2d mc2 idl
100
-1
nFilesPlot
StringPlot
DnSavePlot
iDtSavePlot
StringPlot
DnSavePlot
iDtSavePlot
StringPlot
DnSavePlot
iDtSavePlot
StringPlot
DnSavePlot
iDtSavePlot
[sec]
[sec]
[sec]
[sec]
162
Default is nFilesPlot=0.
StringPlot must contain the following 3 parts (separated with space) in arbitrary order:
plotarea
= ’2d’, ’3d’
plotvar
= ’min’, ’max’, ’mc1’, ’mc2’
plotformat = ’tec’, ’idl’
The plotformat specifies whether to output files for processing in either Tecplot or Idl. Tecplot formatt is
ascii, idl is binary (therefore, more compact).
The plotarea string defines the region for the plots, 2d or 3d. Currently the 3D output is implemented for
Tecplot format only. 2d means writing variables on the two-dimensional ionospheric grid. 3d refers not to
the third spatial dimension but to the energy dependences (writing 3d is essentially writing the distribution
function of ring current population).
The plotvar string specifies which variables to write, either a minimum set, or a maximum set (the ’rcm’
string is preserved for backwards compatibility only, and it is the same as the ’max’ string), or one of the
custom sets ’mc1’ or ’mc2’. The ’min’ value corresponds to the variables ’rho T P rho(MHD) T(MHD)
P(MHD’ in 2D and to ’eeta veff’ in 3D.
The ’max’ value corresponds to a lot of variables in 2D. For Tecplot format they include the ’min’
variables, but for IDL format the ’max’ and ’min’ variables are distinct, so you need to specify two IDL plot
files to get all the variables. In 3D only the Tecplot format is available, and the ’max’ variable set contains
’bndloc Vm —B— V birk alam eeta veff w’.
The values ’mc1’ and ’mc2’ were originally designed to be used by CCMC. For 2d files, ’mc1’ and
’mc2’ mean the same thing and define a set of both ionospheric quantities (potential, field-aligned currents,
conductances) as well as plasma moments of the ring current species. For 3d, ’mc1’ and ’mc2’ will cause
output of full particle energy spectra (together with some extra variables); for ’mc1’, these spectra will be in
the form of flux-tube content (proportional to the phase space density), while for ’mc2’ it will be differential
particle fluxes.
The DnSavePlot and DtSavePlot integers define the plotting frequency in number of time steps and
number of seconds, respectively. A negative value -1 means that the frequency parameter is ignored. Note
that DtSavePlot must be a multiple of the time step iDtRcm (see the #TIMESTEP command).
5.6.3
Time integration
#RESTART command
#RESTART
T
DoRestart
The DoRestart parameter determines if the RCM starts from the restart files saved from a previous run, or
from scratch via the standard input files. The default is DoRestart = .false.
#TIMESTEP command
#TIMESTEP
5
iDtRcm
The iDtRcm parameter defines the time step in seconds. The default value is 5 seconds.
5.6.4
Physics parameters
#COMPOSITION command
#COMPOSITION
5.6. INPUT COMMANDS FOR THE RICE CONVECTION MODEL 2: IM
COMPONENT
0.7
0.3
163
FractionH
FractionO
Fractional composition in RCM of H+ and O+. The two need to add up to 1.0
#CHARGEEXCHANGE command
#CHARGEEXCHANGE
T
125.
169.
90.
UseChargeExchange
SunspotNumber
F107MonthlyMean
DayOfYear
Activate charge exchange in RCM and specify solar conditions. Default values are shown.
#OUTERBOUNDARY command
#OUTERBOUNDARY
ellipse
10.0
TypeBoundary
xMaxNight
Define the outer boundary for RCM. Options are ”max” that defines the whole closed field line region and
”ellipse” that is fitted inside the closed field line region. For ”ellipse” xMaxNight defines the furthest distance
in the magnetotail of the ellipse. Default values are shown.
#IONOSPHERE command
#IONOSPHERE
IE
TypeIonosphere
Define which ionosphere solver to use. Options are ”IE” (SWMF solver) or ”RCM” (internal solver). Default
is ”IE”.
#PRECIPITATION command
#PRECIPITATION
0.3
LossFactore
0.0
LossFactorH
0.0
LossFactorO
Parameter that controls, in a somewhat crude manner, the rate of particle precipitation into the atmosphere
(one for each species, total of 3). RCM code calculates the rate of precipitation in the limit of strong pitchangle scattering, and the factors here reduce this maximum possible rate. In other words, if the max. rate of
precipitation for electrons is R ele, then in the code the rate will be set to R ele*LossFactore. If LossFactor=0,
then there is no loss through precipitaton; if LossFactor=1, the precipitation is maximum possible. This
parameter is used in two places in the RCM: one is a loss process for hot magnetospheric population (righthand side of the advection equation), the other one is to evaluate conductance enhancements in the auroral
oval (in the module that computes conductances).
#TEMPERATURE command
#TEMPERATURE
3.0
TemperatureFactor
Artificially increase the temperature obtained from the magnetosphere model. Default value is 1, i.e. no
change.
164
#DECAY command
#DECAY
F
36000.
UseDecay
DecayTimescale in seconds
Add a decay to the ring current vi exp(-(deltaT/DecayTimescale))
5.7. INPUT COMMANDS FOR THE DGCPM: PS COMPONENT
5.7
165
Input Commands for the DGCPM: PS Component
List of PS commands used in the PARAM.in file.
5.7.1
Stand alone mode
Options for configuring the model in stand-alone mode (no SWMF-interface.) Many of these are required if
DGCPM is not called from the SWMF, redundant otherwise.
5.7.2
Numerical scheme
Options for configuring the schemes and solvers, boundary conditions, and other numerical options.
#TIMESTEP command
#TIMESTEP
10.0
DtStep
Set the timestep for the simulation. Default values are shown.
5.7.3
Physical parameters
#FILLING command
#FILLING
3.0
EmptyPeriodClosed
1.0
EmptyPeriodOpen
1.5
FillDays
2.0E12 FluxMax
Set parameters that control flux tube refilling rate.
5.7.4
Output parameters
#MLTSLICE command
#MLTSLICE
4
nMltSlice
300.0
DtMltSlice
Save output extracted at a number (nMltSlice) of evenly spaced lines of constant MLT at a cadence of
DtMltSlice seconds. Each slice will have its own file. For example, if nMltSlice is set to 4, output will
extracted at 00, 06, 12, and 18 MLT. The current limitation is that no interpolation is made, therefore the
total number of azimuthal cells (default is 120) must be evenly divisible by nMltSlice. Default values are
shown.
166
5.8
Input Commands for the PWOM: PW Component
List of PW commands used in the PARAM.in file
5.8.1
Numerical scheme
#SCHEME command
#SCHEME
Godunov
0.05
F
F
F
TypeSolver
DtVertical
IsFullyImplicit
IsPointImplicit
IsPointImplicitAll
TypeSolver sets the type of solver which is to be used. Currently only two options are available: Godunov and
Rusanov. DtVertical sets the time step for plasma propagating along the field line. IsFullyImplicit determines
whether the fully implicit time stepping is used. If not, the last two parameters are also read. IsPointImplicit
determines if the point implicit scheme is used or not for the collision terms. IsPointImplicitAll is true if all
terms are point implicit.
The default values are shown.
#LIMITER command
#LIMITER
1.5
LimiterBeta
Sets the beta parameter in the Rusanov scheme.
#DIFFUSION command
#DIFFUSION
LaxFriedrichs
TypeDiffusion
Sets the type of diffusion for use in the Rusanov scheme. The other option is LocalLaxFriedrichs. The
default is shown.
#VERTICALGRID command
#VERTICALGRID
390
2e6
nPoints
DeltaR
Sets the number of grid points in the vertical direction and the grid spacing.
#STARTTIME command
#STARTTIME
2006
7
19
0
0
0
iYear
iMonth
iDay
iHour
iMinute
iSecond
5.8. INPUT COMMANDS FOR THE PWOM: PW COMPONENT
167
The STARTTIME command sets the integer year, month, day, hour, minute and second at which the
simulation begins. This command is only used in standalone mode.
#TIMEACCURATE
T
DoTimeAccurate
DoTimAccurate determines if the field lines are solved in time accurate mode or in steady state mode.
#TIMESTEP command
#TIMESTEP
50
DtHorizontal
DtHorizontal is the timestep for horizontal motion of the field line. Default value is shown.
#VARIABLEDT command
#VARIABLEDT
F
IsVariableDt
When IsVariableDt=T then the vertical timestep is variable based on the change in pressure.
#MOTION command
#MOTION
T
DoMoveLine
This command determines which to move the field lines as determined by the horizontal convection, or to
hold them in their initial locations. The default value is shown.
#ROTATION command
#ROTATION
T
UseCentrifugalForce
This command determines whether centrifugal forces should be included. The default is shown.
#FAC command
#FAC
F
UseJr
UseJr determines whether to use field aligned currents to affect the ion outflow. The default is shown.
5.8.2
Input/output
#TEST command
#TEST
PW_move_line
0
2
StringTest
iProcTest
iLineTest
Set test parameters. The subroutines to be tested are listed in StringTest, the tested processor is iProcTest,
and the tested field line is iLineTest. If iLineTest is 0, all field lines produce test output.
Default is an empty StringTest, i.e. no test output is produced.
168
#FIELDLINE command
#FIELDLINE
1
nTotalLine
nTotalLine sets the number of field lines included in the simulation. The default is shown.
#RESTART command
#RESTART
T
IsRestart
If the IsRestart variable is true, then the PWOM uses a restart file. Otherwise, the PWOM uses a cold start
routine. The default is shown.
#SAVEPLOT command
#SAVEPLOT
10.0
-1
T
DtSavePlot
DnSavePlot
DoSaveFirst
The frequency which plot files are written out are defined here. As is whether or not to save a plot on the
first call. The default values are given.
#SAVEPLOTELECTRODYNAMICS command
#SAVEPLOTELECTRODYNAMICS
F
DoPlotElectrodynamics
10
DtPlotElectrodynamics
DoPlotElectrodynamics determines whether the electrodynmics plot information is saved. For instance the
field aligned currents, and the polar cap potental can be saved with this command. The frequency of output
is determined by the DtPlotElectrodynamics parameter.
#STATICATMOSPHERE command
#STATICATMOSPHERE
T
UseStaticAtmosphere
To keep the MSIS atmosphere constant set UseStaticAtmosphere to True.
#MSISPARAM command
#MSISPARAM
60
60
4
4
4
4
4
4
4
F107
F107A
AP(1)
AP(2)
AP(3)
AP(4)
AP(5)
AP(6)
AP(7)
This command sets the MSIS parameters for the the neutral atmosphere. The defaults are shown.
5.8. INPUT COMMANDS FOR THE PWOM: PW COMPONENT
169
#NGDC INDICES command
#NGDC_INDICES
ApFile.dat
NameNgdcFile
Read the Ap Index from a file and calculate the appropriate array of AP indices to feed to MSIS.
#NOAAHPI INDICES command
#NGDCHPI_INDICES
HpiFile.dat
NameHpiFile
Read the HPI from a file. Used to get the Auroral ionization and heating
#HPI command
#HPI
0
HemisphericPower
Set the HPI to a constant value. Used to get the Auroral ionization and heating
#AURORA command
#AURORA
F
UseAurora
Set whether or not to include auroral ionization and bulk heating.
#SOLARWIND command
#SOLARWIND
0
0
0
400
bx
by
bz
vx
This command sets the solar wind parameters for the Weimer model. The solar wind parameters are constant
if this command is used
#MHD INDICES command
#MHD_INDICES
IMF.dat
UpstreamFile
Read the IMF from a file. Unlike the SOLARWIND command, the imf can be time dependant in this case.
#END command
#END
170
#STOP command
#STOP
10
-1
Tmax
MaxStep
The #STOP command sets the stopping condition for the PWOM during standalone execution. Tmax
sets the stop time in timeaccurate mode. and MaxStep sets the maximum number of iterations for nontimeaccurate mode.
5.9. INPUT COMMANDS FOR THE RBE: RB COMPONENT
5.9
171
Input Commands for the RBE: RB Component
List of RB commands used in the PARAM.in file
5.9.1
Numerical scheme
#SPLITING command
#SPLITING
F
F
UseSplitting
UseCentralDiff
The SPLITING command determines whether the drift equations are solved using a dimensionally split or
unsplit version of the solver. Also whether or not central differencing is used is set here.
The default values are shown.
#TIMESTEP command
#TIMESTEP
3
Dt
Dt is the timestep of the calculation.
Default value is shown.
#LIMITER command
#LIMITER
F
2
UseMcLimiter
BetaLimiter
Set whether or not the MC limiter is used. If it is not, the super bee limiter is used. Also set the Beta
parameter for the MC limiter. The default value is shown.
#TIMESIMULATION
0.0
TimeSimulation
This command specifies the simulation time.
#SPECIES command
#SPECIES
e
NameSpecies
Determine whether electrons or protons are solved for in RBE. The default is shown.
#BMODEL command
#BMODEL
MHD
F
NameModel
UseFixedB
The type of magnetic field is used (t96, t04, or MHD).
172
#IEMODEL command
#IEMODEL
1
iConvect
The model for determining convection is set. 1 for Weimer and 2 for MHD
#PLASMASPHERE command
#PLASMASPHERE
F
UsePlasmaSphere
Command determines whether the plasmasphere is used.
#STARTUPTIME command
#STARTUPTIME
0.0
tStartup
Startup time for RBE model.
5.9.2
Input/output
#INPUTDATA command
#INPUTDATA
2000f223
NameStorm
The name of the input data associated with the storm
#SAVEPLOT command
#SAVEPLOT
2
F
2000f223
DtSavePlot
UseSeparatePlotFiles
OutName (read if UseSeparatePlotFiles is false)
Define frequency and output name of plots.
#PLOTELECTRODYNAMICS command
#PLOTELECTRODYNAMICS
F
DoSaveIe
Determine whether or not to save IE output. The frequency is defined in the SAVEPLOT command.
#RESTART command
#RESTART
F
IsRestart
Determine whether or not to continue a previous run.
5.9. INPUT COMMANDS FOR THE RBE: RB COMPONENT
173
#END command
#END
174
5.10
Input Commands for the Kota Solar Energetic Particle Model:
SP Component
5.10.1
Testing
#VERBOSE command
#VERBOSE
0
iVerbose
information to STDOUT.
5.10.2
Output
#PLOT command
#PLOT
5
DnPlot
The DnPlot parameter defines the frequency for saving the information to file. Default value is 5.
5.10.3
Magnetic field lines
#LINE command
#LINE
0.0
0.0
0.0
1.1
21.0
xLine
yLine
zLine
rBoundSc
rBoundIh
[Rs]
[Rs]
[Rs]
[Rs]
[Rs]
The xLine, yLine and zLine are the coordinates of the starting point of the magnetic field line given in units
of solar radii (Rs) in the Heliographic Inertial (HGI) frame of reference. If the starting point is given as
all zeros, which is the center of the Sun (or any position inside the Sun), then the starting point is set to
coincide with the position of the Earth at the time the SP component is switched on. The default values are
zero for these 3 variables.
The rBoundSc variable defines the radius of a sphere, inside which the points of the magnetic field line
are considered as not belonging to the Solar Corona. The integration of the original magnetic field line is
from the starting point towards the Sun. On reaching the surface of the radius of rBoundSc, the integration
inside the SC component stops. The default value is rBoundSc = 1.1 [Rs].
The rBoundIh variable defines the radius of a sphere, inside which the points of the magnetic field line
are considered as not belonging to the Inner Heliosphere. The integration of the original magnetic field line is
from the starting point towards the Sun. On reaching the surface of the radius of rBoundIh, the integration
inside the IH component stops. The default value is rBoundIh = 21.0 [Rs].
5.10.4
Control
#DORUN command
#DORUN
T
DoRun
When DoRun is set to the value .false., the component skips all computations. The default value is true, i.e.
computations are performed.
5.10. INPUT COMMANDS FOR THE KOTA SOLAR ENERGETIC PARTICLE MODEL:
SP COMPONENT
175
#SAVEMHDATA command
#SAVEMHDATA
F
DoSaveMhData
When DoSaveMhData is true, the SEP code saves all the MHD data coming from the coupler(s). Setting
DoRun=.false. (or .true.) and SaveMhData=.true. one can perform (or repeat) complete run for SP only,
without running the other components.
Default value is false.
#DOREADMHDATA command
#DOREADMHDATA
F
DoReadMhData
When .true. the SP component is expected to work as a single component or at least it is assumed not to be
coupled with an MHD model. The MHD data are read from the flat files in this case, rather than received
through the couplers. Default value is false.
5.10.5
Shock wave sensor
#RTRANSIENT command
#RTRANSIENT
1.0
rTransient [Rs]
The code searches for the shock wave at a distance larger than rTransient from the Solar center. The
rTransient is given in units of solar radii. Default value is 1.
#NSMOOTH command
#NSMOOTH
0
nSmooth
Usually the MHD data from the coupler contains some spurious oscillation. If nSmooth > 0, the SP code
repeats some smoothing procedure nSmooth times for the data obtained from the coupler. Default value is
0.
Index
CON
#CHECKSTOP, 54
#CHECKSTOPFILE, 55
#COMPONENT, 57
#COUPLE1, 59
#COUPLE1SHIFT, 59
#COUPLE1TIGHT, 60
#COUPLE2, 59
#COUPLE2SHIFT, 60
#COUPLE2TIGHT, 61
#COUPLEORDER, 58
#COUPLETIME, 61
#CPUTIMEMAX, 55
#CYCLE, 57
#DESCRIPTION, 52
#DIPOLE, 65
#ECHO, 62
#END, 52
#ENDTIME, 53
#FLUSH, 62
#IDEALAXES, 65
#INCLUDE, 52
#MAGNETICAXIS, 64
#MAGNETICCENTER, 65
#NSTEP, 54
#PLANET, 63
#PRECISION, 57
#PROGRESS, 56
#RESTARTFILE, 61
#ROTATEHGI, 63
#ROTATEHGR, 63
#ROTATION, 64
#ROTATIONAXIS, 64
#RUN, 52
#SAVERESTART, 61
#STARTTIME, 53
#STDOUT, 62
#STDOUTDIR, 63
#STOP, 54
#STRICT, 52
#TEST, 55
#TESTPROC, 55
#TESTTIME, 55
#TIMEACCURATE, 53
#TIMESIMULATION, 54
#TIMESTEP, 66
#TIMING, 56
#UPDATEB0, 65
#VERBOSE, 56
#VERSION, 57
GM,SC,IH/BATSRUS
#ACTIVEREGIONHEATING, 145
#ADVECTWAVES, 147
#ALFVENWAVES, 147
#AMR, 112
#AMRCRITERIA, 112
#AMRCRITERIALEVEL, 113
#AMRINITPHYSICS, 106
#AMRLEVELS, 111
#AMRLIMIT, 112
#AMRREGION, 106
#AMRRESOLUTION, 111
#ANISOTROPICPRESSURE, 138
#BEGIN COMP, 68
#BIERMANNBATTERY, 137
#BLOCKLEVELSRELOADED, 74
#BODY, 134
#BORIS, 125
#BORISSIMPLE, 125
#BUFFERGRID, 78
#CHECKGRIDSIZE, 74
#CHECKSTOPFILE, 92
#CLIMIT, 124
#CODEVERSION, 73
#COLLISION, 122
#COMPONENT, 67
#CONSERVATIVECRITERIA, 118
#CONTROLDECREASE, 119
#CONTROLFACTOR, 120
#CONTROLINCREASE, 120
#CONTROLINIT, 119
#CONTROLTIMESTEP, 119
#CONTROLVAR, 119
176
INDEX
#COORDSYSTEM, 81
#CORONALHEATING, 144
#CORRECTP, 127
#CPCPBOUNDARY, 80
#CPUTIMEMAX, 92
#DEBUG, 73
#DESCRIPTION, 67
#DIPOLE, 70
#DIPOLEBODY2, 142
#DIVB, 126
#DIVBSOURCE, 126
#DOAMR, 111
#ECHO, 67
#ELECTRONPRESSURE, 138
#EMPIRICALSW, 143
#END, 69
#END COMP, 68
#EQUATION, 74
#EXTRABOUNDARY, 79
#EXTRAINTERNALENERGY, 138
#FACEBOUNDARY, 79
#FIXAXIS, 83
#FIXEDTIMESTEP, 85
#FLATTENING, 117
#FLUSH, 106
#GAMMA, 130
#GEOMAGINDICES, 97
#GRAVITY, 135
#GRID, 80
#GRIDGEOMETRY, 82
#GRIDRESOLUTION, 108
#GRIDSYMMETRY, 81
#HALLREGION, 136
#HALLRESISTIVITY, 136
#HEATCONDUCTION, 140
#HEATFLUXLIMITER, 139
#HEATFLUXREGION, 141
#HELIOBUFFERGRID, 146
#HELIODIPOLE, 146
#HELIOUPDATEB0, 146
#HYPERBOLICDIVB, 126
#IDEALAXES, 71
#IE, 128
#IECOUPLING, 128
#IM, 129
#IMCOUPLING, 129
#IMCOUPLINGSMOOTH, 80
#IMPLCHECK, 89
#IMPLICIT, 86
#IMPLICITCRITERIA, 87
#IMPLICITENERGY, 87
177
#IMPLSCHEME, 89
#IMPLSTEP, 88
#INCLUDE, 147
#INNERBOUNDARY, 78
#IONHEATCONDUCTION, 141
#IOUNITS, 76
#JACOBIAN, 89
#KRYLOV, 91
#KRYLOVSIZE, 91
#LASERBEAM, 140
#LASERBEAMPROFILE, 140
#LASERBEAMS, 139
#LASERPULSE, 139
#LDEM, 143
#LIMITER, 124
#LIMITRADIUS, 82
#LOCALTIMESTEP, 68
#LONGSCALEHEATING, 144
#LOOKUPTABLE, 131
#MAGNETICAXIS, 70
#MAGNETICCENTER, 70
#MAGNETICINNERBOUNDARY, 78
#MAGNETOGRAM, 142
#MAGNETOMETER, 97
#MASSLOADING, 140
#MESSAGEPASS, 123
#MHDIONS, 122
#MINIMUMDENSITY, 137
#MINIMUMPRESSURE, 137
#MULTIFLUIDIM, 129
#MULTIION, 121
#MULTIIONSTATE, 122
#MULTISPECIES, 121
#NEUTRALFLUID, 121
#NEWRESTART, 77
#NEWTON, 89
#NONCONSERVATIVE, 117
#NORMALIZATION, 75
#NPREVIOUS, 84
#NSTEP, 84
#OPENCLOSEDHEAT, 145
#OUTERBOUNDARY, 77
#OUTFLOWPRESSURE, 77
#PARTIMPL, 88
#PARTSTEADY, 85
#PARTSTEADYCRITERIA, 85
#PLANET, 69
#PLASMA, 130
#PLOTDIR, 93
#PLOTFILENAME, 105
#POINTIMPLICIT, 86
178
INDEX
#POLARBOUNDARY, 80
#PRECISION, 74
#PRECONDITIONER, 90
#PROGRESS, 67
#PROJECTION, 126
#RADIATION, 138
#RADIATIVECOOLING, 145
#RAYTRACE, 127
#RAYTRACELIMIT, 128
#READPOTENTIALFIELD, 143
#RESCHANGE, 124
#RESISTIVEREGION, 136
#RESISTIVITY, 135
#RESISTIVITYOPTIONS, 136
#RESOLUTIONCHANGE, 123
#RESTARTINDIR, 76
#RESTARTINFILE, 76
#RESTARTOUTDIR, 93
#RESTARTOUTFILE, 93
#ROTATION, 70
#ROTATIONAXIS, 69
#RUN, 68
#SATELLITE, 95
#SAVEBINARY, 105
#SAVEINITIAL, 105
#SAVELOGFILE, 93
#SAVELOGNAME, 105
#SAVEPLOT, 98
#SAVEPLOTNAME, 104
#SAVEPLOTSAMR, 106
#SAVERESTART, 93
#SCHEME, 115
#SCHEME4, 116
#SECONDBODY, 141
#SEMICOEFF, 88
#SEMIIMPLICIT, 87
#SEMIKRYLOV, 91
#SEMIKRYLOVSIZE, 92
#SEMIPRECONDITIONER, 90
#SHOCKPOSITION, 132
#SHOCKTUBE, 132
#SOLARWIND, 133
#SOLARWINDFILE, 133
#STARTTIME, 83
#STEADYSTATESATELLITE, 96
#STOP, 92
#STRICT, 73
#TEST, 72
#TESTDIM, 73
#TESTIJK, 72
#TESTTIME, 72
#TESTVAR, 72
#TESTXYZ, 72
#THINCURRENTSHEET, 146
#TIMEACCURATE, 68
#TIMESIMULATION, 83
#TIMESTEPPING, 84
#TIMING, 74
#TRANSITIONREGION, 145
#TVDRESCHANGE, 124
#UNIFORMAXIS, 82
#UNIFORMSTATE, 132
#UPDATEB0, 70
#UPDATECHECK, 118
#USEB0, 125
#USECURLB0, 125
#USERFLAGS, 71
#USERINPUTBEGIN, 71
#USERINPUTEND, 71
#USERMODULE, 73
#VERBOSE, 73
#WSACOEFF, 143
IE/Ridley serial
#AMIEFILES, 151
#BACKGROUND, 151
#BOUNDARY, 151
#CONDUCTANCE, 151
#DEBUG, 148
#GEOMAGINDICES, 150
#IM, 150
#IONODIR, 148
#IONOSPHERE, 149
#KRYLOV, 152
#MAGNETOMETER, 150
#SAVELOGFILE, 149
#SAVELOGNAME, 149
#SAVEPLOT, 148
#SAVEPLOTNAME, 149
#SOLVER, 152
#SPS, 151
#STRICT, 148
#UA, 151
IM/CRCM
#END, 154
#INITIALF2, 154
#LIMITER, 153
#MINIMUMPRESSURETOGM, 154
#RESTART, 154
#SAVELOG, 153
#SAVEPLOT, 153
#TIMESIMULATION, 153
INDEX
#TYPEBOUNDARY, 153
IM/HEIDI
#BFIELD, 159
#BOUNDARY, 157
#CONVECTION, 158
#ENERGYSETUP, 156
#GRID, 155
#INCLUDEWAVES, 159
#INDICES, 156
#INITIAL, 157
#INITIALTHERMALPLASMA, 159
#INJECTIONFREQUENCY, 158
#INNERBOUNDARY, 156
#OUTPUT, 157
#OUTPUTINFO, 158
#PITCHANGLE, 159
#SAVERESTART, 160
#SOLARWIND, 159
#SPECIES, 156
#STARTTIME, 155
#STOP, 155
#STORM, 156
#TIMESTEP, 155
IM/RCM2
#ASCII, 161
#CHARGEEXCHANGE, 163
#COMPOSITION, 162
#DECAY, 164
#IONOSPHERE, 163
#OUTERBOUNDARY, 163
#PRECIPITATION, 163
#RCMDIR, 161
#RESTART, 162
#SAVEPLOT, 161
#SAVEPLOTNAME, 161
#STRICT, 161
#TEMPERATURE, 163
#TIMESTEP, 162
PS/DGCPM
#FILLING, 165
#MLTSLICE, 165
#TIMESTEP, 165
PW/PWOM
#AURORA, 169
#DIFFUSION, 166
#END, 169
#FAC, 167
#FIELDLINE, 168
#HPI, 169
#LIMITER, 166
179
#MHD INDICES, 169
#MOTION, 167
#MSISPARAM, 168
#NGDC INDICES, 169
#NOAAHPI INDICES, 169
#RESTART, 168
#ROTATION, 167
#SAVEPLOT, 168
#SAVEPLOTELECTRODYNAMICS, 168
#SCHEME, 166
#SOLARWIND, 169
#STARTTIME, 166
#STATICATMOSPHERE, 168
#STOP, 170
#TEST, 167
#TIMEACCURATE, 167
#TIMESTEP, 167
#VARIABLEDT, 167
#VERTICALGRID, 166
RB/RBE
#BMODEL, 171
#END, 173
#IEMODEL, 172
#INPUTDATA, 172
#LIMITER, 171
#PLASMASPHERE, 172
#PLOTELECTRODYNAMICS, 172
#RESTART, 172
#SAVEPLOT, 172
#SPECIES, 171
#SPLITING, 171
#STARTUPTIME, 172
#TIMESIMULATION, 171
#TIMESTEP, 171
SP/Kota
#DOREADMHDATA, 175
#DORUN, 174
#LINE, 174
#NSMOOTH, 175
#PLOT, 174
#RTRANSIENT, 175
#SAVEMHDATA, 175
#VERBOSE, 174

Space Weather Modeling Framework User Manual Code Version 2.4

Transcription

Similar documents

How to Upgrade KU-007 Plus firmware

1: Boot from DVD. 2: Click on Setting Icon→ Disk tools→Disk Utility 3

STAY IN THE ! RED LETTERS

EurekaWeb - Eureka Support

Veterans Day 2013 - St Thomas Historical Trust

File

Creating Procedures in Blackcat Logo

Data sheet - Marvin Test Solutions, Inc.

MediaStar IR Blaster Module (911-4153)

Heritage Category: Listing List Entry No : 1227165 Grade: II County