Update and break into separate files.

Regression testing

==================

Generating local regression test data

-------------------------------------

Developers are encouraged to create local benchmark data for regression

testing prior to committing code the GitLab repository.

1. Create a location to store benchmark data and clone the MFiX and

   AMReX repositories.

   .. code:: shell

       mkdir /home/user/exa-rt

       mkdir /home/user/exa-rt/benchmark

       cd /home/user/exa-rt

       git clone http://mfix.netl.doe.gov/gitlab/exa/mfix.git

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

2. Create a local copy the regression test setup file from the MFiX

   repository.

   .. code:: shell

       cp mfix/RegressionTesting/MFiX-tests.ini MFiX-local.ini

3. Edit the local setup file. Specify the top level directories for test

   and web output under the ``[main]`` heading.

   .. code:: shell

       [main]

       testTopDir = /home/user/exa-rt/benchmark

       webTopDir =  /home/user/exa-rt/web

   Specify the AMReX source directory location under the ``[AMReX]``

   heading.

   .. code:: shell

       [AMReX]

       dir = /home/user/exa-rt/amrex

       branch = development

   Specify the MFiX-Exa source directory location under the ``[source]``

   heading.

   .. code:: shell

       [source]

       dir = /home/user/exa-rt/mfix

       branch = develop

4. Run the AMReX regression test tool. The second argument is a user

   supplied comment.

   .. code:: shell

       cd /home/user/exa-rt

       amrex/Tools/RegressionTesting/regtest.py --make_benchmarks "MFiX" MFiX-local.ini

+------------------------------------------------------------------------------------------------------------------------+

| ## Prerequisite: Environment Dependencies on Joule (Joule specific)                                                    |

+------------------------------------------------------------------------------------------------------------------------+

| For the Joule environment, load the gnu module and set environment variables first. If not on Joule, skip this step.   |

+------------------------------------------------------------------------------------------------------------------------+

| \`\`\`shell                                                                                                            |

+------------------------------------------------------------------------------------------------------------------------+

| > module load gnu/6.1.0                                                                                                |

+------------------------------------------------------------------------------------------------------------------------+

| > export CC=/nfs/apps/Compilers/GNU/6.1.0/bin/gcc                                                                      |

+------------------------------------------------------------------------------------------------------------------------+

| > export CXX=/nfs/apps/Compilers/GNU/6.1.0/bin/g++                                                                     |

+------------------------------------------------------------------------------------------------------------------------+

| > export F77=/nfs/apps/Compilers/GNU/6.1.0/bin/gfortran                                                                |

+------------------------------------------------------------------------------------------------------------------------+

| > export FC=/nfs/apps/Compilers/GNU/6.1.0/bin/gfortran                                                                 |

+------------------------------------------------------------------------------------------------------------------------+

| \`\`\`                                                                                                                 |

+------------------------------------------------------------------------------------------------------------------------+

Running MFiX Test Suite

=======================

MFiX-Exa comes with several tests aimed at evaluating software

functionalities. The source files as well as the required input files

for each test are located in the ``tests`` directory. The ``tests``

directory is copied to the build directory during MFiX-Exa configuration

process. When a test is run (see below), output files are stored in

``build_dir/tests/test-name``.

There are various dependencies for comparing test results.

o To compare results to archived flow slices stored in ``AUTOTEST``

directories with the case files, the environment variable ``FEXTRACT``

must point to the location of the AMReX ``fextract`` utility located in

the directory, ``amrex/Tools/PostProcessing/F_Src``. Additionally,

``numdiff`` must be installed for comparing results.

o To compare point-by-point field data, the environment variable

``FCOMPARE`` must point the AMReX utility ``plt_compare_diff_grids``

found in the directory, ``amrex/Tools/PostProcessing/F_Src``.

Additionally, the environment variable ``MFiX_BENCHMARKS_HOME`` must

point to the location of a local regression test data set. See

*Generating local regression test data* for instructions on creating a

local regression test data set.

Run all tests

-------------

.. code:: shell

    > cd to mfix-build-dir

    > ctest

List all tests (without running them)

-------------------------------------

.. code:: shell

    > cd to mfix-build-dir

    > ctest -N

Run a particular test by the index listed in ctest -N

-----------------------------------------------------

.. code:: shell

    > cd to mfix-build-dir

    > ctest -I 3,3             # run the third test

Run a particular test by name

-----------------------------

.. code:: shell

    > cd to mfix-build-dir

    > ctest -R DEM01  # running all tests with "DEM01" in the test name

Run a particular test via make

------------------------------

.. code:: shell

    > cd to mfix-build-dir

    > make run_DEM01-x  # running "DEM01-x" and output to the screen

Run specific

------------

If the environment variable GRID is defined, it specifies which grid

types to run for the test(s). If GRID variable is not defined, the

default is to run the tests for all grid types. > env GRID="tiled" ctest

-R DEM01 # running all tests with "DEM01" for tiled grid > env

GRID="single multiple" ctest -R DEM01 # running all tests with "DEM01"

for single grid and multiple grid > ctest -R DEM01 # running all tests

with "DEM01" for all grid types (single, multiple, tiled)

Run a user-defined case

-----------------------

.. code:: shell

    > ./mfix inputs-myrun

*inputs-myrun* is a text file containing the AMReX input parameters;

this can be named anything as long as it is the **first** argument

following the executable. Note that many of the problem parameters are

still defined in *mfix.dat*.

See the User's Guide for more about MFiX-Exa

============================================

To build the User's Guide,

.. code:: shell

    > cd doc/UsersGuide

    > make

This will build a pdf of the MFiX-Exa User's Guide, which contains

information about the equations being solved, run-time parameters,

checkpoint/restart capability, options for visualization and more.

Directory overview

==================

+--------------+------------------------------------------------+

| File         | Description                                    |

+==============+================================================+

| benchmarks   | UC Benchmark cases (see benchmark/README.md)   |

+--------------+------------------------------------------------+

| doc          |  Source code for building the documentation    |

+--------------+------------------------------------------------+

| exec          | Directory for building with gmake (optional)  |

+--------------+------------------------------------------------+

| exec_cc       | Directory for building with gmake (optional)  |

+--------------+------------------------------------------------+

| src          | Source files for SIMPLE and projection algorithm |

|              | with face-centered velocity components         |

+--------------+------------------------------------------------+

| src_cc       | Source files for projection algorithms with    |

|              | cell-centered velocity components              |

+--------------+------------------------------------------------+

| tests        | Regression tests (see tests/README.md)         |

+--------------+------------------------------------------------+

| tools        | CMake configuration files                      |

+--------------+------------------------------------------------+

| tutorials    | Set-ups for different EB geometries            |

+--------------+------------------------------------------------+