Skip to content

Output and Probes

Flow Stats

Controls interval of sampling flow statistics such as integrated kinetic energy, maximum Mach number and integrated domain volume (see Monitor section for descriptions).

output {
    flow stats {
        # Defaults to monitor interval by default
        interval = 10
    }
}

Loads

In this section, you can define several loads integration groups which can integrate forces and moments over specified components of the geometry.

output {
    loads {
        # Interval at which the loads are computed, this is common for all integration groups
        interval      = 10
        # Following 3 inputs apply to all the groups by default
        # But you can optionally specify them different for any individual group
        # Center around which moments are computed
        moment center = [33.,0.0,4.5]
        # Provide non-dimensional force and moments
        normalize     = true
        # Use gauge pressure (p-p_ref) in pressure forces
        gauge         = true
        # If true, this flag will output each surface component integrations separately
        # (in addition to the groups listed below)
        do individual comps = true
        group_1 {
            # Group name
            name          = airplane
            # Which BC zones to include
            include       = [1-32]
        }
        group_2 {
            name = wing
            include = [7,8,10-13]
            normalize     = false
            # Use gauge pressure (p-p_ref) in pressure forces
            gauge         = false
        }
        group_3 {
            name = tail
            include = [14,16]
            moment center = [48.,0.0,4.5]
        }
        ...
    }
}
The code will always output non-normalized force/moment values. If normalize = true is specified, the code will additionally output normalized force/moment coefficients. The values of the reference conditions section are used for normalization.

The result of the load integrations are output to screen (if requested) and to the monitor file (.iter). Detailed description of the monitor and the loads output variables are provided in the monitor section.

If you only have single loads integration group, you can skip the group_1 subsections:

output {
    loads {
        interval      = 10
        moment center = [33.,0.0,4.5]
        normalize     = true
        gauge         = true
        do individual comps = true
        name          = airplane
        include       = [1-32]
    }       
}

Monitor

Monitor output tracks typically high frequency information such as time step, CFL, residuals, integrated aerodynamics loads and performance metrics among others.

If monitor section is not included in the input file, you will get a default set of variables output to screen every time steps (or every pseudo step for implicit runs). The variable list given here only affects the screen output while every other available variable is always output to the .iter file.

The .iter file can be plotted using the tool plotHist.py

output {
    monitor {
        # Output interval applies both to screen and file (.iter) file outputs.
        interval = 10
        # Variable list only affects the screen output
        variables = [nt,time,ctu,dt,maxcfl,maxmach,cl_airplane,wallt,mups,elapsed]
        # When restarting, the code looks for a copy of the .iter file in the restart directory
        # corresponding to the time step you are restarting from. If the .iter file is missing,
        # by default the code will quit with an error message. The flag below, if activated, will
        # instead start a new .iter file from scratch
        reset if missing = false # default
        # The monitor keeps track of some averaged performance metrics. This entry will set the interval
        # for averaging. By default, it is set to 10xinterval (specified above)
        avg interval = 100
    }
}

Each screen line ends with notes on what happened since the previous line, name^N for N times: the outputs written (volume, iso, surf, point, line, restart), the buffered outputs flushed (write-surf-buff-N, write-iso-buff-N, N files) and, on unst GPU runs, dtoh-q and dtoh-qave when all of the solution or of its time averages was copied from the device to the host, which takes a noticeable share of a step on large grids.

List of available monitor variables:

Variable Description Units
nt Time step
ns Pseudo time step
time Physical simulation time [s]
ctu Convective time unit [non-dimensional time]
dt Time step size [s]
nts Completed sync steps (sync-clock runs only, see the time section)
dtratio dt / sync dt (sync-clock runs only)
substeps RK sub-steps in the last completed sync step (sync-clock runs only)
maxcfl Maximum CFL number in the domain
maxmach Maximum Mach number in the domain
integratedmass Integrated mass of fluid in the domain [kg]
integratedvolume Integrated volume of the domain [m^3]
integratedke Integrated kinetic energy in the domain [J]
nondim_integratedke Non-dimensional integrated kinetic energy
integratedxmomentum Integrated x-momentum [kg*m/s]
integratedymomentum Integrated y-momentum [kg*m/s]
integratedzmomentum Integrated z-momentum [kg*m/s]
integratedetotal Integrated total energy in the domain [ (kg/m^3)(m^2/s^2) ]
nondim_integratedetotal Non-dimensional integrated total energy
minpressure min pressure in the domain [Pa]
maxpressure max pressure in the domain [Pa]
minuvelo min u-velocity in the domain [m/s]
maxuvelo max u-velocity in the domain [m/s]
minvvelo min v-velocity in the domain [m/s]
maxvvelo max v-velocity in the domain [m/s]
minwvelo min w-velocity in the domain [m/s]
maxwvelo max w-velocity in the domain [m/s]
mintemperature min temperature in the domain [K]
maxtemperature max temperature in the domain [K]
mups Average MUPS, averaged through the log interval
mups_min Minimum MUPS through the monitor log interval
mups_max Maximum MUPS through the monitor log interval
mups_long Average MUPS, averaged through the avg interval
mups_long_min Minimum MUPS through the monitor avg interval
mups_long_max Maximum MUPS through the monitor avg interval
wallt Wall time per time step, averaged through the log interval [s]
wallt_min Minimum wall time through the monitor log interval [s]
wallt_max Maximum wall time through the monitor log interval [s]
wallt_long Wall time (s), averaged through the avg interval [s]
wallt_long_min Minimum wall time through the monitor avg interval [s]
wallt_long_max Maximum wall time through the monitor avg interval [s]
elapsed Total elapsed wall time from beginning, including the restart history [hr]
memory CPU host memory usage on root MPI rank [GB]
memory_gpu GPU device memory usage on root MPI rank [GB]

