====== couette ======

''couette'' integrates plane Couette or channel flow from a given initial condition and save velocity fields to disk at a regular interval. (It should probably be called ''integrate''; I might change it to that in the next release.)
====== main options ======

<code>
  -T0       --T0                <real>      default == 0           start time
  -T1       --T1                <real>      default == 100         end time
  -dt       --dt                <real>      default == 0.03125     timestep
  -dT       --dT                <real>      default == 1           save interval
  -ts       --timestepping      <string>    default == sbdf3       timestepping algorithm
  -nl       --nonlinearity      <string>    default == rot         method of calculating nonlinearity,
  -o        --outdir            <string>    default == data/       output directory
  -R        --Reynolds          <real>      default == 400         Reynolds number
  -c        --channel                                              channelflow instead of plane Couette
  -b        --bulkvelocity                                         hold bulk velocity fixed, not pressure gradient
  -P        --dPdx              <real>      default == 0           value for fixed pressure gradient
  -U        --Ubulk             <real>      default == 0           value for fixed bulk velocity
  -symms    --symmetries        <string>    default == ""          filename for generators of flow-invariant symmetry subspace
  <flowfield>      (trailing arg 1)                                initial condition
</code>

[[docs:utils:couette:alloptions|Complete option list]]

===== time intervals =====

The integration starts at ''t=T0'' and saves data at times ''t = T0 + n dT'', exactly. The ''dt'' 
value is //approximate//. Channelflow actually rounds ''dt'' to the closest integral divisor of ''dT''
so that the save interval is exactly what you asked for. Data is saved to disk in files named ''u0.ff, u1.ff, u2.ff, ...'' if ''t'' takes on integer values or filenames with four-digit precision if ''t'' otherwise, e.g. ''u0.000.ff, u0.125.ff, u0.250.ff, ...''. The integration stops when ''t = T0 + n dT > T1.''

===== timestepping =====

The ''-ts'' or ''--timestepping'' sets the finite-difference time stepping algorithm. It takes the following 
values

^value^  %%O(dt^n)%%  ^algorithm^
|''cnfe1''|  1  |Crank-Nicolson Forward Euler|
|''cnab2''|  2  |Crank-Nicolson Adams-Bashforth|
|''smrk2''|  2  |Spalart-Moser Runge-Kutta|
|''sbdf1''|  1  |Semi-implict Backwards Differentiation|
|''sbdf2''|  2  |Semi-implict Backwards Differentiation|
|''sbdf3''|  3  |Semi-implict Backwards Differentiation|
|''sbdf4''|  4  | Semi-implict Backwards Differentiation|
===== nonlinearity =====

The ''-nl'' or ''--nonlinearity'' specifies the method for calculating the
nonlinearity u⋅∇u in the Navier-Stokes equation.

^  value  ^      ^method^
|''rot''|  (∇×u)×u  |rotational|
|''conv''|  u⋅∇u  |convection|
|''div''|  ∇⋅(uu)  |divergence|
|''skew''|  (u⋅∇u + ∇⋅(uu))/2  |skew-symmetric|
|''alt''| |alternating between ''conv'' and ''div''|

===== mean constraints =====
===== symmetries =====

The ''-symms filename.asc'' option will cause the numerically integrated solution to be periodically projected onto a flow-invariant symmetric subspace specified by the named file. The file should list the generators of the subspace's symmetry group. For example, suppose you want to restrict integration to the symmetry group ''S = {s1,s2,s3}''

<latex>
 $ \begin{align*}
  s_1 \, [u, v, w](x,y,z) &= [u, v, -w](x+L_x/2, y, -z) \\
  s_2 \, [u, v, w](x,y,z) &= [-u, -v, w](-x+L_x/2,-y,z+L_z/2) \\
  s_3 \, [u, v, w](x,y,z) &= [-u,-v,-w](-x, -y, -z+L_z/2) \\
\end{align*}
$ 
</latex>

s1 and s2 are generators of S. So construct a file s1s2.asc with these contents

  % 2
  1  1  1 -1  0.5  0.0
  1 -1 -1  1  0.5  0.5

The first line specifies the number of generators, and the following lines specify the generators, according to

  c sx sy sz ax az

where 

  (c sx sy sz ax az) [u, v, w](x, y, z) → c [sx u, sy v, sz w](sx x + ax Lx, sy y, sz z + az Lz)
 
This functionality is provided because numerical errors and instability of invariant symmetric subspaces will cause numerical solutions to drift out of the invariant subspaces. The integration routines do the project at intervals ''dT''.  


====== Usage examples ======