mahgadalla/PeleLM

PeleLM - README

PeleLM is an adaptive-mesh low Mach number hydrodynamics code for reacting flows. PeleLM has a project homepage, and can be obtained via GitHub. Use this link to to sign up for the PeleLM user forum, where updates and significant changes will be posted. The forum is also where general questions can be posted about building and running the code, processing code output, and details about the algorithm and its implementation.

Current project build status

https://readthedocs.org/projects/pelelm/badge

Getting started with PeleLM

To compile and run the Pele suite of codes, one needs a C++ compiler that supports the C++11 standard and a Fortran compiler that supports the 2003 standard. A hierarchical strategy for parallelism is supported, based MPI + OpenMP. The codes work with all major MPI and OpenMP implementations. The codes should build and run with no modifications to the make system if using a Linux system with the GNU compilers, version 4.8.4 and above.

To build PeleLM and run a sample 2D flame problem:

Set the environment variable, AMREX_HOME, and clone a copy of AMReX there

export AMREX_HOME=<location for AMReX>
git clone https://github.com/AMReX-Codes/amrex.git ${AMREX_HOME}
   or (if you have the proper SSH keys set in your GitHub settings)
git clone git@github.com:AMReX-Codes/amrex.git ${AMREX_HOME}

Set the environment variable, IAMR_HOME, and clone a copy of IAMR there

export IAMR_HOME=<location for IAMR>
git clone https://github.com/AMReX-Codes/IAMR.git ${IAMR_HOME}
   or (if you have the proper SSH keys set in your GitHub settings)
git clone git@github.com:AMReX-Codes/IAMR.git ${IAMR_HOME}

Set the environment variable, PELELM_HOME, and clone a copy of PeleLM there

export PELELM_HOME=<location for PeleLM>
git clone https://github.com/AMReX-Combustion/PeleLM.git ${PELELM_HOME}
   or (if you have the proper SSH keys set in your GitHub settings)
git clone git@github.com:AMReX-Combustion/PeleLM.git ${PELELM_HOME}

Set the environment variable, PELE_PHYSICS_HOME, and clone a copy of PelePhysics there

export PELE_PHYSICS_HOME=<location for PelePhysics>
git clone https://github.com/AMReX-Combustion/PelePhysics.git ${PELE_PHYSICS_HOME}
   or (if you have the proper SSH keys set in your GitHub settings)
git clone git@github.com:AMReX-Combustion/PelePhysics.git ${PELE_PHYSICS_HOME}

Move to an example build folder, build an executable

cd ${PELELM_HOME}/Exec/RegTests/FlameSheet
make
./PeleLM2d.xxx.yyy.ex inputs.2d-regt

Notes
1. In the exec line above, xxx.yyy is a tag identifying your compiler and various build options, and will vary across pltaform. (Note that GNU compilers must be at least 4.8.4, and MPI should be at least version 3).
2. The example is 2D premixed flame, flowing vertically upward through the domain with no gravity. The lateral boundaries are periodic. A detailed methane model is used. The solution is initialized with a wrinkled (perturbed) 1D steady flame solution computed using the PREMIX code. Two levels of solution-adaptive refinement are automatically triggered by the presence of the flame intermediate, H.
3. In addition to informative output to the terminal, periodic plotfiles are written in the run folder. These may be viewed with CCSE's Amrvis (<https://github.com/AMReX-Codes/Amrvis>) for example. Please look at the AMReX documentation for further options about visualization (<https://amrex-codes.github.io/amrex/docs_html/Visualization.html>).

Dependencies

PeleLM was created in 2017 by renaming LMC, the low Mach code from CCSE, and is built on the AMReX library and the IAMR code (see above).

Development model

To add a new feature to PeleLM, the procedure is:

Create a branch for the new feature (locally)
```
git checkout -b AmazingNewFeature
```

Develop the feature, merging changes often from the development branch into your AmazingNewFeature branch

git commit -m "Developed AmazingNewFeature"
git checkout development
git pull                     [fix any identified conflicts between local and remote branches of "development"]
git checkout AmazingNewFeature
git merge development        [fix any identified conflicts between "development" and "AmazingNewFeature"]

Push feature branch to PeleLM repository

git push -u origin AmazingNewFeature [Note: -u option required only for the first push of new branch]

Submit a merge request through the github project page - be sure you are requesting to merge your branch to the development branch.

Documentation

Documentation for PeleLM is under development in the Docs directory. To build

cd ${PELELM_HOME}/Docs
make html

Acknowledgment

This research was supported by the Exascale Computing Project (ECP), Project Number: 17-SC-20-SC, a collaborative effort of two DOE organizations -- the Office of Science and the National Nuclear Security Administration -- responsible for the planning and preparation of a capable exascale ecosystem -- including software, applications, hardware, advanced system engineering, and early testbed platforms -- to support the nation's exascale computing imperative.

mahgadalla / PeleLM