Note

MUPS: Millions of Updates per Second, i.e. millions of cells advanced through a full time step per second

Integratrated loads, as described in the Loads section, are also output via the monitor. Each loads integration group, corresponding to the its specied name will produce the following monitor output variables:

Variable Description
cx_name Total x-force coefficient
cy_name Total y-force coefficient
cz_name Total z-force coefficient
cx_inv_name Inviscid x-force coefficient
cy_inv_name Inviscid y-force coefficient
cz_inv_name Inviscid z-force coefficient
cx_visc_name Viscous x-force coefficient
cy_visc_name Viscous y-force coefficient
cz_visc_name Viscous z-force coefficient
cmx_name Total x-moment coefficient
cmy_name Total y-moment coefficient
cmz_name Total z-moment coefficient
cmx_inv_name Inviscid x-moment coefficient
cmy_inv_name Inviscid y-moment coefficient
cmz_inv_name Inviscid z-moment coefficient
cmx_visc_name Viscous x-moment coefficient
cmy_visc_name Viscous y-moment coefficient
cmz_visc_name Viscous z-moment coefficient
cl_name Total lift coefficient
cd_name Total drag coefficient
cs_name Total side force coefficient
cl_inv_name Inviscid lift coefficient
cd_inv_name Inviscid drag coefficient
cs_inv_name Inviscid side force coefficient
cl_visc_name Viscous lift coefficient
cd_visc_name Viscous drag coefficient
cs_visc_name Viscous side force coefficient

Restart

Restart files, also referred to as checkpoint files, allow you to restart the simulation seamlessly from a given point. You can set the interval of restart file writes as:

output {
    restart {
        # Specify restart file output interval (time step for unsteady, pseudo-step for steady)
        interval = 1000
    }
}
Every restart write first flushes the buffered surface outputs (see Buffered surface outputs).

Stopping a run early. Create a file named STOP in the run directory to end a run before its last step. The solver looks for it every 40 steps and then ends the run after the step in progress (an implicit unsteady run finishes its physical step, a subcycled Cart run its coarse step) as if it were the last one: it writes that step's final outputs, every buffered output and a restart, and exits cleanly. A STOP file present when a run starts is deleted.

When the scheduler ends a run. A batch scheduler ends a job past its wall time with SIGTERM, then SIGKILL after a grace period. On SIGTERM to any rank, every rank writes its buffered outputs at the end of the step in progress and the run exits with an error status, without a restart: a restart cut short by the SIGKILL could leave the latest restart file unreadable. A second SIGTERM ends the run at once. To end with a restart, use a STOP file or set the number of steps so the run ends before the job does.

Buffered surface outputs

Surface outputs (the BC surface output, the surface probes and the iso-surfaces) reach the disk in one of two ways:

  • Gathered: the parts of an output on every rank are collected on one writer rank and written there as one file, in any format the output supports. Gathered outputs are buffered: an output is held in memory by a rotating storage rank and written at the next flush, so a flush writes many files from many ranks at once.
  • Parallel: every rank writes its own part into one shared CGNS file, at every output, never buffered. A vertex that several ranks share is written once by each of them.
Output Unst Cart
BC surface gathered; doparallel = true in the surface section writes it in parallel gathered
Surface probe gathered; doparallel = true writes it in parallel (format = cgns only) gathered
Iso-surface gathered; doparallel = true writes it in parallel (format = cgns only) cgns and xdmf in parallel, vtk and vtp gathered; doparallel overrides

On Unst, a gathered output whose single output, collected on its writer rank, would take more memory than the limit below is written in parallel instead, as CGNS, for the rest of the run, so a large surface never has to fit on one rank. The check is made once per output, at its first output with faces, and the log says which output it moved and its size. A vtk or vtp output then writes .cgns files holding the same surface and values. Fwh and Plot3D surface probes and Cart iso-surfaces have no parallel writer and stay gathered, with a warning.

Input (output section) Unit Default Effect
output buffer interval surf steps automatic Flush the buffered BC surface and surface probe outputs every so many steps; 0 writes each output at once
output buffer interval isos steps automatic The same for the gathered iso-surfaces
output buffer snapshots outputs 100 The automatic intervals let each rank hold at most this many outputs
output buffer flush period wall-clock seconds 0 (off) Also flush once the oldest buffered output has been held this long, which bounds what a killed job loses between restarts
output buffer memory MB per rank, 1 MB = 2^20 bytes automatic Also flush at any output step that leaves a rank holding more than this; a single gathered output larger than this is written in parallel
  • The intervals count time steps; with a sync clock they count sync steps, and every output and flush happens on the sync marks. The automatic interval is the number of steps over which all the buffered outputs, counted together, fill output buffer snapshots outputs per rank, and at least the number of ranks; it is shortened when the hosts are over half full at startup, and set to 1 over 80%. The log reports it.
  • Without output buffer memory, the limit is a quarter of the memory available to each rank: the available memory of its node shared by the ranks on the node, the least over all ranks, measured when the check is made. The log reports it at the first surface output.
  • Every restart write, the end of the run, a STOP file and a SIGTERM flush every buffered output, so a restart never precedes outputs still in memory.
