Makeitso – Use for MAGE without TIEGCM

Introduction

The Python script makeitso.py was developed to simplify the process of configuring and running GR MAGE (that is, the geospace application of the kaiju software without TIEGCM.) It provides an interactive, prompt-driven interface to specify all of the parameters needed for a model run.

The makeitso.py script can operate in one of three different modes: BASIC, INTERMEDIATE, or EXPERT. Each mode provides access to a subset of the kaiju parameters. The BASIC mode requires the user to provide the minimum set of parameters needed to specify a model run, such as the run ID, and the simulation time period. The INTERMEDIATE mode allows the user to specify all of the parameters from the BASIC mode, as well as a wider set of run parameters, such as non-standard file locations and some MHD parameters. The EXPERT mode provides access to all of the user-adjustable parameters from the kaiju software. When finished, the script generates the files needed to run a magnetosphere model, and saves all options in a convenient JSON file so that the run can be repeated at a later date.

Running the makeitso.py script

The makeitso.py script is provided as part of the kaiju software. It is found at $KAIJUHOME/scripts/makeitso/makeitso.py, where $KAIJUHOME is the location of your kaiju software tree. After configuring your kaiju software, you can get help text for the script like this:

makeitso.py --help
usage: makeitso.py [-h] [--clobber] [--debug] [--mode MODE] [--options_path OPTIONS_PATH] [--verbose]

Interactive script to prepare a MAGE magnetosphere model run.

optional arguments:
  -h, --help            show this help message and exit
  --clobber             Overwrite existing options file (default: False).
  --debug, -d           Print debugging output (default: False).
  --mode MODE           User mode (BASIC|INTERMEDIATE|EXPERT) (default: BASIC).
  --options_path OPTIONS_PATH, -o OPTIONS_PATH
                        Path to JSON file of options (default: None)
  --verbose, -v         Print verbose output (default: False).

The --options_path option allows the user to specify an existing JSON file from a previous run of makeitso.py so that the entire process of model generation can be automated. The --mode option specifies the user mode to run in, with BASIC being the default.

An example in BASIC mode

This section provdes an annotated example session of makeitso.py running in the default BASIC mode on the aitken supercomputer.

makeitso.py
Name to use for PBS job(s) [geospace]:

Enter an identifying string to use for your model run. This name will be used as the basis for most of the files created by makeitso.py and the kaiju software. The default name is geospace.

Do you have an existing boundary condition file to use? (Y|N) [N]:

If you already have a file containing solar wind data to use for the inner boundary conditions of your simulation, enter Y, and you will then be prompted for the path top the file. If you don’t have the file, enter N and you will be prompted for the date range to use.

Start date for simulation (yyyy-mm-ddThh:mm:ss) [2016-08-09T09:00:00]:
Stop date for simulation (yyyy-mm-ddThh:mm:ss) [2016-08-09T11:00:00]:

Enter the start and stop date and time for the solar wind data you want to use. The required data will be fetched from CDAWeb, and converted into a format usable by the kaiju software.

Do you want to split your job into multiple segments? (Y|N) [N]:

Enter Y here if you want to split your simulation into multiple PBS jobs. This will allow you to run long simulations that are chained together, with each using the results of the previous job as a starting point. If you enter Y, you will be prompted for segment length (in simulated time).

GAMERA grid type (D|Q|O|H) [Q]:

The codes represent double- (D), quad- (Q), oct- (O) and hex- (H) resolutions in the LFM grid used in the kaiju software.

Name of HPC system (derecho|aitken) [aitken]:

The makeitso.py script supports the derecho and aitken supercomputers. The selection you make here will customize the remaining prompts for the selected system.

PBS account name [your_login_name]:

On aitken, your login name is usable here. On derecho, you will need a PBS account ID.

Run directory [.]:

Specify the directory that you wish to perform the simulation in. The directory will contain all of the files generated by makeitso.py.

Path to kaiju installation [YOUR_PATH_HERE]:
Path to kaiju build directory [YOUR_PATH_HERE]:

Enter the paths to the location of your kaiju code, and the location of your kaiju build directory.

PBS queue name (low|normal|long|debug|devel) [normal]:

Select a PBS queue to use on the selected supercomputer.

You are responsible for ensuring that the wall time is sufficient
to run a segment of your simulation! Requested wall time for each PBS job
segment (HH:MM:SS) [01:00:00]:

Specify the wall clock time to request for your job (or each segment, if you split your job into multiple segments).

(GAMERA) Relative path to HDF5 file containing solar wind boundary conditions [bcwind.h5]:

This is the path to your existing solar wind file, or the path that makeitso.py will use to create the file.

(VOLTRON) File output cadence in simulated seconds [60.0]:

How often (in simulated seconds) the kaiju software should output results during the course of the simulation.

The script then runs several additional tools to prepare the files needed for your simulation. This includes input files, as well as PBS job scripts for your simulation, and a bash shell script to submit the PBS jobs.

Running preprocessing steps.
Generating Quad LFM-style grid ...

Output: lfmQ.h5
Size: (96,96,128)
Inner Radius: 2.000000
Sunward Outer Radius: 30.000000
Tail Outer Radius: 322.511578
Low-lat BC: 45.000000
Ring params:
<ring gid="lfm" doRing="T" Nr="8" Nc1="8" Nc2="16" Nc3="32" Nc4="32" Nc5="64" Nc6="64" Nc7="64" Nc8="64"/>

Writing to lfmQ.h5
Retrieving f10.7 data from CDAWeb
Retrieving solar wind data from CDAWeb
        Using Bx fields
Bx Fit Coefficients are  [-3.78792744 -0.77915822 -1.0774984 ]
Saving "OMNI_HRO_1MIN.txt_bxFit.png"
Converting to Gamera solar wind file
        Found 21 variables and 120 lines
        Offsetting from LFM start ( 0.00 min) to Gamera start ( 0.00 min)
Saving "OMNI_HRO_1MIN.txt.png"
Writing Gamera solar wind to bcwind.h5
Reading /glade/derecho/scratch/ewinter/cgs/aplkaiju/kaipy-private/development/kaipy-private/kaipy/rcm/dktable
Reading /glade/derecho/scratch/ewinter/cgs/aplkaiju/kaipy-private/development/kaipy-private/kaipy/rcm/wmutils/chorus_polynomial.txt
Dimension of parameters in Chorus wave model, Kp: 6 MLT: 97 L: 41 Ek: 155
Wrote RCM configuration to rcmconfig.h5
Creating .ini file(s) for run.
Converting .ini file(s) to .xml file(s).


Template creation complete!


Creating PBS job script(s) for run.
The PBS job scripts ['./geospace-00.pbs'] are ready.
The PBS scripts ['./geospace-00.pbs'] have been created, each with a corresponding XML file. To submit the jobs with the proper dependency (to ensure each segment runs in order), please run the script geospace_pbs.sh like this:
bash geospace_pbs.sh

When finished, the script creates the file runid.json, where runid is the identifying string for your simulation. This file contains a record of all of the parameters used in your simulation. This file can be passed back to makeitso.py in a subsequent session to repeat the simulation, and also provides a convenient starting point for minor tweaks to your simulation parameters.

Additional parameters in INTERMEDIATE and EXPERT mode

Many more parameters are available in INTERMEDIATE and EXPERT modes. These parameters are documented in the file option_descriptions.json, which is stored in the same directory as the makeitso.py script.