Skip to content
This repository has been archived by the owner on Jan 10, 2024. It is now read-only.

Commit

Permalink
Merge pull request #141 from AMReX-Combustion/Update_GHReadme
Browse files Browse the repository at this point in the history 
Clean up PeleLM description and doc
  • Loading branch information
@esclapez
esclapez authored Jan 16, 2021
2 parents eece7b3 + 57754f7 commit 434793c
Show file tree
Hide file tree
Showing 14 changed files with 399 additions and 535 deletions.
64 changes: 37 additions & 27 deletions Docs/source/GNUmakeSystem.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Dissecting a Simple Make File
-----------------------------

An example input file for GNU Make can be found in any of the example setup,
such as ``$(PELELM_HOME)/Exec/FlameInABox``. Table :numref:`tab:makevars`
such as ``$(PELELM_HOME)/Exec/RegTests/FlameSheet``. Table :numref:`tab:makevars`
below shows a list of important variables.

.. raw:: latex
Expand All @@ -29,27 +29,37 @@ below shows a list of important variables.

.. table:: Important make variables

+------------+-------------------------------------+-------------+
| Variable | Value | Default |
+============+=====================================+=============+
| AMREX_HOME | Path to amrex | environment |
+------------+-------------------------------------+-------------+
| COMP | gnu, cray, ibm, intel, llvm, or pgi | none |
+------------+-------------------------------------+-------------+
| DEBUG | TRUE or FALSE | TRUE |
+------------+-------------------------------------+-------------+
| DIM | 1 or 2 or 3 | none |
+------------+-------------------------------------+-------------+
| USE_MPI | TRUE or FALSE | FALSE |
+------------+-------------------------------------+-------------+
| USE_OMP | TRUE or FALSE | FALSE |
+------------+-------------------------------------+-------------+
+--------------------+-------------------------------------+-------------+
| Variable | Value | Default |
+====================+=====================================+=============+
| AMREX_HOME | Path to amrex | environment |
+--------------------+-------------------------------------+-------------+
| IAMR_HOME | Path to IAMR | environment |
+--------------------+-------------------------------------+-------------+
| PELELM_HOME | Path to PeleLM | environment |
+--------------------+-------------------------------------+-------------+
| PELE_PHYSICS_HOME | Path to PelePhysics | environment |
+--------------------+-------------------------------------+-------------+
| COMP | gnu, cray, ibm, intel, llvm, or pgi | none |
+--------------------+-------------------------------------+-------------+
| DEBUG | TRUE or FALSE | TRUE |
+--------------------+-------------------------------------+-------------+
| DIM | 2 or 3 | none |
+--------------------+-------------------------------------+-------------+
| USE_MPI | TRUE or FALSE | FALSE |
+--------------------+-------------------------------------+-------------+
| USE_OMP | TRUE or FALSE | FALSE |
+--------------------+-------------------------------------+-------------+
| USE_CUDA | TRUE or FALSE | FALSE |
+--------------------+-------------------------------------+-------------+
| USE_HIP | TRUE or FALSE | FALSE |
+--------------------+-------------------------------------+-------------+

.. raw:: latex

\end{center}

