Matlab/Octave package Channel3DLab: Short

manual
Karri Keskinen
Department of Energy Technology, Aalto University
karri.keskinen@aalto.fi
December 14, 2015

Contents
1 Introduction 2
1.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Package components 8
2.1 Components intended for user editing . . . . . . . . . . . . . . . . . . . 8
2.2 Other components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 Saved fields and variables . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4 Notes on Matlab/Octave interchangeability . . . . . . . . . . . . . . . . 14

3 Run Examples 15
3.1 Laminar flow - coarse grid . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Turbulence initialization - coarse grid . . . . . . . . . . . . . . . . . . . 16
3.3 Turbulence development - fine grid . . . . . . . . . . . . . . . . . . . . 16

1
1 Introduction
The DNSLab package, containing both the NS2DLab two-dimensional pseudospectral
code and the Channel3DLab three-dimensional finite difference code, is provided as a
pedagogic gateway kit to eddy-resolving turbulent flow simulation. The software is
compatible with both the commercial Matlab software, and the open-source Octave
software.

This document is intended to aid the user of the Channel3DLab package by explaining
the properties of different scripts and functions contained within the archive. A quick
example of running the code is given in subsection 1.1. The most relevant points for
code permutation are provided in section 2. Later, in subsection 3, guidelines are
provided for running the channel flow solver from start to finish, i.e. from a laminar
flow initialization to a fully developed turbulent flow.

While the present methodology is applicable to a wide range of computational studies,

the package is primarily intended for computation of either laminar or turbulent channel
flow. An explanation of the channel geometry is given in Figure 1.

Figure 1: Schematic of a turbulent channel flow, with colors representing streamwise

velocity magnitude. The flow is driven by the body force g x . No-slip conditions are im-
posed on the top and bottom walls, while boundaries in the length and width directions
are periodic.

The computational code operates using a finite difference formulation. This means
that variables are stored in point locations (nodes), and derivatives of the variables
are computed according to values in the node itself and its neighbors. However, the
node spacing here complies with the cell-centered approach presented by Hirsch [1].
Hence, the present formulation, applied to Cartesian grids, has similarities with the

2
finite volume method, which is more commonly used for CFD.

A central feature in the present methodology is the ability to express differentiation

operations explicitly and briefly within the code via vectorization. For example, this can
be applied to the operation where the streamwise component of velocity is differentiated
with respect to the streamwise direction:
u
Dx un (1)
x
If the 3D geometry consists of N N N nodes, Dx is a N 3 N 3 -sized sparse matrix,
and un is a column vector with size N 3 1. Importantly, boundary conditions for the
operated variables are encoded within the differentiation matrix. With velocity compo-
nents, this boundary condition is no-slip (Dirichlet) condition, whereas with pressure,
the zero-gradient (Neumann) condition is employed. In principle, it is possible for the
user to implement boundary conditions of their liking simply by modifying the appro-
priate differentiation matrices, as no explicit conditions are given anywhere in the code.
For future reference, Table 1 clarifies the item type for each colored font in the text.

Table 1: Item legend.

Type Color within text
Script (.m) Green
Function (.m) Orange
Case parameter Blue
Vector, matrix or multidimensional array Black

1.1 Getting Started

1. Start Matlab/Octave

2. Go to folder DNSLab/Channel3DLab

3. Start the simulation by executing the command ThreeDChannelFlow_Run or by

opening the ThreeDChannelFlow_Run.m script and selecting the Run option from
the graphical user interface. If prompted, add the folder to the programme path

4. The program will present the utilized computational setup, as well as several op-
tions that can be subsequently modified (Figure 2). After the necessary operators
have been loaded, the simulation will start. Progress is indicated on the command
window

5. With the default setup, the first result visualizations (Figures 3-6*) will appear
after 10 steps, and will be updated every 5 steps. The visualizations can be moved
and resized freely, and are formed within the ThreeDChannel_Visualize.m script.

3
 The relevant source data can be observed in the Workspace window, and is saved
to a date-coded .mat file in the root directory

*NB: With Octave, only Figures 3 and 4 are available due to availability of 3D visualization components

Figure 2: Output in the command window upon running the code.

4
Figure 3: Mean velocity profile (top left), componentwise fluctuation profiles (top right),
Reynolds shear stress profile (bottom left), evolution of solution kinetic energy and mean
friction Reynolds number (bottom right).

