************************************************************************
    This file is part of
    FEINS, Finite Element Incompressible Navier-Stokes solver,
    which is expanding to a more general FEM solver and toolbox,
    Copyright (C) 2003--2008, Rene Schneider 
    <rene.schneider@mathematik.tu-chemnitz.de>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program. If not, see <http://www.gnu.org/licenses/>.

    Minor contributions to this program (for example bug-fixes and
    minor extensions) by third parties automatically transfer the
    copyright to the general author of FEINS, to maintain the
    possibility of commercial re-licensing. If you contribute but wish
    to keep the copyright of your contribution, make that clear in
    your contribution!

    Non-GPL licenses to this program are available upon request from
    the author.
************************************************************************

------------------------------------------------------------------------
Getting started:
------------------------------------------------------------------------


Compilation 
-----------

Requirements: 
 * LAPACK and BLAS, see "http://www.netlib.org" should be in the default
   search path for libraries 
 * the "Triangle" mesh-generator should be in subdirectory "triangle",
   specifically a file "triangle/triangle.c" will be used. See 
	"http://www.cs.cmu.edu/~quake/triangle.html"
   A note from the Triangle website of Jonathan Richard Shewchuk:
   "Please note that although Triangle is freely available, it is copyrighted
    by the author and may not be sold or included in commercial products
    without a license."
   A copy of Triangle may already be included in this distribution.
 
Compilation of the source code on different architectures is
controlled via the environment variable $ARCHI. The master makefile
picks the architecture dependent variables by including
"make_inc.$ARCHI". See what Architectures are already available by
listing "ls make_inc.*".

Attention: between the gcc versions 3.* and 4.* a major change has
occured on how to link C-code to Fortran libraries (e.g. LAPACK). Note
the difference between LINUX_P4 and LINUX_P4_GCC4, both are for Intel
Pentium 4 based machines.

To set a $ARCHI, type for example 
"export ARCHI="LINUX_P4_GCC4" #(Bash)
or 
"setenv ARCHI "LINUX_P4_GCC4" #(csh, tcsh).

To compile and link or rebuild after code changes: 
"make test_navsto_solver"



Running the Navier-Stokes solver
--------------------------------

Make sure a subdirectory visual/ exists.

Once compiled, run
"./test_navsto_solver"
to get some information on arguments

To get something working, try 
"./test_navsto_solver bump.f1m 0 6"

This will solve a problem on a mesh with 132225 nodes, resulting in
297795 degrees of freedom in the FE-system. The last number are the
number of uniform refinement steps for the initial and the final mesh
in the multigrid hierarchy. Solving this problem takes about 10
minutes on my current machine.

This Navier-Stokes solver is geared toward shape optimisation. For a
given mesh file "exmesh.f1m" it will compute the performance criteria
specified therein, by the geometry and the parameters, and save the
results in "exmesh.f1m_crit". The sensitivities of these criteria
wrt. the shape parameters defined in the mesh will be saved in
"exmesh.f1m_grad", the FE solution vector in "exmesh.f1m_sol" which
allows re-use to some degree.

The format of the mesh files (*.f1m) is fairly well documented in
"mesh_example.f1m".

Output of the flow solution for visualisation is for now only possible
in three formats:
  * NAG Iris explorer (to which I have no longer access) in 
     visual/2d_mesh*.pyr and .lat
  * flow profiles along horizontal and vertical lines pre-specified in
    the source code are saved in
     visual/line.[xy].[level].txt
  * output for grape is also possible.

If you know of a open source tool to visualise data on triangular
elements, please let me know!

It is a good idea to keep the visual subdirectory on a fast local disk
and symlink to it, because the files there can get very large.



Troubleshooting:
----------------

- Upon trying to run make you get 
   "No rule to make target `make_inc.'"
  or similar.
+ Set $ARCHI, see above.

