.. _GettingStarted

###############
Getting Started
###############


.. _Requirements

Requirements
============

.. toctree:: 

   Requirements

In addition to the other requirements for running FLASH you will need a C++ compiler, `CMake <https://cmake.org/>`_ and the 
`pybind11 library <https://pybind11.readthedocs.io/en/stable/index.html>`_. Because **pyFlash** is linked directly agains the Fortran
FLASH source it is important that all C/C++ & Fortran compilers are from the same vendor. Particularly on MacOs the default system 
compiler for C/C++ is Clang, but doesn't support Fortran. 

.. note::
   **pyFlash** requires Python >= 3.9


CMake
-----

Building FLASH with the python bindings is only supported through CMake. Like with the GNU Make building of FLASH, the CMake configuration
supports a site specific configuration file ``site.cmake`` that gets imported by CMake analagous to the ``Makefile.h``. Often times CMake can succesfully 
find all the needed libraries, but we provide library specific directories that can be set to help hint CMake to their location. 
In addition any other configurations you want to pass to CMake can be specified here.

.. code-block:: cmake
   :caption: sites/mySite/site.cmake

    # look for packages. Not necessary, but can help if CMake is struggling to find the libraries
    set(PYBIND11_DIR "/opt/homebrew/lib/python3.11/site-packages/pybind11")
    set(MPI_DIR "/usr/local/flash-deps/openMPI")
    set(HDF5_DIR "/usr/local/flash-deps/hdf5")
    set(HYPRE_DIR "/usr/local/flash-deps/hypre")

    # specify compilers
    set(CMAKE_Fortran_COMPILER  ${MPI_DIR}/bin/mpif90)
    set(CMAKE_C_COMPILER  ${MPI_DIR}/bin/mpicc)
    set(CMAKE_CXX_COMPILER ${MPI_DIR}/bin/mpicxx)

    #compiler flags
    set(FFLAGS "-ffree-line-length-0 -fdefault-real-8 -fdefault-double-8 -fallow-argument-mismatch")
    set(CFLAGS "")
    set(CXXFLAGS "")

.. note::
   `Setup` will automatically generate a `CMakeLists.txt` that looks for and links against all the necessary files for your simulation



pybind11
--------

.. toctree::

   pybind11

`Pybind11 <https://pybind11.readthedocs.io/en/stable/index.html>`_ can be
installed using ``pip`` or ``conda``.

.. code-block::

   pip install pybind11
   conda install pybind11


.. tip::
   If CMake has trouble finding pybind11 you can point to the install location inside your ``site.cmake`` file with the `PYBIND11_DIR` variable.

.. _setup

Setup
=====

.. toctree::

   Setup

Simulations can be setup with the python bindings by including the ``Python/PythonMain`` unit in FLASH along with
enabling CMake in the setup configuration. These can both be accomplished with the setup arguments ``-python`` & ``-cmake``. Equivalently
there is a setup shortcut ``+python`` that will do both. Any simulation may be set up with ``+python`` and enables the use of the 
:ref:`python parfiles <parfiles>`.

.. _old setup:

.. code-block:: bash
   :caption: Two equivalent setups

    ./setup Sedov -auto -2d +uhd +pm4dev +python
    ./setup Sedov -auto -2d +uhd +pm4dev -python -cmake

Similarly to previous iterations of FLASH's setup script this will pull all the source code links into ``object/source``. The code
is compiled by telling ``cmake`` where the ``object`` directory exists. A typical pattern is

.. code-block:: bash

   cd object
   mkdir build
   cd build
   cmake ..
   make

.. tip::
   With CMake FLASH doesn't have to be built in the ojbect directory. You could also specify ``cmake /path/to/object``. Because 
   the python unit builds and additional python package and links the FLASH executable against that library it can be more cumbersome
   to move the executable around in the file system.


.. _parfiles

Parfile
=======

.. toctree::

   Parfile

Including the `Python` unit in a simulation enables the use of the ``flashPar.py`` script, bot in setup and for setting runtime parameters.

To pass setup arguments to ``setup`` you must specify a function ``setupArgs()`` that returns a list of setup arguments:

.. code-block:: python
   :caption: source/Simulation/SimulationMain/Sedov/flashPar.py

    def setupArgs():
        args = [
                "-auto",
                "-2d",
                "+uhd",
                "+pm4dev",
                "+python"
               ] 
        return args

The above would allow the same setup as :ref:`above <old setup>` with just

.. _new setup

.. code-block:: bash

   ./setup Sedov

.. tip::
   command line setup arguments can still be combined with those from ``setupArgs``. For example to put the setup into a named object
   directory:

    .. code-block:: bash

        ./setup Sedov -objdir=sedov

Runtime parameters can be set in ``flashPar.py`` by defining a function ``parms()``. Runtime parameters are then set by using either
the APIs in the :ref:`flash.parm` module. `setup` will populate that module with all the available parameters for your simulation.

.. code-block:: python
   :caption: Simulation/SimulationMain/Sedov/flashPar.py

    def parms():
        import flash.parm as p

        p.sim_pAmbient(1.E-5) 
        p.sim_rhoAmbient(1.) 
        p.sim_expEnergy(1.) 
        p.sim_rInit(0.013671875) 
        p.sim_xctr(0.5) 
        p.sim_yctr(0.5) 
        p.sim_zctr(0.5) 

.. tip::
   Unlike with the ``flash.par`` input any valid python expressions can be used inside ``flashPar.py``

.. tip::
   You can convert your ``flash.par`` definitions with this ``sed`` command:

    .. code-block:: bash

       sed -r 's/^\s*(#\s*)?([^#]\S*)\s*=\s*(\".*\")?(\S*)?\s*(#.*$)?/\1p.\2\(\3\4\) \5/' flash.par | sed -r 's/\.true\./True/I' | sed -r 's/\.false\./False/I' > flashPar.py 

    You'll still have to format this int the ``parms()`` function and ``import flash.parm as p``