From 2b656b537053194c2deeb5d8fcfd62c8f902b74e Mon Sep 17 00:00:00 2001 From: Bruce Perry Date: Thu, 25 Jan 2024 17:44:41 -0700 Subject: [PATCH 1/4] update README with citation and more info --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d85409ec2..6300ad5fe 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,75 @@ # PelePhysics -*A repository of physics databases and implementation code for use with the `Pele` suite of of codes* + +[![AMReX Badge](https://img.shields.io/static/v1?label=%22powered%20by%22&message=%22AMReX%22&color=%22blue%22)](https://amrex-codes.github.io/amrex/) +[![Exascale Computing Project](https://img.shields.io/badge/supported%20by-ECP-blue)](https://www.exascaleproject.org/research-project/combustion-pele/) + +## Overview + +PelePhysics is a repository of physics databases and implementation code for use with the [Pele suite of codes](https://amrex-combustion.github.io), +primarily the compressible solver [PeleC](https://amrex-combustion.github.io/PeleC/) and low-Mach solver [PeleLMeX](https://amrex-combustion.github.io/PeleLMeX/). + +PelePhysics contains C++ source code for the following physics and other modules, in the `Source` directory: + +* *EOS*: Equation of State, include multi-species ideal and real gas options +* *Transport*: Routines to evaluate multi-species transport properties +* *Reactions*: Routines for substepped integration of stiff chemical systems, including with CVODE +* *Spray*: Lagrangian spray droplet library, formerly part of [PeleMP](https://github.com/AMReX-Combustion/PeleMP) +* *Soot*: An implementation of the Hybrid Method of Moments soot model, formerly part of [PeleMP](https://github.com/AMReX-Combustion/PeleMP) +* *Radiation*: Raidative heat transfer model based on the spherical harmonics method, formerly [PeleRad](https://github.com/AMReX-Combustion/PeleRad) +* *Utility*: Several handy modules for data management across other Pele codes + +Additionally, PelePhysics contains a variety of stand-alone tools to aid in Pele simulation workflows, found in the `Support` directory. +Most notable among these is CEPTR, described further below, a tool that converts chemical mechanisms from Cantera format to efficient +source code files for use in the Pele codes. + +For convenience, the `Mechanisms` directory contains the CEPTR-generated source code for a number of chemical mechanisms, as well as both +Cantera and CHEMKIN format data files for each mechanism. + +Documentation for these various capabilities, to varying degrees, can be found in the `Docs` directory or online +at https://amrex-combustion.github.io/PelePhysics/. The papers listed below under the Citation heading may also be valuable resources. + +PelePhysics has two required dependencies, AMReX and SUNDIALS, which are both git submodules located the `Submodules` directory. +The `ThirdParty` directory is used when building these submodules, and for downloading and building other optional submodules. + +Finally, the `Tests` directory includes several stand-alone codes for exercising various aspects of the physics modules mentioned above. + +## Getting Started + +PelePhysics is primarily intended as a library for use with other Pele codes. For more information on how to download PelePhysics and +its dependencies, and how to build the stand-alone test codes, consult the [online documentation](https://amrex-combustion.github.io/PelePhysics/GettingStarted.html). + + +## Citation + +To cite the multi-physics (soot, spray, radiation) capabilities in PelePhysics that were imported from +PeleMP and PeleRad, please use the following [Journal of Fluids Engineering article](PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite): +``` +@article{owen2023pelemp, + title={PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite}, + author={Owen, Landon D and Ge, Wenjun and Rieth, Martin and Arienti, Marco and Esclapez, Lucas and S Soriano, Bruno and Mueller, Michael E and Day, Marc and Sankaran, Ramanan and Chen, Jacqueline H}, + journal={Journal of Fluids Engineering}, + pages={1--41}, + year={2023} +} +``` + +To cite PelePhysics as a whole and its use as part of the broader Pele suite, please cite the following +SIAM Parallel Processing article: + +``` +@article{HenrydeFrahan2024, + doi = {}, + url = {}, + year = {2024}, + publisher = {SIAM}, + volume = {}, + number = {}, + pages = {}, + author = {Marc T. {Henry de Frahan} and Lucas Esclapez and Jon Rood and Nicholas Wimer and Paul Mullowney and Bruce A. Perry and Landon Owen and Hariswaran Sitaraman and Shashank Yellapantula and Malik Hassanaly and Mohammad J. Rahimi and Michael Martin and Olga Doronina and Sreejith Nadakkal Appukuttan and Martin Rieth and Wenjun Ge and Ramanan Sankaran and Ann Almgren and Weiqun Zhang and John B. Bell and Ray Grout and Marc S. Day and Jacqueline H. Chen}, + title = {The {Pele} Simulation Suite for Reacting Flows at Exascale}, + journal = {{SIAM Proceedings Series on Parallel Processing for Scientific Computing}} +} +``` ## CEPTR @@ -34,5 +104,5 @@ If the `Pele` codes are built with `Eos_Model = Fuego`, the make system variable `PelePhysics` currently supports a cubic EOS model: `Soave-Redlich-Kwong`. It is built on top of the ideal gas models, and is selected by specifying its name as the `Eos_Model` during the build (the make system requires that both `Eos_Model` and `Chemistry_Model` be specified). Any additional parameters required for the EOS (e.g., attractions, repulsions, critical states) are either included in the underlying CEPTR database used to generate the source file model implementation, or else are inferred from the input model data. -## Model generation procedures -This repository provides the tools necessary for generating new Pele-compatible combustion mechanisms. Please refer to the `CEPTR documentation `_ for instructions on generating mechanism models. Make sure that you edit the `GNUmakefile` where you want to use this (in, e.g., `PeleC/Exec`) so that `Chemistry_Model` is `XXX`. In `PeleC/Exec/Make.PeleC`, the model is expected to be in the folder `${PELE_PHYSICS_HOME}/Mechanisms/$(Chemistry_Model)`, and it is expected that the folder contains a `Make.package` file to include, so make sure things are where they need to be. Refer to other mechanisms for additional guidance. +### Model generation procedures +This repository provides the tools necessary for generating new Pele-compatible combustion mechanisms. Please refer to the `CEPTR documentation `_ for instructions on generating mechanism models. Make sure that you edit the `GNUmakefile` where you want to use this (in, e.g., `PeleC/Exec`) so that `Chemistry_Model` is `XXX`. In `PeleC/Exec/Make.PeleC`, the model is expected to be in the folder `${PELE_PHYSICS_HOME}/Mechanisms/$(Chemistry_Model)`, and it is expected that the folder contains a `Make.package` file to include, so make sure things are where they need to be. Refer to other mechanisms for additional guidance. \ No newline at end of file From 2193e61d4d42ed54c5b1eadccf181ccc56715c56 Mon Sep 17 00:00:00 2001 From: Bruce Perry Date: Thu, 25 Jan 2024 17:46:00 -0700 Subject: [PATCH 2/4] fix CEPTR link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6300ad5fe..deac33453 100644 --- a/README.md +++ b/README.md @@ -105,4 +105,4 @@ If the `Pele` codes are built with `Eos_Model = Fuego`, the make system variable `PelePhysics` currently supports a cubic EOS model: `Soave-Redlich-Kwong`. It is built on top of the ideal gas models, and is selected by specifying its name as the `Eos_Model` during the build (the make system requires that both `Eos_Model` and `Chemistry_Model` be specified). Any additional parameters required for the EOS (e.g., attractions, repulsions, critical states) are either included in the underlying CEPTR database used to generate the source file model implementation, or else are inferred from the input model data. ### Model generation procedures -This repository provides the tools necessary for generating new Pele-compatible combustion mechanisms. Please refer to the `CEPTR documentation `_ for instructions on generating mechanism models. Make sure that you edit the `GNUmakefile` where you want to use this (in, e.g., `PeleC/Exec`) so that `Chemistry_Model` is `XXX`. In `PeleC/Exec/Make.PeleC`, the model is expected to be in the folder `${PELE_PHYSICS_HOME}/Mechanisms/$(Chemistry_Model)`, and it is expected that the folder contains a `Make.package` file to include, so make sure things are where they need to be. Refer to other mechanisms for additional guidance. \ No newline at end of file +This repository provides the tools necessary for generating new Pele-compatible combustion mechanisms. Please refer to the [CEPTR documentation](https://amrex-combustion.github.io/PelePhysics/Ceptr.html) for instructions on generating mechanism models. Make sure that you edit the `GNUmakefile` where you want to use this (in, e.g., `PeleC/Exec`) so that `Chemistry_Model` is `XXX`. In `PeleC/Exec/Make.PeleC`, the model is expected to be in the folder `${PELE_PHYSICS_HOME}/Mechanisms/$(Chemistry_Model)`, and it is expected that the folder contains a `Make.package` file to include, so make sure things are where they need to be. Refer to other mechanisms for additional guidance. \ No newline at end of file From 0aa299529428a45bef06fd1b2b42b4d45edf4de2 Mon Sep 17 00:00:00 2001 From: Bruce Perry Date: Thu, 25 Jan 2024 17:52:30 -0700 Subject: [PATCH 3/4] mote readme updates and add contributing guidelines --- CONTRIBUTING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 25 ++++++++++++++++--- 2 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..fc7072a68 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +## Contributions Model + +New contributions to *PelePhysics* are welcome ! + +The *PelePhysics* contributions workflow follows these steps: +1. Fork the main repository +2. Create an `AmazingNewFeature` branch implementing your changes +3. Open a Pull Request (PR) from `AmazingNewFeature` on your fork to branch `development` of the main *PelePhysics* repository + +Follow [GitHub directions](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) +to fork *PelePhysics* main repo on your GitHub account, and use a recursive `git clone` to get your fork of *PelePhysics* and its dependencies. + +Then step into the *PelePhysics* folder and add the main *PelePhysics* repository as the `upstream` remote in order to keep track of the main repo : + + git add remote upstream https://github.com/AMReX-Combustion/PelePhysics + +At any point, you can update the `development` branch of your local repository with changes implemented in the main *PelePhysics* repo by pulling from `upstream` : + + git checkout development + git pull upstream development + +We recommend setting your development branch to track the upstream one instead of your fork: + + git branch -u upstream/development + +You are now free to modify your own fork of *PelePhysics*. To add a new feature to *PelePhysics*, the procedure is: + +1. Create a branch for the new feature from the `development` branch (locally) : + + git checkout development + git checkout -b AmazingNewFeature + +2. and commit your changes to your local repo : + + git commit -m "Developed AmazingNewFeature" + +3. Alongside your development, regularly merge changes from the main repo `development` branch into your `AmazingNewFeature` branch, +fix any conflicts, and push your changes to your GitHub fork : + + git push -u origin AmazingNewFeature + +4. When you are ready to propose your new feature/improvement/bug fix to the main *PelePhysics* repo, reiterate Step 3 and submit a PR through the GitHub page from your fork onto the `development` branch of the main repo: + + - Click on the ``compare & pull request`` button to start your PR. + - Provide a title and a short description for your PR: + * what feature/fix do you propose + * how did you test it + * any other information deemed useful : does it modify the default *PeleLM* behavior ? ... + - Press ``Create pull request``. + +Please DO NOT write large PR, as they are very difficult and time-consuming to review. +As much as possible, split them into small targeted PRs. +For example, if find typos in the documentation open a pull request that only fixes typos. +If you want to fix a bug, make a small pull request that only fixes a bug. + +## PelePhysics Coding Style Guide + +Source code files can be automatically formatted to adhere to the appropriate formatting rules using ``clang-format``. To format all files, use the command: + + find Source Testing \( -name "*.cpp" -o -name "*.H" \) -exec clang-format -i {} + + +from within the PelePhysics base directory. You can also format files individually using ``clang-format -i /path/to/file``. Adherence to this format is checked for all PRs. + +Beyond that, as much as possible, `PelePhysics` adheres to [AMReX Coding Style](https://github.com/AMReX-Codes/amrex/blob/development/CONTRIBUTING.md#amrex-coding-style-guide) +and we are encouraging contributors to follow those guidelines. diff --git a/README.md b/README.md index deac33453..f2013bd84 100644 --- a/README.md +++ b/README.md @@ -31,18 +31,27 @@ at https://amrex-combustion.github.io/PelePhysics/. The papers listed below unde PelePhysics has two required dependencies, AMReX and SUNDIALS, which are both git submodules located the `Submodules` directory. The `ThirdParty` directory is used when building these submodules, and for downloading and building other optional submodules. -Finally, the `Tests` directory includes several stand-alone codes for exercising various aspects of the physics modules mentioned above. +Finally, the `Testing` directory includes several stand-alone codes for exercising various aspects of the physics modules mentioned above. ## Getting Started PelePhysics is primarily intended as a library for use with other Pele codes. For more information on how to download PelePhysics and its dependencies, and how to build the stand-alone test codes, consult the [online documentation](https://amrex-combustion.github.io/PelePhysics/GettingStarted.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. ## Citation To cite the multi-physics (soot, spray, radiation) capabilities in PelePhysics that were imported from -PeleMP and PeleRad, please use the following [Journal of Fluids Engineering article](PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite): +PeleMP and PeleRad, please use the following [Journal of Fluids Engineering article](https://doi.org/10.1115/1.4064494): ``` @article{owen2023pelemp, title={PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite}, @@ -53,7 +62,7 @@ PeleMP and PeleRad, please use the following [Journal of Fluids Engineering arti } ``` -To cite PelePhysics as a whole and its use as part of the broader Pele suite, please cite the following +To cite PelePhysics as a whole and its use as part of the broader Pele suite, please use the following SIAM Parallel Processing article: ``` @@ -71,6 +80,16 @@ SIAM Parallel Processing article: } ``` +## Getting help, contributing + +Do you have a question ? Found an issue ? Please use the [GitHub Discussions](https://github.com/AMReX-Combustion/PelePhysics/discussions) to engage +with the development team or open a new [GitHub issue](https://github.com/AMReX-Combustion/PelePhysics/issues) to report a bug. The development team +also encourages users to take an active role in respectfully answering each other's questions in these spaces. When reporting a bug, it is helpful +to provide as much detail as possible, including a case description and the major compile and runtime options being used. Though not required, +it is most effective to create a fork of this repository and share a branch of that fork with a case that minimally reproduces the error. + +New contributions to *PelePhysics* are welcome ! Contributing Guidelines are provided in [CONTRIBUTING.md](CONTRIBUTING.md). + ## CEPTR This `PelePhysics` repository contains the CEPTR source code generation tool in order to support the inclusion of chemical models specified in the Cantera yaml format. CETPR derives from FUEGO, which was originally created by Michael Aivazis at CalTech, and donated to CCSE in 2001. Originally, FUEGO was part of a larger Python-based set of workflow tools Michael developed for managing and publishing simulation-based studies. FUEGO itself was developed as a drop-in replacement for the CHEMKIN library, and provided "hand-coded" replacement routines for evaluation of EOS thermodynamic functions that are considerably more efficient than their CHEMKIN counterparts. Since 2001, CCSE has continued to modify FUEGO independently for its own use so that the current version here bears little resemblance to Michael's original code, or its intentions. CEPTR has adapted FUEGO code to use the Cantera yaml format and is now the preferred way of generating mechanism files. From f3f4e9dbf4d72ed9c769c1d4eecd5250de3d16a3 Mon Sep 17 00:00:00 2001 From: Bruce Perry Date: Fri, 26 Jan 2024 10:18:14 -0700 Subject: [PATCH 4/4] swap order --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f2013bd84..bde83106b 100644 --- a/README.md +++ b/README.md @@ -50,18 +50,6 @@ imperative. ## Citation -To cite the multi-physics (soot, spray, radiation) capabilities in PelePhysics that were imported from -PeleMP and PeleRad, please use the following [Journal of Fluids Engineering article](https://doi.org/10.1115/1.4064494): -``` -@article{owen2023pelemp, - title={PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite}, - author={Owen, Landon D and Ge, Wenjun and Rieth, Martin and Arienti, Marco and Esclapez, Lucas and S Soriano, Bruno and Mueller, Michael E and Day, Marc and Sankaran, Ramanan and Chen, Jacqueline H}, - journal={Journal of Fluids Engineering}, - pages={1--41}, - year={2023} -} -``` - To cite PelePhysics as a whole and its use as part of the broader Pele suite, please use the following SIAM Parallel Processing article: @@ -80,6 +68,18 @@ SIAM Parallel Processing article: } ``` +To cite the multi-physics (soot, spray, radiation) capabilities in PelePhysics that were imported from +PeleMP and PeleRad, please use the following [Journal of Fluids Engineering article](https://doi.org/10.1115/1.4064494): +``` +@article{owen2023pelemp, + title={PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite}, + author={Owen, Landon D and Ge, Wenjun and Rieth, Martin and Arienti, Marco and Esclapez, Lucas and S Soriano, Bruno and Mueller, Michael E and Day, Marc and Sankaran, Ramanan and Chen, Jacqueline H}, + journal={Journal of Fluids Engineering}, + pages={1--41}, + year={2023} +} +``` + ## Getting help, contributing Do you have a question ? Found an issue ? Please use the [GitHub Discussions](https://github.com/AMReX-Combustion/PelePhysics/discussions) to engage