Differences

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

--- docs:install [2014/02/20 09:57]
gibson [from the subversion server]
+++ docs:install [2016/08/04 10:38] (current)
gibson [Mac OS X]
@@ Line 1: / Line 1: @@
 ====== 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]].
+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 [[:download#numbered_releases| numbered development package]].
+===== 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. Assuming your home directory is ''/home/brenda'', run
+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>
-  cd /home/brenda
+  mkdir ~/channelflow
-  wget http://www.channelflow.org/download/channelflow-1.4.1.tgz
+  cd ~/channelflow
-  tar xvfpz channeflow-1.4.1.tar.gz
+  wget http://www.channelflow.org/download/channelflow-1.5.0.tgz
-  cd channelflow-1.4.1
+  tar xvfpz channeflow-1.5.0.tar.gz
-  ./configure --prefix=/home/brenda/channelflow-1.4.1
+  mkdir build
+  cd build
+  cmake -DCMAKE_INSTALL_PREFIX=~/channelflow ../channelflow-1.5.0
   make
+  make test
   make install
 </code>
@@ Line 23: / Line 45: @@
 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. As of 2011, channelflow SVN source builds with CMake instead of autoconf.
-<code>
-  cd /home/brenda
-  svn co http://svn.channelflow.org/channelflow
-  cd channelflow/trunk
-  cmake -DCMAKE_INSTALL_PREFIX=$(pwd) .
-  make
-  make test
-  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.
@@ Line 48: / Line 51: @@
 To install and use channelflow, you need
-  - a computer
+  - a computer, preferably running some form of Unix
-  - a C++ compiler
+  - a C++ compiler (e.g. g++)
-  - make (the Unix "make" utility)
   - the standard C++ library
   - the standard C math library
-  - FFTW for computing Fourier transforms
+  - the [[http://www.cmake.org/overview/cmake|cmake]] build system
-  - (optional) the Octave linear algebra libraries and headers
+  - the Unix "make" utility
-  - (optional) the HDF5 high-density data file libraries and headers
+  - 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://www.octave.org|Octave]]. Channelflow programs can
+[[http://eigen.tuxfamily.org/|Eigen]] is a C++ pure-template linear algebra library.
-optionally use the Octave linear algebra libraries.
+Most channelflow code does not rely on Eigen. The core fluid simulation algorithms of
-Octave is an interactive numerical linear algebra system, designed as a free
+Channelflow do not require Eigen, however, a few high-level algorithms do (such as
-alternative to Matlab. The Octave libraries offer a very convenient C++ interface to the
+computing equilibria and periodic orbits). If you are just interested in time integration,
-efficient and well-tested Fortran Lapack and BLAS numerical libraries. The core fluid
+you could strip out the the channelflow code that relies on it.
-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,
@@ Line 77: / Line 77: @@
 You will need to install the required tools and libraries if they are not already installed.
-===== Linux =====
-=== installing required packages with native package manager===
-On Linux systems, these prerequisites can be easily installed with the native package manager
+===== MS-Windows =====
-(e.g. ''rpm'', ''Yast,''''synaptic'' or ''adept''). Channelflow is developed and regularly compiled
-on AMD Phenom II and Intel Core 2 Duo machines running OpenSUSE Linux 11.2, 11.3, CentOS 5.2, and RedHat
-Enterprise 4 with packages
-  gcc-3.4, 4.1, 4.3, 4.4
+FIXME //Incomplete instructions//
-  make-3.81
-  glibc, glibc-devel-2.3, 2.5, 2.8, 2.10
-  libstdc++, libstdc++-devel-3.4, 4.3, 4.4
-  fftw, fftw-devel-3.1.2, 3.2
-  octave, octave-devel-3.0, 3.2
-  hdf5, hdf5-devel-1.8
-  libhdf5_hl, libhdf5-0-1.8
-If you plan to write and compile your own channelflow programs, you will probably want to install
-these packages as well (version numbers indicate values on recent opensuse distributions)
-  autoconf-2.63
-  automake-1.11
-  gdb-6.8
-  subversion-1.6
-  libtool-2.2
-=== installing required packages in your home directory===
-If you're working on a departmentally-administered cluster, it will likely have gcc, g++, make, and fftw
-installed but not Octave or HDF5, and you won't be able to install those packages with the package manager
-because you don't have root access. In this case, you can compile and install those packages in your home
-directory and configure channelflow to look for them there. For example, HDF5 can be compiled with
-  cd /home/brenda
-  wget http://www.hdfgroup.org/ftp/HDF5/current/src/hdf5-1.8.5-patch1.tar.gz
-  tar xvfpz hdf5-1.8.5-patch1.tar.gz
-  cd hdf5-1.8.5-patch1
-  ./configure --prefix=$(pwd) --enable-cxx --with-zlib
-  make
-  make install
-At this point make sure the HDF5 lib path appears in your LD_LIBRARY_PATH environment variable. For example,
-you could put something like this in your ~/.bash_profile (and then run ''source ~/.bash_profile'')
-  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib:~/lib:~/channelflow/lib:/usr/lib64/octave-2.1.71:~/hdf5-1.8.5-patch1/lib
-Then use the CFLAGS and LDFLAGS ./configure variables to tell channelflow where to look for the HDF5 installation
-  ./configure CFLAGS='-I/nv/hp1/jg356/hdf5-1.8.5-patch1/include/' LDFLAGS='-L/nv/hp1/jg356/hdf5-1.8.5-patch1/lib/'
-===== 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 =====
+{{:docs:channelflow_mac_osx.pdf|Installing channelflow on Mac OS X}}, by Eric Jelli, Dept. Physics, U. Marburg.
-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 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>
-. 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.

channelflow.org

User Tools

Site Tools

Differences

Page Tools