On Linux/Unix systems that have the required tools and libraries installed, you can install channelflow invoking the standard GNU configure-make commands on the channelflow source code. You can download the source code as a tarball from the download page or via subversion from http://svn.channelflow.org/channelflow.

Installing from a tarball is good if you're content with stable releases and infrequent updates of channelflow. Assuming your home directory is /home/brenda, run

  cd /home/brenda
  wget http://www.channelflow.org/download/channelflow-1.4.1.tgz
  tar xvfpz channeflow-1.4.1.tar.gz
  cd channelflow-1.4.1
  ./configure --prefix=/home/brenda/channelflow-1.4.1
  make 
  make install

Of course if you're installing a different version of channelflow, change the version numbers to suit. If that doesn't work, read on. The most common problem with channelflow installation is that the compiler can't find required header files or libraries (such as FFTW3), because they're either not installed or installed in unusual locations. Fixes for these issues are discussed in the prerequisites and the configuration_options sections.

If you want access to the latest code and frequent updates, it's better to install from the subversion server.

  cd /home/brenda
  svn co http://svn.channelflow.org/channelflow
  cd channelflow/trunk
  autoreconf --install
  ./configure --prefix=/home/brenda/channelflow/trunk
  make 
  make install

Subversion is a source-code control system that makes it very easy to download, modify, and merge changes. For example, you can download any recent changes to the channelflow sources by running svn up in your channelflow directory.

If you have trouble with the ./configure, make, or make install steps, read on.

To install and use channelflow, you need

1. a computer
2. a C++ compiler
3. make (the Unix “make” utility)
4. the standard C++ library
5. the standard C math library
6. FFTW for computing Fourier transforms
7. (optional) the Octave linear algebra libraries and headers
8. (optional) the HDF5 high-density data file libraries and headers

FFTW is an elegant and efficient self-optimizing Fourier transform library. FFTW is required for channelflow.

Octave. Channelflow programs can optionally use the Octave linear algebra libraries. Octave is an interactive numerical linear algebra system, designed as a free alternative to Matlab. The Octave libraries offer a very convenient C++ interface to the efficient and well-tested Fortran Lapack and BLAS numerical libraries. The core fluid simulation algorithms of Channelflow do not require Octave, however, a few high-level algorithms do (such as computing equilibria and periodic orbits). For examples of how to use Octave with Channelflow, see the programs-octave subdirectory.

HDF5 provides flexible, efficient, cross-platform, and standardized data files that can be read by matlab, tecplot, etc. HDF5 is not required, but it is highly recommended. If you do not install HDF5, you can use a channelflow-specific binary files and transfer data to other tools with ASCII files.

You will need to install the required tools and libraries if they are not already installed.

On Linux systems, these prerequisites can be easily installed with the native package manager (e.g. Yast on SUSE systems, synaptic or adept on Ubuntu). Channelflow development is currently conducted on AMD Athlon X2 and Intel Core 2 Duo machines running OpenSUSE Linux 11.0, 11.1, and Kubuntu 8.10 with these packages

gcc-4.1, 4.3,
make-3.81
glibc-2.5, 2.8
glibc-devel-2.5, 2.8
libstdc++-4.3
libstdc++-devel-4.3
fftw-3.1.2
fftw-devel-3.1.2
octave-3.0.0-22
octave-devel-3.0.0-22
hdf5-1.6.7
hdf5-devel-1.6.7
libhdf5_hl0-1.6.7
libhdf5-0-1.6.7

If you plan to write and compile your own channelflow programs, you will probably want to install these packages as well

autoconf-2.61
automake-1.10.1
gdb-6.8
subversion-1.5
libtool-1.5

On MS-Windows, you will probably need to install the CygWin Linux emulation environment.

add links to basic installation instructions for cygwin and specific instructions for packages required by channelflow. John Hyatt and John Gibson installed on Hyatt's Windows machine a few days ago. John H. if you help anyone else with Windows installation in the coming days, could you take notes and insert them here? Thanks

