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: .. code-block:: bash 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. .. code-block:: bash 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``. .. code-block:: bash 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. .. code-block:: bash 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. .. code-block:: bash 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). .. code-block:: bash 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. .. code-block:: bash 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. .. code-block:: bash PBS account name [your_login_name]: On ``aitken``, your login name is usable here. On ``derecho``, you will need a PBS account ID. .. code-block:: bash 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``. .. code-block:: bash 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. .. code-block:: bash PBS queue name (low|normal|long|debug|devel) [normal]: Select a PBS queue to use on the selected supercomputer. .. code-block:: bash 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). .. code-block:: bash (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. .. code-block:: bash (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. .. code-block:: bash 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: 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.