1. Intro
---------

This file gives a brief description of how to use the supplied C++ code for
generating 3-dimensional velocities distributed according to the Maxwellian
inflow distribution. The generator implements in total 7 algorithms,
the four main algorithms:

 Envelope 1 (for a <  0, recommended for low-speed problems)
 Envelope 2 (for a <  0, recommended general problems)
 Envelope 3 (for a >= 0, recommended for low-speed problems)
 Envelope 4 (for a >= 0, recommended general problems)

and for instructive comparison, the less efficient Inverse Transform method
and the two approximate methods:

 Box envelope
 Reservoir envelope

Much of the standard mathematics in the generator (like uniform and gaussian
random number generators and evaluation of the error function) has been
implemented using the Gnu Scientific Library (GSL). This library may not be a
standard component, and has to be downloaded and installed manually if
necessary (see "1. Installation requirements").

Each occurrence of a GSL-specific component in the code (like a function call
or a numeric constant) is followed by a comment starting with the phrase
"gls-specific content".


2. Source code contents
------------------------

The source code of the generator consists of 3 files:

 MaxwellInflowGen.h
 generators.h
 Rnd.h

The code is written in (object oriented) C++, and the file MaxwellInflowGen.h
defines the main class (MaxwellInflowGen) in which the generator is
contained. The file generators.h defines a set of classes, one for each of the
7 generator algorithms, that envelop the 7 specific algorithms. All
algorithm-specific code is thus contained within each these classes.
The file Rnd.h contains a class that provides uniform and Gaussian random
number generators.


3. Installation requirements
-----------------------------

The generator takes advantage of several components of the Gnu Scientific
Library (GSL). If this is not already installed on the system, it needs to be
installed manually. All information about GSL, including full documentation
and downloadable source code can be found at:

http://www.gnu.org/software/gsl/

As of May 5th 2006, the latest version, GSL-1.8, can be found here:

ftp://ftp.gnu.org/gnu/gsl/gsl-1.8.tar.gz

After downloading, unpack this file with:

tar -xzf gsl-1.8.tar.gz

A directory, gsl-1.8, will be created containing all the source code of
GSL. Within this directory, instructions on how to compile and install GSL can
be found in the INSTALL file. In short, the installation consists of three
steps invoked by the following commands:

./configure
make
make install

Note that the default installation directory is /usr/local. Only a user with
root privileges can install on /usr/local. A different directory can be
chosen, typically $HOME/install (where $HOME is the path to the users home
directory), by modifying the first step:

./configure --prefix=PATH

where PATH may be substituted by the desired directory (i.e. $HOME/install)


4. Program example
-------------------

In the following program example substitute PATH_TO_SOURCE with the path to
the directory containing the 3 files listed in "2. Source code contents". The
program generates 100 velocity vectors and writes them to standard output.

#include "PATH_TO_SOURCE/MaxwellInflowGen.h"
#include <iostream>

using namespace std;

int main() {

  double rho   = 1;          //Density
  double T     = 0.5;        //Temperature
  double V[]   = {0, 0, 1.}; //Fluid velocity, cartesian coordinates (x,y,z)

  //Angular orientation of normal surface vector
  //pointing along the positive inflow direction
  double phi   = 0; // The angle between the positive x-axis and
                    // the vector projected onto the xy-plane, [0, 2pi]
  double theta = 0; // The angle between the positive z-axis and
                    // the vector, [0, pi]

  //Creating an object of the main generator class
  MaxwellInflowGen max(rho, T, V, phi, theta, 0, 1, new Envelope3(2, 3, 4, 5));

  /* Notes on the parameters of MaxwellInflowGen max(...):
   * All the integer parameters are seeds to random number generators. The
   * first two (0 and 1) are for the two velocity components parallel to the
   * inflow plane. Note that the last parameter is a pointer to an object
   * containing the specific algorithm for the normal velocity component, in
   * this case Evelope3 which takes four seeds to initialize its random
   * number generators.
   */

  double v[3];
  for (int i = 0; i < 100; i++) {
    max.generateVelocity(v);
    cout << v[0] << " "
         << v[1] << " "
         << v[2] << endl;
  }


  return 0;

}

The formal declaration of the constructor of MaxwellInflowGen is:

MaxwellInflowGen(double rho, double T, double V[], phi, theta,
                 unsigned long int s1, unsigned long int s2,
                 Generator* generator);

The parameters are defined and described in the comments of the above example
program.

Generator is the base class for the normal velocity generator classes. Their
constructors are declared as follows:

Envelope1(unsigned long int s1, unsigned long int s2);

Envelope2(unsigned long int s1, unsigned long int s2,
          unsigned long int s3);

Envelope3(unsigned long int s1, unsigned long int s2,
          unsigned long int s3, unsigned long int s4);

Envelope4(unsigned long int s1, unsigned long int s2,
          unsigned long int s3, unsigned long int s4);

For declarations of constructors of the other supplied Generator-derived
classes, see the comment near the top of the generators.h file.


5. Compiling and linking
-------------------------

To appropriately include the components of the GSL-library the two following
parameters must be given to the linker:

-lgsl -lgslcblas

If GSL was not installed on /usr/local (as per default) but for example on
$HOME/install (see "3 Installation requirements") then the following parameter
must be given to the compiler:

-I$HOME/install/include

and the following parameter must in addition be given to the linker:

-L$HOME/install/lib

The following line may also need to be added to the .bashrc file

export LD_LIBRARY_PATH=$HOME/install/lib

(don't forget to source the .bashrc file after including this line)