output {
    output buffer flush period = 1800 # flush at least every 30 minutes
    output buffer memory       = 2000 # flush once a rank holds more than 2000 MB
    surface {
        interval   = 100
        doparallel = true             # unst: every rank writes its part of each BC surface file
    }
}

Volume

The Cartesian solver writes volume output using parallel HDF5 output. The volume output is controlled with the following, where interval can be 0 for no output:

volume  {
     interval = 1000
     variables = [q,mach,density,mask,processor]
   }

variables takes the tokens below. The run stops at input on any other token, and on a token that names no field in the run, such as qstats without volume time averaging. A field that several tokens name is written once.

Tokens Fields
q; pressure, velocity, uvelocity, vvelocity, wvelocity, temperature the primitive variables, all of them or some
density (rho), mach (machnumber), soundspeed (sound), ptot (totalpressure) density, Mach number, speed of sound, isentropic total pressure
vorticity; xvorticity, yvorticity, zvorticity the vorticity components, all of them or one
eddyviscosity (mut) subgrid-scale eddy viscosity
errormetric the refinement error metric
ducrossensor, psisensor, lmsensor, strainsensor, wenoshocksensor, neumannshocksensor, laplaciansensor, wigglesensor the shock and upwind-blending sensors
leonardstressmag, smallscaleenergy, chuenergynorm LES diagnostics
laplacianq; laplacianpressure, laplacianuvel, laplacianvvel, laplacianwvel, laplaciantemperature the normalized second difference of each primitive variable that Laplacian refinement tags on
distancefunction, imagedistance, normalintofluid, component, bodyvelocity immersed-boundary geometry data
mask; masksource the cell mask; the source term of each cell (runs with source terms only)
processor (procrank, rank), loadbalance, ibox (box, boxid), threadnum (thread, threadid), xyz partition and debugging data; xyz is x + y + z of the cell center
qstats, qavg, pavg, uavg, vavg, wavg, tavg, qqav, pppp (ppav), upup (uuav), vpvp (vvav), wpwp (wwav), tptp (ttav), upvp (uvav), upwp (uwav), vpwp (vwav), tke, reynoldsstress, ptotavg (totalpressureavg) time averages, with volume time averaging on; the second moments are central (p'p', u'v', ...); they hold no value before the first sample
heatreleaserate heat release rate, chemistry builds

In addition to the full volume output, you can also output a subset of the domain using a box region. Each subset can have its own output interval that differs from the main volume interval.

volume {
     interval = 1000
     variables = [q,mach,density,mask,processor]

     subset_1 {
         type = box
         lo = [0.1, 0, 1.0]    # Minimum coordinates [x_min, y_min, z_min]
         hi = [1.0, 0.5, 0.1]  # Maximum coordinates [x_max, y_max, z_max]
         interval = 500        # Output interval specific to this subset
     }
     subset_2 {
         type = box
         lo = [-1.0, -0.01, -0.01]
         hi = [ 1.0,  0.01,  0.01]
         interval = 100
     }
   }

The variables input is shared across all subsets. Each subset can have its own output interval. Output files follow the naming convention sub01.Cart.XXXXXXXXX.hdf5, sub02.Cart.XXXXXXXXX.hdf5, etc. Thin box subsets can be used to approximate plane extractions; the plane subset type is available only in the unstructured solver.

The 3D block-structured box layout is also written to boxes_* files at the same frequency as interval. These files contain the outlines of all boxes in the domain and are primarily useful for visualizing the volume mesh structure.

Tip

For large simulations, using subsets can significantly reduce storage requirements and post-processing time.

Iso-Surfaces

In-situ extraction of iso-surfaces for post-processing and visualization is supported. Iso-surfaces are defined by specifying a contour value for a chosen field, and the solver will output the corresponding isosurface as a triangulation at a user-defined interval.

isosurfaces_1 {
    isovalue     = 0.5
    contour      = vortmag
    colorfields  = [umag]
    interval     = 100
    format       = vtk
    clipbox_1 {
        lo     = [0.0, 0.0, 0.0]
        hi     = [1.0, 1.0, 1.0]
        invert = false
    }
}
isosurfaces_2 {
    contour      = cutplane
    normal       = [0, 1, 0]         # Normal vector of the plane (e.g., y-normal)
    point        = [0.0, 0.5, 0.0]   # A point on the plane
    colorfields  = [densitygradmag]
    interval     = 100
}
isosurfaces_3 {
    contour     = cutplane
    point       = [9.75, 0, 0]
    normal      = [1, 0, 0]
    format      = vtk
    interval    = 100
    colorfields = [q, mach, density]   # primary field first, then derived fields
}
isosurfaces_4 {
    isovalue        = 300
    contour         = q
    qcompcontouring = 4 # temperature component of the q vector for 3D simulations
    colorfields     = [q]
    qcompcoloring   = 0 # pressure component of the q vector
    interval        = 100
    format          = vtk
}

