README for Immersed Boundary Projection Method (IBPM)
=====================================================

The code contained in this distribution uses an immersed boundary method to
solve the two-dimensional incompressible Navier-Stokes equations around
complex geometries, using the projection method described in Taira and
Colonius (2007). In particular, this code implements the "fast method"
described in Section 3.3 of Colonius and Taira (2008), using the multi-domain
approach for far-field boundary conditions, as described in section 4 of this
reference.


Getting started
===============

To run the code, first build the executables as described below. The main
executable is called 'ibpm' and will be created in the 'build' directory.

The code reads an input file to determine the geometry, and a sample input
file (for a cylinder) is contained in 'examples/cylinder.geom'.

To run the code for this example:
	cd examples
	../build/ibpm -geom cylinder.geom

This will initialize the solver with a zero initial condition, and evolve the
flow for 250 timesteps, writing binary 'restart' files (e.g. ibpm00100.bin)
and ASCII files readable by the Tecplot plotting software (ibpm00100.plt).
Lift and drag forces are written to the file ibpm.force, and the command
executed is written to a file ibpm.cmd (so the same run can be recreated
later).

The default options (numbers of gridpoints, names of output files, etc) can be
changed by command line arguments. To see the available options:
	../build/ibpm -h


Installation
============

Requirements:
	C++ compiler

	FFTW library, version 3
		http://www.fftw.org/

	Doxygen (to build documentation)
		http://www.stack.nl/~dimitri/doxygen/


Building the library and executables:

The default configuration is to compile the code with the GCC compiler, with
the FFTW library in a default location known to the compiler (e.g.
/usr/local/lib). If this is acceptable, then to build the library and
executables, all you need to do is type

	make

from the root directory of the distribution (we will call this <ibpm>). The
library and command-line tools will be generated in the 'build' directory.

To customize the build process for your system, make a copy of the file
'config/make.inc.gcc' and modify it as needed (this file is included by other
Makefiles, and the format is pretty self-explanatory). Save the new file as
<ibpm>/config/make.inc and type 'make' from the root <ibpm> directory, as
before.

Building and running the automated tests:
	make test

Building the documentation:
	make doc


Documentation
=============

The documentation consists of a user manual (in doc/ibpm_manual.tex), which
describes the main functionality of the code, as well as detailed
documentation automatically generated by Doxygen.

The user manual is the best starting place for new users, and explains the
format of the geometry files, among other things.

The default configuration for the automatically generated documentation is to
generate both html and LaTeX documentation, but this can be changed by
modifying the file 'doc/Doxyfile'. Once the documentation has been built, the
html documentation (usually the most useful) can be found in
'doc/html/index.html', and the LaTeX documentation can be found in
'doc/latex/refman.tex'.


References
==========
K. Taira and T. Colonius. The immersed boundary method: A projection approach. J. Comput. Phys., 225(2):2118-2137, August 2007.

T. Colonius and K. Taira. A fast immersed boundary method using a nullspace approach and multi-domain far-field boundary conditions. Comp. Meth. Appl. Mech. Eng., 197(25-28):2131–46, 2008.