ElmerSolver test case how-to 
============================

This How-to describes how to create and use test cases in software
development and case definition. 

The test cases are used to check for possible bugs, and to ensure
consistancy and backward compability. For that purpose they are
currently around 160 (Feb 2011) minimalistic cases the run-time of
each is typically measured in seconds. The tests should be located in
directory

$ELMERHOME/tests

To run the cases in Unix/mingw you can go the the directory tests and say

Make check



A. How to create a test case 
----------------------------

When a new feature has been verified it is often a good idea to
create a mimalistic test case that ensures the feature will be 
maintained also in the future versions of Elmer. To do this:

1) create new directory in the "tests" directory under fem/. The folders
   in this directory will be automatically scanned and tests run

2) define your analysis write your .sif file, mesh files
   etc. necessary to run the test analysis ELMERSOLVER_STARTINFO

3) define how to run the test write a Makefile (named Makefile), that
   details two targets: run: how to run the test clean: how to
   clean up if successfull Note, that ElmerSolver should be
   referred to by variable $(ELMER_SOLVER) to allow the test
   runner to select the binary to test

4) Define expected results Add the following lines to your .sif file
	
    $fprintf( stderr, "TEST CASE 1\n"); RUN $fprintf( stderr, "END
     TEST CASE 1: Target NRM=<target>,EPS=<eps>\n" );
	
    where you replace <target> with the target NRM value and <eps>
    with the desired tolerance. These lines will add lines to
    output and the test runner find these and compare actual
    values emitted by the solver with the specified target.  The
    NRM value is the norm of the result vector. Normal way to
    determine desired value is to examine the analysis results in
    detail the first time and if the results are OK, record the
    NRM value and use it as target value in the future.

5 ) If you have access right to the svn you may also

       svn add mytestcase
       svn commit mytestcase
 


B. How to use the test case as starting point
---------------------------------------------

One can take these examples as a starting point or copy-paste
appropriate solver sections from there. These examples do not include
any ElmerGUI project file and therefore the graphical user interface
cannot be used to view these cases. You can look at the Makefile in
each test to see what sequence of command is usually needed. Typically
some simple ascii definition for the mesh is used and the running of
the case could be something like

ElmerGrid 1 2 square
ElmerSolver

Now to get more out of the test the user may add verbosity of
ElmerSolver and define an output file in the Simulation section

Max Output Level = 10 
Post File = case.ep

Also, to increase the problem size one can increase the mesh density,
for example, by

ElmerGrid 1 2 square -relh 0.5
