channelflow.org

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Channelflow installation ======

If you are content to use channelflow's predefined command-line utilities (for time-integration, computation of equilibria and periodic orbits, etc.), you can [[:download#numbered_releases| download precompiled binary packages]] and install them using your Linux distribution's package manager.

If you want to write your own channelflow programs or tinker with the channelflow source code, you should download channelflow source [[:download|via subversion]] (preferable) or as a tarball (e.g. [[http://channelflow.org/dokuwiki/lib/exe/fetch.php?media=downloads:channelflow-devel-1.5.0.tar.gz]]. 

===== from the subversion server =====

Installing from the subversion source gives you access to the latest code and simplifies the process of
merging your modifications to the source code with modifications to the official distribution.

<code>
  cd ~
  svn co http://svn.channelflow.org/channelflow
  cd channelflow
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=~/channelflow ../channelflow/trunk
  make
  make test
  make install
</code>


===== from a tarball =====

Installing from a tarball is good if you're content with stable releases and infrequent updates of
channelflow. The following will download, compile, and install channelflow-1.5.0, using an out-of-source build directory ''~/channelflow/build'', and installing executables, libraries, and header files into ''~/channelflow/bin'', ''~/channelflow/lib'', ''~/channelflow/include''.

<code>
  mkdir ~/channelflow
  cd ~/channelflow
  wget http://www.channelflow.org/download/channelflow-1.5.0.tgz
  tar xvfpz channeflow-1.5.0.tar.gz
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=~/channelflow ../channelflow-1.5.0
  make 
  make test
  make install
</code>

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.

  

====== Prerequisites ======

To install and use channelflow, you need
  - a computer, preferably running some form of Unix
  - a C++ compiler (e.g. g++) 
  - the standard C++ library
  - the standard C math library
  - the [[http://www.cmake.org/overview/cmake|cmake]] build system
  - the Unix "make" utility
  - the [[http://www.fftw.org|FFTW]] Fourier transform package (development version)
  - the [[http://eigen.tuxfamily.org/|Eigen]] linear algebra package 
  - the [[http://www.hdfgroup.org/HDF5|HDF5]] high-density datafile package(development version)

[[http://www.fftw.org|FFTW]] is an elegant and efficient self-optimizing Fourier 
transform library. **FFTW is required** for channelflow. 

[[http://eigen.tuxfamily.org/|Eigen]] is a C++ pure-template linear algebra library.
Most channelflow code does not rely on Eigen. The core fluid simulation algorithms of 
Channelflow do not require Eigen, however, a few high-level algorithms do (such as 
computing equilibria and periodic orbits). If you are just interested in time integration,
you could strip out the the channelflow code that relies on it. 

[[http://www.hdfgroup.org/HDF5|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. 


===== MS-Windows =====

FIXME //Incomplete instructions//

On MS-Windows, you will probably need to install the [[http://www.cygwin.com|CygWin]]
Linux emulation environment. 

===== Mac OS X =====

FIXME // This is only a rough sketch of what you need to do to install on a Mac. //


Installation on Macintosh computers is best done by first installing [[http://www.finkproject.org|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 fftw3, hdf5, and eigen - here via fink
   * Install [[http://www.finkproject.org/|fink]] - assumed install directory ''/sw/''
   * Install software:
<code>
       fink install fftw3
       fink install hdf5
       fink install eigen
</code>


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.







====== Basic installation ======

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.((The GNU autoconf documentation 
recommends that you don't install into the build directory like this, 
but it keeps everything in one place, and I've never had a problem 
with it. You can also install directly into your home directory
using %%--prefix=/home/brenda%% if you prefer.)) 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|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.

====== Configuration options ======

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

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
<code>
./configure --prefix=/home/brenda/channelflow-1.3.2
</code> 
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.

===== CFLAGS =====

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.
===== LDFLAGS =====

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
<code> 
./configure CFLAGS='-I/opt/fftw3/include' LDFLAGS='-L/opt/fftw3/lib'
</code>

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

====== Verifying installation ======

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).


====== Basic usage ======


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 [[docs:tutorial]].

====== Installation and compilation in detail ======

Installing channelflow consists of
  - getting the source files from a tarball or subversion
  - configuring channelflow for your computer system
  - compiling the channelflow libraries
  - copying the channelflow headers and libraries to an appropriate place in your file system
===== Installing from a tarball =====

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 [[#important_variations_on_basic_installation|discussed above]].


===== Directory structure =====


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



====== Compiling your own channelflow programs ======

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


====== Debugging and profiling channelflow programs ======

=====  Compiling debugging and profiling libraries =====


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.


=====  Debugging channelflow programs =====

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.


===== Profiling channelflow programs =====

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.
channelflow.org

User Tools

Site Tools

Page Tools