- Upon trying to run make you get something similar to 
  "make: *** No rule to make target `/usr/lib/..../stddef.h',
  needed by `test_stokes2.d'.
+ try "make clean", and if that fails as well "rm *.d"



Overview of the files in the code
---------------------------------

For most of the *.c files exists a *.h file that is automatically
created using the headerer.pl script. Those automatically created
header files are omitted here. The makefile also creates *.d files
which are used to keep track of changes in header-files and to
initiate a re-compilation if header-files have changed.


feins_macros.h            - defines a few preprocessor macros for 
			    error-handling and global setup of parameters
datastruc.h               - defines the basic data structures for the FEM:
                            i.e. the mesh, handling of cubature information and
                            basis functions for the elements, 
			    hierarchical/multilevel information, BPX and
			    multigrid preconditioning, and general purpose data
                            structures such as simply connected list of
                            integer data
meshdetails.h             - provides the "what is where" information for
                            locating data within the parts of the mesh
			    data structure by defining preprocessor constants
sparse_struct.h		  - data-structure for sparse matrices and vectors,
			    struct for vectors sufficiently simple and 
			    canonical  such that direct manipulation allowed,
                            but sparse matrices should always only be accessed
			    via routines in sparse.c, such that replacement of
			    the whole storage format remains feasible without
			    changes in the code using the matrices!
navsto_struct.h 	  - data structure for collecting sparse matrices into
			    the block structure natural to the Stokes and 
			    Navier-Stokes equations, also holding data required
			    for the preconditioning of the systems 

assembly.c                - assembly for Poisson and Lame equations and some
 			    general assembly routines
boost_wrapper.h           - deprecated, was used to for an interface
                            to the boost library, 
cd_assem.c                - will contain convection-diffusion assembly
copyright_header.h        - the copyright header which should be in each source
                            file
cubature.c                - creates cubature formulas
elements.c                - defines ansatz functions on n-d elements
feins_lapack.h            - header information to interface with the
                            (Fortran 77) libs LAPACK and BLAS
gen_aux.c                 - collects general auxiliary routines (e.g. projected
                            matrix-vector product and general BPX-preconditioner)
lin_solver.c              - (iterative) solvers for linear equation systems
                            (CG, PCR, GMRES)
mesh.c                    - all routines handling the mesh data-structure
mesh_deform.c             - deformation of the initial mesh to allow for curved
			    geometries and avoid re-meshing after shape
			    parameter change
navsto_ad_derivs.c        - deprecated, (did collect routines to be 
			    AD differentiated)
navsto_adj.c              - routines required for the adjoint implementation
                            for Navier-Stokes, e.g. performance functional and
                            derivatives of the residual
navsto_aux.c              - auxiliary routines for Navier-Stokes, e.g.
			    matrix-vector multiply and preconditioners
navsto_solver.c           - outer solver for Navier-Stokes + shape sensitivity
navsto_solver_bcontrol.c  - dito, but for sensitivity to boundary control
navstoassem.c             - assembly for Navier-Stokes system
needderiv2.c              - deprecated, similar to navsto_ad_derivs.c
process_parallel.c        - routines to control distribution of (serial) jobs
                            over a parallel computer (MPI),
			    (e.g. for tests of parameter ranges)
sparse.c		  - handling of the sparse matrices in their basic
                            form and vector operations
stokes_aux.c              - auxiliary routines for Stokes, e.g.
			    matrix-vector multiply and preconditioners
stokesassem.c             - assembly for the Stokes system
stokes_struct.h           - deprecated, replaced by more general navsto_struct.h
test_assem.c              - test of the Poisson assembly by solving the Poisson
                            equation
test_lame.c               - test for the lame-assembly
test_mesh_deform.c        - test routine for the mesh_deform routine
test_navsto.c             - deprecated test of Navier-Stokes routines
test_navstoMG.c           - deprecated test of Navier-Stokes routines, 
                            development of multigrid 
test_navsto_solver.c      - outer control of the navsto_solver routine
test_navsto_solver_bcontrol.c
                          - dito for boundary control
test_navsto_solver_derivpaper.c
                          - dito with special modifications for the paper 
			    "On the Evaluation of Finite Element Sensitivities
			     to Nodal Coordinates"
test_print_cubat.c        - for debugging the cubature formulas
test_stokes.c             - deprecated outer loop of Stokes solver
test_stokes2.c            - outer loop of Stokes solver
