fentonWave - A stream function wave boundary condition for OpenFOAM
===================================================================

This is an OpenFOAM boundary condition class for generation of stream function waves.
It is intended for use with interFoam type solvers in coastal and offshore applications.
The implementation for the Fourier approximation of the stream function waves follows
closely the describtion in section 3.1.2 of the paper by J.D. Fenton, "Numerical
Methods for Nonlinear Waves" (1999), Numerical Methods for Nonlinear Waves,
Advances in Coastal and Ocean Engineering, Vol. 5, pp241-324. Equation numbers in
the code refer to this paper. At the time of writing the paper could be downloaded
here:

http://www.johndfenton.com/Papers/Fenton99Liu-Numerical-methods-for-nonlinear-waves.pdf

The assumptions behind the calculation are: 

- 2-dimensional flow with the surface elevation a well-defined function of the position 
  along the axis of wave propagation.
- Infinite, flat, horizontal seabed
- Inviscid fluid and irrotational flow so that stream function theory applies
- Steady flow, i.e. there is a frame of reference in which the flow is stationary
- Periodic flow (with either wave period or wave length specified by the user)

There is no assumption about infinitesimal wave amplitude as is the case for linear
(Airy) waves.

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

Compiled as a library libFentonWaveBC.so in the FOAM_USER_LIBBIN using 'wmake libso'.

Prior to compilation you must ensure that you have the GSL (Gnu Scientific Library) 
installed on your computer. The source can be downloaded from here:

ftp://ftp.gnu.org/gnu/gsl/

After downloading GSL install it by following the instructions in the INSTALL file.

You must also export an environmental variable, GSL_DIR, containing the path to the GSL 
installation such that the following files exist:

$GSL_DIR/include/gsl/gsl_vector.h 
$GSL_DIR/include/gsl/gsl_multiroots.h
$GSL_DIR/lib/libgsl.so
$GSL_DIR/lib/libgslcblas.so

Usually GSL_DIR is simply /usr.

After running 'wmake libso' from the fentonWave directory GSL_DIR may be unset.

Usage
=====

See header in fentonWaveFvPatchField.H and tutorials

Availiability
=============

This code is freely available at https://github.com/roenby/fentonWave.git

Features
========
Calculates Fourier coefficients only once at object construction and writes
data to a file. 

The code uses template specialization to minimize code duplication and allow the 
same class to be used for both volume fraction, velocity and pressure fields.

The volume fraction field at faces intersected by the water surface is calculated 
correctly provided the faces are parallelograms (in particular rectangles) with 
horizontal sides.

Bug reporting
=============

Please report bugs to jro at dhigroup.com

Author
======

Johan Roenby, DHI Water & Environment, jro at dhigroup.com

Todo
====

- Add tutorials
- Implement analytical fixedGradient pressure field
- Specify waveProperty file name in 0/field to allow different 
  dictionaries for different boundaries
- Generalize face cutting method in alpha calculation to allow
  arbitrary face shapes on the patch

Known bugs
==========

- The root finding algorithm has been observed to crash with a floating 
  point exception if very small wave height is used in combination with
  too many nHeightSteps. Try to lower nHeightSteps.