At the beginning of ``$(PELELM_HOME)/Exec/FlameInABox/GNUmakefile``, the make
At the beginning of ``$(PELELM_HOME)/Exec/FlameSheet/GNUmakefile``, the make
variable ``AMREX_HOME`` is set to the path to the top directory of AMReX. Note that in
the example :cpp:`?=` is a conditional variable assignment operator that only
has an effect if ``AMREX_HOME`` has not been defined (including in the
Expand All @@ -71,14 +81,18 @@ prior to running ``make``. alternatively, in tcsh one can set

setenv AMREX_HOME /path/to/amrex

Path to `IAMR` (``IAMR_HOME``), `PelePhysics` (``PELE_PHYSICS_HOME``) and `PeleLM` (``PELELM_HOME``)
should also be provided in the same manner.

One must set the ``COMP`` variable to choose a compiler suite (for C, C++, f90).
Currently the list of supported compiler suites includes gnu, cray, ibm, intel, llvm,
and pgi. One must also set the ``DIM`` variable to either 1, 2, or 3, depending
on the dimensionality of the problem.

Variables ``DEBUG``, ``USE_MPI`` and ``USE_OMP`` are optional with default set
to TRUE, FALSE and FALSE, respectively. The meaning of these variables should
be obvious. When ``DEBUG=TRUE``, aggressive compiler optimization flags are
Variables ``DEBUG``, ``USE_MPI``, ``USE_OMP``, ``USE_CUDA`` and ``USE_HIP`` are optional with default set
to TRUE, FALSE, FALSE, FALSE and FALSE, respectively. Note that the last three entries are mutually exclusive.
The meaning of these variables should be obvious.
When ``DEBUG=TRUE``, aggressive compiler optimization flags are
turned off and assertions in source code are turned on. For production runs,
``DEBUG`` should be set to FALSE.

Expand Down Expand Up @@ -107,9 +121,9 @@ Variables for various source file types are shown below.
Free format Fortran source with .F90 extension. Note that these
Fortran files will go through preprocessing.

In the ``FlameInABox` example, the extra source file, ``drm19Soln_seed_0.50.f`` is in a
In the ``FlameSheet`` example, the extra source file, ``drm19Soln_seed_0.50.f`` is in a
directory that is already in the build system's search path. Additional files,
that are local to this setup, such as ``Prob_$(DIM)d.F`` need to be added to the appropriate
that are local to this setup, such as ``pele_prob.cpp`` need to be added to the appropriate
file list explicitly as well. If this case included files in a separate folder
(e.g., ``mysrcdir``), you will then need to add the following:

Expand All @@ -130,10 +144,7 @@ for a list of currently recognized models, and to see which folder that the stri
in ``$(PELE_PHYSICS_HOME)/Support/Fuego/Mechanism/Models`` folder. That folder will contain
a ``Make.package`` that appends the model-specific source files to the build list (typically
a C-source file generated by `FUEGO` from a CHEMKIN-compatible set of specification files -- see
the file ``$(PELELM_HOME)/README.rst`` for more information on model generation.



the file ``$(PELE_PHYSICS_HOME)/README.rst`` for more information on model generation.

Tweaking the Make System
------------------------
Expand Down Expand Up @@ -209,4 +220,3 @@ that you use homebrew's mpich. Normally is it fine to simply install its
binaries: ``brew install mpich``. But if you are experiencing problems, we
suggest building mpich usinging homebrew's gcc: ``brew install mpich
--cc=gcc-8``.

99 changes: 68 additions & 31 deletions Docs/source/GettingStarted.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@

`PeleLM` Quickstart
===================

`PeleLM` was created in 2017 by renaming `LMC`, the low Mach code from `CCSE <https://ccse.lbl.gov>`_,
and is built on the `AMReX` library, the `IAMR` code and the `PelePhysics` chemistry and thermodynamics library.
For the impatient, the following summarizes how to obtain `PeleLM` and all the supporting software
required, and how to build and run a simple case in order to obtain a first set of results.
A thorough discussion of the model equations, and time stepping algorithms in `PeleLM` is
Expand All @@ -15,34 +16,68 @@ of the results from `PeleLM` is discussed in :ref:`sec:visualization`.
Obtaining `PeleLM`
------------------

First, make sure that "git" is installed on your machine---we recommend version 1.7.x or higher. Then...
First, make sure that "git" is installed on your machine---we recommend version 1.7.x or higher.

Then, there are two options to obtain `PeleLM` and its dependencies:

1. PeleProduction
^^^^^^^^^^^^^^^^^

`PeleProduction` enable the user to obtain a consistent version of `PeleLM` and all its dependencies
with a single git clone (from the user). This is the prefered option when one want to use `PeleLM`
but do not intend to make development into the code. More information on `PeleProduction` can be found
on the `GitHub page <https://github.com/AMReX-Combustion/PeleProduction.git>`_.

a. Download the `PeleProduction` repository and : ::

git clone https://github.com/AMReX-Combustion/PeleProduction.git

cd PeleProduction

b. The first time you do this, you will need to tell git that there are submodules. Git will look at the ``.gitmodules`` file in this branch and use that : ::

cd Submodules
git submodule init

c. Finally, get into the FlameSheet folder of the `PeleLM` submodule: ::

1. Download the `AMReX` repository by typing: ::
cd PeleLM/Exec/RegTests/FlameSheet

git clone https://github.com/AMReX-Codes/amrex.git
2. Individual repositories
^^^^^^^^^^^^^^^^^^^^^^^^^^

This will create a folder called ``amrex/`` on your machine. Set the environment variable, ``AMREX_HOME``, on your
machine to point to the path name where you have put `AMReX`::
Alternatively, all the individual dependencies of `PeleLM` can be obtained independently. The user then needs to provide environment variables for each of `AMReX`, `IAMR`, `PelePhysics` and `PeleLM` installation path.
This method is intended for users wanting to modify the `PeleLM` source code and who are more comfortable with maintaining up-to-date the four repositories.

a. Download the `AMReX` repository by typing: ::

git clone https://github.com/AMReX-Codes/amrex.git

This will create a folder called ``amrex/`` on your machine. Set the environment variable, ``AMREX_HOME``, on your
machine to point to the path name where you have put `AMReX`::

export AMREX_HOME=/path/to/amrex/
2. Download the `IAMR` repository by typing: ::
b. Download the `IAMR` repository by typing: ::

git clone https://github.com/AMReX-Codes/IAMR.git
git clone https://github.com/AMReX-Codes/IAMR.git
This will create a folder called ``IAMR/`` on your machine.
Set the environment variable, ``IAMR_HOME``.
This will create a folder called ``IAMR/`` on your machine.
Set the environment variable, ``IAMR_HOME``.

3. Clone the `Pele` repositories: ::
c. Clone the `PeleLM` and `PelePhysics` repositories: ::

git clone [email protected]:AMReX-Combustion/PeleLM.git
git clone [email protected]:AMReX-Combustion/PelePhysics.git
git clone [email protected]:AMReX-Combustion/PeleLM.git
git clone [email protected]:AMReX-Combustion/PelePhysics.git

This will create folders called ``PeleLM`` and ``PelePhysics`` on your machine.
Set the environment variables, ``PELELM_HOME`` and ``PELE_PHYSICS_HOME``, respectively to where you put these.
This will create folders called ``PeleLM`` and ``PelePhysics`` on your machine.
Set the environment variables, ``PELELM_HOME`` and ``PELE_PHYSICS_HOME``, respectively to where you put these.

4. Periodically update each of these repositories by typing ``git pull`` within each repository.
d. Periodically update each of these repositories by typing ``git pull`` within each repository.

e. Finally, get into the ``FlameSheet`` folder of the `PeleLM` : ::

cd PeleLM/Exec/RegTests/FlameSheet

Building `PeleLM`
-----------------
Expand All @@ -52,28 +87,31 @@ sub-folder under ``$(PELELM_HOME)/Exec/``, and a local version of the
`PeleLM` executable is built directly in that folder (object libraries are not used to manage `AMReX`
and the application code). In the following, we step through building a representative `PeleLM` executable.

1. We will work in the folder containing setup for the `FlameSheet` problem in 2D
(``$(PELELM_HOME)/Exec/RegTests/FlameSheet``).
In this setup, cold fuel enters the domain bottom and passes through a flame sheet.
Hot products exit the domain at the top. The sides of the domain are periodic, and the coordinates are
cartesian. Go to the problem-specific source folder::

cd $(PELELM_HOME)/Exec/RegTests/FlameSheet
1. Regardless of which path you decided to choose in order to get the `PeleLM` code and its dependencies, you should be now be in the ``FlameSheet`` folder.

2. Edit the ``GNUmakefile`` to ensure that the following are set::
2. Edit the ``GNUmakefile`` to ensure that the following are set: ::

DIM = 2
COMP = gnu (or your favorite C++/F90 compiler suite)
DEBUG = TRUE
USE_MPI = FALSE
USE_OMP = FALSE

If you want to try compilers other than those in the GNU suite, and you find that they don't
work, please let us know. Note that for centers managing their enviroments with "modules", the
programming environment determining your available compiler should agree with your choice of ``COMP``
in the ``GNUmakefile`` (e.g., ``PrgEnv-gnu`` module requires ``COMP=gnu``).
If successful, the resulting executable name will look something like ``PeleLM2d.gnu.ex``.
If you want to try compilers other than those in the GNU suite, and you find that they don't
work, please let us know. Note that for centers managing their enviroments with "modules", the
programming environment determining your available compiler should agree with your choice of ``COMP``
in the ``GNUmakefile`` (e.g., ``PrgEnv-gnu`` module requires ``COMP=gnu``).

3. Start by building the Sundials Third Party Library used to integrate the chemistry: ::
make TPL

and finally build `PeleLM` executable: ::

make

If successful, the resulting executable name will look something like ``PeleLM2d.gnu.ex``. Depending on your
compilation option the actual name of the executable might vary (including ``MPI``, or ``DEBUG```, ...).

Running `PeleLM`
----------------
Expand All @@ -94,7 +132,7 @@ Visualization of the results
----------------------------

There are several options for visualizing the data. The popular
packages `Vis-It` and `Paraview` support the `AMReX` file format natively (currently called ``BoxLib`` format),
packages `Vis-It` and `Paraview` support the `AMReX` file format natively,
as does the `yt` python package. The standard tool used within the
`AMReX`-community is `Amrvis`, a package developed and supported
by CCSE that is designed specifically for highly efficient visualization
Expand All @@ -103,4 +141,3 @@ tools available in `Amrvis`, so most users make use of multiple tools depending

For more information on how to use `Amrvis` and `VisIt`, refer to the `AMReX`
User's guide in the `AMReX` git repository for download/build/usage instructions.

Loading

0 comments on commit 434793c

Please sign in to comment.