Channelflow examples/README file.

This directory provides some simple examples of channelflow programs
and a simple Makefile, in order to illustrate how channelflow programs
can be written and compiled. THESE EXAMPLE PROGRAMS ARE NOT INTENDED
FOR PRODUCTION RUNS. You can use them as a starting point for your own
codes. But please refer to the programs in channelflow/programs as
well, since these codes are more configurable and make better use of
channelflow's features. Reading channelflow/doc/TUTORIAL is a good
starting point for the channelflow/programs.

A second warning: YOU MIGHT HAVE TO MODIFY THE MAKEFILE IN ORDER TO
GET IT TO COMPILE CORRECTLY. The example/Makefile is as simple as
possible, in order that it can be modified to suit your needs.
However, this means it generally MUST be modified to work correctly.
See step (1) below.


To compile and run the example programs in this directory

(0) Configure, build, and install channelflow as specified in the
INSTALL file in the top-level directory of the channelflow
distribution.

(1) Edit the Makefile to set the CHANNELDIR variable to the directory
in which channelflow is installed. E.g. if you configured channelflow
with "./configure --prefix=/home/brenda/channelflow-1.3.2 ; make ; make
install", you'll need to change Makefile to read

  CHANNELDIR = /home/brenda/channelflow-1.3.2

In some cases you might need to manually edit the CHANNELINC and
CHANNELIB variables, too. For example, if channelflow was installed
by a system administrator into system-wide directories, you might
need to figure out where the headers files and libraries are, and
manually set CHANNELINC and CHANNELLIB accordingly.

  CHANNELDIR =
  CHANNELINC = -I/usr/include
  CHANNELLIB = -L/usr/lib64


(2) Compile an example programs. E.g.

  make couette.x

If you compiled and installed the channelflow debugging libraries, you can
compile debuggable executables as well, with

  make couette.dx

If you encounter errors at this stage, they are in all likelihood
caused by a misconfigured Makefile sending gcc the wrong compilation
options. Check the values of the -I and -L gcc option that get printed
to the screen. These values show where gcc is looking for header files
and libraries, respectively. Look in those directories. If those
directories don't contain channelflow/*.h and libchflow.so (or
libchflow.a), you need to fix the Makefile. See step (1).

Please consult readily available documentation on the web about
gcc options and Makefiles for help configuring them properly.


(3) Make sure that the channelflow library directory is in your shared
library path. With the bash shell (the default on most Unix systems
including Mac OS X), do this

  echo $LD_LIBRARY_PATH
  /usr/local/lib:/usr/lib64/octave-3.0.0

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/brenda/channelflow-1.3.2/lib

  echo $LD_LIBRARY_PATH
  /usr/local/lib:/usr/lib64/octave-3.0.0:/home/brenda/channelflow-1.3.2/lib


If you're running tcsh or csh (god help you), try

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

in place of "export LD_LIBRARY_PATH ..." above.

It's a good idea to put this command in your shell start-up file, e.g.
~/.bash_profile or ~/.tcshrc.



(4) Run the program

  ./couette.x
or
  ./couette.dx

If you encounter an error like this

   couette.x: error while loading shared libraries: libchflow.so.0:
   cannot open shared object file: No such file or directory

your operating system cannot find the shared library needed to execute
couette.x. You need to set the LD_LIBRARY_PATH variable as described in
step (3).


(5) The couette.x program will integrate a flow and save data
to disk in a data/ directory. What next? The channelflow/doc/TUTORIAL
explains how to use channelflow utilities to analyze and plot this
data.



See also

channelflow/INSTALL for compiling and locating the channelflow libraries

channelflow/docs/TUTORIAL for prerequisites for writing channelflow codes

channelflow/docs/channelflow.tex for detailed discussion of the libraries