This is an old revision of the document!
====== Channelflow installation ====== 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|download page]] or via subversion from [[http://svn.channelflow.org/channelflow]]. ===== from a tarball ===== 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 <code> 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 </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. ===== from the subversion server ===== If you want access to the latest code and frequent updates, it's better to install from the subversion server. <code> cd /home/brenda svn co http://svn.channelflow.org/channelflow cd channelflow/trunk autoreconf --install ./configure --prefix=/home/brenda/channelflow/trunk make make install </code> [[http://subversion.tigris.org|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. ====== Prerequisites ====== To install and use channelflow, you need - a computer - a C++ compiler - make (the Unix "make" utility) - the standard C++ library - the standard C math library - FFTW for computing Fourier transforms - (optional) the Octave linear algebra libraries and headers - (optional) the HDF5 high-density data file libraries and headers [[http://www.fftw.org|FFTW]] is an elegant and efficient self-optimizing Fourier transform library. **FFTW is required** for channelflow. [[http://www.octave.org|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. [[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. ===== Linux ===== 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 ===== MS-Windows ===== On MS-Windows, you will probably need to install the [[http://www.cygwin.com|CygWin]] Linux emulation environment. FIXME //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// ===== Mac OS X ===== 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 hdf5 / octave / fftw3 - here via fink * Install [[http://www.finkproject.org/|fink]] - assumed install directory ''/sw/'' * Install software: <code> fink install fftw3 fink install octave (automatically selects hdf5) </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. FIXME // 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// ====== 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.