5
Figure 4: Streamwise velocity field cutouts in an XY-plane (top), an XZ-plane within
the boundary layer (center), and two ZY-planes (bottom).

6
 Figure 5: Three-dimensional cutout representation of streamwise velocity.

Figure 6: Isosurface of the Q-criterion (Q = 10), a vorticity indicator. Isosurfaces have

been colored according to local velocity magnitude.

7
2 Package components
2.1 Components intended for user editing
The main script of the package is ThreeDChannelFlow_Run. Use this to run the simu-
lation. All of the relevant parameters to the computational setup and visualization can
be accessed via the ThreeDChannel_Casesetup script. The variable runmode refers to
the state of the case which is being simulated.

Table 2: Flow solver modes of operation

Variable Value Explanation
runmode 0 Laminar flow initialized at a specified bulk Reynolds number
ReD .
1 Flow initialized from runmode=0 result or continued from ex-
isting runmode=1 result, with added randomized disturbance
for all velocity components. With appropriate conditions,
disturbances can develop into coherent turbulent flow struc-
tures
2 Flow initialized from runmode=1 result or continued from ex-
isting runmode=2 result. Possible to utilize velocity field in-
terpolation onto new grid (interpolatenew). Use this option
for refined turbulent flow computation and statistics genera-
tion.

The retain option determines whether currently computed result variables are saved,
and resume determines whether the simulation run is restarted from the saved result.
Similarly, the retainoperators option saves generated differential operators and pre-
conditioners, carried out in ThreeDChannel_DifferentialOperators and
ThreeDChannel_Preconditioners, respectively. The former is a time-consuming op-
eration with large grids.

With the resumeoperators option, the user is able to import previous differential
operators for a rapid start to the simulation. With runmode=2, preconditioners are also
loaded. While preconditioner generation is typically a minor operation, Octave versions
older than 4.0.0 do not intrinsically support the contemporary implementation of the
incomplete LU matrix decomposition.

The interpolatenew option determines whether the pre-existing velocity fields are fed
to the interpolation function ThreeDChannel_newgridvelocity, yielding an interpo-
lated velocity field on the new grid.

TIM lets the user select a temporal discretization method. Four schemes have been
preset in the form of Butcher tableaus: the explicit Euler scheme (not suitable for

8
turbulence simulation), as well as 2nd, 3rd and 4th order Runge-Kutta methods (all
of which can be used for turbulence simulation). If the user wishes to implement their
own scheme in the code, it can be done easily via the butchertableau script. Note
that the code only supports explicit schemes.

Variables related to the runtime are displayed in Table 3.

Table 3: Explanation of timing parameters

Variable Explanation
nsteps Number of time steps to be simulated
tstepopt Time step option. 0 = fixed time step, 1 = dynamic time
step (adjusted after each completed time step)
setdt Magnitude of fixed time step (requires tstepopt=0)
CoTarget Target Courant number, which is defined locally as Co =
udt
dx
+ vdt
dy
+ wdt
dz
. Only relevant with dynamic time stepping.
interval Time step interval for result visualization and statistical sam-
pling.
timing Select whether run is timed or not. If the run is timed, the
total duration of solver loops will be provided after the run
has finished. For a fair description of the solver speed, one
should set the interval parameter to be larger than nsteps,
since visualization slows down the computation.
statinit Select the time step when result statistics collection is started
(relative to the beginning of the present simulation). Increase
this integer if you want to start statistics generation at a later
stage.

Select the linear equation solver by setting either sbicg or spcg to 1. This refers to
the biconjugate gradient method and the conjugate gradient method, respectively. By
default, sbicg should be used, since it is compatible with an asymmetric coefficient
matrix. This is generated for the Poisson equation if the grid is non-equispaced in one
of the three coordinate directions (usually, this is the wall-normal coordinate).

Next, we have settings related to the solution of the linear equation system. Here, the
primary point of interest should be the tolerance (bicgtol,pcgtol), which determines
how accurately the system is required to be solved. The effect of the tolerance on result
quality may vary case-by-case. However, the tolerance has a significant effect on the
speed of the solver.

Geometric definitions for the channel geometry are provided in Table 4.

9
 Table 4: Geometry parameters for computational domain.
