[GRASS-dev] New grass library and modules

[Soeren Gebbert]

Dear developers,
i would like to submit a new library and two modules based on the new library 
into cvs.

The new library called "gpde_lib" is designed to support the solution of 
partial differential equations within grass. The discretization of PDE's is 
based on raster and volume maps. 
I have implemented groundwater flow for two and three dimensions.
Heat flow and solute transport are on my todo list.

All library functions start with a N_ 
eg: N_create_les() or N_alloc_array_2d().

The current draft doxygen documentation is available here:

http://www-pool.math.tu-berlin.de/~soeren/grass/modules/grass-pde-lib/html/

I have implemented two modules based on the new library to solve confined and 
unconfined groundwater flow in two dimensions and confined groundwater flow 
in three dimensions. The two programs are still very basic and support only 
two boundary conditions (dirichlet and neumann).

The modules are called r.gwflow and r3.gwflow.

The grass PDE lib provied functions to create and solve lineare equation 
systems. Therefor different linear equation solvers are implemented:
* LU decomposition for quadratic matrices (direct)
* GAUSS elimination for quadratic matrices (direct)
* CG method for quadratic and sparse matrices (iterative)
* BiCGStab method for quadratic and sparse matrices (iterative)

The solvers and the creation of a linear equation system (matrix assembling) 
are parallelized with OpenMP http://www.openmp.org. The speedup of the 
solvers is quite good (IMHO):
http://www-pool.math.tu-berlin.de/~soeren/grass/modules/screenshots/sgi_altix_cg_bench.png

The new library do not use functions of the gmath library to create vectors or 
matrices, or to solve a linear equation systems. There reasons are:
1.) I was quite unsure if the gmath library calls are thread safe
2.) I do not wanted to use function calls to get access to vectors and
     matrices for performance reasons
3.) I wanted to parallelize the equation solvers with OpenMP and therefor all 
     vector and matrix operations i use
4.) I'm not very familiar with the gmath library 
5.) I do not know which gmath functions need LAPACK or BLAS

If those question can be clarified, it should be possible to use gmath 
functions in the gpde library.
The only problems i see for now are, that there are two different function 
calls to perform a LU decomposition and the gpde lib do not use the matrix 
and vector structures of the gmath lib.

I have implemented a lot of unit and integration tests on code basis, which 
will also be commited into cvs. Those tests assure the correct functionality 
of the lib. If the tests are compiled, a new module called test.gpde.lib is 
created and can be executed within grass to test all functions of the 
library. IMHO we should create a test structure for each library to check the 
correct functionality on function base. 

If there are no objections against the library, i would like to commit it to 
cvs.

Best regards
Soeren