Differences

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

--- docs:tutorial [2009/02/10 16:57]
wikiadmin
+++ docs:tutorial [2010/02/02 07:55]
@@ Line 1: / Line 1: @@
-====== Channelflow Tutorial ======
-===== Intro =====
-So you've installed channelflow. Now what? Well, computational fluid
-dynamics is a pretty big field, and there's no telling what kinds of
-ideas you might want to explore. For this reason Channelflow was
-developed primarily as a *programming language*. If you're using
-Channelflow for research towards a Ph.D. thesis, you will probably
-eventually end up writing your own channelflow programs, for example,
-modifying existing programs to integrate flows and analyze data. Or
-you might need to modify the time-integration routines to incorporate
-additional physics (polymer additives, bubbles, etc.)
-However, channelflow also includes a number of predefined utility
-programs that a basic set of important computations, such as
-time-integration of plane Couette and channel flows and measuring
-properties of velocity fields. These utilities suffice for the bulk
-of my own research. Probably the best way to get started with
-channelflow is to step through a few examples of run-of-the-mill
-calculations using these utilities. If you want to get right to these
-examples, skip to Section 3.
-===== Overview of channelflow utility programs =====
-Here's a list of current channelflow utilities. The first three
-are taken out of alphabetical order because they're featured in
-Section 3, Example Calculations.
-^ program name ^ purpose ^
-| randomfield   | build a random initial velocity field, save to disk |
-| couette       | integrate an initial condition, save results to disk |
-| fieldprops    | print out norms, symmetries, geometrical data of a stored field |
-| makemovie     | extract slices of fields in order to make a movie |
-| addfields     | compute sum a_n u_n and store result to disk |
-| arnoldi       | compute the eigenvalues and eigenfunctions of eqbs and orbits |
-| ascii2field   | convert a file of ASCII data to a channelflow FlowField |
-| changegrid    | change the discretization or box size of a field |
-| field2ascii   | convert a channelflow FlowField to a file of ASCII data |
-| fieldplots    | extract a number of 2D slices of the 3D field, good for plots |
-| findorbit     | compute an equilibrium or periodic orbit of plane Couette |
-| L2Dist        | compute the L2 distance between two fields |
-| L2IP          | compute the L2 inner product |
-| makebasis     | construct an orthonormal basis from a set of fields |
-| makeheatmode  | construct a field that decays in time according to Laplace eqn |
-| makestokesmode | construct a stokes eigenfunction of laminar equilibrium |
-| perturbfield  | add random perturbations to a given field |
-| projectfields | project a set of fields onto a given basis |
-| projectseries | project a sequence of fields onto a given basis |
-| seriesprops   | compute statistics on a sequence of data |
-| symmetrize    | find the phase shift of a field that optimizes symmetries |
-The utilities are stand-alone command-line programs that are run from
-the Unix shell. You can get brief built-in help information on each
-utility by running it with a -h or --help option. For example, running
-"couette --help" produces
-  gibson@akbar$ couette --help
-  couette :
-        integrate an initial condition and save velocity fields to disk.
-  options :
-    -T0       --T0           <real>   default == 0       start time
-    -T1       --T1           <real>   default == 100     end time
-    -vdt      --variabledt                               adjust dt for CFL
-    -dt       --dt           <real>   default == 0.03125 timestep
-    -dtmin    --dtmin        <real>   default == 0.001   minimum time step
-    -dtmax    --dtmax        <real>   default == 0.05    maximum time step
-    -dT       --dT           <real>   default == 1       save interval
-    -CFLmin   --CFLmin       <real>   default == 0.4     minimum CFL number
-    -CFLmax   --CFLmax       <real>   default == 0.6     maximum CFL number
-    -ts       --timestepping <string> default == sbdf3   timestepping algorithm
-    ...
-     -p        --pressure                                print pressure grad
-    <flowfield>      (trailing arg 1)                    initial condition
-The built-in help gives a brief description of each utility's purpose
-and a list of its command-line options and arguments. Channelflow
-utilities are invoked at the command line with syntax like
-   utility -opt1 value -opt2 value -flag1 arg3 arg2 arg1
-or concretely
-   couette -T0 0 -T1 -vdt -dt 0.02 -ts sbdf4 u0.ff
-"Options" (e.g. -opt1 value) are used to reset default values
-of parameters. For options, the first two columns in the built-in
-help give the short and long form of the option (e.g. -ts and
---timestepping), the third column indicates the type of parameter
-expected (e.g. real, int, bool, string), and the fourth gives the
-the default value. For example, "couette -dt 0.02 -ts cnab2" sets
-the time stepping method to 2nd order Crank-Nicolson Adams-Bashforth
-with dt=0.02.
-"Flags" simply turn on boolean options that would otherwise be set
-to false. For example, calling "couette -vdt" turns on variable-dt
-timestepping, which adjusts dt at fixed intervals to keep the CFL
-number within bounds. For flags the third and fourth columns of
-built-in help are left blank.
-"Arguments" always come after all options and flags. Arguments usually
-specify the filenames of binary velocity fields that the utility will
-load and operate on. Most channelflow programs have one required
-argument (e.g. "couette u0.ff") some two (e.g. "L2Dist u0.ff u2.ff").
-Others take a variable number of arguments (e.g. makebasis u0 u1 u2").
-Unfortunately it's difficult to document variable-number arguments
-properly in the four-column option system, so variable-number arguments
-are usually documented with a "usage: line right after the description
-of the utility's purpose.
-So, as you read work through the Example Calculations, you can run the
-suggested command with a --help option to clarify what the options are
-doing and what other options are possible.
-===== Example Calculations =====
-==== Making a movie ====
-=== 1. Generate an initial condition and examine its properties ===
-  gibson@akbar$ randomfield -Nx 48 -Ny 35 -Nz 48 -lx 0.875 -lz 0.6 -m 0.20 u0.ff
-This command generates a no-slip, divergence-free velocity field with
-random spectral coefficients on a 48 x 35 x 48 grid, on [0, 2pi] x
-[-1, 1] x [0, pi], with magnitude 1/V \integral_V |u|^2 dx = 0.2. The
-field is a perturbation from the laminar flow --by default, velocity
-fields in channelflow are differences from laminar. The spectral
-coefficients are random within an exponentially decaying envelope,
-roughly similar to turbulent fields. The velocity field is saved to
-disk in binary format in file u0.ff (the .ff stands for "FlowField",
-the name of the C++ class for velocity, pressure and tensor fields in
-channelflow). The channelflow binary format stores the spectral
-coefficients, the geometry, and all discretization information so the
-field can be reconstructed entirely from the data in the file. You can
-list this information and some dynamical properties of the field by
-running
-  gibson@akbar$ fieldprops u0.ff
-=== 2. Integrate a flow in time, saving the results to disk ===
-  gibson@akbar$ couette -T0 0 -T1 200 -l2 -o data u0.ff
-This command load the velocity field u0.ff from disk and integrates it
-in time (using the default integration algorithm and parameters) from
-t=T0=0 to t=T1=200, and saves the time varying velocity field to disk
-at the interval dT=1.0 (the default save interval) in a directory
-named data/. The -l2 option prints out the L2 norm of u as well as the
-Chebyshev-weighted norm.
-After this command finishes, look in the data/ directory, and you will
-see u0.ff u1.ff u2.ff etc. The integer label is the time (remember the
-save interval is dT=1.0). If you choose a noninteger save interval,
-the filenames will be something like u0.000.ff u0.975.ff etc.
-=== 3. Extract data from the sequence of stored velocity fields for plotting ===
-  gibson@akbar$ movieframes -T0 0 -T1 200 -d data -o frames
-The movieframes program reads in the series of files data/u0.ff,
-data/u1.ff, etc. and extracts a number of 2D slices of the 3D fields
-that are good for visualizing the flow. These 2D slices are stored in
-the frames/ directory with filenames like u0_yz_slice.asc.
-=== 4. Make a movie from the extracted data ===
-To make a movie using channelflow's existing visualization tools, you
-need Matlab. (If you would like to write similar tools for another
-visualization package, please do so and send them to me!). Start up
-Matlab. Get all the scripts in channelflow/matlab into your Matlab
-path. Do this either by copying the scripts into the current
-directory, by copying them to wherever you store your Matlab scripts,
-or by putting channelflow/matlab in your Matlab path. You can do that
-by typing 'addpath /home/larry/channelflow-1.3.2/matlab' at the Matlab
-prompt (changing the directory as appropriate).
-Then, within Matlab change to the directory that where you ran the
-couette programs, the one with data/ and frames/ subdirectories.
-Within Matlab run
-   makemovie(0,1,200,0,1,10, 'couette.avi');
-This will construct a movie of the 3D velocity field as it evolves in
-time and store the result in file couette.avi, in AVI format. Running
-'help makemovie' will give you a help string about the makemovie
-script and its arguments; briefly, here the arguments are
-    starting frame number      int
-    frame interval             int
-  ending frame number        int
-    starting time              float
-    time interval              float
-   frames per second          int
-  'couette.avi' output filename   string
-further optional arguments are
-  title     printed this in the upper-left corner    string
-  credit    printed this in the lower-right corner   string
-  xstride   plot every xstride-th gridpoint          int
-  ystride   plot every ystride-th gridpoint          int
-  zstride   plot every zstride-th gridpoint          int
-  perspect  do a perspective plot                    0 or 1 (false or true)
-  framedir  directory containing frame data          string (default='frames')
-Note: The Matlab scripts provided with channelflow are kludgy. I cobbled them together
-in order to get the plots I want. Some things, like the position of the title and credit
-strings, must be positioned manually by editing values in the script files. Improvements
-in the scripts and alternatives for systems other than matlab are welcome.
-=== 5. Convert the AVI file ===
-Matlab produces only uncompressed AVI files on Linux. You will probably want to
-compress the AVI file and convert it to another format. On Linux you can do this with
-''mencoder'', which is part of the MPlayer package. For example, this command will
-convert ''couette.avi'' file to a flash video file ''couette.flv''.
-   gibson@akbar$ mencoder couette.avi -nosound -of lavf -lavopts format=flv -ovc lavc -lavcopts vcodec=flv:vmax_b_frames=0:vbitrate=1600 -o couette.flv
-Adjust the bitrate to balance filesize and video quality.
-==== Computing a 1d unstable manifold ====
-The Nagata (1990) "lower-branch" equilibrium has a one-dimensional unstable manifold.
-Here we compute the unstable manifold by integrating two 1d trajectories
-<latex>
-u_{\pm}(x,t) = f^t(u_{LB} \pm v_{LB}), t \in [0, \infty]
-</latex>
-using several channelflow utilities:
-  * ''fieldprops''
-  * ''arnoldi''
-  * ''addfields''
-  * ''couette''
-  * ''seriesprops''
-  * ''makebasis''
-  * ''projectseries''
-=== Download the Nagata lower-branch solution ===
-...from the [[http://www.channelflow.org/database|channelflow database]]. ''LB'' stands for 'lower-branch'.
-   wget http://channelflow.org/database/a1.14_g2.5_Re400/LB.ff
-=== Examine the solution's properties ===
-The ''fieldprops'' utility will print out basic information about the field. For example,
-   fieldprops -g LB
-prints out the field's geometrical properties: cell size, grid size, etc. Try ''--help''
-to get a list of other options. Channelflow adds a ''.ff'' file extension to ''LB''
-if you leave it off.
-=== Plot the solution ===
-Visualization of fluid velocity fields is an art in itself. Channelflow provides a
-few scripts for plotting the velocity field on certain slices of the rectangular domain.
-I've found these plots useful, but if you have better ideas please adapt the scripts
-accordingly.
-Plotting take two steps. First you extract some 2D slices from the 3D field with a
-channelflow utility, like this
-   fieldplots -o plot LB
-That saves the 2D slices as ASCII data files in a plot/ directory. Then within Matlab,
-go to the plot/ driectory and run
-   plotbox('LB')
-The matlab ''plotbox'' script has a number of default parameters that you can change.
-Try ''help plotbox'' within Matlab for more information.
-=== Compute the eigenfunctions ===
-The Nagata lower-branch solution is an equilibrium of plane Couette dynamics. You can
-compute the eigenvalues and eigenfunctions of the linearized dynamics about the equilbrium
-with the ''arnoldi'' utility. (Will write documentation on Arnoldi iteration later).
-   arnoldi --flow LB.ff
-This produces a set of (approximate) eigenfunctions ''ef1.ff, ef2.ff, ...'' and a
-file of eigenvalues ''lambda.asc''.
-=== Perturb along the unstable manifold ===
-The Nagata lower branch has a single unstable eigenvalue, so its unstable manifold is 1d
-and can be computed as a trajectory initiated with small perturbations in the +/- directions
-of the unstable eigenvector/eigenfunction. The following calculates LB +/- 0.01 ef1 and
-saves the results into files LBp01ef1 and LBm01ef1
-  addfields 1 LB  0.01 ef1  LBp01ef1
-  addfields 1 LB -0.01 ef1  LBm01ef1
-=== Integrate the perturbations ===
-  couette -T0 0 -T1 400 -o data-LBp01 LBp01ef1
-  couette -T1 0 -T1 400 -o data-LBm01 LBm01ef1
-=== Produce input vs dissipation curves ===
-The ''seriesprops'' utility computes a few quantities like energy dissipation D and
-wall shear I for a time series of stored velocity fields
-   seriesprops -T0 0 -T1 400 -d data-LBp01ef1 -o props-LBp01ef1
-   seriesprops -T0 0 -T1 400 -d data-LBm01ef1 -o props-LBm01ef1
-The results will be stored in files in props-LBp01ef1/ and props-LBm01ef1/ directories
-=== Make movies ===
-   movieframes -T0 0 -T1 100 -d data-LBp01ef1 -o frames-LBp01ef1
-   movieframes -T0 0 -T1 100 -d data-LBm01ef1 -o frames-LBm01ef1
-From here you can adapt the [[#make_a_movie_from_extracted_data|movie-making instructions]] from above.
-==== Project movie data onto state-space coordinates ====
-It can be useful to look at the temporal evolution of a fluid as
-a trajectory in state space. The number of degrees of freedom in
-a fluid simulation is very high (e.g. 10^5), so it is necessary
-to project the fields into a low-dimensional basis in order to
-plot the trajectory and look at it. We have found that good
-projection bases can be constructed from the "group orbits" of
-equilibria under the symmetries of plane Couette flow. In simple
-language, we take linear combinations of equilibria and their
-translations in x,z to form orthonormal basis sets. For a more
-detailed description of the logic and mathematics of this approach,
-see [[:references|Gibson et al (2007) JFM 611]]. Here we will just
-outline how the computation is done using channelflow.
-=== Make a low-d basis ===
-Make a subdirectory and descend into it, so that the following steps
-don't pollute the current directory with a bunch of extraneous files
-  mkdir basis-UBtrans
-  cd basisUBtrans
-Download an equilibrium solution of plane Couette flow from the
-channelflow website, one that is compatible in geometry and
-discretization. For example, you can get the Nagata upper-branch
-equilibrium (UB) with the Unix "wget" utility.
-  wget http://www.channelflow.org/database/a1.14_g2.5_Re400/UB.ff
-Compute the half-cell translations of UB in x, in z, and in x,z with
-the channelflow [[:docs:utils:symmetryop]] utility:
-  symmetryop -ax 0.5 UB UBx
-  symmetryop -az 0.5 UB UBz
-  symmetryop -ax 0.5 -az 0.5 UB UBxz
-Briefly, symmetryop constructs a symmetry σ parameterized by the options,
-applies it to the first FlowField argument, and saves the result to the
-second FlowField argument, according to the symmetry parameterization described
-in [[:docs:math:symmetry]]. Let if τ<sub>x</sub> be translation by Lx/2, etc.
-Then the above lines compute τ<sub>x</sub> UB, τ<sub>z</sub>, and
-τ<sub>xz</sub> respectively.
-Now construct the following orthogonal linear combinations of the above fields
-<latex> $ \begin{align*}
-  UB_{pppp} = UB + \tau_x UB + \tau_z UB + \tau_{xz} UB \\
-  UB_{ppmm} = UB + \tau_x UB - \tau_z UB - \tau_{xz} UB \\
-  UB_{pmpm} = UB - \tau_x UB + \tau_z UB - \tau_{xz} UB \\
-  UB_{pmmp} = UB - \tau_x UB - \tau_z UB + \tau_{xz} UB
-\end{align*} $ </latex>
-with the channelflow [[:docs:utils:addfields]] utility:
-  addfields 1 UB  1 UBx  1 UBz  1 UBxz UBpppp
-  addfields 1 UB  1 UBx -1 UBz -1 UBxz UBppmm
-  addfields 1 UB -1 UBx  1 UBz -1 UBxz UBpmpm
-  addfields 1 UB -1 UBx -1 UBz  1 UBxz UBpmmp
-Finally, use the channelflow [[:docs:utils:makebasis]] utility to
-apply Gram-Schmidt orthogonalization on those fields and form an
-orthonormal basis set:
-  makebasis UBpppp UBppmm UBpmpm UBpmmp
-The output of "makebasis" will be four orthonormal basis elements e0.ff, e1.ff,
-e2.ff, and e3.ff saved to disk. In this case the input fields are already orthogonal
-and all "makebasis" does is normalize.
-Now pop out of the basis-UBtrans subdirectory
-  cd ..
-=== Project a series of fields onto the basis ===

channelflow.org

User Tools

Site Tools

Differences

Page Tools