Variable Explanation
res Node number per Cartesian direction (in default width and
length scale setup).
Wscale,Lscale Geometry width and length scale (default = 0.5). Changing
this parameter will change the geometry, and also change the
number of nodes placed in the specified direction.
ctanh This variable determines how strongly the computational
mesh is condensed towards the wall for resolution of the
boundary layer. For a uniform mesh in the wall-normal di-
rection, set this to a very small number, e.g. 1E-10. The
default value (5E-2) yields a y + value of ca. 0.6 for the first
computational node in the case of the Re = 180 turbulent
channel flow.

Parameters for visualization are provided in Table 5, while parameters for movie gen-
eration** are given in Table 6.

**NB: Only applicable in Matlab

Table 5: Parameters for visualization.

Variable Explanation
ploxx Select whether the relevant plotting is on (1) or off (0).
yplane Select the horizontal plane for velocity cutout description.
Note that the given value only specifies the index of the plane,
rather than the dimensional or dimensionless distance.
USC This parameter sets the colorbar scale for velocities across
the board.
Qset Select the value of Q to be visualized.
plo11 Turns on (=1) visualization of plots, containing the mean
streamwise velocity U + , RMS of diagonal Reynolds stress
0 0 0
components (u+ , v + , w+ ), and one off-diagonal Reynolds
0 0
stress u+ v + . Furthermore, evolution of total kinetic energy
and the actual shear Reynolds number are given.
plo12 Turns on (=1) visualization of streamwise velocities in carte-
sian cut planes. This is useful for observing when turbulent
structures begin to form.
plo13 Turns on (=1) a cakepiece representation of streamwise ve-
locity in two separate cut planes.
plo14 Turns on (=1) a three-dimensional representation of Q iso-
surfaces, colored by velocity magnitude. This is useful for
visualization of three-dimensional vortical structures.

10
 Table 6: Parameters for movie generation.
Variable Explanation
recmovie Select whether movie recording is on (1) or off (0).
nframes Select how many frames are included in the movie. A frame
is captured at each visualization interval.
fr Select the desired framerate (frames per second)

The generated movies will, by default, be named e.g. mov11_date.avi. Thus, if you
intend to generate several movies on the same day, be sure to rename movies that have
already been saved.

11
2.2 Other components
Editing of the following scripts and functions is not required for use of the package.
Hence, the essential content of each component is presented in Tables 7 and 8 briefly.

Table 7: Brief presentation of package components (pre-solver).

Component name and Explanation
ThreeDChannel_CreateFields
Depending on the selections in the case setup, either creates or loads
the geometry and velocity fields. Note that within the code, the z-
direction is normal to the wall.
ThreeDChannel_DifferentialOperators
Either creates or loads differential operators (large, sparse matrices).
These include first derivatives with either Dirichlet and Neumann wall
condition, second derivative with Dirichlet condition, and the Poisson
operator. All spatial derivatives are computed with the central dif-
ferencing scheme, while accounting for non-uniformity in the grid.
While it is not a simple task (or necessary for turbulence simulation),
interested users may want to implement their own spatial differencing
schemes. In that case, please familiarize yourselves with the genera-
tion algorithms for the matrices.
ThreeDChannel_Preconditioners
Generates preconditioning matrices for the solution of linear equa-
tions. For bicg, this is the incomplete LU-decomposition, while for
pcg, the diagonally compensated incomplete Cholesky decomposition
is used.
ThreeDChannel_Projection_init
Performs velocity projection on the initial velocity field, which may
or may not be divergence-free. Table 8 contains further information.

12
 Table 8: Brief presentation of package components (solver).
Component name and Explanation
ThreeDChannel_AdjustTimeStep
If the dynamic time step is selected, this routine will change the time
step according to the computed maximum Courant number.
ThreeDChannel_Solver
The main solver script. Here, 3D velocity arrays U,V,W are first re-
shaped into vectors, which are then operated on by the differentia-
tion matrices. The solver structure is built for explicit Runge-Kutta
schemes and the
 fractional step method. Evaluation of the convection
