.. _fixed_grid:

#####################
Run a fixed MESA grid
#####################

Default evolutionary parameters
===============================

POSYDON makes it easy to run a fixed grid of binaries with MESA within a high
performance computing environment. Note that these instructions assume you
are using slurm as your job scheduler. We just need to start by setting a few
environment variables. We recommend you add these to your `.bashrc` or
`.bash_profile` so they are included at login. The filepaths of these need to be
edited for your own installation.

.. code-block::

    export MESA_DIR="/projects/b1119/mesa_sdk/mesa-r11701"
    export OMP_NUM_THREADS=4
    export MESASDK_ROOT="/projects/b1119/mesa_sdk/mesasdk"
    source $MESASDK_ROOT/bin/mesasdk_init.sh

Next, you will need to create a working directory for your grid of binaries.
For this example, we will create a working directory called `example_grid`:

.. code-block::

    mkdir example_grid
    cd example_grid

This directory will contain all the binary runs and associated data generated
by the individual MESA runs as well as the functionality for slurm to run the
grid.

Now that we have our directory, we need to create two separate files: a file
containing the list of binaries we want to evolve and an :samp:`ini` file that
contains all the parameters associated with running the grid. Let's start with
the list of binaries we want to evolve. For the case of this example, let's
evolve a series of high-mass X-ray binaries with neutron star accretors at a
series of initial binary periods. We'll use our favorite text editor to add the
following lines into a file we'll call `grid.csv`. As we'll see below, it can
be given any name, but the entries must be separated by commas.

.. code-block::

    m1,m2,initial_period_in_days
    10,1.4,1
    10,1.4,10
    10,1.4,100
    10,1.4,1000

POSYDON internally allows any variable to be included here, so long as it has
the same name as a variable in MESA. However, these three parameters ought to
always be specified, otherwise you will be evolving a binary with a default
orbital period and masses.

As for the :samp:`ini` file, you can copy over the `example
<https://github.com/POSYDON-code/POSYDON/blob/development/grid_params/grid_params.ini>`_
from the :ref:`inifile` page, which provides a more detailed description of all
the entries. Make sure to carefully go through each of the separate entries and
adjust them for your particular needs. Place that :samp:`ini` file (which we have
named `example_grid.ini`) in the example_grid directory.

Now, with our `grid.csv` and `example_grid.ini` files ready to go, we use a
POSYDON script `posydon-setup-grid` to generate all the necessary files to run
the grid using slurm. Note the different arguments here. We are designating
that: 1) we are using a fixed grid, 2) that our job scheduler is slurm, and 3)
the name of the :samp:`ini` file. We may expand compatibility for other job
schedulers in the future, but for now slurm is the only implemented option.

.. code-block::

    posydon-setup-grid --grid-type fixed --submission-type slurm --inifile example_grid.ini

This will take a minute to run. You will note that it includes a pull from the
POSYDON GitHub repository to ensure the correct, designated version of the MESA
inlists are being used. It is possible that you will need to enter your
GitHub username and password during this step. Additionally, note that this
step takes some time to run, as several MESA files are being compiled.

Once finished, you will note that in our `example_grid` directory, we now have
several new files and new directories. One advantage of this implementation is
that all the binaries we run use a single version of the MESA executables,
rather than each binary having its own copy of the same files.

Finally, we are ready to submit our jobs with:

.. code-block::

    ./run_grid.sh

This shell script will submit the two slurm jobs
:samp:`slurm_job_array_grid_submit.sh` and :samp:`cleanup.sh`. The first one
will run the MESA simulations, where several runs will go in parallel. The
second job, will run after all MESA runs are completed. It is doing some
cleanup:

- removing files no longer needed (e.g. memory copies created as backups)
- compressing files containing a lot of text (those files are individually
  compressed and will be kept in place, hence getting a file extension `.gz`
  added)
- changing the owning group and permissions (this will only be done if a new
  group was specified in the :samp:`ini` file in the setup)

Once the grid of runs is completed, we recommend you use our provided PSyGrid
functionality to examine and collate the individual binary runs
(link for documentation: :mod:`posydon.grids.psygrid`.)


Non-default evolutionary parameters
===================================

If you want to change the binary evolution parameters so you are using
non-default options, we have constructed a hierarchy of MESA inlists. You can
provide a non-default option in your own user-provided MESA inlist, which is
explicitly linked in the :samp:`ini` file (make sure you uncomment the appropriate
lines). We additionally provide the capability to use your own
`run_star_extras.f` and `run_binary_extras.f` as well as provide your own list
of history and profile columns. See :ref:`inifile` for details.