Differences

This shows you the differences between two versions of the page.

--- docs:install [2015/06/09 12:47]
gibson [Channelflow installation]
+++ docs:install [2016/08/04 10:38] (current)
gibson [Mac OS X]
@@ Line 3: / Line 3: @@
 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 numbered development package [[:download#numbered_releases| numbered development package]]. Downloading source code via subversion is preferable because it greatly simplifies merging your local changes with updates to the standard distribution.
+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 [[:download#numbered_releases| numbered development package]].
 ===== from the subversion server =====
@@ Line 15: / Line 15: @@
   mkdir build
   cd build
-  cmake -DCMAKE_INSTALL_PREFIX=~/channelflow ../channelflow/trunk
+  cmake -DCMAKE_INSTALL_PREFIX=~/channelflow ~/channelflow/trunk
   make
   make test
@@ Line 87: / Line 87: @@
 ===== Mac OS X =====
+{{:docs:channelflow_mac_osx.pdf|Installing channelflow on Mac OS X}}, by Eric Jelli, Dept. Physics, U. Marburg.
-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.
-. 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;
-. 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>
-. 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

Differences

Page Tools