************************************************************************
    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 
-----------

These instructions are for Linux and most Unixes. There they should work, 
especialy if a recent version of the GNU compiler collection can be used.

Support for Windows is only preliminary and not (yet) maintained. But a few
remarks to this end can be found below, Section Compilation on Windows.

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.
 
Automatic configuration is achieved using cmake, 
   http://www.cmake.org/ .
A typical configure an compile call would be 

   cd [feins_root/]build
   cmake ../src
   make test_navsto_solver

creating the executable "test_navsto_solver" in the directory build. 



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

Make sure a subdirectory build/visual/ exists.

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

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

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
"meshfiles/mesh_example.f1m".

Output of the flow solution for visualisation is for now only possible
in four formats:
  * paraview (http://www.paraview.org/) in 
    visual/2d_mesh_vtk_.vtk
    in "paraviewfiles" you can find a few example configurations of
    paraview 
  * 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 another 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:
----------------

- (nothing yet)



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

All the source code is held in the directory "src".
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.

src/
  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
  assem_conv_diff.c       - assembly for Convection-Diffusion equations 
  boost_wrapper.h         - deprecated, was used to for an interface
                            to the boost library, 
  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_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
  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
  test_assem.c            - test of the Poisson assembly by solving the Poisson
                            equation
  test_convection_diffusion.c        - test of the Convection-Diffusion assembly by 
                            solving the Convection-Diffussion equation
  test_lame.c             - test for the lame-assembly
  test_mesh_deform.c      - test routine for the mesh_deform routine
  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_stokes2.c          - outer loop of Stokes solver




Compilation on Windows
----------------------

There are two variants to this end. The simpler and more reliable appears
to be the use of MinGW, the "Minimalist GNU for Windows", profiding the 
GNU toolchain.
  http://www.mingw.org/
The other variant is to use the native Visual Studio Compilers. However, 
since there is no Fortran compiler included in Visual Studio, loads of
trouble are to be expected linking to BLAS and LAPACK in this case.

Cmake is available for windows, this helps in both cases. 

Note that in all cases you will probably have to convert the meshfiles 
to have windows line endings, e.g. "unix2dos donut.f1m".

The compilers are compared by taking timings of the execution of the 
example "test_lame_adj donut.f1m". The results are reported in 
  testresults/windows_performance_comparison.txt


Compilation using MinGW
-----------------------

Luckily the current release 3.3.0 of Lapack contains CMake support. 
So once you have installed MinGW (with the GNU compiler collection, 
both gcc and gfortran will be required) you can install BLAS and LAPACK
by running the following commands in the MinGW shell: 
  cd lapack-3.3.0
  cmake.exe -G "MSYS Makefiles" .
  make
  cp BLAS/SRC/libblas.a SRC/liblapack.a /lib/
Then go to the FEINS directory and compile FEINS in almost the usual way
  cd feins
  ls
  cd build
  cmake.exe -G "MSYS Makefiles" -DCMAKE_VERBOSE_MAKEFILE=ON -DBLAS_LIBRARIES=blas -DLAPACK_LIBRARIES="-L/lib/ -llapack -lblas -lgfortran" ../src/
  make

The automatic detection of LAPACK and BLAS fails on MinGW for some 
reason, but this simple workaround of specifying them directly does the 
trick. 


Compilation using Visual Studio
-------------------------------

We have been able to compile all executables with Visual Studio 9 (2008). 
This required numerous changes of non-standard portions of the code. So 
this porting should have improved the standard compliance of the code
also with respect to other compilers. 

The most difficult part was to link against LAPACK and BLAS. The default 
CMake functionality only works if a Fortran compiler is available. For 
this the Intel Fortran Compiler (ifort) can be used with Visual Studio. 
This However is not included in Visual Studio and comes at an extra price 
(although a 30 days trial is available for download). We have tried to
avoid this by using precompiled libraries from the web. 

The version we have used is from
  http://www.fi.muni.cz/~xsvobod2/misc/lapack/
using the .dll version.

We have also tried the pre compiled libraries from
  http://icl.cs.utk.edu/lapack-for-windows/
but couldn't make this work. This may become more interesting though, as
this project appears to be ongoing. They have set the goal to provide a 
windows installer.

We have used the cmake-gui (Version 2.8.4) and set the generator to 
  "Visual Studio 9 2008". 
This generates .vcproj files which you can open with Visual Studio.
As we couldn't find a way to work around the Fortran requirement that the 
cmake modules for BLAS and LAPACK generate, we modified the CMakeLists.txt
to not use this automatic detection. This modified file is now called 
   CMakeLists_win32.txt
(you may have to rename it to CMakeLists.txt). It specifies the .lib files
directly and also the library path. However, this is still of limited use,
as the corresponding .dll files have to be in the path. We have opted to
put them in the build directory where the .exe files are build, i.e. in 
build/Debug, which is generated when you first try to build the project.

This should set out the main points that have to be taken care of. If you 
succeed in improving this build procedure or apply it with different
version of the compilers, please let us know.