ui ui uj 2 ui
term C n = 12 uj x j
+ xj
, diffusion term D n
= x2j
, and body
force term gi commences, followed by pressure correction.
ThreeDChannel_Projection
This pressure correction script, located within
ThreeDChannel_Solver, performs velocity projection by solving
the discrete form of the Poisson equation p = C n . Upon
solution, intermediate velocities ui are corrected by the pressure
p
gradient, i.e., ui = ui x i
.
ThreeDChannel_RunPostProcessing
Contains scripts for post-processing, which are run at a frequency
according to the interval parameter.
ThreeDChannel_Analyze_Fluctuations_Compact
Computes field means and RMS-values of Reynolds stresses (velocity
fluctuations).
ThreeDChannel_ComputeQCriterion
Computes the field Q = 21 (Sij Sij ij ij ). A large Q signifies
vorticity dominance, whereas a low Q signifies strain dominance.
ThreeDChannel_Visualize
Plots different data to figures according to the case setup variables.

13
2.3 Saved fields and variables

Table 9: Fields and operators contained within the archive

File and explanation
Fields0,Fields1,Fields2
Velocity fields from runmode =0,1,2.
Operators0,Operators1,Operators2
Discrete differential operators (large, sparse matrices) compatible
within runmode =0,1,2. Note that when an entirely new geometry is
built (different dimensions, resolution or condensing rate), you should
use the option retain =0. New differential operators, compatible for
the present geometry, will be built. Depending on the size of the case,
this operation could take tens of minutes. Thus, it is important to
consider the geometry beforehand e.g. by running only the scripts
ThreeDChannel_Casesetup and ThreeDChannel_CreateFields, and
checking the wall-normal spacing z. The operators contained within
the archive are only compatible with respective settings in the Run
Example section.

2.4 Notes on Matlab/Octave interchangeability

While the package was developed with the Matlab software, most of its properties
remain intact when processed in Octave instead. However, this depends on the version:

Octave 4.0.0: The package can be utilized without modification, but three-dimensional
visualization features available in the Matlab version will be disabled.

Octave 3.8.1: Functionality is retained but is best with preloaded preconditioners

(supplied with the package). If preloaded preconditioners are not utilized (on
a new grid), moderation is recommened in grid node count. This is due to the
contemporary incomplete LU decomposition function ilu not being intrinsic

14
3 Run Examples
This section contains a short guideline for those who want advance from laminar to
turbulent channel flow without using any predefined turbulent flow field as an initial
condition. This process can be divided into the following parts:

Generating a developing laminar channel flow on a coarse grid (runmode=0)

Superimposing a disturbance on the laminar flow, and developing flow turbulence

(runmode=1)

Importing the coarse grid turbulent flow onto a finer grid, and achieving a devel-
oped state(runmode=2)

It should be noted that the presented steps are, by no means, the only method of
generating a turbulent channel flow. However, when using this package, the steps
presented are simple to follow and have proven to be reasonably robust.

3.1 Laminar flow - coarse grid

This portion is computed in order to generate a small boundary layer near the channel
wall. Try the following setup:

Main Runtime Geometry and

Computations
runmode=0 nsteps=50 TIM=2
retain=1 tstepopt=1 res=36
resume=0 CoTarget=0.9 ctanh=5E-2
resumeoperators=0 interval=10
interpolatenew=0

15
3.2 Turbulence initialization - coarse grid

Main Runtime Geometry and Visualization

Computations
runmode=1 nsteps=1E3 TIM=2 plo11=1
retain=1 tstepopt=1 res=36 plo12=1
resume=0 CoTarget=0.9 ctanh=5E-2 plo13=0
resumeoperators=0 interval=20 plo14=0
interpolatenew=0

3.3 Turbulence development - fine grid

Main Runtime Geometry and Visualization

Computations
runmode=2 nsteps=1E3 TIM=4 plo11=1
retain=1 tstepopt=1 res=72 plo12=1
resume=0 CoTarget=0.5 ctanh=5E-2 plo13=1
resumeoperators=1 interval=10 plo14=1
interpolatenew=1

Note that if you wish to generate high-quality statistics, you will want to run the
runmode=2 case for ca. 1000 steps, and restart a new case from that state. Guidelines
for the resume and resumeoperators options:
if you wish to load the velocity field or operators for a certain runmode, ensure
that the case setup parameter res complies with the fields loaded.
The default fields and operators (provided with the archive) assume that res =
36 when runmode = 0 or 1, and that res = 72 when runmode = 2.
If you wish to run a simulation with a different res or ctanh parameter than in
the existing fields and operators, be sure to set resume and resumeoperators to
0.

References
[1] Hirsch C, Numerical Computation of Internal and External Flows, Butterworth-
Heinemann, Massachusetts, 2nd edition, 2007.

16