Running AthenaK
===============

After building the code, an executable named ``athena`` will be created in the
``build/src`` subdirectory. To run it, an input file must also be specified on the
command line, e.g.

.. code-block:: bash

   athena -i example.athinput

Examples of input files can be found in the ``inputs/`` subdirectory. Input files that
work with the built-in test problems can be found in ``inputs/tests``.

When the code runs, all output files are created in the current working directory by
default. The code will output simulation progress and some diagnosis messages to
stdout.

Command-line options
--------------------

A variety of command-line options have been implemented in AthenaK. The list of the
options as well as the code configuration is given by the ``-h`` switch:

.. code-block:: text

   $ athena -h
   Athena v0.1
   Usage: athena [options] [block/par=value ...]
   Options:
     -i <file>       specify input file [athinput]
     -r <file>       restart with this file
     -d <directory>  specify run dir [current dir]
     -n              parse input file and quit
     -c              show configuration and quit
     -m              output mesh structure and quit
     -t hh:mm:ss     wall time limit for final output
     -h              this help

Overriding parameters in the input file
---------------------------------------

Some parameter values specified in the input file can be overridden by specifying new
values on the command line using the following format:
``<parameter_block>/<parameter>=<value>``. For example, if you want to extend the
simulation time limit when restarting,

.. code-block:: bash

   athena -r example.00010.rst time/tlim=100

Some parameters, such as the sizes of the Mesh and MeshBlock, cannot be changed in this
way.

Resuming cluster jobs from the latest restart file
--------------------------------------------------

Large jobs on clusters often require submitting requests to continue from a checkpoint.
The following snippet can help in making a submission script (e.g. for Slurm) that does
this automatically. This uses ``$input_dir/$name.athinput`` but overrides the
``job/basename`` field to be ``$name``. Only the ``# Parameters`` section needs to be
modified from job to job, and generally at most the ``tlim`` entry needs to be modified
with each restart. Additional command-line overrides can be specified with additional
lines to the ``arguments`` variable.

.. code-block:: bash

   # Parameters
   name=<name of job and input file>
   bin_name=<name of executable>
   input_dir=<path to directory containing input file>
   data_dir=<path to directory for writing outputs>
   arguments="\
     time/tlim=<tlim> \
   "

   # Check for restart file
   test_file=$(find $data_dir/rst -maxdepth 1 -name "$name.*.rst" -print -quit)
   if [ -n "$test_file" ]; then
     restart_files=$(ls -t $data_dir/rst/$name.*.rst)
     restart_file=(${restart_files[0]})
     restart_line="-r $restart_file"
     printf "\nrestarting from $restart_file\n\n"
   else
     restart_line="-i $input_dir/$name.athinput job/basename=$name"
     printf "\nstarting from beginning\n\n"
   fi

   # Run code
   <srun or equivalent> <options> $bin_name -d $data_dir $restart_line $arguments