Installation on Macintosh computers is best done by first installing fink and then installing channelflow. Fink is, roughly, a Debian Linux emulation environment for the Mac.

1. Uncomment the typedef unsigned int uint; line in channelflow/mathdefs.h

//typedef unsigned int uint;

so that it looks like this

typedef unsigned int uint;

2. Install hdf5 / octave / fftw3 - here via fink

• Install fink - assumed install directory /sw/
• Install software:

       fink install fftw3
       fink install octave
       (automatically selects hdf5)

3. Compile channelflow - requires location of libs / headers. Set these environment variables

  export CFLAGS=-I/sw/include 
  export LDFLAGS=-L/sw/lib 
  export CXXFLAGS=$CFLAGS 
  export CPPFLAGS=$CXXFLAGS 
  export ACLOCAL_FLAGS="-I /sw/share/aclocal"
  export PKG_CONFIG_PATH="/sw/lib/pkgconfig"
  export PATH=/sw/var/lib/fink/path-prefix-10.6:$PATH
  export MACOSX_DEPLOYMENT_TARGET=10.

This is only a general outline of what you need to do to install on a Mac. Detailed instructions will follow as soon as my Mac-using friends finish their installations 2010-02-10

Ok, assuming you've installed the prerequisite packages, if you're moderately lucky you can compile, verify, install, and start using channelflow with a few commands. Most likely you will want to install channelflow into your home directory. Suppose your home directory is /home/brenda, and that you're installing channelflow-1.3.2. Then, run the following commands

cd ~
tar xfpvz channeflow-1.3.2.tar.gz
cd channelflow-1.3.2
./configure --prefix=/home/brenda/channelflow-1.3.2
make
make test       # optional
make install

When this finishes, the channelflow executables, header files, and libraries will be installed in bin, include, and lib subdirectories of /home/brenda/channelflow-1.3.2.¹⁾ From here on I'll use the Unix shorthand ~ for your home directory.

Now there is one last step. The channelflow executables are linked to the channelflow shared library in ~/channelflow-1.3.2/lib, so you must put the ~/channelflow-1.3.2/lib directory in your LD_LIBRARY_PATH. How you do this depends on what Unix shell you are using. If you use “bash” (the default on most Linux distributions, Mac OS X, and Cygwin), run

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/channelflow-1.3.2/lib

If you're using “tcsh”, run

setenv ${LD_LIBRARY_PATH}:/home/brenda/channelflow-1.3.2/lib

If you don't know which shell you're using, run “echo $SHELL”.

Now you should be able to run the channelflow utility programs in ~/channelflow-1.3.2/bin. See the Tutorial for more on that. You'll probably want to put ~/channelflow-1.3.2/bin in your path, if it's not already there. Please refer to your shell documentation on that (basically you want to add ~/channelflow-1.3.2/bin to your PATH variable, just like you added ~/channelflow-1.3.2/lib to your LD_LIBRARY_PATH).

Note: The executables in the programs-octave/ subdirectory use Octave (a C++ interface to LAPACK) and will only be compiled if you have the Octave development package installed.

If you run into any problems, please see the following sections.

Here are few important options to the ./configure script that let you customize the build procedure.

The --prefix option lets you specify where channelflow will be installed on your system. I usually prefer to install channelflow into the build directory by running

./configure --prefix=/home/brenda/channelflow-1.3.2

In bash you can specify the build directory more simply with --prefix=$(pwd).

You can also install into the default installation directory /usr/local by dropping the --prefix option, e.g. run ./configure. If you do this you'll need to run make install as root.

The CFLAGS option allows you to send options to the compiler. A good example of use is telling the compiler to optimize for your particular chipset. For example

./configure CFLAGS='-march=athlon64'

will add a -march=athlon64 flag to any invocation of the C or C++ compiler. athlon64 is a good choice for any 64 bit AMD Athlon or Intel Core 2 Duo processor. Please refer to GCC documentation for other good choices.

