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).
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]
}
...
}
}
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
}
}
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 snapshotsoutputs 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
STOPfile 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:
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)qcriterionlambda2machdensitygradmagq(a specific component of the q vector. The optionqcompcontouringis then required to specify the component index)cutplane(for planar cuts; requiresnormalandpoint, as surface probe cut planes and volume plane subsets do. On Unst, the whole cells a plane passes through are written by a volumesubsetoftype = 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_Nblocks 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)vortmagqcriterionerrormetric(Cart only)densitygradmagmachdensitynut(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,1inside the geometry and0in fluid. On a cut plane the edge interpolation makes it a smooth0..1ramp across the body boundary, so you can threshold or mask on it. Most useful withdosolvecellsonly = false, the cut-plane default, so the plane fills through the body.)ducros(Cart only; Ducros shock/upwind sensordilatation²/(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 sensor1 − 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; withqcompcoloring, only the component of that index.fullqis 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 beqwithoutqcompcoloring. Example:colorfields = [q, mach, inbody, ducros]. A single field with no extras is justcolorfields = [umag](or[mach],[inbody], etc.).Unst color lists. On Unst
colorfieldsis one flat list of up to 16 entries in any order:q,umag,vortmag,qcriterion,lambda2,densitygradmag,mach,density,nut,dx,processorandqstats. Each entry is written once, in the listed order, and the first entry names the file.qwrites all components of the q vector, or withqcompcoloringonly the component of that index; a list holding both the full vector (fullq) and aqcomponent 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 forq. A vertex on a partition boundary is extracted by every rank holding its edge, soProcessordiffers 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) plusderivedvars = [...]syntax still works, but is deprecated and will be removed in a future release; usecolorfields = [<field>, ...]instead.colorfield = Xis equivalent tocolorfields = [X], andcolorfield = fullq; derivedvars = [a, b]is equivalent tocolorfields = [q, a, b]. A deck using either key warns at startup with the exactcolorfieldsline to replace it with. - interval: Output interval in time steps (e.g.,interval = 100). - format: Output file format. Withdoparallel = trueevery rank writes its piece of the surface into one shared file; withdoparallel = falsethe surface is gathered on one rank and written there, buffered overoutputbufferintervalisosoutputs (see Buffered surface outputs). A format its write path cannot produce stops at input. - Cart:vtk(default),vtpandcgnsgathered;cgnsandxdmfdefault to parallel output, andvtkwithdoparallel = truewrites one ASCII file per rank. - Unst:cgns(default),vtkandvtp, gathered and buffered unlessdoparallel = true, which writescgnsin parallel. A gathered iso-surface too large for one rank is written in parallel instead. -vtkandvtpfiles hold single precision values;vtpis VTK XML PolyData with raw binary appended data. -vtpwrites 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 totrue. Cut planes default tofalse, so the plane fills through the body and you can see the section of the geometry — pair with theinbodycolorfield to visualize or mask the solid. Setdosolvecellsonly = trueon 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, whendosolvecellsonlymasking is on. By default (ghost) gradient fields extend all the way to the wall using the immersed-boundary image states.nearwallgradients = excludeinstead 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 singleclipbox_1 { lo=...; hi=...; invert=false }; emits a deprecation warning at run time. Cannot be combined with indexedclipbox_Nsub-sections. Preferclipbox_1in 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 haslo,hi, and an optionalinvertflag (defaultfalse). Wheninvert=falsethe box keeps points inside it; wheninvert=trueit keeps points outside it. All configured boxes are AND'd together, and AND'd with allclipfrustum_Nregions. On Unst, boxes and frustums are in the coordinates ofpointandnormal(the laboratory frame, or the reference frame withframe = <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:- clipfrustum_N: (Optional) Indexed frustum (or hollow frustum) clip(s). Up to 4 frustums are supported per iso-surface (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_1,clipfrustum_2, ...). The frustum axis runs fromlotohi;radiusis the cross-section radius atlo, and the optionalradiushiis the radius athi(defaults toradius, i.e., a cylinder). The optionalradiusinnerandradiushiinnercarve out a coaxial hollow region (defaults:0). An optionalinvertflag (defaultfalse) flips the keep/discard sense for that frustum: withinvert=truepoints 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 betweeny=0.1andy=0.4with outer radius0.18and inner radius0.08:- normal, point: (Optional) For planar cuts, specify the normal vector and a point on the plane.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 } }
- 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,
cutplanecontour only, defaultlab) Reference frame the cut plane is fixed in. Withframe = <zone name>(a rotating zone, e.g.frame = rotor1;motion_Nalso works) the plane co-rotates with that zone's rigid body motion, so every output cuts the same material section of the blade.pointandnormalare 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 defaultlabkeeps the plane fixed in the laboratory frame.
- frame coordinates: (Optional, Unst only, requires a rotating
frame, defaultlab) Coordinate system the extracted surface is written in.labdumps 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 = frameinstead 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 aLAVA_FrameMotiondescriptor on the surface zone.
- relative velocity: (Optional, Unst only, default
false) With a rotatingframe, 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 ofcolorfields(q, orqwith a velocity component,umagandmach), 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-alignedcutplane(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). Setwritequads = falseto 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-alignedcutplane, write the outlines of the AMR boxes the plane passes through to a companionboxes_<filename>in the same directory — one quad per box, at the box's full extent, carryingProcessor,DXandLevelas 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 ofwritequadsand needs no color fields. One is written alongside every cut-plane output, so each surface file has aboxes_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 thanvtk/vtp. Setwriteboxes = falseto suppress the companion file. - qcompcontouring: Required for
contour = q, selects the q component to contour. - qcompcoloring: Optional with a
qcolor field, selects the single q component to write; without itqwrites all components. -
colorfields (additional entries): The entries after the first in
colorfieldsare extra color fields written into the same file (except forqstats, the first entry must beqwithoutqcompcoloring). 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 volumeqstats), written after the other color fields. Requires atime averagingsection; listing it switches the volume average on likevariables = [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.machdensityerrormetric(Cart only; contains zeros unless the solution-based AMR error-metric machinery is configured)densitygradmagumagvortmagqcriterionlambda2nut(Unst only)dx,processorinbody(Cart only; immersed-body indicator0..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 isq, then each additional field in order, with theqstatsfields 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, droperrormetricand useformat = cgns):
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
normalandpoint. - 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,
cgnsandxdmfdefault 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
qandqcompcoloringis not specified, the full Q vector is used for coloring. - Buffered output for isosurfaces is controlled by the
outputbufferintervalisosvariable 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 whenoutputbufferintervalisoswas set), on Unst it leaves the others buffered. - For
qcompcontouringandqcompcoloring, the component of the state vector follows this 0-index order: [p u v (w) T (Y1 Y2 Y3 ...)]. Here, note that the fieldwonly exists when running the 3D executable.
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)
}
}
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:
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⁺ =partialslipheightto the tangential velocity at the wall-model sample point.1= fully slip (profile is nearly flat between y⁺ =partialslipheightand the sample point);0= no-slip (laminar flow detected by the transition sensor, ortau_w ≈ 0). Useful for visualizing where thewmpartialslipBC 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/wmisothermalwall is present in the BC configuration (the value would be zero).turbulence: turbulence-transition sensor. Automatically skipped if no wall hastransitionthreshold > 0configured (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 intervalcontrols how often a sample is folded into the running average; the outputintervalcontrols 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 intervalis set, globally or in the target's own block, every target (volume,surface,lineprobes,pointprobes) samples on the loadsinterval, or every 100 steps when there is no loads output. Setsampling interval = 1to sample every step. - Listing an averaging token in a target's
variableslist is what enables averaging for that target; thetime averaging { }block only shapes the schedule. - Targets are
volume,surface,lineprobes, andpointprobes. 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:
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:
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'svariableslist. For Cartesian surfaces,do surface = falsestill turns the surface statistics off.do exponential moving average = truewithexponential moving average window ctu(orexponential moving average window) — the pre-methodEMA spelling.frequency— deprecated alias forsampling 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.
