Getting Started

Requirements

In addition to the other requirements for running FLASH you will need a C++ compiler, CMake and the pybind11 library. 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.

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

Pybind11 can be installed using pip or conda.

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

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

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

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.

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:

source/Simulation/SimulationMain/Sedov/flashPar.py

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

The above would allow the same setup as above with just

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

./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 flash.parm module. setup will populate that module with all the available parameters for your simulation.

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:

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