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:

.. code-block:: bash

    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.

.. code-block:: bash

    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``.

.. code-block:: bash

    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.

.. code-block:: bash

    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.

.. code-block:: bash

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

.. code-block:: bash

    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.

.. 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

  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

  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``.

.. 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

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

.. code-block:: bash

    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.

.. code-block:: bash

    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.

.. code-block:: bash

    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.