Skip to content

Quick Start

This guide takes you through your first LAVA Unstructured simulation in a few minutes: the Taylor–Green vortex, a canonical transition-to-turbulence case in a periodic box. It needs no geometry and consists of the two steps of every unstructured case — generate a mesh with the LAVA Voronoi mesher, then run the solver on it — each driven by a single small input file. The initial condition is built into the solver.

Prerequisites

Before starting, ensure you have:

  • The LAVA solver and utilities installed and your environment properly set up, see the LAVA Installation Guide. You need a 3D unstructured executable (any lavaunst.3D.NS1 build).
  • The LAVA Voronoi mesher installed, see the Voronoi Installation Guide.
  • Python with matplotlib for the plotHist.py utility, and optionally ParaView for the volume and iso-surface files.

The Case

The Taylor–Green vortex starts from a smooth, analytic vortical velocity field in a triply periodic box. The large initial vortices stretch, break down into ever smaller scales, and finally decay — making it the standard test of how much numerical dissipation a scheme adds to an under-resolved turbulent flow. In a box \(\mathbf{x} \in [0,1]^3\) with \(f = 2\pi\), the built-in initial condition is

\[ u_x(\mathbf{x},0) = V_0 \sin(f x)\cos(f y)\cos(f z), \quad u_y(\mathbf{x},0) = -V_0 \cos(f x)\sin(f y)\cos(f z), \quad u_z(\mathbf{x},0) = 0, \]

with the corresponding pressure field

\[ p(\mathbf{x},0) = P_0 + \frac{\rho_0 V_0^2}{16} \bigl[\cos(2 f z) + 2\bigr] \bigl[\cos(2 f x) + \cos(2 f y)\bigr]. \]

We run the classic configuration of Carton de Wiart et al. (2014): Reynolds number 1600, Mach number 0.1, on a uniform mesh of \(64^3\) cubic cells — a deliberately coarse resolution where the quality of the numerical scheme is visible. This is the same setup as the Cartesian Quick Start, so the two solvers can be compared directly on identical grids.

Reference: Carton de Wiart, C., Hillewaert, K., Duponcheel, M., & Winckelmans, G. (2014), "Assessment of a discontinuous Galerkin method for the simulation of vortical flows at high Reynolds number," International Journal for Numerical Methods in Fluids, 74(7), 469–493.

Note

This quick start is about getting a first simulation running, not about producing a reference-quality solution: the \(64^3\) grid deliberately under-resolves the flow. Expect the results to be qualitatively right and quantitatively close — in this run the dissipation peak arrives about one and a half time units early and some 10% low compared with the reference DNS, the expected behavior of a second-order finite-volume scheme on a grid this coarse. Grid and scheme refinement studies are what the rest of the documentation is for.

Tutorial Files

Download the three input files into a working directory:

File Description
tgv_box.yml Voronoi mesher input: a periodic unit box
tgv.inputs solver input file
tg.spec gas/species definition (sets the viscosity, i.e. the Reynolds number)

Meshing

The unstructured solver reads its mesh from a CGNS file. Here the LAVA Voronoi Mesher generates it from the following input:

# LAVA Voronoi mesher input for the unstructured quick start: a triply
# periodic unit box filled with 64^3 cubic cells. No geometry is needed.

# Seed spacing of the finest region (spacing_rel = 1): 64 cells across the box
reference_length: 0.015625

# Fully three-dimensional mesh
2d: false

# Periodic in x, y and z: seeds near a boundary are mirrored across the
# opposite side so the cells connect seamlessly (no boundary zones are written)
periodicDir: [true, true, true]

# The lattice fits the box exactly, so no Lloyd smoothing is needed
lloyd_iter: 0

regions:
  # The first region is always the axis-aligned box that bounds the domain.
  # A cartesian seed lattice gives cubic cells; bodycentered gives the
  # truncated octahedra typically used for meshes around geometry.
  - name: box
    type: cube
    seed: cartesian
    spacing_rel: [1, 1, 1]
    distance: [1.0, 1.0, 1.0]
    center: [0.5, 0.5, 0.5]

