User Tools

Site Tools


docs:tutorial

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
docs:tutorial [2009/01/31 17:37]
john_h Changed "Arnolid" to "Arnoldi
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. +
- +
- +
-===== 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+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 
  
-and a list of its command-line options and arguments. Channelflow +<​code>​ 
-utilities are invoked at the command line with syntax like+  couette --help 
 +</​code>​
  
-   ​utility -opt1 value -opt2 value -flag1 arg3 arg2 arg1 
  
-or concretely+====== Example Calculations ====== 
 +===== Making a movie =====
  
-   ​couette -T0 0 -T1 -vdt -dt 0.02 -ts sbdf4 u0.ff+===1Generate an initial condition and examine its properties ===
  
- +  ​gibson@akbar$ randomfield -Nx 48 -Ny 33 -Nz 48 -lx -lz -m 0.20 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 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 227: Line 138:
 Adjust the bitrate to balance filesize and video quality. Adjust the bitrate to balance filesize and video quality.
  
-==== Computing a 1d unstable manifold ====+===== Computing a 1d unstable manifold ​=====
        
 The Nagata (1990) "​lower-branch"​ equilibrium has a one-dimensional unstable manifold. The Nagata (1990) "​lower-branch"​ equilibrium has a one-dimensional unstable manifold.
Line 246: Line 157:
   * ''​projectseries''​   * ''​projectseries''​
  
-=== Download the Nagata lower-branch solution ===+=== 1. Download the Nagata lower-branch solution ===
  
 ...from the [[http://​www.channelflow.org/​database|channelflow database]]. ''​LB''​ stands for '​lower-branch'​. ​ ...from the [[http://​www.channelflow.org/​database|channelflow database]]. ''​LB''​ stands for '​lower-branch'​. ​
Line 252: Line 163:
    wget http://​channelflow.org/​database/​a1.14_g2.5_Re400/​LB.ff    wget http://​channelflow.org/​database/​a1.14_g2.5_Re400/​LB.ff
  
-=== Examine the solution'​s properties ===+=== 2. Examine the solution'​s properties ===
  
 The ''​fieldprops''​ utility will print out basic information about the field. For example, The ''​fieldprops''​ utility will print out basic information about the field. For example,
Line 262: Line 173:
 if you leave it off.  if you leave it off. 
  
-=== Plot the solution ===+=== 3. Plot the solution ===
  
 Visualization of fluid velocity fields is an art in itself. Channelflow provides a Visualization of fluid velocity fields is an art in itself. Channelflow provides a
Line 283: Line 194:
  
  
-=== Compute the eigenfunctions ===+=== 4. Compute the eigenfunctions ===
  
 The Nagata lower-branch solution is an equilibrium of plane Couette dynamics. You can  The Nagata lower-branch solution is an equilibrium of plane Couette dynamics. You can 
Line 295: Line 206:
  
  
-=== Perturb along the unstable manifold ===+=== 5. Perturb along the unstable manifold ===
  
 The Nagata lower branch has a single unstable eigenvalue, so its unstable manifold is 1d The Nagata lower branch has a single unstable eigenvalue, so its unstable manifold is 1d
Line 306: Line 217:
  
  
-=== Integrate the perturbations ===+=== 6. Integrate the perturbations ===
  
   couette -T0 0 -T1 400 -o data-LBp01 LBp01ef1   couette -T0 0 -T1 400 -o data-LBp01 LBp01ef1
-  couette -T1 0 -T1 400 -o data-LBm01 LBm01ef1+  couette -T0 0 -T1 400 -o data-LBm01 LBm01ef1
  
  
-=== Produce input vs dissipation curves === +=== 7. Produce input vs dissipation curves === 
  
 The ''​seriesprops''​ utility computes a few quantities like energy dissipation D and The ''​seriesprops''​ utility computes a few quantities like energy dissipation D and
Line 323: Line 234:
  
  
-=== Make movies ===+=== 8. Make movies ===
  
    ​movieframes -T0 0 -T1 100 -d data-LBp01ef1 -o frames-LBp01ef1    ​movieframes -T0 0 -T1 100 -d data-LBp01ef1 -o frames-LBp01ef1
Line 330: Line 241:
 From here you can adapt the [[#​make_a_movie_from_extracted_data|movie-making instructions]] from above. From here you can adapt the [[#​make_a_movie_from_extracted_data|movie-making instructions]] from above.
  
-==== Project movie data onto state-space coordinates ====+===== 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 340: 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.1233452237.txt.gz · Last modified: 2009/01/31 17:37 by john_h