Another important use of CFLAGS is specifying the location of required header files, if they're in unusual places. For example, suppose the FFTW3 header files are in /opt/fftw3/include rather than the standard /usr/include. Then

./configure CFLAGS='-I/opt/fftw3/include'

will tell the compiler to look in that directory when compiling source files.

If your FFTW3 header files are in an unusual place, the libraries probably are, too. You can specify unusual locations for libraries with the LDFLAGS option. For example if your FFTW3 header files are in an unusual place, the libraries probably are, too, and you'll probably want to ./configure like this

 
./configure CFLAGS='-I/opt/fftw3/include' LDFLAGS='-L/opt/fftw3/lib'

The combination of CFLAGS and LDFLAGS can solve a whole lot of configuration problems.

The tests/ directory contains a number of test programs that verify that channelflow behaves correctly. The tests fall into two groups: simple tests of channelflow classes and their member functions, and tests of full-fledged Navier-Stokes simulations.

To run the tests, run

make test

The output will look like

tridagTest:        pass
helmholtzTest:     pass
tausolverTest:     pass
poissonTest:       pass
pressureTest:      pass
dnsZeroTest     --cnfe1   --bulk                   pass
dnsZeroTest     --cnfe1   --bulk                   pass
dnsZeroTest     --cnfe1   --gradp                  pass
dnsZeroTest     --cnab2   --bulkv                  pass
dnsZeroTest     --cnab2   --gradp                  pass
dnsZeroTest     --cnrk2   --bulkv                  pass
etc.

If a test runs to completion but fails, you'll see “FAIL” instead of “pass”. If a test seg faults or produces a run-time error, you'll get neither. In general, the tests produce a numerical approximation g to a known function f, and the passes if L2Norm(f-g)/L2Norm(f) < max_error, were max_error is set to a predetermined value for the given test-problem parameters.

The test programs produce log files (e.g. tridiagTest.log) that detail the particular tests being run and their error norms.

All the tests that run by “make -s check” should pass. If any fail, there's an error somewhere that needs to be tracked down and eliminated. All channelflow distribution tarballs with version numbers have passed the test suite on my development system (currently OpenSUSE-10.2 Linux with gcc-4.0.2 on a Pentium 4 M).

To check that the executables installed correctly, try running “couette.x -h” or “couette –help”. For example,

gibson@tansen$ ~/bin/couette --help
couette :
      integrate plane Couette or channel flow from a given initial condition
      and save velocity fields to disk.
options :
  -T0       --T0                <real>      default == 0           start time
  -T1       --T1                <real>      default == 100         end time
  -dt       --dt                <real>      default == 0.03125     timestep
  -vdt      --variabledt                                           adjust dt to keep CFL in bounds
  etc.

Each channelflow executable program in ~/bin will print out a short description of the program's purpose and command line options, if you run it with a -h or –help option. For an overview of the most important programs and how to use them, see the tutorial.

Installing channelflow consists of

1. getting the source files from a tarball or subversion
2. configuring channelflow for your computer system
3. compiling the channelflow libraries
4. copying the channelflow headers and libraries to an appropriate place in your file system

For the most part you can follow the generic GNU installation instructions listed in the INSTALL file, which boil down to

tar xfpvz channeflow-1.3.0.tar.gz  # maybe change release number
cd channelflow-1.3.0
./configure
make
make install

The default installation directory is /usr/local. If you would like to install channelflow some place else, use the –prefix option to configure as discussed above.

Channelflow follows standard GNU packaging structure as much as possible. The main subdirectories are

channelflow/     the channelflow library source code
programs/        executable programs
programs-octave/ executable programs that require octave libs
examples/        how to write and compile your own channelflow program
matlab/          Matlab scripts for plotting channelflow data
tests/           a suite of test programs for the library code
data/            a few data files useful for the test programs
doc/             tutorial, timing results
doc/userguide/   in-depth LaTeX documentation
obsolete/        code that doesn't compile now but might be brought back

The channelflow/examples directory has several examples of simple channelflow programs and a rudimentary Makefile. See examples/README for more instructions.

To compile debugging and profiling libraries, run these commands

make clean
./configure --enable-debug
make
cp channelflow/libchflow.a /usr/local/libchflow-debug.a
make clean
./configure --enable-profile
cp channelflow/libchflow.a /usr/local/libchflow-profile.a

If you set ”–prefix=/some/other/directory” when in step 1., you should copy the libraries into /some/other/directory/lib” rather than /usr/local/lib.

Warning: It's easy to let the debugging and profiling libraries get out of sync with the headers and the optimized library, since you have to remember to perform these steps whenever you modify the sources. I would like to automate these steps to reduce the potential for error. Ideally, optimized, debugging, and profiling libraries would be compiled and installed with a single ”./configure; make; make install”. Help from any autoconf/automake experts would be appreciated.

The Channelflow debugging libraries have quite a few run-time checks for things like out-of-bounds errors on indices and discretization compatibility between binary operations on fields. You can catch such errors by running your channelflow programs with debugging turned on; the debugging libraries will will produce a relatively informative run-time error message, which can then be checked in-depth with a debugger.

If you skip this check and run your channelflow programs with optimized libraries, the error will produce a seg fault, or worse, keep running without complaint! Thus it is always a good idea to test your channelflow programs with the debugging libs before running them for real.

To compile a debugging executable, run “make <program>.dx”. E.g.

akbar$ cd examples
akbar$ make ./errorexamples.dx
g++ -Wall -g -O1  -I/usr/local/include  -o errorexamples.do -c errorexamples.cpp
g++ -g -o errorexamples.dx errorexamples.do  -L/usr/local/lib -lchflowdebug -lfftw3 -lm
rm errorexamples.do

akbar$ ./errorexamples.dx
(deliberately causing an index-out-of-bounds error...)
errorexamples.dx: /usr/local/include/channelflow/flowfield.h:347:
  int FlowField::flatten(int, int, int, int) const:
  Assertion `ny>=0 && ny<Ny_' failed.
Aborted

Compare this to the same code linked against optimized libraries:

akbar$ make ./errorexamples.x
g++ -Wall -O2 -DNDEBUG -I/usr/local/include  -c errorexamples.cpp
g++ -o errorexamples.x errorexamples.o  -L/usr/local/lib -lchflow -lfftw3 -lm
rm errorexamples.o

akbar$ ./errorexamples.x
(deliberately causing an index-out-of-bounds error...)
(deliberately causing a field-state error...)
(deliberately causing a field incompatibility error...)
Segmentation fault

The optimized error examples program runs straight through two serious programming errors without warning, before hitting one that's bad enough to cause a segmentation fault and stop execution! A channelflow program that contains such errors might well produce numerical garbage with no warning whatsoever. The lesson is: Test your codes for a few time steps with debugging turned on before running them for production use.

When you encounter a run-time error in a debugging executable, it's almost always necessary to rerun the program within a debugger to examine the stack and the values of variables. You can try “gdb errorexamples.dx”, or better, use a GUI debugger. I run “M-x gdb errorexamples.dx” within xemacs.

To compile a debugging executable, run “make <program>.px”. E.g.

akbar$ cd examples
akbar$ make couette.px
g++ -Wall -pg -O2 -DNDEBUG -I/home/gibson/channelflow/include  -o couette.po -c couette.cpp
g++ -pg -o couette.px couette.po  -L/home/gibson/channelflow/lib -lchflow-profile -lfftw3 -lm
rm couette.po

To produce a profiling analysis, run the profiled program, and run gprof on the raw profile-data output file gmon.out:

akbar$ ./couette.px
akbar$ gprof couette.px gmon.out > couette.profile

Then look at the file couette.profile. It will contain the profiling results and some brief documentation on its meaning. See gprof documentation for more details.