The only region is the axis-aligned unit cube that defines the domain; the first region of every mesher input is this bounding box. Seeds are placed on a cartesian lattice with spacing reference_length, which yields \(64^3\) cubic cells. periodicDir makes all three directions periodic: seeds near a boundary are mirrored across the opposite side, so the cells connect seamlessly and the mesh has no boundary zones at all. For meshes around geometry the bodycentered seed lattice (truncated octahedra) is the usual choice — see Refinement regions in the mesher manual.

Run the mesher in the working directory (any lavavoro executable works; adjust the name to your build):

export OMP_NUM_THREADS=8
lavavoro.AVX2 tgv_box.yml

It writes tgv_box.cgns — a single volume zone of 262,144 polyhedral cells — in a few seconds.

The Input File

The complete solver input file:

# LAVA Unstructured quick start: the Taylor-Green vortex.
# A triply periodic box meshed with the Voronoi mesher; the initial condition
# is built into the solver.
exact flow name = taylorgreenvortex

time {
  steady     = false
  finish ctu = 20    # run for 20 convective time units
  cfl        = 0.8
}

reference conditions {
  velocity    = [1.0, 0, 0]
  density     = 6.283185307179586    # 2 pi
  temperature = 71.4285714285714     # gives Mach 0.1
  length      = 0.15915494309189535  # 1 / (2 pi): one classic TGV time unit per ctu
}

fluid {
  species = tg   # calorically perfect gas with constant viscosity 1/1600 (Re = 1600)
}

unst {

  grid {
    file = tgv_box.cgns
  }

  periodic {
    do lava voro periodic = true   # the mesh was built periodic by the Voronoi mesher
    xmin = 0.0
    xmax = 1.0
    ymin = 0.0
    ymax = 1.0
    zmin = 0.0
    zmax = 1.0
  }

  explicit {
    method = ssprk33   # 3rd-order strong-stability-preserving Runge-Kutta
  }

  convective terms {
    scheme                  = keepblend   # kinetic-energy/entropy-preserving flux blended with upwind
    order                   = 2
    limiter                 = none
    flux function           = ausmpw+
    upwind blending sensors = [ducrosmod]
  }

  navier stokes {
    viscous = true
  }

  output {
    monitor {
      interval  = 10
      variables = [nt, time, ctu, dt, maxcfl, maxmach, integratedke, mups]
    }
    flow_stats {
      interval = 10
    }
    volume {   # full-volume CGNS snapshots for visualization
      interval  = 500
      variables = [q, density, mach]
    }
  }
}

Walking through it block by block:

  • exact flow name selects one of the analytic initial conditions built into the solver — no restart or geometry files needed.
  • time requests an unsteady run for 20 convective time units with an adaptive time step at cfl = 0.8.
  • reference conditions set the nondimensionalization: with \(V_0 = 1\), the reference temperature gives Mach 0.1, and the reference length of \(1/(2\pi)\) makes one convective time unit (the ctu monitor column) equal to one classic Taylor–Green time unit.
  • fluid points to tg.spec, a calorically perfect gas with a constant viscosity of \(1/1600\) — which is the Reynolds number definition for this nondimensionalization.
  • Everything else lives inside the unst block:
    • grid names the mesh file — see Grid Setup.
    • periodic tells the solver that the mesh was built periodic by the Voronoi mesher (do lava voro periodic = true) and gives the box extents — see Periodic. No BC_N blocks are needed, since the periodic mesh has no boundary zones.
    • explicit picks the explicit third-order strong-stability-preserving Runge–Kutta scheme — see Explicit Stepping.
    • convective terms select the keepblend scheme, the recommended low-dissipation scheme for scale-resolving simulations: a kinetic-energy and entropy preserving flux blended with an upwind flux where the ducrosmod sensor detects compressibility effects — on this coarse grid a dissipative scheme would visibly damp the vortices. See Convective Terms.
    • navier stokes switches the viscous terms on.
    • output writes a monitor line every 10 steps (with the integrated kinetic energy from flow_stats) and a full-volume snapshot every 500 steps for visualization — see Output and Probes.

Running the Case

From the working directory, run on a few MPI ranks with a few OpenMP threads each (any lavaunst 3D NS1 executable works; adjust the name to your build):

