Makeitso-gamhelio – Use for GAMERA-Helio

The Python script makeits-gamhelio.py was developed to simplify the process of configuring and running GAMERA-helio (that is, the inner heliosphere applicatoin of the kaiju software.) It provides an interactive, prompt-driven interface to specify all of the parameters needed for a model run.

The makeitso-gamhelio.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 helioosphere model, and saves all options in a convenient JSON file so that the run can be repeated at a later date.

Running the makeitso-gamhelio.py script

The makeitso-gamhelio.py script is provided as part of the kaiju software. It is found at $KAIJUHOME/scripts/makeitso-gamhelio/makeitso-gamhelio.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-gamhelio.py --help
usage: makeitso-gamhelio.py [-h] [--clobber] [--debug] [--mode MODE] [--options_path OPTIONS_PATH] [--verbose]

Interactive script to prepare a GAMERA heliosphere 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-gamhelio.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-gamhelio.py running in the default BASIC mode.

makeitso-gamhelio.py --verbose
Name to use for PBS job(s) [helio]:

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-gamhelio.py and the kaiju software. The default name is helio.

Path to WSA boundary condition file to use [wsa.fits]:

Enter the path to the FITS file that contains output from the WSA model for use as the inner boundary conditions.

Start date for simulation (yyyy-mm-ddThh:mm:ss) [2017-07-20T05:22:47]:
Stop date for simulation (yyyy-mm-ddThh:mm:ss) [2017-08-16T12:05:59]:

Enter the start and stop date and time for the simulation.

Do you want to split your job into multiple segments? (Y|y|N|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).

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

The makeitso-gamhelio.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.

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.

Run directory [.]:

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

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

Select a PBS queue to use on the selected supercomputer.

WARNING: 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).

Number of radial grid cells [128]:
Number of polar angle grid cells [64]:
Number of azimuthal angle grid cells [128]:

Specify the number of grid cells to use in each dimension of the spherical coordinate system used to define the simulation.

Running preprocessing steps.
Creating .ini file(s) for run.
Converting .ini file(s) to .xml file(s).

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.

Template creation complete!


Creating PBS job script(s) for run.
The PBS job scripts ['./helio-00.pbs'] are ready.
The PBS scripts ['./helio-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 helio_pbs.sh like this:
bash helio_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-gamhelio.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-gamhelio.py script.