Parameters

  • isovalue: The value of the chosen field at which to extract the iso-surface (e.g., isovalue = 0.5).
  • contour: The field to contour. Options include:
    • vortmag (vorticity magnitude, default)
    • qcriterion
    • lambda2
    • mach
    • densitygradmag
    • q (a specific component of the q vector. The option qcompcontouring is then required to specify the component index)
    • cutplane (for planar cuts; requires normal and point, as surface probe cut planes and volume plane subsets do. On Unst, the whole cells a plane passes through are written by a volume subset of type = plane)
  • colorfields: Array of fields to attach to the iso-surface, all written into the same output file. On Cart the first entry is the primary color field and any additional entries are derived variables (see the derived-variable list under colorfields (additional entries) below); on Unst the list is flat (see Unst color lists below). This replaces the need for several isosurfaces_N blocks that differ only in their color field, so one block produces one file per output interval instead of many (fewer inodes). The first entry may be:

    • umag (velocity magnitude, default)
    • vortmag
    • qcriterion
    • errormetric (Cart only)
    • densitygradmag
    • mach
    • density
    • nut (Unst only; the turbulence model variable, needs a turbulence model)
    • dx (cell size; on Unst the cube root of the cell volume)
    • processor (the rank that extracted the vertex)
    • inbody (Cart only; immersed-body indicator, 1 inside the geometry and 0 in fluid. On a cut plane the edge interpolation makes it a smooth 0..1 ramp across the body boundary, so you can threshold or mask on it. Most useful with dosolvecellsonly = false, the cut-plane default, so the plane fills through the body.)
    • ducros (Cart only; Ducros shock/upwind sensor dilatation²/(dilatation²+enstrophy) in [0,1], ~1 in compression/shocks, ~0 in smooth vortical flow — the sensor the CentralQ upwind blending uses)
    • strain (Cart only; strain-based upwind sensor 1 − enstrophy/(2·SᵢⱼSᵢⱼ+enstrophy) in [0,1], ~1 in strain/compression-dominated regions, ~0 in rotation-dominated flow)
    • q (all components of the q vector; with qcompcoloring, only the component of that index. fullq is accepted as another name for all components)

    On Cart, additional entries may be any of the same fields except q, and require the first entry to be q without qcompcoloring. Example: colorfields = [q, mach, inbody, ducros]. A single field with no extras is just colorfields = [umag] (or [mach], [inbody], etc.).

    Unst color lists. On Unst colorfields is one flat list of up to 16 entries in any order: q, umag, vortmag, qcriterion, lambda2, densitygradmag, mach, density, nut, dx, processor and qstats. Each entry is written once, in the listed order, and the first entry names the file. q writes all components of the q vector, or with qcompcoloring only the component of that index; a list holding both the full vector (fullq) and a q component drops the component with a warning. The written names are those of Cart (Umag, VortMag, QCriterion, Lambda2, DensityGradMag, Mach, Density, Nut, DX, Processor) and the volume output's state names for q. A vertex on a partition boundary is extracted by every rank holding its edge, so Processor differs between its copies. Example — one cut plane with the mean and instantaneous flow and the gradient fields:

    isosurfaces_1 {
        contour     = cutplane
        point       = [0, 0, 0]
        normal      = [0, 1, 0]
        interval    = 100
        colorfields = [q, vortmag, qcriterion, mach, qstats]
    }
    

    Deprecated: the older colorfield = <field> (single value) plus derivedvars = [...] syntax still works, but is deprecated and will be removed in a future release; use colorfields = [<field>, ...] instead. colorfield = X is equivalent to colorfields = [X], and colorfield = fullq; derivedvars = [a, b] is equivalent to colorfields = [q, a, b]. A deck using either key warns at startup with the exact colorfields line to replace it with. - interval: Output interval in time steps (e.g., interval = 100). - format: Output file format. With doparallel = true every rank writes its piece of the surface into one shared file; with doparallel = false the surface is gathered on one rank and written there, buffered over outputbufferintervalisos outputs (see Buffered surface outputs). A format its write path cannot produce stops at input. - Cart: vtk (default), vtp and cgns gathered; cgns and xdmf default to parallel output, and vtk with doparallel = true writes one ASCII file per rank. - Unst: cgns (default), vtk and vtp, gathered and buffered unless doparallel = true, which writes cgns in parallel. A gathered iso-surface too large for one rank is written in parallel instead. - vtk and vtp files hold single precision values; vtp is VTK XML PolyData with raw binary appended data. - vtp writes VTK XML PolyData (.vtp) files with raw binary appended data. - dosolvecellsonly: (Optional, Cart only) Restrict extraction to solved fluid cells, skipping immersed-body (INBODY) and GCM ghost cells (which carry non-physical reference/image states). Field contours (vortmag, qcriterion, etc.) default to true. Cut planes default to false, so the plane fills through the body and you can see the section of the geometry — pair with the inbody colorfield to visualize or mask the solid. Set dosolvecellsonly = true on a cut plane to restore the old behavior (a clean hole at the body, no in-body data). - nearwallgradients: (Optional, Cart only, expert) Near-wall treatment of the gradient-based contour fields (vortmag, qcriterion, lambda2, densitygradmag) at immersed bodies, when dosolvecellsonly masking is on. By default (ghost) gradient fields extend all the way to the wall using the immersed-boundary image states. nearwallgradients = exclude instead stands them off about one cell from the wall, so the derivative stencils never touch the immersed-boundary band. - cliplo, cliphi: (Optional, deprecated) Lower and upper bounds for spatial clipping of the iso-surface, specified as coordinate arrays. Defaults to the full domain. Equivalent to a single clipbox_1 { lo=...; hi=...; invert=false }; emits a deprecation warning at run time. Cannot be combined with indexed clipbox_N sub-sections. Prefer clipbox_1 in new inputs. - clipbox_N: (Optional) Indexed axis-aligned box clip(s). Up to 4 boxes are supported per iso-surface (clipbox_1, clipbox_2, ...). Each box has lo, hi, and an optional invert flag (default false). When invert=false the box keeps points inside it; when invert=true it keeps points outside it. All configured boxes are AND'd together, and AND'd with all clipfrustum_N regions. On Unst, boxes and frustums are in the coordinates of point and normal (the laboratory frame, or the reference frame with frame = <zone>), and cells of moving zones are tested at their current position. Example — keep points inside a large box but excluded from a small interior box:

    clipbox_1 { lo = [0.5, 0.0, 0.3];  hi = [1.0, 0.5, 0.7];  invert = false }
    clipbox_2 { lo = [0.7, 0.2, 0.45]; hi = [0.8, 0.3, 0.55]; invert = true  }
    
    - clipfrustum_N: (Optional) Indexed frustum (or hollow frustum) clip(s). Up to 4 frustums are supported per iso-surface (clipfrustum_1, clipfrustum_2, ...). The frustum axis runs from lo to hi; radius is the cross-section radius at lo, and the optional radiushi is the radius at hi (defaults to radius, i.e., a cylinder). The optional radiusinner and radiushiinner carve out a coaxial hollow region (defaults: 0). An optional invert flag (default false) flips the keep/discard sense for that frustum: with invert=true points inside the frustum are discarded. All frustums are AND'd together and AND'd with any box clips. Example — a hollow cylinder along the y-axis between y=0.1 and y=0.4 with outer radius 0.18 and inner radius 0.08:
    isosurfaces_4 {
        isovalue   = 10
        contour    = vortmag
        colorfields = [umag]
        interval   = 100
        clipfrustum_1 {
            lo            = [0.75, 0.10, 0.50]
            hi            = [0.75, 0.40, 0.50]
            radius        = 0.18
            radiusinner   = 0.08
            # radiushi      = 0.18     # optional, defaults to radius (cylinder)
            # radiushiinner = 0.08     # optional, defaults to radiusinner
            # invert        = false    # optional, default false
        }
    }
    
    - normal, point: (Optional) For planar cuts, specify the normal vector and a point on the plane.
  • include zones: (Optional, Unst only) Restrict extraction to the listed grid zones of a multi-domain grid, e.g. include zones = [rotor1]. Entries are zone names as printed by the solver at grid read (1-based domain indices also work). Default: all zones. Tiles outside the listed zones are skipped entirely, so a tight filter also reduces extraction cost and file size. Applies to cut planes and field contours alike, and combines with box/frustum clips.
  • frame: (Optional, Unst only, cutplane contour only, default lab) Reference frame the cut plane is fixed in. With frame = <zone name> (a rotating zone, e.g. frame = rotor1; motion_N also works) the plane co-rotates with that zone's rigid body motion, so every output cuts the same material section of the blade. point and normal are interpreted in the chosen frame. With multiple rotors, each cut plane picks its own frame; zones with other motions appear at their instantaneous position relative to the reference frame. The default lab keeps the plane fixed in the laboratory frame.
  • frame coordinates: (Optional, Unst only, requires a rotating frame, default lab) Coordinate system the extracted surface is written in. lab dumps the vertices at their physical position, so the cut sweeps around with the blade and overlays volume, surface and iso-surface output directly — nothing to do in the viewer. frame = frame instead writes them in the reference frame's coordinates: the blade and the cut then stand still across outputs while the far field counter-rotates (the blade-fixed animation), at the price of needing a viewer-side rotation to get back to lab coordinates. Either way the file records the frame state in a LAVA_FrameMotion descriptor on the surface zone.
  • relative velocity: (Optional, Unst only, default false) With a rotating frame, subtract the reference frame's rigid-body velocity from the velocity before computing the colors, so they show the flow as seen from the rotating frame. It applies to the velocity fields of colorfields (q, or q with a velocity component, umag and mach), and the list must hold one of them; the gradient fields (vortmag, qcriterion, lambda2) use the velocity gradient in the laboratory frame.
  • writequads: (Optional, Cart only, default true) For an axis-aligned cutplane (normal parallel to a coordinate axis), emit the surface as the connected quad mesh of the cut cells — one cell-footprint quad per sampled point, with the sampled values carried as cell-centered data — so the output visually matches the Cartesian grid and neighboring quads share corners (visualization tools can then compute gradients). Set writequads = false to keep the raw marching-cubes triangulation. Has no effect for non-axis-aligned planes or field contours, which are always written as triangles.
  • writeboxes: (Optional, Cart only, default true) For an axis-aligned cutplane, write the outlines of the AMR boxes the plane passes through to a companion boxes_<filename> in the same directory — one quad per box, at the box's full extent, carrying Processor, DX and Level as cell data. Useful for seeing the domain decomposition and the AMR level structure behind a cut plane. The outlines come from intersecting the plane with the solver's real boxes, so this is independent of writequads and needs no color fields. One is written alongside every cut-plane output, so each surface file has a boxes_ file of the same timestep next to it — including when the plane produces no surface at all (e.g. one lying entirely inside a body), since the outlines come from the grid, not the surface. Has no effect on non-axis-aligned planes, field contours, or formats other than vtk/vtp. Set writeboxes = false to suppress the companion file.
  • qcompcontouring: Required for contour = q, selects the q component to contour.
  • qcompcoloring: Optional with a q color field, selects the single q component to write; without it q writes all components.
  • colorfields (additional entries): The entries after the first in colorfields are extra color fields written into the same file (except for qstats, the first entry must be q without qcompcoloring). Available options are any combination of:

    • qstats (Unst only; follows any first entry): the volume time average interpolated to the surface (pavg, uavg, vavg, wavg, tavg, TotalPressureAvg, pppp, upup, vpvp, wpwp, tptp, upvp, upwp, vpwp, as the volume qstats), written after the other color fields. Requires a time averaging section; listing it switches the volume average on like variables = [qstats] in the volume block does. The fields hold zeros until the average starts. Typical use is a cut plane carrying the mean flow, e.g. colorfields = [q, qstats]. Averages added by a runtime input change need a restart.
    • mach
    • density
    • errormetric (Cart only; contains zeros unless the solution-based AMR error-metric machinery is configured)
    • densitygradmag
    • umag
    • vortmag
    • qcriterion
    • lambda2
    • nut (Unst only)
    • dx, processor
    • inbody (Cart only; immersed-body indicator 0..1, see the primary-field list above)
    • ducros (Cart only; Ducros shock/upwind sensor [0,1])
    • strain (Cart only; strain-based upwind sensor [0,1])

    The output columns follow the order the fields are listed in colorfields (on Cart the full q vector first when the primary is q, then each additional field in order, with the qstats fields last; on Unst exactly the listed order). On GPUs, each additional field adds to the extraction kernel's shared-memory footprint; if the run aborts with a shared-memory error during isosurface setup, split the fields across two blocks. Cart example — one cut plane carrying the full state vector plus four extra fields in a single file (for Unst, drop errormetric and use format = cgns):

    isosurfaces_1 {
        contour     = cutplane
        point       = [0, 0, 0]
        normal      = [0, 0, 1]
        interval    = 500
        colorfields = [q, mach, density, errormetric, densitygradmag]
        format      = vtp
    }
    

Multiple Iso-Surfaces

You can define multiple iso-surfaces by incrementing the section name, e.g., isosurfaces_1, isosurfaces_2, etc.

Notes
  • Cut planes need both normal and point.
  • A cut plane that misses the grid or the domain is skipped with a warning at startup. On Unst this applies to cut planes in the laboratory frame on grids that do not move.
  • On Unst the iso-surface is marched over a tetrahedralization of the cell centroids. A centroid whose value equals the iso value within roundoff, as on a cut plane through a layer of centroids of a lattice or mirrored grid, or a contour at the value a field holds over a uniform region, lies on the surface: the surface passes through it once, without zero-area triangles around it.
  • On Cart, cgns and xdmf default to parallel output (doparallel = true), the others to a write from the gathered surface; on Unst every format defaults to the gathered write.
  • If the primary color field is q and qcompcoloring is not specified, the full Q vector is used for coloring.
  • Buffered output for isosurfaces is controlled by the outputbufferintervalisos variable in the output section, which defaults to an interval the code determines (see Buffered surface outputs). Buffering applies to gathered output; on Cart an iso-surface written in parallel turns it off for all of them (with a warning when outputbufferintervalisos was set), on Unst it leaves the others buffered.
  • For qcompcontouring and qcompcoloring, the component of the state vector follows this 0-index order: [p u v (w) T (Y1 Y2 Y3 ...)]. Here, note that the field w only exists when running the 3D executable.

Example Q-Criterion colored by velocity magnitude for HLPW6, Cartesian AMR based solution at alpha=35.

Example Q-Criterion output by the LAVA Cartesian AMR flow solver, colored by velocity magnitude for HLPW6 at alpha=35 degrees.

Surface

Surface Probes can be used to sample the flow on a plane slice.

output {
    surface probe_1 {
        point        = [0, 0.1, 0] # a point on the cut plane
        normal       = [0, 1, 0]   # the plane normal, along x, y or z
        interval     = 10 # Interval of sampling
        datalocation = face # sample location (face or node)
    }
}
Multiple surface probes can be specified by adding more sections.

Cartesian cut planes need a normal along x, y or z. One probe can write numplanes evenly spaced parallel planes from point to pointhi. The names of earlier releases, cutpoint, cutpointhi and cutdirection = x, y or z, are still read, with a deprecation warning that gives the replacement line.

The results will be written out to surf_probe directory. Each surface probe section will get its own file and will contain all the variables.

The output format can be selected with the format option. Available options include vtk (legacy VTK, default for Cartesian) and vtp (VTK XML PolyData). Example:

surface probe_1 {
    point        = [0, 0.1, 0]
    normal       = [0, 1, 0]
    interval     = 10
    format       = vtp
}

The Cartesian solver has the ability to buffer our surface output in such a way that all MPI ranks can do simultaneous parallel writes. This is controlled by the optional outputbufferintervalsurf = 20000 variable, where 20000 is an example time-step interval. If the variable is left out, the code will automatically compute the outputbufferintervalsurf if it is not provided.

Wall-model surface variables

In addition to the standard surface variables (q, mach, pcoef, etc.), the following per-vertex wall-model quantities can be requested in the surface variables list and are written when at least one immersed BC uses a wall-stress model:

  • tauwX, tauwY, tauwZ: components of the modeled wall shear stress vector.
  • yplus: y+ evaluated at the wall-model sample point.
  • partialslip: dimensionless slip indicator in [0, 1]: ratio of the wall-model tangential velocity at y⁺ = partialslipheight to the tangential velocity at the wall-model sample point. 1 = fully slip (profile is nearly flat between y⁺ = partialslipheight and the sample point); 0 = no-slip (laminar flow detected by the transition sensor, or tau_w ≈ 0). Useful for visualizing where the wmpartialslip BC is operating in its slip-like vs. no-slip-like regime. Automatically skipped if no wall uses the partial-slip wall model.
  • qdot: surface heat flux. Automatically skipped if no isothermal/wmisothermal wall is present in the BC configuration (the value would be zero).
  • turbulence: turbulence-transition sensor. Automatically skipped if no wall has transitionthreshold > 0 configured (the sensor is inactive).

All of the above are also enabled together via the shorthand token wallmodel in the variables list.

Grid imprinting (cut cells)

By default a surface is sampled and written at the resolution of its input triangulation. For a 3D, triangulation-based geometry, gridimprint (in the output { surface {} } block) imprints the computational grid onto the immersed surfaces — cutting them at the grid cells — so the surface output, surface sampling, and loads are all resolved at the grid's cell resolution. It applies to all immersed surfaces.

output {
    surface {
        gridimprint = cartesian   # none | triangles | cartesian
        variables   = [q, wallmodel]
        format      = cgns
        interval    = 1
    }
}
  • none (default): no imprint — the original body triangulation is used as-is.
  • cartesian: output the per-cell triangles merged into larger flat polygons (recommended).
  • triangles: output the raw per-cell triangles.

The merge cone half-angle (degrees) for the cartesian (merged) imprint is set with clipmergeangle (default 1.0).

Surface Probe

User specified surface extractions are possible using either an arbitrary triangulation, or user specified cut-planes.

surface probe_1 {
     file        = triangulation.i.tri
     scale       = [0.75^3]
     interval    = 10
   }
surface probe_2 {
     point = [1,0,0]
     normal       = [0, 1, 0]
     interval     = 10
   }
surface probe_3 {
     point      = [-0.1,0,0]
     pointhi    = [ 0.1,0,0]
     numplanes = 11
     normal       = [1, 0, 0]
     interval     = 10
   }
}

For cut-plane probes, boxes_* files are also written alongside the cut-plane output. These correspond to the block-structured boxes intersected by each cut-plane and are primarily useful for cleanly visualizing the box layout as intersected by the cut-plane without the visual overhead of full cell-level data. Each box also carries per-box scalar values as a secondary, lower-resolution representation of the flow solution.

Line Probe

lineprobe_1 {
    start = [-1.000, 0.0,0];
    end = [1.000,0.0,0];
    number of points = 512;
    interval = 20;
    # Optional: also write time-averaged statistics (means, RMS, Reynolds stresses)
    # alongside the instantaneous state. See the Time Averaging section for the schedule.
    variables = [q, qstats];
    }

Point Probe

Point probes will sample the flow state at a number of given points. A group of points can be specified at once using an ascii file that lists the x y z coordinates of each point in order (space delimited):

output {
    point probe_1 {
        file = ascii_file_with_xyz_coords.dat
        interval = 1 # Interval of sampling
        scale = 1 # Option to scale the coordinates
        # Optional: also write time-averaged statistics (means, RMS, Reynolds stresses).
        # See the Time Averaging section for the schedule.
        variables = [q, qstats]
    }
}

Results will be written to an ascii file in the point_output directory, where each probe section and each variable will get its own file.

Time Averaging

Time averaging accumulates running statistics of the flow (means, RMS of the fluctuations, Reynolds shear stresses, mean total pressure, ...) as the simulation advances. Two things are configured independently:

1. Which averaged quantities are written. Add the averaging tokens to the variables list of the output you care about (volume, surface, or a line/point probe). Each token expands to its averaged columns:

token averaged columns
qavg means of pressure, velocity, temperature (and species)
qstats the full statistics set: the qavg means, mean total pressure, RMS of each fluctuation, and the Reynolds shear stresses
yplusavg (unstructured surface) mean y+
tauwavg (unstructured surface) mean wall-shear-stress components

Volume (and unstructured surface) second moments are central moments, the averages of the fluctuations: pppp, upup, vpvp, wpwp, tptp and upvp, upwp, vpwp hold p'p', u'u', ... and u'v', ...; do not subtract the squared mean. A moment is always written with its mean.

Cartesian surfaces and probes take qstats only (a partial token is an input error). Line probes, point probes, the body surface and each surface probe accumulate the statistics on their own sample points and write them as extra columns of their ordinary output files: pavg uavg vavg wavg tavg TotalPressureAvg prms urms vrms wrms trms uvavg uwavg vwavg. A surface also gets the running mean of every other column it writes, named <column>avg (Machavg, Densityavg, yplusavg, qdotavg, tauwXavg, MassFraction_<species>avg, ...; not turbulence or ReactionStepCount), and the rms of the wall shear (tauwXrms, tauwYrms, tauwZrms). The statistics survive regrids, moving-body re-clips and restarts at any rank count; every vertex shares its surface's averaging window, newly exposed surface takes the history of the nearest carried surface, and probe vertices inside a body hold no statistics. output qstats = true in a surface or surface probe block is the same as listing qstats.

2. When and how often to accumulate. The optional time averaging { } block sets the schedule. A global schedule applies to every target; per-target sub-blocks override it. If the block is omitted entirely, averaging begins at the first step and samples every step.

output {
    time averaging {
        # ---- global schedule (inherited by every target) ----
        # Start averaging at a step, physical time, or CTU (specify only one).
        # If none is given, averaging starts at the first step.
        start ctu = 50
        # Fold a sample into the running average every N steps. Default: the loads interval, or 100
        # without loads output.
        sampling interval = 1
        # cumulative (default) | exponential   (see "Exponential Moving Average" below)
        method = cumulative

        # ---- optional per-target overrides ----
        volume      { sampling interval = 10 }  # average the volume less frequently
        surface     { start ctu = 60 }          # start the surface average later
        lineprobes  { sampling interval = 1 }   # (Cartesian) probe-statistics schedule
        pointprobes { sampling interval = 1 }
    }

    volume  { interval = 1000; variables = [q, qstats] }               # write cadence + averaged columns
    surface { interval = 1000; variables = [q, wallmodel, qstats] }    # Cartesian: qstats columns
}

Key points:

  • The start is inclusive. The first sample is the solution at the start step, or at the first step at or after the start time or CTU, and every output holds the samples up to and including its own step.
  • The sampling interval is independent of the output interval. sampling interval controls how often a sample is folded into the running average; the output interval controls how often the current average is written to disk. Averaging accumulates continuously at the sampling cadence regardless of when files are written.
  • When no sampling interval is set, globally or in the target's own block, every target (volume, surface, lineprobes, pointprobes) samples on the loads interval, or every 100 steps when there is no loads output. Set sampling interval = 1 to sample every step.
  • Listing an averaging token in a target's variables list is what enables averaging for that target; the time averaging { } block only shapes the schedule.
  • Targets are volume, surface, lineprobes, and pointprobes. Each inherits the global schedule and overrides only the keys it sets.

Exponential Moving Average

By default, LAVA uses a cumulative average (equal weight to all past samples). For long unsteady runs it can be useful to instead use an exponential moving average (EMA), which gives a decaying weight to older data so that the average tracks the recent flow statistics. Select it with method = exponential and set a window:

time averaging {
    start ctu = 50
    method    = exponential

    # Window size W in CTU. Data older than W has approximately 3% residual weight.
    window ctu = 10
    # Alternatively, specify the window directly in physical time units (seconds):
    # window = 0.05
}

The EMA blending weight at each sample step is:

\[ \alpha = \min\!\left(1,\; \frac{c}{W} \cdot \Delta t_\text{elapsed}\right), \qquad c = 3.5 \]

where \(W\) is the window size in physical time and \(\Delta t_\text{elapsed}\) is the elapsed physical time since the last averaging sample. At each step the average is updated as:

\[ \overline{q} \leftarrow \alpha\, q + (1 - \alpha)\, \overline{q} \]

In the continuous limit, data from time \(\tau\) ago carries weight \(\propto e^{-c\,\tau/W}\). At exactly one window back (\(\tau = W\)) the residual weight is \(e^{-3.5} \approx 3\%\). method and window may be set globally or inside any per-target sub-block.

Legacy keys

Older input spellings are still accepted for backward compatibility:

  • do volume / do surface — deprecated and no longer needed. Volume and surface averaging are now controlled solely by whether averaging tokens appear in the target's variables list. For Cartesian surfaces, do surface = false still turns the surface statistics off.
  • do exponential moving average = true with exponential moving average window ctu (or exponential moving average window) — the pre-method EMA spelling.
  • frequency — deprecated alias for sampling interval.

Note

For Cartesian line and point probes, time-averaged statistics are accumulated directly on the probe points (a numerically stable running Welford update), independent of the full-field volume average. Enable them per probe with variables = [q, qstats] (or output qstats = true), and use the lineprobes { } / pointprobes { } sub-blocks to set their sampling schedule.