export OMP_NUM_THREADS=8
mpirun -np 8 lavaunst.3D.NS1.AVX2 tgv.inputs

On 64 CPU cores (8 ranks with 8 threads each) the roughly 8000 time steps take about two minutes, at some 18 million cell updates per second (the mups monitor column); reduce finish ctu for a faster first look. While it runs, the monitor table reports the state every 10 steps:

===========================================================================================================
     Time     |     Time     |     CTU      |    Time    |   Max   |   Max   |  Integrated  |   Million   |
     step     |     (s)      | (Non-dim T)  | step size  |   CFL   |  Mach   |   Kinetic    | Updates/Sec |
 (2147483637) | (3.1831e+00) | (2.0000e+01) |    (s)     |         |         |    Energy    |    n=10     |
-----------------------------------------------------------------------------------------------------------
      nt      |     time     |     ctu      |     dt     | maxcfl  | maxmach | integratedke |    mups     |
===========================================================================================================
             0     0.0000e+00         0.0000   4.0320e-04    0.8000    0.0996     7.8540e-01        0.6338 CFL^3 FlowStats^3 inputs^2 load volume 
            10     4.0320e-03         0.0253   4.0320e-04    0.8000    0.0997     7.8532e-01       18.4087 CFL^10 FlowStats 
            20     8.0641e-03         0.0507   4.0321e-04    0.8000    0.0997     7.8525e-01       18.3463 CFL^10 FlowStats 
            30     1.2096e-02         0.0760   4.0321e-04    0.8000    0.0998     7.8517e-01       18.2731 CFL^10 FlowStats 
            40     1.6128e-02         0.1013   4.0321e-04    0.8000    0.0998     7.8510e-01       18.1585 CFL^10 FlowStats 
            50     2.0160e-02         0.1267   4.0321e-04    0.8000    0.0997     7.8502e-01       18.1591 CFL^10 FlowStats 

Running on a GPU

LAVA Unstructured also runs on NVIDIA GPUs. Use a GPU build with one MPI rank per GPU; the input file is unchanged:

mpirun -np 1 lavaunst.3D.NS1 tgv.inputs

In this example the single-GPU run sustained about 60 million cell updates per second (the mups monitor column) — more than three times the throughput of the 64-core CPU run — and finished in under two minutes including the volume output; the gap grows with grid size.

Checking the Run

The monitor history is stored in monitor/Unst.data.iter. Any column can be plotted with the plotHist.py utility, e.g. the kinetic-energy decay and the maximum Mach number over convective time:

plotHist.py -F monitor/Unst.data.iter ctu integratedke maxmach -doSubplot

The figure below shows the integrated kinetic energy of this run and its decay rate \(-\mathrm{d}KE/\mathrm{d}t\), with the Cartesian Quick Start result on the identical \(64^3\) grid for comparison — the classic Taylor–Green result: the energy is nearly conserved while the vortices merely deform, then transition sets in and the dissipation peaks between \(t^* \approx 7\) and \(9\):

Taylor-Green vortex: integrated kinetic energy (left) and kinetic-energy dissipation rate (right) over convective time on the 64^3 unstructured mesh, compared with the Cartesian quick start on the same grid.

The volume snapshots land in volume/ as CGNS files (Unst.vol.*.cgns, each linking to the mesh in Unst.vol.meshLink.<step>.cgns). Open them in ParaView — remember to enable the solution arrays in the CGNS reader's Cell Arrays list. The z-vorticity on the mid-plane (a Slice through the volume) shows the smooth initial vortex array breaking down into small-scale turbulence:

Taylor-Green vortex: z-vorticity on the mid-plane at t* = 0, 9, and 20, showing the breakdown of the initial vortices into small-scale turbulence.

A Q-criterion iso-surface (ParaView's Gradient filter on the velocity, then Contour) shows the vortex structure. Near the dissipation peak, at \(t^* \approx 9\), the smooth initial vortices have rolled up into a dense tangle of worm vortices:

Taylor-Green vortex: Q-criterion iso-surface near the dissipation peak at t* = 9, colored by velocity magnitude.

You now have a running LAVA Unstructured setup. From here: