channelflow.org

User Tools

Site Tools

Trace:
docs:tutorial

Differences

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

Link to this comparison view

Next revision 		Previous revision
docs:tutorial [2008/12/22 08:35]
gibson created 		docs:tutorial [2010/02/02 07:55] (current)
Line 1: Line 1:
 ====== Channelflow Tutorial ====== ====== Channelflow Tutorial ======
- 
-===== Intro ===== 
  
 So you've installed channelflow. Now what? Well, computational fluid So you've installed channelflow. Now what? Well, computational fluid
Line 19: Line 17:
 of my own research. Probably the best way to get started with 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 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 +calculations using these utilities. ​
-examples, skip to Section 3.+
  
 +Please refer to [[:​docs#​utilities|Utilities]] and [[docs:​utils:​options|Utility Options]]
 +for a detailed guide of individual utilities and their options. You can also run any 
 +utility with a ''​-h''​ or ''​--help''​ option to get a brief description of the
 +utility'​s purpose and options, e.g 
  
-===== Overview of channelflow utility programs =====+<​code>​ 
 +  couette --help 
 +</​code>​
  
-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 ^ +====== Example Calculations ====== 
-| randomfield ​  | build a random initial velocity field, save to disk | +===== Making ​a movie =====
-| 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 +===1. Generate an initial condition and examine its properties ===
-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 +  gibson@akbar$ randomfield -Nx 48 -Ny 33 -Nz 48 -lx 2 -lz 1 -m 0.20 u0.ff
-  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 ===== +
- +
- +
-==== How to make a movie of a flow ==== +
- +
- +
-=== 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 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+random spectral coefficients on a 48 x 33 x 48 grid, on [0, 2pi] x
 [-1, 1] x [0, pi], with magnitude 1/V \integral_V |u|^2 dx = 0.2. The [-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 field is a perturbation from the laminar flow --by default, velocity
Line 146: Line 54:
  
  
-=== Integrate a flow in time, saving the results to disk ===+=== 2. Integrate a flow in time, saving the results to disk ===
  
   gibson@akbar$ couette -T0 0 -T1 200 -l2 -o data u0.ff   gibson@akbar$ couette -T0 0 -T1 200 -l2 -o data u0.ff
Line 163: Line 71:
  
  
-=== Extract data from the sequence of stored velocity fields for plotting ===+=== 3. Extract data from the sequence of stored velocity fields for plotting ===
  
   gibson@akbar$ movieframes -T0 0 -T1 200 -d data -o frames   gibson@akbar$ movieframes -T0 0 -T1 200 -d data -o frames
Line 169: Line 77:
 The movieframes program reads in the series of files data/u0.ff, 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 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 that are good for visualizing the flow. These 2D slices are stored in
 the frames/ directory with filenames like u0_yz_slice.asc. the frames/ directory with filenames like u0_yz_slice.asc.
  
- +=== 4. Make a movie from the extracted data ===
-=== Make a movie from the extracted data ===+
  
 To make a movie using channelflow'​s existing visualization tools, you To make a movie using channelflow'​s existing visualization tools, you
Line 197: Line 103:
 script and its arguments; briefly, here the arguments are script and its arguments; briefly, here the arguments are
  
-  0    starting frame number +  0    starting frame number ​     int 
-  1    frame interval +  1    frame interval ​            int 
-  200  ending frame number +  200  ending frame number ​       int 
-  0    starting time (t=0.0) +  0    starting time              float 
-  1    time interval ​(dT=1.0) +  1    time interval ​             float 
-  10   ​frames per second +  10   ​frames per second ​         ​int ​ 
-  '​couette.avi'​ output filename+  '​couette.avi'​ output filename ​  string
  
-I have a number of scripts that will convert these AVI animations to +further optional arguments ​are
-other video formats and compress them along the way. These conversion +
-scripts ​are not yet part of the channelflow distribution package, but +
-I will try to work them in in the near future. Sorry for the delay, +
-but these things take time.+
  
-==== Project movie data onto state-space coordinates ====+  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''​ 
 + 
 +=== 1. 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 
 + 
 +=== 2. 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.  
 + 
 +=== 3. 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. 
 + 
 + 
 +=== 4. 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''​.  
 + 
 + 
 +=== 5. 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 
 + 
 + 
 +=== 6. Integrate the perturbations === 
 + 
 +  couette -T0 0 -T1 400 -o data-LBp01 LBp01ef1 
 +  couette -T0 0 -T1 400 -o data-LBm01 LBm01ef1 
 + 
 + 
 +=== 7. 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 
 + 
 + 
 +=== 8. 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 It can be useful to look at the temporal evolution of a fluid as
Line 221: Line 251:
 equilibria under the symmetries of plane Couette flow. In simple equilibria under the symmetries of plane Couette flow. In simple
 language, we take linear combinations of equilibria and their language, we take linear combinations of equilibria and their
-translations in x,z to form orthonormal basis sets.+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 ===+=== 1. 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 basis-UBtrans
  
 Download an equilibrium solution of plane Couette flow from the Download an equilibrium solution of plane Couette flow from the
 channelflow website, one that is compatible in geometry and channelflow website, one that is compatible in geometry and
-discretization.+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 .. 
 + 
 + 
 + 
 +=== 2. Project a series of fields onto the basis === 
 + 
 +Ok. Suppose you have a series of velocity fields u0.ff, u1.ff, etc for t=0,​1,​2,​...1000  
 +in a data/ directory and a set of basis elements e0.ff, e1.ff, e2.ff, e3.ff in a  
 +basis-UBtrans/​ directory. To project the fields onto the basis, run  
 + 
 +  projectseries -T0 0 -T1 1000 -d data -b basis-UBtrans -Nb 4 -o a.asc 
 + 
 +That will produce an ASCII file a.asc with 4 columns and 1001 rows. The t-th row and jth  
 +column is the value of (u(t), ej), where ( , ) signifies the L2 inner product 
 + 
 +<​latex>​ 
 +  (f,g) = 1/V \int_V f \cdot g dx dy dz 
 +</​latex>​ 
  
-(to be continued...)+  ​
  
-                                                                     +                                                        ​
docs/tutorial.1229963705.txt.gz · Last modified: 2008/12/22 08:35 by gibson

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
CC Attribution-Share Alike 3.0 Unported Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki