Testing FACETS

To test FACETS, one must first obtain the fctests regression suite:

svn co https://ice.txcorp.com/svnrepos/code/fctests/trunk fctests

Next, you have to decide which results you are going to compare your runs against. If you are running fctests for the first time on your platform, then you will start with an empty results directory which will be populated after your runs are completed. On the other hand, if you are running on a platform where accepted results currently exist (e.g., multipole.txcorp.com), then you would want to check against those results. To get a list of the results sets that are available, use the following:

svn ls https://ice.txcorp.com/svnrepos/results/fcresults/trunk

For the case of multipole.txcorp.com, you would check out the results like so:

svn co https://ice.txcorp.com/svnrepos/results/fcresults/trunk/multipole fcresults

Finally, fctests must be configured:

cd fctests
config/cleanconf.sh
./configure --with-source-dir=/path/to/facets/source --with-serial-dir=/path/to/facets/serial/build \
        --with-parallel-dir=/path/to/facets/parallel/build --with-testdata-dir=/path/to/fcresults

...where source-dir is the directory containing your FACETS source code, serial-dir is the top level of your serial FACETS build, parallel-dir is the top level of your parallel FACETS build, and fcresults is either a checkout as noted above, or an empty directory you create, in the event you are running on a new platform.

As a result of running configure, a file called path.sh will be generated. This file contains a number of variable definitions which are crucial to the proper functioning of fctests.

At this point, you are ready to run the tests. Note that one should run both serial and parallel tests before committing new code; it's possible that an error exists in only one of the builds.

To run the entire suite of tests:

make check

To run the entire suite of tests but discard the output except "pass" and fail" messages (makes it easier to run interactively):

make check-grep

During development, you may wish to run only a single test or subset of the tests in order to save time. This practice is acceptable, as long as you run the entire suite of tests prior to committing new code.

To run only the serial tests:

make check-serial

...and, unsurprisingly, you can run the parallel tests with the complementary command:

make check-parallel

In addition, the make check command will work in any subdirectory. For example, to run only the diffusion tests, you would:

cd tests/diffuse
make check

To run a single test, e.g., advectp.sh (parallel advection), you would:

cd tests/advect
make check-test TEST_NAME=advectp

You can also run a single test by first sourcing txtest/test.aliases (you can do this in your .bashrc file so that you don't have to remember to do it each time), and then typing

check advectp

N.B. test.aliases will only work for bash or other shells derived from sh (i.e., it will not work with csh/tcsh).

Adding new tests (under construction)

Before we do this, however, it will be instructive to understand how the tests are organized within fctests. To do this, change your working directory to 'tests':

cd tests

Inside this directory you will find a number of subdirectories representing the overall organization of the tests: advect, core, diffuse, equil, and other (there are other subdirectories, but the tests within within them are not currently being run as part of the suite). To see how the individual tests are created, change your working directory to 'advect':

cd advect

Once inside this directory, you'll see advect.pre, which is the FACETS input file which performs "Advection equation on domain spread over two components." This file is run through the preprocessor to produce advect.in, which is the input file to FACETS.

Each test which is part of the suite has a shell script which runs FACETS, so that running the test is as simple as running the script (and, as we'll see, modifying the test is as simple as editing the script), which runs the preprocessor on the .pre file and invokes FACETS on the .in file. In addition, the script performs other setup tasks.

In our example, the script is called advectp.sh, where the 'p' indicates the test will be run in parallel.