README updates/citation

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.

README.md

@@ -1,5 +1,94 @@
 # 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 `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 PelePhysics as a whole and its use as part of the broader Pele suite, please use 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}}
+}
+```
+
+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
+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
 
@@ -34,5 +123,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 <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.
+### Model generation procedures
+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.