LAVA Documentation
Computational Aerosciences Branch
NASA Advanced Supercomputing (NAS) Division
Ames Research Center
Joshua L. Anibal, Chase P. Ashby, Michael F. Barad, Francois Cadieux, Christopher J. DeGrendele, Jared C. Duensing, Ercan Dumlupinar, Jeffrey A. Housman, James C. Jensen, James R. Koch, Olivia G. Martin, Abram K. Rodgers, and Emre Sozer
NASA Ames Research Center, Mountain View, California
Alexander W. Aghili, Timothy Chau, David A. Craig Penner, Victor de Carvalho Britto Sousa, Luis dos Santos Fernandes, Brandon Lowe, Nguyen Ly, Kiran Ravikumar, and Gerrit-daniel Stich
Analytical Mechanics Associates, Mountain View, California
Generated on: 11/09/2026
Version: v1.1.0
Table of Contents
Overview
Introduction
The Launch, Ascent, and Vehicle Aerodynamics (LAVA) Framework is a suite of Computational Fluid Dynamics (CFD) and multi-physics solvers with accompanying toolsets for pre- and post-processing including grid generation.
With origins in the late 2000's, LAVA has been continually developed in the Computational Aerosciences branch of NASA Ames Research Center to address a wide variety of NASA's fluids modeling and simulation needs. The solver is built on a modern and flexible software architecture with extensive continuous integration testing at scale, pushing the state-of-the-art in both CFD methods and high-performance computing.
LAVA AMS Seminar
Applications
Some notable areas of application have been:
- Launch pad pressure and thermal environment analysis, including multi-phase simulations of plume-water interactions, over-pressure wave dynamics, and conjugate heat transfer for launch pad components. These capabilities have been applied to Space Shuttle, Artemis, and commercial launch vehicles.
- Aerodynamic performance characterization and sonic boom predictions for the X-59.
- Atmospheric re-entry vehicle deceleration simulations, including supersonic parachute deployment with fluid-structure interaction, dynamic stability analysis with 6DOF motion, and supersonic retro-propulsion dynamics.
- Aero-acoustic predictions for propulsion systems, including open-rotor noise analysis and X-59 jet noise assessment.
- Aerodynamic buffeting mitigation strategies for Artemis at the solid rocket booster forward attachment point.
- Conceptual design evaluation and optimization of novel airframe concepts through programs such as SUSAN and HEATHeR.
- High-fidelity scale-resolving simulations of aircraft operating with deployed high-lift systems during takeoff and landing phases.
Please see the Applications Gallery for more details on some of these applications.
Solver Capabilities
The development of LAVA's capabilities is guided by the application needs. To enable large-scale simulations with relatively modest compute resources and provide the most efficient and appropriate grid paradigms for each application, LAVA emphasizes both algorithmic innovation and code optimization for high-performance computing environments.
A central philosophy of LAVA is to reduce user-effort and improve error-prone aspects of the CFD workflow through extensive automation and robust tooling. This is exemplified by LAVA's support of multiple meshing paradigms: block-structured curvilinear with overset, Cartesian immersed boundary with Adaptive Mesh Refinement (AMR), and arbitrary polyhedral unstructured meshes. These methods provide users with the flexibility to choose the appropriate mesh paradigm for their specific application, ranging from fully hand-tailored body-fitted curvilinear meshes to partial automation using hybrid curvilinear/immersed-boundary approaches, to fully automated Cartesian or Voronoi unstructured meshes. Additionally, LAVA provides comprehensive in-situ and post-processing tools to streamline the entire simulation workflow.
A high-level overview of LAVA solver capabilities is given below:
| Capability | Cartesian | Curvilinear | Unstructured |
|---|---|---|---|
| Mesh type | Cartesian | Block-structured | Arbitrary polyhedral unstructured |
| Equations | Navier-Stokes | Navier-Stokes | Navier-Stokes |
| Discretization | Finite difference | Finite difference | Finite volume |
| Compressibility | Compressible | Compressible | Compressible |
| Fluid Model | Perfect, Stiffened | Perfect | Perfect |
| Boundary representation | Immersed Boundary | Body-fitted/immersed boundary | Body-fitted |
| Mesh transitions | Octree 2:1 interfaces | Overset or multi-block | Conformal |
| Spatial order of accuracy | 2nd, 4th | 2nd, 4th | 2nd |
| Temporal order of accuracy (explicit) | 2nd, 3rd, 4th | 3rd | 2nd, 3rd, 4th |
| Temporal order of accuracy (implicit) | ✗ | 2nd | 2nd |
| Solution Approaches | WMLES | WMLES/HRLES/RANS | WMLES/RANS |
| Mesh Adaptation | Adaptive mesh refinement | Adjoint based redistribution | ✗ |
| Moving bodies | Prescribed/6DOF motion | Prescribed | ✗ |
| Multi-species | ✓ | ✗ | ✓ |
| Multi-phase | ✓ | ✗ | ✗ |
| Reacting flows | ✗ | ✗ | ✗ |
| Radiative heat transfer | ✗ | ✗ | ✗ |
| Fluid-structure interaction | Shell element | ✗ | ✗ |
| Conjugate heat transfer | ✗ | ✗ | Coupled 1-D solid conduction |
| Shape optimization | ✗ | ✓ | ✗ |
| Hardware | CPU, static geometry on GPU | CPU, WMLES on GPU | CPU, WMLES on GPU |
RANS: Reynolds-averaged Navier-Stokes
HRLES: Hybrid Reynolds-averaged Navier-Stokes large-eddy simulation
WMLES: Wall-modeled large-eddy simulation
Getting Started
Gallery
Showcased below is a sampling of application work done with LAVA at NASA. This list is nowhere near exhaustive, but is meant to be illustrative of what LAVA can be used for.
Space
Aeronautics
Tutorials Overview
There are download links throughout the tutorials, but you can also download all the tutorial files (except for the meshes) as a tarball.
Uncompressing the tarball should create a neat file structure organized by <tutorial case>/<solver type>, you can do this with.
wget -r -np -erobots=off -nH --cut-dirs=1 -P tutorial_files/ https://data.nas.nasa.gov/lava/
find tutorial_files/ -name "index.html" -delete
index.html files used by wget.
You can download the meshes one at a time from the NAS data-portal website or from the links embedded in the tutorials throughout.
Tutorial Map
Below is a map of the tutorials available for each solver.
Curvilinear
- QuickStart
- Overset Grid Symposium 2026 Tutorial Collection
- CRM Wing Body Steady RANS
- ONERA OAT15A Hybrid RANS-LES
- JAXA Wing Body Geometry
- NACA0012 Rotor in Hover
- CRM Wing Body Discrete Adjoint
- Aerodynamic Analysis using pyLAVA
- Airfoil Shape Optimization
- Wing Twist Optimization
- Wing Twist Optimization using OpenMDAO
Unstructured
- Supersonic Flow Over Diamond Airfoil
- Double Mach Reflection
- Laminar Flow over Circular Cylinder
- RANS Multielement Airfoil
- Onera M6 Wing
- High-Lift CRM Wing WMLES Tutorial (HLPW6 Case 1)
- JAXA Wing Body RANS
- Genesis Capsule
Cartesian
Version Notes
As new versions of LAVA are released you can find information on the fixes and features added by each version here.
1.1.0
LAVA 1.1.0 is a feature release with bug fixes and improvements across all three solvers. Cartesian and Unstructured defaults changed, some of their inputs were removed, and several fixes change results: read Upgrading from 1.0.1 before rerunning existing decks.
Highlights
- Cartesian: grid-imprinted surfaces (
gridimprint); running statistics (qstats) on probes and surfaces; multi-field iso-surfaces; elliptical, polygonal, spheroidal and telescoping refinement regions; a Noble-Abel stiffened-gas equation of state. - Unstructured: the
gglexandlsqrgradients; therminmodandrvlmclimiters; agglomeration of tiny cells; a matrix-free fallback for stalled implicit runs; watertight iso-surfaces; probes with gradient fields and moving frames. - Cartesian and Unstructured: significantly more accurate float builds (arXiv:2611.05365); a sync clock for evenly spaced output with CFL-driven time steps; one
time averaging { }block for every output; aSTOPfile that ends a run with a restart. - Curvilinear: rotating reference frame; partial-wedge sliding mesh; stiffened-gas builds; exponentially weighted time averaging.
Upgrading from 1.0.1
Inputs removed or now rejected. Decks that use these stop at input with a message.
- Cart:
hwcnsis the only convective scheme. Theweno5*andweno6schemes,muscl,centralskew,centralqandfictghostsextraporder = 2are removed; useflux order = 2or4andfictghostsextraporder = 0or1. - Cart:
dothinbody,use approximate solverandgridqualityinupwind blending sensorsare removed. - Cart: CPU and GPU builds reject options the solver does not implement (for example immersed
distributedboundaries, SGS models other thanvreman,doextrapatcf, several domain-face types, and on GPU thereichardtwall law) instead of ignoring them. - Cart: the partial statistics tokens on surfaces and probes (
pavg,tke,reynoldsstress, ...) are replaced byqstats, and plane volume subsets are replaced by thinboxsubsets. - Unst: a mass-flow inlet needs
temperatureordensityas well aspressure. - Cart volume output and Unst probes reject variables they cannot write.
- Cart and Unst: point-probe
scaletakes one value per direction, and iso-surface formats a write path cannot produce are rejected.
New defaults. Decks that set these inputs explicitly are unaffected.
| Solver | Input | 1.0.1 | 1.1.0 |
|---|---|---|---|
| Cart | upwind blending finetocoarse / corners |
1 / 0.1 |
0 / 0; nonzero values now taper over upwind blending finetocoarse ramp cells (4) |
| Cart | limiter |
weno3op |
weno3js |
| Cart | next to trapped first order (with limiter = none) |
no option, as false |
true; immersed-body decks change |
| Unst | limiter |
minmod |
none; set rminmod for transonic and supersonic flow |
| Unst | reconstruction kappa |
0 |
1/3 (U-MUSCL) |
| Unst | gradient method |
gg |
gglex |
| Unst | agglomerate, size filter method |
no agglomeration, percent |
true, knee |
| Unst | steady implicit: jacobian method, jacobian interval, do line search |
analytical, 1, false |
numerical, 5, true |
| Unst | max CFL; GMRES iterations and tolerance |
20; 10, 1e-3 |
1e4; 40, 1e-2 |
| Cart, Unst | time-average sampling interval |
every step | loads interval (or 100); 1 restores 1.0.1 |
| Cart, Unst | ducros / strain sensor noise floors |
none | on; 0 removes them |
Documentation correction. Cart upwind blending sensors defaults to [none], not [weno] like past documentations stated. [neumann, strain] is recommended.
Other changes to results.
- Cart fixes: HLL-family flux wave speeds, including the default
hllec; Periodic AMR and boundary faces. - Cart: HWCNS upwind blending is reworked, and the laminar wall shear on wall-modeled slip walls with the turbulence sensor is larger.
Renamed outputs and files. Update ParaView states and post-processing scripts.
- Cart: iso-surface file names no longer include the color field, and
colorfieldbecomescolorfields = [...](the old key warns); surfaceqstatsnow hold surface statistics and theavg_surffiles are gone; field contours are no longer extracted inside bodies (dosolvecellsonly = falserestores this). - Unst: probe files use the volume-output variable names (
Mach,Nut,InOut, ...), are numbered from 1, and every latest link is<stem>Latest; iso-surface color fields use the Cart names (Umag,VortMag,QCriterion, ...); grid files are named after their first solution step (Unst.vol.meshLink.<step>.cgns); BC surface variables follow the order of thevariableslist. - Unst: iso-surface files are labeled with the step whose solution they hold (they carried the previous step), label 0 is the initial condition, and every iso-surface is also written at the last step.
- Unst: every surface output is gathered and buffered by default;
doparallel = truewrites parallel CGNS. - Cart and Unst: time-averaged second moments are now fluctuations (u'u', not ⟨uu⟩), so do not subtract the squared mean. They are renamed
ppav→pppp,uuav→upup,uvav→upvp(likewisevpvp,wpwp,tptp,upwp,vpwp) in output files and monitor columns; the old input tokens still work. A moment also writes its mean, and the Tecplot and VisIt derived expressions are reduced to TKE. - Cart and Unst: cut planes take
point,pointhiandnormal(cutpoint,cutpointhi,cutdirectionand subsetoriginstill work, with a warning). - Cart float builds (not multiphase): restart files hold the full integrator state and cannot be read by 1.0.1; 1.0.1 restart files still load.
Cartesian Solver
Enhancements
gridimprintcuts immersed surfaces at the grid cells, so surface output, sampling and loads are resolved at the cell size (3D triangulated geometry). See Output.qstatson line probes, point probes, surfaces and surface probes: running means, rms and Reynolds stresses, independent of the volume average and kept across regrids, moving bodies and restarts.- Iso-surfaces: one
colorfieldslist carries several fields, with new fieldsinbody,ducros,strain,eddyviscosity,processoranddx. Axis-aligned cut planes are written as the cut cells with the AMR box outlines. - Refinement: elliptical and polygonal tag cylinders,
tagspheroids, telescoping regions, and theleonardstressmagerror metric. - Numerics: the
neumannshock sensor;addshockdissipationnow takes effect; per-level convective options are documented and work on GPU. - 2D runs accept
alphaorbetaas the flow angle, and loads report lift and drag against it. - Multiphase: Noble-Abel stiffened-gas equation of state (
bin species files). - Float builds (not multiphase) are substantially more accurate with every Runge-Kutta scheme.
- The volume output variable
eddyviscosityis now filled (Vreman SGS model).
Fixes
farfielddomain faces now apply a farfield condition (1.0.1 stopped on CPU and left the face unset on GPU).- Restarts no longer reset
cflto the scheme limit, and accept surface output columns that differ from the checkpoint. - Scheduled
orderandupwind blending minnow reach every level. tag all geometry max levelno longer rebuilds the finest level at alternate regrids.- An
inputs updatingschedule that changesmax cellsor raises the level limit now regrids at the next step. - Moving bodies: slip walls, surface-probe flags and block classification of rotated bodies.
- Iso-surfaces: large (over 4 GiB) buffered output, crashes with mixed color-field counts, leftover triangles in parallel output, and duplicate writes with free-flight motion.
- Volume files with empty AMR levels that ParaView could not read;
laplacianvvelwas never computed.
Performance
- Faster setup, regrids and restarts with prescribed-motion bodies and in large wall-modeled cases.
Unstructured Solver
Enhancements
- Gradients:
gglex(default) is exact for linear fields on any polyhedral mesh;lsqris a weighted least-squares gradient;ggreproduces 1.0.1. - Limiters:
rminmod(recommended for supersonic and hypersonic flow) andrvlmc(sharper shocks, less robust on strong 3D shocks). Neither limits shear or boundary layers. - Tiny, near-degenerate cells are agglomerated with a neighbor and solved as one conservative cell.
- Steady implicit runs switch to a matrix-free linearization when the CFL controller detects a stall (
matrix free on stall). - Probes write any variable in their
variableslist, including gradient fields (vorticity,qcriterion,lambda2, ...), the size and volume of the cell holding the point (dx,volume) and cell status, and take aframeto follow a moving zone. - Cut planes take any
normal, write every plane of anumplanesset, follow moving zones, and leave no gaps across cells and ranks;crinkle = truewrites the mesh faces instead. output integratedadds gross mass flux and weighted Mach number, pressure and velocity, with one history file per probe.- Iso-surfaces are watertight (~2 times fewer triangles), carry up to 16 color fields, and can be written as
vtkorvtp. - Volume output adds the gradient fields,
umag,dxandprocessor. - Float GPU builds are substantially more accurate with every explicit Runge-Kutta scheme.
Fixes
- GPU: BC statistics and surface output read stale wall shear, heat flux and mass flux, and
Viscosity,mdotandqdotwere never filled. - Probes: per-probe intervals, duplicated samples after restarts, mislabeled columns, interpolation near walls and outside the mesh.
- Surfaces: off-by-one step labels, restart grid links, node-data strides, and
output integratedface areas and hangs. - Volume output: polyhedral cell numbering, overflow beyond 2^31 cells, multi-rank trip-cell output, and a crash once a rank's share of the grid connectivity passed 1 GiB.
- Implicit: the line search used the wrong step's change limit, and matrix-free runs leaked their preconditioner.
Performance
- GPU probes sample on the device, and GPU iso-surface setup is about 20 times faster.
Cartesian and Unstructured Solvers
Enhancements
- Sync clock:
sync dt,sync ctu,sync steps per ctuorsync freqin thetimesection clips CFL-driven time steps so outputs land at even intervals (explicit runs). An Unstructured run ends on the sync mark nearestfinish timeorfinish ctu, with a warning when the finish time is off the marks. See Time. time averaging { }sets one averaging schedule (cumulative or exponential), with per-output overrides for volume, surfaces and probes.- A
STOPfile, checked every 40 steps, ends a run with its buffered outputs and a restart; SIGTERM writes the buffered outputs, but no restart, before stopping. - Buffered outputs can also flush on a timer (
output buffer flush period) or a memory limit (output buffer memory). - The startup check warns when the run directory is on NFS, in memory, node-local or not shared by all ranks (
LAVA_PERF_CHECK=0skips it). - Unsteady runs report
percentage_doneandtime_leftwhen they are listed in the monitorvariables. - An optional reference
spannormalizes the rolling and yawing moment coefficients. - Nozzle boundary conditions accept
radiusdirectionfor slot and planar injectors. - GPU kernel autotuning now covers the Unstructured solver as well as the Cartesian solver. The new
gpu { autotune = false }input turns it off; the default istrue.
Fixes
- Volume subsets write at their own interval, and fields named by several tokens are written once.
- Time averages no longer start one step late.
- A parallel CGNS write no longer slows later I/O, and split-zone grids no longer hang with small zones.
- Unst surfaces read from Plot3D files had wrong face areas.
- A missing restart file is reported on screen; restarts with
binary = falsein the monitor no longer hang.
Curvilinear Solver
Enhancements
- Rotating reference frame (
rotatingRefFramein the input YAML). - Partial-wedge sliding mesh, with optional polar interpolation of velocity in the sliding rings (
usePolarInterpInSlidingRings). - Build options for a stiffened-gas equation of state (liquids) and constant viscosity.
- Subsonic inflow specified by density, velocity and inflow direction.
- Exponentially weighted moving time averaging.
- Output: polar-coordinate variables (
polarradius,polartheta,radialvelocity,swirlvelocity), wiggle sensors (WiggleSensorJ/K/L), MPI-parallel Tecplot slices and iso-surfaces, and integration of Plot3D line probes. - A mesh refinement utility.
Fixes
- Restarts with averaged probe variables.
- Slice and iso-surface output: last-step time stamps, Tecplot strand IDs, and variables that need previous-step data.
sourceUserno longer requires a RANS file.- The adjoint "Mat mult time" counted parallel products twice.
Builds
- Single-species executables for NVIDIA V100 GPUs (
PTX70) in the x86_64 NVIDIA tarball (1.1.0 only; Curvilinear in double precision only).
1.0.1
LAVA 1.0.1 is a patch release with bug fixes, input naming cleanup, and general improvements across all three solvers.
Cartesian solver: Bug fixes address time-averaging EMA restart correctness, HWCNS positivity logic, multiphase nozzle and equilibrium input validation, and immersed boundary and AMR robustness. The default convective flux function changes from Rusanov to HLLEC for improved low-Mach accuracy. New features include volume subset output, an overhauled turbulence transition sensor, the wmpartialslip immersed BC, and new IB diagnostic surface output variables.
Unstructured solver: Bug fixes address time-averaging reset correctness, wall-model TKE sensor numerical stability, CFL diagnostic inconsistency, surface output ordering across MPI configurations, and problem cell output with high rank counts. New features include wall-normal line probe output for u⁺/y⁺ post-processing, anisotropic LES Vreman filter size, solution-linked surface CGNS output, compact binary BC statistics, automatic Jacobian epsilon selection, and problem-cell CGNS dumps on abort.
Cartesian and Unstructured: Exponential moving average (EMA) time-averaging inputs are renamed from ...timescale... to ...window.... Old names still accepted with a deprecation warning. A nozzle ASCII radial table validation fix and the new LAVAParaviewPlugin.py for ParaView mask visualization apply to both solvers.
Curvilinear solver: New extrapolation order and type options for viscous and inviscid wall boundary conditions.
Cartesian Solver (CART)
- Bug fix: Cart surface time-averaging EMA lost its sample timestamp across restarts, causing an inflated alpha on the first post-restart sample.
prevTimeis now persisted per surface in the restart file. - Bug fix: Positivity-preserving logic for HWCNS interpolation was not applied uniformly across all state components. The scheme now treats all state components equally.
- Bug fix: Multiphase nozzle with
asciiLineReadSpeciesnow requires the largest file mass fraction to matchispecies. - Bug fix: Improved robustness of
multiphaseequilibriumfunctionality for multiphase state input to a wide range of user's state input. - Bug fix: Improved robustness of immersed boundary and adaptive mesh refinement functionality.
- Input rename: AMR error-metric EMA inputs renamed:
errormetricexponentialmovingaveragetimescalectu→errormetricexponentialmovingaveragewindowctu(and...timescale→...windowfor the physical-time variant). Old names deprecated. - The default convective flux function has changed from Rusanov to HLLEC. HLLEC provides better accuracy for low-Mach-number flows while remaining robust for high-speed and shocked flows. Cases that explicitly set
fluxfunctionin their input file are unaffected. - Volume subset output: support for writing subsets of the domain (box type) with independent output intervals per subset.
- Transition sensor overhaul: improved robustness, OpenMP threading, and restart support for the turbulence transition sensor.
- New
wmpartialslipimmersed BC: applies wall-model-driven slip velocity at immersed wall cells, improving consistency with the convective operator. The transition height between slip and no-slip behavior (partialslipheight, in wall units y⁺) is configurable; the default is y⁺ = 100. Adds a newpartialslipsurface output variable (0 = no-slip region, 1 = slip region) and suppressesqdot/turbulencesurface outputs for BC configurations where they are not applicable. - Removed a partial-slip wall BC variant that was not reliable for bodies with thin geometry (e.g. thin fins or plates). The
wmpartialslipBC should be used instead. - New surface output variables
NormalIntoFluidX/Y/Z,Component, andBodyVelocityX/Y/Zare available to help diagnose immersed boundary behavior. These can be added to the surface output variable list in the input file. - The
ducrosandstrainoptions forupwind blending sensorscan be used regardless ofdo viscoussetting.
Unstructured Solver (UNST)
- Bug fix: When time averaging is reset mid-run using
resetTimeAvg, the sample interval timer was not zeroed, causing the first new sample after the reset to carry an incorrect time weight. This is now corrected. - Bug fix: Wall-model turbulence-transition TKE sensor used a numerically unstable variance formula (
E[U²]−E[U]²). Replaced with Welford online variance, eliminating catastrophic cancellation for high mean velocities. - Bug fix: Small cell filtering diagnostic was inconsistent with the CFL calculation, causing unexpectedly small time steps in rare cases.
- Bug fix: Surface output (faces and nodes) is now written in a consistent order regardless of how the mesh is distributed across MPI ranks, ensuring identical surface files when rerunning with a different processor count.
- Bug fix: Problem cell output on abort or startup failed when the number of MPI ranks exceeded the number of problem cells. This is now handled correctly.
- Wall-normal BL probe: line probes now support
wall normal = truemode. Output includes wall shear stress, density, and viscosity at the projected foot for u+/y+ post-processing. - LES Vreman subgrid-scale model now uses anisotropic filter size by default.
- Reduced conservatism in the CFL calculation, yielding larger time steps.
- Surface CGNS output now uses solution linking by default: a single mesh file (
Unst.surf.meshLink.cgns) is written once and each solution file links to it, avoiding redundant geometry data. Disable withsplitgridandsolution = falsein thesurface {}output block. - BC statistics output replaced: per-step ASCII
bc_stats_NNNNNNN.datfiles are replaced by a continuous binarysurface/bc_stats.iterfile (same format asmonitor/unst.data.iter). Asurface/bc_name_map.txtmapping file is written once at startup. Mach-driven pressure history is similarly written tosurface/mach_driven_pressure_BCN.iter. Both files support seamless restart continuation. - When running with implicit time stepping or RANS simulation with the numerical Jacobian selected, Jacobian epsilon now defaults to automatic selection based on the magnitude of the solution vector entries.
- During startup and when the unstructured solver aborts in
robustmode, it now dumps out the problem cells to a CGNS file in the volume output directory with the flow solution. - Surface output is now written in deterministic global id order. Split grid and solution for surface output is now false by default.
Cartesian and Unstructured Solvers (CART/UNST)
- Bug fix: Nozzle ASCII radial table length must match
asciiLineTimeStart/Stop/Skipandnumberofradialpoints. - Input rename: Exponential moving average (EMA) time-averaging inputs renamed:
exponentialmovingaveragetimescalectu→exponentialmovingaveragewindowctu(physical-time variant:exponentialmovingaveragetimescale→exponentialmovingaveragewindow). Old names still accepted with a deprecation warning. - Added
LAVAParaviewPlugin.py(inbin/) with Process Cart Mask and Process Unst Mask filters for extracting individual bit flags from LAVA cell mask arrays in ParaView.
Curvilinear Solver (CURV)
- Bug fix: Fixed bug in restart file reading field mapping between variables available in restart file and those required for restart and read into tile. Fixed bug in unsteady simulation restarts using the SAsLM2015 correlation-based turbulence transition model.
- Add normal momentum and constant entropy extrapolation options for
BCWallInviscid,BCWallViscous, andBCWallViscousIsothermalwalls when using a wall model. - Add linear extrapolation option for
BCExtrapolateboundaries. - Add extrapolation order options for
BCWallInviscid,BCWallViscous, andBCWallViscousIsothermalwalls when using a wall model. Maintains backward compatibility withwallModelOrder.
Tools (TOOLS)
- Bug fix: Fixed broken symlinks for some mesh utility tools that were pointing to non-existent binaries.
1.0.0 (2026/03/19)
First public release of LAVA
Our Team
LAVA is developed by a team of NASA civil servants and contractors within the Computational Aerosciences Branch at NASA Ames Research Center.
LAVA Leadership
Jared Duensing
LAVA Team Lead
Jeff Housman
Curvilinear Lead
Emre Sozer
Unstructured Lead
Mike Barad
Cartesian Lead
Gerrit-Daniel Stich
Contractor Lead
LAVA Development Team
Alexander Aghili
Josh Anibal
Chase Ashby
Francois Cadieux
Timothy Chau
Chris DeGrendele
Ercan Dumlupinar
Luis Fernandes
James Jensen
James Koch
Brandon Lowe
Nguyen Ly
Olivia Martin
David Craig Penner
Kiran Ravikumar
Bram Rodgers
Victor Sousa
Acknowledgments
The development and continued progress of LAVA has been made possible through the generous funding and support of multiple NASA programs and projects across the agency. We are deeply grateful to the following mission directorates and their associated programs and projects. We are also grateful to the predecessor projects and programs whose early investments laid the foundation for the LAVA framework. Their sustained commitment to computational fluid dynamics research made LAVA possible.
NASA Program Support
Computational Resources
We gratefully acknowledge the NASA Advanced Supercomputing (NAS) Division at NASA Ames Research Center for providing the world-class computational resources that make large-scale LAVA simulations possible and facilitate our development. Through the High End Computing Capability (HECC) program, NAS provides access to state-of-the-art supercomputing systems, mass storage, high-speed networking, and expert IT support that are essential to the continued development, testing, and application of LAVA.
Collaborators
We gratefully acknowledge NVIDIA for their continued support of the LAVA framework through close collaboration, technical guidance, and support for GPU-accelerated development. Access to modern GPU architectures, development tools, and performance engineering expertise has been instrumental in advancing LAVA’s capabilities on heterogeneous computing platforms and in enabling efficient porting and optimization of key solver components.
We gratefully acknowledge the following individuals for their ongoing contributions to the development and advancement of the LAVA framework:
David Appelhans
NVIDIA Dev Tech
Lucas Erlandson
NVIDIA Dev Tech
Kyle Rollins
NAS IT Support
Tim Sandstrom
NAS Visualization
Ingo Wald
NVIDIA Ray Tracing
We also thank our early alpha testers and initial users, whose feedback and real-world use have been invaluable in helping shape and mature the initial release of LAVA:
Michael Harris
NASA KSC
Brian Heberling
NASA GRC
Kristopher Pierson
NASA GRC
Derek Dalle
NASA ARC
Former LAVA Software Contributors
- Jordan Angel
- Christoph Brehm
- Jonathan Boustani
- Oliver Browne
- Aditya Ghate
- Ryan Hass
- Gaetan Kenway
- Cetin Kiris
- Daniel Maldonado
- Scott Neuhoff
- Michael Piotrowski
- Kumar Saurabh
- Jacob Wagner
- Man-Long Wong
We also gratefully acknowledge the many interns, visiting researchers, and other contributors not individually listed here whose work on predecessor versions of LAVA, as well as on components of the current LAVA framework, helped make the public release of LAVA possible.
Legal Disclaimer
Copyright Notice
Launch Ascent And Vehicle Aerodynamics (LAVA)
Copyright © 2026 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.
Notices
LAVA is provided as a research-oriented computational framework without any express or implied warranties. The accuracy, reliability, and applicability of results generated by LAVA—including all solvers, modules, and post-processing tools—depend on the user's modeling choices, input data, and verification efforts.
By using this software, you acknowledge that you are solely responsible for validating results and ensuring their suitability for your intended purpose. NASA, the LAVA development team, and all contributors or distributing parties assume no liability for any outcomes, damages, or losses arising from the use or misuse of this software.
See the related Software Usage Agreement/License for additional disclaimer, waiver and other liability provisions that apply to the software.
This software may only be used, reproduced, and provided to others as permitted under the terms of the agreement under which it was acquired from the U.S. Government. Otherwise, this software may not be redistributed, shared, or transferred to any unauthorized third parties without explicit permission from the appropriate NASA authorities. Neither title to, nor ownership of, the software is hereby transferred. This notice shall remain on all copies of the software.
Disclaimers
THE SOFTWARE AND/OR TECHNICAL DATA ARE PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SOFTWARE AND/OR TECHNICAL DATA WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SOFTWARE AND/OR TECHNICAL DATA WILL BE ERROR FREE, OR ANY WARRANTY THAT TECHNICAL DATA, IF PROVIDED, WILL CONFORM TO THE SOFTWARE. IN NO EVENT SHALL THE UNITED STATES GOVERNMENT, OR ITS CONTRACTORS OR SUBCONTRACTORS, BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY CONNECTED WITH THIS SOFTWARE AND/OR TECHNICAL DATA, WHETHER OR NOT BASED UPON WARRANTY, CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE AND/OR TECHNICAL DATA.
THE UNITED STATES GOVERNMENT DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD PARTY COMPUTER SOFTWARE, DATA, OR DOCUMENTATION, IF SAID THIRD PARTY COMPUTER SOFTWARE, DATA, OR DOCUMENTATION IS PRESENT IN THE NASA SOFTWARE AND/OR TECHNICAL DATA, AND DISTRIBUTES IT "AS IS."
RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT AND ITS CONTRACTORS AND SUBCONTRACTORS, AND SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT AND ITS CONTRACTORS AND SUBCONTRACTORS FOR ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES THAT MAY ARISE FROM RECIPIENT'S USE OF THE SOFTWARE AND/OR TECHNICAL DATA, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, THE USE THEREOF.
IF RECIPIENT FURTHER RELEASES OR DISTRIBUTES THE NASA SOFTWARE AND/OR TECHNICAL DATA, RECIPIENT AGREES TO OBTAIN THIS IDENTICAL WAIVER OF CLAIMS, INDEMNIFICATION AND HOLD HARMLESS AGREEMENT WITH ANY ENTITIES THAT ARE PROVIDED WITH THE SOFTWARE AND/OR TECHNICAL DATA.
Third-Party Software
LAVA includes the following third-party software components:
1. BVH
Copyright © 2022 Arsène Pérard-Gayot MIT License https://github.com/madmann91/bvh/blob/master/LICENSE.txt
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2. kdtree
Copyright © 2007-2011 John Tsiombikas nuclear@member.fsf.org BSD License https://github.com/jtsiomb/kdtree?tab=License-1-ov-file#readme
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3. libyaml
Copyright © 2017-2020 Ingy döt Net Copyright © 2006-2016 Kirill Simonov MIT License https://github.com/yaml/libyaml/tree/master?tab=MIT-1-ov-file#readme
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
4. Geogram
Copyright © 2000-2022 Inria All rights reserved. BSD License https://github.com/BrunoLevy/geogram?tab=License-1-ov-file#readme
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Inria nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5. yaml-cpp
Copyright © 2008-2015 Jesse Beder MIT License https://github.com/jbeder/yaml-cpp?tab=MIT-1-ov-file#readme
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
6. Pyoptsparse
LAVA uses Pyoptsparse, a third-party library licensed under LGPL License 3.0.
For the complete text of the GNU Lesser General Public License v3.0 and GNU General Public License v3.0, please visit: - LGPL v3: https://www.gnu.org/licenses/lgpl-3.0.html - GPL v3: https://www.gnu.org/licenses/gpl-3.0.html
7. Intel MKL
The LAVA executables compiled with Intel compilers statically link MKL which is distributed under the Intel Simplified Software License (Version October 2022)
PIN: Copyright (C) Intel Corporation
Use and Redistribution. You may use and redistribute the software, which is provided in binary form only, (the "Software"), without modification, provided the following conditions are met:
- Redistributions must reproduce the above copyright notice and these terms of use in the Software and in the documentation and/or other materials provided with the distribution.
- Neither the name of Intel nor the names of its suppliers may be used to endorse or promote products derived from this Software without specific prior written permission.
- No reverse engineering, decompilation, or disassembly of the Software is permitted, nor any modification or alteration of the Software or its operation at any time, including during execution.
No other licenses. Except as provided in the preceding section, Intel grants no licenses or other rights by implication, estoppel or otherwise to, patent, copyright, trademark, trade name, service mark or other intellectual property licenses or rights of Intel.
Third party software. "Third Party Software" means the files (if any) listed in the "third-party-software.txt" or other similarly-named text file that may be included with the Software. Third Party Software, even if included with the distribution of the Software, may be governed by separate license terms, including without limitation, third party license terms, open source software notices and terms, and/or other Intel software license terms. These separate license terms solely govern Your use of the Third Party Software.
DISCLAIMER. THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED. THIS SOFTWARE IS NOT INTENDED FOR USE IN SYSTEMS OR APPLICATIONS WHERE FAILURE OF THE SOFTWARE MAY CAUSE PERSONAL INJURY OR DEATH AND YOU AGREE THAT YOU ARE FULLY RESPONSIBLE FOR ANY CLAIMS, COSTS, DAMAGES, EXPENSES, AND ATTORNEYS' FEES ARISING OUT OF ANY SUCH USE, EVEN IF ANY CLAIM ALLEGES THAT INTEL WAS NEGLIGENT REGARDING THE DESIGN OR MANUFACTURE OF THE SOFTWARE.
LIMITATION OF LIABILITY. IN NO EVENT WILL INTEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
No support. Intel may make changes to the Software, at any time without notice, and is not obligated to support, update or provide training for the Software.
Termination. Your right to use the Software is terminated in the event of your breach of this license.
Feedback. Should you provide Intel with comments, modifications, corrections, enhancements or other input ("Feedback") related to the Software, Intel will be free to use, disclose, reproduce, license or otherwise distribute or exploit the Feedback in its sole discretion without any obligations or restrictions of any kind, including without limitation, intellectual property rights or licensing obligations.
Compliance with laws. You agree to comply with all relevant laws and regulations governing your use, transfer, import or export (or prohibition thereof) of the Software.
Governing law. All disputes will be governed by the laws of the United States of America and the State of Delaware without reference to conflict of law principles and subject to the exclusive jurisdiction of the state or federal courts sitting in the State of Delaware, and each party agrees that it submits to the personal jurisdiction and venue of those courts and waives any objections. THE UNITED NATIONS CONVENTION ON CONTRACTS FOR THE INTERNATIONAL SALE OF GOODS (1980) IS SPECIFICALLY EXCLUDED AND WILL NOT APPLY TO THE SOFTWARE.
8. Intel runtime libraries
The LAVA executables compiled with Intel compilers statically link the Intel runtime libraries - Intel® Fortran Core Library (libifcoremt) - Intel® Math Library (libimf) - Intel® OpenMP Runtime Library (libiomp5) - Intel® Runtime Core Library (libirc) - Intel® Random Number Generator Library (libirng) - Intel® Short Vector Math Library (libsvml)
These components are Copyright © 2026 Intel Corporation. All rights reserved.
These libraries are provided by Intel Corporation under the "Intel End User License Agreement for Developer Tools." Redistribution and use in binary form, without modification, are permitted provided that the following conditions are met:
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
- No reverse engineering, decompilation, or disassembly of these libraries is permitted.
- Neither the name of Intel Corporation nor the names of its suppliers may be used to endorse or promote products derived from this software without specific prior written permission.
DISCLAIMER: THIS SOFTWARE IS PROVIDED BY INTEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Setup and Utilities
LAVA Access Guide
LAVA is released through the NASA Software Catalog.
LAVA
- NAS Users (Module-Based Access): If you have access to NASA Advanced Supercomputing (NAS) systems and want to run LAVA there, use the module system.
- External Users (Tarball Installation): If you would like to run LAVA on your own system, AWS or other cloud services, download pre-compiled binaries and install LAVA locally.
LAVA Voronoi
LAVA Voronoi is a specialized mesh generation tool that creates polyhedral-cell tessellations for two- and three-dimensional computational domains. It is released along with LAVA through the NASA Software Catalog.
- NAS Users (Module-Based Access): If you have access to NASA Advanced Supercomputing (NAS) systems and want to run LAVA there, use the module system.
- External Users (Tarball Installation): If you would like to run Voronoi mesher on your own system, AWS or other cloud services, download pre-compiled binaries and install locally.
Executables
- LAVA: See the full list of supported executables here.
- LAVA Voronoi:
lavavoro.AVX2(hybrid MPI+OpenMP, AVX2-optimized for x86_64 CPUs).
LAVA on NAS
See LAVA on NAS for platform-specific notes and recommendations.
Getting Help
- Documentation: LAVA Documentation
- Contact and LAVA User Community: Contact Us
- NAS System Support: For NAS-specific issues, contact NAS User Services
LAVA Access for NAS Users
If you have access to NASA Advanced Supercomputing (NAS) systems with compute time allocations, a valid Software User Agreement, and want to run LAVA on NAS, submit a NAMS request on IdMax (Launch, Ascent, and Vehicle Aerodynamics (LAVA) Computational Fluid Dynamics (CFD) Access on NAS). Once approved, you can use the module system described below.
Please note the LAVA development team does not have the authority to grant access or issue computer time on NAS systems. You may visit the following page for instructions on how to request NAS computer resources and to see if you qualify.
If you are an external user, go to External Users (Tarball Installation).
Setup Instructions
-
Add the LAVA module path:
Warning
If you use
--appendin the above command, you might not end up loading the right module below. Please make sure to prepend or use the above command as is to avoid conflicts with other modules. -
View available LAVA versions:
-
Load the LAVA module:
Tip
The above will give you access to the latest version of LAVA release. You can also choose to load a specific version of LAVA using
module load LAVA/<version> -
Start using LAVA:
The module automatically:
- Detects your current system (Aitken, Electra, Athena, Cabeus A100, Cabeus Grace Hopper etc.)
- Loads the appropriate compiler and MPI environment
- Adds the correct LAVA executables to your
PATH - Sets necessary environment variables
Sample PBS scripts to run on NAS
For example PBS scripts and NAS runtime guidance, see Running LAVA on NAS.
Troubleshooting
Module LAVA not found
Solution: Ensure you've added the module path: module use /swbuild/LAVA/LAVA_modules
Wrong architecture executable selected
Solution: The module should auto-detect your system. If issues persist, contact LAVA support.
Module conflicts when loading LAVA on Athena (e.g., PrgEnv-intel conflicts with PrgEnv-cray)
Solution: Run module purge to clear all loaded modules, then load LAVA again:
Permission denied errors when loading LAVA_deps (e.g., ERROR: Permission denied on '/nasa/modulefiles/toss4/cmake')
Loading LAVA_deps/rome_old
Module ERROR: no such variable
(read trace on "::env(LAVA_REPO_DIR)")
invoked from within
"set base $::env(LAVA_REPO_DIR)"
(file "/swbuild/LAVA/LAVA_GROUP/LAVA_modules/LAVA_deps/rome_old" line 14)
Please contact <root@localhost>
Loading LAVA_voro/dev
ERROR: Load of requirement 'LAVA_deps' failed
No Modulefiles Currently Loaded.
/swbuild/LAVA/LAVA_GROUP/LAVA_modules/). Ensure that you are prepending the recommended path:
or use the --prepend option on newer TCL module version systems.
Make sure to also check your .bashrc or .profile and remove (or comment) other conflicting module paths like module use -a /swbuild/LAVA/LAVA_GROUP/LAVA_modules.
Module loading errors on Athena
Loading PrgEnv-intel/8.6.0
ERROR: Module cannot be loaded due to a conflict.
HINT: Might try "module unload PrgEnv-cray" first.
Loading LAVA_deps/intel
ERROR: Load of requirement PrgEnv-intel failed
/usr/local/lib/init/global.profile can cause conflicts with LAVA modules. Add this safeguard to your .bashrc or .profile to prevent loading it on Athena:
if [[ $(hostname) != athfe* ]] && [[ $(hostname) != x100* ]] && [ -e /usr/local/lib/init/global.profile ]; then
. /usr/local/lib/init/global.profile
fi
if [ -f /opt/cray/pe/modules/default/init/bash ]; then
source /opt/cray/pe/modules/default/init/bash
else
source /usr/local/lib/global.profile
fi
.bashrc or .profile, start a new terminal session, then try loading the module again. Refer to the following for more details.
Executable not found or module loading errors in PBS jobs on Athena
mbind.x: execvp: lavaunst.3D.NS1.AVX512: No such file or directory
x1000c0s4b0n1.hsn.ath.nas.nasa.gov: rank 0 exited with code 255
Loading craype/2.7.35
ERROR: Conflicting PrgEnv-intel/8.6.0 is loading
Loading PrgEnv-intel/8.6.0
ERROR: Requirement craype is not loaded
source ~/.bashrc at the beginning of your PBS script after the PBS directives and before loading LAVA modules:
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_turin_job
#PBS -q normal
#PBS -l select=16:ncpus=512:mpiprocs=4:model=tur_ath
#PBS -l walltime=04:00:00
#PBS -j oe
#PBS -r n
# Source your bashrc to initialize the environment properly
source ~/.bashrc
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA/v1.0.0
# ... rest of your script
.bashrc settings (including the Athena-specific global profile exclusion) are applied in the PBS job environment. See the NAS Athena documentation for more details.
Module loading fails due to NFS group limitations (Error: "Permission denied" or modules not loading)
Solution: If you are a member of many Unix groups (more than 16), you may encounter NFS filesystem limitations where only the first 16 groups are loaded, potentially causing access issues to LAVA modules and dependencies.
Symptoms:
- Module loading works on some systems but not others
- Inconsistent behavior across different frontends
- Permission denied errors when accessing module files
Workaround: Use the newgrp command to ensure you're logged into the correct group before loading LAVA:
newgrp <your_group> # e.g., newgrp n1546
module use /swbuild/LAVA/LAVA_modules
module load LAVA/<version>
groups or id -Gn. Contact your system administrator if you need help determining the correct group to use.
md5sum error when running LAVA executables (Error: md5.c line 18: cannot open file)
Cannot find executable mbind.x
- All systems except GH:
- GH systems:
LAVA Access validation failed
[I] Using access file: /path/to/access/file
[E] (Rank=00000) LAVA Access validation failed.
Reason: User '<userid>' not authorized for this license
unset LAVA_ACCESS_FILE.
LAVA Installation for External Users
If you do not have NAS system access, install LAVA using the pre-compiled tarballs from the NASA Software Catalog.
If you are a NAS user, go to NAS Users (Module-Based Access).
Acquiring LAVA
Download the appropriate tarball for your system from the NASA Software Catalog. Tarballs are named using the following convention:
Example: LAVA_v1.1.0_nvidia_openmpi_x86_64_2026.11.06.tar.gz
Version numbers follow the format [MAJOR].[MINOR].[PATCH].
Available Build Configurations
LAVA provides four pre-built configurations optimized for different hardware platforms:
| Tarball Name | Compiler | MPI | Architecture | Target Systems |
|---|---|---|---|---|
LAVA_*_nvidia_openmpi_x86_64_*.tar.gz |
NVHPC 25.3 | OpenMPI 4.1.6 | x86_64 (AVX2) | NVIDIA A100 GPUs, RTX 5090, RTX 4090 |
LAVA_*_nvidia_hpcx_aarch64_*.tar.gz |
NVHPC 25.3 | HPC-X | aarch64 (ARM) | NVIDIA GH200 (Grace-Hopper) |
LAVA_*_intel_openmpi_x86_64_*.tar.gz |
Intel 2023.2.1 | OpenMPI 4.1.5 | x86_64 (AVX2 & AVX512) | Intel/AMD CPUs (Haswell, Skylake, Rome, Milan, Genoa) |
LAVA_*_intel_cray-mpich_x86_64_*.tar.gz |
Intel 2023.2.1 | Cray-MPICH | x86_64 (AVX512) | AMD Turin (Zen 5) |
Note
Companies in tarball names above were not involved in generating the LAVA binaries. They only convey compiler information.
Tip
While the Intel and Nvidia binaries were compiled with compiler versions that are older than the most recent available compilers, at runtime the user can choose to use the latest Intel or Nvidia runtime and the binaries should be compatible.
Which Tarball to Download
GPU Systems
| Your Hardware | Minimum Compute Capability Supported | Recommended Tarball |
|---|---|---|
| NVIDIA A100, RTX 5090, RTX 4090 (x86_64 systems) | SM 8.0+ | LAVA_*_nvidia_openmpi_x86_64_*.tar.gz |
| NVIDIA V100 (x86_64 systems) | SM 7.0 (single-species PTX70 executables only) |
LAVA_*_nvidia_openmpi_x86_64_*.tar.gz |
| NVIDIA GH200 (Grace-Hopper ARM systems) | SM 9.0+ | LAVA_*_nvidia_hpcx_aarch64_*.tar.gz |
CPU-Only Systems (Intel/AMD)
| Your CPU | Instruction Set Support | Recommended Tarball |
|---|---|---|
| Intel Haswell, Broadwell, Skylake (non-X) AMD Zen, Zen 2, Zen 3, Zen 4 (Rome, Milan, Genoa) |
AVX2 | LAVA_*_intel_openmpi_x86_64_*.tar.gz(use AVX2 executables) |
| Intel Skylake-X, Cascade Lake, Ice Lake, Sapphire Rapids AMD Zen 5 (Turin) |
AVX512 | LAVA_*_intel_openmpi_x86_64_*.tar.gz(use AVX512 executables) or LAVA_*_intel_cray-mpich_x86_64_*.tar.gz |
Note
The intel_openmpi_x86_64 tarball includes both AVX2 and AVX512 executables with double and single precision variants. Use AVX2 versions for broader compatibility if unsure of your CPU capabilities.
Note
LAVA and its tools require CPUs with AVX2 instruction set at a minimum.
Installation Steps
Extract the tarball
tar -xzf LAVA_<version>_<compiler>_<mpi>_<arch>_<DateStamp>.tar.gz
cd LAVA_<version>_<compiler>_<mpi>_<arch>_<DateStamp>
The extracted directory contains:
bin/- All LAVA executables and utility scriptslib/- Curvilinear libraries and Python packages (Intel builds only)species/- Species database files
Set up your environment
Load the required modules and set environment variables like LD_LIBRARY_PATH based on your configuration.
Environment Setup for NVIDIA + OpenMPI (x86_64 GPU Systems)
Tarball: LAVA_*_nvidia_openmpi_x86_64_*.tar.gz
Required Software
- OpenMPI 4.1.6 or later
- NVIDIA GPU driver version 570.26 or later (required for CUDA 12.8 support)
- See NVIDIA CUDA-Driver Compatibility for driver requirements
- NVIDIA runtime libraries (any version compatible with CUDA 12.8+)
Note
This tarball was compiled with NVHPC 25.3, but you can use newer NVHPC versions (e.g., 25.11 or later) at runtime. The NVHPC runtime libraries are backward compatible.
Environment Setup:
# If using modules (recommended)
module load nvhpc/25.11
module load openmpi/4.1.6
# Set LAVA necessary env variables
export LAVA_INSTALL_DIR=/path/to/LAVA/install
export LAVA_OUTPUT_INTERVAL=1000000
# Add LAVA binaries to PATH
export PATH=/path/to/LAVA/bin:${PATH}
# If NOT using modules, manually set LD_LIBRARY_PATH
# The following paths are required (adjust versions/paths for your installation):
export LD_LIBRARY_PATH=\
/path/to/nvhpc/compilers/lib:\
/path/to/nvhpc/cuda/lib64:\
/path/to/nvhpc/math_libs/lib64:\
/path/to/openmpi/lib:\
${LD_LIBRARY_PATH}
# Example for a typical NVHPC 25.3 installation:
# export LD_LIBRARY_PATH=\
# /opt/nvidia/hpc_sdk/Linux_x86_64/25.3/compilers/lib:\
# /opt/nvidia/hpc_sdk/Linux_x86_64/25.3/cuda/lib64:\
# /opt/nvidia/hpc_sdk/Linux_x86_64/25.3/math_libs/12.8/lib64:\
# /opt/openmpi/4.1.6/lib:\
# ${LD_LIBRARY_PATH}
Required Runtime Libraries
The LAVA executable depends on the following dynamic libraries:
- NVHPC Compiler Libraries:
libcudafor.so,libcudafor_120.so,libnvf.so,libaccdevice.so,libacchost.so,libaccdevaux.so,libnvomp.so,libnvhpcatm.so,libnvc.so,libnvcpumath.so,libnvcpumath-avx2.so,libcudadevice.so,libcudanvhpc.so - CUDA Runtime:
libcudart.so.12 - Curvilinear solver and grid tools only:
libcudafor_128.so,libcudafor2.so,libcudaforwrapblas.so,libcudaforwrapblas117.so,libnvhpcwrapnvtx.so(NVHPCcompilers/lib);libcublas.so.12,libcublasLt.so.12,libcurand.so.10(NVHPCmath_libs/<cuda version>/lib64) - OpenMPI Libraries:
libmpi.so.40,libmpi_mpifh.so.40,libmpi_usempif08.so.40,libmpi_usempi_ignore_tkr.so.40 - System Libraries:
libz.so.1,librt.so.1,libdl.so.2,libstdc++.so.6,libpthread.so.0,libc.so.6,ld-linux-x86-64.so.2,libgcc_s.so.1,libm.so.6
Verifying Your Setup:
# Check if all dependencies are resolved
ldd /path/to/LAVA/bin/lavacart.3D.NS1
# All libraries should show resolved paths (no "not found")
# If you see "not found", ensure the corresponding library path is in LD_LIBRARY_PATH
Environment Setup for NVIDIA + HPC-X (aarch64 GPU Systems)
Tarball: LAVA_*_nvidia_hpcx_aarch64_*.tar.gz
Required Software
- HPC-X MPI (bundled with NVHPC or standalone)
- NVIDIA GPU driver version 570.26 or later (required for CUDA 12.8 support)
- See NVIDIA CUDA-Driver Compatibility for driver requirements
- NVHPC runtime libraries (any version compatible with CUDA 12.8+)
Note
This tarball was compiled with NVHPC 25.3, but you can use newer NVHPC versions (e.g., 25.11 or later) at runtime. The NVHPC runtime libraries are backward compatible.
Environment Setup:
# If using modules (recommended)
module load nvhpc-hpcx-cuda12/25.7
# Set LAVA necessary env variables
export LAVA_INSTALL_DIR=/path/to/LAVA/install
export LAVA_OUTPUT_INTERVAL=1000000
# Add LAVA binaries to PATH
export PATH=/path/to/LAVA/bin:${PATH}
# If NOT using modules, manually set LD_LIBRARY_PATH
# The following paths are required (adjust versions/paths for your installation):
export LD_LIBRARY_PATH=\
/path/to/nvhpc/compilers/lib:\
/path/to/nvhpc/cuda/lib64:\
/path/to/nvhpc/math_libs/lib64:\
/path/to/nvhpc/comm_libs/12.8/hpcx/hpcx-2.22.1/ompi/lib:\
${LD_LIBRARY_PATH}
# Example for a typical NVHPC 25.3 ARM installation:
# export LD_LIBRARY_PATH=\
# /opt/nvidia/hpc_sdk/Linux_aarch64/25.3/compilers/lib:\
# /opt/nvidia/hpc_sdk/Linux_aarch64/25.3/cuda/lib64:\
# /opt/nvidia/hpc_sdk/Linux_aarch64/25.3/math_libs/12.8/lib64:\
# /opt/nvidia/hpc_sdk/Linux_aarch64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ompi/lib:\
# ${LD_LIBRARY_PATH}
Required Runtime Libraries
The LAVA executable depends on the following dynamic libraries:
- NVHPC Compiler Libraries:
libcudafor.so,libcudafor_120.so,libnvf.so,libaccdevice.so,libacchost.so,libaccdevaux.so,libnvomp.so,libnvhpcatm.so,libnvc.so,libnvcpumath.so,libnvcpumath-armv8.so,libnvmalloc.so,libcudadevice.so,libcudanvhpc.so - CUDA Runtime:
libcudart.so.12 - Curvilinear solver and grid tools only:
libcudafor_128.so,libcudafor2.so,libcudaforwrapblas.so,libcudaforwrapblas117.so,libnvhpcwrapnvtx.so(NVHPCcompilers/lib);libcublas.so.12,libcublasLt.so.12,libcurand.so.10(NVHPCmath_libs/<cuda version>/lib64) - HPC-X MPI Libraries:
libmpi.so.40,libmpi_mpifh.so.40,libmpi_usempif08.so.40,libmpi_usempi_ignore_tkr.so.40 - System Libraries: Standard Linux libraries (typically in
/usr/lib64or/lib64)
Verifying Your Setup:
# Check if all dependencies are resolved
ldd /path/to/LAVA/bin/lavacart.3D.NS1
# All libraries should show resolved paths (no "not found")
# If you see "not found", ensure the corresponding library path is in LD_LIBRARY_PATH
Environment Setup for Intel + OpenMPI (CPU Systems)
Tarball: LAVA_*_intel_openmpi_x86_64_*.tar.gz
Required Software
- OpenMPI 4.1.5 or later
Environment Setup:
# If using modules (recommended)
module load intel/2022.1.0
module load openmpi/4.1.5
# Set LAVA necessary env variables
export LAVA_INSTALL_DIR=/path/to/LAVA/install
export LAVA_OUTPUT_INTERVAL=1000000
# Add LAVA binaries to PATH
export PATH=/path/to/LAVA/bin:${PATH}
# If NOT using modules, manually set LD_LIBRARY_PATH
# The following paths are required (adjust versions/paths for your installation):
export LD_LIBRARY_PATH=\
/path/to/openmpi/lib:\
${LD_LIBRARY_PATH}
# Example for a typical OpenMPI 4.1.5 installation:
# export LD_LIBRARY_PATH=\
# /opt/openmpi/4.1.5/lib:\
# ${LD_LIBRARY_PATH}
Required Runtime Libraries
The LAVA executable depends on the following dynamic libraries:
- OpenMPI Libraries:
libmpi.so.40,libmpi_usempif08.so.40,libmpi_usempi_ignore_tkr.so.40,libmpi_mpifh.so.40 - System Libraries:
libz.so.1,libdl.so.2,libstdc++.so.6,libm.so.6,libgcc_s.so.1,libpthread.so.0,libc.so.6,ld-linux-x86-64.so.2
Verifying Your Setup:
# Check if all dependencies are resolved (use AVX2 or AVX512 as appropriate)
ldd /path/to/LAVA/bin/lavacart.3D.NS1.AVX2
# or
ldd /path/to/LAVA/bin/lavacart.3D.NS1.AVX512
# All libraries should show resolved paths (no "not found")
# If you see "not found", ensure the corresponding library path is in LD_LIBRARY_PATH
Choosing AVX2 vs AVX512 Executables:
- This tarball includes both AVX2 and AVX512 versions of each executable in double and single precision
- AVX512 executables:
lavaunst.3D.NS1.AVX512,lavaunst.3D.NS1.AVX512.FLOAT - AVX2 executables:
lavacart.3D.NS1.AVX2,lavacart.3D.NS1.AVX2.FLOAT - Use AVX512 versions on supported CPUs for better performance (10-30% faster)
- Use AVX2 versions for broader compatibility
Environment Setup for Intel + Cray-MPICH (Cray/HPE Systems)
Tarball: LAVA_*_intel_cray-mpich_x86_64_*.tar.gz
Required Software
- Cray MPICH (typically on Cray/HPE systems)
Environment Setup:
# If using modules (recommended)
module load intel-classic/2023.2.1
module load PrgEnv-intel
# Set LAVA necessary env variables
export LAVA_INSTALL_DIR=/path/to/LAVA/install
export LAVA_OUTPUT_INTERVAL=1000000
# Add LAVA binaries to PATH
export PATH=/path/to/LAVA/bin:${PATH}
# If NOT using modules, manually set LD_LIBRARY_PATH
# The following paths are required (adjust versions/paths for your installation):
export LD_LIBRARY_PATH=\
/opt/cray/pe/lib64:\
${LD_LIBRARY_PATH}
# Example for a typical Cray MPICH installation:
# export LD_LIBRARY_PATH=\
# /opt/cray/pe/lib64:\
# ${LD_LIBRARY_PATH}
Required Runtime Libraries
The LAVA executable depends on the following dynamic libraries:
- Cray MPI Libraries:
libmpi_intel.so.12,libmpifort_intel.so.12 - System Libraries:
libz.so.1,libstdc++.so.6,libm.so.6,libgcc_s.so.1,libc.so.6,ld-linux-x86-64.so.2
Verifying Your Setup:
# Check if all dependencies are resolved
ldd /path/to/LAVA/bin/lavacart.3D.NS1.AVX512
# All libraries should show resolved paths (no "not found")
# If you see "not found", ensure the corresponding library path is in LD_LIBRARY_PATH
Note: This configuration is optimized for AMD Turin (Zen 5) processors with AVX512 support.
Troubleshooting
error while loading shared libraries: libmpi.so.XX: cannot open shared object file
Solution: Ensure your MPI module is loaded and matches the tarball's MPI version.
Illegal instruction error
Please verify that both the operating system and the processor support Intel(R) X87, CMOV, MMX, FXSAVE, SSE, SSE2, SSE3, SSSE3, SSE4_1, SSE4_2, POPCNT and AVX instructions.
lscpu | grep -i flags. If AVX2 is not available, the CPU is not supported; LAVA requires AVX2 or newer.
CUDA errors on GPU systems
Solution:
- Verify CUDA version compatibility (
nvidia-smi) - Check that
CUDA_HOMEandLD_LIBRARY_PATHare set correctly - Ensure GPU drivers are up to date
Lot of files like lout.*
Solution:
Ensure the environment variable LAVA_OUTPUT_INTERVAL is set to a large value. This controls the rank stride for the lout files.
Using non scheduler aware MPI runtime
Solution: When running with MPI runtime that is not SLURM or PBS aware, you might need to specify additional options like hostfile and pass environment variables through. Please refer to the mpiexec line in the pbs script for GH200 nodes on NAS for reference.
For more troubleshooting tips please refer here.
LAVA Voronoi Access for NAS Users
If you have access to NASA Advanced Supercomputing (NAS) systems with compute time allocations, a valid Software User Agreement, and want to run LAVA Voronoi on NAS, submit a NAMS request on IdMax (Launch, Ascent, and Vehicle Aerodynamics (LAVA) Computational Fluid Dynamics (CFD) Access on NAS). Once approved, you can use the module system described below.
Please note the LAVA development team does not have the authority to grant access or issue computer time on NAS systems. You may visit the following page for instructions on how to request NAS computer resources and to see if you qualify.
If you are an external user, go to External Users (Tarball Installation).
Setup Instructions
-
Add the LAVA Voronoi module path (same as LAVA):
Warning
If you use
--appendin the above command, you might not end up loading the right module below. Please make sure to prepend or use the above command as is to avoid conflicts with other modules. -
View available LAVA Voronoi versions:
-
Load the LAVA Voronoi module:
Tip
The above will give you access to the latest version of LAVA release. You can also choose to load a specific version of LAVA using
module load LAVA_voro/<version> -
Verify installation:
Running LAVA Voronoi
For detailed examples of PBS job submission and execution workflows, see the Example Usage section. Simply replace the module to load with LAVA_voro and the LAVA executable name with lavavoro.AVX2.
Note
Voronoi executables are only available for Athena, Electra and Aitken.
For more details on NAS module usage and troubleshooting, see the NAS Users section in the main installation guide.
Troubleshooting
For troubleshooting tips please refer here.
LAVA Voronoi Installation for External Users
If you do not have NAS system access, install LAVA Voronoi using the pre-compiled tarballs from the NASA Software Catalog.
If you are a NAS user, go to NAS Users (Module-Based Access).
Acquiring LAVA Voronoi
Download the appropriate tarball for your system from the NASA Software Catalog. Tarballs are named using the convention:
Example: LAVAVORO_v1.1.0_intel_openmpi_x86_64_2026.11.04.tar.gz
Available Build Configuration
LAVA Voronoi is currently available in two pre-built configurations:
| Tarball Name | Compiler | MPI | Architecture | Target Systems |
|---|---|---|---|---|
LAVAVORO_*_intel_openmpi_x86_64_*.tar.gz |
Intel 2023.2.1 | OpenMPI 4.1.5 | x86_64 (AVX2) | Intel/AMD CPUs (Broadwell, Skylake, Rome, Milan, Turin, etc.) |
LAVAVORO_*_intel_cray-mpich_x86_64_*.tar.gz |
Intel 2023.2.1 | Cray MPICH 8.1.33 | x86_64 (AVX2) | Intel/AMD CPUs (Broadwell, Skylake, Rome, Milan, Turin, etc.) |
Note
The executable uses AVX2 instructions for broad CPU compatibility across Intel and AMD processors.
Installation Steps
Extract the tarball
tar -xzf LAVAVORO_<version>_intel_openmpi_x86_64_*.tar.gz
cd LAVAVORO_<version>_intel_openmpi_x86_64_<DateStamp>
The extracted directory contains:
- bin/ - LAVA Voronoi executable
Setup your Environment
Load the required modules and set environment variables like LD_LIBRARY_PATH based on your configuration.
Environment Setup for Intel + OpenMPI (x86_64 Systems)
Tarball: LAVAVORO_*_intel_openmpi_x86_64_*.tar.gz
Required Software
- Intel Compiler Suite 2023.2.1 or later
- OpenMPI 4.1.5 or later
Environment Setup:
# If using modules (recommended)
module load intel/2023.2.1
module load openmpi/4.1.5
# Add LAVA Voronoi binary to PATH
export PATH=/path/to/LAVAVORO/bin:${PATH}
For manual setup without modules, see the External Users Setup section in the main installation guide.
Environment Setup for Intel + Cray-MPICH (x86_64 Systems)
Tarball: LAVAVORO_*_intel_cray-mpich_x86_64_*.tar.gz
Required Software
- Intel Compiler Suite 2023.2.1 or later
- Cray MPICH
Environment Setup:
# If using modules (recommended)
module load intel/2023.2.1
module load cray-mpich
# Add LAVA Voronoi binary to PATH
export PATH=/path/to/LAVAVORO/bin:${PATH}
For manual setup without modules, see the External Users Setup section in the main installation guide.
Verify installation
All libraries should show resolved paths (no "not found").Troubleshooting
For troubleshooting tips please refer here.
Available Executables
Each LAVA distribution contains multiple executables for different physics configurations. The executables are organized by solver type (Cartesian, Curvilinear, Unstructured) with varying numbers of species and multiphase capabilities.
Naming Convention
LAVA executables follow this naming pattern:
<solver>:cart(Cartesian),curv(Curvilinear), orunst(Unstructured)<dim>:2Dor3D(two-dimensional only in Cartesian)<species>:NS1,NS2,NS3,NS4,NS5(number of species)<options>:MP(multiphase, when applicable)<arch>:AVX2orAVX512(CPU executables only; omitted for GPU)<precision>:DOUBLEorFLOAT(optional; defaults to DOUBLE)
Examples:
lavacart.3D.NS1- Cartesian solver, 1 species, double precision, GPUlavacart.3D.NS1.FLOAT- Cartesian solver, 1 species, single precision, GPUlavacart.3D.NS1.AVX2- Cartesian solver, 1 species, double precision, CPU with AVX2lavaunst.3D.NS3.AVX512- Unstructured solver, 3 species, double precision, CPU with AVX512
Executable Selection Guide
For GPU Systems
| System Architecture | GPU Support | Recommended Tarball | Example |
|---|---|---|---|
| x86_64 | CUDA Compute 8.0+ (Ampere A100, Ada RTX 5090/4090, Blackwell, and newer) |
LAVA_*_nvidia_openmpi_x86_64_*.tar.gz |
lavacart.3D.NS1 |
| x86_64 | CUDA Compute 7.0 (Volta V100; single-species only, see V100 executables) |
LAVA_*_nvidia_openmpi_x86_64_*.tar.gz |
lava.3D.NS1.NVIDIA.PTX70.OPENMPI |
| ARM | CUDA Compute 9.0+ (Hopper GH200, H100/H200, and newer) |
LAVA_*_nvidia_hpcx_aarch64_*.tar.gz |
lavacart.3D.NS1 |
For CPU-Only Systems
| Instruction Set | CPU Support | Recommended Tarball | Example |
|---|---|---|---|
| AVX2 | Intel: Haswell, Broadwell, Skylake (non-X) AMD: Zen, Zen 2, Zen 3 (Rome, Milan, Genoa) |
LAVA_*_intel_openmpi_x86_64_*.tar.gz |
lavacart.3D.NS1.AVX2 |
| AVX512 | Intel: Skylake-X, Cascade Lake, Ice Lake, Sapphire Rapids AMD: Zen 5 (Turin) |
LAVA_*_intel_openmpi_x86_64_*.tar.gzor LAVA_*_intel_cray-mpich_x86_64_*.tar.gz |
lavacart.3D.NS1.AVX512 |
Choosing the Right Instruction Set
- AVX512: Use on supported CPUs for best performance
- AVX2: Use for broader compatibility or when AVX512 is not available
- Check your CPU capabilities:
lscpu | grep -i flags(look foravx2oravx512)
Precision Selection
- Double Precision (default): Higher accuracy
- Use executables without precision suffix
-
Example:
lavacart.3D.NS1 -
Single Precision: faster runtime, uses less memory
- Use executables with
.FLOATsuffix - Example:
lavacart.3D.NS1.FLOAT - Not available for the multiphase (
.MP) GPU executables or the Curvilinear solver
Single Precision Validation Required
Single precision may not be suitable for all applications. Users must perform their own testing and validation to verify that .FLOAT executables produce acceptable numerical accuracy for their specific simulation. Compare results against double precision runs to assess solution quality.
Species Selection
Choose the executable based on your application:
- NS1: Single-species
- NS2: Two-species
- NS3: Three-species (can be with or without multiphase (
.MPsuffix required)) - NS4: Four-species with multiphase (requires
.MPsuffix) - NS5: Five-species with multiphase (requires
.MPsuffix)
Note
Higher species counts increase computational cost. Use the executable that best matches your requirements.
Additional Tools
For detailed information regarding supporting tools, please refer to the following documentation.
GPU Executables (NVIDIA Builds)
GPU executables are available in the LAVA_*_nvidia_openmpi_x86_64_*.tar.gz (for x86_64 systems) and LAVA_*_nvidia_hpcx_aarch64_*.tar.gz (for ARM systems) tarballs. GPU executables are ptx-based binaries that support multiple GPU architectures.
V100 (Volta) executables: v1.1.0 only
The default GPU executables require CUDA Compute 8.0+. For NVIDIA V100 (Volta, CUDA Compute 7.0) GPUs, the v1.1.0 LAVA_*_nvidia_openmpi_x86_64_*.tar.gz tarball also includes single-species executables with PTX70 in the name:
| Executable Name | Solver | Dimension | Precision |
|---|---|---|---|
lava.3D.NS1.NVIDIA.PTX70.OPENMPI |
Cartesian and Unstructured | 3 | Double |
lava.3D.NS1.NVIDIA.PTX70.OPENMPI.FLOAT |
Cartesian | 3 | Single |
lava.2D.NS1.NVIDIA.PTX70.OPENMPI |
Cartesian | 2 | Double |
lava.2D.NS1.NVIDIA.PTX70.OPENMPI.FLOAT |
Cartesian | 2 | Single |
lavacurv.3D.NS1.NVIDIA.PTX70.OPENMPI |
Curvilinear | 3 | Double |
There are no lavacart/lavaunst names for these; run the executable directly with your input file, which selects the solver. CUDA 13 removes offline compilation support for Volta, so releases built with CUDA 13 will not include V100 executables.
Cartesian Solver (lavacart) - GPU
| Executable Name | Dimension | Species | Multiphase | Precision |
|---|---|---|---|---|
lavacart.3D.NS1 |
3 | 1 | No | Double |
lavacart.3D.NS1.FLOAT |
3 | 1 | No | Single |
lavacart.3D.NS2 |
3 | 2 | No | Double |
lavacart.3D.NS2.FLOAT |
3 | 2 | No | Single |
lavacart.3D.NS3 |
3 | 3 | No | Double |
lavacart.3D.NS3.FLOAT |
3 | 3 | No | Single |
lavacart.3D.NS3.MP |
3 | 3 | Yes | Double |
lavacart.3D.NS4.MP |
3 | 4 | Yes | Double |
lavacart.3D.NS5.MP |
3 | 5 | Yes | Double |
lavacart.2D.NS1 |
2 | 1 | No | Double |
lavacart.2D.NS1.FLOAT |
2 | 1 | No | Single |
Curvilinear Solver (lavacurv) - GPU
| Executable Name | Species | Multiphase | Precision |
|---|---|---|---|
lavacurv.3D.NS1 |
1 | No | Double |
Unstructured Solver (lavaunst) - GPU
| Executable Name | Species | Multiphase | Precision |
|---|---|---|---|
lavaunst.3D.NS1 |
1 | No | Double |
lavaunst.3D.NS1.FLOAT |
1 | No | Single |
lavaunst.3D.NS2 |
2 | No | Double |
lavaunst.3D.NS2.FLOAT |
2 | No | Single |
lavaunst.3D.NS3 |
3 | No | Double |
lavaunst.3D.NS3.FLOAT |
3 | No | Single |
CPU Executables (Intel Builds)
CPU executables are available in Intel compiler tarballs: LAVA_*_intel_openmpi_x86_64_*.tar.gz and LAVA_*_intel_cray-mpich_x86_64_*.tar.gz.
Intel + OpenMPI (x86_64)
Available in LAVA_*_intel_openmpi_x86_64_*.tar.gz
This tarball includes both AVX2 and AVX512 executables with double and single precision variants.
Cartesian Solver (lavacart) - CPU
| Executable Name | Dimension | Species | Multiphase | Precision | Architecture |
|---|---|---|---|---|---|
lavacart.3D.NS1.AVX2 |
3 | 1 | No | Double | AVX2 |
lavacart.3D.NS1.AVX2.FLOAT |
3 | 1 | No | Single | AVX2 |
lavacart.3D.NS1.AVX512 |
3 | 1 | No | Double | AVX512 |
lavacart.3D.NS1.AVX512.FLOAT |
3 | 1 | No | Single | AVX512 |
lavacart.3D.NS2.AVX2 |
3 | 2 | No | Double | AVX2 |
lavacart.3D.NS2.AVX2.FLOAT |
3 | 2 | No | Single | AVX2 |
lavacart.3D.NS2.AVX512 |
3 | 2 | No | Double | AVX512 |
lavacart.3D.NS2.AVX512.FLOAT |
3 | 2 | No | Single | AVX512 |
lavacart.3D.NS3.AVX2 |
3 | 3 | No | Double | AVX2 |
lavacart.3D.NS3.AVX2.FLOAT |
3 | 3 | No | Single | AVX2 |
lavacart.3D.NS3.AVX512 |
3 | 3 | No | Double | AVX512 |
lavacart.3D.NS3.AVX512.FLOAT |
3 | 3 | No | Single | AVX512 |
lavacart.2D.NS1.AVX2 |
2 | 1 | No | Double | AVX2 |
lavacart.2D.NS1.AVX2.FLOAT |
2 | 1 | No | Single | AVX2 |
lavacart.2D.NS1.AVX512 |
2 | 1 | No | Double | AVX512 |
lavacart.2D.NS1.AVX512.FLOAT |
2 | 1 | No | Single | AVX512 |
Curvilinear Solver (lavacurv) - CPU
| Executable Name | Species | Multiphase | Precision | Architecture |
|---|---|---|---|---|
lavacurv.3D.NS1.AVX2 |
1 | No | Double | AVX2 |
lavacurv.3D.NS1.AVX512 |
1 | No | Double | AVX512 |
Unstructured Solver (lavaunst) - CPU
| Executable Name | Species | Multiphase | Precision | Architecture |
|---|---|---|---|---|
lavaunst.3D.NS1.AVX2 |
1 | No | Double | AVX2 |
lavaunst.3D.NS1.AVX2.FLOAT |
1 | No | Single | AVX2 |
lavaunst.3D.NS1.AVX512 |
1 | No | Double | AVX512 |
lavaunst.3D.NS1.AVX512.FLOAT |
1 | No | Single | AVX512 |
lavaunst.3D.NS2.AVX2 |
2 | No | Double | AVX2 |
lavaunst.3D.NS2.AVX2.FLOAT |
2 | No | Single | AVX2 |
lavaunst.3D.NS2.AVX512 |
2 | No | Double | AVX512 |
lavaunst.3D.NS2.AVX512.FLOAT |
2 | No | Single | AVX512 |
lavaunst.3D.NS3.AVX2 |
3 | No | Double | AVX2 |
lavaunst.3D.NS3.AVX2.FLOAT |
3 | No | Single | AVX2 |
lavaunst.3D.NS3.AVX512 |
3 | No | Double | AVX512 |
lavaunst.3D.NS3.AVX512.FLOAT |
3 | No | Single | AVX512 |
Intel + Cray-MPICH (Athena - AVX512)
Available in LAVA_*_intel_cray-mpich_x86_64_*.tar.gz
Cartesian Solver (lavacart) - CPU AVX512
| Executable Name | Dimension | Species | Multiphase | Precision |
|---|---|---|---|---|
lavacart.3D.NS1.AVX512 |
3 | 1 | No | Double |
lavacart.3D.NS1.AVX512.FLOAT |
3 | 1 | No | Single |
lavacart.3D.NS2.AVX512 |
3 | 2 | No | Double |
lavacart.3D.NS2.AVX512.FLOAT |
3 | 2 | No | Single |
lavacart.3D.NS3.AVX512 |
3 | 3 | No | Double |
lavacart.3D.NS3.AVX512.FLOAT |
3 | 3 | No | Single |
lavacart.2D.NS1.AVX512 |
2 | 1 | No | Double |
lavacart.2D.NS1.AVX512.FLOAT |
2 | 1 | No | Single |
Curvilinear Solver (lavacurv) - CPU AVX512
| Executable Name | Species | Multiphase | Precision |
|---|---|---|---|
lavacurv.3D.NS1.AVX512 |
1 | No | Double |
Unstructured Solver (lavaunst) - CPU AVX512
| Executable Name | Species | Multiphase | Precision |
|---|---|---|---|
lavaunst.3D.NS1.AVX512 |
1 | No | Double |
lavaunst.3D.NS1.AVX512.FLOAT |
1 | No | Single |
lavaunst.3D.NS2.AVX512 |
2 | No | Double |
lavaunst.3D.NS2.AVX512.FLOAT |
2 | No | Single |
lavaunst.3D.NS3.AVX512 |
3 | No | Double |
lavaunst.3D.NS3.AVX512.FLOAT |
3 | No | Single |
GPU PTX/JIT Binaries
LAVA ships two families of GPU executables that are built differently:
- Cartesian / unstructured binaries (
lava*) are built primarily as PTX-bearing binaries and rely on CUDA JIT compilation at runtime, keeping forward compatibility across newer GPU generations. - Curvilinear binaries (
lavacurv*) embed only pre-compiled SASS for a fixed set of architectures and do not JIT. On x86_64 they support compute capabilities 8.0, 8.9, and 12.0; the ARM build targets 9.0. Running a curvilinear binary on any other architecture is not supported (it would fall back to slow runtime translation on latest drivers).
Supported NVIDIA GPU Architectures
The following table lists some of the common GPU architectures supported by the LAVA GPU binaries, including tested systems and additional compatible families.
| System Architecture | GPU Model / Family | Compute Capability (SM) | Status |
|---|---|---|---|
| x86_64 | NVIDIA RTX 5090 | SM 12.0 (Blackwell) | Tested |
| x86_64 | NVIDIA RTX 4090 | SM 8.9 (Ada Lovelace) | Tested |
| x86_64 | NVIDIA A100 | SM 8.0 (Ampere) | Tested |
| ARM | NVIDIA GH200 | SM 9.0 (Hopper) | Tested |
| x86_64 | RTX 50-Series (Other) | SM 12.0 (Blackwell) | Untested |
| x86_64 | RTX 40-Series (Other) | SM 8.9 (Ada Lovelace) | Untested |
| x86_64 | L40 / L40S / L4 | SM 8.9 (Ada Lovelace) | Untested |
| x86_64 | A30 | SM 8.0 (Ampere) | Untested |
| x86_64 | H100 / H200 | SM 9.0 (Hopper) | Untested |
| ARM | H100 / H200 (ARM-based) | SM 9.0 (Hopper) | Untested |
Note
The above list is not exhaustive. Check your GPU against the compute capability supported in External Users (Tarball Installation).
Forward Compatibility and JIT Compilation
The Cartesian / unstructured binaries include PTX intermediate code and rely on the NVIDIA driver JIT compiler to generate native machine code for the installed GPU at runtime:
- x86_64 systems: Forward compatible for GPUs with CC 8.0+
- ARM systems: Forward compatible for GPUs with CC 9.0+
Curvilinear binaries do not JIT
The curvilinear binaries (lavacurv*) do not include a JIT/forward-compatibility path. They run only on the architectures for which native SASS is embedded: CC 8.0, 8.9, and 12.0 on x86_64, and CC 9.0 on ARM.
Runtime Behavior
For the Cartesian / unstructured binaries, the executable automatically detects your hardware at runtime:
- Driver JIT Compilation: On first launch on a given system/driver, the CUDA driver compiles embedded PTX to native GPU code
- JIT Cache Reuse: Subsequent runs reuse the NVIDIA compute cache and start faster
- Zero User Intervention: The process is automatic; no rebuild is required for supported GPUs
Technical Note on PTX/JIT Execution:
- First-Run Compilation Delay: The CUDA driver performs JIT compilation on the first launch, which may add a few hundred milliseconds to several seconds of startup time depending on kernel complexity
- JIT Caching: The compiled binary is stored in the NVIDIA Compute Cache. Subsequent runs will be fast, loading the cached binary directly
- Identical Runtime Performance: Once compiled, execution speed is identical to pre-compiled binaries
- Cache Invalidation: Updating the NVIDIA driver or clearing the cache will trigger recompilation on the next launch
- Driver Compatibility: The PTX target must be supported by your driver/toolchain; use the LAVA-recommended driver baseline for release binaries
In summary, the Cartesian / unstructured GPU builds prioritize PTX + JIT for portability and forward compatibility, with a one-time first-run compile cost, while the curvilinear builds ship native SASS for a fixed set of architectures (CC 8.0/8.9/12.0 on x86_64, CC 9.0 on ARM) and do not JIT.
Running LAVA on NASA Advanced Supercomputing (NAS) Resources
This guide provides NAS-specific information for running LAVA simulations, including PBS job scripts, queue limits, node configurations, and job sizing guidelines.
Note: For LAVA installation instructions, see the LAVA Access Guide. For LAVA Voronoi installation, see the LAVA Voronoi Installation Guide.
Example Usage on NAS Systems
On A100 GPU Systems (Cabeus x86_64)
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_a100_job
#PBS -q gpu_normal
#PBS -l select=4:ncpus=128:model=mil_a100:ngpus=4:mem=500gb
#PBS -W group_list=<your project group ID>
#PBS -l place=scatter:excl
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -k oed
#PBS -r n
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Set environment
export OMP_NUM_THREADS=32
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA
mpiexec -N 4 --bind-to none --report-bindings mbind.x -t $OMP_NUM_THREADS \
lavacart.3D.NS1 cart.inputs |& tee run.log
Submit with: qsub submit_a100.pbs
On GH200 GPU Systems (Cabeus Grace-Hopper ARM)
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_gh200_job
#PBS -q gpu_normal
#PBS -l select=16:ncpus=72:mpiprocs=1:model=gh200:ngpus=1:mem=460gb
#PBS -W group_list=<your project group ID>
#PBS -l walltime=04:00:00
#PBS -j oe
#PBS -k oed
#PBS -r n
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Set environment
export OMP_NUM_THREADS=72
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA with NUMA binding (1 MPI rank per node, 1 GPU per node)
mpiexec -N 1 --report-bindings --hostfile $PBS_NODEFILE \
numactl --cpunodebind 0 --membind 0 \
mbind.x -t $OMP_NUM_THREADS lavaunst.3D.NS1 unst.inputs |& tee run.log
Submit with: qsub submit_gh200.pbs
On CPU Systems - Milan (Aitken)
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_milan_job
#PBS -q normal
#PBS -l select=16:ncpus=128:model=mil_ait
#PBS -W group_list=<your project group ID>
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -k oed
#PBS -r n
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Set environment
export OMP_NUM_THREADS=32
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA (4 MPI ranks per node, 32 threads each)
mpirun -npernode 4 mbind.x -t $OMP_NUM_THREADS \
lavaunst.3D.NS1.AVX2 unst.inputs |& tee run.log
Submit with: qsub submit_milan.pbs
On CPU Systems - Skylake (Electra)
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_skylake_job
#PBS -q normal
#PBS -l select=32:ncpus=40:model=sky_ele
#PBS -W group_list=<your project group ID>
#PBS -l walltime=04:00:00
#PBS -j oe
#PBS -k oed
#PBS -r n
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Set environment
export OMP_NUM_THREADS=20
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA (2 MPI ranks per node, 20 threads each)
mpirun -npernode 2 mbind.x -t $OMP_NUM_THREADS \
lavacart.3D.NS1.AVX512 cart.inputs |& tee run.log
Submit with: qsub submit_skylake.pbs
On AMD Turin Systems (Athena)
#!/bin/bash
#PBS -S /bin/bash
#PBS -N lava_turin_job
#PBS -q normal
#PBS -l select=16:ncpus=512:mpiprocs=4:model=tur_ath
#PBS -W group_list=<your project group ID>
#PBS -l walltime=04:00:00
#PBS -j oe
#PBS -k oed
#PBS -r n
# Load LAVA module
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Set environment
export OMP_NUM_THREADS=128
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA (4 MPI ranks per node, 128 threads each)
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t $OMP_NUM_THREADS \
lavacart.3D.NS1.AVX512 cart.inputs |& tee run.log
Submit with: qsub submit_turin.pbs
Tip
When running on Athena make sure that you have cd $PBS_O_WORKDIR because on athena compute nodes you land on home directory by default.
Available NAS Resources
The following NAS resources are available for running LAVA simulations:
| Node Identifier | CPU | GPU | Number of Nodes | SBUs* | Front End |
|---|---|---|---|---|---|
| Electra | |||||
bro_ele |
2x Intel Broadwell | - | 1152 | 1.0 | pfe |
sky_ele |
2x Intel Skylake | - | 2304 | 1.59 | pfe |
| Aitken | |||||
cas_ait |
2x Intel Cascade Lake | - | 1152 | 1.64 | pfe |
rom_ait |
2x AMD Rome | - | 2048 | 4.06 | pfe |
mil_ait |
2x AMD Milan | - | 512 | 4.38 | afe |
| Athena | |||||
tur_ath |
2x AMD Turin | - | 1024 | 12.19 | athfe |
| Cabeus | [GPU] | ||||
mil_a100 |
1x AMD Milan | 4× NVIDIA A100 | 128 | 37.86 | cfe0[1-2] |
gh200 |
1x NVIDIA Grace | 1× NVIDIA H100 | 350 | 18.34 | cghfe0[1-2] |
*CPU and GPU SBU allocations are separate and thus not directly comparable
For detailed information about hardware specifications, policies, and usage guidelines, refer to the NAS HECC Knowledge Base.
Queue Limits
For the latest queue limits and policies, please refer to the following links:
- Aitken and Electra: PBS Job Queue Structure
- Athena: PBS Job Queue Structure
- Cabeus A100: Preparing to Run on Cabeus A100 GPU Nodes
- Cabeus GH200: Preparing to Run on Cabeus Grace Hopper Nodes
Running Configuration Table
The table below describes the recommended number of MPI ranks and OpenMP threads to use for each model type. The table also lists the executable suffix to use based on the node architecture.
| Model | PBS Select Line | MPI Ranks per Node | OpenMP Threads per Rank | Executable Suffix |
|---|---|---|---|---|
bro_ele |
ncpus=28:model=bro_ele |
2 | 14 | AVX2 |
sky_ele |
ncpus=40:model=sky_ele |
2 | 20 | AVX512 |
cas_ait |
ncpus=40:model=cas_ait |
2 | 20 | AVX512 |
rom_ait |
ncpus=128:model=rom_ait |
4 | 32 | AVX2 |
mil_ait |
ncpus=128:model=mil_ait |
4 | 32 | AVX2 |
tur_ath |
ncpus=512:model=tur_ath |
4 | 128 | AVX512 |
mil_a100 |
ncpus=128:model=mil_a100:ngpus=4:mem=500gb |
4 | 32 | |
gh200 |
ncpus=72:model=gh200:ngpus=1:mem=460gb |
1 | 72 |
Tip
Optimum configuration may vary depending on your specific simulation. Consider performance testing to optimize resource allocation.
LAVA Utilities
LAVA comes with various tools that help with common tasks
plotHist
This tool visualizes data from LAVA history files (typically .iter files), allowing users to plot one or more variables against another variable. It's highly customizable with numerous options for analysis and presentation of simulation results.
Where:
xvar: Variable to use for the x-axis (default: 'iter')yvar1, yvar2, ...: Variables to plot on the y-axis-F <filename>: Specify input file(s) (can be used multiple times)-xscale <value>,-yscale <value>: Scale x-axis or y-axis values-dispVars: Display available variables in the file and exit-xRange <start> <end>: Select a specific x-axis range-doLogx,-doLogy: Use logarithmic scale for the x-axis or y-axis-showGrid <type>: Show gridlines (major, minor, or both)-hLine <value>,-vLine <value>: Draw horizontal or vertical reference lines-showMean: Plot and display the mean value of variables-showStd: Plot and display standard deviation of variables-showMovMean <timescale>: Plot exponential moving average with given timescale-saveFig <filename>: Save the figure to a file-doSubplot: Create a separate subplot for each variable-legend <text>: Custom legend text (format: "line1txt|line2txt|line3txt")-noPlot: Suppress displaying the plot (useful with-saveFig)-dumpData <filename>: Export data to a Tecplot-readable ASCII file-appendFiles: Append listed data files in sequential order-funcFile <filename>: Use a Python file that defines custom functions-hasSubIter: For data with subiterations, only plot the last subiteration-checkConv: Assess statistical convergence — detects the warmup (transient) period using MSER, estimates the effective sample size via integrated autocorrelation time, and suggests an averaging window; annotates the plot accordingly
Examples:
# Plot cl_airplane against convective time units using default history file
$> plotHist.py ctu cl_airplane
# Plot multiple variables with logarithmic y-axis
$> plotHist.py time flowres turres -doLogy
# Compare data from multiple files
$> plotHist.py ctu cl_airplane -F run1.iter -F run2.iter -legend "Baseline|Modified"
# Show statistical information
$> plotHist.py time cd_airplane -showMean -showStd
# Plot only a specific portion of the data
$> plotHist.py ctu cd_airplane -xRange 20 50
# Show statistical information only for a specific portion of the data
$> plotHist.py ctu cd_airplane -showMean -showStd -xRange 20 50
# Save the figure without displaying
$> plotHist.py time cl_airplane -saveFig result -noPlot
# Assess statistical convergence and annotate the plot
$> plotHist.py ctu cl_airplane -checkConv
Tip
If no file is specified, the tool looks for data.iter, monitor/Unst.data.iter, or monitor/Cart.data.iter in the current directory.
plotSpectra
Spectra (PSD, narrow-band SPL, 1/N-octave bands, OASPL, directivity) of any LAVAMonitor .iter
record: point and line probes, monitor histories and the streaming FW-H observer files, with azimuthal
averaging of replicated observers and overlays of experimental spectra. It has its own page:
plotSpectra.
CGNS_to_LAVA
This tool converts a CGNS mesh file into LAVA input formats by extracting:
- boundary conditions (
.bc) - block-to-block connectivity (
.b2b) - structured grid coordinates (
.x, Plot3D binary format)
It is useful when preparing CGNS meshes for LAVA workflows that require explicit BC and connectivity files.
Usage:
Required argument:
cgns_file: Input CGNS file path
Options:
-o, --output <base_name>: Base name for output files- default: input file name without
.cgns --verbose: Print detailed processing information and extraction summary
Output Files:
For input mesh.cgns, the tool writes:
mesh.bc— boundary-condition records in LAVA BC formatmesh.b2b— block connectivity and transform data in LAVA B2B formatmesh.x— Plot3D binary grid coordinates (X, Y, Z for each zone)
What the tool extracts:
- Zone mapping: Builds zone-name to zone-ID mapping
- Boundary conditions: Reads
ZoneBC/PointRangeandFamilyName - If
FamilyNameis missing, a default name is generated - Connectivity: Reads
ZoneGridConnectivityreceiver/donor ranges and transform vectors - Grid coordinates: Reads
CoordinateX/Y/ZunderGridCoordinates
Examples:
# Convert with default output names
$> CGNS_to_LAVA.py mesh.cgns
# Convert with custom base output name
$> CGNS_to_LAVA.py mesh.cgns -o lava_mesh
# Convert with verbose diagnostics
$> CGNS_to_LAVA.py mesh.cgns --verbose
Note
The script expects CGNS content organized under a Base node with standard zone children (e.g., ZoneBC, GridCoordinates, and ZoneGridConnectivity).
Tip
Use --verbose when first processing a new mesh to verify donor-zone mapping and range extraction before running LAVA.
lava_to_cgns
This tool converts a curvilinear LAVA grid setup to a CGNS file. It reads the grid/BC/B2B information from a LAVA run/input file and writes a structured CGNS mesh with:
- zone coordinates (
CoordinateX,CoordinateY,CoordinateZ) - boundary-condition records (with family names)
- 1-to-1 block connectivity (
GridConnectivity1to1)
Usage:
Where:
run_file: LAVA input/run file containing the curvilinear grid setup (includinggrid.curv.gridFileand BC/connectivity references)
Output:
- Writes a CGNS file named from the input Plot3D grid file root:
- if
grid.curv.gridFile = mygrid.x, output ismygrid.cgns
What the tool does:
- Initializes MPI and reads options from the provided run file
- Reads curvilinear grid metadata and BC/connectivity information
- Loads Plot3D coordinates from
grid.curv.gridFile - Writes zones, coordinates, BCs, and block connectivity to CGNS
Examples:
cgns_polyformat
This tool converts an unstructured CGNS grid with standard mixed elements into a polyhedral representation formatted CGNS file. The polyhedral format is more memory-efficient and provides improved handling of complex geometries.
Requirements:
- Input file must contain only a single base
- Input file must contain only a single zone
- The zone type must be unstructured
Supported Element Types:
- Volume elements: TETRA_4, PYRA_5, PENTA_6, HEXA_8
- Surface elements: TRI_3, QUAD_4
Usage:
Where:
inputFile.cgns: The input CGNS file with standard mixed elementsoutputFile.cgns: (Optional) The name for the output file. If not provided, the tool will append "_poly" to the input filename
Process:
- Reads the input CGNS file structure and connectivity
- Creates a dual graph representation using METIS
- Identifies cell faces and their connections
- Preserves all boundary conditions from the original file
- Writes the new polyhedral formatted CGNS file
Example:
# Convert mesh to polyhedral format with default output name
$> cgns_polyformat grid.cgns
# Convert mesh to polyhedral format with specified output name
$> cgns_polyformat input.cgns polyhedral_output.cgns
Note
The polyhedral representation can significantly reduce memory usage and improve solver performance for complex geometries.
unst_brick_cgns
This tool generates a structured hexahedral mesh (brick) in an unstructured CGNS format. It creates a simple rectangular domain with options for different types of grid perturbations, useful for testing and developing computational methods.
Usage:
Where:
ni nj nk: Number of nodes in the x, y, and z directionsxmin ymin zmin: Minimum coordinates of the brick domainxdim ydim zdim: Dimensions of the brick in x, y, and z directionsperturb_type: Optional grid perturbation type (choices: none, sine, random, random_inner)
Boundary Conditions:
The tool automatically creates six boundary faces with the following names:
left: Minimum x boundary (i=0)right: Maximum x boundary (i=ni-1)bottom: Minimum y boundary (j=0)top: Maximum y boundary (j=nj-1)back: Minimum z boundary (k=0)front: Maximum z boundary (k=nk-1)
Perturbation Types:
none: No perturbation applied (creates a perfect grid)sine: Applies a sinusoidal perturbation to internal nodesrandom: Applies random perturbations to all interior nodesrandom_inner: Applies random perturbations only to nodes away from boundaries
Examples:
# Create a 21x21x21 unit cube centered at origin
$> unst_brick_cgns 21 21 21 -0.5 -0.5 -0.5 1.0 1.0 1.0
# Create a 2D-like mesh (one cell thick in z-direction)
$> unst_brick_cgns 101 101 2 0.0 0.0 0.0 1.0 1.0 0.01
# Create a mesh with sinusoidal perturbation
$> unst_brick_cgns 31 31 31 -1.0 -1.0 -1.0 2.0 2.0 2.0 sine
# Create a mesh with random perturbation only in the interior
$> unst_brick_cgns 51 51 51 0.0 0.0 0.0 10.0 10.0 10.0 random_inner
Note
The output file is always named brick.cgns and will be created in the current directory.
unst_extrude_cgns
This tool extrudes a specified boundary section of an unstructured CGNS grid. It creates new grid layers extending from the selected boundary, using various extrusion strategies. This is useful for creating prism layers, wake regions, or far-field extensions.
Usage:
The tool uses an input file to specify the extrusion parameters rather than command-line arguments:
filename = input_grid.cgns # Input CGNS grid file
output = merged # Output mode: "merged" or "extrusiononly"
extrusion {
bcnumber = 3 # Boundary condition number to extrude (1-based)
method = machaligned # Extrusion method
# Additional parameters based on chosen method
# ...
}
Extrusion Methods:
-
machaligned - Extrudes along Mach cone characteristics
method = machaligned mach = 1.5 # Mach number bodyaxis = x axis # Body axis (xaxis, yaxis, or zaxis) origin = [0.0, 0.0, 0.0] # Origin for radial distance calculation initialspacing = 0.001 # First layer height maximumspacing = 0.1 # Maximum layer height stretchingratio = 1.2 # Growth ratio between layers height = 10.0 # Total extrusion height cylinderradius = 1.0 # Optional cylinder radius specification -
stretchtranslate - Extrudes in specified direction with stretching
-
translate - Extrudes uniform layers in specified direction
Output Modes:
merged: Creates a new CGNS file containing both the original grid and the extruded regionextrusiononly: Creates a new CGNS file containing only the extruded region
Example:
# Create a wake region behind an airfoil with stretching
$> cat wake_extrusion.input
filename = airfoil.cgns
output = merged
extrusion {
bcnumber = 3
method = stretchtranslate
direction = [1.0, 0.0, 0.0]
initialspacing = 0.001
maximumspacing = 0.05
stretchingratio = 1.1
height = 5.0
}
$> unst_extrude_cgns wake_extrusion.txt
Note
The extrusion process preserves the topology of the original boundary and creates new cell layers based on the specified extrusion method.
unst_interpolator
This tool can be used to interpolate unstructured solution from one simulation to initialize the simulation on a different grid. Usage can be done via command line arguments:
As a result, the tool will produce the target_restart file which can be used to start the new simulation from interpolated results.
Alternative to the command line, an input file can be provided with additional options to apply transformations to the reference grid and solution before interpolation. The input file for the tool follows the same syntax as in the solver input file:
reference {
grid_file = reference.cgns
restart_file = reference.hdf5
# Scale the grid by a factor of 2
transform_1 {function=scale; factor=2}
# Translate the grid 1 unit length in x direction
transform_2 {function=translate; distance=[1,0,0]}
# Rotate the grid 90 degrees around y axis with an origin of (0,0,0)
transform_3 {function=rotate; center=[0,0,0]; axis=[0,1,0]; angle=90}
# Convert 1-cell thick (essentially 2D) grid into axisymmetric (wedge shape)
# Depth is assumed to be in the depth direction, while y-ccordinate is the height.
transform_4 {function=axisymmetric; y_center=0, y_tolerance=1.e-6, angle=5}
}
target {
grid_file = target.cgns
restart_file = target.hdf5
}
To use the tool with the input file, simply provide the input file name as the only argument:
unst_mirror_cgns
This tool creates a mirror reflection of an unstructured CGNS grid across a specified boundary plane. It's useful for generating symmetric computational domains from asymmetric meshes, and can optionally create periodic connections between the original and mirrored domains.
Usage:
The tool requires an input file that specifies the mirroring parameters:
filename = input_grid.cgns # Input CGNS grid file
mirror {
mirror_bc = 5 # Boundary to mirror across
domain_bc = 3 # Boundary that will be at domain interface
direction = x axis # Mirror direction (xaxis, yaxis, or zaxis)
periodic = false # Create periodic fringes (true or false)
}
Configuration Options:
filename: Path to the input CGNS grid filemirror_bc: Boundary condition number to mirror acrossdomain_bc: Boundary condition number that will be at the interface between original and mirrored domainsdirection: Axis normal to the mirror plane (xaxis, yaxis, or zaxis)periodic: Whether to create periodic connections between original and mirrored domains (true or false)
Process:
- Reads the input CGNS file
- Identifies the mirror plane based on the specified boundary
- Creates a mirrored copy of the grid across this plane
- Optionally creates periodic connections between the original and mirrored domains
- Performs a Gauss flux check to validate the resulting mesh
- Writes the new mirrored CGNS file
Output:
The tool creates a new CGNS file with the original grid plus its mirrored counterpart:
- If
periodic = "false": Outputs a file named[original_name]_mirrored.cgns - If
periodic = "true": Outputs a file named[original_name]_mirroredPeriodic.cgns
Example:
# Create a simple mirror configuration file
$> cat mirror_config.txt
filename = aircraft_half.cgns
mirror {
mirror_bc = 3
domain_bc = 5
direction = y axis
periodic = false
}
# Run the mirroring tool
$> unst_mirror_cgns mirror_config.txt
unst_gridInfo
This tool returns grid information (cell/face/node count) as well as boundary condition information for a CGNS grid. The BC section of the output can be copied directly into the solver input file as a starting point for BC setup.
The tool is shipped as a single self-contained Python file,
unst-gridinfo.pyz. Drop it anywhere on your machine and run it with any
Python 3.9+:
First-run behavior. The first time you run the tool on a given machine, it sets itself up automatically:
- Creates a private virtual environment at
~/.local/share/unst-gridinfo/venv(override withXDG_DATA_HOME). - Installs its small dependency set (
h5py,numpy) into that venv. - Re-executes itself inside the venv and prints the grid info.
This typically takes ~30 seconds and only happens once. Every subsequent
invocation reuses the cached venv and starts instantly. The tool needs no
system CGNS or HDF5 libraries — only Python 3.9+ and pip.
If you ever need to force a clean re-install of the dependencies:
Example output:
[I] Grid file type is CGNS
[I] Reading File Information from exampleGrid.cgns
[I] CGNS lib version : 4300
[I] CGNS file version : 4
[I] .... cellDim = 3
[I] .... physDim = 3
[I] .... Global cell count = 60969873
[I] .... Global face count = 426730528
[I] .... Global node count = 365553518
[I] BC_1 {type = } # Name: mixer_inside_wall_1
[I] BC_2 {type = } # Name: mixer_outside_wall_1
[I] BC_3 {type = } # Name: mixer_te
[I] BC_4 {type = } # Name: outer_wall_5
[I] BC_5 {type = } # Name: inflow_inner
[I] BC_6 {type = } # Name: zMin
[I] BC_7 {type = } # Name: yMin
[I] BC_8 {type = } # Name: xMin
[I] BC_9 {type = } # Name: yMax
[I] BC_10 {type = } # Name: xMax
[I] BC_11 {type = } # Name: zMax
plotLineProbe
This tool allows users to visualize and analyze data from LAVA binary line probe files. It creates plots of selected variables at specified timesteps with various customization options.
Usage:
Options:
-F, --file: Line probe binary file (required)-v, --variables: Variables to plot by name or index (required)-t, --timesteps: Specific timestep indices to plot-r, --range: Plot a range of timesteps (start end [interval])-x: X-axis for plotting (choices: x, y, z, arc) (default: arc length)-i, --info: Display information about available variables and timesteps--latest: Plot only the latest timestep-o, --output: Directory to save figures instead of displaying them
Examples:
# Display information about probe file
$> plotLineProbe.py -F probe.line -i
# Plot pressure and temperature from the latest timestep
$> plotLineProbe.py -F probe.line -v Pressure Temperature
# Plot variables using numeric indices with specific timesteps
$> plotLineProbe.py -F probe.line -v 0 2 5 -t 10 20 30
# Plot data from a range of timesteps with interval
$> plotLineProbe.py -F probe.line -v Pressure -r 10000 20000 1000
# Use y-coordinate for x-axis instead of arc length
$> plotLineProbe.py -F probe.line -v Pressure -x y
# Save figures to a specified directory
$> plotLineProbe.py -F probe.line -v Pressure -o figures/
computeSurfaceCuts
This tool extracts and processes 2D cuts from 3D CFD surface solution files. It can compute intersections between user-defined planes and surface geometry, calculate aerodynamic coefficients along these cuts, and generate both visualizations and data files for analysis. The tool has been enhanced with rotation support for moving surfaces, automatic time extraction from CGNS files, and comprehensive data processing capabilities.
Usage:
$> ./computeSurfaceCuts.py <config_file>
$> computeSurfaceCuts.py <config_file>
$> computeSurfaceCuts.py --help
Key Features:
- Automatic Display Detection: Detects X11 availability and adapts behavior accordingly
- Headless Operation: Runs cleanly without display, suppressing warnings automatically
- Surface Cutting: Extract intersection lines between arbitrary cutting planes and CFD surface data
- Coefficient Calculations: Compute pressure coefficient (Cp) and skin friction coefficient (Cf) along cuts
- Rotation Support: Handle rotating surfaces (e.g., helicopter rotors, propellers) with automatic time-based transformations
- Multiple Cut Types: Support for multiple cuts and multiple planes per cut with automatic intersection capabilities
- Variable Processing: Extract both averaged and instantaneous flow quantities from CGNS surface files
- Coordinate Transformations: Transform coordinates back to fixed reference frame for consistent analysis
- Data Export: Output data in Tecplot or ASCII format with comprehensive unit conversion and normalization options
- Visualization: Generate 2D plots and 3D visualizations of surface geometry and cutting planes
- Chord Normalization: Automatic chord length computation and x/c normalization for blade analysis
- Coefficient Scaling: Per-cut scaling of aerodynamic coefficients for dynamic pressure correction or comparison
Basic configuration file format:
The configuration file uses YAML format with the following comprehensive options:
# Input file path
file_path: /path/to/Unst.surf.100.cgns
# Variables to extract and process
variables: [pcoef, Cf, cpavg, cfavg, pavg, uavg, vavg, wavg, tavg]
# Reference conditions for coefficient calculations
reference_conditions:
Mach: 0.2
SpeedOfSound: 340.0 # m/s
rho: 1.225 # kg/m³
p: 101325.0 # Pa
Supported variables:
The tool supports the following variable types:
Averaged Quantities:
pavg: Average pressureuavg,vavg,wavg: Average velocity componentstavg: Average temperaturetauwXavg,tauwYavg,tauwZavg: Average wall shear stress componentscpavg: Average pressure coefficient (computed frompavg)cfavg: Average skin friction coefficient (computed from wall shear stress)
Instantaneous Quantities:
pcoef: Instantaneous pressure coefficient (extracted directly or computed frompressure)Cf: Instantaneous skin friction coefficient vector (automatically split intoCfx,Cfy,Cfz,Cf_mag)
Rotation Configuration (Optional):
For rotating surfaces like helicopter rotors, propellers, or turbomachinery:
rotation:
enabled: true
axis: [0, 0, 1] # Rotation axis vector (Z-axis for helicopters)
center: [0, 0, 0] # Center of rotation (hub location)
angular_velocity: 157.08 # Rotation speed
velocity_units: rad/s # 'rad/s' or 'rpm'
How Rotation Works:
- Time Extraction: Automatically reads time from CGNS file (
TimeIterValues/TimeValues) - Plane Rotation: Rotates cutting plane origins and normals to match surface position
- Coordinate Transform: Transforms intersection coordinates back to fixed reference frame for consistent plotting
- Fixed Frame Output: All plots and data files use consistent coordinates regardless of rotor position
Output Configuration:
output:
save surface: true # Save 3D surface visualization
save cuts: true # Save 2D plots of each cut
# Optional: Write cut data to files
write cut data:
format: tecplot # 'tecplot' or 'ascii'
units: m # Output units: 'm', 'mm', 'inch', 'ft'
scaling: 1.0 # Additional scaling factor
translate: [0, 0, 0] # Translation vector [x, y, z]
# Chord normalization options (for blade analysis)
normalize_chord: true # Normalize x-coordinates by chord length (per-cut)
chord_length: 0.1905 # Optional: specify chord length manually
# If not specified, computed as (x_max - x_min) for each cut individually
Output Files Generated:
- Plots: Individual PNG files for each variable at each cut (e.g.,
r=0.5_pcoef.png,r=0.5_Cfx.png) - 3D Visualization: Surface plot showing geometry and cut locations (
surface_plot.png) - Data Files: Tecplot or ASCII files with all cut data (
Unst.cutdata.100.dat)
Cut Definitions:
Define one or more cuts with flexible plane specifications:
Single Plane Cut:
Cut 1:
name: "Radial Station r/R=0.5" # Optional descriptive name
coefficients scale factor: 4.0 # Optional: Scale coefficient variables for this cut
plane:
bc_comps_to_cut: [1, 2, 3-5] # Boundary components to intersect (ranges allowed)
origin: [0, 0.5715, 0] # Point on the plane
normal: [0, 1, 0] # Normal vector
units: m # Input units: 'm', 'mm', 'inch'
rotate_with_surface: true # Whether plane rotates with surface (default: true)
Multiple Plane Cut:
Cut 2:
name: "Complex Intersection"
plane 1:
bc_comps_to_cut: [1, 2, 3]
origin: [0.5, 0, 0]
normal: [1, 0, 0]
plane 2:
bc_comps_to_cut: [1, 2, 3]
equation: [0.5, 0.866, 0, 0] # Alternative: plane equation ax + by + cz + d = 0
# Optional: Create intersection line between planes
intersection: [1, 2] # Use planes 1 and 2 to create intersection
Plane Definition Methods:
Method 1: Origin and Normal
plane:
origin: [0, 0.5, 0] # Point on the plane
normal: [0, 1, 0] # Normal vector (will be normalized)
Method 2: Plane Equation
Component Specification:
Boundary components can be specified with ranges for convenience:
Note: Components are converted to zero-based indexing internally.
Coefficient Scaling:
For rotating machinery or cases requiring dynamic pressure correction, you can apply per-cut scaling to aerodynamic coefficients:
Cut 1:
name: "r/R=0.5"
scale factor: 4.0 # Scales all coefficient variables by this factor
plane:
bc_comps_to_cut: [1]
origin: [0, 0.5715, 0]
normal: [0, 1, 0]
Affected Variables:
- pcoef: Instantaneous pressure coefficient
- cpavg: Average pressure coefficient
- cfavg: Average skin friction coefficient
- Cfx, Cfy, Cfz, Cf_mag: Instantaneous skin friction coefficient components
Common Use Cases:
- Dynamic Pressure Correction: Scale coefficients by local-to-reference dynamic pressure ratio
- Rotating Machinery: Account for varying dynamic pressure with radius (e.g., q_local/q_ref = (r*Ω)²/V_ref²)
- Comparative Analysis: Normalize coefficients for easier comparison between different flow conditions
Complete Example Configurations
Basic Airfoil Analysis
file_path: airfoil_surface.cgns
variables: [cpavg, cfavg]
reference_conditions:
Mach: 0.3
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
output:
save surface: true
save cuts: true
write cut data:
format: tecplot
units: m
normalize_chord: true
Cut 1:
name: "Midspan"
plane:
bc_comps_to_cut: [1]
origin: [0, 0, 0]
normal: [0, 0, 1]
Hovering Helicopter Rotor
file_path: surface/Unst.surfLatest.cgns
variables: [pcoef, Cf]
reference_conditions:
Mach: 2.2801826223220284e-01
SpeedOfSound: 3.4120750376331983e+02
rho: 1.2183892815897766e+00
p: 1.0132000000000000e+05
# Rotation configuration
rotation:
enabled: true
axis: [0, 0, 1] # Z-axis rotation
center: [0, 0, 0] # Hub center
angular_velocity: 68.06784 # rad/s
velocity_units: rad/s
output:
save surface: true
save cuts: true
write cut data:
format: tecplot
units: m
normalize_chord: true
chord_length: 0.1905 # Blade chord length
# Multiple radial stations with coefficient scaling
Cut 1:
name: "r/R=0.3"
coefficients scale factor: 4.0 # Scale coefficients by dynamic pressure ratio
plane:
bc_comps_to_cut: [1]
origin: [0, 0.343, 0]
normal: [0, 1, 0]
Cut 2:
name: "r/R=0.5"
coefficients scale factor: 2.16 # Different scaling for this radial station
plane:
bc_comps_to_cut: [1]
origin: [0, 0.5715, 0]
normal: [0, 1, 0]
Cut 3:
name: "r/R=0.7"
coefficients scale factor: 1.56 # Scaling decreases with radius
plane:
bc_comps_to_cut: [1]
origin: [0, 0.8001, 0]
normal: [0, 1, 0]
Complex Multi-Plane Analysis
file_path: wing_surface.cgns
variables: [pcoef, Cf, cpavg]
reference_conditions:
Mach: 0.85
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
output:
save surface: true
save cuts: true
write cut data:
format: ascii
units: mm
scaling: 1000.0
Cut 1:
name: "Wing Station"
plane 1:
bc_comps_to_cut: [1, 2, 3]
origin: [2.0, 0, 0]
normal: [1, 0, 0]
plane 2:
bc_comps_to_cut: [1, 2, 3]
origin: [2.0, 0, 0]
normal: [0.707, 0.707, 0]
intersection: [1, 2] # Create intersection line
Data Processing Features
- Cf Vector Decomposition: Automatically splits 3D
Cfvector intoCfx,Cfy,Cfz, andCf_magcomponents - Coefficient Calculation: Computes
cpavgfrompavgandcfavgfrom wall shear stress components - Missing Variable Handling: Gracefully handles missing variables and provides informative warnings
Coordinate Transformations
- Fixed Frame Transform: For rotating surfaces, coordinates are transformed back to a fixed reference frame
- Unit Conversion: Automatic conversion between meters, millimeters, inches, and feet
- Chord Normalization: For blade analysis, x-coordinates can be normalized to x/c with automatic chord detection
Output Formats
- Tecplot Format: Industry-standard format with proper variable naming (
X/Cfor normalized coordinates) - ASCII Format: Simple column-based format with headers
- Variable Organization: Coordinates first, then all other variables in alphabetical order
Usage Examples
# Basic usage with configuration file (standalone execution)
$> ./computeSurfaceCuts.py blade_analysis.yml
# Alternative usage with python interpreter
$> computeSurfaceCuts.py blade_analysis.yml
# Show comprehensive help and configuration options
$> ./computeSurfaceCuts.py --help
# Process rotating helicopter rotor data
$> ./computeSurfaceCuts.py helicopter_cuts.yml
# Analyze airfoil with chord normalization
$> ./computeSurfaceCuts.py airfoil_analysis.yml
Output Files
The tool generates organized output in a figures/ directory:
Plot Files:
[cut_name]_[variable].png: Individual plots for each variable at each cutsurface_plot.png: 3D visualization of surface and cut locations
Data Files:
[filename].cutdata.[timestep].dat: Combined data file with all cuts- Format determined by configuration (Tecplot or ASCII)
- Includes all computed variables and coordinates
Time Extraction
The tool automatically extracts time information from CGNS files using multiple methods:
- Direct extraction from TimeIterValues/TimeValues
- Field data search for time-related variables
- Filename pattern matching for timestep information
Rotation Analysis
For rotating machinery analysis: - The tool automatically handles time-varying geometry - Coordinates are transformed to a consistent reference frame - Multiple radial stations can be analyzed simultaneously - Chord normalization provides standardized x/c coordinates
Performance
For large surface files or many cuts: - Processing time scales with number of intersection points - Memory usage depends on the number of variables and cut complexity - Consider reducing the number of components or variables for initial testing
Display Behavior
The tool automatically adapts to the execution environment:
- With X11/Display Available:
- save surface: false or save cuts: false → Shows plots interactively
- save surface: true or save cuts: true → Saves to files without showing
- Without Display (Headless):
- Automatically detects and uses off-screen mode
- Suppresses display-related warnings
- Always saves to files (interactive display disabled)
tri2stl
This tool converts triangulated surface mesh files from .tri format to ASCII STL format. It automatically detects the input format (binary Fortran or ASCII) and produces high-precision STL output suitable for engineering applications and 3D printing.
Usage:
Where:
input.tri: Input triangulated mesh file in .tri formatoutput.stl: Output STL file in ASCII format with double precision
stl_converter
This tool converts one or more STL files (binary or ASCII, auto-detected) into a single combined surface mesh written in CGNS, VTK, or i.tri format. It performs global vertex welding across all input files to produce a clean, shared-vertex triangulation. Each input file becomes a separate named component (section) in the output, making it ideal for reassembling component STL exports into a single multi-component surface mesh.
Usage:
The tool is driven entirely by a YAML configuration file:
inputs:
- file: fuselage.stl
name: fuselage
- file: wing.stl
name: wing
output:
format: cgns # cgns, vtk, or tri
filename: combined.cgns
options:
weld_tolerance: 0 # 0 = exact bit-match, >0 = tolerance-based
scale: 1.0
YAML Fields:
inputs: A list of STL files to read. Each entry has:file: Path to the STL file (binary or ASCII, auto-detected)name: (Optional) Component name. Defaults to the filename stem if omitted
output:format: Output format —cgns(single zone, one section per component),vtk(binary polydata), ortri(Fortran binary i.tri with record markers)filename: Output file path
options:weld_tolerance: Vertex welding tolerance. Set to0(or negative) for exact float32 bit-match welding, which is recommended when input STLs originate from the same source mesh. A positive value activates tolerance-based welding with 27-cell neighbor searchscale: Uniform scale factor applied to all vertex coordinates
Welding Modes:
- Exact bit-match (
weld_tolerance ≤ 0): Hashes the raw 12 bytes of each float32 xyz triplet. Two vertices are merged only if their bit representations are identical. Best when STL files were produced from the same triangulated mesh (e.g., fromtri2stl) - Tolerance-based (
weld_tolerance > 0): Quantizes vertices to a Cartesian grid and checks all 27 neighbouring cells to avoid grid-boundary misses. Use this when vertex coordinates may have been perturbed by different tools or rounding
Output Formats:
- CGNS: Single base, single unstructured zone, one
TRI_3section per component. Includes acomponentcell-centered field - VTK: Binary polydata mesh with a
componentcell variable - i.tri: Fortran binary with four records — (nVert, nFace), xyz float32, connectivity int32 (1-based), component IDs int32. Native endianness with Fortran record markers
Examples:
# Convert 24 component STLs to a single CGNS file
$> stl_converter.3D.NS1.OPTHIGH.MPI.OMP.EM.AVX2 components.yaml
# Convert a single STL to i.tri format
$> stl_converter.3D.NS1.OPTHIGH.MPI.OMP.EM.AVX512 single.yaml
Tip
When your STL files come from decomposing an existing .tri mesh (e.g., via tri2stl), use weld_tolerance: 0 for exact bit-match welding. This guarantees all shared vertices are correctly merged without any floating-point tolerance ambiguity.
Note
The tool is compiled with OpenMP support and will report the number of threads on startup. Data-conversion loops (coordinate packing, connectivity mapping) are parallelised, while the welding hash-map pass runs serially.
compareArray
This tool compares two numeric line-based data files (ASCII tables) over a selected zero-based column range and reports pass/fail per column using both relative and absolute error tolerances. It is useful for regression testing and validating solver outputs.
Usage:
Where:
file1: First input filefile2: Second input fileicolLo: First column index to compare (zero-based)icolHi: Last column index to compare (zero-based, inclusive)eps: Optional relative tolerance (default:1e-8)absEps: Optional absolute tolerance (default:1e-10)
Comparison Logic:
- For each element, computes:
- absolute error:
abs(val1 - val2) - relative error:
absError / max(max(abs(val1), abs(val2)), 1e-16) - A value is considered failed when
relError > epsandabsError > absEps, or when a NaN is detected. - Prints a per-column summary table including max relative error, row index, values, and absolute error.
Output Behavior:
- If all selected columns pass, prints a final
PASSsummary and returns exit code0. - If any selected column fails:
- writes
diff.logcontainingabs(file1 - file2)for all entries - prints diagnostic information including last-line values
- returns exit code
1
Examples:
# Compare columns 0 through 4 with default tolerances
$> compareArray.py reference.dat run.dat 0 4
# Compare columns 2 through 8 with custom relative tolerance
$> compareArray.py reference.dat run.dat 2 8 1e-6
# Compare columns 0 through 10 with custom relative and absolute tolerances
$> compareArray.py reference.dat run.dat 0 10 1e-6 1e-9
Note
Both files must have the same number of rows and columns. If dimensions do not match, the tool exits with an error.
compareHist
This tool compares two LAVA binary history (.iter) files variable-by-variable and reports pass/fail based on relative and absolute tolerances. It is useful for regression testing while allowing control over variable lists, row/column ranges, and performance-metric filtering.
Usage:
Required arguments:
file: History file to testreference_file: Reference history file
Common options:
-relTol <value>: Relative tolerance (default:1e-8)-absTol <value>: Absolute tolerance (default:1e-10)-rowRange <beg> <end>: Row range to compare (1-based; negative values index from file end)-colRange <beg> <end>: Column range to compare (1-based; negative values index from end)-varList <var1 var2 ...>: Compare only selected variable names-excludeVars <var1 var2 ...>: Exclude selected variable names-useRefVars: Compare variables listed in the reference file-comparePerf: Include performance variables (normally skipped)
Comparison Behavior:
- Variable names are matched by name between files.
- By default, performance-oriented variables are skipped (e.g., wall time, MUPS, memory, elapsed, full residual time).
- A value fails when both
relError > relTolandabsError > absTol. - The tool prints a summary table with variable name, row index, max relative error, current value, reference value, and absolute error.
Output Behavior:
- If all compared variables pass, prints a final
PASSsummary and returns exit code0. - If any variable fails:
- writes
diff.log - prints a failure summary
- returns exit code
1
Examples:
# Compare two history files with default tolerances
$> compareHist.py run.iter reference.iter
# Compare only selected variables
$> compareHist.py run.iter reference.iter -varList cl_airplane cd_airplane flowres
# Compare last 200 rows only (relative to file end)
$> compareHist.py run.iter reference.iter -rowRange -200 -1
# Include performance metrics and use custom tolerances
$> compareHist.py run.iter reference.iter -comparePerf -relTol 1e-6 -absTol 1e-9
pltCompare
This tool compares and visualizes data from multiple files by plotting specified variables against each other. It automatically detects file formats (ASCII or Tecplot) and provides flexible plotting options for CFD data analysis and comparison studies. The tool is particularly useful for comparing simulation results across different configurations, time steps, or solver settings.
Usage:
Key Features:
- Dual Format Support: Automatically handles both ASCII and Tecplot format files
- Variable Name Input: Accept variable names (for Tecplot files) or column numbers (1-based indexing)
- Per-File Variable Lookup: Handles files with different column layouts by searching each file's variable list individually
- Multiple Plot Types: Support for both line plots and scatter plots
- Custom Legends: Override default filename labels with meaningful descriptions
- Professional Styling: Grid lines, axis inversion, and publication-ready formatting
- Zone-Based Plotting: Creates separate figures for each zone in Tecplot files
- Smart Axis Labels: Uses actual variable names when available, falls back to column numbers
Command-Line Options:
--scatter: Use scatter plot instead of line plot (default: line plot)--invert-y: Invert the y-axis (useful for pressure coefficients)--legend "label1|label2|...": Custom legend labels separated by pipe symbols--saveFig filename: Save figures to files instead of displaying (adds zone names for Tecplot files)
Input Specifications:
<x_var>: X-axis variable (column number 1-based or variable name for Tecplot files)<y_var>: Y-axis variable (column number 1-based or variable name for Tecplot files)<file1> [file2] [...]: One or more data files to compare
Variable Specification:
Use either column numbers (1-based) or variable names (for Tecplot files):
# Column numbers for both ASCII and Tecplot files
$> pltCompare.py 1 4 file1.dat file2.dat
# Variable names for Tecplot files
$> pltCompare.py X/C CPAVG file1.dat file2.dat
# Mixed usage
$> pltCompare.py 1 CPAVG file1.dat file2.dat
Usage Examples:
Basic Comparison:
# Compare two ASCII files using column numbers
$> pltCompare.py 1 4 baseline.dat modified.dat
# Compare Tecplot files using variable names
$> pltCompare.py X/C CPAVG Unst.cutdata.001.dat Unst.cutdata.002.dat
Advanced Options:
# Scatter plot with inverted y-axis and custom legends
$> pltCompare.py --scatter --invert-y --legend "Experiment|CFD" X/C PCOEF exp.dat sim.dat
# Multiple files with custom labeling
$> pltCompare.py --legend "Config A|Config B|Config C" X/C CPAVG case1.dat case2.dat case3.dat
# Mixed format comparison (ASCII + Tecplot)
$> pltCompare.py 1 5 ascii_data.dat tecplot_data.dat
Rotating Machinery Analysis:
# Compare pressure coefficients at different radial stations
$> pltCompare.py --invert-y --legend "L2 Mesh|L4 Mesh" X/C CPAVG hover-L2.dat hover-L4.dat
# Skin friction comparison with scatter plot
$> pltCompare.py --scatter --legend "Baseline|Modified Tip" X/C CFAVG baseline.dat modified.dat
Time Series Comparison:
# Compare solutions at different time steps
*Figure Saving:*
```bash
# Save figures to files instead of displaying
$> pltCompare.py --saveFig comparison X/C CPAVG case1.dat case2.dat
# For Tecplot files, automatically creates separate files per zone
$> pltCompare.py --saveFig hover_analysis --legend "L2|L4" X/C CPAVG hover-L2.dat hover-L4.dat
# Creates: hover_analysis_r05.png, hover_analysis_r068.png, etc.
# Time series comparison with saved output
$> pltCompare.py --saveFig timesteps --legend "t=0.1s|t=0.2s|t=0.3s" X/C CPAVG step1.dat step2.dat step3.dat
Variable Names vs Column Numbers
For Tecplot files, using variable names (e.g., X/C, CPAVG) is more robust than column numbers, especially when comparing files from different analysis tools or versions that may have different column arrangements.
Zone Processing
When processing Tecplot files from computeSurfaceCuts, each radial station becomes a separate zone, allowing easy comparison of the same span location across different cases or time steps. Use --saveFig to automatically generate separate files for each zone.
## plotSurface
This tool visualizes and animates CFD surface data from CGNS and VTK files. It can create both static images and video sequences from time series data, with support for automatic computation of aerodynamic coefficients and flexible view configuration.
**Usage:**
Where:
- `config_file`: YAML configuration file defining visualization parameters
**Key Features:**
- Visualize surface meshes colored by any flow variable or computed coefficient
- Automatic computation of pressure coefficient (Cp), skin friction coefficient (Cf), and Mach number
- Support for both time-averaged and instantaneous flow variables
- Any variable present in the input file can be visualized directly
- Logarithmic color scaling for variables with large dynamic ranges
- Generate videos from time series data with consistent colormaps
- Flexible camera positioning with zoom regions and multiple view angles (including flipped views)
- Grid and axis display for coordinate identification
- Resolution automatically matched to view window aspect ratio
- Output organization by variable name for easy navigation
**Configuration Options:**
The configuration file uses YAML format with the following structure:
*Basic Settings:*
- `directory`: Directory containing CGNS/VTK surface files
- `file_pattern`: Glob pattern to match files (e.g., "*.cgns", "*.vtk", "Unst.surf.*.cgns")
- `variable`: Variable to visualize (supports primitive variables, computed coefficients, and any variable in the file)
- `output_directory`: Directory for output images and videos
*Video Options:*
- `create_video`: Create video from image sequence (true/false)
- `create_video_from_existing_figures`: Generate video from existing PNG files without reprocessing
- `video_fps`: Frames per second for video output
*Visualization Settings:*
- `colormap`: Matplotlib colormap name (viridis, plasma, jet, coolwarm, etc.)
- `colormap_range`: Optional explicit colormap range [min, max] for consistent scaling
- `log_scale`: Apply logarithmic (log10) scaling to the colormap (true/false)
- `show_edges`: Display mesh edges on surface
- `resolution`: Image resolution [width, height] - width auto-calculated for view windows
*View Configuration:*
- `background`: Background color (white, black, etc.)
- `show_axes`: Display coordinate axes
- `show_grid`: Show grid with tick marks for coordinate identification
- `show_bounds`: Show bounding box and print mesh bounds to console
- `view_angle`: Camera angle (isometric, xy, xz, yz) with optional '-' prefix for flipped views
- `view_window_lo/hi`: Zoom into specific region by defining bounding box
- `camera_position`: Explicit camera position (overrides other view settings)
*Reference Conditions:*
Required for computing aerodynamic coefficients (Cp, Cf) and Mach number:
- `Mach`: Reference Mach number (for coefficient calculations)
- `SpeedOfSound`: Speed of sound in m/s (for coefficient and Mach calculations)
- `rho`: Density in kg/m³
- `p`: Reference pressure in Pa
**Supported Variables:**
*Raw Variables:* Any variable present in the input files can be visualized directly, including:
- Pressure, Density, Temperature
- UVel, VVel, WVel (velocity components)
- pavg, uavg, vavg, wavg, tavg (time-averaged quantities)
- tauw (wall shear stress vector)
- tauwXavg, tauwYavg, tauwZavg (averaged wall shear stress components)
*Computed Variables:* Automatically calculated from raw data when reference conditions are provided:
- cp, cpavg (pressure coefficients)
- cf, cfavg, cfx, cfy, cfz, cfxavg, cfyavg, cfzavg (skin friction coefficients)
- Mach (Mach number computed from UVel, VVel, WVel velocity components)
**View Angles:**
Standard and flipped view directions are supported:
- `xy`: Look down the Z-axis (Z+ to Z-)
- `-xy`: Look up the Z-axis (Z- to Z+) - flipped XY view
- `xz`: Look down the Y-axis (Y+ to Y-)
- `-xz`: Look up the Y-axis (Y- to Y+) - flipped XZ view
- `yz`: Look down the X-axis (X+ to X-)
- `-yz`: Look up the X-axis (X- to X+) - flipped YZ view
- `isometric`: 3D perspective view
- `-isometric`: Flipped 3D perspective view
**Logarithmic Scaling:**
Use `log_scale: true` to apply log10 scaling to the colormap. This is useful for variables with large dynamic ranges (e.g., density, pressure, skin friction coefficients). Ensure your variable contains only positive values when using logarithmic scaling.
**Output Structure:**
The tool organizes outputs in subdirectories by variable name:
**Example Configuration File:**
```YAML
# Basic surface visualization configuration
directory: "/path/to/surface/files"
file_pattern: "Unst.surf.*.cgns"
variable: "cpavg"
output_directory: "./output"
# Video settings
create_video: true
create_video_from_existing_figures: false
video_fps: 10
# Visualization options
colormap: "RdBu_r"
colormap_range: [-1.5, 1.0] # Optional: specify explicit colormap range
log_scale: false # Set to true for logarithmic scaling
show_edges: false
resolution: [1920, 1080]
off_screen: true
# View configuration
view:
background: "white"
show_axes: true
show_grid: false
show_bounds: false
fit_to_view: true
view_angle: "isometric" # Use "-isometric" for flipped view
# Optional: zoom into specific region
# view_window_lo: [-1.0, -0.5, -0.2]
# view_window_hi: [2.0, 0.5, 0.2]
# Optional: explicit camera position
# camera_position: [[1.0, 1.0, 1.0], [0.0, 0.0, 0.0], [0.0, 0.0, 1.0]]
# Reference conditions for coefficient calculations and Mach number
reference_conditions:
Mach: 0.85
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
Examples:
Basic pressure coefficient visualization:
$> cat config_basic.yaml
directory: "/data/simulation/surfaces"
variable: "cpavg"
file_pattern: "Unst.surf.*.cgns"
reference_conditions:
Mach: 0.2
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
$> plotSurface.py config_basic.yaml
Process a single specific file:
$> cat config_single.yaml
directory: "/data/simulation/surfaces"
variable: "cpavg"
file_pattern: "Unst.surf.100.cgns" # Specify exact filename to process only one file
reference_conditions:
Mach: 0.2
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
$> plotSurface.py config_single.yaml
Skin friction coefficient with flipped view and log scale:
$> cat config_cf.yaml
directory: "/data/surfaces"
variable: "cf"
file_pattern: "*.cgns"
colormap: "plasma"
colormap_range: [1e-5, 1e-2] # Specify range in linear scale
view:
view_angle: "-xz" # Flipped XZ view
reference_conditions:
Mach: 0.85
SpeedOfSound: 340.0
rho: 1.225
p: 101325.0
$> plotSurface.py config_cf.yaml
Visualize any variable directly from the file:
$> cat config_density.yaml
directory: "/data/surfaces"
variable: "Density" # Any variable present in the file
file_pattern: "*.cgns"
colormap: "viridis"
log_scale: true # Useful for density visualization
view:
view_angle: "xy"
$> plotSurface.py config_density.yaml
View Configuration Tips:
Flipped Views: Use the '-' prefix with any view angle to look from the opposite direction. For example, -xy looks up the Z-axis instead of down, and -isometric provides a flipped 3D perspective.
Identifying Coordinates: Use show_grid: true and show_bounds: true to identify coordinates for defining your view window. The tool prints mesh bounds to help determine appropriate values for view_window_lo and view_window_hi.
Aspect Ratio: When using view_window, the image width is automatically calculated to match the aspect ratio of the viewed region. Only specify the desired height in the resolution parameter.
Camera Control: For advanced control, specify explicit camera position with format [[camera_x, camera_y, camera_z], [focus_x, focus_y, focus_z], [up_x, up_y, up_z]]. This overrides all other view settings.
Colormap Recommendations:
viridis(default): Perceptually uniform blue-yellow-greenplasma: Perceptually uniform purple-orange-yellowRdBu_r: Red-blue diverging colormap (good for Cp visualization)coolwarm: Blue-white-red diverging colormapjet: Rainbow colormap (not perceptually uniform, use with caution)
Note
The tool supports both CGNS (.cgns) and VTK (.vtk, .vtu, .vtp) file formats. Any variable present in the input files can be visualized directly without requiring reference conditions. Computed variables (Cp, Cf, Mach) require appropriate reference conditions.
Tip
Use colormap_range: [min, max] to ensure colors have the same meaning across all frames when creating videos. If not specified, the range from the last file is automatically used for consistency.
Tip
Use log_scale: true for variables with large dynamic ranges. The scalar bar will automatically display as log10(variable) to indicate logarithmic scaling is applied.
Logarithmic Scaling Tips:
When to Use: Apply log_scale: true for variables with large dynamic ranges such as:
- Density variations in compressible flows
- Pressure in high-speed flows
- Skin friction coefficients
- Any variable spanning multiple orders of magnitude
Colormap Range: When using log_scale: true, specify colormap_range values in linear scale - they will be automatically converted to logarithmic scale internally.
bc2mcr
This tool converts a LAVA boundary-condition text file into a Tecplot macro (.mcr) that renames zones and enables the corresponding boundary surfaces for visualization.
Usage:
Where:
bcfile: Boundary-condition file containing entries in the format:name gridNum jMin jMax kMin kMax lMin lMax
What the tool does:
- Reads each BC record from
bcfile(ignoring blank lines and lines starting with!) - Determines which zone face(s) each BC corresponds to (low/high in J, K, or L directions)
- Merges opposite faces into a combined "both" direction when applicable
- Generates
<bcfile>.mcrthat: - renames each Tecplot zone using BC names found for that zone
- sets I/J/K surface ranges and
SurfacesToPlotto display the BC faces
Output:
- Writes a Tecplot macro file named
<bcfile>.mcr
Examples:
# Generate Tecplot macro from a BC file
$> bc2mcr.py grid.bc
# Resulting macro file
$> ls grid.bc.mcr
Note
Zones with no matching BC records are named noBC in the generated macro.
Tip
If a zone has multiple BC names, the macro combines those names into the zone label (comma-separated), making it easier to identify multi-boundary zones during review.
LAVAParaviewPlugin
This ParaView plugin provides filters for processing LAVA cell mask data in ParaView. Two filters are available:
- Process Cart Mask — for Cartesian solver output (
vtkUniformGrid) - Process Unst Mask — for unstructured solver output (
vtkUnstructuredGrid)
Each filter reads the Mask cell data array and extracts a selected bit flag into a new named cell data array (e.g. SOLVECELL, IBGCM).
Loading the plugin:
- In ParaView, go to Tools → Manage Plugins
- Click Load New… and select
LAVAParaviewPlugin.py - To load it automatically on startup, expand the plugin entry and check Auto Load
Applying a filter:
- Select your dataset in the Pipeline Browser
- Go to Filters → Search (or Filters → Alphabetical) and search for Process Cart Mask or Process Unst Mask
- In the Properties panel, use the BitwiseValue dropdown to select the mask flag to extract
- Click Apply — the selected flag is added as a new cell data array visible in the display and color-by menus
- Select ALL from the dropdown to extract all flags simultaneously
Identifying problem cells with Threshold:
The most powerful use of these filters is to follow up with ParaView's Threshold filter to isolate cells flagged by a specific mask bit. After applying the mask filter:
- With the mask filter selected in the Pipeline Browser, go to Filters → Common → Threshold (or search for Threshold)
- Set the Scalars dropdown to the extracted array (e.g.
PROBLEM_SIZE,PROBLEM_GG,PROBLEM_GRAD) - Set the threshold range to
[1, 1]to select only cells where that bit is set - Click Apply — only the flagged cells are shown
Tip
Select ALL first to extract every flag in one pass, then use multiple Threshold filters (each connected to the same mask filter output) to inspect different problem categories side by side.
LAVACGTScriptFramework
This is a set of scripts to help curvilinear users generate a project file system containing a component-based script set to generate curvilnear overset grids, and then generate grids from a starting CAD model using Chimera Grid Tools (CGT) scripting.
The README has more information, but the basics are:
- You should have CGT and tcl/tk installed (the latter is likely required for the former anyway).
- Set the LAVACGTToolsDir environmental variable to the LAVACGTScriptFramework directory path.
- Copy the buildProjectGrid.tcl script into a directory you want your curvilinear gridding project housed in, add initial component names to the Par(fileN) component list, and run the script to give you the bare-bones file structure. See the 2026 Overset Grid Symposium curvilinear tutorial for an example of how to script the gridding process.
plotSpectra — spectra from LAVA probe and FW-H records
Computes and plots PSD, narrow-band SPL, 1/n-octave band levels, OASPL and
directivity from the binary LAVAMonitor .iter files LAVA writes: point and line probes and
monitor histories (monitor/*.data.iter) as well as the streaming FW-H observer records
(fwh/fwh.<name>.iter). Any column of any .iter file is a signal to it; time, an optional
ctu column and one column per probe or observer. Groups of observers replicated in azimuth
(FW-H rings) can be power averaged, rotor phase-lock averaged or decomposed into azimuthal modes,
and spectra of any origin are overlaid on the same axes for comparison with experiments and
other runs.
Three ways to use it, all shipped in the one plotSpectra.pyz:
| Command line (plotHist-style) | plotSpectra.pyz probe1 probe2 -F monitor/Unst.data.iter -df 10 -logx |
| YAML input driver for several figures | plotSpectra.pyz -input plots.yml (see YAML input driver) |
| User API in your own script | plotSpectra.pyz -run myplots.py or from plotspectra import ... (see User API) |
plotSpectra.pyz is installed with LAVA next to plotHist.py. It is one file: copy it anywhere,
it needs Python 3.9+ and fetches numpy, matplotlib and PyYAML into a per-user environment on its
first run. plotSpectra.pyz -h lists every option; the subcommands (convert-digitized,
convert-tecplot, digitize, psdobs) have their own -h.
Getting started
plotSpectra.pyz -createSampleData sample # a dataset to try everything on
cd sample && cat README.txt
The sample is a synthetic two-blade rotor at 5400 rpm heard by two microphones, each replicated
at 12 azimuths: fwh/fwh.rotor.iter (the record, as the solver writes it), observers.txt, an
"experimental" narrow-band spectrum experiment_SPL_df5Hz.dat, and the same comparison figure
driven the three ways, plot.sh, plots.yml and plot.py:
plotSpectra.pyz -F fwh/fwh.rotor.iter -dispVars # what is in the record
plotSpectra.pyz mic1_a000 -F fwh/fwh.rotor.iter -df 5 -logx # one observer
plotSpectra.pyz 'mic1_a*' -F fwh/fwh.rotor.iter -powerAverage -spread -mode spl -df 5 -logx -fRange 50 10000
./plot.sh # both microphones against the experiment, command line
plotSpectra.pyz -input plots.yml # the same from an input file (-dryRun prints the command lines)
plotSpectra.pyz -run plot.py # the same from a script using the library
Replace the sample's files by your own .iter record and your own table and the three drivers
carry over unchanged.
Command line
Selecting data
| option | meaning |
|---|---|
observers |
names or glob patterns ('m1_a*', m1_a000,m2_a090); default: all observers |
-F FILE |
.iter file; repeat to overlay several runs (legend = dir/file:observer) |
Styling your own curves. A selection or a -F file may carry key=value style tokens after
the pattern or path, the same keys as -compare: color, ls, lw, marker, ms, every,
label (quote values with spaces: label="LAVA M1"). Symbols instead of a line: ls=none
marker=o ms=4; on dense curves thin them with every=20 (one marker per 20 points).
plotSpectra.pyz 'm1_a000 color=b ls=- label=in-plane' 'm3_a000 color=r ls=-- label=45deg' -F fwh/fwh.s.iter
plotSpectra.pyz 'm1_a000 ls=none marker=o ms=3 every=10 label=symbols' -F fwh/fwh.s.iter
plotSpectra.pyz 'm1_a*' -powerAverage -F 'coarse/fwh/fwh.s.iter color=0.5 label=coarse' \
-F 'fine/fwh/fwh.s.iter color=k label=fine'
Two runs rarely reach a statistically steady state at the same time, so a file may also carry
its own signal window, t=T0:T1 in seconds or ctu=C0:C1 in convective time units, in place of
-tRange / -ctuRange for that file. An end left out is the record's (ctu=200: from 200 to the
end):
plotSpectra.pyz 'deg090_*' -powerAverage -F 'run1/fwh/fwh.tri.iter ctu=150:350 label=run1' \
-F 'run2/fwh/fwh.tri.iter ctu=220: label=run2'
The summary prints the span each file used. In a YAML input file the window goes with the record:
run2: 'run2/fwh/fwh.tri.iter ctu=220:'.
A file style applies to every curve from that file and its label replaces the dir/file
legend prefix; a selection style applies to the curves it picked (also to the group it forms with
-powerAverage) and overrides the file style. A selection label is used alone when the
selection produced one curve, otherwise as label:observer.
| -dispVars | list the observers, sample rate and time span of each file, then exit |
| -tRange T0 T1, -ctuRange C0 C1 | part of the record to use (seconds, or convective time units from the ctu column); a file's own t= / ctu= in its -F wins (below) |
What to plot
-mode |
curve |
|---|---|
psd (default) |
power spectral density: dB/Hz re 20 µPa (-db, default) or Pa²/Hz (-linear) |
spl |
narrow-band level = PSD·Δf per bin, dB or Pa² (the old pyPost "SPL") |
octave |
1/-octave N band levels (default 1/3), base-2 ratios (-octaveBase10 for base 10) |
time |
the pressure signals, mean removed |
directivity |
band-limited OASPL versus angle (see Directivity) |
| option | meaning |
|---|---|
-fRange FMIN FMAX |
plot limits and the band for OASPL, directivity and octave bands (does not change the estimate) |
-aWeight |
A-weighting (IEC 61672) |
-pref P |
reference pressure for dB (default 20e-6 Pa) |
Frequency axis
-xaxis |
x |
|---|---|
hz (default) |
f in Hz |
st |
Strouhal f·L/U from -stLength L -stVelocity U, else f·T_ref with the reference time recovered from the ctu column (or -refTime T) |
fref |
f / f_ref with -fref F (any reference frequency) |
bpf |
f / BPF with -rpm R -blades N (BPF = R·N/60 Hz, e.g. 5400 rpm × 2 blades = 180 Hz); the harmonics then sit at 1, 2, 3, … |
A PSD is a density, so it depends on what it is per. -density hz (the default in dB) keeps
dB per Hz on any axis; -density st re-expresses it per unit of the chosen axis (per St, per
f/f_ref, per f/BPF; the integral over the axis is preserved), which is how the NASA jet-noise sets
are given ("PSD per unit Strouhal number": 10·log10(U/D) above the per-Hz value, about 38 dB for
a 2-inch Mach 0.9 jet). -linear has always been per unit of the axis; -density hz makes it per
Hz. Comparison tables (-compare) always hold per-Hz densities and are converted the same way, so
one file serves both views.
Welch controls
| option | meaning | default |
|---|---|---|
-df 10 |
frequency resolution in Hz → segment length fs/df samples; -df match takes the bin width of the first -compare spec with df= |
whole record (one segment) |
-nperseg N |
segment length in samples | |
-nseg K |
number of overlapping segments (windows); length and df follow from the record and the overlap | |
-overlap 0.5 |
overlap fraction, 0 ≤ x < 1 | 0.5 |
-window hann |
hann, hamming, blackman, blackmanharris, flattop, bartlett, rectangular (periodic forms) |
hann |
-detrend 0 |
polynomial trend removed from the whole record: 0 mean, 1 linear, none |
0 |
-segDetrend none |
extra per-segment detrend constant / linear (scipy style); none keeps content slower than a segment, like the old pyPost tool |
none |
-fs F |
resample to this rate first (non-uniform records are resampled automatically) | record rate |
Give only one of -df, -nperseg, -nseg; the number of segments is
1 + floor((N − nperseg) / (nperseg·(1 − overlap))) and is printed in the summary line
(Welch: nperseg = ..., df = ..., segments = ..., window = ... (ENBW ...), overlap = ...).
A smaller df resolves lower frequencies and finer lines but leaves fewer segments and a noisier
estimate; more segments smooth the estimate but coarsen df. The old pyPost call
getPSD(var, tStart, tEnd, fs, binFreq, overlap) maps to
-tRange tStart tEnd -fs fs -df binFreq -overlap overlap with the default detrend.
Azimuthal copies of a microphone
Grouping. Copies are grouped by their names in the record, not by the observer file.
-groupBy chooses the rule; the summary lists the groups and their sizes.
-groupBy |
rule | azimuth of each copy |
|---|---|---|
name |
<group>_a<angle> names: m1_a090 → group m1, azimuth 90 (-groupRegex for other conventions) |
from the name |
pattern |
every selection argument on the command line is one group: 'm1_a*' 'm2_a*' → two groups; obs1,obs2,obs3 → one |
from the observer file if given, else unknown |
geometry |
observers with the same radius and elevation about -axis in the -observers file form a ring |
from the observer file |
auto (default) |
name if any selected name matches the regex (the others stay single), else geometry if an observer file is given, else pattern |
What is computed — three different questions:
| option | what it computes | when it is the right thing |
|---|---|---|
-powerAverage |
power average of the copies' PSDs, one curve per group; -spread shades the min/max envelope and the summary prints the copy-to-copy spread |
the default choice: the copies are independent realizations of a statistically axisymmetric field, so averaging the power lowers the estimate variance like more Welch segments, for tones and broadband alike. Phases, and hence the rotation rate, play no role. This is what the old averageData… script did for the jet arrays. |
-azSync RPM (-azSyncAuto) |
rotor phase-locked (synchronous) average: each copy is shifted in time by azimuth/Ω and the copies are averaged → the rotor-locked tonal signal; the residuals give the broadband spectrum; the summary prints the tonal share of the mean-square | rotors only, when you want the tonal/broadband split. RPM is signed with the sense in which the azimuth angle increases; -azSyncAuto tries both senses and keeps the better. Needs the azimuth of every copy. |
-azModes M |
PSD of the azimuthal Fourier modes m = −M…M of the ring (m = 0 axisymmetric, ±m helical co-/counter-rotating with the azimuth angle); the modes sum to the ring average |
jets: which modes radiate; rotors: harmonic n of a B-bladed rotor lives in mode m = nB only, a clean check of the record. Needs a uniform full ring with known azimuths: from m1_a090-style names or the -observers file; a pattern group without a geometry is refused, since its copies would only be numbered in file order. |
Averaging the raw time signals without the phase shift is deliberately not offered: it is the
m = 0 mode and cancels everything that rotates.
Directivity
-mode directivityalone plots the band-limited OASPL of every observer against the azimuth angle taken from its name, one curve per group (polar plot;-cartesianDirectivityfor level versus angle).- With
-powerAverage -observers observers.txtevery group is placed at the elevation (rotor convention) or polar angle (-angleKind polar, jet convention) of its copies about-axis/-origin, giving the classic OASPL-versus-angle plot from azimuth-averaged levels. Elevation is positive toward+axis(polar angle 0); give the axis as-1,0,0if your convention counts the downwash side negative.
The observer file is the FW-H observers file (x, y, z[, name] per line). Names are matched
case-insensitively (the file may say M1_a000, the record m1_a000).
Output
| option | meaning |
|---|---|
-saveFig NAME |
write NAME.png (no window unless -show); -dpi |
-dumpData FILE |
write the plotted curves as a Tecplot-style ASCII table (format below) |
-noPlot |
compute and print only |
-quiet |
no summary table |
-fontSize 14, -legendSize 12 |
font size of axis and tick labels, and of the legend (default legend = fontSize − 2) |
-noInfo |
drop the small "Welch: df = …, segments …" note in the figure corner |
-logx -logy -xscale k -yscale k -yRange Y0 Y1 -doSubplot -legend ... -title ... |
plot cosmetics |
-input FILE [-dryRun] [-only NAME ...] |
figures described in a YAML file, see YAML input driver |
-run SCRIPT [ARG ...] |
run your own script with the library importable, see User API |
Dump format. -dumpData writes a Tecplot-readable ASCII table: # comment lines stating
the quantity and units, a TITLE, a VARIABLES line that names the columns, a ZONE line, then
one row per frequency. The first column is the frequency axis in the plotted unit (f_Hz, St
or f_over_fref), followed by one column per curve named after the curve (observer, group,
m1 tonal, m1 m=+2, ...), in the plotted quantity (e.g. PSD in dB/Hz, SPL in dB per bin):
# plotSpectra psd (PSD dB/Hz re 2e-05 Pa): first column = f_Hz, then one column per curve
TITLE = "plotSpectra psd (PSD dB/Hz re 2e-05 Pa)"
VARIABLES = "f_Hz" "m1" "m3"
ZONE T = "spectra.dat", I = 7347
0.0000000000e+00 5.6922486728e+01 5.6899857066e+01
...
Curves on different frequency grids (e.g. two files with different Δf) get their own
f_Hz_<curve> column each.
Every run prints, per observer or group, the band-limited OASPL from the PSD, the share of the total power inside the band, the overall level straight from the time signal (a consistency check: they agree when no band is set), the peak frequency and its level.
Examples
# any .iter file: a point probe's pressure from the monitor history
plotSpectra.pyz probe_p1 -F monitor/Unst.data.iter -df 10 -logx
# FW-H observer records
plotSpectra.pyz -F fwh/fwh.rotor.iter -dispVars
plotSpectra.pyz m1_a000 m1_a090 -F fwh/fwh.rotor.iter -df 5 -logx -fRange 20 5000
plotSpectra.pyz 'm1_a*' -F fwh/fwh.rotor.iter -mode octave -octave 3 -fRange 20 20000 -saveFig m1_oct
plotSpectra.pyz m1_a000 -F run1/fwh/fwh.s.iter -F run2/fwh/fwh.s.iter -xaxis fref -fref 90
plotSpectra.pyz m1_a000 -F fwh/fwh.rotor.iter -linear -xaxis st -dumpData psd_st.dat
# azimuthal copies
plotSpectra.pyz 'm1_a*' 'm3_a*' -F fwh/fwh.rotor.iter -powerAverage -spread -df 20 -logx -fRange 45 5000
plotSpectra.pyz 'obs*' -F fwh/fwh.ring.iter -powerAverage -groupBy pattern -df 20
plotSpectra.pyz -F fwh/fwh.ring.iter -powerAverage -groupBy geometry -observers observers.txt -axis z
plotSpectra.pyz 'm1_a*' -F fwh/fwh.rotor.iter -azSync 5400 -azSyncAuto -df 20 -fRange 45 2000
plotSpectra.pyz 'm1_a*' -F fwh/fwh.rotor.iter -azModes 4 -df 22.5 -fRange 45 500
plotSpectra.pyz -F fwh/fwh.rotor.iter -mode directivity -powerAverage -observers observers.txt -axis x -fRange 45 5000
Comparing with experimental data
The approach is always the same: bring every dataset into one table format, then make the simulation match the experiment in quantity, bin width, frequency axis, distance and observer set, never the other way round. The tool has the time signal and can recompute its spectrum any way the experiment was reduced; the experiment is a published curve and cannot be re-reduced.
The table format
-compare SPEC overlays curves from an ASCII table in the same format — a -dumpData file from
another run, or experimental spectra: frequency in Hz in the first column, one curve per further
column, names from the VARIABLES line (a header-less numeric table gets col2, col3, ...).
Repeat -compare for several files. Each SPEC carries its own selection and styling:
-compare 'FILE [vars=A+B] [color=k+r] [ls=--] [lw=1.2] [marker=o] [label=exp] [df=5]' # long form
-compare 'FILE:vars:color:ls:label:df' # short form
| key | meaning | default |
|---|---|---|
vars=A+B |
columns to overlay (+ or , separated) |
all columns, or -compareVars |
color=k+r |
matplotlib colors, one per variable or one for all (k, red, 0.4, #1f77b4) |
matplotlib cycle |
ls=-- |
line style -, --, -., :; none draws the markers only |
-- |
lw=1.2 |
line width | 1.0 |
marker=o |
marker (o, s, ^, x, +, ., ...) |
none |
ms=4 |
marker size in points | 3 |
every=20 |
one marker every N points (thins the symbols on dense data) | every point |
label=exp |
legend label (used alone for one variable, as exp:var for several) |
file name, or -compareLabel |
df=5 |
the file holds narrow-band SPL at this bin width [Hz] | -compareDf, else none |
panel=NAME |
with -doSubplot: draw on the panel of the curve labelled NAME (a selection label=, or the resolved name) |
first panel |
Short-form fields may be left empty: exp.dat:mic1+mic2:k:-- or exp.dat::::exp:5.
The globals -compareVars, -compareDf, -compareLabel (one per file, in order) are the defaults
for specs that do not set them.
Curves on their own frequency grids. A curve may bring its own frequency column named
f_Hz_<curve> (the form -dumpData writes for curves on different grids and the form
convert-digitized produces from digitizer output with f, level column pairs). -compare uses it when present and falls back to the first column otherwise; shorter
curves are NaN-padded.
Getting a dataset into the format
Whatever the source, the result is one ASCII table, frequency in Hz first, one column per curve, in the units the file states. Four ways to get there:
A curve digitized from a figure. Most published spectra are only available as a plot.
plotSpectra.pyz digitize fig.png -xcal 100:px1 10000:px2 -ycal 0:py1 70:py2 -color blue -logx -name M1 -out m1.dat
extracts a curve of a given colour from a PNG, pixel by pixel, after you give it two ticks per
axis (value:pixel, -logx for a logarithmic axis); plotSpectra.pyz convert-digitized digitized.csv exp.dat -names M1 M3
turns the output of any plot digitizer (pairs of f, level columns, one pair per curve, comma or
whitespace separated) into the table, every curve on its own frequency column. Note the bin width the authors used; it goes on the
-compare spec as df=. Expect ±1 dB at peaks and ±1.5 dB on the floor from the digitizing
itself, and thin dense point sets with every= when plotting symbols.
Tecplot block files, e.g. the NASA jet-noise sets. The consensus / SHJAR set-point files
(D2a_SP7.dat and friends: variables Log(St), Polar angle, PSD (dB), St; one row of
Strouhal points per polar angle; PSD per unit Strouhal number, lossless, at 100 jet diameters)
are converted by plotSpectra.pyz convert-tecplot into one table with an f_Hz column and one
PSD column per polar angle (a050 … a160, angle from the jet inlet axis, dB/Hz):
plotSpectra.pyz convert-tecplot D2a_SP7.dat D2a_SP7_psd.dat -refTime 1.63871e-4 # the run's D/U
plotSpectra.pyz convert-tecplot D2a_SP7.dat D2a_SP7_psd.dat -velocity 310 -length 0.0508 -rObs 50
The Strouhal axis is mapped to Hz with the run's D/U (-refTime, the T_ref plotSpectra
prints, or -velocity/-length), the per-St level becomes per Hz (+10·log10(T_ref)), missing
bins (-999) become NaN, and -rObs (observer distance in diameters) applies the spherical
spreading shift from the file's 100 D. Overlay it on the ring at the same polar angle:
plotSpectra.pyz 'deg055_*' -F fwh/fwh.tri.iter -powerAverage -mode psd -df 100 -logx \
-compare 'D2a_SP7_psd.dat vars=a055 color=k ls=none marker=o ms=3 label=experiment' # dB/Hz vs Hz
plotSpectra.pyz 'deg055_*' -F fwh/fwh.tri.iter -powerAverage -mode psd -df 100 -xaxis st -density st -logx \
-compare 'D2a_SP7_psd.dat vars=a055 color=k ls=none marker=o ms=3 label=experiment' # per St vs St, as the NASA plots
Another LAVA run. -dumpData run1.dat writes the plotted curves of one run as a table; a
later run overlays it with -compare 'run1.dat label=run1'. Curves computed at a different Δf
carry their own frequency column and are handled like any other table.
Legacy post-processor output. plotSpectra.pyz psdobs ... turns the spectra written by the
old FW-H post-processor (PSDObs.sampleNN.dat: frequency, then one column per observer with the
azimuthal copies of each polar point as the fast index) into this table format. It averages the
mean-square values over the sample files and over the -ncirc copies (the legacy averaging, with
the copy-to-copy spread reported), applies the Hann recovery factor (-coef, default √(8/3) as in
averageDataNewWithOctaveBands_correct.py), drops the leading bins (-skip, default 2) and writes
the same quantities plotSpectra plots: -mode psd|spl|octave, -db/-linear, -xaxis
hz|st|fref|bpf (with -stLength/-stVelocity, -fref, -rpm/-blades), -fRange, -aWeight; -perAzimuth
adds every copy as <name>_aXXX, -oaspl writes the band-limited OASPL per polar angle, -saveFig
a quick look. With the legacy settings it reproduces the old *_tec.dat PSD columns to 1e-9 dB.
plotSpectra.pyz psdobs -F 'PSDObs.sample*.dat' -ncirc 36 -names M1 M3 -angles 0 45 -mode spl -o legacy_spl
plotSpectra.pyz 'm1_a*' -F fwh/fwh.rotor.iter -powerAverage -mode spl -df match -xaxis bpf -rpm 5400 -blades 2 \
-compare 'legacy_spl.dat vars=M1 df=8 ls=none marker=o ms=2 every=3 label=legacy'
Same quantity and the same bin width
The comparison data are plotted as the same quantity as the tool's curves. Experimental data are
usually narrow-band SPL at a stated bin width; with df= the tool converts: to PSD in dB/Hz it
subtracts 10·log10(df), to SPL at its own Δf it adds 10·log10(Δf / df). Without df= the file
is taken to hold the plotted quantity already (PSD in dB/Hz when plotting PSD).
A narrow-band spectrum depends on its bin width in two opposite ways. Broadband power is
spread evenly, so its level per bin grows with Δf (+10·log10 Δf) while its PSD (per Hz) does
not depend on Δf. A tone puts all its power into one bin (about 1.5 with a Hann window), so
its level per bin is the tone level whatever Δf is, while its PSD peak falls as 1/Δf. No
single correction therefore makes both agree between two different bin widths: converting SPL at
5 Hz to PSD lines up the broadband and leaves the tool's tone peaks 10·log10(Δf/5) dB low.
Since the tool has the time signal, the clean answer is to compute with the experiment's Δf:
-df 5 (or -df match, which takes the bin width from the first -compare spec with df=) and
-mode spl, so both curves are SPL per 5 Hz bin with no conversion at all. The price is fewer
Welch segments (a 0.23 s record gives one 5 Hz segment), i.e. a noisier broadband estimate, which
is exactly the trade-off the experiment also faced with its record length. Interpolating a
spectrum from one Δf to another does not help: a tone captured in a 20 Hz bin cannot be
redistributed into 5 Hz bins, only a new estimate from the time data can. The tool prints its
Δf, segment count and window in the summary, in the figure corner (-noInfo to suppress) and in
the header of every -dumpData file, and warns when a comparison's df= differs from its own.
# like for like: SPL per 5 Hz bin on both sides, no conversion
plotSpectra.pyz 'mic1_a*' -powerAverage -F fwh/fwh.rotor.iter -mode spl -df match -logx -fRange 100 10000 \
-compare 'experiment_SPL_df5Hz.dat vars=mic1 color=k ls=-- df=5'
# broadband only: PSD, the experiment converted to dB/Hz (tone peaks will not line up)
plotSpectra.pyz 'mic1_a*' -powerAverage -F fwh/fwh.rotor.iter -mode psd -df 20 -logx \
-compare 'experiment_SPL_df5Hz.dat vars=mic1 df=5'
# 1/3-octave bands: both sides integrated to the same bands, bin width no longer matters
plotSpectra.pyz 'mic1_a*' -powerAverage -F fwh/fwh.rotor.iter -mode octave -octave 3 -fRange 50 20000 \
-compare 'experiment_SPL_df5Hz.dat vars=mic1 df=5'
Octave bands are the robust choice when the bin widths differ a lot or the experiment is only available in bands: both sides are integrated to the same band edges, so broadband and tones are treated alike.
Same axis, distance and weighting
- Frequency axis. Published jet spectra are usually per unit Strouhal number against
St: plot with-xaxis st -density st(-stLength/-stVelocity, or the reference time from the record) and convert the dataset to Hz with the run'sD/Uas shown above. Rotor spectra are often against harmonics of the blade-passing frequency:-xaxis bpf -rpm R -blades N. Keep comparison tables in Hz and let the tool scale them; the same file then serves every view. - Distance. Experiments are reported at a microphone radius or extrapolated to a standard
distance (the NASA jet sets to 100 jet diameters, lossless). Place the LAVA observers where the
microphones were, or shift the dataset by spherical spreading,
20·log10(r_data / r_obs)(-rObsofconvert-tecplotdoes this). The tool applies no atmospheric absorption, so prefer lossless data or short distances. - Reference pressure and weighting. dB are re 20 µPa (
-prefto change); A-weighted levels with-aWeighton both sides. - Record length. The lowest frequency and the number of Welch segments follow from the record:
a 0.2 s record gives one segment at Δf = 5 Hz. Flush the transient before sampling (restart or
startctufor FW-H surfaces,-tRange/-ctuRangehere) rather than clipping afterwards.
Same observers
- Azimuthal copies. A microphone replicated around the axis of an axisymmetric mean flow gives
independent realizations:
-powerAverageaverages their PSDs into one curve per microphone (-spreadshades the copy-to-copy band). Average powers, never complex spectra or time signals: tones of a rotor carry a phase that rotates with the observer and would cancel. - One panel per observer.
-doSubplotwithpanel=<label>on each-comparespec puts every experimental curve on the panel of its simulated counterpart; the input file'ssweepwrites those specs for you (the sample'splots.yml). - Directivity.
-mode directivity -powerAverage -observers observers.txt -axis x -fRange ...gives the band-limited OASPL against polar or elevation angle from the azimuth-averaged levels, the usual form of an experimental directivity plot.
When curves disagree
- Same quantity and same Δf on every curve? (
-mode spl -df match,df=on every narrow-band file; or octave bands.) - Simulation: transient flushed before sampling, record long enough for the Δf asked for? The summary prints the segment count and Δf of every curve.
- Dataset: units of the file (SPL per bin, PSD per Hz, per St), its bin width, distance and any correction (lossless, free-field) read from the source, not assumed.
- Observers at the microphone positions, azimuth copies averaged, same polar-angle convention
(from the inlet axis or from the jet axis;
-angleKind). - Digitized curves: ±1 dB at the peaks, more on the floor; compare trends and levels, not wiggles.
Worked examples
# rotor: one microphone, 36 azimuth copies power averaged, SPL at the facility's 5 Hz bins, as symbols
plotSpectra.pyz 'mic1_a* color=b' -F fwh/fwh.rotor.iter -powerAverage -mode spl -df match -logx \
-compare 'facility_SPL_df5Hz.dat vars=mic1 ls=none marker=o ms=3 every=25 color=k label=experiment df=5'
# the same against the harmonics of the blade-passing frequency, two runs overlaid
plotSpectra.pyz 'mic1_a*' -powerAverage -mode spl -df match -xaxis bpf -rpm 5400 -blades 2 -fRange 90 3000 \
-F 'coarse/fwh/fwh.rotor.iter color=0.5 label=coarse' -F 'fine/fwh/fwh.rotor.iter color=k label=fine' \
-compare 'facility_SPL_df5Hz.dat vars=mic1 color=r ls=-- df=5'
# jet: one polar angle against the NASA set point, per unit Strouhal number
plotSpectra.pyz 'deg055_*' -F fwh/fwh.tri.iter -powerAverage -mode psd -df 100 -xaxis st -density st -logx \
-compare 'D2a_SP7_psd.dat vars=a055 color=k ls=none marker=o ms=3 label=experiment'
# every observer on its own panel from an input file: the sample's plots.yml does this with a sweep
plotSpectra.pyz -input plots.yml
YAML input driver
plotSpectra.pyz -input plots.yml reads a YAML file that describes several figures. Each figure
is expanded into an ordinary command line and run through the command-line front end, so the
file and the command line mean exactly the same thing; -dryRun prints those command lines
instead of running them (paste one back to tweak it by hand), -only NAME ... picks figures.
Paths in the file are relative to the file. All figures are shown together at the end when any
of them asks for a window.
defaults: # CLI options for every figure: the option name without the dash,
powerAverage: true # `flag: true` for switches, a list for options with several values
df: 100
xaxis: st
density: st
logx: true
fRange: [400, 50000]
records: # name -> .iter file, optionally with a style and window ('path label=fine ctu=200:')
run01: fwh/fwh.tri.iter
compare: # name -> comparison table and its default keys (the -compare keys)
nasa: {file: D2a_SP7_psd.dat, ls: none, marker: o, ms: 3, label: exp}
figures:
- name: all_angles # {name} in templates; default figure1, figure2, ...
records: [run01] # or record: run01 (a name from `records`, or a path)
sweep: {angle: ["055", "090", "140"]}
select: "deg{angle}_* color={color} lw=1.2 label={angle}deg" # one selection per sweep value
compare: "nasa vars=a{angle} color={color} panel={angle}deg" # one -compare per sweep value
doSubplot: true # any other key is a CLI option for this figure (overrides defaults)
saveFig: plots/{name}
show: true
- Sweeps.
sweepmaps keys to lists;selectandcompareentries (strings or lists of strings) are formatted once per sweep step with{key}, plus{name},{i}(the step index) and{color}(a 23-colour cycle, matplotlib's tab20 and three dark extras). An entry without a placeholder is emitted once. Several sweep keys are zipped and must have the same length. Quote values that look like numbers: YAML reads055as a number. - Named comparisons. A
compareentry whose first word is a name from the file'scomparemap takes that entry's keys and adds or overrides thekey=valuepairs that follow; anything else is passed to-compareunchanged (a file path with keys, or the short form). - Hiding curves from the legend.
label=_nolegend_(matplotlib skips labels starting with an underscore), useful when many experimental symbols share the colour of their simulation curve. recordsvalues may carry a style the way-Fdoes;-onlywith an unknown name lists the figures in the file.
The sample's plots.yml is a complete file with two figures; plotSpectra.pyz -input plots.yml -dryRun
shows the commands it generates.
User API
The package is importable straight from the zipapp. The simplest route is to let the .pyz
run your script, which also gives it the tool's own numpy/matplotlib environment:
plotSpectra.pyz -run myplots.py [args ...] # sys.argv = [myplots.py, args ...], plotspectra importable
Or put the .pyz (or the checkout) on sys.path and use any python that has numpy and
matplotlib. The sample's plot.py is a complete script that works both ways.
import sys; sys.path.insert(0, "/path/to/plotSpectra.pyz") # not needed under -run
from plotspectra import read_iter, compute_spectrum, spectra_from_file, directivity, db
rec = read_iter("fwh/fwh.rotor.iter") # rec.names, rec.time, rec["m1_a000"], rec.ref_time()
sp = compute_spectrum(rec.time, rec["m1_a000"], df=10.0, window="hann", overlap=0.5, detrend_order=0)
sp.f, sp.psd # Hz, Pa^2/Hz sp.psd_db(), sp.spl, sp.spl_db()
sp.oaspl(50, 5000) # dB re 20 uPa sp.oaspl(a_weight=True)
sp.octave(3, 20, 20e3) # (fc, fl, fu, band power Pa^2)
sp.scaled("st", ref_time=rec.ref_time()) # Strouhal axis + density per St
rec, spectra = spectra_from_file("fwh/fwh.rotor.iter", ["m1_a*"], ctu0=15, df=10)
angles, levels, names = directivity(spectra, fmin=50, fmax=5000)["m1"]
from plotspectra import azimuth_average, azimuth_sync, azimuth_modes, build_groups
avg = azimuth_average(spectra)["m1"] # Spectrum; avg.meta["n"], ["spread_db"]
groups = build_groups(list(spectra), "pattern", patterns=["m1_a*"]) # or "geometry" with observer_angles(...)
avg2 = azimuth_average(spectra, groups=groups)["m1_a*"] # needed for rings not named <group>_a<angle>, e.g. deg055_01
sync = azimuth_sync(rec, spectra, rpm=5400, auto_sign=True, df=20)["m1"] # ["tonal"], ["broadband"], ["tonal_fraction"]
modes = azimuth_modes(rec, spectra, mmax=4, df=22.5)["m1"] # {m: Spectrum}
Lower level: welch(x, fs, df=..., window=..., overlap=...) returns (f, psd, info);
welch_segments gives the per-segment complex spectra; power_average, sync_average,
azimuthal_modes, octave_bands, band_integrate, a_weighting_db, make_scale,
read_observer_file, observer_angles, write_ascii, write_iter.
Conventions
- PSD is one-sided with energy-consistent window scaling
1/(fs·Σw²)(identical toscipy.signal.welch(scaling="density")):Σ PSD·Δf = <p'²>for a stationary signal, whatever the window. Windows are the periodic (DFT-even) forms. - Narrow-band SPL is
PSD·Δf(Pa² per bin), the convention of the previous pyPost tool with its energy-preserving (EFT) window factor. A pure tone spreads over ~1.5 bins with a Hann window; the sum over the peak bins gives the tone level, and OASPL is exact. - dB:
10·log10(P / pref²),pref = 20 µPa(-prefto change). - Band integrals treat each bin as a constant density over
[f−Δf/2, f+Δf/2], so band edges and 1/n-octave bands narrower than Δf are handled consistently. - A-weighting: IEC 61672-1 (0 dB at 1 kHz, −19.1 dB at 100 Hz).
- Azimuthal modes:
P_m = (1/N) Σ_i X_i e^{+i m ψ_i}per Welch segment, so a patterncos(ωt − mψ)rotating toward increasing azimuth is mode+m; the phase-locked average shifts copies by an exact Fourier phase.
Running Databases
LAVA provides a Python script (setup.py) for setting up and running databases (parametric sweeps) of simulations. It reads a setup file and a run matrix, creates per-run sub-directories with parameterized input files and PBS job scripts, and optionally submits the jobs.
Usage
setup.py <setup_file> # Generate directories and PBS scripts only
setup.py <setup_file> run # Generate and submit jobs via qsub
setup.py <setup_file> debug # Generate PBS scripts as if on a NAS front-end (useful for local testing)
setup.inputs
The setup file specifies the run configuration. All parameters have defaults and can be omitted if the default is acceptable. An example:
run_matrix = "run_matrix.txt"
run_path = "runs/"
inputs_template = "run.inputs"
grids_path = "/path/to/grids"
sym_links = ["../../grid.cgns"]
copy_files = []
exec_name = "lavacart.3D.NS1"
num_nodes = 10
pbs_queue = "long"
pbs_gid = "your_project_gid"
pbs_model = "mil_ait"
pbs_walltime = "8:00:00"
pbs_source = "module use /swbuild/LAVA/LAVA_modules\nmodule load LAVA"
All Parameters
| Parameter | Default | Description |
|---|---|---|
run_matrix |
run_matrix.txt |
Path to the run matrix file |
run_path |
runs/ |
Output directory where all run sub-directories are created |
inputs_template |
run.inputs |
Template input file for LAVA |
grids_path |
(empty) | Path to a directory containing grid files; a symlink is created per run using the grid column from the run matrix |
sym_links |
["../grid.cgns"] |
List of files/patterns to symlink into every run directory |
copy_files |
[] |
List of files/directories to copy into every run directory |
exec_name |
lavacart.3D.NS1 |
Base executable name; architecture suffix (e.g. AVX2, AVX512) is appended automatically per node type |
num_nodes |
10 |
Number of nodes to request |
num_mpi |
(auto) | MPI ranks per node; defaults to a per-model value if not set |
num_omp |
(auto) | OpenMP threads per MPI rank; derived from hyperthreadfac and cores/node if not set |
hyperthreadfac |
1 |
Hyperthreading multiplier used to compute num_omp automatically |
pbs_queue |
devel |
PBS queue name |
pbs_gid |
a1455 |
PBS group/project ID |
pbs_model |
(required) | Node model (see table below) |
pbs_walltime |
2:00:00 |
Requested wall-clock time |
pbs_shell |
/bin/bash |
Shell for the PBS script (/bin/bash or /bin/csh) |
pbs_source |
module use .../LAVA_modulesmodule load LAVA |
Commands written into the PBS script after cd $PBS_O_WORKDIR, used to set up the environment. Override with a custom source command if needed. |
pbs_pinning |
mbind |
Process pinning tool for CPU nodes: mbind or omplace |
pbs_email |
False |
Send PBS email notifications (True/False) |
pbs_emailaddress |
$USER@nas.nasa.gov |
Address for PBS email notifications |
pbs_lock |
False |
Write a RUNNING/FINISHED lock-file guard into the PBS script |
pbs_multi_model |
[] |
List of additional node models to generate PBS scripts for; SBU-equivalent node counts are computed automatically |
pbs_filesystems |
(empty) | Value for #PBS -l site=needed=<filesystems> (e.g. lustre) |
| do_interactive | False | Keep the job alive after the solver finishes (for interactive debugging) |
| do_several_tries | False | Wrap the executable with /u/scicon/tools/bin/several_tries |
Supported Node Models (NAS)
The script automatically selects the correct MPI launch command, architecture suffix, and select-line format for each node type.
| Model | System | Cores | GPUs | Mem (GB) | SBU | MPI Launch |
|---|---|---|---|---|---|---|
bro_ele |
Electra (pfe) | 28 | — | 128 | 1.00 | mpirun -npernode |
sky_ele |
Electra (pfe) | 40 | — | 192 | 1.59 | mpirun -npernode |
cas_ait |
Aitken (afe) | 40 | — | 192 | 1.64 | mpirun -npernode |
rom_ait |
Aitken (afe) | 128 | — | 512 | 4.06 | mpirun -npernode |
mil_ait |
Aitken (afe) | 128 | — | 512 | 4.38 | mpirun -npernode |
tur_ath |
Athena (athfe) | 512 | — | 1024 | 12.19 | mpiexec -ppn --cpu-bind none |
mil_a100 |
Cabeus (cfe) | 128 | 4× A100 | 500 | 37.86 | mpiexec -N --bind-to none |
gh200 |
Cabeus GH200 (cghfe) | 72 | 1× GH200 | 460 | 18.34 | mpiexec -N + numactl |
pbs_multi_model
Setting pbs_multi_model generates one PBS script per listed node type. The number of nodes for each model is scaled automatically to maintain an equivalent SBU cost relative to the reference pbs_model. When more than one model is listed, pbs_lock is enabled automatically so that only one script can run at a time.
This produces run_mil_ait.pbs, run_tur_ath.pbs, and run_mil_a100.pbs in each run directory.
run_matrix.txt
The run matrix is a whitespace-delimited text file. The first row is the header (column names); subsequent rows are parameter values. Each row produces one run sub-directory.
Column names that match setup parameters (num_nodes, pbs_model, pbs_queue, pbs_walltime, etc.) override the corresponding setup-file value for that run. Any other column names are treated as template substitution variables.
Append * to a column name to exclude it from the sub-directory name.
Example:
dt* num_steps* levels num_nodes*
8.00e-5 3125 5 5
4.00e-5 6250 6 5
2.00e-5 12500 7 5
1.00e-5 25000 8 10
5.00e-6 50000 9 25
2.50e-6 100000 10 50
1.25e-6 200000 11 400
This creates directories named run_levels5/, run_levels6/, …, one per row.
inputs_template
The template input file is a standard LAVA input file with substitution placeholders of the form ${PARAM}, where PARAM matches a column header in run_matrix.txt. The script replaces all placeholders with the corresponding value for each row.
Example Directory Structure
After running setup.py setup.inputs, the output looks like:
Curvilinear User Guide
Introduction
The LAVA-Curvilinear solver, also known as LAVACurv is developed at
the NASA Ames Research Center. It solves the
Navier-Stokes equations on structured-curvilinear overset grids assuming
laminar, Reynolds-Averaging, LES filtering, or hybrid RANS-LES.
Steady-state problems are solved using an approximate Newton-Krylov
solver with ILU preconditioned GMRES.
Unsteady problems are solved using either an implicit dual-time stepping method with
options for first or second order backward differencing for time
discretization or explicit time-stepping methods like TVD-RK3.
The fluid is assumed to obey an ideal gas equation of state of the form:
rho = p/(RGAS*T) and h = Cp*T
where
p - Pressure
T - Temperature
rho - Density
h - Enthalpy
Alternative equations of state that can be expressed as a function of pressure and temperature can also be utilized.
A summary of some key features of LAVACurv are given below:
- Hybrid MPI-OpenMP implementation
- Parallel I/O for grids, volume, surface, iso-surface, and probe solutions
- Structured multi-block as well as general overset connectivity is supported
- 1st through 4th order convective flux discretization options available
- Implicit and explicit time integration
- Sliding mesh capabilities for turbomachinery applications (see tutorials)
- General grid motion via a user defined function also available
- Discrete adjoint solver as well as design optimization framework for aerodynamic shape optimization (see tutorials)
Details on how to set up your environment and run the LAVACurv solver can be found
Setup and Utilities. For a list of supported executables.
QuickStart
This guide will take you through running the LAVACurv solver for a steady-state RANS
solution around an airfoil at transonic conditions.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver and utilities installed and your' environment properly setup, see LAVA Installation Guide
- Chimera Grid Tools (CGT) installed for optional mesh building
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | grid file |
| grid.bc | grid bc file |
| grid.b2b | grid block-to-block file |
| run.yaml | solver input file |
Obtaining the Grid
The easiest way is to download the grid directly from above, but alternatively you can generate a structured curvilinear grid. This section assumes you have Chimera Grid Tools (CGT) installed on your computer. First a structured curvilinear grid must be generated. In this case we download a grid from the AIAA Drag Prediction Workshop. Download the following zip file:
Once downloaded, unzip the directory and find the Plot3D grid file grid_OAT15A_Deck.x.
Now copy and past the following grided input file into a file named grided.inp located in
the same location as the Plot3D grid file:
grid.x containing the ONERA OAT15A airfoil grid
generated by Sebastian Deck from ONERA1. This is a multi-block structured curvilinear
grid containing 4 zones: 1305x3x224, 160x3x224, 227x3x160, 160x3x224 for a total of
1200960 grid points. Here is an image of the grid system
If you do not have CGT installed on your machine and want to use some
other grid generation software, then you will need to:
- rotate the grid by 90.0 degrees about the x-axis
- copy the 2D slice in both the positive y and negative y directions by 0.5
- concatenate the three 2D slices in the spanwise (y-axis) direction such that the first slice is at y = -0.5, the second slice is at y = 0.0, and the last slice is at y = 0.5
- swap indices between k and l (the 2nd and 3rd indices) such that k is in the span direction and l is in the wall normal direction
Setting up Boundary Conditions, Block-2-Block Conditions, and the Input File
Now that we have the grid, which is in meters, with a chord of 0.23 meters and a span of 1.0 meter, we can set up the boundary condition file.
At this point we simply need to associate a name for particular subsets of the grid. Below is the boundary condition file for this grid, grid.bc:
! Name GridNumber Jmin Jmax Kmin Kmax Lmin Lmax
!*********** *********** ***** ***** ***** ***** ***** *****
wall 1 1 -1 1 -1 1 1
far 1 1 -1 1 -1 -1 -1
symm 1 1 -1 1 1 1 -1
symm 1 1 -1 -1 -1 1 -1
far 2 1 1 1 -1 1 -1
far 2 1 -1 1 -1 -1 -1
symm 2 1 -1 1 1 1 -1
symm 2 1 -1 -1 -1 1 -1
wall 3 1 -1 1 -1 1 1
far 3 1 -1 1 -1 -1 -1
symm 3 1 -1 1 1 1 -1
symm 3 1 -1 -1 -1 1 -1
far 4 -1 -1 1 -1 1 -1
far 4 1 -1 1 -1 -1 -1
symm 4 1 -1 1 1 1 -1
symm 4 1 -1 -1 -1 1 -1
With the boundary condition file complete, the block-2-block connectivity file can be generated with the following LAVA utility program command:
This will generate the followinggrid.b2b file:
!----------------------------------------------------------------------------------------------------------------------------
! BlkID js je ks ke ls le DonorID djs dje dks dke dls dle tx ty tz
!----------------------------------------------------------------------------------------------------------------------------
1 1 1 1 -1 1 -1 2 -1 -1 1 -1 1 -1 1 2 3
1 -1 -1 1 -1 1 -1 4 1 1 1 -1 1 -1 1 2 3
2 -1 -1 1 -1 1 -1 1 1 1 1 -1 1 -1 1 2 3
2 1 -1 1 -1 1 1 3 -1 -1 1 -1 -1 1 -3 2 1
3 1 1 1 -1 1 -1 4 1 -1 1 -1 1 1 -3 2 1
3 -1 -1 1 -1 1 -1 2 -1 1 1 -1 1 1 3 2 -1
4 1 1 1 -1 1 -1 1 -1 -1 1 -1 1 -1 1 2 3
4 1 -1 1 -1 1 1 3 1 1 1 -1 1 -1 3 2 -1
The final preprocessing step is to create an input yaml file for running the solver. Details of the inputs can be found at
Curvilinear User Guide-YAML Input File. For brevity we simply ask you to save the run.yaml file from the tutorial files section.
Running LAVACurv
With grid.x, grid.bc, grid.b2b, and run.yaml as input files we are ready to perform
steady-state RANS analysis on the ONERA OAT15A airfoil. Here we walk through setting up an example
PBS script to run on the NASA Advanced Supercomputing (NAS) computer using a Sky Electra node.
The commands are similar no matter where you decide to run this example.
The first step is to copy the aforementioned files into a working directory on Pleiades.
Next create a PBS file named run_sky.pbs with the following contents (note this is for c-shell users, see
Setup and Utilities for other options):
#PBS -S /bin/bash
#PBS -N oat_rans_curv
#PBS -l select=1:ncpus=40:mpiprocs=2:model=sky_ele
#PBS -l walltime=2:00:00
#PBS -q normal
#PBS -l site=needed=/home6+/nobackupp27
#PBS -j oe
#PBS -W group_list=<your project group ID>
log_file="run.log"
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
unset F_UFMTENDIAN
cd $PBS_O_WORKDIR
mpiexec -npernode 2 mbind.x -t 20 lavacurv.3D.NS1.AVX2 run.yaml |& tee -a ${log_file}
run.out. An example of what your run.out file should look like upon completion can be downloaded below
Checking the Run
In order to plot the residual convergence history, use the plotHist.py python command
The convergence history of the integrated forces and momements along with the maximum Mach number in the domain can be plotted by
Here we see that the flow solver converged the L2 norm of the flow residual by the requested 8-orders of
magnitude yielding a lift coefficient of 9.914e-01, drag coefficient of 3.8800e-02, pitching moment coefficient
of -1.401e-01, and maximum Mach number of 1.377e+00. A plot of the x-direction velocity on a cutting
plane at y=0 is shown below.

You should now have a very basic understanding of how to use the LAVACurv flow solver and are ready to move on
in the documentation :)
Relevant Publications
-
Deck, S., and Renard, N., "Towards an Enhanced Protection of Attached Boundary Layers in Hybrid RANS/LES Methods," Journal of Computational Physics, Vol. 400, 2020, p. 108970. https://doi.org/10.1016/j.jcp.2019.108970 ↩
Curvilinear Solver Inputs
The YAML file format is used for specifying the information required.
The documentation below lists the name and type of each option. If an option is flagged as required then it must be included when the parent block is present. The default values and lower/upper bounds are also included for variables that have them. If an option is flagged as mutable then it can be modified on a solver restart. Each tab level in the YAML file should be 2 spaces. Blocks which can take multiple sub-blocks of an entry argument are prefaced by a -. Keywords in the YAML input file are case-insensitive.
Grid
- This section defines the location of basic input files associated with the structured overset grid generated for the problem.
grid:
curv:
gridFile: <required>
BCFile: <required>
fileType:
B2BFile:
interpFile:
IBINDFile:
restartFile:
RANSFile:
initFile:
loadInfoOnInit:
subsetFile:
initWithExactSolution:
initVelocitiesWithXYZ:
-
curv
- Category of options to work with structured overset grids.
-
gridFile (
string(fileName),required)- Input file name for the grid file. This will be a Plot3D file. Refer to file formats page for details. More file formats may become available in future software releases. It is customary to use
.xor.x.ihcextension for Plot3D files. The.ihcextension is used in the output grid that gets generated after running overset grid connectivity usingcurvSolver > task: connectivity.
- Input file name for the grid file. This will be a Plot3D file. Refer to file formats page for details. More file formats may become available in future software releases. It is customary to use
-
BCFile (
string(fileName),required)- File specifying where the boundaries of the computational domain are. It is customary to use the
.bcextension for BC files. These can be generated through LAVA custom CGT Tools. - Example format shown below:
- These names will be assigned a BC type in
BC > names: <name>.
- File specifying where the boundaries of the computational domain are. It is customary to use the
-
fileType (
string,default="plot3d")- Accepted Values: [
"plot3d"] - Input grid file type. More file formats may become available in future software releases.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
- Accepted Values: [
-
B2BFile (
string(fileName),default="")- This file contains the block-to-block interface indices. This can be auto generated through connectivity by setting
B2BExtractor > extractB2Bs: trueor by using the B2BExtractor tool.
- This file contains the block-to-block interface indices. This can be auto generated through connectivity by setting
-
interpFile (
string(fileName),default="")- Interpolation file for fringe stecil donors. Required if grid has overset. This file is usually called
INTOUTwith no extensions. The INTOUT file is generated usingcurvSolver > task: connectivity
- Interpolation file for fringe stecil donors. Required if grid has overset. This file is usually called
-
IBINDFile (
string(fileName),default="")- File containing known immersed boundary indices. Can also contain trip and transition trip strips represented as negative indices.
-
restartFile (
string(fileName),default="")- Restart file allows for a continuation of the solution. This preserves history of the solution. Cannot be used with
initFileoption. Restart files are written asrestart.#######.rstwhere the number is based on number of iterations or timesteps.restart.latest.rstwill be linked to the latest written restart files. If the user wants to construct a file to use as a restart file it must be a stream access Plot3D function file with the.rstextension.
- Restart file allows for a continuation of the solution. This preserves history of the solution. Cannot be used with
-
RANSFile (
string(fileName),default="")- This file is used when the user wants to load in a pre-computed Reynold-Averaged Navier-Stokes solution. It will generate dummy qVec and turVec data and initialize a solution. It can be used in conjuction with
user.F90for special user-defined boundary conditions and/or source terms.
- This file is used when the user wants to load in a pre-computed Reynold-Averaged Navier-Stokes solution. It will generate dummy qVec and turVec data and initialize a solution. It can be used in conjuction with
-
initFile (
string(fileName),default="")- Plot3D function file to use as initial conditions for the simulation. It must have the following fields in this order:
pressure, velocityX, velocityY, velocityZ, temperature, turVar1(optional), andturVar2(optional). The restart file written by the code is also valid. This differs from a restart file in that no history from the previous simulation is preserved. - NOTE: If using
loadInfoOnInit(described below) then theinitFileshould have a.rstextension.
- Plot3D function file to use as initial conditions for the simulation. It must have the following fields in this order:
-
loadInfoOnInit (
boolean,default=False)- Read the info file when using init to perform free stream correction. This option allows for a restart file to be used for initializing a simulation where the history is not wanted in the new simulation. The information includes freestream conditions and more. An example where this is needed is when a solution is being initialized from a different angle of attack.
- NOTE: The user should remove all other data in
restart.#######.infothat is not freestream values for restarting unsteady cases when using this option.
-
subsetFile (
string(fileName),default="")- File used to define grid surface subsets and associated names for the subsets. It is used for defining actuator regions as well as for specifying surface output on non-BC surface subsets. If used for actuator regions, each region must have a unique subset name.
-
initWithExactSolution (
boolean,default=False)- Initialize the flow with a user-supplied dynamic link library (DLL) file defining the exact solution. Specifying a restart or initialization file along with this option will give an error.
-
initVelocitiesWithXYZ (
boolean,default=False)- Initialize the velocities in the X, Y, and Z directions with the X, Y, and Z grid coordinates, respectively, after all other initializations have been performed. This is useful for debugging.
Overset
- This section defined parameters associated with performing grid overset connectivity.
overset:
writePostHoleCutGrid:
viscousStencilRepairDist:
repairInviscidStencils:
useExistingHoleCut:
performHoleCutExplicitly:
exactPointMatching:
optimizeOverlap:
useClusters:
orphanBallSearchLim:
IBOrphanSearchDist:
rayExtensionMaxIter:
debugNode:
octTreeFileName:
surfPaintBlankingNIter:
octTreeFloodIter:
octTreePadSides:
octTreeFloodSeeds:
-
pt:
boundarySurfaces:
periodicB2BsAreBoundaries:
inOutFlowsAreBoundaries:
internalFlow:
nSphereSurface:
nSphereVolume:
curvatureFactor:
edgeFactor:
octTreeMinDepth:
octTreeMaxDepth:
octTreeCubesPerEdge:
priority:
explicitSurface:
explicitJKL:
writeExplicitCutters:
writeBodyCutEdges:
writeSurfDeviation:
writeSurfBCClasses:
writeUncertainNodes:
writeBlankedSurfaceInfo:
writeNameGroupedBCs:
writeDistBandOrphData:
distBandOrphBandLims:
distBandOrphWriteAllHigher:
distBandOrphWriteAllLower:
zoneSpecific:
-
zones:
explicitJKL:
curvatureFactor:
edgeFactor:
octTreeMinDepth:
octTreeMaxDepth:
octTreeCubesPerEdge:
priority:
explicitSurface:
explicitBlanking:
-
type: <required>
zones:
paintSource:
xMin:
xMax:
rotationAngle:
radius:
radiusInner:
nFacet:
fileName:
fileNames:
fileType:
offset:
operator:
variable:
value:
origin:
normal:
axis1Pt:
axis2Pt:
-
writePostHoleCutGrid (
boolean,default=False)- Allows grid to be written post hole-cut, prior to any donor search or overlap optimization. The affix of this grid file will be 'rhc' for 'raw' hole cut. This can help when debugging those latter connectivity steps as you can use the written grid with useExistingHoleCut below to skip the holecut step of the algorithm.
-
viscousStencilRepairDist (
float,lower bound=0.000,default=0.1000E-02)- When donors are being searched for near a viscous wall during connectivity's donor search processess, or during wall-distance calculations, viscous surfaces must be projected onto each-other to properly account for the differences in which two grids can represent the same underlying surface. If a grid node is within this distance of a viscous wall node projected for this correction, it is also shifted. This value should be sized according to:
-
- A) The size of the viscous geometry;
-
- B) The expected boundary layer height.
- A good rule of thumb for this is the physical distance between a viscous wall node and its ~30th node from the wall in a curvilinearly-normal direction.
-
repairInviscidStencils (
boolean,default=False)- Perform viscous stencil repair projections during donor search for inviscid walls as well.
-
useExistingHoleCut (
boolean,default=False)- If true, connectivity will not run hole cutting at all, and assume the iblank array, if provided in the grid, has properly defined all hole regions and move directly to donor search.
-
performHoleCutExplicitly (
boolean,default=False)- If true, connectivity will not run implicit hole cutting, instead using the explicit cutters defined in the
.yamlinput file.
- If true, connectivity will not run implicit hole cutting, instead using the explicit cutters defined in the
-
exactPointMatching (
boolean,default=False)- If overlapped surfaces are exactly point-matched then some in/out tests may be performed improperly. This options activates certain double-checking routines to try and handle this.
-
optimizeOverlap (
boolean,default=True)- Perform a fringe-reduction by blanking portions of grid if the resulting blanked grid can find better donors for its new fringes. Default is to optimize.
-
useClusters (
boolean,default=True)- Multiblock-connected blocks cannot cut each other.
-
orphanBallSearchLim (
integer,default=10)- If an orphan isnt immersed, a search is performed to find nearby tiles to get a closest pt. This is the number of possible accepted tiles. If orphans arent finding nodes you would expect then increasing this may help, at a performance hit. Note that this should be at least 1.
-
IBOrphanSearchDist (
integer,default=3)- If an orphan is immersed, it will attempt to find a local donor node by locally stencil walking. This search distance is the jkl distance walked away from the immersed orphan.
- NOTE: If this distance is < 3 then no walk search is performed.
-
rayExtensionMaxIter (
integer,default=10)- In/out surface ray-casts by default only try to travel a certain distance within the surface octree. In very rare cases some nodes will need more iterations of this to properly find if they are in/out of the surface geometry.
-
debugNode ([
integer, ...],default=0)- Format is
[iBlk, j, k, l]. If this is on, then information related to this node will be dumped to the screen and various optional information files will be written.
- Format is
-
octTreeFileName (
string,default="")- If this is specified then the surface octree is written.
-
surfPaintBlankingNIter (
integer,default=10)- The max number of master iterations of the surface-painting blanking process using the flooded surface octree.
-
octTreeFloodIter (
integer,default=1000)- Maximum number of flood iterations performed using the octree for hole cutting. Increase if flooding fails.
-
octTreePadSides ([
boolean,boolean,boolean,boolean,boolean,boolean],default=[True, "True, "True, "True, "True, "True])- States if the sides of the surface octree used for flood-based in/out checking should be padded off the geometry. Entries are for the [xMin, yMin, zMin, zMax, yMax, zMax] sides. This should only be false if you know a side of the geometry is open and planar.
-
octTreeFloodSeeds
- Specify locations where to start flooding surface octree.
-
pt ([
float,float,float],default=[0.000, 0.000, 0.000])- Physical
[X, Y, Z]location of where to start flooding surface octree for internal flows.
- Physical
-
boundarySurfaces ([
string, ...],default=[""])- Surfaces defining closed body for hole cutting.
-
periodicB2BsAreBoundaries (
boolean,default=False)- If this is True, connectivity will treat non-self-point-matched b2bs (translated or rotated) as portions of the closed boundary. This currently does not support partial b2bs.
-
inOutFlowsAreBoundaries (
boolean,default=False)- If this is True, connectivity will treat inlets and outlets as portions of the closed boundary. Does not count Riemann. Specifying
boundarySurfacesignores this option.
- If this is True, connectivity will treat inlets and outlets as portions of the closed boundary. Does not count Riemann. Specifying
-
internalFlow (
boolean,default=False)- If this is True, connectivity will treat inlets, outlets, and non-self-point-matched b2bs (translated or rotated) as portions of the closed boundary. In order to use this, at least one entry must exist in
octTreeFloodSeeds. SpecifyingboundarySurfacesignores this option.
- If this is True, connectivity will treat inlets, outlets, and non-self-point-matched b2bs (translated or rotated) as portions of the closed boundary. In order to use this, at least one entry must exist in
-
nSphereSurface (
integer,lower bound=1,default=100)- Number of fail-safe hemispherical rays used for surface cutting.
-
nSphereVolume (
integer,lower bound=1,default=100)- Number of fail-safe hemispherical rays used for volume cutting.
-
curvatureFactor (
float,default=1.000)- A value which is representative of the average surface curvature. The smaller, the less lenient the surface overlap checks will be w.r.t. curvature-based projection distance when determining if two surfaces are the 'same'. Increasing this value will make overlapping of surfaces easier, and can help if edge-cutting is occuring near the boundary. It stops being very effective after a value of 5.
-
edgeFactor (
float,default=0.1000)- A value which is representative of the average surface edge length. The smaller, the less lenient the surface overlap checks will be w.r.t. grid-scaled normal-based projection distance when determining if two surfaces are the 'same'.
-
octTreeMinDepth (
integer,default=11)- Minimum number of levels to build the surface octree.
-
octTreeMaxDepth (
integer,default=15)- Maximum number of levels to build the surface octree.
-
octTreeCubesPerEdge (
float,default=2.000)- Resolution of surface octree. Default is usually OK.
-
priority (
float,default=1.000)- Change priority of all blocks. Can be helpful when making only a few blocks lower priority in the zone options section.
-
explicitSurface (
integer,default=0)- Can be 0 or 1. Explicit surfaces can only be blanked by explicit hole cuts (EHCs). Because of this, they should never have any 'geometry-internal' faces.
-
explicitJKL ([
integer,integer,integer,integer,integer,integer],default=0)- A range of a block which cannot be implicitly blanked. Can still be blanked by EHCs. Supplied list specifies
[jMin, jMax, kMin, kMax, lMin, lMax]. This should be used as a last-resort hot-fix to prevent blanking when the user has no idea why something is being blanked.
- A range of a block which cannot be implicitly blanked. Can still be blanked by EHCs. Supplied list specifies
-
writeExplicitCutters (
boolean,default=False)- Write all EHCs in Tecplot format with names
ehcSurface.###.plt. Writing can fail for INTEL compilers.
- Write all EHCs in Tecplot format with names
-
writeBodyCutEdges (
boolean,default=False)- Write all edges cut by implicit surface to
bodyCutEdges.dat.
- Write all edges cut by implicit surface to
-
writeSurfDeviation (
boolean,default=False)- Write the deviation (offset distances) of the surface mesh to
surfaceDeviation.plt.
- Write the deviation (offset distances) of the surface mesh to
-
writeSurfBCClasses (
boolean,default=False)- Write all 'classes' of surface mesh BCs to
surfaceBCClasses.plt.
- Write all 'classes' of surface mesh BCs to
-
writeUncertainNodes (
boolean,default=False)- Write all volume-cut uncertain nodes not near the wall to
uncertainNodesNotNearWall_#.dat.
- Write all volume-cut uncertain nodes not near the wall to
-
writeBlankedSurfaceInfo (
boolean,default=False)- Write relevant overset information of blanked surface to
blanked_surf_info.plt.
- Write relevant overset information of blanked surface to
-
writeNameGroupedBCs (
boolean,default=False)- Write all the BCs of the grid, grouped by name to
nameGroupedBCs.plt.
- Write all the BCs of the grid, grouped by name to
-
writeDistBandOrphData (
boolean,default=False)- Writes orphan donor and receiver info into
distBandedOrphanInfo.dat. Each zone of written file contains orphans whose distance to its interpolation point is within one of the distance bands defined inoverset > distBandOrphBandLims. Additionally, all orphans with distances from their interpolations below or above the defined bands can be written to their own zones ifoverset > distBandOrphWriteAllLoweroroverset > distBandOrphWriteAllHigherare defined. Each Tecplot zone contains either the donor cells or the interpolation vectors for a specific band, and all zones have fields representing blockID, j, k, l, where jkl for donor cells pertains to the lower-left cell corner.
- Writes orphan donor and receiver info into
-
distBandOrphBandLims ([
float, ...],default=[0.1000E-02, 0.1000E-01, 0.1000, 0.2000, 0.5000])- A value list which is used to band orphan data written to
distBandedOrphanInfo.datifoverset > writeDistBandOrphDatais true. Distance bands are defined between successive values, which must be positive and stricly increasing.
- A value list which is used to band orphan data written to
-
distBandOrphWriteAllHigher (
boolean,default=True)- Writes all orphan data for orphans which have an interpolation distance above the highest band to a single Tecplot zone pair inside
distBandedOrphanInfo.datifoverset > writeDistBandOrphDatais defined as true.
- Writes all orphan data for orphans which have an interpolation distance above the highest band to a single Tecplot zone pair inside
-
distBandOrphWriteAllLower (
boolean,default=True)- Writes all orphan data for orphans which have an interpolation distance below the lowest band to a single tecplot zone pair inside
distBandedOrphanInfo.datifoverset > writeDistBandOrphDatais defined as true. - WARNING: In the presence of many orphans, most of them may be banded here and could cause Tecplot to become slow.
- Writes all orphan data for orphans which have an interpolation distance below the lowest band to a single tecplot zone pair inside
-
zoneSpecific
- Entries in
zoneSpecificwill allow individual treatment of zones (overset optimization priority, etc.) and is the easiest way to fix issues with grid quality. -
zones ([
string, ...],default=[""])- List of zones to have values specifically set for.
-
explicitJKL ([
integer,integer,integer,integer,integer,integer],default=0)- Refer to
overset > explicitJKLabove.
- Refer to
-
curvatureFactor (
float,default=1.000)- Refer to
overset > curvatureFactorabove.
- Refer to
-
edgeFactor (
float,default=0.1000)- Refer to
overset > edgeFactorabove.
- Refer to
-
octTreeMinDepth (
integer,default=11)- Refer to
overset > octTreeMinDepthabove.
- Refer to
-
octTreeMaxDepth (
integer,default=15)- Refer to
overset > octTreeMaxDepthabove.
- Refer to
-
octTreeCubesPerEdge (
float,default=2.000)- Refer to
overset > octTreeCubesPerEdgeabove.
- Refer to
-
priority (
float,default=1.000)- The higher this value, the better the stencil 'quality' of the zone is artifically increased, which makes it more likely to be retained during overlap optimization.
-
explicitSurface (
integer,default=0)- Refer to
overset > explicitSurfaceabove.
- Refer to
- Entries in
-
explicitBlanking
- Entries here will explicitly blank zone nodes within geometric shapes defined either by triangulations or simple polygons.
-
type (
string,required)- Accepted Values: [
"box","cone","sphere","surfile","jkl","clip"] - The type of EHC shapes. All defined EHC options will cut both surface and volume, and are applied prior to IHC or optimization.
- A) Geometric-type EHC options available:
box-
- A box that is specified using
xMinandxMaxcoordinates.
- A box that is specified using
cone-
- A cone that is specified using start and end coordinates/radii
xMin/rMinandxMax/rMax.
- A cone that is specified using start and end coordinates/radii
sphere-
- A sphere that is specified using centroid
xMinand radiusrMin.
- A sphere that is specified using centroid
- All geometric-type EHC options may be rotated about the Cartesian axes using the
rotationAngleentry. - B) File-type EHC options available:
surFile-
- A closed surface triangulation can be specified using the
fileNameandfileTypeoptions.
- A closed surface triangulation can be specified using the
- C) Grid-type EHC options available:
jkl-
- A
[j,k,l]range may be specified usingxMinandxMaxinteger (computational) coordinates.
- A
- D) Clipping-type EHC options available:
clip-
- A clipping plane can be specified using the
operatoroption, paired with thevalue + variable,origin + normal, ororigin + axis1Pt + axis2Ptoptions.
- A clipping plane can be specified using the
- Clipping lenience is set by the
offsetvalue. If no zones are provided, then this EHC will become a true clipping plane, i.e., it will limit the sizing of the connectivity octree.
- Accepted Values: [
-
zones ([
string, ...],default=[""])- List of zones to blank with this EHC object. If this is ommited then all grids will be used.
-
paintSource (
boolean,default=False)- Defines if the explicit hole cutter will generate sources for the surface-blanking painting routine. If this is True, then the cutter will only cut the surface, NOT the volume, and all surface faces cut will be marked to initiate the flooding routines. This option should only be used for connectivity hot-fixes.
-
xMin ([
float,float,float],default=[0.000, 0.000, 0.000])- First point supplied to a geometric EHC object:
-
- A) The lower jkl curvilinear grid index set.
-
- B) The lower left corner of a box.
-
- C) The starting point of a cone.
-
- D) The centroid of a sphere.
-
xMax ([
float,float,float],default=[1.000, 1.000, 1.000])- Second point supplied to a geometric EHC object:
-
- A) The upper jkl curvilinear grid index set.
-
- B) The upper right corner of a box.
-
- C) The ending point of a cone.
-
rotationAngle ([
float,float,float],default=[0.000, 0.000, 0.000])- Defines axis rotation
[xrot, yrot, zrot]for geometric EHC objects (box,cone,sphere) around the barycenter.
- Defines axis rotation
-
radius ([
float, ...],default=[1.000, 1.000])- Radii at
xMinandxMaxwhen EHC type isconeor radius atxMinwhen EHC type issphere.
- Radii at
-
radiusInner ([
float, ...],default=[1.000, 1.000])- Format is
[xMin, xMax]. Inner tube radii atxMinandxMaxwhen EHC type iscone, or inner radius of shell atxMinwhen EHC type issphere.
- Format is
-
nFacet (
integer,default=16)- Number of facets on EHC regions defined by curved geometric shapes [
cone,sphere].
- Number of facets on EHC regions defined by curved geometric shapes [
-
fileName (
string(fileName),default="file")- Filename for the closed EHC surface. Chosen over
overset > explicitBlanking > fileNames.
- Filename for the closed EHC surface. Chosen over
-
fileNames ([
string, ...],default=["file"])- Filenames list for the closed EHC surface. Must be same
fileType.
- Filenames list for the closed EHC surface. Must be same
-
fileType (
string,default="tecplot")- Accepted Values: [
"tri","plot3d","tecplot"] - Filetype of the closed EHC surface.
tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
Tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
offset ([
float, ...],default=[0.1000E-11])- The offset distance from the EHC geometry within which nodes of the defined zones will also be blanked. This can be a list of offsets for each zone.
-
operator (
string,default="<")- Accepted Values: [
"<",">"] - The direction applied to a
clipEHC type. <-
- Values for which
variableis below thevaluespecified are clipped.
- Values for which
>-
- Values for which
variableis above thevaluespecified are clipped.
- Values for which
- Accepted Values: [
-
variable (
string,default="y")- Accepted Values: [
"x","y","z"] - The X, Y or Z value for plane of
clipEHC type. Must also supplyvalue. x-
- Clip using a constant-X plane.
y-
- Clip using a constant-Y plane.
z-
- Clip using a constant-Z plane.
- Accepted Values: [
-
value (
float,default=0.000)- An X, Y or Z value for plane of
clipEHC type. Must also supplyvariable.
- An X, Y or Z value for plane of
-
origin ([
float,float,float],default=[0.000, 0.000, 0.000])- The origin of the
clipEHC type. Must also supplynormaloraxis1Pt+axis2Pt.
- The origin of the
-
normal ([
float,float,float],default=[0.000, 0.000, 0.000])- The normal of the
clipEHC type. Must also supplyorigin.
- The normal of the
-
axis1Pt ([
float,float,float],default=[0.000, 0.000, 0.000])- The local x axis of the
clipEHC plane from the origin. Must also supplyorigin+axis2Pt.
- The local x axis of the
-
axis2Pt ([
float,float,float],default=[0.000, 0.000, 0.000])- The local y axis of the
clipEHC plane from the origin. Must also supplyorigin+axis1Pt.
- The local y axis of the
Reference Conditions
- This section defines parameters related to the freestream reference conditions.
referenceConditions:
pressure: <required>
temperature: <required>
umag: <required>
alpha: <required>
beta:
qref:
cp:
gamma:
SLConst:
SLRef:
prandtl:
area:
length:
span:
momentCenter:
turvarfac:
turvarfac_k:
turvarfac_w:
tu:
hrms:
additionalNormalizations:
-
names:
area:
length:
momentCenter:
-
pressure (
float,required,lower bound=0.000,mutable)- The reference pressure of the fluid in Pascal.
-
temperature (
float,required,lower bound=0.000,mutable)- The static temperature of the freestream in Kelvin.
-
umag (
float,required,mutable)- The magnitude of the freestream velocity in meters per second
-
alpha (
float,required,mutable)- The angle of attack of the freestream condition relative to the body frame of the geometry. This assumes a standard orientation of 'span in y'.
-
beta (
float,default=0.000)- The side-slip angle of the freestream condition relative to the body frame of the geometry. This assumes a standard orientation of 'span in y'.
-
qref (
float,mutable,default=-1.000)- Overides the dynamic pressure from \(\rho_{ref} U_{ref}^2\), only for load normalization. Used for hovering cases when freestream velocity is zero and \(Q_{ref}\) should use tip velocity.
-
cp (
float,mutable,default=1005.)- Specific heat at constant pressure of the working fluid in Joule per kilogram. Default corresponds to air.
-
gamma (
float,mutable,default=1.400)- Ratio of specific heats. Default corresponds to air.
-
SLConst (
float,mutable,default=0.1450E-05)- Constant used in Sutherland's Law for computing viscosity. Default corresponds to air.
-
SLRef (
float,mutable,default=110.0)- Reference temperature used in Sutherland's Law. Default corresponds to air.
-
prandtl (
float,mutable,default=0.7200)- Prandtl number of the working fluid. Default corresponds to air.
-
area (
float,lower bound=0.000,default=1.000)- Reference area used for normalization of aerodynamic coefficients.
-
length (
float,lower bound=0.000,mutable,default=1.000)- Reference length used for normalization of aerodynamic moments. Also used in reference timescale estimates in some upwind/centered blending functions.
-
span (
float,lower bound=0.000,mutable,default=1.000)- Reference length used for normalization of aerodynamic roll moments.
-
momentCenter ([
float,float,float],mutable,default=[0.000, 0.000, 0.000])- Point from which to take the aerodynamic moments about.
-
turvarfac (
float,mutable,default=3.000)- Used for SA turbulence model and should be set between 3-5 for fully turbulent simulations, 0.1 for free/fixed-transition simulations.
-
turvarfac_k (
float,mutable,default=0.2250E-06)- Used for two equation turbulence models. Non-dimensional farfield or ambient turbulent kinetic energy (will be multiplied by \(U_{ref}^2\) within the code).
-
turvarfac_w (
float,mutable,default=125.0)- Used for two equation turbulence models. Non-dimensional farfield or ambient specific turbulence dissipation rate (will be multiplied by \(U_{ref} / L_{ref}\) within the code).
-
tu (
float,mutable,default=0.2400)- Freestream turbulence intensity (%) using the Langtry-Menter transition model.
-
hrms (
float,mutable,default=0.1000E-05)- Used in Langtry-Menter transition model. Represents the surface roughness for the \(C_f\) correlations:
- ~ 0.25e-6m > highly polished,
- ~ 0.50e-6m > polished,
- ~ 3.33e-6m > painted.
-
additionalNormalizations
- This section may be used to set surface-specific reference length, area and moment center for user-specified surface families.
-
names ([
string, ...],default=["default"])- Names specified here correspond to the boundary condition subsets specified in
grid > curv > BCFilefor which to apply the custom normalizations to.
- Names specified here correspond to the boundary condition subsets specified in
-
area (
float,default=1.000)- Refer to
referenceConditions > area.
- Refer to
-
length (
float,default=1.000)- Refer to
referenceConditions > length.
- Refer to
-
momentCenter ([
float,float,float],default=[0.000, 0.000, 0.000])- Refer to
referenceConditions > momentCenter.
- Refer to
Curvilinear Solver
- This section defines general parameters associated with the curvilinear flow solver.
curvSolver:
equations: <required>
tileSize:
wallDistCorrectionOffset:
overlapComm:
matrixScheduling:
task:
verbose:
echoRestart:
integrationWeights:
overwriteIntegrationWeights:
integrationWeightsDir:
USURPBoundaries:
writeIBINDFile:
writeIBGeomTecplot:
initializeImmersedBoundaries:
zoneOptions:
-
zones:
file:
B2BTol:
userSharedObject:
writeRecordMarkersInGrids:
initializeBoundaryLayer:
initializeBoundaryLayerHeight:
outputDir:
metricExchange:
fixBadRecon:
checkForPBS:
PBSStopBuffer:
iterFileName:
autoLoadBalance:
debugCommFileName:
saveIBADTInMem:
useGPU:
streamDirection:
groundDirection:
exactSolutionErrorVariables:
exactSolutionErrorExcludeBCNames:
nImmersedWallOffsetPts:
writeIBWallModelInterpNodes:
writeProbeInterpNodes:
configGPUWarningsAsErrors:
integratePRef:
usePolarInterpInSlidingRings:
debugSlidingRings:
-
equations (
string,required)- Accepted Values: [
"rans","euler","laminar","les"] - The type of equations to solve:
RANS-
- Reynolds-Averaged Navier-Stokes (RANS) or Hybrid RANS-LES.
Euler-
- Euler equations (ignores viscous flux evaluation and turbulence model).
Laminar-
- Navier-Stokes equations (ignores turbulence and/or SGS model).
LES-
- Large eddy simulation (LES).
- Accepted Values: [
-
tileSize ([
integer,integer,integer],lower bound=4,default=18)- The size of the tiles, including one level of halos. The optimum tilesize is primarily a function of the computer architecture, not the grid. The default size should give near optimum performance on modern x86 architectures.
-
wallDistCorrectionOffset (
float,lower bound=0.000,default=0.1000E-01)- This is the offset distance from wall boundaries within which a more accurate/corrective search is performed to account for geometric features such as overlap and ambiguously close surface proximity (for wall-normal calculations).
-
overlapComm (
boolean,default=True)- Flag specifying if the code should overlap communication and computation. This should generally be set to true unless the effect of this option is to be investigated.
-
matrixScheduling (
string,default="p2p")- Accepted Values: [
"barrier","p2p"] - The type of matrix scheduling to use.
p2p-
- Should always be used as it is faster.
barrier-
- Should only be used for comparison purposes.
- Accepted Values: [
-
task (
string,default="solve")- Accepted Values: [
"solve","verify","broyden","mms","connectivity","writesolution","adjoint","panelweights","writeibind","verifybcgpu","verifyresgpu","verifysolvegpu","writenamegrpbc","checkstencils"] - The main task to be performed by the solver:
solve-
- Solve the specified equations.
verify-
- Tests YAML inputs to ensure validity and formatting. It is recommended to run this task to verify input options prior to running the code.
Broyden-
- Solve the specified equations until the target values in the Broyden input section are satisfied.
MMS-
- Perform Method of Manufactored Solutions for solver verification
connectivity-
- Perform overset grid connectivity.
writeSolution-
- Read restart, init, or set freestream and write the requested restart, volume, surface, etc. output(s).
adjoint-
- Solve the adjoint equations.
panelWeights-
- Perform overlapper procedure to compute surface panel weights for surface integrations.
writeIBInd-
- If immersed boundaries are present, this task will write a file named
IBINDcontaining information on which cells fall inside the immersed boundaries. This file can be provided ingrid > curv > IBINDFileso that this tagging does not have to be regenerated.
- If immersed boundaries are present, this task will write a file named
verifyBCGPU: Compare the state vector of the CPU and GPU after applying boundary condition(s).verifyResGPU-
- Compare the residual vector of the CPU and GPU.
verifySolveGPU-
- Compare the solution vector of the CPU and GPU after solving on each architecture separately.
writeNameGrpBC-
- Write boundary condition(s) to a Tecplot file and group them by name.
- Accepted Values: [
-
verbose (
boolean,default=True)- Flag to request extra solver output.
-
echoRestart (
boolean,default=True)- Replay monitor data to STDOUT on restart.
-
integrationWeights (
string,default="overlapper")- Accepted Values: [
"none","usurp","overlapper"] - The method used to integrate on viscous surfaces.
none-
- This should be used if the entire grid does not contain overlapping surfaces.
USURP-
- This makes a call to Penn State's polygonal clipping algorithm USURP which is available as part of Chimera Grid Tools (CGT). It is limited to having viscous surfaces defined on J = 1 or L = 1 surfaces.
overlapper-
- LAVA-internal tool which utilizes an internally developed polygonal clipping algorithm.
- Accepted Values: [
-
overwriteIntegrationWeights (
boolean,default=False)- If false and the requested panel weights file already exists then panel weight generation will be skipped unless
curvSolver > taskis set topanelWeights.
- If false and the requested panel weights file already exists then panel weight generation will be skipped unless
-
integrationWeightsDir (
string,default="")- The directory in which all integration weights files are placed. If
curvSolver > integrationWeightsisusurp, this defaults tousurp/, and likewise tooverlapper/forcurvSolver > overlapper.
- The directory in which all integration weights files are placed. If
-
USURPBoundaries ([
string, ...],default=[""])- Use this option when running
curvSolver > integrationWeights: USURPto specify over which surfaces to perform integrations over. These names correspond to the subset names specified in the boundary condition file specified ingrid > curv > BCFile.
- Use this option when running
-
writeIBINDFile (
boolean,default=False)- If the
IBINDfile has not been provided ingrid > curv > IBINDFileand this is true, write theIBINDfile after immersed boundaries are assessed.
- If the
-
writeIBGeomTecplot (
boolean,default=False)- Write a Tecplot file with all immersed geometry to
immBndGeom.plt.
- Write a Tecplot file with all immersed geometry to
-
initializeImmersedBoundaries (
boolean,default=False)- Initialize relevant fields to respect all immersed boundary targets (zero velocity, target temperature, etc).
-
zoneOptions
- Use this section to apply options to select zones only.
-
zones ([
string, ...],default=[""])- Zone number(s) to apply zone-based options to.
-
file (
string,default="")- Name of YAML file containing specific options to use for specified zones.
-
B2BTol (
float,lower bound=0.1000E-15,upper bound=1.000,default=0.1000E-09)- Block-to-block (B2B) face-center proximity tolerance.
-
(
string,default="")- Path to shared object file which contains compiled user-provided subroutines. For example grid motion, source terms, etc.
-
writeRecordMarkersInGrids (
boolean,default=True)- Used to control if record markers are written in the Plot3D grid file(s) output by the code after connectivity or during moving grid simulations.
-
initializeBoundaryLayer (
string,default="none")- Accepted Values: [
"none","false","true","ramp","zero"] - Used to initialize a simple boundary layer profile near no-slip walls. This may increase robustness for steady-state solves, but is typically not necessary.
noneorfalse-
- Does not apply a boundary layer profile correction.
ramportrue-
- Applies a boundary layer profile near no-slip walls with a fall-off based on the wall-distance. The user can control the distance away from no-slip walls over which this correction is applied via the
initializeBoundaryLayerHeightoption.
- Applies a boundary layer profile near no-slip walls with a fall-off based on the wall-distance. The user can control the distance away from no-slip walls over which this correction is applied via the
zero-
- Zeroes out the velocity field near no-slip walls. The user can control the distance away from no-slip walls over which this correction is applied via the
initializeBoundaryLayerHeightoption.
- Zeroes out the velocity field near no-slip walls. The user can control the distance away from no-slip walls over which this correction is applied via the
- Accepted Values: [
-
initializeBoundaryLayerHeight (
float,lower bound=0.000,default=0.1000)- Distance from no-slip walls to construct velocity profiles if
curvSolver > initializeBoundaryLayeris set toramp,trueorzero.
- Distance from no-slip walls to construct velocity profiles if
-
outputDir (
string,default="./")- Path to output directory for any output requested in the
outputsection of the input file.
- Path to output directory for any output requested in the
-
metricExchange (
boolean,default=True)- Determines if metric terms are exchanged across B2B surfaces. This should only be set to false if using HWCNS schemes and negative volumes or Jacobians are reported.
-
fixBadRecon (
boolean,default=False)- Performs a 1st order reconstruction of the left and right states when unphysical (non-positive) pressures and temperatures are reconstructed or interpolated to a mid-point.
-
checkForPBS (
boolean,default=False)- Checks for a PBS job environment and outputs a restart file prior to the end of the job if the solver is still running.
-
PBSStopBuffer (
float,default=180.0)- Time in seconds to reserve for the restart file output at the end of the PBS job when
curvSolver > checkForPBSis set to true.
- Time in seconds to reserve for the restart file output at the end of the PBS job when
-
iterFileName (
string,default="data.iter")- Filename for datafile containing solver history, integrated forces and moments, probe history, etc.
-
autoLoadBalance (
boolean,default=False)- Utilizes a series of RHS calls to re-load balance based on timing differences. This should be set to true when performing explicit time-stepping.
-
debugCommFileName (
string,default="")- Write a debug file to replicate the communication structure.
-
saveIBADTInMem (
boolean,default=False)- Allows the entire source immersed boundary (IB) geometry set to be held in memory in the grid object. While this can be expensive, it may be desired if geometry is moving as re-computation of large IBs when wall distance is needed can prohibitively extend simulation time.
-
useGPU (
boolean,default=False)- Controls if GPU kernels are utilized. Should be set to true if running on GPUs.
-
streamDirection (
string,default="x")- Accepted Values: [
"x","y","z"] - Main Cartesian coordinate for the direction of the flow. This is used for adjusting the flow based on angle of attack, and for computing the lift and drag coefficients.
x-
- Main flow direction along the X-axis (default).
y-
- Main flow direction along the Y-axis.
z-
- Main flow direction along the Z-axis.
- Accepted Values: [
-
groundDirection (
string,mutable,default="z")- Accepted Values: [
"x","y","z"] - Main Cartesian coordinate for the direction of the ground. This is used for adjusting the flow based on angle of attack, and for computing the lift and drag coefficients.
x-
- Ground direction along the X-axis.
y-
- Ground direction along the Y-axis.
z-
- Ground direction along the Z-axis (default).
- Accepted Values: [
-
exactSolutionErrorVariables ([
string, ...],default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature"])- Variables whose errors are evaluated with respect to a user-supplied dynamic link library (DLL) file defining the exact solution. \(L^{\infty}\), \(L^1\), and \(L^2\) error norms are evaluated for combined boundary and interior nodes, interior nodes alone, and boundary nodes alone. The default variables are the five primitive variables:
[p, u, v, w, t].
- Variables whose errors are evaluated with respect to a user-supplied dynamic link library (DLL) file defining the exact solution. \(L^{\infty}\), \(L^1\), and \(L^2\) error norms are evaluated for combined boundary and interior nodes, interior nodes alone, and boundary nodes alone. The default variables are the five primitive variables:
-
exactSolutionErrorExcludeBCNames ([
string, ...],default=[""])- Names of boundary condition(s) whose nodes will be excluded from the evaluation of errors with respect to a user-supplied dynamic link library (DLL) file defining the exact solution. For example, this option can be used to exclude the errors on symmetry plane boundaries when simulating a two-dimensional problem on a three-dimensional mesh, or to isolate the errors on a specific boundary or set of boundaries.
-
nImmersedWallOffsetPts (
integer,default=0)- The number of sample/offset points from non-curvilinear-cartesian immersed walls for calculating wall models and shear stresses. Default is 0. Curv-Cart uses 2, but currently all our implemented non-Curv-Cart methods only use cell center and wall-model match-distance interpolation, meaning using anything greater than 0 of these points now is simply extra memory overhead. When other methods are added (e.g. IBBC), then this default can increase, or appropriate logic added.
-
writeIBWallModelInterpNodes (
boolean,default=False)- Write the physical vectors from immersed boundary cell centers to their wall model offset and match location nodes. These are written to
IBSurf_offsetPtVecs.datandIBSurf_matchLocVecs.datinside thecurvSolver > integrationWeightsDirfolder, respectively.
- Write the physical vectors from immersed boundary cell centers to their wall model offset and match location nodes. These are written to
-
writeProbeInterpNodes (
boolean,default=False)- Write the physical vectors from probe nodes to their wall model offset and match location nodes. These are written in
probe_offsetPtVecs.datandprobe_matchLocVecs.datwithin thecurvSolver > integrationWeightsDirfolder, respectively.
- Write the physical vectors from probe nodes to their wall model offset and match location nodes. These are written in
-
configGPUWarningsAsErrors (
boolean,default=False)- While verifying the input YAML file, for bad GPU options raise an error instead of a warning and modifying.
-
integratePRef (
boolean,default=True)- Option to include the reference pressure in the integration of the pressure over the surface. If true, then the pressure forces are integrated as \(\mathbf{F_p} = -(p_{ref} - p) \ \mathbf{n} \ dA\), where \(\mathbf{n}\) is the surface normal vector and \(dA\) is a surface area element). Otherwise, the pressure forces are integrated as \(\mathbf{F_p} = -p \ \mathbf{n} \ dA\). This may be useful when doing a drag breakdown as integrating \(-(p-p_{ref})\) on an open surface will lead to different results compared to integrating \(-p\) on the same surface.
- NOTE: Integrating \(-(p-p_{ref})\) or \(-p\) over a closed surface will give back the same result.
-
usePolarInterpInSlidingRings (
boolean,default=False)- When set to True, the sliding ring interpolations are performed in polar coordinates, as opposed to Cartesian coordinates.
-
debugSlidingRings (
boolean,default=False)- When set to True, the code outputs the internal representation of the sliding mesh rings after pre-processing onto a formatted Tecplot ASCII file called 'rings.dat' with each ring as a separate zone. Currently only works when using a single processor.
Time Stepping
- This section defines parameters related to the time discretization in the simulation.
timeStepping:
steady: <required>
timeSteps:
dt:
method:
initializeAveraging:
initializeEWMAveraging:
jacobianLag:
gridMotion:
explicitCFLLimit:
conservativeInTime:
timescaleCTU:
constantStepExit:
EWMAvgFact:
-
steady (
boolean,required)- Flag specifying if the simulation is steady or unsteady.
-
timeSteps (
integer,lower bound=1,mutable,default=1000)- The number of timesteps to perform for an unsteady simulation. While this value has a default, it should be specified for unsteady simulations. Only used if
steadyis false.
- The number of timesteps to perform for an unsteady simulation. While this value has a default, it should be specified for unsteady simulations. Only used if
-
dt (
float,default=0.1000E-02)- The timestep to use for the unsteady simulation. For methods
BDF1andBDF2this is the actual timestep. For the explicit schemes, this is the maximum timestep to use. Stability constraints may dictate a smaller timestep is actually used. This timestep will be used for I/O purposes using either implicit or explicit time-stepping.
- The timestep to use for the unsteady simulation. For methods
-
method (
string,default="bdf2")- Accepted Values: [
"bdf1","bdf2","tvd_rk3","rk4","ssp_rk45","rk1"] - The type of time marching scheme to use. Available are the following options:
BDF1-
- 1st order implicit backwards difference in time.
BDF2-
- 2nd order implicit backwards difference in time. Most common implicit scheme.
RK1-
- 1st order explicit Runge-Kutta scheme. Commonly known as explicit Euler.
TVD_RK3-
- 3rd order explicit Runge-Kutta scheme. Most common explicit scheme.
RK4-
- Classic 4th order Runge-Kutta (RK4) scheme.
SSP_RK45-
- Strong stability preserving Runge-Kutta scheme.
- Accepted Values: [
-
initializeAveraging (
integer,mutable,default=1)- The timestep at which to start averaging output variables. The physical time at which this occurs is equal to timestep*dt.
-
initializeEWMAveraging (
integer,mutable,default=1)- The timestep at which to start averaging output variables using exponentially weighted moving averaging. The physical time at which this occurs is equal to timestep*dt. See
timeStepping > EWMAvgFactfor details about the exponentially weighted moving average.
- The timestep at which to start averaging output variables using exponentially weighted moving averaging. The physical time at which this occurs is equal to timestep*dt. See
-
jacobianLag (
integer,lower bound=1,upper bound=50,default=1)- The number of timesteps over which to lag the recomputation of the flow Jacobian (aka LHS). This should not be changed unless it is known that the flow is not substantially changing from one timestep to the next. It should always be 1 for a moving grid simulation.
-
gridMotion (
boolean,default=False)- Flag specifying if the grid is moving in time. Two types of grid motion are supported: a user-supplied dynamic link library (DLL) file describing the motion through a user.F90 routine or rigidly rotating blocks using the
rotatingMeshinput section. Only one type of motion may be used at a time.
- Flag specifying if the grid is moving in time. Two types of grid motion are supported: a user-supplied dynamic link library (DLL) file describing the motion through a user.F90 routine or rigidly rotating blocks using the
-
explicitCFLLimit (
float,lower bound=0.000,default=1.000)- Explicit CFL Limit for explicit time marching schemes. This will indirectly determine the maximum timestep in the explicit schemes.
-
conservativeInTime (
boolean,default=False)- Flag specifying that the grid that is moving in time should use a temporal discretization that is strongly conservative in time. This option is only relevant when the grid is moving in time.
-
timescaleCTU (
float,default=0.000)- Timescale to use for the monitoring of 'convective time units' (CTUs) for an unsteady flow solve. If a timescale is not provided, the reference length and reference velocity magnitude are used to compute a timescale.
-
constantStepExit (
boolean,default=False)- Flag specifying that the time loop for Runge-Kutta methods should be exited based on the number of constant timesteps as opposed to the number of timesteps. Setting this option to true ensures that the final numerical solution corresponds to a final time equal to the number of specified timesteps multiplied by the specified fixed timestep. This is useful for evaluating errors with respect to an exact solution at a specific final time.
-
EWMAvgFact (
float,lower bound=0.000,upper bound=1.000,default=0.000)- The exponentially weighted moving average constant factor used for time-filtering. This is only used when
zdesmode8orzdesmode9is activated, or whenewmavgis appended to the end of an output variable name. When activated, the time averaging for the generic variable \(\psi\) is computed as \(\psi_\mathrm{avg} = w \psi_\mathrm{avg} + (1 - w) \psi\), where \(w = \min(n / (n + 1), 1 - \mathrm{EWMAvgFact})\) is the weight applied to the existing average and \((1-w)\) is the weight for the new sample. Initially, this formula behaves like a cumulative arithmetic mean, which prevents the initial zero-valued average from biasing the result when only a few samples are available. If \(\mathrm{EWMAvgFact} = 0\) (the default) then \(w=n / (n + 1)\), which is the cumulative arithmetic mean. If \(\mathrm{EWMAvgFact} = 1\) then \(w=0\) and the intantaneous sample is returned with no averaging. If \(0 < \mathrm{EWMAvgFact} < 1\) then once enough samples have been obtained, the average becomes a standard exponentially weighted moving average where larger values of \(\mathrm{EWMAvgFact}\) give more weight to recent samples. Exponentially weighted moving averaging is not supported for immersed boundary surface fields.
- The exponentially weighted moving average constant factor used for time-filtering. This is only used when
Nonlinear Solver
- This section defines parameters related to the nonlinear solver used in the code.
nonlinearSolver:
method:
kind:
iterations:
minIterations:
L2Conv:
jacobianLag:
subIterTur:
useScaledResiduals:
CFLStart:
CFLLimit:
CFLLimitTur:
CFLRamp:
CFLStepTol:
CFLLinItsTol:
CFLFromFile:
-
method (
string,default="implicit")- Accepted Values: [
"implicit"] - The nonlinear solver method.
implicit-
- Use an implicit approach to solve the coupled system of governing equations.
- Accepted Values: [
-
kind (
string,default="ank")- Accepted Values: [
"ank","nk"] - The kind of solver to use.
ANK-
- Approximate Newton-Krylov algorithm.
NK-
- Newton-Krylov algorithm. This option is experimental and may not work properly for all cases.
- Accepted Values: [
-
iterations (
integer,lower bound=0,default=1000)- The maximum number of nonlinear iterations to perform. For steady simulations this is the total number of iterations to perform. For implicit unsteady simulations, it is the number of nonlinear iterations, or sub-iterations, to perform during each timestep.
-
minIterations (
integer,lower bound=0,default=0)- Perform at least this fixed number of nonlinear iterations. This parameter is useful when using the Broyden solve option in
curvSolver > task.
- Perform at least this fixed number of nonlinear iterations. This parameter is useful when using the Broyden solve option in
-
L2Conv (
float,lower bound=0.1000E-15,upper bound=1.000,mutable,default=0.1000E-07)- The required convergence for the nonlinear solver. This is relative to the initial residual.
-
jacobianLag (
integer,lower bound=1,upper bound=50,default=5)- The number of nonlinear iterations over which to lag the recomputation of the jacobian, or LHS. Typical values are between 5 and 10.
-
subIterTur (
integer,lower bound=1,upper bound=50,default=1)- The number of nonlinear iterations over which to sub-iterate the turbulence model for each flow solve iteration. Typical values are between 1 and 5.
-
useScaledResiduals (
boolean,default=True)- Use volume weighted residuals to determine convergence. This should generally be true for steady simulations and false for unsteady simulations.
-
CFLStart (
float,lower bound=0.000,mutable,default=10.00)- The starting CFL for the flow simulation. Both the flow and turbulence (if applicable) start at this CFL.
-
CFLLimit (
float,lower bound=0.000,default=0.1000E+05)- The maximum CFL limit to use for the flow equations.
-
CFLLimitTur (
float,mutable,default=-1.000)- The maximum CFL limit to use for the turbulence model. If this value is less than 0.0, it uses the
nonlinearSolver > CFLLimitvalue.
- The maximum CFL limit to use for the turbulence model. If this value is less than 0.0, it uses the
-
CFLRamp (
float,default=1.250)- The factor used to ramp the CFL when there are good solution updates.
-
CFLStepTol (
float,mutable,default=0.5000E-01)- The factor used for judging acceptable update sizes. The CFL is reduced if the step size is below this factor.
-
CFLLinItsTol (
float,mutable,default=0.9000)- The average linear iteration tolerance, relative to the Krylov subspace size, used to control CFL ramping.
-
CFLFromFile (
boolean,default=False)- Use CFL from input YAML file instead of restart file.
Linear Solver
- This section defines parameters related to the linear solver used in the code.
linearSolver:
method:
tolerance:
maxTolerance:
failureTolerance:
subSpaceSize:
matFree:
HOSwitchTol:
approxViscFluxes:
useLHSBlending:
monitor:
lineSearch:
adJacobian:
useModifiedGS:
jacobianType:
jacTypeSwitchTol:
-
method (
string,default="gmres")- Accepted Values: [
"gmres","richardson"] - The linear solver method.
GMRES-
- Generalized minimal residual (GMRES) method.
Richardson-
- Richardson method. Not to be used in practice.
- Accepted Values: [
-
tolerance (
float,lower bound=0.1000E-15,upper bound=0.9999,default=0.1000)- The target convergence tolerance for the linear solver.
-
maxTolerance (
float,lower bound=0.1000E-14,default=0.5000)- The maximum linear convergence tolerance which is acceptable before the CFL is reduced.
-
failureTolerance (
float,lower bound=0.000,upper bound=1.000,mutable,default=0.8000)- The maximum linear convergence tolerance which is considered a failure. A CFL reduction is executed and no step is taken.
-
subSpaceSize (
integer,lower bound=1,default=40)- The maximum number of Krylov vectors to use for GMRES. This also sets the maximum number of linear iterations to perform.
-
matFree (
boolean,default=True)- Flag controling the use of the matrix-free method for doing matrix-vector products within the GMRES algorithm. This is usually desirable for steady simulations as it allows for effectively higher-order left-hand operator to be used. If the convergence is failing switch to false. If running unsteady also set to false.
-
HOSwitchTol (
float,lower bound=0.1000E-15,default=0.1000E-03)- The convergence ratio relative to freestream residual at which to activate the higher order left-hand side. Only meaningful if
linearSolver > matFreeis true.
- The convergence ratio relative to freestream residual at which to activate the higher order left-hand side. Only meaningful if
-
approxViscFluxes (
boolean,default=False)- Flag specifying if 1st order approximate viscous fluxes are used for the LHS. Only meaningful if
linearSolver > matFreeis true. This makes the matrix-free LHS closer to the matrix-based LHS which always uses approximate viscous fluxes.
- Flag specifying if 1st order approximate viscous fluxes are used for the LHS. Only meaningful if
-
useLHSBlending (
boolean,default=False)- Flag specifying if blending is to be used for the LHS. Only meaningful if
linearSolver > matFreeis true. Should almost always be set to false.
- Flag specifying if blending is to be used for the LHS. Only meaningful if
-
monitor (
boolean,default=False)- Display the convergence of the linear GMRES iterations in STDOUT.
-
lineSearch (
boolean,default=True)- Whether to use a linear search for residual reduction. It is highly recommended to use this option as it increases the solver robustness.
-
adJacobian (
boolean,default=False)- Use analytical derivatives to form the explicit Jacobian. This is different from using the
linearSolver > matFreeapproach, since analytical differentiations of the fluxes are used to form the Jacobian.
- Use analytical derivatives to form the explicit Jacobian. This is different from using the
-
useModifiedGS (
boolean,default=False)- Use the modified Gram-Schmidt algorithm for orthogonalization in the linear solver. Modified Gram-Schmidt is slower than standard Gram-Schmidt, but it can be used with preconditioner.type = none to give processor-count-independent solutions to single precision when the flow is not fully converged
-
jacobianType (
string,default=)- Accepted Values: [
"frechet","analytical","explicit","hybrid_frechet","hybrid_analytical"] - The type of Jacobian to use for the LHS of the linear system for the flow problem at each Newton iteration:
frechet-
- Use a Frechet derivative of the residual as the LHS matrix.
analytical-
- Use a matrix-free analytical derivative of the residual as the LHS matrix.
explicit-
- Use an explicit Jacobian formed using a nearest-neighbor approximation of the residual Jacobian .
hybrid_frechet-
- Perform the initial Newton iterations with the explicit Jacobian until the flow residual reaches a specified tolerance. After that, switch to the (mat-free) Frechet derivative LHS.
hybrid_analytical-
- Perform the initial Newton iterations with the explicit Jacobian until the flow residual reaches a specified tolerance. After that, switch to the (mat-free) analytical derivative LHS.
- Accepted Values: [
-
jacTypeSwitchTol (
float,lower bound=0.1000E-15,default=0.1000E-03)- The convergence ratio relative to freestream residual at which to switch from an explicit Jacobian to a matrix-free Jacobian. This is only used if
linearSolver.jacobianTypeis set to hybrid.
- The convergence ratio relative to freestream residual at which to switch from an explicit Jacobian to a matrix-free Jacobian. This is only used if
- This section defines parameters associated with the Navier-Stokes equations and the numerical scheme utilized to solve them.
navierStokes:
convective:
type:
dissipationType:
riemannSolver:
dis2:
dis4:
sigma:
eigEps:
dSwitch:
symmetricMetricTerms:
constantSource:
sourceFile:
schemeOrder:
interpOrder:
limiter:
entropyfix:
lowspeedPreCon:
beta:
interiorBlending:
upwindSensor:
fdBlendARCutOff:
fdARCutOff:
fdLTurbCutOff:
ducrosMachCutOff:
sensorCutOffForRoe:
interiorZetaMin:
interiorZetaMax:
meshARCutOff:
meshPSCutOff:
meshSRCutOff:
interiorZetaWS:
interiorZetaUS:
interiorZetaWM:
interiorZetaPow:
interiorZeta:
fringeZeta:
minWENO:
useLimiter:
turbulenceModel:
type:
useQCR:
QCRVersion:
useRC:
useRC_TD:
useFdExtraProtection:
useSACC:
useSAlowRe:
useFT2:
mode:
gridLengthScale:
LHSFacMode7:
mode2_C1:
RANS_InterfaceHeight:
sgsmodel:
csgs:
komega_sust:
komega_muRefFac:
komega_prodLimFacExp:
komega_prodLimFacImp:
komega_CDkwmin:
komega_a1:
lin:
turLimit_n:
turLimit_p:
prandtLTurb:
smth:
smthfac:
sttsfac:
locCFLMin:
useTransCF:
useTransCFdelay:
useTransCFTol:
useTransCFAlg:
useTransCC:
freezeQ:
freezeT:
sa_sigma:
sa_akar:
sa_cb1:
sa_cb2:
sa_ct3:
sa_ct4:
sa_cv1:
sa_cw2:
sa_cw3:
-
-
(
string,default="upwind")- Accepted Values: [
"upwind","centeredq","centeredw","kep","hwcns","keep","ranocha","keeppe","aec0","aec1","aec2","keepg0","keepg1","keepg2"] - The type of convective flux.
upwind-
- Roe-like upwind scheme which can be used with or without low-Mach preconditioning activated. This is the default scheme and should be used for most RANS-based analysis.
centeredq-
- Central difference scheme with artifical dissipation based on the primitive variables \([p, u, v, w, T]\). Can be used with or without low-Mach preconditioning activated. Should have less artificial dissipation than the
centeredwscheme in the boundary layer.
- Central difference scheme with artifical dissipation based on the primitive variables \([p, u, v, w, T]\). Can be used with or without low-Mach preconditioning activated. Should have less artificial dissipation than the
centeredw-
- Central difference scheme with artificial dissipation based on conserved variables \([\rho, \rho u, \rho v, \rho w, e]\).
KEP-
- Kinetic-energy-preserving (KEP) flux of Pirozzoli. Refer to 10.1016/j.jcp.2010.06.006 and 10.1016/j.jcp.2011.01.001 .
HWCNS-
- Hybrid Weighted Compact Nonlinear Scheme (HWCNS) which uses a combination of mid-point fluxes based on Roe-like scheme and node fluxes to construct a high-order finite upwind difference stencil (up to 4th order implemented).
KEEP-
- Kinetic-energy-preserving flux of Kuya et al. This flux is not entropy-consistent, but has favorable entropy-preserving behavior. Refer to 10.1016/j.jcp.2018.08.058 and 10.1016/j.jcp.2021.110482 .
ranocha-
- Kinetic-energy-preserving, entropy-consistent, and and pressure-equilibrium-preserving flux of Ranocha. This flux uses the logarithmic mean for density and internal energy. Refer to Dissertation, 10.1007/978-3-030-39647-3_42 and 10.1007/s42967-021-00148-z .
KEEPPE-
- Kinetic-energy-preserving and pressure-equilibrium-preserving flux of Shima et al. This flux is not entropy-consistent, but has favorable entropy-preserving behavior (although slightly worse entropy-preserving behavior compared to the KEEP scheme). Refer to 10.1016/j.jcp.2020.110060 .
AEC0,AEC1,AEC2-
- Kinetic-energy-preserving, asymptotically entropy-consistent, and pressure-equilibrium-preserving fluxes of De Michele and Coppola. The fluxes are based on the arithmetic mean for density and the harmonic mean for internal energy, which makes them cheaper than the entropy-consistent flux of Ranocha that uses the logarithmic mean. The numbers 0, 1, and 2 are related to the number of terms retained in the asymptotic expansions. Refer to 10.1016/j.jcp.2023.112439 .
KEEPG0,KEEPG1,KEEPG2-
- Kinetic-energy-preserving, asymptotically entropy-consistent, and pressure-equilibrium-preserving fluxes of Kawai and Kawai. The fluxes are based on the geometric mean for density and internal energy, which makes them cheaper than the entropy-consistent flux of Ranocha that uses the logarithmic mean, but slightly more expensive than the AEC fluxes since the geometric mean involves a square root. The numbers 0, 1, and 2 are related to the number of terms retained in the asymptotic expansions. Refer to 10.2514/6.2024-3788 .
- Accepted Values: [
-
(
string,default="jst")- Accepted Values: [
"jst","reconblend","interpblend","interpscale"] - The type of dissipation for the convective fluxes.
JST-
- Dissipation based on Jameson-Schmidt-Turkel scheme by by Jameson et al. Refer to 10.2514/6.1981-1259 .
reconBlend-
- Dissipation based on modified-Roe formulation with blending of reconstructed states using robustness sensors. Mimics the dissipation of the upwind scheme with the
modifiedRoeoption innavierStokes > convective > riemannSolverinput.
- Dissipation based on modified-Roe formulation with blending of reconstructed states using robustness sensors. Mimics the dissipation of the upwind scheme with the
interpBlend-
- Dissipation based on modified-Roe-HLL formulation with blending of interpolated states using robustness sensors. Mimics the dissipation of the
upwindscheme with themodifiedRoeHLLoption innavierStokes > convective > riemannSolverinput.
- Dissipation based on modified-Roe-HLL formulation with blending of interpolated states using robustness sensors. Mimics the dissipation of the
interpScale-
- Dissipation based on modified-Roe-HLL formulation with scaling of entire artificial dissipation based on robustness sensors. Mimics the dissipation of the upwindHS scheme with the
modifiedRoeHLLoption innavierStokes > convective > riemannSolverinput.
- Dissipation based on modified-Roe-HLL formulation with scaling of entire artificial dissipation based on robustness sensors. Mimics the dissipation of the upwindHS scheme with the
- Accepted Values: [
-
(
string,default="modifiedroe")- Accepted Values: [
"modifiedroe","hll","modifiedroehll","none"] - Approximate Riemann solver used in the numerical flux for upwind and HWCNS-type schemes.
modifiedRoe-
- A Roe-like numerical flux with artificial dissipation applied to the primitive variables \([p, u, v, w, T]\).
HLL-
- A Harten, Lax, and van Leer like numerical flux with artificial dissipation applied to the primitive variables \([p, u, v, w, T]\).
modifiedRoeHLL-
- Combination of
modifiedRoeandHLLnumerical fluxes which are blended based on a shock sensor (refer tonavierStokes > convective > dSwitch). This approximate Riemann solver should be used for high supersonic cases which contain bow shocks.
- Combination of
none-
- No approximate Riemann solver is used in the numerical flux.
- Accepted Values: [
-
(
float,lower bound=0.000,upper bound=10.00,mutable,default=0.2500)- Second-difference dissipation coefficient used for JST type dissipation.
-
(
float,lower bound=0.000,upper bound=10.00,mutable,default=0.2000E-01)- Fourth-difference dissipation coefficient used for JST type dissipation.
-
(
float,default=6.000)- Lumping coefficient for LHS operator used for JST type dissipation. Values between 4 and 6 are suggested.
-
(
float,lower bound=0.000,upper bound=1.000,mutable,default=0.3000)- Constant used for eigenvalue scaling when using
entropyfixiiinnavierStokes > convective > entropyFix.
- Constant used for eigenvalue scaling when using
-
(
float,lower bound=0.000,default=1.000)- Constant used for pressure-based shock sensor which is important when using the
modifiedRoeHLLRiemann solver innavierStokes > convective > riemannSolver. Values between 0.001 and 0.1 are typically sufficient, with lower values identifying weaker gradients as shocks.
- Constant used for pressure-based shock sensor which is important when using the
-
(
boolean,default=True)- Utilize symmetric metric terms for the HWCNS type flux.
-
([
float,float,float,float,float],default=[0.000, 0.000, 0.000, 0.000, 0.000])- Constant source term to run channel flow or other applications which require a user-imposed source.
-
(
string(fileName),default="")- Filename containing a spatially varying source term, often used for MMS.
-
(
integer,default=2)- Order of the finite-difference operator used for convective flux discretization.
schemeOrder2 and 4 are acceptable for the HWCNS and KEEP family of schemes. All other types assume aschemeOrderof 2.
- Order of the finite-difference operator used for convective flux discretization.
-
(
integer,lower bound=1,upper bound=4,default=3)- Order of the interpolation/reconstruction used for the left/right state interpolations/reconstructions input to the approximate Riemann solver. Values of 1, 2, 3, and 4 are accepted where odd numbers are upwind biased and even numbers are centered.
-
(
string,default="koren")- Accepted Values: [
"vanalbada","vanleer","koren","none","minmod","weno","wenoshkfr","unstmuscl"] - Slope limiter option for left/right state interpolation/reconstruction.
vanAlbada-
- The van Albada slope limiter can be used with the upwind
modifiedRoe,HLL, andmodifiedRoeHLLRiemann solvers.
- The van Albada slope limiter can be used with the upwind
vanLeer-
- The van Leer slope limiter can be used with the upwind
modifiedRoe,HLL, andmodifiedRoeHLLRiemann solvers.
- The van Leer slope limiter can be used with the upwind
koren-
- The Koren slope limiter can be used with the upwind
modifiedRoe,HLL, andmodifiedRoeHLLRiemann solvers
- The Koren slope limiter can be used with the upwind
minmod-
- The minmod slope limiter can be used with the upwind
modifiedRoe,HLL, andmodifiedRoeHLLRiemann solvers.
- The minmod slope limiter can be used with the upwind
WENO-
- The Weighted Essentially Non-Oscillatory (WENO) interpolation can be used with the HWCNS flux.
WENOShkFr-
- The Weighted Essentially Non-Oscillatory (WENO) interpolation combined with local shock detection can be used with the HWCNS flux.
- Accepted Values: [
-
(
string,default="entropyfixi")- Accepted Values: [
"entropyfixi","entropyfixii","none"] - Entropy fix used for
modifiedRoeandmodifiedRoeHLLapproximate Riemann solvers. entropyFixI-
- Standard entropy fix for Roe-type schemes.
entropyFixII-
- Gnoffo strong entropy fix. Can be overly dissipative.
- Accepted Values: [
-
(
string,mutable,default="none")- Accepted Values: [
"localinviscidvelocity","constantbeta","none"] - Low-speed preconditioning. This should be activated when the freestream Mach number becomes less than 0.1.
localInviscidVelocity-
- Uses the local velocity magnitude to determine the artificial sound speed.
constantBeta-
- Uses a constant to set the artificial sound speed.
none-
- Do not use low-speed preconditioning.
- Accepted Values: [
-
(
float,lower bound=0.1000,default=1.000)- Constant used in low-speed preconditioning for either
localInviscidVelocityorconstantBetapreconditioning. ForlocalInviscidVelocitythis acts as the minimum local velocity. This should be between \(10 U_{ref}\) and \(100 U_{ref}\) and affects both the steady-state convergence rate as well the amount of local artificial dissipation.
- Constant used in low-speed preconditioning for either
-
(
string,default="none")- Accepted Values: [
"fixed","localmach","fd","ducros","ducrosstab","fdshock","shockint","ducrosmach","none","wigglestab"] - Upwind/centered blending function used to reduce local dissipation.
none-
- No upwind/centered blending (default).
fixed-
- Uses a fixed amount of upwind dissipation throughout the zone/domain.
localMach-
- Uses the local Mach number to determine the amount of upwinding. If the local Mach is greater than or equal to 1 then full upwinding is used.
fd-
- Uses the shielding function along with a wiggle sensor and the
navierStokes > convective > upwindSensorinput to determine amount of local upwinding. Iffd< 0.8 (RANS mode), full upwinding is used.
- Uses the shielding function along with a wiggle sensor and the
wiggleStab-
- Uses a combination of the wiggle sensor of Mary and Sagaut (refer to 10.2514/2.1763), and
navierStokes > convective > upwindSensorinto the upwind/centered blending of velocity.
- Uses a combination of the wiggle sensor of Mary and Sagaut (refer to 10.2514/2.1763), and
- Accepted Values: [
-
(
string,mutable,default="vorticitydilatation")- Accepted Values: [
"vorticitydilatation","vorticitystrainrate","lowspeedsensor","hrlessensor"] - The upwind sensor controls local amount of upwind dissipation used when blending is activated.
vorticityDilatation-
- Sensor based on the Ducros relation comparing vorticity magnitude and dilatation. Can be used with Hybrid RANS/LES (HRLES) or Wall-Modeled LES (WMLES).
lowSpeedSensor-
- Sensor based on vorticity magnitude and strain rate magnitude using the expression for \(g\) in Eq. (3) in Spalart et al. (refer to 10.2514/6.2012-1174). Can be used with unsteady RANS (URANS), HRLES, and WMLES.
vorticityStrainRate-
- Same as
lowSpeedSensorbut numerically more efficient using approximations. Can be used with URANS, HRLES, and WMLES.
- Same as
hrlesSensor-
- Sensor based on the full expression, Eqs. (2)-(3) in Spalart et al. (refer to 10.2514/6.2012-1174). This sensor should only be used with HRLES.
- Accepted Values: [
-
(
float,lower bound=0.1000E-05,default=0.1000E+07)- Deactivates the centered blending if the local aspect ratio of the mesh is larger than this value.
-
(
float,lower bound=0.1000E-05,default=0.1000E+07)- Activates RANS-mode shielding if the local aspect ratio of the mesh is larger than this value.
-
(
float,lower bound=0.000,mutable,default=0.000)- Activates RANS-mode shielding if local turbulent length scale estimate is smaller than this value.
-
(
float,lower bound=0.000,mutable,default=0.7000)- Scales local Mach test in when
navierStokes > convective > interiorBlendingis set toducrosMach. Smaller value results in more centering.
- Scales local Mach test in when
-
(
float,lower bound=0.000,default=2.000)- Determines if
modifiedRoeflux is used orHLLflux is used in HWCNS. IfnavierStokes > convective > upwindSensoris less than this value or if this value is larger than 1 themodifiedRoeflux is used, otherwise theHLLflux is used.
- Determines if
-
(
float,lower bound=0.000,default=0.000)- Minimum blending coefficient allowed no matter which blending option is chosen, i.e. there will always be at least
interiorZetaMinamount of upwinding in the interpolation/reconstruction of left/right states.
- Minimum blending coefficient allowed no matter which blending option is chosen, i.e. there will always be at least
-
(
float,lower bound=0.000,upper bound=1.000,mutable,default=1.000)- Maximum blending coefficient. This can be used to bound the total amount of upwinding, i.e. there will never be more than
interiorZetaMaxamount of upwinding in the interpolation/reconstruction of left/right states.
- Maximum blending coefficient. This can be used to bound the total amount of upwinding, i.e. there will never be more than
-
(
float,lower bound=1.000,mutable,default=100.0)- Not currently used, but can be used as a threshold for identifying regions where the local mesh aspect ratio is larger than the value specified.
-
(
float,lower bound=0.5000,mutable,default=0.8500)- Not currently used, but can be used as a threshold for identifying regions where the local mesh planar skewness is larger than the value specified.
-
(
float,lower bound=1.000,mutable,default=1.200)- Not currently used, but can be used as a threshold for identifying regions where the local mesh stretching ratio is larger than the value specified.
-
(
float,lower bound=0.000,upper bound=1.000,mutable,default=0.000)- Utilizes a wiggle sensor to detect non-physical oscillations and incorporate
interiorZetaWSamount of local upwinding. Typical values of 0.1 to 0.3 are used if activated.
- Utilizes a wiggle sensor to detect non-physical oscillations and incorporate
-
(
float,lower bound=0.000,upper bound=1.000,mutable,default=1.000)- Bounds the amount of upwinding used to
interiorZetaUSif the upwind sensor returns a value larger than the value specified.
- Bounds the amount of upwinding used to
-
(
float,lower bound=0.000,default=1.000)- Decrease the amount of upwinding to the value specified for nodes with a stencil that contains a wall-model node. This is only activated if the current amount of upwind blending is larger than this value, otherwise it is left unmodified.
-
(
float,lower bound=1.000,default=4.000)- Power used in when
navierStokes > convective > interiorBlendingis set towiggleStab. A larger power results in a sharper sensor and less dissipation (default is 4).
- Power used in when
-
([
float,float,float,float,float],lower bound=0.000,upper bound=1.000,mutable,default=[1.000, 1.000, 1.000, 1.000, 1.000])- Initial blending values used before the selected blending procedure is applied. If fixed blending is used, then this vector will be used to blend upwind and centered interpolations/reconstructions for \([p, u, v, w, T]\).
-
([
float,float,float,float,float],lower bound=0.000,upper bound=1.000,mutable,default=[1.000, 1.000, 1.000, 1.000, 1.000])- Specify the amount of upwinding for nodes which contain a fringe (receiver) in their stencil.
-
([
float,float,float,float,float],lower bound=0.000,default=[0.000, 0.000, 0.000, 0.000, 0.000])- Used to reduce the amount of WENO interpolation, i.e. dissipation when using the
wenoShkFrlimiter. This overrides the shock sensor which means if the shock sensor detects a shock and wants to use full WENO, theminWENOoverrides this behavior and usesminWENOamount of WENO and (1 -minWENO) amount of optimal weights in the left/right state interpolation.
- Used to reduce the amount of WENO interpolation, i.e. dissipation when using the
-
([
integer,integer,integer,integer,integer],lower bound=0,upper bound=1,mutable,default=0)- Utilized to set a minimum amount of upwinding for each individual primitive variable when utilizing either the
ducrosStaborducrosMachblending option innavierStokes > convective > interiorBlending.
- Utilized to set a minimum amount of upwinding for each individual primitive variable when utilizing either the
-
-
- This section is dedicated to the fine-tuning of turbulence model options and parameters.
-
(
string,default="sa")- Accepted Values: [
"sa","saorig","komegasst","komegabsl","saslm2015"] - Turbulence model type.
SA-
- Negative form of the Spalart-Allmaras (SA) turbulence model.
SAOrig-
- Original Spalart-Allmaras (SA) turbulence model.
kOmegaSST-
- Menter Shear Stress Transport (SST) turbulence model.
kOmegaBSL-
- Menter Baseline (BSL) turbulence model.
SASLM2015-
- Smooth local correlation-based transition model for the Spalart-Allmaras turbulence model. Refer to 10.2514/1.J059784.
- Accepted Values: [
-
(
boolean,default=True)- Flag to activate the Quadratic Constitutive Relation (QCR).
-
(
string,default="qcr2000")- Accepted Values: [
"qcr2000","qcr2013","qcr2013v","qcr2020","qcr2020s"] - Version options for QCR.
QCR2000-
- Original 2000 version of QCR (most stable for steady-state RANS analysis. Refer to 10.1016/S0142-727X(00)00007-2.
QCR2013-
- Additional normal stress term to account for turbulent kinetic energy. Refer to 10.2514/6.2013-860.
QCR2013V-
- Similar to
QCR2013, but replaces the use of strain-rate magnitude with the anti-symmetric rotation sensor. Refer to 10.2514/6.2020-1304.
- Similar to
QCR2020-
- Improved version of QCR with updated coefficients. Refer to 10.2514/1.J059683.
QCR2020S-
- Improved version of QCR but utilizing the strain-rate magnitude. Refer to 10.2514/1.J059683.
- Accepted Values: [
-
(
boolean,mutable,default=True)- Activate the Rotation/Curvature correction within the Spalart-Allmaras (SA) turbulence model (unsteady term neglected). Refer to 10.2514/2.1058.
-
(
boolean,default=False)- Activates the unsteady time derivative term in the Rotation/Curvature correction within the Spalart-Allmaras (SA) turbulence model. Should be used for unsteady problems with
navierStokes > turbulenceModel > useRCset to true when activated.
- Activates the unsteady time derivative term in the Rotation/Curvature correction within the Spalart-Allmaras (SA) turbulence model. Should be used for unsteady problems with
-
(
boolean,default=True)- Activates an extra protection based on estimated local length scales compared to the local grid spacing. This will result in staying in RANS mode for ZDES-Mode# HRLES models.
-
(
boolean,default=False)- Activates the compressibility correction in the Spalart-Allmaras (SA) turbulence model. Refer to 10.2514/6.2000-2306.
-
(
boolean,mutable,default=False)- Activate the low Reynolds number correction in the Spalart-Allmaras (SA) turbulence model. Refer to 10.2514/1.J059489.
-
(
boolean,default=False)- Activates the \(f_{t2}\) term in the Spalart-Allmaras (SA) turbulence model which by default is deactivated.
-
(
string,default="zdesmode0")- Accepted Values: [
"zdesmode0","zdesmode1","zdesmode2","zdesmode3","zdesmode4","zdesmode7"] - Zonal Detached Eddy Simulation (ZDES) mode.
ZDESMode0-
- RANS mode (default).
ZDESMode1-
- DES97 mode.
ZDESMode2-
- ZDES-Mode2 2012 mode (DDES).
ZDESMode3-
- ZDES-Mode3 (Wall-Modeled LES).
ZDESMode4-
- ZDES-Mode4 (LES).
ZDESMode7-
- ZDES Mode 2 (2020).
ZDESMode8-
- Reynolds Stress Contrained Eddy Simulation version 1. Currently under development, not ready for prime-time. When using this option,
timeStepping > EWMAvgFactshould also be specified appropriately.
- Reynolds Stress Contrained Eddy Simulation version 1. Currently under development, not ready for prime-time. When using this option,
ZDESMode9-
- Reynolds Stress Contrained Eddy Simulation version 2. Currently under development, not ready for prime-time. When using this option,
timeStepping > EWMAvgFactshould also be specified appropriately.
- Reynolds Stress Contrained Eddy Simulation version 2. Currently under development, not ready for prime-time. When using this option,
- Accepted Values: [
-
(
string,default="lenscalecubevol")- Accepted Values: [
"lenscalemaxedge","lenscalecubevol","lenscaleomega"] - Local grid length scale used in HRLES models.
lenScaleMaxEdge-
- Maximum edge length attached to the node/vertex.
lenScaleCubeVol-
- Cube-root of the volume of the dual-cell associated with the node/vertex.
lenScaleOmega-
- Square-root of the dual cell area perpendicular to the local vorticity vector.
- Accepted Values: [
-
(
boolean,default=False)- Activates a scaling factor to control diagonal dominance of the LHS for ZDES Mode 2 (2020). This should be set to true if
navierStokes > turbulenceModel > modeis set tozdesMode7.
- Activates a scaling factor to control diagonal dominance of the LHS for ZDES Mode 2 (2020). This should be set to true if
-
(
float,lower bound=8.000,default=8.000)- Constant used in \(r_d\) part of shielding function for HRLES. This can be increased if shielding of the attached boundary layer is breaking down, i.e., going into LES mode and either the grid has insufficient resolution or the timestep is not sufficiently small.
-
(
float,lower bound=0.000,default=0.000)- Fixed interface height for either RANS mode in
zdesMode3or Reynolds stress constraint height inzdesMode8andzdesMode9.
- Fixed interface height for either RANS mode in
-
(
string,default="sigmasgs")- Accepted Values: [
"sigmasgs","vremansgs","vremananisosgs","amdsgs","dynsmag"] - Sub-grid scale (SGS) turbulence model used in Large Eddy Simulation (LES).
sigmaSGS-
- Sigma SGS turbulence model. Use
csgs\(\approx 1.35\).
- Sigma SGS turbulence model. Use
vremanSGS-
- Vreman SGS turbulence model. Use
csgs\(\approx 0.07\).
- Vreman SGS turbulence model. Use
vremanAnisoSGS-
- Vreman anisotropic grid SGS turbulence model. Use
csgs\(\approx 0.07\) (good for anisotropic meshes).
- Vreman anisotropic grid SGS turbulence model. Use
amdSGS-
- Anisotropic Minimum-Dissipation (AMD) SGS turbulence model. Use
csgs\(\approx 0.3\) for 2nd order and 0.212 for 4th order numerical discretizations. Refer to 10.1063/1.4928700.
- Anisotropic Minimum-Dissipation (AMD) SGS turbulence model. Use
dynSmag-
- Dynamic Smagorinsky SGS turbulence model.
csgsis not used.
- Dynamic Smagorinsky SGS turbulence model.
- Accepted Values: [
-
(
float,default=1.350)- Constant used in sub-grid scale turbulence model for LES. Refer to description of SGS model to chose
csgsvalue.
- Constant used in sub-grid scale turbulence model for LES. Refer to description of SGS model to chose
-
(
float,default=0.000)- Sustaining terms for \(k-\omega\) turbulence model. Should be set to one to force \(k\) and \(\omega\) to freestream, or zero otherwise.
-
(
float,default=0.9000E-02)- Fraction of reference viscosity added to the turbulent eddy viscosity to avoid division by zero in \(k-\omega\) SST and BSL source terms.
-
(
float,default=20.00)- Production limiter constant used in RHS of \(k-\omega\) SST and BSL.
-
(
float,default=20.00)- Production limiter constant used in LHS of \(k-\omega\) SST and BLS.
-
(
float,default=0.1000E-19)- Minimum value of \(CD_{kw}\) in \(k-\omega\) SST and BSL.
-
(
float,default=0.3100)- Constant used in turbulent eddy viscosity evaluation in \(k-\omega\) SST.
-
(
string,default="full")- Accepted Values: [
"full","stts"] - Linearization flag for the turbulence model.
full-
- Full linearization.
STTS-
- Source-term time-stepping linearization used for the \(k-\omega\) SST and BSL turbulence models.
- Accepted Values: [
-
(
float,mutable,default=0.1000)- Scale factor which controls how much a turbulence variable can change in the negative direction.
-
(
float,mutable,default=0.6000)- Scale factor which controls how much a turbulence variable can change in the positive direction.
-
(
float,mutable,default=0.9000)- Turbulent Prandtl number.
-
(
boolean,mutable,default=False)- Activate smoothing in the
SASLM2015turbulence transition model.
- Activate smoothing in the
-
(
float,default=300.0)- Smoothing factor used in the
SASLM2015turbulence transition model.
- Smoothing factor used in the
-
(
float,mutable,default=0.8000)- Scale factor used in source-term time-stepping method for \(k-\omega\) SST and BSL turbulence models.
-
(
float,mutable,default=1.000)- Local CFL restriction for source-term time-stepping method for \(k-\omega\) SST and BSL turbulence models.
-
(
boolean,default=False)- Activate transition model crossflow correlations.
-
(
boolean,mutable,default=False)- Delay the activation of the crossflow correlations until
useTransCFTolis hit. This parameter is required for transonic simulations to prevent upstream transition front.
- Delay the activation of the crossflow correlations until
-
(
float,default=0.1000E-02)- Turbulence model residual convergence tolerance before activating the crossflow correlations in the
SASLM2015transition model.
- Turbulence model residual convergence tolerance before activating the crossflow correlations in the
-
(
boolean,mutable,default=True)- Recommended to use algebraic formulation for the crossflow correlations \((F_\text{onset, scf})\).
-
(
boolean,mutable,default=False)- Compressibility correlations for the Tollmien-Schlichting and crossflow empirical correlations.
-
(
boolean,default=False)- Freezes the primitive variable updating. Can be used to debug turbulence model settings.
-
(
boolean,mutable,default=False)- Freezes the turbulence model updating. Can be used to debug convective and viscous flux settings.
-
(
float,lower bound=0.6000,upper bound=1.000,default=0.6667)- Sigma constant used in the SA turbulence model. Do not touch this unless you know what you're doing.
-
(
float,lower bound=0.000,default=0.4100)- Von Karman constant used in the SA turbulence model. Do not touch this unless you know what you're doing.
-
(
float,default=0.1355)- SA cb1 constant. Do not touch this unless you know what you're doing.
-
(
float,default=0.6220)- SA cb2 constant. Do not touch this unless you know what you're doing.
-
(
float,default=1.200)- SA ct3 constant. Do not touch this unless you know what you're doing.
-
(
float,default=0.5000)- SA ct4 constant. Do not touch this unless you know what you're doing.
-
(
float,default=7.100)- SA cv1 constant. Do not touch this unless you know what you're doing.
-
(
float,default=0.3000)- SA cw2 constant. Do not touch this unless you know what you're doing.
-
(
float,default=2.000)- SA cw3 constant. Do not touch this unless you know what you're doing.
Preconditioner
- This section defines parameters related to the linear solver preconditioner used in the code.
preconditioner:
type:
ILUFill:
subIter:
-
type (
string,default="ilu")- Accepted Values: [
"ilu"] - The type of preconditioner to use.
ILU-
- Incomplete lower-upper (ILU) factorization.
- Accepted Values: [
-
ILUFill (
integer,lower bound=0,upper bound=10,default=1)- The level of fill used for ILU. Higher levels of fill take more time to apply and use more memory, but it can result in lower number of linear iterations. The most common values are 0 and 1. Values of 0 are more often used for unsteady simulations.
-
subIter (
integer,lower bound=1,upper bound=5,default=1)- The number of sub-iteration applications of preconditioner to perform. This option should be rarely changed. The only time this could be increased to 2 is if memory requirements dictate only a fill level of 0 can be used, but a stronger preconditioner is desired.
Boundary Conditions
- This section specifies the association between named subsets from the
grid > curv > BCFileto boundary conditions which should be applied/enforced on the specified boundaries.
BC:
-
type:
names:
location:
projectNodes:
symPlaneOrigin:
symPlaneNormal:
symPlaneAxis1:
symPlaneAxis2:
totalPressure:
totalTemperature:
inflowDir:
density:
pressure:
mach:
temperature:
velocity:
wallVelocity:
wallModel:
wallModelOrder:
matchLoc:
roughnessLength:
robustOutflow:
gridFile:
qFile:
useFreestream:
reflectNormalVelocityAboutMidpoint:
firstHaloExtrapolationOrder:
secondHaloExtrapolationOrder:
velocityExtrapolationOrder:
pressureTreatment:
temperatureTreatment:
-
type (
string,default="bcfarfield")- Accepted Values: [
"bcwallviscous","bcwallviscousisothermal","bcwallinviscid","bcsymmetryplane","bcfarfield","bcinflowsubsonic","bcoutflowsubsonic","bctypeuserdefined","bcextrapolate","bcinflowsupersonic","bcdirichlet","userdefined","bcdirichletriemann"] - Type of boundary condition to apply/enforce at the named BC subset.
BCWallViscous-
- No-slip adiabatic wall boundary condition.
BCWallViscousIsothermal-
- No-slip isothermal wall boundary. Requires the specification of a wall temperature.
BCWallInviscid-
- Slip-wall boundary condition.
BCSymmetryPlane-
- Symmetry plane boundary condition.
BCFarfield-
- Far-field Riemann invariants boundary condition.
BCInflowSubsonic-
- Subsonic inflow boundary condition. Requires the specification of one of the following variable combinations:
-
- a) Velocity magnitude, temperature, and flow angle;
-
- b) Total pressure, total temperature, and flow angle.
BCOutflowSubsonic-
- Subsonic outflow boundary condition. Requires the specification of pressure.
BCTypeUserDefined-
- User-supplied boundary condition. Requires the specification of a dynamic link library (DLL) file (refer to
curvSolver > userSharedObject).
- User-supplied boundary condition. Requires the specification of a dynamic link library (DLL) file (refer to
BCExtrapolate-
- Extrapolate all variables from interior. This can be used for supersonic outflows.
BCInflowSupersonic-
- Supersonic inflow boundary condition fixes the prescribed boundary values. Requires the specification of pressure, temperature, velocity magnitude, and flow angle.
BCDirichlet-
- Dirichlet-type boundary condition which fixes the boundary surface and the neighboring interior surface to pre-computed or set solution values.
BCDirichletRiemann-
- Dirichlet-Riemann boundary condition which resets the boundary surface and the neighboring interior surface to pre-computed or set solution values, and then applies the Riemann invariant boundary condition procedure first to the neighboring surface, and then to the boundary surface.
- Accepted Values: [
-
names ([
string, ...],default=["default"])- Name of the subset specified in
grid > curv > BCFile.
- Name of the subset specified in
-
location (
string,default="unknown")- Accepted Values: [
"unknown","onbody","offbody"] - The location of the boundary condition. Specifying this option will overwrite all other assessments of this BC performed during connectivity.
unknown-
- Let the code assess whether the BC should be associated with the geometry or not (default).
onBody-
- The BC is on the considered geometry.
offbody-
- The BC is not associated with the geometry, and can be ignored during connectivity.
- Accepted Values: [
-
projectNodes (
boolean,default=False)- If this BC is symmetry, this will project all nodes of a block face with this BC onto its symmetry plane using the normal and origin defined by the user, or at \(y=0\) if no symmetry plane definitions are provided.
-
symPlaneOrigin ([
float,float,float],default=[0.000, 0.000, 0.000])- If this BC is symmetry, this helps to explicitly define the symmetry plane when provided alongside either
symPlaneNormal, or bothsymPlaneAxis1andsymPlaneAxis2. The explicit definition will be used instead of block sides if projecting nodes. This argument defines the origin of the explicit symmetry plane definition.
- If this BC is symmetry, this helps to explicitly define the symmetry plane when provided alongside either
-
symPlaneNormal ([
float,float,float],default=[0.000, 0.000, 0.000])- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
symPlaneOrigin. This argument defines the normal of the explicit symmetry plane definition.
- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
-
symPlaneAxis1 ([
float,float,float],default=[0.000, 0.000, 0.000])- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
symPlaneOrigin. This argument defines the first axis (from the origin) of the explicit symmetry plane definition, and must be supplied together withsymPlaneAxis2.
- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
-
symPlaneAxis2 ([
float,float,float],default=[0.000, 0.000, 0.000])- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
symPlaneOrigin. This argument defines the second axis (from the origin) of the explicit symmetry plane definition, and must be supplied together withsymPlaneAxis1.
- If this BC is symmetry, this helps to explicitly define the symmetry plane along with
-
totalPressure (
float,lower bound=0.000,default=1.000)- Total pressure (or stagnation pressure) used in subsonic inflow.
-
totalTemperature (
float,lower bound=0.000,default=1.000)- Total temperature (or stagnation temperature) used in subsonic inflow.
-
inflowDir ([
float,float,float],default=[1.000, 0.000, 0.000])- Inflow direction which should have a norm of one. This defines the velocity direction used in subsonic inflow.
-
density (
float,lower bound=0.000,default=1.000)- Density which can be specified instead of temperature for a subsonic inflow boundary condition.
-
pressure (
float,lower bound=0.000,default=1.000)- Specified static pressure for subsonic outflow.
-
mach (
float,lower bound=0.000,default=0.5000)- Mach which can be specified instead of pressure for a subsonic outflow. Sometimes used in inlets for propulsion elements within a supersonic aircraft.
-
temperature (
float,lower bound=0.000,default=1.000)- Specified temperature for subsonic inflow or isothermal wall boundary condition(s).
-
velocity (
float,default=100.0)- Velocity magnitude used for subsonic inflows.
-
wallVelocity ([
float,float,float],default=[0.000, 0.000, 0.000])- Specified velocity for a moving adiabatic wall.
-
wallModel (
string,default="none")- Accepted Values: [
"muskerslaw","reichardtslaw","nosliplaw","roughwall","roughwallrandom","none","blendedloglaw","salaw"] - Wall model law.
muskersLaw-
- Follows fitting procedure of A.J. Musker (1979).
reichardtsLaw-
- Follows fitting procedure of H. Reichardt (1951).
noSlipLaw-
- Assumes resolution is sufficient to capture boundary layer.
roughWall-
- Includes surface roughness factors.
roughWallRandom-
- Randomizes the surface roughness. Only implemented for the Curvilinear-Cartesian immersed-boundary method.
blendedLogLaw-
- A fitting procedure that is computationally more efficient than
muskersLawandreichardtsLaw.
- A fitting procedure that is computationally more efficient than
SALaw-
- A profile consistent with the SA turbulence model that can be used when performing WM-RANS using the SA turbulence model.
- Accepted Values: [
-
wallModelOrder (
integer,lower bound=0,upper bound=2,mutable,default=1)- Method used for extrapolating data from the interior to the wall for a wall-modeled wall.
1-
- Constant (zeroth-order polynomial) extrapolation of pressure, temperature, and tangential velocity yielding first-order truncation error. Most robust option. This is equivalent to setting the following options:
firstHaloExtrapolationOrdertofirstOrder,secondHaloExtrapolationOrdertofirstOrder,velocityExtrapolationOrdertofirstOrder,pressureTreatmenttozeroGradientExtrapolation, andtemperatureTreatmenttozeroGradientExtrapolation.
- Constant (zeroth-order polynomial) extrapolation of pressure, temperature, and tangential velocity yielding first-order truncation error. Most robust option. This is equivalent to setting the following options:
2-
- Constant (zeroth-order polynomial) extrapolation of pressure and temperature yielding first-order truncation error, and linear (first-order polynomial) extrapolation of tangential velocity, yielding second-order truncation error. This is equivalent to setting the following options:
firstHaloExtrapolationOrdertofirstOrder,secondHaloExtrapolationOrdertofirstOrder,velocityExtrapolationOrdertosecondOrder,pressureTreatmenttozeroGradientExtrapolation, andtemperatureTreatmenttozeroGradientExtrapolation.
- Constant (zeroth-order polynomial) extrapolation of pressure and temperature yielding first-order truncation error, and linear (first-order polynomial) extrapolation of tangential velocity, yielding second-order truncation error. This is equivalent to setting the following options:
0-
- Linear (first-order polynomial) extrapolation of pressure and temperature. The stencil uses BDF2 coefficients (4/3, -1/3) and seeks to enforce second-order truncation error in the normal pressure and temperature gradients, although the pressure and temperature values themselves are associated with first-order truncation error. Constant (zeroth-order polynomial) extrapolation is used for the tangential velocity, yielding first-order truncation error. This is equivalent to setting the following options:
firstHaloExtrapolationOrdertosecondOrder,secondHaloExtrapolationOrdertofirstOrder,velocityExtrapolationOrdertofirstOrder,pressureTreatmenttozeroGradientExtrapolation, andtemperatureTreatmenttozeroGradientExtrapolation.
- Linear (first-order polynomial) extrapolation of pressure and temperature. The stencil uses BDF2 coefficients (4/3, -1/3) and seeks to enforce second-order truncation error in the normal pressure and temperature gradients, although the pressure and temperature values themselves are associated with first-order truncation error. Constant (zeroth-order polynomial) extrapolation is used for the tangential velocity, yielding first-order truncation error. This is equivalent to setting the following options:
-
matchLoc (
float,lower bound=1.000,upper bound=3.000,default=2.000)- This is the distance off the boundary used for wall model and viscous stress calculations, and should be set to integer values (e.g. 2). For body-fitted walls, the match location is placed that many cell layers off the wall. For sharp (i.e. Curv-Cart) immersed geometries, it will be scaled by the local Cartesian block cell size. For other general immersed approaches, it is a multiplicative factor of the
immersedBoundary > interpOffsetDistvalue defined in the IB entry.
- This is the distance off the boundary used for wall model and viscous stress calculations, and should be set to integer values (e.g. 2). For body-fitted walls, the match location is placed that many cell layers off the wall. For sharp (i.e. Curv-Cart) immersed geometries, it will be scaled by the local Cartesian block cell size. For other general immersed approaches, it is a multiplicative factor of the
-
roughnessLength (
float,lower bound=0.1000E-11,upper bound=1.000,mutable,default=0.1000E-09)- Length of the roughness used in the rough wall wall-model.
-
robustOutflow (
boolean,default=False)- This activates checking of the flow direction for the neighboring node to the boundary. If activated and the flow direction is not out of the domain, then perform a slip-wall procedure. This may need to be activated for propulsion inlets of supersonic aircraft if steady-state convergence is being slowed down by the use of the
BCSubsonicOutflowboundary condition at the propulsion inlet.
- This activates checking of the flow direction for the neighboring node to the boundary. If activated and the flow direction is not out of the domain, then perform a slip-wall procedure. This may need to be activated for propulsion inlets of supersonic aircraft if steady-state convergence is being slowed down by the use of the
-
gridFile (
string(fileName),default="bc.x")- This is the name of the Plot3D grid file representing the boundary surface and its neighbor when using
BCDirichletorBCDirichletRiemannboundary condition(s).
- This is the name of the Plot3D grid file representing the boundary surface and its neighbor when using
-
qFile (
string(fileName),default="bc.q")- This is the name of the Plot3D function file representing the solution on the boundary surface and its neighbor when using
BCDirichletorBCDirichletRiemannboundary condition(s).
- This is the name of the Plot3D function file representing the solution on the boundary surface and its neighbor when using
-
useFreestream (
boolean,default=False)- Allows the
BCDirichletorBCDirichletRiemannsurface and neighbor nodes be set to freestream instead of reading a Plot3D function file.
- Allows the
-
reflectNormalVelocityAboutMidpoint (
boolean,default=False)- Flag that reflects the normal velocity at the interior nodes near a wall-model wall about the first midpoint into the fluid off of the wall when populating the velocities in the halo nodes. This option only applies to
BCWallViscousandBCWallViscousIsothermalwalls when using a wall model. This option was introduced as a quick fix to run channel flow with WMLES and should be used with caution.
- Flag that reflects the normal velocity at the interior nodes near a wall-model wall about the first midpoint into the fluid off of the wall when populating the velocities in the halo nodes. This option only applies to
-
firstHaloExtrapolationOrder (
string,default="firstorder")- Accepted Values: [
"firstorder","secondorder"] - Controls the order of accuracy of extrapolation to the first halo node coinciding with the domain boundary. Note: the order refers to truncation error, not the degree of the extrapolating polynomial. This option applies to the pressure and temperature at
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model, and the primitive variables \([p, u, v, w, T]\) atBCExtrapolateboundaries. firstOrder-
- Constant (zeroth-order polynomial) extrapolation, yielding first-order truncation error.
secondOrder-
- Linear (first-order polynomial) extrapolation, yielding second-order truncation error. For
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model, the stencil uses BDF2 coefficients to compute the pressure (and/or temperature) in the first halo node, e.g., \(p_1 = \frac{4}{3} p_2 - \frac{1}{3} p_3\). This seeks to enforce second-order accuracy in the normal pressure gradient, although the first halo node value itself is only first-order accurate. ForBCExtrapolateboundaries, standard linear extrapolation is used, yielding second-order truncation error, e.g., \(p_0 = 2 p_1 - p_2\).
- Linear (first-order polynomial) extrapolation, yielding second-order truncation error. For
- Accepted Values: [
-
secondHaloExtrapolationOrder (
string,default="firstorder")- Accepted Values: [
"firstorder","secondorder"] - Controls the order of accuracy of extrapolation to the second halo node just beyond the domain boundary. Note: the order refers to truncation error, not the degree of the extrapolating polynomial. This option applies to the pressure and temperature at
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model, and the primitive variables \([p, u, v, w, T]\) atBCExtrapolateboundaries. firstOrder-
- Constant (zeroth-order polynomial) extrapolation, yielding first-order truncation error, e.g., \(p_0 = p_1\).
secondOrder-
- Linear (first-order polynomial) extrapolation, yielding second-order truncation error, e.g., \(p_0 = 2 p_1 - p_2\).
- Accepted Values: [
-
velocityExtrapolationOrder (
string,default="firstorder")- Accepted Values: [
"firstorder","secondorder"] - Controls the order of accuracy of extrapolation of velocity components \([u,v,w]\) to the first halo node coinciding with the domain boundary. Note: the order refers to truncation error, not the degree of the extrapolating polynomial. This option applies to
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model. firstOrder-
- Constant (zeroth-order polynomial) extrapolation, yielding first-order truncation error, e.g., \(u_1 = u_2\).
secondOrder-
- Linear (first-order polynomial) extrapolation, yielding second-order truncation error, e.g., \(u_1 = 2 u_2 - u_3\).
- Accepted Values: [
-
pressureTreatment (
string,default="zerogradientextrapolation")- Accepted Values: [
"zerogradientextrapolation","normalmomentum"] - Controls how pressure is set at boundary halo nodes. This option applies to
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model. zeroGradientExtrapolation-
- Copies/extrapolates the interior pressure seeking to enforce zero normal gradient at the wall.
normalMomentum-
- Computes the boundary pressure by solving a discrete normal momentum relation. Refer to 10.2514/3.50745 for details regarding the normal momentum relation. This option is not currently supported with grid motion and has not been throughly tested with iblanks and special corners.
- Accepted Values: [
-
temperatureTreatment (
string,default="zerogradientextrapolation")- Accepted Values: [
"zerogradientextrapolation","constantentropyextrapolation"] - Controls how temperature is set at boundary halo nodes. This option only applies to
BCWallInviscidwalls andBCWallViscousandBCWallViscousIsothermalwalls when using a wall model. zeroGradientExtrapolation-
- Copies/extrapolates the interior temperature seeking to enforce zero normal gradient at the wall.
constantEntropyExtrapolation-
- Copies the interior entropy from the first node off of the wall and recomputes temperature consistent with the boundary pressure using the equation of state.
- Accepted Values: [
Probes
- This section is used to define user-requested data to be recorded at probe points and surfaces. The surfaces are general, so this could be a Plot3D volume grid file containing a volume of points to probe. Probe surface data can often be used for external purposes like acoustic propagation using Ffowcs Williams-Hawkings (FWH) or monitoring functionals like mass flow rate.
probes:
point:
-
name: <required>
variables: <required>
position:
fileName:
sourceFileType:
stationaryProbeInMovingMesh:
surface:
-
sourceFileName: <required>
location: <required>
writeFrequency: <required>
stationaryProbeInMovingMesh:
bufferSize:
sourceFileType:
fileName:
outFileType:
name:
integrationVars:
variables:
precision:
outsideTreatment:
offset:
offsetUpdateFrequency:
yPlusTarget:
wallModel:
-
point
- This sub-section is used to define point probes.
-
name (
string,required)- Name associated with the probe point(s) for monitoring. Can be used with the
output > monitorinput section to get point probe data output.
- Name associated with the probe point(s) for monitoring. Can be used with the
-
variables ([
string, ...],required)- Variables to report at the probe point(s). Refer to the list of available variables here.
- NOTE: Certain variables may result in increased computational cost if probed at a high frequency. This is especially true for non-primitive variables computed from \([p, u, v, w, T]\). Make sure to consider how often any non-primitive variable needs probing.
-
position ([
float,float,float],default=[0.000, 0.000, 0.000])[X, Y, Z]position of point probe location.
-
fileName (
string(fileName),default="")- Filename containing list of [X, Y, Z] positions of point probe locations.
-
sourceFileType (
string,default="formatted")- Accepted Values: [
"unformatted","formatted"] - File type of the source point probe location.
unformatted-
- FORTRAN unformatted file.
formatted-
- ASCII formatted file.
- Accepted Values: [
-
stationaryProbeInMovingMesh (
boolean,default=False)- This option accounts for the movement of the mesh relative to a stationary probe by recomputing the probe donors and interpolation weights when appropriate. This option should be set to true if the mesh is moving and should be set to false if it is known that the probe will always be located in a stationary portion of the mesh throughout the mesh movement.
-
surface
- This sub-section is used to define surface probes.
-
sourceFileName (
string,required)- File name of the source sampling probe surface.
-
location (
string,required)- Accepted Values: [
"vertex","cellcentered"] - Location on the probe surface to interpolate data to.
vertex-
- Interpolate data to the surface nodes.
cellCentered-
- Interpolate data to the surface cell centers.
- Accepted Values: [
-
writeFrequency (
integer,required,lower bound=-1)- Frequency in number of iterations for steady runs or timestep for unsteady runs at which to extract and write the probe data.
- NOTE: The data may not be written to disk immediately depending on the
bufferSizespecified.
-
stationaryProbeInMovingMesh (
boolean,default=False)- Refer to
probes > point > stationaryProbeInMovingMeshabove.
- Refer to
-
bufferSize (
integer,lower bound=1,upper bound=10000,default=100)- Number of probe surface output files to store before writing to disk. It is highly encouraged to use a buffer size larger than 1 to increase performance since the write is MPI parallel.
- WARNING: If the simulation stops before the data is written it is lost. Also, if the buffer size is too large, the user may run out of memory.
-
sourceFileType (
string,default="tri")- Accepted Values: [
"tri","plot3d","tecplot"] - File type of the source sampling probe surface.
tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
Tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
fileName (
string,default="surfprobe")- Output file name prefix for sampled data.
-
outFileType (
string,default="tri")- Accepted Values: [
"tri","plot3d","tecplot","triq","sboom"] - Output file type for sampled data. Set to the same file type as in
sourceFileTypeby default, as well as forPlot3DandTecplotprobes. For tri probes the user may chooseTecplotoutput (Plot3Doutput is the same as tri). The user may also choose to output as atriqfile, which forces a specific choice of variables in the buffer to be accepted by triload. Refer to triload's documentation for more details. tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
Tecplot-
- Tecplot PLT binary format file.
triq-
- Annotated triangulation Cart3D file format. Refer to cart3dTriangulations for details.
SBOOM-
- Custom format required for input to the sonic boom propagation tool (sBOOM) developed at NASA Langley Research Center.
- Accepted Values: [
-
name (
string,default="")- Name associated with the probe surface for monitoring and reporting functions like lift, mass flow rate, or average Mach.
-
integrationVars ([
string, ...],default=["flow"])- Selects which variables to integrate on the probe.
flow-
- Activates mass flow rate, mass-averaged total pressure, mass-averaged total temperature, mass-averaged Mach, area, area-averaged total pressure, area-averaged total temperature, and area-averaged Mach.
aero-
- Aerodynamic forces and moments. Viscous contributions utilize a wall-model to compute skin friction on the surface.
aerop-
- Pressure-only aerodynamic forces and moments.
-
variables ([
string, ...],default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature"])- Surface probe variable(s) to be interpolated. Refer to the list of available variables here.
- NOTE: Certain variables may result in increased computational cost if probed at a high frequency. This is especially true for non-primitive variables computed from \([p, u, v, w, T]\). Make sure to consider how often any non-primitive variable needs probing.
- WARNING: Viscous surface-based average quantities, such as
cfavg, ustaravg, yplusavg, are currently not available for surface probing.
-
precision (
string,default="double")- Accepted Values: [
"single","double"] - Precision used in the output of the surface-sampled data.
single-
- Data is output in single-precision.
double-
- Data is output in double-precision.
- Accepted Values: [
-
outsideTreatment (
string,default="zerovalue")- Accepted Values: [
"zerovalue","reference"] - Values to assign to interpolation point if interpolation stencil is not found.
zeroValue-
- Assigns values to be zero.
reference-
- Assigns values based on reference freestream conditions.
- Accepted Values: [
-
offset (
float,default=0.2500E-03)- Offset distance to determine offset interpolation node locations. Used for \(\tau_{\text{wall}}\). The default value of 2.5e-4 [m] is what is required to obtain an average \(y^+\) value of about 51 for the probe surface for a flat plate test case.
-
offsetUpdateFrequency (
integer,lower bound=-1,default=-1)- This sets the frequency at which to update the probe surface offset distance for wall model evaluation based on the target average \(y^+\) value. Default value is -1. If set to a negative number it will prevent offset distance updates.
-
yPlusTarget (
float,lower bound=30.00,upper bound=100.0,default=55.00)- Average \(y^+\) value to target when updating probe surface offset distance for wall model evaluation. This value should be set such that the \(y^+\) values for the probe surface are within the log-layer. For this reason, 30 <=
yPlusTarget<= 100, and its default value is 55.
- Average \(y^+\) value to target when updating probe surface offset distance for wall model evaluation. This value should be set such that the \(y^+\) values for the probe surface are within the log-layer. For this reason, 30 <=
-
wallModel (
string,default="none")- Accepted Values: [
"muskerslaw","reichardtslaw","nosliplaw","roughwall","roughwallrandom","none","blendedloglaw","salaw"] - Possible wall model law for surface probe. Used for \(\tau_{\text{wall}}\). Refer to descriptions of wall model laws under
BC > wallModel.
- Accepted Values: [
Output
- This section is used to define the desired solution output parameters.
output:
ioProcs:
averageFrequency:
cylindricalAxisBeg:
cylindricalAxisEnd:
restart:
frequency:
fileName:
filesToKeep:
volume:
-
frequency:
fileName:
fileType:
precision:
variables:
surface:
-
frequency:
fileName:
fileType:
BCTypes:
names:
variables:
bufferSize:
slice:
-
frequency:
bufferSize:
fileName:
fileType:
debug:
forceMPIWrite:
variables:
specs:
-
plane:
values:
range:
origin:
normal:
writeDummyFileIfEmpty:
isoSurface:
-
isoVariable: <required>
isoValues: <required>
frequency:
bufferSize:
fileName:
fileType:
debug:
forceMPIWrite:
variables:
writeDummyFileIfEmpty:
monitor:
precision:
variables:
frequency:
adjoint:
write:
fileName:
writeRHS:
RHSFileName:
writeResidual:
residualFileName:
variables:
surfGradient:
-
families: <required>
fileName:
jacobian:
frequency:
fileName:
-
ioProcs (
integer,lower bound=0,default=0)- Number of processors over which the volume solution is partitioned to perform MPI parallel solution output. When set to 0 (default) all processors running the simulation are utilized.
-
averageFrequency (
integer,lower bound=1,upper bound=1000000000,default=1)- Frequency used to update the user-requested averaged variables. Default is 1 (every timestep) for implicit time-stepping. Consider increasing the frequency to 10 or 100 for explicit time-stepping.
-
cylindricalAxisBeg ([
float,float,float],mutable,default=[0.000, 0.000, 0.000])- The start point
[X, Y, Z]of the cylindrical axis with respect to which any cylindrical coordinates variable output is defined.
- The start point
-
cylindricalAxisEnd ([
float,float,float],mutable,default=[0.000, 0.000, 0.000])- The end point
[X, Y, Z]of the cylindrical axis with respect to which any cylindrical coordinates variable output is defined.
- The end point
-
restart
- This sub-section covers the output of restart files.
-
frequency (
integer,lower bound=-1,mutable,default=500)- Frequency used to write the restart file to disk in number of iterations (steady) or timesteps (unsteady).
-
fileName (
string,mutable,default="restart")- File name prefix used for the restart file(s).
-
filesToKeep (
integer,lower bound=0,upper bound=100,default=3)- Number of restart files to keep around. Since these can get large, only the latest
filesToKeepnumber of restarts are retained on the disk, while the previous restarts (written during the current simulation) are deleted.
- Number of restart files to keep around. Since these can get large, only the latest
-
volume
- This sub-section covers the output of volume files.
-
frequency (
integer,lower bound=-1,mutable,default=0)- Frequency used to write the volume file(s) to disk in number of iterations (steady) or timesteps (unsteady).
-
fileName (
string,mutable,default="volume")- File name prefix used for the volume output file(s).
-
fileType (
string,mutable,default="default")- Accepted Values: [
"plot3d","plot3dsoln","default"] - File type used in writing the volume solution.
Plot3D-
- Plot3D function file containing the user-requested volume solution variables. Refer to file formats page for details.
Plot3DSoln-
- Plot3D solution file which is restricted to 5 fields and includes a header containing the reference flow conditions. The five variables should be the conserved variables \([\rho, \rho u, \rho v, \rho w, e]\), but it is left to the user to set the variables as they may want dimensional or nondimensional conserved variables depending on the external program that is using the file. For example, triload and overint would typically be used with nondimensional conserved variables.
default-
- Use the input grid file type specified in
grid > curv > fileTypefor the output file type.
- Use the input grid file type specified in
- Accepted Values: [
-
precision (
string,mutable,default="double")- Accepted Values: [
"single","double"] - Precision used in the output of the volume data.
single-
- Data is output in single-precision.
double-
- Data is output in double-precision.
- Accepted Values: [
-
variables ([
string, ...],mutable,default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature", "Mach"])- List of variables to include the volume output file. Refer to the list of available output variables here.
-
surface
- This sub-section covers the output of surface files.
-
frequency (
integer,lower bound=-1,mutable,default=0)- Frequency used to write the surface file(s) to disk in number of iterations (steady) or timesteps (unsteady).
-
fileName (
string,mutable,default="surface")- File name prefix used for the surface output file(s).
-
fileType (
string,mutable,default="default")- Accepted Values: [
"plot3d","turbo","default"] - File type of the surface output file(s).
Plot3D-
- Plot3D function file containing the user-requested surface solution variables. Refer to file formats page for details.
turbo-
- Custom format used for coupling to the TURBO flow solver developed at NASA Glenn Research Center. Refer to 10.2514/6.2024-1195 for details.
default-
- Use the input grid file type specified in
grid > curv > fileTypefor the output file type.
- Use the input grid file type specified in
- Accepted Values: [
-
BCTypes ([
string, ...],default=["bcwallviscous", "bcwallinviscid", "bcsymmetryplane"])- Accepted Values: [
"bcwallviscous","bcwallviscousisothermal","bcwallinviscid","bcsymmetryplane","bcfarfield","bcinflowsubsonic","bcoutflowsubsonic","bctypeuserdefined","bcinflowsupersonic"] - Surface types to include in the surface output solution file(s) as defined by their boundary condition(s). These have a direct correspondence to the naming utilized in
BC > type.
- Accepted Values: [
-
names ([
string, ...],default=[""])- Names from the
grid > curv > subsetFileto include in the surface output solution file(s).
- Names from the
-
variables ([
string, ...],default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature"])- List of variables to include in the surface output solution file(s). Refer to the list of available output variables here.
-
bufferSize (
integer,lower bound=1,upper bound=10000,default=1)- Number of surface output solution file(s) to store before writing to disk. It is highly encouraged to use a buffer size larger than 1 to increase performance since the write is MPI parallel.
- WARNING: If the simulation stops before the data is written it is lost. Also, if the buffer size is too large, the user may run out of memory.
-
slice
- This sub-section covers the output of solution slices.
-
frequency (
integer,lower bound=-1,default=0)- Frequency used to write slice file(s) to disk in number of iterations (steady) or timesteps (unsteady).
-
bufferSize (
integer,lower bound=1,upper bound=10000,default=1)- Number of slice output solution file(s) to store before writing to disk. It is highly encouraged to use a buffer size larger than 1 to increase performance since the write is MPI parallel.
- WARNING: If the simulation stops before the data is written it is lost. Also, if the buffer size is too large, the user may run out of memory.
-
fileName (
string,mutable,default="slice")- File name prefix used for the slice output file(s).
-
fileType (
string,default="tecplot")- Accepted Values: [
"tecplot"] - File type used for the slice output file(s).
tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
debug (
boolean,default=False)- Debug flag used to get minimal verbose information during runtime related to slicing algorithm.
-
forceMPIWrite (
boolean,default=False)- Flag used to force parallel MPI data writing. Only use this option if the ranks are running out of memory when using slice or iso-surface output. Currently only available with Tecplot PLT binary file output.
-
variables ([
string, ...],default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature"])- List of variables to be sampled at (interpolated onto) the slice triangulation nodes. Refer to the list of available output variables here.
-
specs
- Specify different slice definitions in this sub-section.
-
plane (
string,default="y")- Accepted Values: [
"x","y","z","general"] - Slice cut plane.
x,y,z-
- Slice the volume solution at a constant X, Y or Z plane. The user must also provide a list of
valuesor arangedefining the slice.
- Slice the volume solution at a constant X, Y or Z plane. The user must also provide a list of
general-
- Slice the volume solution along a general plane. User must also provide
originandnormalfor each slice specification.
- Slice the volume solution along a general plane. User must also provide
- Accepted Values: [
-
values ([
float, ...],default=[0.000])- List of values defining the constant coordinate(s) (
x,yor 'z') to take the slice at. Cannot be used whenrangeis provided.
- List of values defining the constant coordinate(s) (
-
range ([
float,float,float],default=[0.000, 1.000, 2.000])- Take slices using a range. The first number is the start value, the second number is the end value, and third number corresponds to the number of slices between the start and end values (slices are equally spaced in the range provided). Cannot be used when
valuesis provided.
- Take slices using a range. The first number is the start value, the second number is the end value, and third number corresponds to the number of slices between the start and end values (slices are equally spaced in the range provided). Cannot be used when
-
origin ([
float,float,float],default=[0.000, 0.000, 0.000])- The
[X, Y, Z]location corresponding to the origin of the slice when usingplane: general. User must also supplynormal.
- The
-
normal ([
float,float,float],default=[0.000, 0.000, 0.000])- The
[X, Y, Z]defining the vector normal to the slicing plane when usingplane: general. User must also supplyorigin.
- The
-
writeDummyFileIfEmpty (
boolean,default=False)- Flag used to force the writing of a dummy file at the specified frequency even if the surface does not have data. By default, a dummy file is written when data is not found on the surface only after the surface has already had data on it at a previous writing time-step/iteration.
-
isoSurface
- This sub-section covers the output of solution iso-surfaces.
-
isoVariable (
string,required,mutable)- Variable that will be probed to define the iso-surface geometry. The geometry is defined by the
isoValuesof the variable specified here. Refer to the list of available variables here.
- Variable that will be probed to define the iso-surface geometry. The geometry is defined by the
-
isoValues ([
float, ...],required,mutable)- List of value(s) used to define the iso-surface(s) from the volume solution.
-
frequency (
integer,lower bound=-1,mutable,default=0)- Frequency used to write iso-surface file(s) to disk in number of iterations (steady) or timesteps (unsteady).
-
bufferSize (
integer,lower bound=1,upper bound=10000,default=1)- Number of iso-surface output solution file(s) to store before writing to disk. It is highly encouraged to use a buffer size larger than 1 to increase performance since the write is MPI parallel.
- WARNING: If the simulation stops before the data is written it is lost. Also, if the buffer size is too large, the user may run out of memory.
-
fileName (
string,mutable,default="isosurface")- File name prefix used for the iso-surface output file(s).
-
fileType (
string,default="tecplot")- Accepted Values: [
"tecplot"] - File type used for the iso-surface output file(s).
tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
debug (
boolean,default=False)- Debug flag used to get minimal verbose information during runtime related to iso-surfacing algorithm.
-
forceMPIWrite (
boolean,default=False)- Flag used to force parallel MPI data writing. Only use this option if the ranks are running out of memory when using slice or output. Currently only available with Tecplot PLT binary file output.
-
variables ([
string, ...],default=["pressure", "velocityX", "velocityY", "velocityZ", "temperature"])- List of variables to be sampled at (interpolated onto) the iso-surface(s) triangulation nodes. Refer to the list of available variables here.
-
writeDummyFileIfEmpty (
boolean,default=False)- Flag used to force the writing of a dummy file at the specified frequency even if the surface does not have data. By default, a dummy file is written when data is not found on the surface only after the surface has already had data on it at a previous writing time-step/iteration.
-
monitor
- This sub-section covers the monitoring and reporting of user-defined solution functionals to STDOUT.
-
precision (
integer,lower bound=4,upper bound=18,mutable,default=7)- Precision (number of digits) used when writing to STDOUT for the monitored variables.
-
variables ([
string, ...],mutable,default=["cl", "cd", "cmy"])- List of solution functionals to monitor in STDOUT. This list accepts a vast amount of functionals that are defined depending on other user-provided inputs to the code.
- Some typical examples that are always available are
minpressure, mintemperature, maxmach, etc., which allow for monitoring of min/max primitive variables as the solution progresses to quickly detect suspect flow solves. - Functionals that depend on user-defined surface integrations are also available. These are automatically defined based on the boundary condition specifications provided by the user. Dimensional force/moment functionals (
forcex, forcey, momenty) as well as non-dimensional coefficients (cl, cd, cmy, cfx, cfy) may be requested. These functionals may also be appended with a boundary condition (BC) name (as defined in thegrid > curv > BCFileto obtain the force/moment functional applied to that BC. For example, if two separate surface definitions are provided in theBCFile, with the nameswingandfuselage, then functionals such ascl_wing, cd_wing, cl_fuselage, cd_fuselage, cfx_wing, forcey_wingare available. - This option may also be combined with point and surface probes (via
probes > pointandprobes > surface). Variables may be monitored at point probes defined inside the computational domain by appending the name defined for the probe to the variable name. For example, if a point probe has been defined withprobes > point > name: point_1, then variables such aspressure_point1andmach_point1are available. Surface probes may also be desirable for monitoring flow-rates or mass-averaged/area-averaged quantities across a flow section. If a surface probe has been defined withprobes > surface > name: surf1, andprobes > surface > integrationVars: flow, functionals such as the mass flow rate (mdot_surf1), mass-averaged total-pressure, total-temperature and Mach (mavgptot_surf1, mavgttot_surf1, mavgmach_surf1) and area-averaged total-pressure, total-temperature and Mach (aavgptot_surf1, aavgttot_surf1, aavgmach_surf1) are also available for monitoring.
-
frequency (
integer,lower bound=1,default=1)- Frequency used to report the user-requested monitor variables STDOUT. Default is 1 for steady-state and implicit time-stepping. Consider increasing the frequency to 10 or 100 for explicit time-stepping.
-
adjoint
- This sub-section covers the output of adjoint solution files.
-
write (
boolean,mutable,default=False)- Flag used to specify whether to write the adjoint solution to a file.
-
fileName (
string,mutable,default="adjoint.q")- Name of file containing the adjoint solution. It should contain the file extension.
-
writeRHS (
boolean,mutable,default=False)- Flag used to specify whether to write the adjoint RHS \((\partial J / \partial Q)\) to a file.
-
RHSFileName (
string,mutable,default="adjointRHS.q")- Name of file containing the adjoint RHS. It should contain the file extension.
-
writeResidual (
boolean,mutable,default=False)- Flag used to specify whether to write the adjoint residual \((\partial J / \partial Q - \psi^T \partial R / \partial Q)\) to a file.
-
residualFileName (
string,mutable,default="adjointRes.q")- Name of file containing the adjoint residual. It should contain the file extension.
-
variables ([
string, ...],mutable,default=["adjointp", "adjointu", "adjointv", "adjointw", "adjointt"])- List of variables to include in the adjoint output file.
-
surfGradient
- Use this sub-section to define families of surface gradients to output.
-
families ([
string, ...],required)- Name of surface families for surface gradient output.
-
fileName (
string,default="surfGrad.plt")- Name of file containing the surface gradient. It should contain the file extension.
-
jacobian
- This sub-section covers the output of jacobian files. These files are only useful for debugging and developer.
-
frequency (
integer,lower bound=-1,mutable,default=-1)- Frequency used to write the jacobian file to disk in number of iterations (steady) or timesteps (unsteady).
-
fileName (
string,mutable,default="jacobian")- File name prefix used for the jacobian file(s).
Overlapper
- This section is used to define parameters associated with the integration of solution functionals over viscous surfaces.
overlapper:
ignoreImmersedBoundaries:
simpleIntersectionWeights:
method:
wallPriorityType:
tolerance:
offsetEpsPerc:
projAngLim:
coPlanarPreference:
writeOctTrees:
writeADTTrees:
writeBlanking:
writeIntersections:
writeAllIntegratedGeom:
writeZonesIntegratedGeom:
debugWallBlkJKL:
debugWallBlkBCCell:
debugWallGlbCell:
debugIBFileCell:
debugIBSurfCell:
debugIBGlbCell:
debugVerbose:
debugWriteWallBlankingFronts:
debugWriteIBBlankingFronts:
debugWriteIOUncertainNodes:
debugWriteClipPoly:
-
ignoreImmersedBoundaries (
boolean,default=False)- This is an option which will allow immersed boundaries to be ignored. This is currently implemented as a stop-gap to prevent errors while kinks in the isect processess are being finalized. Note that if this is True, but IB surfaces still exist, they will STILL be integrated over, but the panel weights will be assigned based on cell-center and offset interpolation validity instead of actual weights (i.e. exactly what probes do).
-
simpleIntersectionWeights (
boolean,default=False)- This option should only be used as a stop-gap if the calculation of immersed boundary <-> wall intersections goes awry during panel weight calculation. This option causes panel weights of intersected wall or immersed boundary elements to become a fraction of the nodes external to other surfaces. If issues are found with intersecting panel weights, set this to true and contact James Koch.
-
method (
string,default="dcel")- Accepted Values: [
"dcel","bruteforce"] - The method used to integrate on viscous surfaces when using the LAVA-internal overlapper integration tool. Overlapping quads are projected and parameterized, and a fraction found for each quad which represents the surface it owns.
DCEL-
- Uses a doubly-connected edge list (DCEL) surface-overlap decomposition to sub-divide the overlap exacly.
bruteForce-
- The brute force method is less-accurate, creating an integration grid to approximate quad area.
- Accepted Values: [
-
wallPriorityType (
string,default="elemarea")- Accepted Values: [
"zonearea","elemarea"] - The method used to define viscous surface element priority when using the LAVA-internal overlapper integration tool so that accounted-for surface is unit. Lesser area always correlates to higher priority.
zoneArea-
- Sets priority of all elements in the zone to that of the zone's average area.
elemArea-
- Sets each elements's priority to its own area.
- Accepted Values: [
-
tolerance (
float,default=0.1000E-07)- The tolerance for overlap clipping and intersection checks.
-
offsetEpsPerc (
float,default=1.000)- The positive percentage by which the quad bounding box is expanded prior to checking for quad-quad overlap. Default is 1.0%: increase if finding that certain overlap sections aren't recognizing each-other (which generally only happens when compared cells are Cartesian axis-aligned).
-
projAngLim (
float,default=78.00)- The angle in degrees which limits which quads can project onto eachother when comparing normals. Increase to be more lenient. It is bounded between 45 and 85 degrees. USURP uses 78 degrees.
-
coPlanarPreference (
string,default="immersed")- Accepted Values: [
"immersed","wall"] - If immersed boundaries and viscous walls both exist when generating panel weights, then it is possible they could have elements which are coplanar. In this situation, either all walls or all immersed elements should be considered over the other set.
immersed-
- Immersed elements are preferred (default).
wall-
- Wall elements are preferred.
- Accepted Values: [
-
writeOctTrees (
boolean,default=False)- Will write the last iteration of the flooded surface-defining octrees for all walls and immersed boundary surfaces.
-
writeADTTrees (
boolean,default=False)- Will write the surface defining the IO search ADT trees of all walls and immersed boundary surfaces.
-
writeBlanking (
boolean,default=False)- Will write the blanking values for all walls and immersed boundary surfaces in a single Tecplot
.pltfile.
- Will write the blanking values for all walls and immersed boundary surfaces in a single Tecplot
-
writeIntersections (
boolean,default=False)- Will write the intersection cutlines between all walls and immersed boundary surfaces in a single Tecplot
.pltfile.
- Will write the intersection cutlines between all walls and immersed boundary surfaces in a single Tecplot
-
writeAllIntegratedGeom (
boolean,default=False)- Will write a triangulated representation of the accounted-for integration area of all walls and immersed boundaries. All wall and immersed surface portions of this integration area will be in a single zone. Note that actual integration in the LAVA code is still a node-fractional representation.
- WARNING: very high cell count for the
bruteForcemethod.
-
writeZonesIntegratedGeom (
boolean,default=False)- Will write a triangulated representation of the accounted-for integration area of all walls and immersed boundaries. Each zone in this file pertains to a wall zone's or immersed surface's integration portion. Note that actual integration in the LAVA code is still a node-fractional representation.
- WARNING: very high cell count for the
bruteForcemethod.
-
debugWallBlkJKL ([
float,float,float,float],default=[0.000, 0.000, 0.000, 0.000])- Format is
[iBlk, j, k, l]. If this is provided, then debug info related to the surface quad with the lower-left jkl index ofiBlkwill be printed during the overlapper process. Note that this jkl MUST pertain to a lower-left boundary-condition (BC) cell within the defined block.
- Format is
-
debugWallBlkBCCell ([
float,float,float],default=[0.000, 0.000, 0.000])- Format is
[iBlk, iBC, iElem]. If this is provided, then debug info related to the wall BC surface of the block will be printed during the overlapper process. Generally, the user would getiBlk,iBCandiElemby interrogatingoverlap_wallElemFracs.pltand looking at the zone name and cell index label.
- Format is
-
debugWallGlbCell (
float,default=0.000)- If this is provided, then information related to this unique wall surface quad will be printed to the screen during the overlapper routine. This option is used for more print-in-line debugging approaches.
-
debugIBFileCell ([
float,float],default=[0.000, 0.000])- Format is
[fileI, elemI]. If this is on, then information related to elementelemIwithin immersed boundaryfileI's surface file will be printed to the screen during the overlapper routine.
- Format is
-
debugIBSurfCell ([
float,float],default=[0.000, 0.000])- Format is
[iSurf, iCell]. If this is provided, then debug info related to this unique IB surface cell will be printed during the overlapper process. Generally, the user would getiSurfandiCellby interrogatingoverlap_IBElemFracs.plt. - NOTE:
iSurfmay not be the same asfileI, because spatially-unique surface sets are divided if multiple exist within a single immersed surface file.
- Format is
-
debugIBGlbCell (
float,default=0.000)- If this is provided, then information related to this unique IB surface quad will be printed to the screen during the overlapper routine. This option is used for more print-in-line debugging approches.
-
debugVerbose (
boolean,default=False)- Debugging will print each looked-at cell in order to help find issue.
-
debugWriteWallBlankingFronts (
boolean,default=False)- Debugging will write each wall flood iteration's blanked nodes.
- WARNING: Can take a while to run.
-
debugWriteIBBlankingFronts (
boolean,default=False)- Debugging will write each IB flood iteration's blanked nodes.
- WARNING: Can take a while to run.
-
debugWriteIOUncertainNodes (
boolean,default=False)- Debugging will write all wall and IB intersection-local nodes which have uncertain oct/ADT IO raycast checks.
-
debugWriteClipPoly (
boolean,default=False)- Print and write the clip poly task required for isect negative area calc. This is quite verbose, so is default false.
B2B Extractor
- This section is used to automate the generation of the file specifying block-to-block (B2B) interfaces when they are present in the grid file (the
grid > curv > B2BFile).
B2BExtractor:
extractB2Bs:
writePrefix:
onlyFullB2Bs:
fullInds:
nPatchAlloc:
orderByDonor:
writeB2BZones:
warnPartialB2Bs:
debugBlkID:
debugFaceI:
transformations:
-
type:
translationVec:
rotAxisBeg:
rotAxisEnd:
rotAxisAng:
blockTols:
-
zone: <required>
B2BTol: <required>
ignoredBlockFaces:
-
zone: <required>
faceI: <required>
-
extractB2Bs (
boolean,default=False)- Will read grid file, find all B2B relations between blocks, write B2B file and use the written file.
-
writePrefix (
string,default="NONE")- The prefix of the file holding extracted b2bs. If none is provided, then the grid name will be the prefix.
-
onlyFullB2Bs (
boolean,default=False)- If true, then only B2B connections between entire block faces which match 1:1 will be considered for b2bs.
-
fullInds (
boolean,default=False)- When writing the B2B file, jkl indices will be the full index values instead of (possibly) -1 which represents the max index value.
-
nPatchAlloc (
integer,default=50)- The max number of B2B patches that is allocated per block. The default should be ok pretty much always.
-
orderByDonor (
boolean,default=False)- Orders the written b2bs for a block by donor block ID instead of by face I
-
writeB2BZones (
boolean,default=False)- Will write all the grid surfaces associated with the b2bs found to a file with the prefix defined in
B2BExtractor > writePrefix+.b2b.x.
- Will write all the grid surfaces associated with the b2bs found to a file with the prefix defined in
-
warnPartialB2Bs (
boolean,default=False)- B2B extraction process will provide warnings if partial b2bs are detected (unless
B2BExtractor > onlyFullB2Bsis true, in which case there is no need to check). This can be used to check if the process finds partials when the user does not expect there should be any, and can find errors in grid topology.
- B2B extraction process will provide warnings if partial b2bs are detected (unless
-
debugBlkID (
integer,default=-1)- A debug block ID for the B2B extraction process. Will spit out data for that block. It is recommented to specify
B2BExtractor > debugFaceIas well to get more specific info.
- A debug block ID for the B2B extraction process. Will spit out data for that block. It is recommented to specify
-
debugFaceI (
integer,default=-1)- A debug block face I for the B2B extraction process. To use, also specify
B2BExtractor > debugBlkID.
- A debug block face I for the B2B extraction process. To use, also specify
-
transformations
- Entries here are a transformation type and its info.
-
type (
string,default=)- Accepted Values: [
"none","translation","rotation"] - A periodic transformation type which is relevant for the entire mesh.
none-
- No periodic transformation is applied (default).
translation-
- Apply a periodic translation transformation (e.g. infinite wing). Must specify
translationVec.
- Apply a periodic translation transformation (e.g. infinite wing). Must specify
rotation-
- Apply a periodic rotational transformation (e.g. turbomachinery blade cascade). Must specify
rotAxisBeg,rotAxisEnd, androtAxisAng.
- Apply a periodic rotational transformation (e.g. turbomachinery blade cascade). Must specify
- Accepted Values: [
-
translationVec ([
float,float,float],default=[0.000, 0.000, 0.000])- The
[X, Y, Z]periodic translation vector for the B2B extraction process.
- The
-
rotAxisBeg ([
float,float,float],default=[0.000, 0.000, 0.000])- The
[X, Y, Z]of the periodic rotation axis start point for the B2B extraction process.
- The
-
rotAxisEnd ([
float,float,float],default=[0.000, 0.000, 0.000])- The
[X, Y, Z]of the periodic rotation axis end point for the B2B extraction process.
- The
-
rotAxisAng (
float,default=0.000)- The periodic rotation angle for the B2B extraction process.
-
blockTols
- Entries here are a block and tolerance pair, and will change the tolerance of B2B face contact checks for those specific blocks during the b2bExtractor process. Should only be used as a last resort. It is recommended that the grids be fixed first.
-
zone (
integer,required)- The block which will be assigned a new B2B tolerance.
-
B2BTol (
float,required)- The tolerance used for B2B checks during the B2BExtractor process instead of
curvSolver > b2bTol.
- The tolerance used for B2B checks during the B2BExtractor process instead of
-
ignoredBlockFaces
- Entries here are a block and faceID pair, and will set a block face to be ignored by the B2BExtractor process. Should only be used as a last resort. It is recommended that the grids be fixed first.
-
zone (
integer,required)- The block number to be ignored by the B2BExtractor process.
-
faceI (
integer,required)- The face of the block to be ignored by the B2BExtractor process (follows the mapping 1-6 -> JMin, JMax, KMin, KMax, LMin, LMax).
Rotating Mesh
- This section defines regions of the mesh that are to undergo rotational motion as the simulation progresses.
- NOTE: Make sure to set
timeStepping > gridMotiontoTruefor the motion specified in this section to take effect.
rotatingMesh:
-
omega:
zones:
axis1:
axis2:
-
omega (
float,default=1.000)- Angular rotation rate in radians per second.
-
zones ([
string, ...],default=[""])- List of zones that undergo rotational motion.
-
axis1 ([
float,float,float],default=[0.000, 0.000, 0.000])- Start point
[X, Y, Z]of mesh rotation axis.
- Start point
-
axis2 ([
float,float,float],default=[1.000, 0.000, 0.000])- End point
[X, Y, Z]of mesh rotation axis.
- End point
Immersed Boundaries
- This section is used to define immersed boundaries within the computational domain.
immersedboundaries:
-
fileName: <required>
filetype: <required>
updateType:
octTreefilename:
octTreeCubes:
octTreeMinDepth:
octTreeMaxDepth:
octTreeCubesPerEdge:
zones:
BCName:
timescaleInterval:
timescaleValues:
timescaleValuesType:
timescaleIntervalType:
timescaleRampType:
ibMarkOffsetDist:
interpOffsetDist:
uniqueSurfOptions:
-
uniqueSurfs:
octTreeCubes:
octTreeMinDepth:
octTreeMaxDepth:
octTreeCubesPerEdge:
timescale:
cartInterpOffsetDistFactor:
-
fileName (
string(fileName),required)- Filename containing the closed water-tight surface triangulation which represents the immersed body.
-
filetype (
string,required)- Accepted Values: [
"tri","tecplot"] - Filetype of the immersed boundary surface triangulation.
tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
updateType (
string,default="settozero")- Accepted Values: [
"settozero","drivetozero"] - The type of update the immersed boundary undergoes each timestep.
setToZero-
- Forces velocity/momentum to be 0, but can be numerically unstable.
driveToZero-
- Drives velocity/momentum toward zero using an update \(\eta\) of \(1 / T\), where \(T\) is the timescale.
- Accepted Values: [
-
octTreefilename (
string,default="")- Filename for octree used for in/out testing of the immersed boundary
-
octTreeCubes (
integer,default=500000)- The maximum number of cubes allowed in the octree. If resolution is poor, increase. Decrease to resolve memory limit issues.
-
octTreeMinDepth (
integer,default=9)- Minimum number of subdivision levels allowed to resolve the immersed surface using an octree. Lower to allow enforcement of memory limitations. Raise to force increase of minimum surface resolution.
-
octTreeMaxDepth (
integer,default=12)- Maximum number of subdivision levels allowed to resolve the immersed surface using an octree. Lower this to enforce memory limitations. Raise to allow increased local resolution if needed.
-
octTreeCubesPerEdge (
float,default=2.000)- Resolution requirement of immersed surface octree which states how many final cubes must be on a surface edge. Default is usually OK.
-
zones ([
string, ...],default=[""])- List of zones that claim to represent this immersed boundary. If specified, nodes of these zones will not be blanked by connectivity when found to be inside closed geometry, instead being marked as immersed. Nodes of these grids may still be blanked by explicit hole cuts. Can cause the
IBINDfile to be re-written if its write was desired. - NOTE: To properly remember the update to the
IBINDfile, ensure thatcurvSolver > writeIBINDFileis set to true.
- List of zones that claim to represent this immersed boundary. If specified, nodes of these zones will not be blanked by connectivity when found to be inside closed geometry, instead being marked as immersed. Nodes of these grids may still be blanked by explicit hole cuts. Can cause the
-
BCName (
string,default="default")- This is the name of the BC which this immersed boundary will seek to emulate. The name list of each entry in the BC sub-dictionary will be looked through until this BC name is found.
- NOTE: The BC entry for the immersed boundary must include definitions for both
BC > matchLocandBC > wallModel.
-
timescaleInterval ([
integer, ...],default=1)- Array of integers specifying the iteration or CTU value to update timescale for immersed boundary penalization.
-
timescaleValues ([
float, ...],default=[0.1000E-07])- Array of real numbers specifying the timestep values or multiplicative factor relative to the physical timestep for explicit solvers
-
timescaleValuesType (
string,default="none")- Accepted Values: [
"none","factor","specified"] - Type of timescale scheduling.
none-
- Turn off all timescale scheduling (default).
factor-
- Interprets the values specified in
immersedBoundaries > timescaleValuesas a multiplicative factor of the timestep for explicit solvers.
- Interprets the values specified in
specified-
- Interprets the values specified in
immersedBoundaries > timescaleValuesas explicit values.
- Interprets the values specified in
- Accepted Values: [
-
timescaleIntervalType (
string,default="iter")- Accepted Values: [
"ctu","iter"] - Type of timescale scheduling interval.
iter-
- Interprets
immersedBoundaries > timescaleIntervalas an array of outer iterations.
- Interprets
ctu-
- Interprets
immersedBoundaries > timescaleIntervalas an array of integer CTU values.
- Interprets
- Accepted Values: [
-
timescaleRampType (
string,default="discrete")- Accepted Values: [
"linear","discrete"] - Type of timescale ramping.
linear-
- Linearly interpolates at each outer iteration between the containing user-specified interval. May be viewed as continuous ramping.
discrete-
- Changes the value of timescale at each timescale interval provided by the user (default). May be viewed as discrete ramping.
- Accepted Values: [
-
ibMarkOffsetDist (
float,default=0.000)- This is a user-defined physical distance off of this immersed boundary's elements normals which, if > 0.0, will tag volume cells as inside the immersed geometry if they are outside the surface but still within this distance.
- NOTE: This value is meant to be small, as it is only used if volume nodes fall within the wall-holding cells of the search octree.
-
interpOffsetDist (
float,default=0.2500E-03)- This is a user-defined physical distance off of this immersed boundary's elements normals at which interpolation points will be placed. This value times its
BC > matchLocwill determine the wall model interp location, while a number of successive offset locations equal tocurvSolver > nImmersedWallOffsetPtswill be used to interpolate integrable immersed surface values from the volume solution. The default value of 2.5e-4 is what is required to obtain an average yplus value of about 51 for the probe surface for a flat plate test case.
- This is a user-defined physical distance off of this immersed boundary's elements normals at which interpolation points will be placed. This value times its
-
uniqueSurfOptions
- Use this section to define unique surfaces within the supplied immersed boundary file.
-
uniqueSurfs ([
string, ...],default=[""])- The ids of the unique surfaces within the supplied immersed boundary file. If there is only a single unique surface, then there is no need to use
immersedBoundaries > uniqueSurfOptions.
- The ids of the unique surfaces within the supplied immersed boundary file. If there is only a single unique surface, then there is no need to use
-
octTreeCubes (
integer,default=500000)- Refer to
immersedBoundaries > octTreeCubesabove.
- Refer to
-
octTreeMinDepth (
integer,default=9)- Refer to
immersedBoundaries > octTreeMinDepthabove.
- Refer to
-
octTreeMaxDepth (
integer,default=12)- Refer to
immersedBoundaries > octTreeMaxDepthabove.
- Refer to
-
octTreeCubesPerEdge (
float,default=2.000)- Refer to
immersedBoundaries > octTreeCubesPerEdgeabove.
- Refer to
-
timescale (
float,default=0.1000E-03) -
cartInterpOffsetDistFactor (
float,default=1.000)- If this immersed boundary surface is represented by a
sharpIB type, then itsimmersedBoundary > interpOffsetDistsused for surface integration and wall model calculation are automatically inferred directly from the local mesh dx. This factor multiplies the found dx to increase the effectiveimmersedBoundary > interpOffsetDistsif needed.
- If this immersed boundary surface is represented by a
Actuator Regions
- This section is used to define actuator regions inside the computational domain. This feature can be used to apply volumetric momentum sources inside the fluid domain.
actuatorRegions:
-
rotAxisBegin: <required>
rotAxisEnd: <required>
thrust: <required>
names:
type:
method:
torque:
interpolationFile:
actuatorLineFile:
relax:
iterRelaxRange:
-
rotAxisBegin ([
float,float,float],required)- Start point
[X, Y, Z]of actuator region rotation axis. Currently no nodes of the actuator region can lie on the axis of rotation.
- Start point
-
rotAxisEnd ([
float,float,float],required)- End point
[X, Y, Z]of actuator region rotation axis. Currently no nodes of the actuator region can lie on the axis of rotation.
- End point
-
thrust (
float,required)- Total thrust force imparted to the flow through the entire actuator region.
-
names ([
string, ...],default=["default"])- List of names of regions specified in the subset file. These names must match those provided in the first colum of the file provided in
grid > curv > subsetFile. The actuator disk will be applied over these regions.
- List of names of regions specified in the subset file. These names must match those provided in the first colum of the file provided in
-
type (
string,default="disk")- Accepted Values: [
"disk"] - Actuator region type. Options include:
disk-
- The source terms are applied uniformly across a disk. This is a steady-state computation.
- Accepted Values: [
-
method (
string,default="const")- Accepted Values: [
"const"] - Actuator region method. Options include:
const-
- Constant loading across the radius of the disk.
- Accepted Values: [
-
torque (
float,default=0.000)- Total torque imparted to the flow through the entire actuator region.
-
interpolationFile (
string(fileName),default="")- Prescribed loading distribution across the radius of the disk. Only used if using
method: interp.
- Prescribed loading distribution across the radius of the disk. Only used if using
-
actuatorLineFile (
string(fileName),default="")- File containing control points used in the distribution function for the actuator line approach when
type: lineis used. Refer to NTRS/20220010349 for more details.
- File containing control points used in the distribution function for the actuator line approach when
-
relax (
boolean,default=True)- Whether to apply a relaxation/ramping factor to the source terms for this actuator disk during the flow solve.
-
iterRelaxRange ([
integer,integer],default=0)- Nonlinear iterations range (start and end) over which this actuator disks source terms are ramped from zero (not applied) to one (fully applied).
Adjoint
- This section defines parameters associated with the adjoint solver.
adjoint:
method:
objectives:
-
name: <required>
weight:
designVariables:
pseudo:
timeStepStart:
timeStepMax:
timeStepMin:
timeStepRamp:
timeStepStepTol:
iterMax:
tolerance:
matFree:
doLineSearch:
timeStepLinItsTol:
maxTimeStepLinTol:
linearSolver:
tolerance:
subSpaceSize:
iterMax:
monitor:
solver:
recycleSize:
iterativeRefinement:
preconditioner:
type:
ilufill:
subIter:
freezeT:
scaleAdjointOutput:
freezeConnectivity:
probeTargets:
-
name: <required>
fileName: <required>
sourceFileType:
targetVars:
precision:
exactBCDiff:
freezeProbeWeights:
sBOOMAdjoints:
-
probeName: <required>
fileName:
weight:
warmStartFromApprox:
exactSolutionErrorVariables:
-
method (
string,default="approx")- Accepted Values: [
"approx","pseudo","exact"] - The linear adjoint solver method.
approx-
- Approximate linear adjoint solver method.
pseudo-
- Pseudo linear adjoint solver method.
exact-
- Exact linear adjoint solver method.
- Accepted Values: [
-
objectives
- This sub-section defines the objective functionals for either optimization or adaptation.
-
name (
string,required)- Objective functionals for either optimization or adaptation.
-
weight (
float,default=1.000)- Weights used for multi-objective functionals.
-
designVariables ([
string, ...],default=["alpha"])- Design variables for optimization.
-
pseudo
-
timeStepStart (
float,default=0.000)- Starting timestep size for pseudo-transient continuation (PTC) of adjoint. If set to zero (\(< 10^{-12}\)), then no PTC is done and it goes straight into the inexact-Newton method.
-
timeStepMax (
float,default=0.000)- Maximum timestep size for pseudo-transient continuation (PTC) of adjoint. If set to zero (\(< 10^{-12}\)), then the max step is infinity!... which means it will eventually switch into the inexact-Newton method.
-
timeStepMin (
float,default=0.000)- Minimum timestep size for pseudo-transient continuation (PTC) of adjoint. If set to zero (\(< 10^{-12}\)), then it takes the starting timestep as the minimum. Memory-wise, it is beneficial to have
timeStep,timeStepMax, andtimeStepMinset to zero, in which case the PTC approach is never used. If PTC is never used, an explicit residual Jacobian is not stored in memory to quickly reapply the timestep before refactoring the preconditioner.
- Minimum timestep size for pseudo-transient continuation (PTC) of adjoint. If set to zero (\(< 10^{-12}\)), then it takes the starting timestep as the minimum. Memory-wise, it is beneficial to have
-
timeStepRamp (
float,mutable,default=1.250)- The factor used to ramp the timestep when there are good updates.
-
timeStepStepTol (
float,mutable,default=0.5000E-01)- The factor used for judging acceptable update sizes. The timestep is reduced if the step size is below this factor.
-
iterMax (
integer,default=100)- Number of pseudo timestep iterations.
-
tolerance (
float,lower bound=0.1000E-15,default=0.1000)- The required convergence for the linear solver for the pseudo adjoint problem. This is not relative to the initial residual.
-
matFree (
boolean,default=True)- Use the matrix-free method for doing matrix-vector products in the linear system solve.
-
doLineSearch (
boolean,default=False)- Perform a backtracking line search for each Newton iteration.
-
timeStepLinItsTol (
float,mutable,default=0.9000)- The average linear iteration tolerance, relative to the Krylov subspace size, used to control timestep ramping.
-
maxTimeStepLinTol (
float,lower bound=0.1000E-14,upper bound=0.9999,default=0.5000)- The maximum linear convergence tolerance which is acceptable before the timestep is reduced.
-
-
linearSolver
-
tolerance (
float,lower bound=0.1000E-15,upper bound=1.000,mutable,default=0.1000E-08)- The required convergence for the linear solver for the adjoint problem. This is relative to the initial residual.
-
subSpaceSize (
integer,lower bound=1,default=200)- The maximum number of Krylov vectors to use for GMRES.
-
iterMax (
integer,lower bound=1,default=1000)- Sets the maximum number of linear iterations to perform.
-
monitor (
boolean,default=True)- Display the convergence of linear iterations for the adjoint solve.
-
solver (
string,default="gmres")- Accepted Values: [
"gmres","gcrodr"] - The linear solver to use for solving the linear system.
GMRES-
- Generalized minimal residual (GMRES) method (default).
GCRODR-
- Generalized Conjugacy Residual with Deflated Restarting (GCRO-DR) method.
- Accepted Values: [
-
recycleSize (
integer,lower bound=0,default=10)- Number of Krylov vectors recycled between GMRES restarts. This option is only used if
GCRODRis selected assolver.
- Number of Krylov vectors recycled between GMRES restarts. This option is only used if
-
iterativeRefinement (
boolean,default=False)- Use iterative refinement to solve the adjoint problem. Similar to the flow solve, this technique solves the linear system in single precision, and uses a sequence of correction steps to obtain an adjoint solution in double precision. Only valid if using
approxorexactadjoint methods.
- Use iterative refinement to solve the adjoint problem. Similar to the flow solve, this technique solves the linear system in single precision, and uses a sequence of correction steps to obtain an adjoint solution in double precision. Only valid if using
-
-
preconditioner
-
type (
string,default="ilu")- Accepted Values: [
"ilu"] - The type of preconditioner to use for the adjoint solve.
ILU-
- Incomplete lower-upper (ILU) factorization.
- Accepted Values: [
-
ilufill (
integer,lower bound=0,upper bound=10,default=1)- The level of fill used for ILU. Higher levels of fill take more time to apply and use more memory, but it can result in lower number of linear iterations. The most common values are 0 and 1. Values are 0 are more often used for unsteady simulations.
-
subIter (
integer,lower bound=1,upper bound=5,default=1)- The number of sub-iteration applications of preconditioner to perform. This option should be rarely changed. The only time this could be increased to 2 is if memory requirements dictate only a fill level of 0 can be used, but a stronger preconditioner is desired.
-
-
freezeT (
boolean,default=False)- Flag specifying that contributions from the turbulence model will be ignored in the calculation of the adjoint solution. Only the flow residual will be linearized and used as the operator for the LHS of the adjoint problem.
-
scaleAdjointOutput (
boolean,default=False)- Flag specifying if the output written by
adjoint > writeAdjointSolwill be scaled by the metric Jacobian. This scaling option is only useful for visualizing the adjoint and should not be used for any error or gradient calculations.
- Flag specifying if the output written by
-
freezeConnectivity (
boolean,default=True)- Flag specifying if the connectivity for a given grid remains unchanged throughout the optimization process. The default is true, for which connectivity is not recomputed each time the volume grid is deformed. If this is set to false by the user, then connectivity will be recomputed each time the volume grid is deformed. Derivatives for the overset weights will be included in the gradient calculations. However, recomputing connectivity may lead to a non-smooth design space resulting in increased difficulty for gradient-based optimization.
-
probeTargets
- This section may be used to set target variables for the adjoint problem defined on probes specified by the user.
-
name (
string,required)- Name of the probe for which this target is set. This probe, and its corresponding name, should exist in the
probessection of the YAML input file.
- Name of the probe for which this target is set. This probe, and its corresponding name, should exist in the
-
fileName (
string,required)- Name of the probe solution file that holds the target values. For example, this solution file should contain the pressure targets if the user is targetting pressure on a given probe.
-
sourceFileType (
string,default="tri")- Accepted Values: [
"tri","plot3d","tecplot"] - File type of the probe target file.
tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
Tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
-
targetVars ([
string, ...],default=["pressure"])- Variables that the user is targeting on the probe surface.
-
precision (
string,default="double")- Accepted Values: [
"single","double"] - Precision used in the output of the probe target solution data.
single-
- Data is output in single-precision.
double-
- Data is output in double-precision.
- Accepted Values: [
-
exactBCDiff (
boolean,default=True)- Flag specifying if the boundary condition(s) (BCs) are to be differentiated exactly. When performing the reverse pass over the BCs, the value of \(Q\) at the node is technically needed before the BC has been applied. However, if a node has two BCs applied to it (like at the edge or corner of the farfield) then the first set of BCs must be applied before computing the derivatives. In all, this will cost a bit more in computations and memory (it needs a temporary
qVec).
- Flag specifying if the boundary condition(s) (BCs) are to be differentiated exactly. When performing the reverse pass over the BCs, the value of \(Q\) at the node is technically needed before the BC has been applied. However, if a node has two BCs applied to it (like at the edge or corner of the farfield) then the first set of BCs must be applied before computing the derivatives. In all, this will cost a bit more in computations and memory (it needs a temporary
-
freezeProbeWeights (
boolean,default=False)- Flag specifying if the interpolation weights for all probes remain unchanged throughout the optimization process. The default is
false, for which probe weights are recomputed each time the volume grid is deformed and/or the probe is moved. If this is set totrueby the user, then the probe weights will not be recomputed each time the volume grid or probe is deformed. Derivatives for the interpolation weights will be excluded from the gradient calculations.
- Flag specifying if the interpolation weights for all probes remain unchanged throughout the optimization process. The default is
-
sBOOMAdjoints
- This sub-section defines parameters related to performing sBOOM adjoint computations.
-
probeName (
string,required)- Name of the probe for which an sBOOM adjoint is applied. This probe, and its corresponding name, should exist in the
probessection of the YAML input file.
- Name of the probe for which an sBOOM adjoint is applied. This probe, and its corresponding name, should exist in the
-
fileName (
string,default="Gradient.plt")- Name of the sBOOM adjoint file that holds adjoint solution output from sBOOM. Typically, this would be
Gradient.plt
- Name of the sBOOM adjoint file that holds adjoint solution output from sBOOM. Typically, this would be
-
weight (
float,default=1.000)- Weights applied to this sBOOM adjoint, useful for when there are multiple sBOOM adjoints or other functionals and the user would like to weight them all differently.
-
warmStartFromApprox (
boolean,default=False)- Warm start the exact adjoint solution using the solution and Krylov subspace from the approximate adjoint solve.
-
exactSolutionErrorVariables ([
string, ...],default=["adjointp", "adjointu", "adjointv", "adjointw", "adjointt"])- Variables whose errors are evaluated with respect to a user-supplied dynamic link library (DLL) file defining the exact adjoint solution. \(L^{\infty}\), \(L^1\), and \(L^2\) error norms are evaluated for interior compute nodes.
Broyden Solver
- This section defines parameters associated with utilizing the Broyden method to adjust input parameters while solving the RANS equations to meet a target output. For example, adjusting alpha to meet a target lift coefficient.
broydenSolver:
outputs:
outputTargets:
tolerance:
maxIterations:
inputs:
inputIndices:
initialStep:
initialJacobian:
-
outputs ([
string, ...],default=["cl"])- List of output functionals to target.
-
outputTargets ([
float, ...],default=[0.5000])- Targets for each output functional of interest. Must be the same size as
broydenSolver > outputs.
- Targets for each output functional of interest. Must be the same size as
-
tolerance (
float,default=0.1000E-03)- Tolerance used around the target value(s) when assessing whether the Broyden solver procedure has completed successfully.
-
maxIterations (
integer,lower bound=1,upper bound=100,default=10)- Maximum number of Broyden solves to perform before stopping the procedure.
-
inputs ([
string, ...],default=["referenceconditions.alpha"])- Input parameters which can be adjusted by the Broyden procedure. Must be the same size as
broydenSolver > outputs.
- Input parameters which can be adjusted by the Broyden procedure. Must be the same size as
-
inputIndices ([
integer, ...],default=0)- Index for each input parameter (0-based). Must be the same size as
broydenSolver > outputs.
- Index for each input parameter (0-based). Must be the same size as
-
initialStep ([
float, ...],default=[0.1000E-01])- After the first RANS solve the input parameters are incremented by this amount in order to start the Broyden procedure. Must be the same size as
broydenSolver > outputs.
- After the first RANS solve the input parameters are incremented by this amount in order to start the Broyden procedure. Must be the same size as
-
initialJacobian ([
float, ...],default=[0.1000])- Scale factor used for limiting the initial Jacobian formed during the first step of the Broyden procedure. Must be the size of
broydenSolver > outputssquared.
- Scale factor used for limiting the initial Jacobian formed during the first step of the Broyden procedure. Must be the size of
Convergence Criteria
- This section defines convergence criteria that will be used to control the stoppage of a steady-state RANS-based analysis. When using limiters, steady-state convergence can often stall due to limiter rattling, leading to long run times. This option allows users to prescribe a standard deviation tolerance over a specified number of iterations for specific quantities of interest. If either the residual converges to the specified tolerance or all of the specified functional-based convergence tolerances are met, then the steady-state solve is completed. This can also be used within implicit unsteady runs using dual time-stepping, if a large timestep is being used.
convergenceCriteria:
-
quantity: <required>
stdTolerance: <required>
stdWindowIterations:
verbose:
frequency:
-
quantity (
string,required)- Quantity used to monitor convergence in addition to using the residual norm. The default quantity is \(C_d\) which represents the drag coefficient.
-
stdTolerance (
float,required)- Standard deviation tolerance for the specified quantity of interest. For example, the default is 0.00001 which represents a tenth of a drag count.
-
stdWindowIterations (
integer,default=500)- The size of the iteration window used for computing the standard deviation of the quantity of interest. Common examples are 100, 500, or 1000 depending on the problem and functional. The default is set to 500 which should be good for cases in which the CFL becomes larger than 100.0 during steady-state convergence.
-
verbose (
boolean,default=True)- Setting verbose to true will report the mean and standard deviation of the quantity of interest every time the convergence criteria is checked.
-
frequency (
integer,default=10)- This sets the frequency at which the convergence criteria is checked. Also controls the output of the mean and standard deviation if verbose is set to true. The default is set to every 10 iterations.
Parameter Scheduling
- This section is used to specify iteration-based user-defined input parameter changes.
parameterScheduling:
-
iter: <required>
modify: <required>
-
iter (
integer,required)- Iteration to apply parameter change at.
-
modify ([
string, ...],required)- Parameter to change. Example: dt:1.0e-4.
Sponges
- This section is used to define sponge regions. A sponge region can be defined to activate a source term in the equations to smoothly return the solution to the reference conditions within the specified region. This can be used if the domain is too small and non-physical waves are being generated at the boundary that interact with a region of interest.
sponges:
-
type: <required>
applySpongeTo: <required>
xMin:
xMax:
rotationAngle:
radius:
radiusInner:
nFacet:
fileName:
fileType:
-
type (
string,required)- Accepted Values: [
"box","surfile","cone"] - The type of volume region specification.
box-
- A cartesian aligned box specified using
xMinandxMaxcoordinates.
- A cartesian aligned box specified using
surFile-
- A closed surface triangulation that is specified using the
fileNameandfileTypeoptions.
- A closed surface triangulation that is specified using the
cone-
- A cone using min/max radii specified using
rMin/rMaxatxMin/xMax.
- A cone using min/max radii specified using
- Accepted Values: [
-
applySpongeTo (
string,required)- Accepted Values: [
"interior","exterior"] - Location relative to the sponge where source terms are applied.
interior-
- Sponge is applied to the interior of the closed triangulation.
exterior-
- Sponge is applied everywhere not inside the triangulation.
- Accepted Values: [
-
xMin ([
float,float,float],default=[0.000, 0.000, 0.000])- Lower left corner of refinement region when type is
box. Starting point of cone axis when type iscone.
- Lower left corner of refinement region when type is
-
xMax ([
float,float,float],default=[1.000, 1.000, 1.000])- Upper right corner of refinement region when type is
box. End point of axis when type iscone.
- Upper right corner of refinement region when type is
-
rotationAngle ([
float,float,float],default=[0.000, 0.000, 0.000])- Defines axis rotation for
boxaround barycenter[xrot, yrot, zrot].
- Defines axis rotation for
-
radius ([
float,float],default=[1.000, 1.000])- Radius at
xMinandxMaxwhen type iscone.
- Radius at
-
radiusInner ([
float,float],default=[1.000, 1.000])- Inner radius of tube at
xMinandxMaxwhen type iscone.
- Inner radius of tube at
-
nFacet (
integer,default=120)- Number of facets on sponges defined by curved geometric shapes (applies to types
[cone]).
- Number of facets on sponges defined by curved geometric shapes (applies to types
-
fileName (
string(fileName),default="file")- Filename for the closed surface for type
surFile.
- Filename for the closed surface for type
-
fileType (
string,default="tecplot")- Accepted Values: [
"tri","plot3d","tecplot"] - Filetype of closed surface for type
surFile. tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
Plot3D-
- Plot3D file format. Refer to file formats page for details.
Tecplot-
- Tecplot PLT binary format file.
- Accepted Values: [
Tripping Strips
- This section is dedicated to the specification of flow tripping strips by adding momentum source terms to trigger resolved turbulence in the boundary layer.
tripStrips:
-
projectionType: <required>
fileName:
xMin:
xMax:
xRadius:
dirStart:
projectionVector:
tripLength:
tripSkip:
radius:
families:
timescaleFact:
-
projectionType (
string,required)- Accepted Values: [
"closest","vector"] - Type of projection to apply to the trip strip geometry.
closest-
- Project the trip strip nodes to the closest wall geometry found.
vector-
- Project the trip strip nodes to the wall geometry along a direction specified by the vector
projectionVector.
- Project the trip strip nodes to the wall geometry along a direction specified by the vector
- Accepted Values: [
-
fileName (
string(fileName),default="tripStrips.x")- File name of input Plot3D file with trip strip geometry.
-
xMin ([
float,float,float],default=[0.000, 0.000, 0.000])- Physical location
[X, Y, Z]of the trip strip start.
- Physical location
-
xMax ([
float,float,float],default=[1.000, 0.000, 0.000])- Physical location
[X, Y, Z]of the end of the trip strip.
- Physical location
-
xRadius (
float,default=1.000)- Radius for circular trip strip.
-
dirStart ([
float,float,float],default=[0.000, 0.000, -1.000])- Direction to start circle. Usually -zhat for y-symm plane
-
projectionVector ([
float,float,float],default=[1.000, 0.000, 0.000])- Direction of projection to apply to trip strip geometry.
-
tripLength (
float,default=4.000)- Length of individual trips.
-
tripSkip (
float,default=4.000)- Distance between individual trips.
-
radius (
float,default=1.414)- Radius of influence.
-
families ([
string, ...],default=[""])- Project trip strip onto parts defined with these names in the BC file only.
-
timescaleFact (
float,default=3.000)- Factor to control strength of tripping source term.
Transition Model Tripping Strips
- This section is to be used in conjunction with the Spalart Allmaras Smooth Langtry Mentor 2015 transition model in
navierStokes > turbulenceModel > type: SASLM2015. Use these parameters to set a location in the geometry to transition the flow using the intermittency function.
transTripStrips:
-
projectionType: <required>
fileName:
xMin:
xMax:
xRadius:
dirStart:
projectionVector:
radius:
dxtrans:
families:
timescaleFact:
-
projectionType (
string,required)- Accepted Values: [
"closest","vector"] - Type of projection to apply to the trip strip geometry.
closest-
- Project the trip strip nodes to the closest wall geometry found.
vector-
- Project the trip strip nodes to the wall geometry along a direction specified by the vector
projectionVector.
- Project the trip strip nodes to the wall geometry along a direction specified by the vector
- Accepted Values: [
-
fileName (
string(fileName),default="transTripStrips.x")- File name of input Plot3D file with trip strip geometry.
-
xMin ([
float,float,float],default=[0.000, 0.000, 0.000])- Physical location
[X, Y, Z]of the trip strip start.
- Physical location
-
xMax ([
float,float,float],default=[1.000, 0.000, 0.000])- Physical location
[X, Y, Z]of the end of the trip strip.
- Physical location
-
xRadius (
float,default=1.000)- Radius for circular trip strip.
-
dirStart ([
float,float,float],default=[0.000, 0.000, -1.000])- Direction to start circle. Usually -zhat for y-symm plane
-
projectionVector ([
float,float,float],default=[1.000, 0.000, 0.000])- Direction of projection to apply to trip strip geometry.
-
radius (
float,default=1.414)- Radius of influence.
-
dxtrans (
float,default=1.000)- Reference grid length (off-wall or streamwise spacing, could use characteristic length of domain (i.e. MAC) as well).
-
families ([
string, ...],default=[""])- Project trip strip onto parts defined with these names in the BC file only.
-
timescaleFact (
float,default=1.000)- Factor to control strength of tripping source term.
Target Volume Source Regions
- This section specifies regions defined by a triangulation within which a series of target values for flow variables can be specified. In terms of analogy to
immersedBoundaries, this uses thedriveToZeroupdate method.
targetVolumeSourceRegions:
-
fileName: <required>
fileType: <required>
targetVariables: <required>
targetValues:
octTreeFileName:
octTreeCubes:
timescale:
-
fileName (
string(fileName),required)- The name of the tri file (
*.i.tri) to use when defining the region.
- The name of the tri file (
-
fileType (
string,required)- Accepted Values: [
"tri"] - Input file format.
tri-
- Triangulation Cart3D file format. Refer to cart3dTriangulations for details.
- Accepted Values: [
-
targetVariables ([
string, ...],required)- A list of variable names which have defined target values within the
targetVolumeSourceRegions > targetValueslist. Therefore, they must be same size. Allowed names are:[pressure, xvelocity, yvelocity, zvelocity, xvelocitynormal, yvelocitynormal, zvelocitynormal, temperature, rho, turbulencevar1, turbulencevar2, turbulencevar3]. If a certain combination of variables is not physically legal then the code will complain.
- A list of variable names which have defined target values within the
-
targetValues ([
float, ...],default=[0.000])- A list of target values for each variable name in the
targetVolumeSourceRegions > targetVariableslist.
- A list of target values for each variable name in the
-
octTreeFileName (
string,default="")- If defined, writes the octree used to tag nodes inside the region.
-
octTreeCubes (
integer,default=500000)- Defines the maximum number of octree cubes allowed to define the region.
-
timescale (
float,mutable,default=0.1000E-03)- A source-application update scalar. Scales update by 1/timescale. Currently this is mutable to allow potential tuning during runtime.
Rotating Reference Frames
- This section specifies options for rotating frames of reference for a specified number of zones in the grid. Zones which are specified to exist in the rotating frames do not actually rotate, but the equations are modified in such a way that frame of reference is rotating/non-inertial.
rotatingRefFrame:
-
zones:
omega:
axis1:
axis2:
-
zones ([
string, ...],default=[""])- Zones that are in the rotating reference frame.
-
omega (
float,default=1.000)- Angular rotation rate for the reference .
-
axis1 ([
float,float,float],default=[0.000, 0.000, 0.000])- Start point of rotation axis for the reference frame.
-
axis2 ([
float,float,float],default=[1.000, 0.000, 0.000])- End point of mesh rotation axis for the reference frame.
Output Variables
This section discusses the available output variables for volume, surface, probe, and slice/isosurface outputs. We also discuss how to get time-averaged variables output. Note that .nam file is written for volume, surface, and restart output files. These .nam files contain a list of the variables included in the Plot3D function file. Some visualization packages can read these files in at the same time as the function file so that the proper names are associated with the variables.
Volume Output Variables
The list of available volume output variables is listed below along with a brief description.
- Pressure: Pressure, [Pa].
- VelocityX: X-direction velocity, [m/s].
- VelocityY: Y-direction velocity, [m/s].
- VelocityZ: Z-direction velocity, [m/s].
- Temperature: Temperature, [K].
- Cp: Coefficient of pressure.
- nut: Spalart-Allmaras turbulence model working variable, [m^2/s].
- k: Turbulent kinetic energy in the k-omega BSL and SST models, [m^2/s^2].
- omega: Specific dissipation rate in the k-omega BSL and SST models, [1/s].
- intermittency: Intermittency factor in the Langtry-Menter transition model.
- ReTheta: Transition-onset momentum thickness Reynolds number in the Langtry-Menter transition model.
- ResPressure: Residual of the conservation of mass equation.
- ResVelocityX: Residual of the conservation of momentum equation in the x-direction.
- ResVelocityY: Residual of the conservation of momentum equation in the y-direction.
- ResVelocityZ: Residual of the conservation of momentum equation in the z-direction.
- ResTemperature: Residual of the conservation of energy equation.
- ResNut: Residual of the Spalart-Allmaras turbulence model equation.
- ResK: Residual of the turbulent kinetic energy equation in the k-omega BSL and SST turbulence models.
- ResOmega: Residual of the specific dissipation rate equation in the k-omega BSL and SST turbulence models.
- ResInt: Residual of the intermittency equation in the Langtry-Menter transition model.
- ResRet: Residual of the transition-onset momentum thickness Reynolds number equation in the Langtry-Menter transition model.
- uu: X-direction velocity squared, [m^2/s^2].
- uv: X-direction velocity times Y-direction velocity, [m^2/s^2].
- uw: X-direction velocity times Z-direction velocity, [m^2/s^2].
- vv: Y-direction velocity squared, [m^2/s^2].
- vw: Y-direction velocity times Z-direction velocity, [m^2/s^2].
- ww: Z-direction velocity squared, [m^2/s^2].
- uT: X-direction velocity times Temperature, [m K/s].
- vT: Y-direction velocity times Temperature, [m K/s].
- wT: Z-direction velocity times Temperature, [m K/s].
- Mach: Mach number.
- sos: Speed of sound.
- Density: Density, [kg/m^3].
- rhou: X-direction momentum, [kg m/s].
- rhov: Y-direction momentum, [kg m/s].
- rhow: Z-direction momentum, [kg m/s].
- rhoE: Total energy, [kg m^2/s^2].
- Entropy: Entropy, [kg m^2/(s^2 K)].
- EddyViscosity: Turbulent eddy viscosity, [kg/(m s)].
- EddyViscosityRatio: Turbulent eddy viscosity divided by reference viscosity.
- StrainRateMagnitude: Magnitude of the strain rate.
- KFromSA: Estimate of the turbulent kinetic energy from the Spalart-Allmaras turbulence model using Bradshaw's hypothesis.
- EpsilonFromSA: Estimate of isotropic turbulent dissipation from the Spalart-Allmaras turbulence model using Bradshaw's hypothesis.
- SSTBlendingF1: The F1 blending function in the k-omega SST turbulence model.
- SSTBlendingF1Var1: First input in the arg1 function in the F1 blending function in the k-omega SST turbulence model.
- SSTBlendingF1Var2: Second input in the arg1 function in the F1 blending function in the k-omega SST turbulence model.
- SSTBlendingF1Var3: Third input in the arg1 function in the F1 blending function in the k-omega SST turbulence model.
- SSTBlendingF2: The F2 blending function in the k-omega SST turbulence model.
- fw: The fw function in the Spalart-Allmaras turbulence model.
- Qcriterion: Q-criteria, [1/s^2].
- RhoGradMag: Magnitude of the density gradient vector.
- ShockSurface: Shock Surface.
- VelocityMag: Magnitude of the velocity vector, [m/s].
- DPressureDt: Time-derivative of the pressure.
- DucrosSensor: Originally the Ducros sensor, now plots the selected upwind sensor.
- ShockSensor: Shock sensor based on second difference of pressure, values are controlled by dswitch in
navierstokes.convective. - WiggleSensorJ: Wiggle sensor in the j-coordinate direction. Pressure-based wiggle sensor detects non-physical oscillations in pressure. 1 for wiggles, 0 for no wiggles.
- WiggleSensorK: Wiggle sensor in the k-coordinate direction. Pressure-based wiggle sensor detects non-physical oscillations in pressure. 1 for wiggles, 0 for no wiggles.
- WiggleSensorL: Wiggle sensor in the l-coordinate direction. Pressure-based wiggle sensor detects non-physical oscillations in pressure. 1 for wiggles, 0 for no wiggles.
- Vorticity: Magnitude of vorticity vector, [1/s].
- XVorticity: X-direction of vorticity vector, [1/s].
- YVorticity: Y-direction of vorticity vector, [1/s].
- ZVorticity: Z-direction of vorticity vector, [1/s].
- Helicity: Helicity which is the dot-product of velocity and vorticity vectors, [m^2/s^2].
- polarRadius: Radial coordinate relative to rotational axis defined in the input file, [m].
- polarTheta: Azimuthal coordinate relative to rotational axis defined in the input file, [rad].
- radialVelocity: Radial velocity relative to rotational axis defined in the input file, [m/s].
- swirlVelocity: Azimuthal velocity relative to rotational axis defined in the input file, [m/s].
- fr1: Function for Rotation-Curvature correction, set to unity if userc is False.
- csgsDynSmag: The spatially varying Csgs coefficient when using the Dynamic Smagorinsky sub-grid scale model.
- DLen: Local length scale used in both LES and HRLES models, [m].
- DelS: Local grid length scale, depends on option set in
navierstokes.turbulenceModel.gridLengthScale. - DelM: Maximum grid length scale at each node.
- DelSJ: Grid spacing in the j-coordinate direction at each node.
- DelSK: Grid spacing in the k-coordinate direction at each node.
- DelSL: Grid spacing in the l-coordinate direction at each node.
- fd: Shielding or constraint function used in HRLES models.
- fdr: Original DDES shielding function used as part of fd in
navierstokes.turbulenceModel.mode = zdesmode7. - fpp: Enhanced protection function used as part of fd in
navierstokes.turbulenceModel.mode = zdesmode7. - fr: Inhibition function used as part of fd in
navierstokes.turbulenceModel.mode = zdesmode7. - iblank: Grid node status value: 1 for compute, 0 for blank, -nz for fringe where nz is the zone number of the donor cell.
- smin: Minimum wall-distance.
- sminvecx: X-direction of the vector from the grid node to the closest point on the wall.
- sminvecy: Y-direction of the vector from the grid node to the closest point on the wall.
- sminvecz: Z-direction of the vector from the grid node to the closest point on the wall.
- dt: Maximum possible explicit time-step at each node based on
timestepping.explicitCFLLimit. - dtinc: Maximum possible explicit convective time-step (no speed of sound) at each node based on
timestepping.explicitCFLLimit. - ug: X-direction grid velocity for a moving grid.
- vg: Y-direction grid velocity for a moving grid.
- wg: Z-direction grid velocity for a moving grid.
- x: X-grid coordinate at current time-level.
- y: Y-grid coordinate at current time-level.
- z: Z-grid coordinate at current time-level.
- xn: X-grid coordinate at previous time-level.
- yn: Y-grid coordinate at previous time-level.
- zn: Z-grid coordinate at previous time-level.
- wn1: Conserved variable 1 at previous time-level.
- wn2: Conserved variable 2 at previous time-level.
- wn3: Conserved variable 3 at previous time-level.
- wn4: Conserved variable 4 at previous time-level.
- wn5: Conserved variable 5 at previous time-level.
- turvarn1: Turbulence model variable 1 at previous time-level.
- turvarn2: Turbulence model variable 2 at previous time-level.
- Sij11: Component 1,1 of strain rate tensor at current time-level.
- Sij12: Component 1,2 of strain rate tensor at current time-level.
- Sij13: Component 1,3 of strain rate tensor at current time-level.
- Sij22: Component 2,2 of strain rate tensor at current time-level.
- Sij23: Component 2,3 of strain rate tensor at current time-level.
- Sij33: Component 3,3 of strain rate tensor at current time-level.
- Sijn11: Component 1,1 of strain rate tensor at previous time-level.
- Sijn12: Component 1,2 of strain rate tensor at previous time-level.
- Sijn13: Component 1,3 of strain rate tensor at previous time-level.
- Sijn22: Component 2,2 of strain rate tensor at previous time-level.
- Sijn23: Component 2,3 of strain rate tensor at previous time-level.
- Sijn33: Component 3,3 of strain rate tensor at previous time-level.
- dj: Metric term jacobian at current time-level.
- djn: Metric term jacobian at previous time-level.
- djh: Metric term jacobian used with higher-order metrics.
- dij: Metric term jacobian used in conservative time-metric routine.
- rtxyz11: Metric term J^(-1)d(xi)/dt.
- rtxyz12: Metric term J^(-1)d(xi)/dx.
- rtxyz13: Metric term J^(-1)d(xi)/dy.
- rtxyz14: Metric term J^(-1)d(xi)/dz.
- rtxyz21: Metric term J^(-1)d(eta)/dt.
- rtxyz22: Metric term J^(-1)d(eta)/dx.
- rtxyz23: Metric term J^(-1)d(eta)/dy.
- rtxyz24: Metric term J^(-1)d(eta)/dz.
- rtxyz31: Metric term J^(-1)d(zeta)/dt.
- rtxyz32: Metric term J^(-1)d(zeta)/dx.
- rtxyz33: Metric term J^(-1)d(zeta)/dy.
- rtxyz34: Metric term J^(-1)d(zeta)/dz.
- ibmark: Status of a grid node with respect to immersed boundary, 1 - inside, 0 - outside.
- globalindex: Index of a grid node in the global index array.
- referenceindex: Reference index of a grid node.
- tileid: Which tile a grid node is assigned to.
- procid: Which MPI rank a grid node is assigned to.
- source1: User provided/specified source for equation 1.
- source2: User provided/specified source for equation 2.
- source3: User provided/specified source for equation 3.
- source4: User provided/specified source for equation 4.
- source5: User provided/specified source for equation 5.
- nx: X-direction component of the unit normal vector to the closest wall point.
- ny: Y-direction component of the unit normal vector to the closest wall point.
- nz: Z-direction component of the unit normal vector to the closest wall point.
- nondimdensity: Plot3D solution file style non-dimensional density.
- nondimrhou: Plot3D solution file style non-dimensional x-direction momentum.
- nondimrhov: Plot3D solution file style non-dimensional y-direction momentum.
- nondimrhow: Plot3D solution file style non-dimensional z-direction momentum.
- nondimrhoe: Plot3D solution file style non-dimensional total energy.
- adjointp: Adjoint variable for the conservation of mass equation.
- adjointu: Adjoint variable for the conservation of momentum equation in the x-direction.
- adjointv: Adjoint variable for the conservation of momentum equation in the y-direction.
- adjointw: Adjoint variable for the conservation of momentum equation in the z-direction.
- adjointt: Adjoint variable for the conservation of energy equation.
- adjointtur1: Adjoint variable for the Spalart-Allmaras turbulence model equation.
- aspectratioj: Maximum aspect ratio in the j-coordinate direction.
- aspectratiok: Maximum aspect ratio in the k-coordinate direction.
- aspectratiol: Maximum aspect ratio in the l-coordinate direction.
- planarskewnessj: Planar skewness in the j-coordinate direction.
- planarskewnessk: Planar skewness in the k-coordinate direction.
- planarskewnessl: Planar skewness in the l-coordinate direction.
- stretchingratioj: Maximum stretching ratio in the j-coordinate direction.
- stretchingratiok: Maximum stretching ratio in the k-coordinate direction.
- stretchingratiol: Maximum stretching ratio in the l-coordinate direction.
- ARquality: Aspect ratio quality metric.
- PSquality: Planar skewness quality metric.
- SRquality: Stretching ratio quality metric.
- minEdgeLength: Minimum edge length connected to the node.
- maxEdgeLength: Maximum edge length connected to the node.
- cellvolume: Volume of the dual-cell at the node, equivalent to the inverse Jacobian of the coordinate transformation.
- cuberootcellvolume: Cube root of the volume of the dual-cell at the node.
Surface Output Variables
The list of surface specific output variables is listed below along with a brief description. Note that since subsets are also considered surface data that any of the volume outputs can also be output for surface subsets. For example, Cp can be output for volume, surface, or subset surfaces.
- yplus: Wall spacing in viscous units.
- xi1plus: Transverse spacing direction 1 in viscous units.
- xi2plus: Transverse spacing direction 2 in viscous units.
- ustar: Friction velocity.
- Cf: Skin-friction magnitude.
- Cfx: Skin-friction in the x-direction.
- Cfy: Skin-friction in the y-direction.
- Cfz: Skin-friction in the z-direction.
- signedCf: Signed skin-friction magnitude where the sign is determined from the dot product of the skin friction and freestream velocity vectors.
- SAturbIndex: Spalart-Allmaras based turbulence index used to detect transition.
- PanelWeight: The weight of each quad used in aerodynamic force and moment integration to account for overlapping surface grids.
Probe/Slice/Isosurface Output Variables
Probes, slices, and isosurfaces are similar to subset surfaces. All volume output variables can be requested on either probes, slices and/or isosurfaces. In addition, probe surfaces can request skin-friction and yplus variables where a wall-model, selected by the user, is used to compute the values on the probe surface(s).
Averaging
In order to output time-averaged variable, the user can simply append avg to the end of a variable name and a time-averaged version will be output. For example, velocityXavg and Cfxavg will output the time-averaged x-direction velocity and x-direction skin-friction. A more detailed example can be found in the Hybrid RANS-LES tutorial. To use the exponentially weighted moving time average, ewmavg can be appended at the end of a variable name instead of avg. Note that the averaging can be used to compute resolved turbulent stresses by adding velocityXavg, velocityYavg, velocityZavg, temperatureavg, uuavg, uvavg, uwavg, vvavg, vwavg, wwavg, uTavg, vTavg, wTavg and computing:
- \(\overline{u u}\) = uuavg - velocityXavg velocityXavg
- \(\overline{u v}\) = uvavg - velocityXavg velocityYavg
- \(\overline{u w}\) = uwavg - velocityXavg velocityZavg
- \(\overline{v v}\) = vvavg - velocityYavg velocityYavg
- \(\overline{v w}\) = vwavg - velocityYavg velocityZavg
- \(\overline{w w}\) = wwavg - velocityZavg velocityZavg
- \(\overline{u T}\) = uTavg - velocityXavg temperatureavg
- \(\overline{v T}\) = vTavg - velocityYavg temperatureavg
- \(\overline{w T}\) = wTavg - velocityZavg temperatureavg
File Formats
In this section we describe the file formats of all files used by the solver.
Grid File format
LAVACurv uses plot3d grids as the format for specifying the
multi-block grids. Since there are nearly unlimited number of formats of
plot3d grids, we will be very specific about what constitutes valid input
to the solver. The plot3d grids for LAVACurv must use the following
format(s):
- Multiblock
- Double precision
- Little-Endian
- With or Without Iblank Array
- With or Without Record Markers
That is there are 4 possible formats : With/Without Iblanks and With/Without Record Markers. The solver can distinguish between these 4 grid types and no further information is required. The following fortran code will write a valid grid without record markers and with an iblank array.
! Each of X,Y,Z,ib are of length nZone and are a list
! of variable sized arrays. Eg:
! type listOfArraysR8
! real(kind=8), dimension(:, :, :), allocatable :: arr
! end type
! type listOfArraysI4
! integer(kind=4), dimension(:, :, :), allocatable :: arr
! end type
type(listOfArraysR8) :: X,Y,Z
type(listOfArraysI4) :: ib
allocate(X(nZone), Y(nZone), Z(nZone), ib(nZone))
! Allocate individual arrays for each zone and set variables
open(newUnit=iUnit, form='unformatted', access='stream')
write(iUnit) nZone ! Number of Zones
write(iUnit) sizes ! Dimensions of (3, nZone)
do i=1, nZone
write(iUnit) X(i)%arr, Y(i)%arr, Z(i)%arr, ib(i)%arr
end do
close(iUnit)
BC and Subset Files
The BCFile and the optional Subset file are used to define contiguous sections of grid blocks. For the BCFile this is used for specifying boundary conditions. For the subset file, these sections are used for a variety of purposes. These files have the following syntax
!------------------------------------------------------------
! Label nz jbeg jend kbeg kend lbeg lend
!------------------------------------------------------------
in 1 1 -1 1 1 1 -1
out 1 1 -1 -1 -1 1 -1
sym 1 1 -1 1 -1 -1 -1
sym 1 1 1 1 -1 1 -1
sym 1 -1 -1 1 -1 1 -1
sym 1 1 -1 1 49 1 1
sym 1 1 -1 129 -1 1 1
wall 1 1 -1 49 129 1 1
All lines that begin with ! are treated as comment lines and ignored.
The first entry is the label. This can be any string that is appropriate
for the specific problem. The second column is the zone (or grid or
block) number the section belong to. The remaining 6 entries (jBeg,
jEnd, kBeg, kEnd, lBeg, lEnd) give the start and end ranges for that
particular subset. A special negative syntax is allowed: The -1 index
refers to the last node of the block. Therefore a range of 1 -1 covers
the entire block range no matter what the block size. Note that multiple
different tags are allowed on a given surface. In the example above, the
L=1 boundary has 3 different (1->49, 49->129 and (129->-1)sections,
with two unique labels (sym and wall). The order of line in the BC file
does not matter. Additional blank and or comments lines may be added as
desired.
B2B Files
The B2B file is used to uniquely describe how two blocks are connected to each other in a multi-block grid. Note that periodic boundary conditions also fall into this category.
! BlkID js je ks ke ls le DonorID djs dje dks dke dls dle tx ty tz
8 1 1 1 -1 1 -1 8 -1 -1 1 -1 1 -1 1 2 3
8 -1 -1 1 -1 1 -1 8 1 1 1 -1 1 -1 1 2 3
Like the BC and subset files, the ! denotes a comment line. The
ordering of the lines do not matter and blank lines are ignored. The
first entry is BlkID the index of grid block this connection applies
to. The next 6 numbers (js/je/ks/ke/ls/le) are describe the range of the
blkID that is connected to another block (or itself in the case of
periodic boundary). DonorID is the block that which previously
described section is connected to. This can be any block number including
itself. The next 6 numbers (djs/dje/dks/dke/dls/dle, the \'d\' means
\"donor\" here) are the subset of the donor block that is connected to
the first range. Note that depending on how the blocks are oriented, the
starting indices may be larger than the end indices. Note that like
the BC and subset files, a special \"negative\" index is allowed where
-1 denotes the last index of the block. The final 3 numbers describe the
\"transform\" which is how the indices of the first block relate to the
indices of the second block. See the explanation on the CGNS website for
more information:
https://cgns.github.io/CGNS_docs_current/sids/cnct.html#Transform
Interp Files
These files are required only when overset meshes are used. The file
must be in \"INTOUT\" file type. This file is typically written by
LAVACurv itself when performing hole cutting but we describe the
format here as well.
open(newunit=iUnit, file="INTOUT", form='unformatted',&
status='replace')
write(iUnit) nOnBlock
do iBlk=1, nZones
write(iUnit) &
blkIntData(iBlk)%arr(:, 1), & ! j index
blkIntData(iBlk)%arr(:, 2), & ! k index
blkIntData(iBlk)%arr(:, 3), & ! l index
blkIntData(iBlk)%arr(:, 4), & ! donor Block
blkIntData(iBlk)%arr(:, 5), & ! donor j
blkIntData(iBlk)%arr(:, 6), & ! donor k
blkIntData(iBlk)%arr(:, 7), & ! donor l
blkRealData(iBlk)%arr(:, 1), & ! fracJ
blkRealData(iBlk)%arr(:, 2), & ! fracK
blkRealData(iBlk)%arr(:, 3) ! fracL
write(iUnit) blkIblank(iBlk)%arr ! iBlank
end do close (iUnit)
The first write is array sized nZones. Each entry contains the number of fringes (or interpolated) points for that block. Then, looping over each zone, we write the jkl indices of the fringe node followed by donor block, lower left-index of the donor cell, and the three fractional weights. Finally, a full iblank array for the zone is written. This iblank array however is not used by the solver and its values do not matter.
Restart Files
These files are written by the solver to restart a previous simulation where it finished. Restart files are used to restart both steady and unsteady simulations. The contents of the restart file depend on the type of simulation being performed: The code automatically determines which variables need to be saved to ensure a seamless restart. When a restart \"file\" is written there are actually 4 files written:
- a
.rstfile - a
.namfile - a
.infofile - a
.iterfile
The .rst is the main file storing the field information. This is a
plot3d function file, written in double precision, native endian,
without record markers. This file may be loaded into tecplot using
the standard Plot3D grid loader.
The .nam is an ascii file that contains the variable names written in
the file. A typical .nam file for a steady RANS simulation might look
like the following:
Note that this file can be loaded into Tecplot to label the variables
from the .rst file.
The .info file is ascii file that contains various pieces key-value
information required by the solver for seamless restarts. This file
should not be modified by the user.
Finally a .iter file stores the iteration-level history of all
\"iteration variables\". This file is identical to the data.iter
file also written by the code. See dataiterfile{.interpreted-text
role="ref"} for more the format of this file.
data.iter File
The data.iter is binary file automatically written by the solver which
records non-linear iteration level data during both steady and unsteady
simulations. This is a binary file and thus it is not human readable. It
can be processed by the plotHist.py routine for performing various
post-processing plotting functions.
The format of the file is as follows:
- a single 32-bit integer, nVar, listing the number of variables
- a single 32-bit integer, varNameLen, listing the length of each variable name
- nVar * varNameLen bytes containing the variable names
- Each subsequent nVar*8 bytes are treated as 64-bit real values corresponding to a single non-linear iteration
The following sample code will read the file using fortran:
module iterLoader
contains
subroutine loadData(fName, varNames, data)
use iso_fortran_env
implicit none
character(len=*) :: fName
real(kind=8), dimension(:, :), allocatable :: data
character(len=:), allocatable, dimension(:) :: varNames
integer :: fSize, iUnit, nVar, varNameLen, n
inquire(file=fName, size=fSize)
fSize = fSize * FILE_STORAGE_SIZE /8 ! Number of bytes
open(newUnit=iUnit, file=fName, status='old', &
form='unformatted', access='stream')
! Read Header Info
read(iUnit) nVar
read(iUnit) varNameLen
allocate(character(len=varNameLen)::varNames(nVar))
read(iUnit) varNames
! Determine the number of "lines" to read:
n = (fSize - 8 - nVar*varNameLen) / (nVar*8)
allocate(data(nVar, n))
read(iUnit) data
close(iUnit)
end subroutine loadData
end module iterLoader
The following sample code will read the file using python:
def loadData(fName):
import os
import numpy as np
fSize = os.path.getsize(fName)
f = open(fName, 'rb')
nVar = np.fromfile(f, dtype='i4',count=1)[0]
strSize = np.fromfile(f, dtype='i4', count=1)[0]
strs = np.fromfile(f, dtype='c', count=nVar*strSize)
keys = []
for i in range(nVar):
keys.append("".join(strs[i*strSize:(i+1)*strSize]).strip().lower())
remainingBytes = fSize - 8 - nVar * strSize
lines = remainingBytes // (nVar * 8)
buf = np.fromfile(f, dtype=float, count=-1, sep='')
data = buf[0:lines*nVar].reshape((nVar, lines), order='f')
f.close()
return keys, data
Connectivity
Everything you need to know about understanding, running, and debugging overset connectivity can be found in the "LAVA Curvilinear Overset Grid Connectivity Manual". The latest version of the manual can be downloaded below.
pyLAVA
pyLAVA Description
pyLAVA is the Python interface to the LAVA Curvilinear solver, designed to streamline aerodynamic analysis and design optimization workflows. It provides a high-level API for interacting with the solver's dynamic library and managing simulation tasks.
The pylava package currently includes the following core classes:
- LAVA: Interfaces directly with the LAVA-curvilinear dynamic library. This class supports preprocessing, flow solving, mesh warping, and solution I/O.
- optLAVA: Wraps the LAVA class to enable aerodynamic design optimization. It integrates with pyGeo for geometry parameterization and pyOptSparse for optimization.
pyLAVA is required for running optimizations using either the optLAVA class or the OpenMDAO framework. When using OpenMDAO, the MPhys package is also required to manage multidisciplinary models.
Beyond optimization, pyLAVA can be used for standalone aerodynamic analysis, including flow solves, adjoint solves, and mesh manipulation.
Design Optimization
Design optimization is performed through Python to enable modular, scriptable workflows that integrate seamlessly with external packages. This modularity allows users to define geometry, configure solvers, and manage optimization problems in a flexible and reproducible manner.
The user may choose to perform design optimizations through the optLAVA class or through OpenMDAO. The optLAVA class has strict requirements on the python packages required for running an optimization case, discussed in the section pyLAVA Setup and Requirements. Optimizations through OpenMDAO do not rely on the optLAVA class, and instead rely only on the LAVA class (i.e. the direct python interface for the LAVA Curvilinear solver). OpenMDAO is much more modular and allows you to bring your own geometry engine and external disciplines to the game.
pyLAVA Setup and Requirements
Setting Up a Virtual Environment
We recommend using a virtual environment to isolate dependencies for this project. While venv is the easiest option since it’s part of the standard Python library, you are free to use conda or any other environment management tool you prefer.
Create a virtual environment:
Activate the environment: Verify that Python now points to the virtual environment:Accessing pyLAVA
On the NAS Cluster
On the NAS cluster, pylava is provided as part of the LAVA modules.
Information on loading the module is provided in the LAVA Installation Guide for NAS Users.
Loading one of the LAVA modules will append the PYTHONPATH environment variable to include the path to the pylava package.
This will provide python access to pylava without needing to install it in your own environment.
External Installation
To obtain pylava on a machine outside the NAS Cluster, first download the correct LAVA tarball by following the LAVA Installation Guide for External Users.
Once extracted, the directory structure will look like this:
pylava package is available as an installed package in /path/to/LAVA/lib/pylava/pylava.
Method 1 : pip install
Start by navigating to the pyLAVA root folder, LAVA/lib/pylava. From this directory using pip should add it to your python, environment.
Note
If you have permission errors when installing try changing the permission of the LAVA tarball directories to allow reading and writing.
Method 2 : Modify the PYTHONPATH
To make pylava accessible in your Python environment, add its parent directory to your PYTHONPATH:
To verify the installation, run:
This will display details like version, location, and dependencies, confirming that Python can find the package.Method 3 : Append the path in your Python scripts
If you prefer not to modify PYTHONPATH globally, add the following lines at the top of your Python script:
Requirements for pyLAVA
The pylava package is not shipped with the necessary dependencies.
You will need to install the required packages manually.
The required packages depend on the type of case you plan to run: simply running aerodynamic analyses through pylava requires fewer packages than running shape optimization cases. We provide details below.
Aerodynamic Analysis Requirements
In addition to pylava itself, the following python packages are required for running the aerodynamic analysis cases
(i.e. non-optimization cases).
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
numpy |
link | Fundamental package for array computing in Python | 2.4.2 |
pyYAML |
link | YAML parser and emitter for Python | 6.0.3 |
mpi4py |
link | Python bindings for MPI (only required if running MPI) | 4.0.0 |
Optimization Requirements
In addition to pylava itself, the following python packages are required for running shape optimization cases through the pylava package.
Some of these can be installed via pip, while others need to be installed from their respective GitHub repositories.
Please visit the provided links for installation instructions.
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
numpy |
link | Fundamental package for array computing in Python | 2.4.2 |
pyYAML |
link | YAML parser and emitter for Python | 6.0.3 |
pandas |
link | Powerful data structures for data analysis, time series, and statistics | 3.0.0 |
tabulate |
link | Pretty-print tabular data | 0.9.0 |
pyspline |
link | Python tools for B-spline curves, surfaces, volumes | 1.5.3 |
pygeo |
link | Object-oriented geometry framework for MDO and CAD. | 1.17.0 |
pyoptsparse |
link | Framework for efficient large-scale nonlinear optimization | 2.14.5 |
mpi4py |
link | Python bindings for MPI | 4.0.0 |
If you plan to vizualize the optimization history using pyoptsparse's optview, you will need to install the following packages
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
pyoptsparse.optview |
link | Interactive visualization of optimization history | 2.14.5 |
OpenMDAO-Based Optimization Requirements
For connecting to OpenMDAO, the following packages are required,
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
numpy |
link | Fundamental package for array computing in Python | 2.4.2 |
pyYAML |
link | YAML parser and emitter for Python | 6.0.3 |
openMDAO |
link | Multidisciplinary optimization framework | 3.42.0 |
MPhys |
link | Multiphysics framework built on OpenMDAO | 2.0.0 |
Additionally, for MPI support, you will require the following packages
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
mpi4py |
link | Python bindings for MPI | 4.0.0 |
petsc4py |
link | PETSc for Python | 3.24.2 |
Shape Optimization YAML Input Options
Description of inputs for a yaml file provided to the optLAVA class for aerodynamic shape optimization with LAVA.
Example yaml files, named opt.yaml, can be found in the shape optimization tutorials provided in the LAVA Curvilinear tutorials.
objective
-
name (
String,Default=obj)- Name of the objective function.
-
scale (
Float,Default=1.0)- Scaling factor applied to objective function.
-
functionals [SEQUENCE]
-
A sequence specifying the functionals used as the objective function for optimization. Multiple functionals can be specified, these will all be multiplied by the user-specified weight for each, and then summed together to get the objective function value. Surface (aka BC) families for aerodynamic objectives can be specified for given functionals.
-
func (
String)- Name of the functional used for the objective. For example, cl, cd, or cmy.
-
families (
List)- List of surface (aka BC) families on which this functional is computed. The name of the families must match the name given in the LAVA yaml and grid.bc files. As an example use, if we only want \(C_L\) on the wing and tail, then we may set the families to be [wing, tail].
-
weight (
Float,Default=1.0)- The weight multiplied to this functional in the calculation of the total objective function. Typically, with multiple objective functions all the weights should sum to 1.
-
target (
Float)- The target for this functional. Default is none, for which the optimizer attempts to minimize (or maximize) the functional on its own. If a target is specified, then the objective function for this functional is modified to be (func - target)^2.
-
-
probetarget [SEQUENCE]
-
probename (
String,Required)- Name of the probe for which this target is set. This probe, and its corresponding name, must exist in the 'probes' section of the LAVA yaml file.
-
filename (
String(FileName),Required)- Name of the probe solution file that holds the target values. For example, this solution file should contain the pressure targets if we are targetting pressure on a given probe.
-
sourcefiletype (
String(FileName),Default=tri)- File type of the probe target file. Acceptable values are: [tri, plot3d, tecplot]
-
targetvars (
String|List,Required)- Variables that we are targeting on the probe surface.
-
precision (
String)- Precision of the file containing the probe target solution.
-
restart (String)
- Name of the pyOptSparse hot start file. See the official pyOptSparse documentation.
lava
-
suffix (
String)- Suffix for the dynamic library lavacurv name. For example, if given
suffix=GNU, the dynamic librarylavacurv.GNU.sowill be used for optimization.
- Suffix for the dynamic library lavacurv name. For example, if given
-
libpath (
String)- Absolute path to the directory containing the lavacurv dynamic library file.
-
warmstart (
Boolean,Default=False)- Boolean, if true then we never reset the solution (Q) vector in LAVA to freestream, all flow solves start from the solution vector obtained from the last flow solve.
designvars
-
ffd [SEQUENCE]
-
name (
String,Required)- Unique name for this FFD parameterization.
-
filename (
String(FileName),Required)- Name of the plot3d file containing the FFD control point coordinates.
-
families (
List,Default=['*'])- List of surface families to be included in this FFD. Default is [all] which includes all surfaces.
-
blocks (
List)- List of mesh blocks that will be warped based on the deformation of the surface families listed in the families entry. Default is none, for which all mesh blocks will be deformed. Note that this option is not used if MultiFFD is specified.
-
shape
-
Creates local shape design variables via pyGeo.DVGeometry.addLocalDV. See the official pyGeo documentation.
-
name (
String,Required)- Unique name for this design variable group
-
lower (
Float)- Lower bound applied to all local shape variables.
-
upper (
Float)- Upper bound applied to all local shape variables.
-
scale (
Float,Default=1.0)- Scaling factor for the variables.
-
axis (
String,Default=y)- Direction of control-point motion. One of {'x','y','z'}. Use multiple entries if you need more than one direction.
-
vollist (
List)- Indices of FFD volumes whose control points are used for this DV group.
-
config (
String|List)- Apply this DV group to one or more DVGeo configurations (None applies to all configurations).
-
-
sectionshape
-
Creates section-local shape design variables via pyGeo.DVGeometry.addLocalSectionDV. See the official pyGeo documentation.
-
name (
String,Required)- Unique name for this section-local DV group
-
secindex (
String|List,Required)- Sectioning index per volume: choose 'i', 'j', or 'k' (list allowed). The chosen index defines the transverse (2) direction for section-local perturbations.
-
lower (
Float)- Lower bound applied to all section-local shape variables.
-
upper (
Float)- Upper bound applied to all section-local shape variables.
-
scale (
Float,Default=1.0)- Scaling factor for the variables.
-
axis (
Integer,Default=1)- Direction within/out of the section plane: 0=longitudinal (in-plane), 1=latitudinal (in-plane), 2=transverse (out-of-plane).
-
vollist (
List)- Indices of FFD volumes to include (None uses all volumes).
-
orient0 (
String|List)- How to orient the in-plane '0' axis: None (best-fit through section points), one of {'i','j','k'} (mean FFD-edge direction), or a vector [x,y,z] (projected onto the section plane).
-
orient2 (
String,Default=svd)- Method for the out-of-plane '2' axis: 'svd' (from section-plane SVD) or 'ffd' (use FFD direction of secIndex).
-
config (
String|List)- Apply this DV group to one or more DVGeo configurations (None applies to all configurations).
-
-
spanwiselocal
-
Creates spanwise-constant local shape variables via pyGeo.DVGeometry.addSpanwiseLocalDV. See the official pyGeo documentation.
-
name (
String,Required)- Unique name for this spanwise-local DV group.
-
spanindex (
String,Required)- Axis along which DVs are constant: one of {'i','j','k'} (the FFD index specifying the spanwise direction).
-
axis (
String,Default=y)- Direction of control-point motion. One of {'x','y','z'}. Use multiple entries if you need more than one direction.
-
lower (
Float)- Lower bound applied to all spanwise-local shape variables.
-
upper (
Float)- Upper bound applied to all spanwise-local shape variables.
-
scale (
Float,Default=1.0)- Scaling factor for the variables.
-
vollist (
List)- Indices of FFD volumes whose control points are used.
-
config (
String|List)- Apply this DV group to one or more DVGeo configurations (None applies to all configurations).
-
-
axialcurve [SEQUENCE]
-
Creates a reference axis for global design variables via pyGeo.DVGeometry.addRefAxis. See the official pyGeo documentation
-
name (
String,Required)- Name of axial curve
-
pts (
String|List)- A set of (x, y, z) coordinates for which a B-Spline curve is constructed. The resulting B-Spline curve is used as the axis.
ptscan be given directly as a list of (x, y, z) points in the yaml file, for example - Alternatively, a file name
pts : axis.datcan be given, for which the corresponding file contains the (x,y,z) points. The file should list the coordinates of each point, with x, y, and z separated by the delimiter specified in the yaml (see next yaml entry). For example, to create an axis that runs along the y-coordinate, we can use the following entries in a fileaxis.dat: - This option cannot be used in conjuction with the options
xFraction,yFraction, andzFraction.
- A set of (x, y, z) coordinates for which a B-Spline curve is constructed. The resulting B-Spline curve is used as the axis.
-
delimiter (
String)- The delimiter used to separate the x, y, and z values in the file containing the axis points. This is only used if a file name is specified for the
ptsentry above.
- The delimiter used to separate the x, y, and z values in the file containing the axis points. This is only used if a file name is specified for the
-
xfraction (
Float)- Parametric streamwise location of the reference axis node relative to front/rear control points.This option cannot be used in conjunction with the option
pts.
- Parametric streamwise location of the reference axis node relative to front/rear control points.This option cannot be used in conjunction with the option
-
yfraction (
Float)- Parametric location along axis 1 relative to top/bottom control points. This option cannot be used in conjunction with the option
pts.
- Parametric location along axis 1 relative to top/bottom control points. This option cannot be used in conjunction with the option
-
zfraction (
Float)- Parametric location along axis 2 relative to top/bottom control points. This option cannot be used in conjunction with the option
pts.
- Parametric location along axis 2 relative to top/bottom control points. This option cannot be used in conjunction with the option
-
alignindex (
String)- FFD axis along which the reference axis will lie (i, j, or k). Required when using xFraction.
-
axis (
String|List,Default=x)- Controls how links between control points and the reference axis are computed. Use 'x','y','z' for ray-based projection or a 3-element vector for plane-based projection (recommended for angled axes).
-
-
twist
-
Add the global design variable for twist to the pyGeo.DVGeometry object.
-
name (
String,Required)- A unique name to be given to the twist design variable. This may be useful if multiple twist variables are present.
-
curve (
String,Required)- Name of the axial curve about which this twist variable is defined.
-
axis (
String,Required)- Cartesian axis about which to perform the rotation about the axial curve. Allowed values are
x,y, orz. For example, if the span-wise direction of a wing is \(y\), then the twist axis should be set toy.
- Cartesian axis about which to perform the rotation about the axial curve. Allowed values are
-
value (
Float|List,Default=0.0)- The initial value of the twist DV. Can be either a single float applied to all twist DVs, or a list of values.
-
lower (
Float|List,Required)- The lower bound(s) for the variable(s).
-
upper (
Float|List,Required)- The upper bound(s) for the variable(s).
-
scale (
Float|List,Required)- The scaling of the variables.
-
rigid (
Boolean,Default=False)- Boolean, set to true if the FFD rotates rigidly. In other words, all control point stations rotate the same amount.
-
-
-
aero [SEQUENCE]
-
List of aerodynamic design variables.
-
name (
String,Required)- Name of the aerodynamic design variable.
-
value (
Float,Default=0.0)- Starting value for the aerodynamic design variable.
-
lower (
Float)- Lower bound for the design variable value.
-
upper (
Float)- Upper bound for the design variable value.
-
scale (
Float,Default=1.0)- A scaling factor for the dv.
-
-
multiffd
-
Options for the pyGeo object DVGeoMulti. This can handle intersections where two bodies (e.g. wing and fuselage) are parameterized by separate FFDs. As a result, one body can be deformed while the other remains unchanged around the intersection. See the official pyGeo documentation
-
components [SEQUENCE]
-
Sequence of components added to DVGeoMulti. See addComponent in the official pyGeo documentation.
-
name (
String,Required)- User-defined name for this component.
-
ffdname (
String,Required)- Name of the FFD volume that will be given as a component to the DVGeoMulti object. This name must match an entry given in the designVars.FFD.name section of the yaml file
-
trimesh (
String,Required)- Name of the CGNS file which contains (1) the triangulation of the surface for this component and (2) the feature curves for this surface.
-
-
intersections [SEQUENCE]
-
Sequence of intersection definitions between components. See addIntersection in the official pyGeo documentation.
-
compa (
String,Required)- Name of the first component in the intersection.Must match an entry given in designVars.MultiFFD.components.name.
-
compb (
String,Required)- Name of the second component in the intersection.Must match an entry given in designVars.MultiFFD.components.name.
-
dstara (
Float,Default=0.2)- Distance over which inverse-distance deformation is applied on compA.
-
dstarb (
Float,Default=0.2)- Distance over which inverse-distance deformation is applied on compB.
-
featurecurves (
List)- List of curves used as 'feature' curves for the deformation. Points on feature curves will remain on the same curve after deformations and projections.the march direction for all curves is
marchDirThe name of these curves must match thezone_sectionname for a curve specified in the triMesh CGNS files listed in the component options. For e.g., say we have a curve namedcon-1in the zonewingin the CGNS file given to a component. The feature curve name for this iswing_con-1.
- List of curves used as 'feature' curves for the deformation. Points on feature curves will remain on the same curve after deformations and projections.the march direction for all curves is
-
disttol (
Float,Default=1e-14)- Tolerance for merging nearby nodes in intersection curves.
-
project (
Boolean,Default=False)- If True, projects points to curves and surfaces after deformation.
-
marchdir (
Integer,Default=1)- Axis and direction for remeshing feature curves (1=x, 2=y, 3=z).
-
includecurves (
Boolean,Default=False)- If True, includes feature curves in inverse-distance deformation.
-
intdir (
Integer)- Specifies which intersection curve to use when multiple exist (sign and axis).
-
curveeps [SEQUENCE]
-
Required if using feature curves. Specifies curve names and point distances.
-
name (
String,Required)- Name of the feature curve.
-
distance (
Float,Required)- Distance threshold for considering points on the curve.
-
-
tracksurfaces [SEQUENCE]
-
Specifies surfaces whose points should remain on the same surfaces after deformation and projection
-
name (
String,Required)- Name of the surface. This must correspond to a surface available in a triMesh CGNS file given to one of the components. The name convention is
zone_sectionname. For example, if a surface calledtriElementsis in zonewingof the CGNS file, then the specified surface name iswing_triElements.
- Name of the surface. This must correspond to a surface available in a triMesh CGNS file given to one of the components. The name convention is
-
distance (
Float,Required)- Distance threshold for tracking points on the surface.
-
-
excludesurfaces [SEQUENCE]
-
Specifies surfaces to exclude from intersection computations.
-
name (
String,Required)- Name of the surface. This must correspond to a surface available in a triMesh CGNS file given to one of the components. The name convention is
zone_sectionname. For example, if a surface calledtriElementsis in zonewingof the CGNS file, then the specified surface name iswing_triElements.
- Name of the surface. This must correspond to a surface available in a triMesh CGNS file given to one of the components. The name convention is
-
distance (
Float,Required)- Distance threshold for excluding points on the surface.
-
-
remeshbwd (
Boolean,Default=True)- If True, remesh feature curves on both sides of the intersection.
-
anisotropy (
List,Default=[1.0, 1.0, 1.0])- Scaling factors [x,y,z] for curve-based deformation to improve mesh quality.
-
-
pointsets [SEQUENCE]
-
Sequence of point sets (or surface meshes) to be added to the DVGeoMulti object for parameterization. See addPointSet in the official pyGeo documentation.
-
name (
String,Required)- Surface name for this point set within the context of all the point sets given to the DVGeoMulti object.This must correspond to the BC family names from the grid.bc and lava.yaml files
-
compnames (
List)- List of components to which this point set is added (default: all components).
-
applyic (
Boolean,Default=False)- If True, point set follows updated intersection curves (typically for CFD meshes).
-
-
debug (
Boolean,Default=False)- If true, writes out debug info for DVGeometryMulti Object.
-
constraints
-
aero [SEQUENCE]
-
Aerodynamic-functional-based constraints. For example, an equality on \(C_L\), or an inequality constraint \(C_{My}\).
-
name (
String,Required)- Unique name of the aerodynamic constraint. This may be the name of the function we wish to constrain, e.g. cl. However, when dealing with surface families, we may have various cl's to constrain, hence this should be a unique name for this aerodynamic constraint. For example, if we have different cl constraints for a wing and tail, we may choose to name them 'cl_wing' and 'cl_tail', hence giving them unique names.
-
functionals [SEQUENCE]
- List of functions and weights to be used in this constraints. This list allows us to create compound constraints by taking the sum of multiple aerodynamic functionals. E.g., we may want to have a constraint such as lift = drag (I don't know why, but just go with it). We would then specify :
- constraints :
- aero :
-
- name : cl_cd
- func :
-
- name : cl
- weight : 1.0
-
- name : cd
- weight : -1.0
- upper : 0.0
- lower : 0.0
-
If none is given, then the 'name' option is taken as the functional.
-
func (
String,Required)- Name of the aerodynamic functionals to constrain.
-
families (
List)- LAVA surface families for which to apply this aerodynamic constraint. For example, if we only want to constrain the lift coef on the wing and body of a full configuration, then we would have
name = clandfamilies=[wing, body].
- LAVA surface families for which to apply this aerodynamic constraint. For example, if we only want to constrain the lift coef on the wing and body of a full configuration, then we would have
-
weight (
Float,Default=1.0)- The weight to apply to this functional.
-
designvars [SEQUENCE]
- List of design variables to be used in this constraints. This list allows us to create compound constraints by including of multiple design variables. E.g., we may want to have a constraint such as drag=thrust. We would then specify :
- constraints :
- aero :
-
- name : cd_thrust
- func :
-
- name : cd
- weight : 1.0
- designVars :
-
- name : acd.1.thrust
- weight : -1.0
- upper : 0.0
-
lower : 0.0
-
name (
String,Required)- Name of the design variable to include in this constraint.
-
weight (
Float,Default=1.0)- Weight applied to this design variable for this constraint.
-
lower (
Float)- Lower bound on this functional. If upper and lower bounds are equal, then the constraint is an equality.
-
upper (
Float)- Upper bound on this functional. If upper and lower bounds are equal, then the constraint is an equality.
-
scale (
Float,Default=1.0)- A scaling factor for the constraint. It is generally advisable to have most optimization constraint around the same order of magnitude.
-
-
surfaces [SEQUENCE]
-
Entries pertaining to the surfaces that will be passed to pyGeo.DVCon on which the constraints will be placed.
-
name (
String,Required)- Unique name of the aerodynamic surface. If no filename is provided for this surface, then optLAVA will get the surface from the LAVA grid families. Thus, unless a filename is provided, this family MUST be present in LAVA's YAML input file.
-
dvgeoname (
String,Default=default)- Name of the DVGeo object to compute the constraint with. You only need to set this if you're using multiple DVGeo objects for a problem. For backward compatibility, the name is 'default' by default
-
filename (
String(FileName))- File name for the surface. This is an optional argument, if it is not provided, then optLAVA will get the surface from LAVA's grid families. Currently, the surface file must be a CART3D-style tri file.
-
-
pinnedlete [SEQUENCE]
-
Adds leading-edge/trailing-edge pinning constraints via pyGeo.DVConstraints.addLeTeConstraints. See the official pyGeo documentation. These constraints enforce equal and opposite movement of paired control points on LE/TE faces to prevent unintended twist.
-
volid (
Integer,Required)- Single integer specifying the volume index.
-
faceid (
String,Required)- Face identifier for the constraint. Must be one of: ['iLow', 'iHigh', 'jLow', 'jHigh', 'kLow', 'kHigh'].
-
start (
Integer)- The control point index in the edge-wise direction for which to start placing the pinned constraint. For example,
start : 3andend : 3will only pin the third control point along the edge of the FFD.
- The control point index in the edge-wise direction for which to start placing the pinned constraint. For example,
-
end (
Integer)- The control point index in the edge-wise direction for which to place the last pinned constraint. For example,
start : 3andend : 3will only pin the third control point along the edge of the FFD.
- The control point index in the edge-wise direction for which to place the last pinned constraint. For example,
-
dvgeoname (
String,Default=default)- Name of the DVGeo object associated with this constraint (default: 'default').
-
comp (
String)- Component name when using DVGeometryMulti.
-
topid (
String)- Symmetry direction identifier for 2×2 faces. Must be one of: {'i', 'j', 'k'}.
-
-
volume [SEQUENCE]
- Adds a wing volume constraint via pyGeo.DVConstraints.addVolumeConstraint. See the official pyGeo documentation.
-
Defines a 2D domain between leading and trailing edges (leList/teList), subdivided into nSpan × nChord points and projected onto the surface to compute volume.
-
lelist (
List|String,Required)- List/array of Nx3 points (N ≥ 2) defining the leading edge of the domain.
-
telist (
List|String,Required)- List/array of Nx3 points defining the trailing edge of the domain.
-
nspan (
Integer|List,Required)- Number of points interpolated along leList/teList; a list can specify per-segment counts.
-
nchord (
Integer,Required)- Number of points interpolated between leading and trailing edges.
-
lower (
Float,Default=1.0)- The lower bound for the volume constraint.
-
upper (
Float,Default=3.0)- The upper bound for the volume constraint.
-
scaled (
Boolean,Default=True)- If True, bounds are relative to the initial volume (e.g., 0.85–1.15 permits ±15%). If False, bounds are absolute physical volumes.
-
scale (
Float,Default=1.0)- Optimization scaling factor; typically left at 1.0 unless magnitudes differ significantly.
-
name (
String)- Optional identifier for this constraint (useful with multiple DVCon objects).
-
addtopyopt (
Boolean,Default=True)- Set False if not adding directly to the optimization problem.
-
surfacename (
String,Default=default)- Name of the projection surface (matches the name used in setSurface()).
-
dvgeoname (
String,Default=default)- Name of the DVGeo object associated with this constraint.
-
compnames (
List)- For DVGeometryMulti, list components to which the point set is added (default: all).
-
thickness [SEQUENCE]
- Adds spanwise/chordwise thickness constraints via pyGeo.DVConstraints.addThicknessConstraints2D. See the official pyGeo documentation
-
Defines a 2D region between leading and trailing edges (leList/teList), subdivided into nSpan × nChord and projected onto the surface; each grid point enforces a local thickness bound.
-
lelist (
List|String,Required)- Leading-edge definition: either an Nx3 array of points (N ≥ 2) or a filename containing that array in text form (first line: count; subsequent lines: X Y Z).
-
telist (
List|String,Required)- Trailing-edge definition (same formats as leList).
-
nspan (
Integer|List,Required)- Number of thickness sample locations along leList/teList. A list can specify per-segment counts.
-
nchord (
Integer,Required)- Number of thickness sample locations between leading and trailing edges.
-
lower (
Float|List,Default=1.0)- Lower bound. Use a single float (applies to all samples) or an array of size (nSpan × nChord) for per-sample bounds.
-
upper (
Float|List,Default=3.0)- Upper bound. Use a single float or an array of size (nSpan × nChord) for per-sample bounds.
-
scaled (
Boolean,Default=True)- If True, bounds are relative to initial thickness at each location (e.g., 0.85–1.15 allows ±15%). If False, bounds are specified as absolute physical lengths.
-
scale (
Float|List,Default=1.0)- Optimization scaling factor(s). Typically 1.0; when using arrays, supply size (nSpan × nChord).
-
name (
String)- Optional identifier for this constraint (useful when multiple DVCon objects are present).
-
addtopyopt (
Boolean,Default=True)- Set False to compute thickness values without adding them directly to the optimization problem.
-
surfacename (
String,Default=default)- Name of the projection surface (must match the name used in setSurface()).
-
dvgeoname (
String,Default=default)- Name of the DVGeo object associated with this constraint.
-
compnames (
List)- For DVGeometryMulti, list components to which the point set is added (default: all).
-
projected (
Boolean,Default=False)- If True, uses the component of thickness aligned with the original thickness direction.
-
shapethickness [SEQUENCE]
-
If included in the yaml file, this option will add a thickness constraint to the control points of the FFD volume. This is done by making a call to the function
addLinearConstraintsShapein the pyGeo.DVConstraint object . See the official pyGeo documentation for details on addLinearConstraintsShape. -
volid (
Integer,Required)- Single integer specifying the volume index.
-
dirindex (
String,Required)- One of
i,j, ork. Specifies the direction for which the constraint is placed. For example, an FFD for a wing may have all the control points below the wing atk=0, and all the control points above the wing atk=1. In this example,dirIndexwould be set tok.
- One of
-
axis (
String,Required)- One of
x,y, orz. The cartesian coordinate along which to place the thickness constraint.
- One of
-
lower (
Float,Default=0.1)- Lower bound based on the initial thickness, for example 'lower : 0.25' is a 25% thickness lower bound. Default is 10%.
-
upper (
Float,Default=10)- Upper bound based on the initial thickness, for example 'upper : 1.25' is a 125% thickness upper bound. Default is 1000%.
-
name (
String)- Unique name for this constraint.
-
config (
String)- The DVGeo configuration to apply this constraint to. Must be either None which will apply to ALL the local DV groups or a single string specifying a particular configuration.
-
childname (
Integer)- Name of the child FFD, if this constraint is being applied to a child FFD
-
comp (
String)- The component name if using DVGeometryMulti
-
dvgeoname (
String,Default=default)- Name of the dv geo object to which this constraint is applied.
-
-
monotonic [SEQUENCE]
-
Adds monotonic constraints via pyGeo.DVConstraints.addMonotonicConstraints. See the official pyGeo documentation.
-
key (
String,Required)- Name of the global design variable to constrain.
- NOTE : When using the DVGeoMulti, you must define the
keyas 'ffdname_key'. For example, if an ffd namedwingffdhas the design vartwist, then thekeyentry when using DVGeoMulti iswingffd_twist.
-
slope (
Float,Default=1.0)- Direction of monotonicity along the DV vector: 1.0 enforces monotonic decrease left→right; −1.0 enforces monotonic decrease right→left.
-
name (
String)- Optional identifier for this constraint (useful when multiple DVCon objects are present).
-
start (
Integer,Default=0)- Inclusive start index of the DV slice to constrain (use with stop to constrain a subset).
-
stop (
Integer,Default=-1)- Inclusive end index of the DV slice to constrain (use with start to constrain a subset).
-
config (
String)- Apply the constraint to a specific DVGeo configuration (None applies to all local DV groups).
-
childidx (
Integer)- Zero-based index of the child FFD to which this constraint applies (if constraining a child FFD).
-
comp (
String)- Component name when using DVGeometryMulti.
-
dvgeoname (
String,Default=default)- Name of the DVGeo object associated with this constraint (default: 'default').
-
optimizer
-
name (
String,Required,Default=SNOPT)- Name of the optimizer from pyOptSparse to use. See official pyOptSparse documentation.
-
options
- The set of options given to pyOptSparse's OPT class. See official pyOptSparse documentation. Note that all the keys in this section are case sensitive. Dependent on the selected optimizer. See the tutorials for examples.
output
-
Options which control the outputs from the optimization process.
-
outputdir (
String,Default=.)- Directory into which to write all the output files.
-
monitor
-
These options are used to specify the variables that a user wants to monitor during the optimization. Specified variables are written to the file specified by the
filenameoption. -
filename (
String(FileName),Default=optMonitor.txt)- Name of the file in which the monitored variables are written.
-
variables (
List,Default=[])- List of variable names (
strings) which the user is interested in monitoring during the optimization process. (I'll write more about what is supported in a future iteration of this documentation.)
- List of variable names (
-
-
history
- List (a short list) of options for the history file written by pyOptSparse reflecting the history of the optimization problem. This history file is written in a SQL-type database format. It contains the values of the functionals, gradients, and design variables for each function/gradient evaluation done during the optimization.
- It later can be used as a restart file for optimization assuming all parameters are exactly the same for the optimization problem.
-
See the official pyOptSparse documentation.
-
filename (
String(FileName),Required)- Name of the history file.
-
surface [SEQUENCE]
-
List of options to write out the surface geometry. Note that these files are written to a tecplot
.pltfile, and contain both surface and FFD coordinate information. Thus, they can be used to visualize the FFD volume and control points as well as the surface. -
filename (
String(FileName),Default=surface.opt)- Filename for the surface geometry information. When writing the files, this will be appended with the iteration number, e.g.
surface.opt.0000010.plt.
- Filename for the surface geometry information. When writing the files, this will be appended with the iteration number, e.g.
-
frequency (
Integer,Default=-1)- Frequency at which to write the surface information. If set to
-1, then no file is written.
- Frequency at which to write the surface information. If set to
-
variables (
List,Default=[])- List of strings containing the flow field variables that a user wants plotted on the surface. For example, if a user wants to see the primitive variables on the surface, they can write
- variables : [pressure, velocityx, velocityy, velocityz, temperature]
- Any variable output option available in LAVA can be plotted on the surface.
-
first (
Boolean,Default=False)- If set to
True, then write the surface geometry output at the first design iteration before any changes have been made.
- If set to
-
latest (
Boolean,Default=False)- If set to
True, then write a file called, for example,surface.opt.latest.pltwhich holds the geometry for the latest function evaluation. Note that if the file already exists from a previous 'latest' write, then that file is deleted before writing the new 'latest'. If the latest surface geometry has been written out from thefrequencyoutput, then a link is created for the 'latest' file for that iteration.
- If set to
-
-
volume [SEQUENCE]
-
List of options to write out the volume grid and solution to file. Writing the files is done by LAVA, not by python. Hence, most options mimic the volume output options from the standard LAVA yaml. A volume grid file is always written. If either the variables entry if non-empty, or the filetype is specified as
plot3dsolution, then a volume solution file is also written. -
filename (
String(FileName),Default=volume.opt)- Filename for the volume geometry information. When writing the files, this will be appended with the iteration number, e.g.
volume.opt.0000010.plt.
- Filename for the volume geometry information. When writing the files, this will be appended with the iteration number, e.g.
-
filetype (
String(FileName),Default=plot3d)- File type for the resulting volume output. Options include
-
- plot3d
-
- cgns (only available if code is compiled with cgns capability)
-
- plot3dsolution
- Note: if
plot3dsolutionis specified, then a solution file containing the conservative flow variable is also written.
-
variables (
List,Default=[])- List of strings containing the flow field variables that a user wants plotted on the volume. For example, if a user wants to see the primitive variables on the volume, they can write
- variables : [pressure, velocityx, velocityy, velocityz, temperature]
- Any variable output option available in LAVA can be plotted in the volume.
- Note: if
plot3dsolutionis specified as the file type, then all user-specified variables are ignored. Only conservative flow variables are written for this file type.
-
frequency (
Integer,Default=-1)- Frequency at which to write the volume information. If set to
-1, then no file is written.
- Frequency at which to write the volume information. If set to
-
first (
Boolean,Default=False)- If set to
True, then write the volume output at the first design iteration before any changes have been made.
- If set to
-
latest (
Boolean,Default=False)- If set to
True, then write a file called, for example,volume.opt.latest.xwhich holds the geometry for the latest function evaluation. Note that if the file already exists from a previous 'latest' write, then that file is deleted before writing the new 'latest'. If the latest volume file has been written out from thefrequencyoutput, then a link is created for the 'latest' file for that iteration.
- If set to
-
usesingle (
Boolean,Default=False)- Use single precision for volume output.
-
-
designvars [SEQUENCE]
- List of options to write out the design variable values to a file for given iteration numbers.
-
Note : this output is under construction, and thus far only geometric design variables such as
sectionShapeandtwistare supported for this output. More support to come in the near future. -
variables (
List,Required,Default=False)- List of strings containing the design variables to include in the file. These strings must match the names of the design variables given in the
designVarssection of the YAML.
- List of strings containing the design variables to include in the file. These strings must match the names of the design variables given in the
-
filename (
String(FileName),Default=dvs)- Filename for the design variable information. When writing the files, this will be appended with the iteration number, e.g.
dvs.0000010.dat.
- Filename for the design variable information. When writing the files, this will be appended with the iteration number, e.g.
-
frequency (
Integer,Default=-1)- Frequency at which to write the design variable information. If set to
-1, then no file is written.
- Frequency at which to write the design variable information. If set to
-
first (
Boolean,Default=False)- If set to
True, then write the design vars are output at the first design iteration before any changes have been made.
- If set to
-
print (
Boolean,Default=False)- If set to
True, then the information that is written to the file is also printed to the screen.
- If set to
-
latest (
Boolean,Default=False)- If set to
True, then write a file called, for example,dvs.latest.datwhich holds the geometry for the latest function evaluation. Note that if the file already exists from a previous 'latest' write, then that file is deleted before writing the new 'latest'. If the latest volume file has been written out from thefrequencyoutput, then a link is created for the 'latest' file for that iteration.
- If set to
-
ffd [SEQUENCE]
-
List of options to write out pyGeo's FFD volumes to file. Writing the files is done by pyGeo's writeTecplot function.
-
filename (
String(FileName),Default=ffd)- Filename for the ffd file. Note that the file will be appended by the name of the FFD and the iteration number. So for example, if we have two FFDsnamed 'wingFFD' and 'tailFFD', and we choose to write them both,we will get two files: 'ffd.wingFFD.0000001.dat' and 'ffd.airfoilFFD.0000001.dat
-
names (
List)- List of FFD names to write to file. These names should match the names given in the designVars.FFD.nameinputs in the yaml file. The default is None, which writes all FFDs.
-
frequency (
Integer,Default=-1)- Frequency at which to write the volume information. If set to
-1, then no file is written.
- Frequency at which to write the volume information. If set to
-
first (
Boolean,Default=False)- If set to
True, then write the ffd output at the first design iteration before any changes have been made.
- If set to
-
Tools
Description
b2bExtractor is a utility program which constructs the Block-2-Block (B2B) file for
point-matched multi-block portions of the grid system. This operation can be performed
during task: connectivity, but many users prefer to perform the operation independently
to assess the correctness of their mesh and B2B inputs.
Example
Assuming a grid system which contains point-matched B2B interfaces has been constructed, then the following command can be used to generate the B2B file:
Here the grid filename isgrid.x and we also provided a BC file grid.bc so
that surface subsets do not have to checked for point matched neighbors. Finally, the
output filename base grid is given to generate the B2B file grid.b2b. An example
B2B file can be found in the Curvilinear User Guide-Quickstart section. More information
on available options can be found using
$> b2bExtractor -help
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
+--------+--------+
____ ____ ____ ____ _ _ / /* /|
| _ \/ __ | _ \| __) | | | | / /** / |
| |_| )_|/ | |_| ) |__ _ _| |_ _ __ ____ ___| |_ ___ _ __ +--------+--------+ |
| _ ( / /| _ (| __| \ / | _| '__/ _ |/ __) _/ _ \| '__) | |*** | +
| |_| )/ /_| |_| ) |__ ) X (| |_| | ( (_) ( (__| |( (_) ) | | |** | /
|____/|____)____/|____|_/ \_|\__|_| \__,_|\___)\__\___/|_| | |* |/
+--------+--------+
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
b2bExtractor usage: b2bExtractor gridFileName
or: b2bExtractor -help
b2bExtractor optional arguments:
[-help]
[-oFileName #]
[-fullInds]
[-orderByDonor]
[-tol #]
[-onlyFullB2Bs]
[-blkTols # ## ..?.. ##]
[-BCFile #]
[-nPatchAlloc #]
[-translation # # #]
[-rotation # # # # # # #]
[-writeB2BZones]
[-warnPartialB2Bs]
[-ignoreBlkFaces # ## ..?.. ##]
[-debugBlkID #]
[-debugFaceI #]
Description
octFarfield is an Octree based Cartesian mesh generator for constructing off-body
Cartesian background grids for an overlapping curvilinear grid system. The utility
can also construct offset surfaces from an input surface triangulation to ensure
proper overlap with the near-body grids. It supports tecplot binary surface
triangulations.
Example
The following YAML input file, createOffset.yaml constructs an offset surface 0.8 meters from
an input CRM wing-body-tail configuration.
octFarField:
inputType : surface
inputFileType : tecplot
inputFile : wbh_aoa484_buffet_deformed_updatednose_mm_full.plt
externalFlow : True
dx : 0.001
cubeLength : 6275.0
outerBCs : [far, far, far, far, far, far]
nRefine : 16
nCellBuffer : 24
nbuffer : 0
usenearbodycoarsening : False
includeoverlap : True
createOffsetSurf : True
offsetSurfDist : 0.8
octFarfield utility:
This will generate at tecplot binary file offsetSurface.plt which is plotted along with
the input CRM wing-body-tail surface wbh_aoa484_buffet_deformed_updatednose_mm_full.plt.
Note the offset distance was set to 0.8 meters based on the near-body grid marching distance
which was set to 1.0 meter.
Now that the offset surface is generated, the Octree based off-body Cartesian grid can be
generated using the following YAML file, createOct.yaml
octFarField:
inputType : surface
inputFileType : tecplot
inputFile : offsetSurface.plt
externalFlow : True
dx : 0.046667
ymin : 0.0
cubeLength : 6275.0
refinementRegions:
-
type : box
xMin : [37.0, 0.0, 2.0]
xMax : [67.0, 30.0, 8.5]
refineFactor : -1
outerBCs : [far, far, symm, far, far, far]
nRefine : 16
nCellBuffer : 24
nbuffer : 0
usenearbodycoarsening : False
outputName : farfieldGrid
includeoverlap : True
mergeGrids utility (see tools documentation).
An image of the Cartesian grid system is shown with the offset surface for clarity.

Description
mergeGrids is a utility to merge multiple Plot3D overset grids together and
concatenate/combined the .bc and .b2b files. This utility is useful
when the near-body grids are generated using CGT while the off-body grids are
generated using the Octree based Cartesian grid generator octFarfield (see
Curvilinear User Guide-Tools documentation).
Example
Assuming the near-body Plot3D grid file nearbodyGrid.x has already been generated
along with the associated nearbodyGrid.bc and nearbodyGrid.b2b files,
and the off-body Plot3D grid file farfieldGrid.x along with farfieldGrid.bc
and farfieldGrid.b2b have also been generated using octFarfield or some other
tool, then the following utility can be used to merge the grids, BC, and B2B files:
grid.x, grid.bc, and grid.b2b
containing the merged Plot3D grid system and the concatenate/combined BC and B2B files.
Here is an image of the combined grid system for the CRM wing-body-tail.

Description
interpolator is a utility program to interpolate the solution from an existing
volume solution to another surface, volume, or unformatted set of points. This
can be useful when starting a fine grid solution when a coarse grid solution
already exists, or when interfacing to other solvers like the LAVA SpaceMarching
solver.
Example
An example YAML file, fringe.yaml, for using the interpolator is provided below:
interpolate :
sourcegridfile : grid.in.ihc
sourcegridfiletype : plot3d
sourcesolutionfile : volume.0010000.q
interpgridfile : fringe.x
interpgridfiletype : unformattedPoints
interpsolutionfile : fringe.q
location : vertex
stencilFile : stencils
useStencilFile : False
outsideTreatment : fixedValue
outsideValue : [0.0]
indices : [1,2,3,4,5]
grid.in.ihc and volume.0010000.q. The requested point locations for interpolation
are a set of unformatted points in the fringe.x file and the output will be put in
fringe.q. Here we are interpolating the first five variables from the solution file.
To run the utility,
refineTriangulation
Introduction
refineTriangulation is a triangulation refinement utility capable of refining
surface triangulations based on various criteria. The utility is based on a
longest edge bisection algorithm with neighbor propagation to ensure consistent
refinement. It supports:
-
Component-based refinement: users can specify components to refine along with target edge lengths.
-
Surface solution-based refinement: refinement is guided by a input target surface solution with prescribed edge lengths, where the surface solution is based on the size of the initial triangulation.
-
Volume solution-based refinement: refinement can be performed using a target volume solution generated using
writesolutiontask with the following output variables:cubeRootCellVolume(cube root of cell volume)minEdgeLength(minimum cell edge length)maxEdgeLength(maximum cell edge length)
Example Using Component-Based Refinement
The following YAML input file refines component 2 of a simple triangulation consisting of four triangles across two components.
triangulations:
-
sourceFile : rightTriangle.i.tri
sourceFileType : tri
outBaseName : refinedRightTriangle
outFileType : tecplot
outputDir : ./refinedRightTriangle
writeFrequency : 1
maxRefineIterations : -1
refineRegions:
-
components : [2]
targetEdgeLength : 0.001
This command runs the refineTriangulation utility using the YAML input file.
The output specifies how the number of triangles and vertices increase as successive refinement iterations are performed.
----------------------------------------------
| Global | Local |Number of |Number of |
| Iteration |Iteration |Triangles | Vertices |
----------------------------------------------
0 0 4 6
1 1 9 9
2 2 13 12
3 3 27 20
4 4 41 29
5 5 75 47
6 6 121 73
7 7 219 123
8 8 377 207
9 9 699 369
10 10 1273 665
11 11 2427 1243
12 12 4601 2347
13 13 8955 4525
14 14 17401 8781
15 15 34299 17231
16 16 67577 33935
17 17 134139 67217
18 18 266233 133393
This image shows the refinement pattern for component 2 of the simple
triangulation, demonstrating how the mesh is locally refined where specified and
propagated to neighbor triangles to ensure consistent refinement.

The output can also be monitored using the plotHist tool using the following command.
refineTriangulation YAML dict options
The YAML file format is used for specifying the information required.
The documentation below lists the name and type of each option. If an option is flagged as required then it must be included when the parent block is present. The default values and lower/upper bounds are also included for variables that have them. If an option is flagged as mutable then it can be modified on a solver restart. Each tab level in the YAML file should be 2 spaces. Blocks which can take multiple sub-blocks of an entry argument are prefaced by a -. Keywords in the YAML input file are case-insensitive.
interpolate
interpolate:
sourceGridFile:
sourceGridFiletype:
targetVolumeSolutionFile:
outsideTreatment:
outsideValue:
targetVolumeVariableIndex:
-
sourceGridFile (
string(fileName),default="grid.x")- Source grid file whose cell sizes are used to determine an edge length to be targeted during triangulation refinement.
-
sourceGridFiletype (
string,default="plot3d")- Accepted Values: [
"plot3d"] - Source grid file type.
- Accepted Values: [
-
targetVolumeSolutionFile (
string(fileName),default="sol.q")- Volume solution file corresponding to source grid file holding edge length value(s) (e.g., cubeRootCellVolume, minEdgeLength, maxEdgeLength). The selected value is interpolated onto the cell centers of the triangulation and targeted during refinement. Only one type of target solution (surface or volume) may be used at once.
-
outsideTreatment (
string,default="closest")- Accepted Values: [
"closest","fixedvalue"] - Values to assign to interpolation point if interpolation stencil is not found.
- closest: Assigns values based on closest point.
- fixedValue: Assigns values based on user-specified value.
- Accepted Values: [
-
outsideValue (
float,default=-99.00)- User-specified value to fill in interpolation points if interpolation stencil is not found and outsideTreatment is fixedValue.
-
targetVolumeVariableIndex (
integer,lower bound=1,default=1)- Index of variable within target volume solution file that should be targeted during triangulation refinement.
triangulations
triangulations:
-
sourceFile: <required>
sourceFileType:
outBaseName:
outFileType:
outputDir:
writeFrequency:
maxRefineIterations:
targetSurfaceSolutionFile:
targetSurfaceSolutionFileType:
targetSurfaceVariableIndex:
refineRegions:
-
components:
targetEdgeLength:
- Entries in triangulations are defined by a surface triangulation to be refined along with options specifying the refinement.
-
sourceFile (
string(fileName),required)- Source surface triangulation file to be refined.
-
sourceFileType (
string,default="tri")- Accepted Values: [
"tri","cgns"] - Source surface triangulation file type.
- Accepted Values: [
-
outBaseName (
string,default="out")- The basename for the output surface triangulation file without the file extension. The file extension will be automatically determined based on outFileType.
-
outFileType (
string,default="tri")- Accepted Values: [
"tri","cgns","tecplot"] - Output surface triangulation file type.
- Accepted Values: [
-
outputDir (
string,default="./")- Output directory relative to the run directory where the refined triangulations are to be written. A different output directory can be specified for each input triangulation.
-
writeFrequency (
integer,lower bound=-1,default=0)- Controls the frequency of writing refined triangulations. A value of 0 writes only the final refined triangulation. A positive value N writes every Nth intermediate refinement (e.g., 1 writes every step, 2 writes every second step). A value of -1 disables writing altogether.
-
maxRefineIterations (
integer,lower bound=-1,default=-1)- Maximum number of refinement iterations. A value of -1 indicates no maximum. When a source grid file is provided for refinement targeting, the maximum number of iterations corresponds to the maximum number of local refinement iterations between interpolations.
-
targetSurfaceSolutionFile (
string(fileName),default="surf.q")- Target surface solution file holding edge length value(s) (e.g., cubeRootCellVolume, minEdgeLength, maxEdgeLength). The selected value is targeted during refinement. Only one type of target solution (surface or volume) may be used at once.
-
targetSurfaceSolutionFileType (
string,default=)- Accepted Values: [
"tri"] - Target surface solution file type.
- Accepted Values: [
-
targetSurfaceVariableIndex (
integer,lower bound=1,default=1)- Index of variable within target surface solution file that should be targeted during triangulation refinement.
-
refineRegions
- Entries in refineRegions denote specific components or groups of components within a surface triangulation to be refined to a user-specified target edge length.
-
components ([
string, ...],default=[""])- List of components separated by commas. Components can be specified by number (e.g., 1), number range (e.g., 2-5), or name (e.g., wing).
-
targetEdgeLength (
float,lower bound=0.000,default=1.000)- Target edge length for component(s).
Example YAML Files
Example YAML File Using Component-Based Refinement
triangulations:
-
sourceFile : rightTriangle.i.tri
sourceFileType : tri
outBaseName : refinedRightTriangle
outFileType : tri
outputDir : ./refinedRightTriangle
writeFrequency : 0
maxRefineIterations : -1
refineRegions:
-
components : [2]
targetEdgeLength : 0.01
Example YAML File Using Surface Solution-Based Refinement
triangulations:
-
sourceFile : rightTriangle.i.tri
sourceFileType : tri
outBaseName : refinedRightTriangle
outFileType : tri
outputDir : ./refinedRightTriangle
writeFrequency : 0
maxRefineIterations : -1
targetSurfaceSolutionFile : rightTriangle.q
targetSurfaceSolutionFileType : tri
targetSurfaceVariableIndex : 1
Example YAML File Using Volume Solution-Based Refinement
interpolate:
sourceGridFile : grid.x
sourceGridFileType : plot3d
targetVolumeSolutionFile : vol.q
targetVolumeVariableIndex : 1
outsideTreatment : fixedValue
outsideValue : -1
triangulations:
-
sourceFile : rectangle.i.tri
sourceFileType : tri
outBaseName : refinedRectangle
outFileType : tri
outputDir : ./refinedRectangle
writeFrequency : 0
maxRefineIterations : -1
refine
Introduction
refine is a structured curvilinear overset mesh refinement utility. The algorithm is OpenMP parallel and enables the following key features:
- Non-integer refinement factors
- Global refinement
- Direction-specific refinement
- Zone-specific refinement
- Smoothing
- Refined surface extraction by boundary condition (BC) names
Input Options
refine uses the YAML file format for specifying the information required to run the solver.
The documentation below lists the name and type of each option. If an option is flagged as required then it must be included when the parent block is present. The default values and lower/upper bounds are also included for variables that have them. If an option is flagged as mutable then it can be modified on a solver restart. Each tab level in the YAML file should be 2 spaces. Blocks which can take multiple sub-blocks of an entry argument are prefaced by a -. Keywords in the YAML input file are case-insensitive.
refine
Grid refinement options
refine:
factor:
coarseGridFile: <required>
coarseGridFiletype:
tileSize:
refineGridFile:
bcFile:
writerecordmarkersingrids:
refinedirection:
smoothdirection:
nsmooth:
zoneSpecific:
-
zones:
refinedirection:
smoothdirection:
nsmooth:
-
factor (
float,lower bound=1.000,default=2.000)- Grid refinement factor to be applied to all blocks. A refinement factor cannot mathematically be guaranteed, however, non-integer factors are supported.
-
coarseGridFile (
string(fileName),required)- The coarse grid file name.
-
coarseGridFiletype (
string,default="plot3d")- Accepted Values: [
"plot3d"] - Coarse grid file type. Only plot3d is currently supported.
- Accepted Values: [
-
tileSize ([
integer,integer,integer],lower bound=4,default=18)- The size of the tiles, including one level of halos. The optimum tilesize is a primarily a function of the computer architecture, not the grid. The default size should give near optimum performance on modern computers.
-
refineGridFile (
string,default="refine.x")- The refined grid output file name.
-
bcFile (
string(fileName),default="")- Coarse grid BC file. This is used for extracting surfaces.
-
writerecordmarkersingrids (
boolean,default=True)- Write Fortran record markers in the refined Plot3D grid file.
-
refinedirection (
string,default="all")- Accepted Values: [
"j","k","l","jk","jl","kl","all"] - Block index directions to refine, applied to all zones not listed in zoneSpecific. Two-direction values refine both directions. A direction with 3 nodes is treated as a finite span and is never refined.
- Accepted Values: [
-
smoothdirection (
string,default="all")- Accepted Values: [
"j","k","l","all"] - Block index directions in which nsmooth smoothing iterations are applied, for all zones not listed in zoneSpecific.
- Accepted Values: [
-
nsmooth (
integer,lower bound=0,default=5)- Number of smoothing iterations for each zone. Smoothing is only applied for each block direction that has a non-unity stretching ratio. If refinement introduces a non-unity stretching ratio (mesh is uniform) in a given direction, then smoothing will be applied.
-
zoneSpecific
- Entries override refinedirection, smoothdirection and nsmooth for the listed zones. Options not given in an entry use the global value.
-
zones ([
string, ...],default=["default"])- The zones to apply the zone-specific options to.
-
refinedirection (
string,default="all")- Accepted Values: [
"j","k","l","jk","jl","kl","all"] - Block index directions to refine for the specified zones.
- Accepted Values: [
-
smoothdirection (
string,default="all")- Accepted Values: [
"j","k","l","all"] - Block index directions to smooth for the specified zones.
- Accepted Values: [
-
nsmooth (
integer,lower bound=0,default=5)- Number of smoothing iterations for specified zones.
surface
Refined surface extraction options:
surface:
extract:
surfaceGridFile:
bcFile:
surfaceBCNames:
zoneSpecific:
-
zones:
faces:
-
extract (
boolean,default=False)- Flag specifying whether to output the refine surfaces.
-
surfaceGridFile (
string,default="surface.x")- Name of the output refined surface file.
-
bcFile (
string(fileName),default="")- The boundary condition file used for surface extraction.
-
surfaceBCNames ([
string, ...],default=[""])- The name of the boundary conditions to extract to the surface file.
-
zoneSpecific
- Entries extract the listed block faces of the listed zones, in addition to the faces selected by surfaceBCNames.
-
zones ([
string, ...],default=["default"])- The zones containing non-physical BCs to extract.
-
faces ([
string, ...],default=["lLow"])- The faces to extract for each specified zone. Options are: 'jLow', 'jHigh', 'kLow', 'kHigh', 'lLow', 'lHigh'
Example YAML Input Files
Uniformly refine grid.in with a global factor of 2.0:
Refine all zones in every direction with a factor of 2.0, except zones 1-3 and 10, which are refined only in j and l:
refine:
factor : 2.0
coarseGridFile : grid.in
refineGridFile : refine.x
refineDirection : all
zoneSpecific:
-
zones: [1-3, 10]
refinedirection : jl
Comprehensive configuration with zone-specific smoothing and surface extraction:
refine:
factor : 1.4
tileSize : [18,10,10]
coarseGridFile : grid.in
refineGridFile : refine.x
refinedirection : all
smoothdirection : all
nsmooth : 10
writerecordmarkersingrids : false
zonespecific :
-
zones: [1-10]
nsmooth : 10
refinedirection : j
smoothdirection : j
surface:
extract: True
surfaceGridFile: surface.x
bcFile: grid.bc.in
surfaceBCNames: [wing,fuse,tail,fin]
Execution
Run the utility with an input configuration file (input.yaml):
With thread binding utilities (e.g., mbind.x):
2026 Overset Grid Symposium Tutorials
Overview
This material reflects the content presented by the LAVA team's tutorial during the 2026 Overset Grid Symposium. While intended as a follow-along for the in-person tutorial, this material is of value to new LAVA Curvilinear users as it showcases best-practices in how to think about gridding, scripting, solving on, and setting up optimization/design problems for an overset grid system.
The baseline geometry considered is the Common Research Model (CRM) used in Drag Prediction Workshop 6. The initial wing and horizontal tail are added to in later tutorials to exemplify available design/optimization techniques.
Tutorial Set
The larger OGS tutorial has been broken into piecemeal tutorials which are intended to be completed sequentially, taking outputted files from previous tutorials as a starting point. However, 'checkpoint' files are provided within each tutorial to allow the user to start from any point.
The tutorials, along with what the user should expect to take away from them, are as follows:
- Project Grid Scripting
- How to setup component-based scripted grid generation for a LAVA Curvilinear project.
- What to consider when preparing CAD geometry for gridding.
- Rules of thumb for surface grid generation with forethought towards LAVA gridding utilities.
- How to use the octFarfield executable to create a farField which can then be connected to script-generated nearBody grids.
- Connecting a Grid
- How to connect a built curvilinear overset grid.
- Strategies for removing orphans.
- Generating a Grid using EPOGS
- How to generate the required inputs for EPOGS, if preferred to or in support of scripted grid generation.
- Running Steady-State RANS
- How to compute a steady-state RANS solution.
- Conducting a Grid Refinement Study
- How to easily construct a refined mesh family with LAVA's 'Spline-and-Refine' tool.
- Performing Geometry Morphing
- How to set up a geometry morphing optimization (e.g. AOA-specific shapes for a wing).
- General use cases for the LAVA Geometry morphing tool.
- Performing Design Optimization
- Setup a design optimization problem (e.g. drag reduction on a wing.)
- Design limitations.
- Plugging into an external optimization framework (MDAO).
- Including Immersed Geometry
- Including immersed geometry to alleviate needless body-fitted gridding (for a set of flap track Fairings).
- Considerations/requirements when including immersed geometry.
CRM Project Tutorial Files
These ordered tutorials seek to emulate a bottom-up progression of a design research project on the CRM geometry. Thus, a LAVA best-practice project_OGS_CRM.tar.gz file system is provided in order to allow the user to follow along, and can be uncompressed with the following command.
tar -xzf project_OGS_CRM.tar.gz
These files and their tree organization will be elaborated upon in the following tutorials, but the number of the main/first tutorial they are discussed in is labeled with '[X]' after the file name.
project_OGS_CRM/
├── geom/
│ ├── masterCAD.igs [1]
│ ├── NEARBODY_REF.plt [1]
│ ├── CRM_EPOGS.stp.zip [3]
│ ├── fuse/
│ │ ├── FUSE_BODY.x [1]
│ │ ├── FUSE_NOSE.x [1]
│ │ ├── FUSE_REFSUR.i.tri [1]
│ │ └── FUSE_TRISURF.cgns.zip [7]
│ ├── wing/
│ │ ├── WING_WING.x [1]
│ │ ├── WING_CAP_LE.x [1]
│ │ ├── WING_CAP_OUT.x [1]
│ │ ├── WING_CAP_TE.x [1]
│ │ ├── WING_TRISURF.cgns [7]
│ │ └── WING_TRISURF.tri [7]
│ │── tail/
│ │ ├── TAIL_WING.x [1]
│ │ ├── TAIL_CAP.x [1]
│ │ ├── TAIL_REF.zip [1]
│ │ └── TAIL_TRISURF.cgns [7]
│ │── nacelle/
│ │ └── NACELLE_BODY.x [8]
│ └── pylon/
│ ├── PYLON_AFT.x [8]
│ ├── PYLON_NOSE.x [8]
│ ├── PYLON_CUSP.x [8]
│ └── immGeom_PYLON.i.tri [8]
├── parm/
│ └── makeParm.tcl [1]
├── fuse/
│ ├── fuse.tcl [1]
│ ├── fuse.BC.tcl [1]
│ └── fuse.cut.tcl [1]
├── wing/
│ ├── wing.tcl [1]
│ ├── wing.BC.tcl [1]
│ └── wing.cut.tcl [1]
├── tail/
│ ├── tail.tcl [1]
│ ├── tail.BC.tcl [1]
│ └── tail.cut.tcl [1]
├── nearBody_EPOGS/
│ ├── nearBody_EPOGS.tcl [3]
│ ├── nearBody_EPOGS.BC.tcl [3]
│ └── nearBody_EPOGS.cut.tcl [3]
├── nacelle/
│ ├── nacelle.tcl [8]
│ ├── nacelle.BC.tcl [8]
│ └── nacelle.cut.tcl [8]
├── pylon/
│ ├── pylon.tcl [8]
│ ├── pylon.BC.tcl [8]
│ └── pylon.cut.tcl [8]
├── envVars.sh [overview]
├── run_buildGrid.sh [1]
├── buildProjectGrid_nearBody.tcl [1]
├── init_connectivity.sh [2]
├── run_connectivity.sh [2]
├── run_buildGrid_EPOGS.sh [3]
├── buildProjectGrid_nearBody_EPOGS.tcl [3]
├── init_connectivity_EPOGS.sh [3]
├── init_RANS.sh [4]
├── run_RANS.sh [4]
├── run_refineGrid.sh [5]
├── init_morphing.sh [6]
├── run_morphing.sh [6]
├── init_design.sh [7]
├── run_design.sh [7]
├── run_buildGrid_immBnd.sh [8]
├── buildProjectGrid_nearBody_immBnd.tcl [8]
├── init_connectivity_immBnd.sh [8]
├── init_RANS_immBnd.sh [8]
├── auxFiles/
│ ├── LAVA_octFarField.yaml [1]
│ ├── LAVA_connectivity.yaml [2]
│ ├── LAVA_connectivity_sky_ele.pbs [2]
│ ├── LAVA_connectivity_EPOGS.yaml [3]
│ ├── LAVA_solver_RANS.yaml [4]
│ ├── LAVA_solver_RANS_athena.pbs [4]
│ ├── LAVA_refine.yaml [5]
│ ├── LAVA_morphing.py [6]
│ ├── LAVA_morphing_disp_aoa2p5.txt [6]
│ ├── LAVA_morphing_ea.txt [6]
│ ├── LAVA_morphing_rom_ait.pbs [6]
│ ├── LAVA_morphing_tur_ath.pbs [6]
│ ├── LAVA_design_fuse_wing_tail.py [7]
│ ├── LAVA_solver_design.yaml [7]
│ ├── LAVA_design_FFD_fuse.xyz [7]
│ ├── LAVA_design_FFD_tail.xyz [7]
│ ├── LAVA_design_FFD_wing.xyz [7]
│ ├── LAVA_design_rom_ait.pbs [7]
│ ├── LAVA_design_tur_ath.pbs [7]
│ ├── LAVA_design_postProc.py [7]
│ ├── LAVA_connectivity_immBnd.yaml [8]
│ └── LAVA_solver_RANS_immBnd.yaml [8]
└── run/
Note that the 'masterCAD.igs' file mentioned is not held under revision here due to size constraints, but can be downloaded here. You only need to do this if you want to attempt to reproduce the Project Grid Scripting tutorial (which is recommended for new users).
Prerequisites
If you intend to follow along with or re-produce the workflow described in this tutorial set, you will need to install/setup the following list of programs. The number(s) in [] brackets after the listing denote the tutorials that program is needed.
- Chimera Grid Tools (CGT) version 3.0 installed and accessible. [1, 3, 5, 8]
- Engineering Sketch Pad, which should be installed as 'part of' CGT. [3]
- the LAVA solver installed and accessible — see LAVA Installation
Guide (This tutorial uses
lavacurvas a proxy for the appropriate executable). [1-8] - access to computing resources such as NASA's High End Computing Capability for simulation replication - likely a PC will be insufficient. ['technically' none: effectively all]
- Python 3.9 or above installed. [6, 7]
- pyLAVA: see this documentation for information on setting up pyLAVA). [6, 7]
- numpy 2.0.2 installed. [6, 7]
- Python virtual Environment on NAS. [6, 7]
- The Python packages listed in the OpenMDAO-based Optimization Requirements. [7]
- SNOPT and pyOptSparse [7]
- pySurf installed. [7]
Warning
Due to the application of pygeo's DVGeoMulti class (installed when
pyLava is setup), tutorial 7 requires that the following issue be resolved
in your local installation of pygeo:
Additionally, you may need to downgrade your version of numpy to 1.26.4
due to pysurf.
Additionally, the following issues may need to be resolved in your local
installation of pysurf depending on your installation of CGNS:
Environmental Variables
There are several environmental variables needed for the programs/scripts in
these tutorials to run properly. They are all defined in the envVars.sh file
shown in the file system above, and seen below. Before proceeding to run the
OGS tutorial set be sure to set these variables appropriately.
# The location of the LAVACGTScriptFramework directory shipped with LAVA.
# On local compute this is likely where you shipped LAVA files are.
# For those with access, this will be available on NAS at /swbuild/LAVA/ as
# well once released.
# Used for tutorials which build with CGT scripting: 1, 3, 5, 8.
export LAVACGTToolsDir=path/to/shipped/LAVA/folder/LAVACGTScriptFramework
# e.g. ~/LAVA_v1.0.1_intel_openmpi_x86_64_2026.06.10/LAVACGTScriptFramework
# The location of the directory containing the shipped LAVA executables.
# Generally more important for local compute.
# Needed for tutorials running LAVA.
export LAVA_EXE_DIR=path/to/shipped/LAVA/folder/bin
# e.g. ~/LAVA_v1.0.1_intel_openmpi_x86_64_2026.06.10/bin
# Will be used for executable types (e.g. lavacurv.LAVA_EXE_SUFFIX),
# and to access libraries (e.g. liblavacurv.LAVA_EXE_SUFFIX.so).
# On local compute this tells the executable build type you want to use.
# On NAS, pbs scripts in these tutorials will set this appropriately.
# For python-driven design and optimization (tutorials 6 and 7),
# this variable is commonly expected internally.
export LAVA_EXE_SUFFIX=3D.NS1.AVX2
# The location of the directory containing the shipped LAVA dynamic libraries.
# If you will be running on NAS, this can be set to `none'.
# If set to `none`, it will be assumed that the path has been included in the
# `LD_LIBRARY_PATH` environment variable.
# For python-driven design and optimization (tutorials 6 and 7),
# this variable is commonly expected internally.
export LAVA_LIB_DNY=path/to/shipped/LAVA/folder/lib
# e.g. ~/LAVA_v1.0.1_intel_openmpi_x86_64_2026.06.10/lib
# The number of threads needed to run threaded executables.
# This is only needed for running on your local machine: thread counts in NAS
# pbs scripts are as per the node being requested.
export OMP_NUM_THREADS=50
# The number of procs to run the LAVA_EXE_CURV solver with.
# Only relevant if running on a local compute environment with pbs scripts;
# on NAS, pbs scripts will inherently define this.
export N_PROC=1
# The charge group number needed for NAS pbs job submission scripts.
export GROUP_ID='<your_group_ID>'
# The python version you are running with.
# Currently only matters for tutorial 7 for certain compute node types.
PYTHON_VERSION=3.11
# Path to python virtual environment that contains required Python packages
# and the bin/activate file.
# The user is responsible for making this virtual environment.
# Needed for running tutorials 6 and 7 on NAS.
export PY_VIRTUALENV_DIR=your/path/to/virtual_env/bin/activate
# e.g. ~/.venv/pyLAVA/bin/activate
Calling Run Scripts
Many of the tutorials are designed to exemplify how to setup best-practice
scripting of a LAVA project. There are several init_* run_* script files
within the project's base directory (project_OGS_CRM) to this effect. When
building a specific case for a project modularity is the key: a sub-folder is
made within the run directory, FROM WHICH THE INIT_* AND RUN_* SCRIPS ARE
CALLED: e.g. if you are in the run/myCase directory and want to build the
grid as described in tutorial 1, your command line call should be
../../run_buildGrid.sh.
Macos
Note that the run/init_*.sh scripts are primarily designed for linux. If
you are running on macOS, you may need to adjust the sed commands.
Case 'Mirroring' on a Local and NAS/compute Environment
Some tutorials are small enough to be run on a local workstation while others
ask for the solver to be MPI-run in a NAS compute environment. For projects, it
is useful to have a 'mirrored' setup on both the compute and local workstation
environments for accounting ease and script simplicity. We recommend copying
and unzipping the provided project_OGS_CRM folder into both locations.
Similarly, if you are building grids on local compute and running the solver or
other utilities on NAS compute, keep the same run/ sub folder tree so transfers
become less confusing.
Project Grid Scripting
Overset gridding can be a powerful design tool because it is easy to leverage component-based buildup by gridding said components individually, altering a base set of grids efficiently, and tailor grids minutely to the requirements of problem numerics. While automated methods such as EPOGS exist, it is often still required to partially or fully script curvilinear overset grid generation for specific method requirements or grid sensitivities.
The LAVA best practices for setting up a project's grid scripting file system will be described in this tutorial. The CAD and surface grid choices made will be discussed, and the scripts to generate the volume grids overviewed. CGT is used for scripted grid generation. In the next tutorial, we will also be using an automated POGS approach to generate the volume grids for comparison, as they are sufficient for RANS analysis.
The final result of constructing a grid with a scripted project is the grid and bc files needed for subsequent tutorials. If you cannot or do not want to run this tutorial yourself, they can be downloaded here:
- grid.x: The combined CRM nearBody and octree-generated farField volume grid without iblanks.
- grid.sur: The CRM nearBody surface grids relevant to integrated loads.
- grid.bc: The combined CRM nearBody and octree-generated farField BCs.
LAVA Curvilinear Overset Project Grid Script File System
Before actually going through the process of CAD manipulation and grid generation we will discuss the scripting framework and process in which we are working. An abstract representation of a scripted project can be seen below with rough steps.
A Project requires three starting files:
- A parameter file located in a parm directory which contains information that controls how the other grid-related scripts function. Values relating to min/max allowed grid spacings, first-cell height, AOA, grid movement parameters, refinement level, etc., are held here and referenced by other files.
- A master CAD geometry located in a geom directory. This will be divided into different 'floating' component CAD files according to user preference which will be held in their own sub-directories.
- A master build script which sets which components will be built for a grid system. This script will be called in a 'run' sub directory and will sequentially look at the grid-building scripts of the relevant components.
In addition, each component will have its own directory in which its grid scripts are held, which copy and manipulate on-CAD surface grids built and held in the component's sub-directory.
The process of constructing a scripted project is usually performed in the following steps:
- Break the master CAD file into components. Usually the master CAD undergoes some cleanup first to fill gaps or remove other issues. When sectioning off a component, things to consider are how much CAD on another touching component to include for blending grids, and if gaps should be filled to create a closed geometry if cutter triangulations need to be made. Additionally, depending on your grid generation method cutting the CAD along the lines you wish your grid to follow may be beneficial.
- Export from CAD to get surface geometry (usually igs or step format) on which to build surface grids. If you want to define manual cutter triangulations from the CAD you should also export those, though often you will not realize you need them until you see issues during connectivity later.
- Build the surface grids on the geometry using a tool of choice, and then export them into plot3D format. Depending on your gridding method, you may export triangulations instead on which surface grids can be grown, e.g. via CGT scripting. How you choose to build/export your surfaces comes down to how you want to script their volume construction, and so is driven by personal preference. Depending on preference, you can export multiple sets of surface grids at various refinement levels here, if they can be refined on the CAD, or, as is done in this tutorial, perform refinement on the entire grid system later with an appropriate tool. Note that if you have a method or reason to manually build the volume grids (e.g. for wake grids) you can just build and export them here as well.
- Write the components' grid scripts. There are usually three scripts:
- Grid script: copies each surface grid from the component geometry sub-directory, then manipulates it and builds its volume grids. The settings of the volume construction are gleaned from the parameter file. Note that volume grids built in the geom sub-directory can just be copied in by this script, but they may still be manipulated depending on your parameter settings (pitch/yaw, etc) or tiling (e.g. the vanes of a wind tunnel).
- BC script: defines the BCs for each volume side built in the grid script. Each of the six sides can have partial BCs on them. If a portion or whole side doesn't have a BC, a block-to-block (B2B) with another volume will be attempted to be found later. If none is found, the side is assumed to be overset. Note that each volume side must either be completely covered with BCs and/or B2Bs OR be entirely overset.
- Cutter script: if manual cutters triangulations have been created in the component geometry sub-directory, they are copied in here and manipulated based on the parameter file (pitch, yaw, etc).
- Build a grid system: by making a sub-directory to run in, naming it after the desired parameters set in the parameter script and the components defined in the master build script. The master script is then run from within the run sub-directory. The grids and cutters built from the component scripts called are all built within the run sub-directory. Additionally, auxiliary data may be built such as yaml input files if scripts are set up to generate them. If this script is ever re-run and a component's scripts or volume grid exist and haven't been modified, that component won't be re-built.
Building the CRM Project NearBody Grid
To build the starting nearBody CRM project grid, you would simply make a new sub-folder in the 'run' directory (e.g. 'RANS'), then run the 'buildProjectGrid_nearBody.tcl' while in that folder (do not copy it in). However, do not do so yet: we will be building the entire grid system later including the offBody with a separate wrapping script.
While the CRM components' surface grids and scripts are provided in order to build the full grid while following this tutorial, the broken-up portions of the master CAD for each component are not (though they are visualized and discussed below). It is highly recommended that new users attempt this process from scratch to become familiar with CGT grid scripting and the thought process behind how to break up CAD and build surfaces with volume grid generation in mind. An example of this may be first attempting to re-create the surface grids provided, then trying different surface grid topologies.
Master and Component CAD
Some forethought should be put into cleaning up the master CAD file and breaking it into component CAD so that building surface grids on them is easier:
- Ensure that the CAD is properly segmented between features, cutting it if not.
- Ensure that no undesired open edges exist and that any spurious/sliver features are removed/repaired.
- Similarly, cut the CAD to ensure feature lines you want respected are explicitly known.
- It may be easier to pre-define the limits of particular surface grids by cutting out CAD surfaces in their final shape. Multiple of these CAD surfaces can overlap and be held in the same CAD component file.
- After cutting out a portion of the master CAD for a component, you may need to fill holes in that component to have a closed surface on which to grow the grid. This matter especially if you will be conducting a component build-up.
The cleaned master CAD file is shown below. Note that extra cuts have been added near the wing and tail caps to allow for ease of cap CAD separation.
Fuse Component
The fuse component has been cut out into two pieces which will become their own surfaces grids: the main body which has the holes left by the tail and wing removal filled, and the cap. Note that many of the extra lines of the master CAD have been removed. The only cuts which exist on the main body are those delineating curvature changes to allow for appropriate clustering. The nose has been inscribed with a square on the CAD instead of being drawn or grown on to simplify the surface definition. The fuse volumes have been grown out such that they adhere to the symmetry plane of the case.
Lets take a look the portion of the 'fuse.tcl' script responsible for generating these volumes:
73 # Use incremental building procedures (IBP).
74 # --------
75 IBP_initIncVars
76 # --------
77
78 # The fuse body is grown along the symm plane except where it overlaps
79 # with the nose.
80 # --------
81 puts "\tBuilding fuse body ..."
82 # --------
83 IBP_incVol
84 # --------
85 GenHypVolGrid FUSE_BODY.x v.[IBP_nVol] \
86 [list \
87 hyptan \
88 specsr \
89 $Par(sr) \
90 $Par(md) \
91 $Par(ds,wall) \
92 $Par(ds,glb) \
93 $Par(klayer) \
94 ] \
95 [list -10 2 2 2] \
96 [list 1.5 150 3]
97 # --------
98 IBP_extractBlkSurs v.[IBP_nVol] [list +L]
99 # --------
100
101 # The nose has one side on the symm plane.
102 # --------
103 puts "\tBuilding fuse nose ..."
104 # --------
105 IBP_incVol
106 # --------
107 GenHypVolGrid FUSE_NOSE.x v.[IBP_nVol] \
108 [list \
109 hyptan \
110 specsr \
111 $Par(sr) \
112 $Par(md) \
113 $Par(ds,wall) \
114 $Par(ds,glb) \
115 $Par(klayer)\
116 ] \
117 [list -10 -10 2 -10] \
118 [list 1.5 150 3]
119 # --------
120 IBP_extractBlkSurs v.[IBP_nVol] [list +L]
121 # --------
122
123 # Group the component meshes into surfaces and volumes.
124 # --------
125 IBP_combineGrids $fileN
126 # --------
The methodology for clean grid accounting utilized is 'incremental': the
surfaces and volumes are counted as new grids are made and then later combined,
such that only s.* (surface) and v.* (volume) files are created. They can
then later be deleted as a set without worry. IBP_initIncVars on line 75
instantiates the surface and volume counts. When a finished volume is created,
the volume count is first incremented (line 83), and then accessed through
[IBP_nVol] (line 85). The Par growth parameters of the volume are set in
MakeParm.tcl.
After each volume is created the sides of its block which are BCs are extracted
using IBP_extractBlkSurs on line 98 which takes a list of sides (+ being the
J, K, or L 1 side and - being the max side) and increments the surface count as
they are extracted. After all grids are built, the volumes and surfaces up to
the known count are combined on line 125.
You will see that the BC scripts use a similar method. The advantages of this
incremental style of building become more apparent when we look at more
complicated components such as the wing below, and also allow for extra grids
to be added in the middle of a script down the line without having to edit all
the variables below them. Below is an excerpt from fuse.BC.tcl in which the
following BC-addition functionality defined in
$LAVACGTToolsDir/AddBCInfoProcs.tcl is utilized for the body:
AddWallBCInfo $fileN [IBP_nVol] [list +L] "fuse"
AddWallBCInfo $fileN [IBP_nVol] [list -J +K -K] "symm"
The AddWallBCInfo simply takes a grid index in the component and a list of
block sides and applies a BC name to it. The first says that the lMin side of
the fuse body is named 'fuse', while the jMax, kMin and kMax sides are
named 'symm'. We are not actually assigning BC types here for LAVA, only names:
the LAVA BC types are assigned in the yamls. There are delineations between
AddWall/Outlet/Etc/BCInfo proc calls in $LAVACGTToolsDir/AddBCInfoProcs.tcl
because a different file (bcmain.dat) is written by the master build script
which can be read into OVERGRID to visualize BCs, and that file needs to know
BC type.
Wing Component
The wing component consists of two overlapped CAD cutouts of the wing and its cap. The surface grids of the wing are pre-divided at feature lines that should be retained during the refinement procedure in a later tutorial. The Cap has a small surface at the trailing edge (TE) which is point-matched with the surfaces which loop around the cap tip.
Unlike the fuse, the wing has sharp feature lines which must be retained for the spline-and-refine procedures in a later tutorial. Thus, surface grids which are initially divided across feature lines are first interrogated for sizing, combined, and then grown out into a single volume which is re-divided. Doing this measurement within the scripts instead of hard-coding volume splitting numbers means that the surface grids can be freely altered and the grid scripts will still function as intended.
The junction between the wing and fuse is a collar constructed using the following code. A curve (denoted as c.*) extracted from the wing is projected onto the fuse, then grown onto it (lines 126-134). A portion of the wing surface is extracted and combined with the surface grown on the fuse (lines 135-138). A volume is generated and subsequently divided into 6 pieces.
The wing.tcl grid script better showcases the utility of incremental
building. The [IBP_nSurP 2] call on line 128 returns a number 2 higher than
the current surface count, preventing the user from accidentally overwriting a
previously made surface. The volume constructed in line 139 calls [IBP_nVolP
7], to give room for the six feature line-respecting volumes which are
subsequently extracted from it. While the collar is built first in this script,
this code chunk could technically be pasted anywhere in the file and it would
still function as intended. This same strategy is used for the wing itself.
126 ExtractSubs WING_WING.x c.1 [list 1 1 -1 1 1 1 1]
127 Project c.1 fuse.sur dummy c.2 [list -1] [list 1] [list 1 n 0 0 1]
128 GenHypSurGrids fuse.sur c.2 s.[IBP_nSurP 2] 1 1 \
129 [list \
130 -1 \
131 [list 10 10] \
132 [list 25 0 0.05 0.000263 0.0] \
133 [list 0.5 20] \
134 ]
135 SwapInd s.[IBP_nSurP 2] s.[IBP_nSurP 1] [list revj revk]
136 ExtractSubs WING_WING.x s.[IBP_nSurP 2] \
137 [list 1 1 -1 2 [expr $wingColEndK + $Par(np,hlfOrlp)] 1 1]
138 ConcatGridsn [list s.[IBP_nSurP 1] s.[IBP_nSurP 2]] s.[IBP_nSurP 3] k 0
139 GenHypVolGrid s.[IBP_nSurP 3] v.[IBP_nVolP 7] \
140 [list \
141 hyptan \
142 specsr \
143 $Par(sr) \
144 $Par(md) \
145 $Par(ds,wall) \
146 $Par(ds,glb) \
147 $Par(klayer)\
148 ] \
149 [list 10 10 -20 -20] \
150 [list 1.5 250 3]
The cap grids of the wing demonstrate one strategy to create a set of grids at the TE which are well-aligned with flow coming off the wing. As shown on lines 293-298 below, a copy of the small TE cap grid is translated aft of the wing, connected to the one still on the wing TE, and then re-distributed to generate a volume grid which matches the spacing of the other cap grids on the wing surface in the stream-wise direction.
293 IBP_incVol
294 # --------
295 GedTranslate WING_CAP_TE.x s.[IBP_nSurP 1] $teTx $teTy $teTz
296 ConcatGridsn [list WING_CAP_TE.x s.[IBP_nSurP 1]] v.[IBP_nVolP 1] l 0
297 SrapRedist v.[IBP_nVolP 1] v.[IBP_nVol] 1 l 1 2 0 \
298 [list 1 -1 $Par(sr) $teDs 0.0]
The surfaces of this cap TE volume are then extracted and combined with those cap surfaces on the wing abutting the TE (lines 315-323). The combined surface is then grown as one volume which will subsequently be re-divided to six volumes which respect the TE feature lines as was done with the wing and collar before (lines 324-335).
315 ExtractSubs v.[IBP_nVol] s.[IBP_nSurP 2] [list 1 1 -1 1 1 1 -1]
316 SwapInd s.[IBP_nSurP 2] s.[IBP_nSurP 1] [list swaplk swapjk revk]
317 ExtractSubs v.[IBP_nVol] s.[IBP_nSurP 3] [list 1 1 1 1 -1 1 -1]
318 SwapInd s.[IBP_nSurP 3] s.[IBP_nSurP 2] [list swaplj]
319 ExtractSubs v.[IBP_nVol] s.[IBP_nSurP 4] [list 1 1 -1 -1 -1 1 -1]
320 SwapInd s.[IBP_nSurP 4] s.[IBP_nSurP 3] [list swaplk swapjk]
321 ConcatGridsn [list s.[IBP_nSurP 1] s.[IBP_nSurP 2] s.[IBP_nSurP 3]] \
322 s.[IBP_nSurP 4] k 1
323 ConcatGridsn [list WING_CAP_OUT.x s.[IBP_nSurP 4]] s.[IBP_nSurP 1] j 1
324 GenHypVolGrid s.[IBP_nSurP 1] v.[IBP_nVolP 7] \
325 [list \
326 hyptan \
327 specsr \
328 $Par(sr) \
329 $Par(md) \
330 $Par(ds,wall) \
331 $Par(ds,glb) \
332 $Par(klayer) \
333 ] \
334 [list -10 -1 -5 -5] \
335 [list 1.5 150 3]
Tail Component
The tail component uses the same methodology as the wing for its collar with the fuse and its body. Its cap, however, showcases a different construction method.
The tail cap surfaces are initially defined on outer mould lines of the cap
only, and not on the wing itself. The cap surfaces were initially divided into
leading, outer, and trailing edges, but were measured and combined at the start
of the tail.tcl script. The curve of the combined grid on the tail top is
extracted, projected onto a triangular surface representing the local tail, and
then grown along it (lines 267-277). The same is then done for the tail bottom
(lines 281-290). Finally, the grids are combined and grown as one volume, which
will be subsequently split into the 9 volumes shown above (lines 293-306).
267 ExtractSubs TAIL_CAP.x c.2 [list 1 1 -1 1 1 1 -1]
268 ReverseInd c.2 c.1 [list revj]
269 Project c.1 TAIL_REF.i.tri dummy c.2 [list -1] [list -1] \
270 [list 1 n 0 0 1]
271 GenHypSurGrids TAIL_REF.i.tri c.2 s.[IBP_nSurP 2] 1 1 \
272 [list \
273 1 \
274 [list -1 -20] \
275 [list 25 0 0.01 0.0002 0.0] \
276 [list 5.0 150 0.0 3] \
277 ]
278 ReverseInd s.[IBP_nSurP 2] s.[IBP_nSurP 1] [list revj revk]
279 set nKCapTop [lindex [GetDim s.[IBP_nSurP 1] 1] 1]
280 # --------
281 ExtractSubs TAIL_CAP.x c.1 [list 1 1 -1 -1 -1 1 -1]
282 Project c.1 TAIL_REF.i.tri dummy c.2 [list -1] [list -1] \
283 [list 1 n 0 0 1]
284 GenHypSurGrids TAIL_REF.i.tri c.2 s.[IBP_nSurP 2] 1 1 \
285 [list \
286 1 \
287 [list -1 -20] \
288 [list 25 0 0.01 0.0002 0.0] \
289 [list 5.0 150 0.0 3] \
290 ]
291 set nKCapBot [lindex [GetDim s.[IBP_nSurP 2] 1] 1]
292 # --------
293 ConcatGridsn [list s.[IBP_nSurP 1] TAIL_CAP.x s.[IBP_nSurP 2]] \
294 s.[IBP_nSurP 3] k 1
295 GenHypVolGrid s.[IBP_nSurP 3] v.[IBP_nVolP 10] \
296 [list \
297 hyptan \
298 specsr \
299 $Par(sr) \
300 $Par(md) \
301 $Par(ds,wall) \
302 $Par(ds,glb) \
303 $Par(klayer) \
304 ] \
305 [list -20 -20 -20 -20] \
306 [list 0.5 5 1]
Building the CRM Project Grid
You will note that the grid.* files constructed with
buildProjectGrid_nearBody.tcl do not constitute a closed computational
domain, i.e. a far-field or off-body grid set doesn't exist. While there are
ways to create such far-field grids using CGT scripting, LAVA provides an
octFarfield executable which makes a size-efficient resolution-telescoping
Cartesian box-grid set given a closed surface triangulation to target as the
smallest telescoped grid level. The triangulated surface generated from the
masterCAD.igs file (NEARBODY_REF.plt) which will be used is shown below.
Using this executable is not possible within the CGT scripting framework
described above, as it should be threaded and has its own input yaml file.
Thus, to conjoin the nearBody scripting-generation method and offBody
exe-generation method we utilize the run_buildGrid.sh bash script, shown
below. Remember to properly set the LAVACGTToolsDir, LAVA_EXE_DIR,
LAVA_EXE_SUFFIX, and OMP_NUM_THREADS environmental variables in
envVars.sh first.
# Build the nearBody grid using the normal project build script.
# By default the grid is built to grid.in: renaming here is just preference
# becuase we will be combining this grid with the exe-generated farField grid.
# ---------------------------------------------------------------------------- #
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
$baseDir/buildProjectGrid_nearBody.tcl
mv -f grid.in nearBodyGrid.x
mv -f grid.bc.in nearBodyGrid.bc
mv -f grid.sur nearBodyGrid.sur
mv -f grid.b2b nearBodyGrid.b2b
mv -f bcmain.dat nearBodyGrid.bcmain.dat
rm -f gridnames.txt
# ---------------------------------------------------------------------------- #
# Build the farField using the octFarfield exe.
# First copy over the input script and the surface representation it requires
# as a starting point.
# ---------------------------------------------------------------------------- #
cp $baseDir/geom/NEARBODY_REF.plt .
cp $baseDir/auxFiles/LAVA_octFarField.yaml .
$LAVA_EXE_DIR/octFarfield.$LAVA_EXE_SUFFIX LAVA_octFarField.yaml
rm NEARBODY_REF.plt LAVA_octFarField.yaml check.plt farFieldGrid.x.cart
# ---------------------------------------------------------------------------- #
# use the mergeGrids exe guild combine the nearBody and farField -> final grid.
# The 'surface' grid is defined simply as the nearbody surface grid.
# ---------------------------------------------------------------------------- #
$LAVA_EXE_DIR/mergeGrids.$LAVA_EXE_SUFFIX nearBodyGrid.x farFieldGrid.x grid.x
cp -f nearBodyGrid.sur grid.sur
# ---------------------------------------------------------------------------- #
The nearBody CGT generation master script buildProjectGrid_nearBody.tcl is
called first. The offBody generation is conducted next after the appropriate
files needed by the executable are copied over. Finally, the two grids and
their BCs are combined. The LAVA_octFarField.yaml far-field generation input
file is shown below. dx determines the grid spacing in [m] which should
encompass the nearBody triangulation. cubeLength determines the total size of
the far-field limits, which is adjusted by how many times the farField is
expected to telescope its grid resolution (nRefine). The symmetry plane has
been enforced in the outerBCs. More information on the octFarField yaml
arguments can be found in the curvilinear documentation.
octFarField:
inputType : surface
inputFileType : tecplot
inputFile : NEARBODY_REF.plt
externalFlow : True
dx : 0.006
ymin : 0.0
cubeLength : 200.0
outerBCs : [far, far, symm, far, far, far]
nRefine : 16
nCellBuffer : 24
nbuffer : 0
usenearbodycoarsening : False
outputName : farFieldGrid
includeoverlap : True
The resulting files are grid.x and grid.bc, which are the required input to
the connectivity process discussed in the next tutorial. Views of the
farFieldGrid.x and zoomed-in grid.x are shown below.
The nearBody grid has 40 grids and ~125 million nodes, while the farField grid has 161 grids and ~118 million nodes, for a combined set of 201 grids with ~243 million nodes.
Connecting a Grid
Overset grids need to have their non-BC, or fringe, block sides interpolate from other overlapping block cells (donors) which aren't themselves near a fringe. The connectivity task within the LAVA curvilinear solver handles this donor interpolation calculation, along with many other useful data such as portions of the grid which can be blanked (removed) because of redundant overlapping of grids. Its manual can be found in the curvilinear documentation, and contains an overview of overset grid requirements, walkthrough of the connectivity process for user understanding, overview of connectivity's options in the context of the connectivity process, and a trouble-shooting section to help remove orphans (fringe nodes which can't find a donor).
To run this tutorial yourself the project grid scripting
tutorial must first be completed to generate
the grid.x and grid.bc files required as input to connectivity, or they can
be downloaded directly from that tutorial. Here we will be using the
connectivity pre-processing task to generate the following files, which can
also be directly downloaded by clicking on them here in case you can't or don't
want to run this tutorial:
- grid.x.ihc : the grid with blanking included.
- INTOUT : the fringe/donor interpolation information.
- grid.x.b2b : the block-to-block information if non-BC block faces are incident instead of overlapping.
- panel_weights.dat
: the fractional weights of each wall-surface face on the geometry which
determines its contribution to integrated values (such as loads). Note that
if you download this, put it into a subdirectory named
overlapper.
The b2b file will be calculated using the B2BExtractor utility which can be optionally triggered as a LAVA curvilinear input yaml entry, while the panel weights will be found using LAVA's overlapper utility.
Perform Connectivity
Before running connectivity, copy over and alter the needed files by running
the init_connectivity.sh script from the case directory created in the
project grid scripting tutorial.
To run the connectivity process on the grid on a local environment, run the
run_connectivity.sh script from the case directory created in the project
grid scripting tutorial to call the curvilinear solver executable you have
pointed to by appropriately defining LAVA_EXE_DIR, LAVA_EXE_SUFFIX, and
OMP_NUM_THREADS in the envVars.sh file. Running connectivity with 55
threads takes roughly 5.5 seconds with this grid, which has zero orphans.
To run connectivity on the NAS environment, submit the
LAVA_connectivity_sky_ele.pbs job. Remember to ensure your charge GROUP_ID
is properly set in the envVars.sh file before calling init_connectivity.sh
above. If you did not build your grid on the NAS system, remember to copy the
grid.x, grid.bc, LAVA_connectivity.yaml, and
LAVA_connectivity_sky_ele.pbs files into an appropriate folder on NAS and
submit the PBS script.
Input File
The connectivity yaml file is shown below. The B2B generation has been declared
using the B2BExtractor functionality. The BCs are defined with a location,
which can be onBody or offBody. Connectivity will use this information to
understand which BCs should be interpreted as part of the closed body; the
fuse, wing and tail for this case.
grid :
curv :
gridFile : grid.x
bcfile : grid.bc
fileType : plot3d
curvSolver :
task : connectivity
B2BExtractor :
extractB2Bs : true
overset :
zoneSpecific:
-
# All non-nose or collar near-body zones.
zones : [1,9-22,29-40]
priority : 100.0
-
# All nose and collar near-body zones.
zones : [2,3-8,23-28]
priority : 1000.0
bc :
-
names : [fuse,wing,tail]
type : BCWallViscous
location : onbody
-
names : [symm]
type : BCSymmetryPlane
location : offbody
symplaneorigin : [0.0, 0.0, 0.0]
symplanenormal : [0.0, 1.0, 0.0]
projectnodes : true
-
names : [far]
type : BCfarfield
location : offbody
Output
The implicit hole cutting routines handle all geometry IO blanking well for this geometry's grid, without any user-required intervention to remove ambiguity. If portions of the geometry were disappearing or orphans existed, it may have been necessary to employ explicit hole cutters (EHCs). If simple geometry shapes were desired they can simply be put into the yaml above. As per the discussions in the project grid scripting tutorial, more component-specific cutters should be defined in that component's geom subdirectory, and then copied in and appropriately manipulated for build parameters such as yaw, etc, within the *.cut.tcl script of that component. They would then be utilized in the connectivity yaml and assigned what grids to cut by how much. For most grids no such manual intervention is required: see the connectivity manual for a larger discussion on solving orphan-related issues.
You will also note that a smallGapDetectionInfo.txt file was written. The
surface geometry must be resolved by the octree for IO testing. If the octree
is too coarse then IO tests may not be trustworthy, and this written file
states how fine the octree levels would need to be for each grid to be
completely resolved. In the case where many orphans are appearing in certain
grids, you may want to use this to identify a more reasonable octree resolution
to be assigned locally. Otherwise, it can be ignored.
Grid Priorities
The yaml above also has a set of zone-specific commands which increase the
priority for different sets of nearbody grids. This value increases the seen
quality of those grids' nodes, forcing them to exist where other, smaller
cells would normally overtake them. Below are a series of figures with the
priority assignment removed from the yaml on the left, and included on the
right. The purpose of assigning these priorities is mainly to force the collar
grids to be retained, thus getting more consistent hole cuts with increasing
mesh resolution. You will note that the priorities do not affect how far the
nearbody grids overlap with the far-field grids: the size of the far-field cell
size local to the body in conjunction with the distance the nearbody grids are
grown out turns out to require the full nearbody grid necessary pretty much
everywhere and thus its retraction is insensitive to priority. This will change
for refined grids where more overlap exists.
Utilizing EPOGS
EPOGS is a new automated curvilinear overset grid generation software developed by NASA. We will use it in this tutorial to generate a nearbody grid commensurate with that just created in the prior scripting tutorial, then generate a far-field using LAVA's octFarField utility and connect the grid using LAVA's connectivity task.
The 'from-scratch' EPOGS gridding process involves first running the egads2srf
and then pogs CGT executables, stopping them at checkpoints, reviewing certain
files for issues, then potentially creating new files or altering existing ones
to tweak values before continuing from each checkpoint. This process is well
tutorialized within CGT 3.0 and will not be discussed here in depth: the
presented scripted application of EPOGS within this tutorial's CRM project
directory structure exemplifies how to include EPOGS once this checkpoint
process has been undergone and all settings/files have been properly set/built.
egads2srf requires a 'solid' CAD geometry as an input, which involves taking
an existing geometry file and processing it correctly within applicable CAD
software. A solid version of the CRM body-wing-tail geometry has been provided
in the geom directory. Eventually, surface grids will be grown on each face of
this solid, as well as from each of its edges and on each of its nodes. Thus, a
solid with the fewest faces is preferable.
The calls to egads2srf and pogs are within a nearBody_EPOGS component
script directory, and have settings which were pre-determined to work as
desired. Thus, the actual building of the grid will seem very similar to the
scripted version on the surface.
Building the CRM Project Grid with an EPOGS Near-body
To build the starting nearBody CRM project grid, simply make a new sub-folder
in the 'run' directory (e.g. 'RANS'), then run the run_buildGrid_EPOGS.sh
script from within that folder. This file is shown below. Remember to properly
set the LAVACGTToolsDir, LAVA_EXE_DIR, LAVA_EXE_SUFFIX, and
OMP_NUM_THREADS environmental variables in envVars.sh first.
This run script first calls a nearbody grid generation script in the same form as the scripting tutorial within which the EPOGS method is employed to generate the nearbody component. Then the farField is generated and the two are combined.
# Run egads2srf and pogs, and write its BC file in LAVA format,
# housed within the component script format.
# ---------------------------------------------------------------------------- #
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
$baseDir/buildProjectGrid_nearBody_EPOGS.tcl
mv -f grid.in nearBodyGrid.x
mv -f grid.sur nearBodyGrid.sur
mv -f grid.bc.in nearBodyGrid.bc
# ---------------------------------------------------------------------------- #
# Build the farField using the octFarfield exe.
# First copy over the input script and the surface representation it requires
# as a starting point.
# ---------------------------------------------------------------------------- #
cp $baseDir/geom/NEARBODY_REF.plt .
cp $baseDir/auxFiles/LAVA_octFarField.yaml .
$LAVA_EXE_DIR/octFarfield.$LAVA_EXE_SUFFIX LAVA_octFarField.yaml
rm NEARBODY_REF.plt LAVA_octFarField.yaml check.plt farFieldGrid.x.cart \
octFarfield.dat
# ---------------------------------------------------------------------------- #
# use the mergeGrids exe guild combine the nearBody and farField -> final grid.
# ---------------------------------------------------------------------------- #
$LAVA_EXE_DIR/mergeGrids.$LAVA_EXE_SUFFIX nearBodyGrid.x farFieldGrid.x grid.x
cp -f nearBodyGrid.sur grid.sur
# ---------------------------------------------------------------------------- #
Let's look at the main nearbody_EPOGS component grid script. Below is a portion
of the main nearbody_EPOGS.tcl script which calls the egads2srf exe.
CRM_EPOGS.stp is the solid geometry file. The first two arguments state that
y plane symmetry exists, and that face 22 should be removed: if egads2srf was
to be check-pointed part way through and inspected, there would be 21 on-body
surface faces, and one in-body symmetry plane face to close the half-fuse which
must be removed. The maxsr and dswall growth parameters are set to be the
same as the scripted grids. maxa, maxe and maxc are geometric parameters
used to identify what edges are 'small' (in this case tag trailing edges), and
npmin is set to be the number of points on those small edges (matching the
scripted grid trailing edges). stenqual is setting the fringe interpolation
requirement to be the same as LAVACurv's.
104 exec egads2srf -i CRM_EPOGS.stp \
105 -isym 2 \
106 -frm 22 \
107 -maxa 4.0 \
108 -maxe 0.5 \
109 -maxc 0.002 \
110 -maxsr $Par(sr) \
111 -npmin 25 \
112 -dswall $Par(ds,wall) \
113 -stenqual 1.0 \
114 > egads2srf.out
After the surface has been assessed pogs can be run as shown below. Due to
known bug in 3.0, this is performed in two steps, first writing out the surface
grids and then restarting from them to grow the volumes. The input file
CRM_EPOGS.001.pogs.i is an output from egads2srf. frc asks to reconstruct
the upper and lower tail surface. A figure of the initial tail face grids is
also shown below. The distribution of the surfaces doesn't align well with the
fuse, and so the intersection of the tail and fuse is used as a guideline to
re-make it.
122 exec pogs -frc 19,20 \
123 -arcse 0.15 \
124 -klayer $Par(klayer) \
125 -stop go.sur \
126 < CRM_EPOGS.001.pogs.i \
127 > pogs.surfGen.out
.
.
.
131 exec pogs -frc 19,20 \
132 -arcse 0.15 \
133 -klayer $Par(klayer) \
134 -start volgen \
135 -stop nb.vol \
136 < CRM_EPOGS.001.pogs.i \
137 > pogs.surfRst.out
After the surface and volume grids are built, they are scaled (the input solid geometry was in inches and LAVA needs meters) and renamed.
143 GedAddRemoveIB nb.vol nb.vol.clean 0
144 GedScale nb.vol.clean $fileN.vol 0.0254
145 GedScale go.sur $fileN.sur 0.0254
No manually-generated cutters are required, but the BC file must still be
written. pogs outputs a generic bc file in LAVA format without component names,
but also outputs a fomoco.i file which has proper BC information. Eventually,
this functionality will be corrected, but for now the appropriate BCs have been
transcribed into nearbody_EPOGS.BC.tcl.
The EPOGS nearbody grid is shown below, and consists of 78 grids and ~226 million nodes compared to the 40 and ~125 millions nodes manually scripted. The farField grid is the same as the scripted case, resulting in a combined set of 239 grids with ~344 million nodes.
Running Connectivity
To run connectivity, follow the instructions in the connectivity tutorial,
keeping in mind that you must use the init_connectivity_EPOGS.sh script
instead of init_connectivity.sh. Running connectivity with 55 threads takes
roughly 13.3 seconds for this case.
The main addition to the LAVA_connectivity_EPOGS.yaml file copied in and
renamed is a symmetry plane explicit cutter (shown below) which states that all
nodes below the y=0 plane should be blanked. This is needed for this case
because several of the pogs generated grids grow past this plane, i.e.
outside the computational domain. Feel free to comment this cutter, re-run
connectivity, and see where they arise.
As shown in the final, connected grid below as black dots, there are 9502
orphans in the final grid. These stem from a lack of proper overlap of surface
grids and/or volume growth splay. Current work on EPOGS seeks to remedy reasons
such orphans can occur. The current strategy to fix these orphans would be to
pop out and script alterations to specific grids within grid.x, insert them
back in, and then re-run connectivity. This process has not been undergone for
this tutorial, but is documented in the CGT 3.0 tutorials. This grid will not
be used for solutions in the following tutorials, but could be substitued for
the traditional script-generated one if desied. For this case, the results are
similar.
Running Steady-State RANS
To run this tutorial yourself, the connectivity
tutorial must first be completed to
generate the grid.x.ihc, INTOUT, grid.bc, grid.x.b2b, and
overlapper/panel_weights.dat files required as in input to the solver, or
they can be downloaded from that tutorial directly.
Navigate to the run sub-directory containing your connected grid and prepare the
files needed to run the solver by running the init_RANS.sh script, shown
below, to make a solution sub directory, then copy over and alter the input and
job submission files into it. Remember to ensure your charge GROUP_ID is
properly set in the envVars.sh file.
# Just copy over the input and pbs file, setting charge group id.
# ---------------------------------------------------------------------------- #
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
mkdir -p soln_RANS
cd soln_RANS
cp $baseDir/auxFiles/LAVA_solver_RANS.yaml .
cp $baseDir/auxFiles/LAVA_solver_RANS_athena.pbs .
sed -i "#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_solver_RANS_athena.pbs
# ---------------------------------------------------------------------------- #
To run the solver process on the grid on a local environment, run the
run_RANS.sh script from the current sub directory. Make sure that
LAVA_EXE_DIR, LAVA_EXE_SUFFIX, OMP_NUM_THREADS, and N_PROC are properly
set in the envVars.sh file. Running with 1 MPI rank with 55 threads takes
roughly 66 minutes.
To run the solver on the NAS environment, push the following files up to
the appropriate mirrored run sub-directory on NAS if you have not
built/connected your grid there already, ssh into athfe01, cd into
soln_RANS and submit the pbs job with qsub LAVA_solver_RANS_athena.pbs,
which should take roughly 20 minutes to complete after the job begins:
grid.x.ihcgrid.bcgrid.x.b2bINTOUToverlappersoln_RANS
Input File
Below is the RANS input file in its entirety for reference, with best practice settings for transonic RANS. Specifics are discussed below.
grid :
curv :
gridFile : ../grid.x.ihc
bcfile : ../grid.bc
b2bfile : ../grid.x.b2b
fileType : plot3d
interpFile : ../INTOUT
timeStepping :
steady : true
referenceConditions :
pressure : 1.5422851978407425e+05
uMag : 3.0583477205837789e+02
temperature : 3.2204000000000002e+02
alpha : 2.50
beta : 0.0
momentCenter : [3.9624, 0.0, 0.0]
area : 1.3985484287039998e-01
length : 1.9099530000000001e-01
cp : 1005.00000
gamma : 1.40000000
slconst : 1.458e-6
slref : 110.400000
nonlinearSolver :
method : implicit
kind : ank
iterations : 10000
miniterations : 100
l2conv : 1e-8
CFLStart : 0.1
CFLlimit : 1000.0
CFLlimitTur : 1000.0
jacobianLag : 5
linearSolver :
tolerance : 0.1
maxTolerance : 0.5
subspaceSize : 40
approxViscFluxes : False
lineSearch : True
jacobianType : hybrid_frechet
jacTypeSwitchTol : 1e-4
preconditioner :
type : ilu
ilufill : 1
subiter : 1
navierstokes :
convective :
type : upwind
riemannsolver : modifiedroe
schemeOrder : 2
interporder : 3
limiter : koren
lowspeedPreCon : none
turbulencemodel :
type : sa
userc : True
useqcr : True
usesacc : False
useSAlowRe : False
mode : zdesMode0
curvSolver :
equations : rans
task : solve
integrationweights : overlapper
integrationweightsdir : ../overlapper
verbose : False
initializeboundarylayer : False
echorestart : False
fixbadrecon : True
b2btol : 1e-8
metricexchange : True
bc :
-
names : [fuse,wing,tail]
type : BCWallViscous
-
names : [far]
type : BCFarfield
-
names : [symm]
type : BCSymmetryPlane
output :
ioProcs : 0
restart :
frequency : 500
fileName : restart
volume :
-
frequency : 500
fileName : vol
variables : ['pressure', 'velocityx', 'velocityy', 'velocityz', 'temperature', 'nut', 'eddyviscosityratio']
fileType : plot3d
surface :
-
BCTypes : [BCWallViscous]
frequency : 500
variables : [cp, signedcf, cfx, cfy, cfz, yplus]
fileName : surface
monitor :
variables : ['cl', 'cd', 'cmy', 'maxmach', 'maxanut']
- referenceConditions: Chosen to match the NTF scale wind tunnel model at Mach 0.8 and Reynolds number of 5 million.
- nonLinearSolver: LAVA best practice for steady state RANS is using the approximate Newton Krylov solver. The solution will be run until 8 orders of residual reduction occurs or 10,000 iterations have been solved. The CFL will begin at 0.1 and ramp up to 1000 to accelerate convergence as the residual is reduced.
- linearSolver: A Hybrid-Frechet Jacobian is used, and starts with an explicit matrix-based GMRES solver until 4 orders of residual reduction is achieved, at which point the solve method switches to matrix-free based GMRES.
- preconditioner: Incomplete U factorization with a fill level of 1.
- navierStokes:
- convective: LAVA best practice for steady-state RANS at transonic conditions is using an upwind numerical flux with a modified Roe Riemann solver and left and right state reconstructions, applying a Koren limiter.
- turbulenceModel: For the AOA of 2.5 simulated, best practice is to
apply both the rotational and QCR2000 corrections to the SA neg model.
For CRM high lift conditions, they should be turned off as together they
induce a lower lift near
clmax.
- curvSolver: RANS solver with fixBadRecon applied for non-subsonic flows to ensure left and right state reconstructions don't result in negative pressure and temperature.
- output: Most output variables are self-explanatory.
signedcfis skin friction signed using a combination of AOA and the skin friction xyz vector to showcase reverse flow regions via skin friction magnitude.
Assessing the Solution
The following files should have been written by the end of the solve, which should be pulled back to your local computer for assessment:
data.iter: the convergence history.restart.info,iter,nam,rst: files needed to restart the solver.vol.q,x,name: the last iteration's volume data.surface.q,x,name: the last iteration's surface data.
Sample shortened output from the run should look like this
██╗ █████╗ ██╗ ██╗ █████╗
██║ ██╔══██╗██║ ██║██╔══██╗
██║ ███████║██║ ██║███████║
██║ ██╔══██║╚██╗ ██╔╝██╔══██║
███████╗██║ ██║ ╚████╔╝ ██║ ██║
╚══════╝╚═╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝
Compiled using: Intel(R) Fortran Intel(R) 64 Compiler Classic for applications running on Intel(R) 64, Version 2021.10.0 Build 20230609_000000
with options: -I/opt/cray/pe/mpich/8.1.33/ofi/intel/2022.1/include -I/opt/cray/pe/mpich/8.1.33/ofi/intel/2022.1/include -sox -fPIC -O3 -march=icelake-server -qopenmp -traceback -g -DLAVA_MPI
from git hash: 63573687cd705182b4f44493e3ecae72bd21d78d*
LAVA version : @GIT_VERSION@
on: Aug 31 2026 at 13:04:08
Using 4 MPI Ranks
Using 64 OpenMP Threads
...
Proc 0 OpenMP Mapping: Proc 1 OpenMP Mapping:
Thread: 0 Bound to CPU 0 Thread: 0 Bound to CPU 64
...
Thread: 63 Bound to CPU 63 Thread: 63 Bound to CPU127
...
--------------------------------------------------------------------------------
preprocessing
--------------------------------------------------------------------------------
readGridInfo Time: 0.00101 seconds
setupBCInfo Time: 0.00120 seconds
readINTOUT Time: 0.26411 seconds
partition Time: 0.34544 seconds
initializeTiles Time: 0.09066 seconds
createGlobalIndex Time: 0.27021 seconds
createGlobalVectors Time: 0.01243 seconds
createPointHaloExchanges Time: 0.04456 seconds
createIOPartition Time: 0.28355 seconds
readGrid Time: 1.35778 seconds
metric Time: 0.01899 seconds
setupBCsForTile Time: 0.00945 seconds
createWallSurfaces Time: 0.03001 seconds
createHaloExchanges Time: 1.49440 seconds
flagNoBlending Time: 0.00293 seconds
setupBCsForVec Time: 0.03054 seconds
setupB2BVecScatter Time: 0.00004 seconds
computeWallDist Time: 3.53948 seconds
setupIntegrations Time: 0.05246 seconds
setupTileWallIntegration Time: 0.00091 seconds
verifyB2Bs Time: 0.06180 seconds
verifyFringes Time: 0.00041 seconds
--------------------------------------------------------------------------------
preprocessing Time: 8.01614 seconds
--------------------------------------------------------------------------------
...
Reference State Information:
Reference Pressure = 154228.51978407
Reference U Velocity = 305.54368512282
Reference V Velocity = 0.0000000000000
Reference W Velocity = 13.340325392204
Reference Temperature = 322.04000000000
Reference UMag = 305.83477205838
Reference Q = 78001.073880796
Reference Speed of Sound = 359.80561418633
Reference Mach Number = 0.85000000000000
Angle of Attack = 2.5000000000000
Reference Density = 1.6678494845492
Reynolds Number per Unit Length = 26178654.657994
Reynolds Number using LengthRef = 5000000.0000000
Reference Viscosity = 0.19484819735724E-04
Gas Constant = 287.14285714286
Free-Stream Residual = 0.19497029766647E+08
Free-Stream Residual Vol = 0.41353482597890E-04
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Time |Nonlin | CFL | CFLTur | Wall | Flow | Tur | Step | Step | Step |LinIt |LinIt |Lin Res |Lin Res | cl | cd | cmy | maxmach | maxanut |
| Step | Iter | | | Time | Res | Res | Phys | LS | Tur | Flow | Tur | Flow | Tur | | | | | |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 0 1.0000E-01 1.0000E-01 3.1240E+00 1.9497030E+07 6.6777235E+06 0.000 0.000 0.000 0 0 0.0000 0.0000 5.9653570E-03 7.0942371E-01 8.2683289E-02 8.5000000E-01 3.5047802E-05
1 1 1.0000E-01 1.0000E-01 4.1014E+00 1.8906246E+07 5.5868839E+06 1.000 1.000 0.669 1 1 0.0000 0.0000 1.1358960E-02 7.0831835E-01 8.3093145E-02 8.5003932E-01 3.5047802E-05
1 2 1.0000E-01 1.0000E-01 4.9670E+00 1.8455838E+07 4.8008919E+06 1.000 1.000 0.731 1 1 0.0000 0.0000 1.6933827E-02 7.0750977E-01 8.3546563E-02 8.5011785E-01 3.5047802E-05
1 3 1.0000E-01 1.0000E-01 5.8332E+00 1.8110752E+07 4.2068418E+06 1.000 1.000 0.808 1 1 0.0000 0.0000 2.2706561E-02 7.0695286E-01 8.4015123E-02 8.5023461E-01 3.5047802E-05
1 4 1.0000E-01 1.0000E-01 6.7083E+00 1.7844096E+07 3.7400436E+06 1.000 1.000 0.903 1 1 0.0000 0.0000 2.8669654E-02 7.0661139E-01 8.4480998E-02 8.5038817E-01 3.5047802E-05
1 5 1.0000E-01 1.0000E-01 7.5762E+00 1.7633819E+07 3.3622711E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 3.4794373E-02 7.0645201E-01 8.4928650E-02 8.5057697E-01 3.5047802E-05
1 6 1.2500E-01 1.2500E-01 1.0339E+01 1.7413854E+07 2.9832121E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 4.2630298E-02 7.0637965E-01 8.5419697E-02 8.5087663E-01 3.5047802E-05
1 7 1.2500E-01 1.2500E-01 1.1206E+01 1.7247199E+07 2.6749993E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 5.0501134E-02 7.0647255E-01 8.5811264E-02 8.5122546E-01 3.5047802E-05
1 8 1.2500E-01 1.2500E-01 1.2073E+01 1.7122515E+07 2.4175369E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 5.8261663E-02 7.0667434E-01 8.6104192E-02 8.5162045E-01 3.5047802E-05
1 9 1.2500E-01 1.2500E-01 1.2942E+01 1.7030918E+07 2.1994157E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 6.5797205E-02 7.0694835E-01 8.6335624E-02 8.5205882E-01 3.5047802E-05
1 10 1.2500E-01 1.2500E-01 1.3811E+01 1.6962291E+07 2.0159631E+06 1.000 1.000 1.000 1 1 0.0000 0.0000 7.3035391E-02 7.0727535E-01 8.6563668E-02 8.5253803E-01 3.5047802E-05
...
1 300 1.0000E+03 1.0000E+03 9.3946E+02 4.5138829E-01 5.9705310E-02 1.000 1.000 1.000 40 8 0.1542 0.0864 5.1795671E-01 2.8604070E-02 -3.8465123E-02 1.4755904E+00 3.3717311E-02
1 301 1.0000E+03 1.0000E+03 9.4824E+02 4.6677417E-01 5.6232379E-02 1.000 1.000 1.000 34 6 0.0992 0.0889 5.1795670E-01 2.8604071E-02 -3.8465096E-02 1.4755904E+00 3.3717329E-02
1 302 1.0000E+03 1.0000E+03 9.5633E+02 4.8309285E-01 5.5681979E-02 1.000 1.000 1.000 40 7 0.1937 0.0932 5.1795670E-01 2.8604071E-02 -3.8465074E-02 1.4755904E+00 3.3717348E-02
1 303 1.0000E+03 1.0000E+03 9.6456E+02 5.1988277E-01 5.3544949E-02 1.000 0.800 1.000 40 8 0.1464 0.0921 5.1795670E-01 2.8604071E-02 -3.8465061E-02 1.4755904E+00 3.3717375E-02
1 304 1.0000E+03 1.0000E+03 9.7267E+02 3.8847802E-01 4.9083825E-02 1.000 1.000 1.000 40 7 0.1287 0.0922 5.1795669E-01 2.8604071E-02 -3.8465049E-02 1.4755904E+00 3.3717396E-02
1 305 1.0000E+03 1.0000E+03 9.8069E+02 3.7961928E-01 4.4516304E-02 1.000 1.000 1.000 40 6 0.2318 0.0974 5.1795669E-01 2.8604071E-02 -3.8465038E-02 1.4755904E+00 3.3717413E-02
1 306 1.0000E+03 1.0000E+03 9.9060E+02 3.5494310E-01 4.2058888E-02 1.000 1.000 1.000 40 6 0.2462 0.0947 5.1795670E-01 2.8604071E-02 -3.8465035E-02 1.4755904E+00 3.3717428E-02
1 307 1.0000E+03 1.0000E+03 9.9863E+02 3.6954132E-01 4.2434745E-02 1.000 1.000 1.000 40 6 0.2185 0.0925 5.1795669E-01 2.8604071E-02 -3.8465022E-02 1.4755904E+00 3.3717447E-02
1 308 1.0000E+03 1.0000E+03 1.0067E+03 4.0734492E-01 4.1340448E-02 1.000 0.800 1.000 40 6 0.1659 0.0984 5.1795670E-01 2.8604072E-02 -3.8465020E-02 1.4755904E+00 3.3717465E-02
1 309 1.0000E+03 1.0000E+03 1.0147E+03 3.1976475E-01 3.8913521E-02 1.000 1.000 1.000 40 6 0.2775 0.0920 5.1795670E-01 2.8604071E-02 -3.8465015E-02 1.4755904E+00 3.3717482E-02
1 310 1.0000E+03 1.0000E+03 1.0227E+03 3.1172209E-01 3.6243799E-02 1.000 1.000 1.000 40 6 0.1801 0.0907 5.1795669E-01 2.8604071E-02 -3.8465007E-02 1.4755904E+00 3.3717499E-02
1 311 1.0000E+03 1.0000E+03 1.0326E+03 3.2380852E-01 3.7397459E-02 1.000 1.000 1.000 40 6 0.1841 0.0887 5.1795669E-01 2.8604071E-02 -3.8464999E-02 1.4755904E+00 3.3717518E-02
1 312 1.0000E+03 1.0000E+03 1.0406E+03 2.7397625E-01 3.8162284E-02 1.000 1.000 1.000 40 5 0.1002 0.0999 5.1795669E-01 2.8604071E-02 -3.8464993E-02 1.4755904E+00 3.3717534E-02
1 313 1.0000E+03 1.0000E+03 1.0488E+03 2.2470154E-01 3.6664621E-02 1.000 1.000 1.000 40 8 0.1899 0.0976 5.1795669E-01 2.8604071E-02 -3.8464990E-02 1.4755904E+00 3.3717554E-02
1 314 1.0000E+03 1.0000E+03 1.0571E+03 2.1174338E-01 3.3072150E-02 1.000 1.000 1.000 40 9 0.1498 0.0860 5.1795669E-01 2.8604071E-02 -3.8464987E-02 1.4755904E+00 3.3717578E-02
1 315 1.0000E+03 1.0000E+03 1.0652E+03 1.8893928E-01 2.8632126E-02 1.000 1.000 1.000 40 8 0.1302 0.0847 5.1795669E-01 2.8604071E-02 -3.8464985E-02 1.4755904E+00 3.3717598E-02
------------------------------------------------
Info msg on proc(0) : Writing restart file...
------------------------------------------------
solve time: 1069.52952598100 sec
res time: 10.7660222251826 %
form time: 3.65699977820859 %
apply time: 29.1776649985200 %
factor time: 5.09388768440312 %
ortho time: 15.4056040247116 %
turb time: 24.7732012903499 %
In order to monitor the residual history you can either look at the 6th and 7th
columns of the standard output which represents the L2 norm of the dimensional
flow and turbulence model residuals or you can use the plotHist plotting
utility that is provided with LAVA by running the following command
to generate the figure below which shows 7 orders of convergence within 315 iterations.
Additionally the convergence history of integrated forces and moments for the wing can be monitored by looking at the 15th, 16th, and 17th column or plotting using the following commands
plotHist.py iter cl_wing cd_wing cmy_wing cl_tail cd_tail cmy_tail -xRange 215 315 -doSubplot
plotHist.py iter cl_wing cd_wing cmy_wing cl_tail cd_tail cmy_tail -xRange 245 315 -showStd
to generate the figures below, which show load flattening after iteration 240 and very low deviation or the last ~70 iterations.
Views of the surface.q function file, surface.x grid file, and
surface.nam field name files are plotted below for average cp and skin
friction with slice plots at various slices at fractional wing span locations.
For this AOA, no reverse flow develops on the wing.
Conducting a Grid Refinement Study
Creating a set of grids for a convergence study is standard procedure to bound a grid's truncation error. Possible options within the context of the LAVA project file system are:
- Incorporate the refinement factors within the grid growth scripts. This
requires the grid parameters in
parm/MakeParm.tclto be dependent on grid level (already inherent), and for a set of starting surface grids to exist within each component's geom sub-directory. Likely, conditional grid growth arguments such as splay have to be implemented iteratively in the components' tcl scripts in order for the now denser grids to have proper overlap, non-folded elements, etc. - Build a new volume grid from scratch using EPOGS for each refinement level desired with appropriate refinement of grid metrics. This may result in needing to manually correct individual grids for each level (see the EPOGS tutorial for a brief discussion on this).
- Use LAVA's
refineutility to take existing volumes and refine them by a factor. If refinement issues arise, the growth parameters of the level one grids (i.e. the starting grids) must be adjusted to allow for a well-posed starting point. This generally doesn't require much effort.
We chose to adopt the last option for this tutorial. As show in the figure below, LAVA's refine executable takes each block and directionally parameterizes each block curve with a spline, redistributes it with a refined point set in parameter space, and then maps that redistribution back to physical space.
There is currently no projection back to CAD, so one caveat is if significant c1-discontinuity or repeated alternations between concavity and convexity exists within the parameterized curve curvature then the refined curves may no longer well-represent the true model geometry (this is no worse than refining grids using existing CGT functionality such as SrapRedist). For this reason the surface grids were built a-priori to delineate feature lines that should be respected.
Building the Refined Grid Set
To run the refinement procedure first navigate to the desired run sub-folder
(pick the one you created for the scripting
tutorial). If you do not have the grid.x and
grid.bc files required as a starting point for this tutorial, either do the
project grid scripting tutorial or download
them from that tutorial. Once those files exist, run the run_refineGrid.sh
script, shown below, making sure the GROUP_ID, LAVA_EXE_DIR, and
LAVA_EXE_SUFFIX, and OMP_NUM_THREADS variables are set in envVars.sh.
# Define a number of refinements (1.414214 and 2.0 here), then
# perform the refinements in appropriate sub directory.
# Use sed to alter the yaml files to have the right refinement factor.
# This script assumes that we will be performing a RANS convergence study,
# and so also copies in and appropriately alters the files needed to run
# a RANS solution on NAS.
# ---------------------------------------------------------------------------- #
factOnes=(1 2)
factDecs=(414214 0)
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
mkdir -p soln_RANS
cp $baseDir/auxFiles/LAVA_solver_RANS.yaml ./soln_RANS/
cp $baseDir/auxFiles/LAVA_solver_RANS_athena.pbs ./soln_RANS/
sed -i "/#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_solver_RANS_athena.pbs
for ((factI=0; factI<${#factOnes[@]}; factI++)); do
# Make and enter refined grid folder.
# ------------------------------------------------------------------------ #
refFolder="refinedGrid_factor${factOnes[$factI]}p${factDecs[$factI]}"
mkdir -p $refFolder
cd $refFolder
# ------------------------------------------------------------------------ #
# Refine the grid.
# ------------------------------------------------------------------------ #
cp ../grid.bc .
cp $baseDir/auxFiles/LAVA_refine.yaml .
sed -i "/ factor : 1.0/c\ factor : ${factOnes[$factI]}.${factDecs[$factI]}" \
LAVA_refine.yaml
$LAVA_EXE_DIR/refine.$LAVA_EXE_SUFFIX LAVA_refine.yaml
mv surface.x grid.sur
rm LAVA_refine.yaml
# ------------------------------------------------------------------------ #
# Get and update the files needed to run RANS on NAS.
# ------------------------------------------------------------------------ #
jobName="LAVA_solver_OGSCRM_AOA2p5_L${factOnes[$factI]}p${factDecs[$factI]}"
factor="${factOnes[$factI]}.${factDecs[$factI]}"
nNode=$(echo "(($factor * $factor * $factor) + 0.5) / 1" | bc)
mkdir -p soln_RANS
cp $baseDir/auxFiles/LAVA_solver_RANS.yaml ./soln_RANS/
cp $baseDir/auxFiles/LAVA_solver_RANS_athena.pbs ./soln_RANS/
sed -i "/#PBS -l select/c\\#PBS -l select=$nNode:ncpus=256:mpiprocs=4:model=tur_ath" \
soln_RANS/LAVA_solver_RANS_athena.pbs
sed -i "/#PBS -N/c\\#PBS -N $jobName" \
soln_RANS/LAVA_solver_RANS_athena.pbs
sed -i "/#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
soln_RANS/LAVA_solver_RANS_athena.pbs
# ------------------------------------------------------------------------ #
# Back to base grid folder.
# ------------------------------------------------------------------------ #
cd ..
# ------------------------------------------------------------------------ #
done
# ---------------------------------------------------------------------------- #
For each grid level defined with a ones and decimals place, a level-named sub-folder is created and the refine executable is called within it to create a local grid. The grid within these sub-folders is named the same as the base grid level so that other run scripts can be called on them (e.g. connectivity - see below). The BC file is copied in because the BCs shouldn't have changed. In this case we are creating grids that are a factor of 1.414214 and 2.0 denser than the original.
The input file to the refinement utility is shown below. Note how the grid to
be refined is one level up from the sub-directory we have created. When it is
imported by run_refineGrid.sh, the factor entry is modified appropriately.
The surface grid is the portion of the refined grid defined by the bc file.
Note that if partial BCs existed (the ranges were not [1,-1]) then the bc file
would have to be altered prior to refine being called to ensure accurate
surface extraction.
refine:
factor : 1.0
coarseGridFile : ../grid.x
refineGridFile : grid.x
nSmooth : 0
writerecordmarkersingrids: false
surface :
extract : True
surfaceGridFile : surface.x
bcFile : grid.bc
surfaceBCNames : [fuse,wing,tail]
Slices and surfaces of the refined grid set can be seen below. The entire grid system has been refined, but note that there are options to refine individual grids to different levels, or directionally.
Connecting and Assessing the Refined Grids
Run the run_connectivity.sh script within each refined grid folder
(refinedGrid_1p414214, refinedGrid_2p0), or run on NAS as described in the
connectivity tutorial: no changes need
to be made to the connectivity files themselves because the grid files are
named as expected. The level 1.414214 grid takes 12 seconds with 56 threads to
run the connectivity script and has ~68 million nodes, while the level 2.0 grid
takes 30 seconds and has ~189 million.
There are generally three things to check for issues on a refined grid:
- Negative Jacobians: Open the
grid.x.ihcfile inovergridand click DIAGNOSE and then the show box next to Jacobian in the bottom right. If any of the table entries have non-zero count then view them in the grid. Look at your level zero grids in the same locations (likely they will be almost folded in the now problem areas) and alter the grid scripts to smooth or splay them more to prevent refinement issues, then rerun refinement. - Orphans: It is unlikely that orphans will appear due to overlap issues
that didn't already exist in the starting grid because the overlapped region
isn't reduced. However, the shape of the geometry surface may have slightly
changed if the spline across a large portion of a body which, for instance,
undulates. More laxity in projection may be needed. Clicking DIAGNOSE within
overgridand then All under orphan analysis in the mid right will count and highlight orphans. - Commensurate B2Bs: The connectivity process assesses and writes a new B2B file. One indication of refinement going wrong is if the B2B file created doesn't match that of the starting grid. Diff the two to double-check.
The level 1.414214 grid does not show any issues for these checks. The Level 2.0 however, shows the orphans on zone 5: the inboard wing trailing edge. Zooming in and cycling through constant L of grid 5 shows that the orphans surround a hole that has been created in grid 5 from [J 17->18, K 47, L 8->9]:
These kind of localized 'hash' patterns of orphans generally mean an edge or
two has been cut, but we will re-run connectivity with a debug node to be sure.
Alter the LAVA_connectivity.yaml file to have the following additional
debugNode entry. The run_connectivity.sh script is designed so that
alterations to the yaml file will not be overwritten.
When connectivity is re-run now, we see output with a 'Debug Node' prefix. Assessing the output from debug nodes can be complex and the manual exists in part to make this output less opaque. We focus in on the following lines, which state that the portion of block 1 (the fuse) which intersects one of the edges of this node is too far away to project to given the relative size of the elements, which means connectivity doesn't think they are the 'same' surface.
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Checking edge [ 17 47 8] to [ 17 47 9] for surface intersection ...
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Start node closest surfNode Blk/i/j/k: 5 17 47 1
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): End node closest surfNode Blk/i/j/k: 5 17 47 1
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Considering intersection 1 of 1 with block 1...
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Found surface relation between intersected face 114099 and edge start node.
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Edge start node dist from wall node to cut node: 0.00001302
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Edge start node max local deviation offset lim: 0.00000378
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Start dist from wall outside of surface deviation limit: cut edge.
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): At least one edge is linked to the block surface: checking unrelated interpolated intersection overlap ...
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Edge node dist from interpolated wall node to cut node: 4.05455871
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Edge average node max local deviation offset lim: 0.00000378
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Interpolated intersection is also outside of surface deviation limit: cut edge.
[[Debug Node (Blk,j,k,l) 5 17 47 8]] (thread 27): Intersected 1 times with surface projs, at least one of which can't be treated as the same surface: blanking both edge nodes.
Taking an x location near the orphans (4.053641), we take a slice of the un-cut grid.x file and zoom into trailing edge intersection with the fuse to find that there is indeed a slightly larger offset of the fuse on the refined grid (right) than was on the original grid (left):
Opening both the original and refined grid.sur files with the Flat Shaded Display Option checked shows that splining the long fuse undulations has caused some minor differences in the fuse which are mostly irrelevant except for this problem location:
The fix for this issue is simple: slightly increase the distance surfaces on
block 5 are allowed to accept projection onto other surfaces. This is done
through the edgeFactor option (defaulted to 1) assigned to block 5 through a
zoneSpecific option by adding the following lines to the
LAVA_connectivity.yaml file and re-running run_connectivity.sh:
overset :
zoneSpecific:
-
# Allow block 5 to project just a bit further (onto block 1).
zones : [5]
edgeFactor : 1.2
One could also argue that the fuselage component should be split into smaller
grids along its length near the fairing, but the changes in shape are so minor
that this was deemed unnecessary. One non-hard-coded strategy for this would be
to use the GetLimitedBBox CGT utility to find the limits of the fairing
within the fuse.tcl script, and then split at the appropriate j indices.
Run RANS Solutions and Assess Grid Convergence
The purpose of building a family of refined grids is to truncate the grid
discretization error - i.e. find the coarsest grid which still captures the
flow physics. In preparation for running a RANS simulation on each of these
grids, the run_refineGrid.sh made a solution sub directory and copied in and
modified a solver input and job submission (LAVA_solver_RANS.yaml and
LAVA_solver_RANS_athena.pbs) file to each case, then modifies them as needed
to account for increased resource need and job name. To run these cases on NAS,
do the following for each:
- Run the
run_connectivity.shscript within the grid's directory to connect the grid. - If you aren't building on NAS, push the following files to the grid's folder
on NAS:
grid.x.ihcgrid.bcgrid.x.b2bINTOUTsoln_RANS
- ssh into
athfe01. - cd into
soln_RANS - submit the pbs job with
qsub LAVA_solver_RANS_athena.pbs.
Note that you could use the run_RANS.sh script to run these solutions
locally, as is done in the RANS tutorial, but especially
for higher grid level refinements this can become untenable.
As shown below, all simulations' flow/turbulence residual converge 7+/5+ orders of magnitude, and their standard deviations of lift and drag coefficient over the last 100 iterations are well below a count. The three levels required ~77, ~294, ~3890 CPU-hrs of computational time, respectively. For a discussion on the RANS solution settings choices and analysis, see the RANS tutorial.
These plots were generated using LAVA's plotHist tool by running the
following commands in the run sub-directory:
plotHist.py -F data.iter iter cl cd -showStd -xRange 230 330
plotHist.py -F refinedGrid_1p414214/data.iter iter cl cd -showStd -xRange 300 400
plotHist.py -F refinedGrid_2p0/data.iter iter cl cd -showStd -xRange 1040 1140
plotHist.py -F data.iter refinedGrid_1p414214/data.iter refinedGrid_2p0/data.iter iter flowres turres
If we plot a trend of cd vs a linearized representation of 3D grid size
increase such that an infinitely fine grid is located on the x axis, we see a
very flat trend with an asymptotic cd estimate of 0.028193. Since all grids
are well within a defined linear trend and we can quantify the bounds of
integrated loads, it is safe to say that the initial grid is fine enough to
resolve the physics of the RANS case at AOA of 2.5 degrees.
Performing Geometry Morphing
This tutorial demonstrates how to use LAVA's grid deformation capabilities to deflect the CRM wing to conform to a known bending and twist distribution. Specifically, we will be deflecting the wing to a prescribed bending and twist distribution corresponding to wind tunnel deflections at a 2.5 degree angle of attack.
Note that currently the figures in this tutorial do not contain the tail as they were re-appropriated from a prior optimization, but the tail is included here in the discussed files and tutorial process.
We will be leveraging LAVA's spline capabilities to create three B-Spline curves:
- a curve which follows the elastic axis inside the wing,
- a curve which interpolates the bending data at the sampled spanwise locations,
- a curve which interpolates the twist data at the sampled spanwise locations.
Rigid links will be created from each wing surface node to the elastic axis curve. These links are restricted to a constant \(y\) value, giving us a unique location along the elastic axis for each surface node. The bending and twist curves will then be used to define the desired deflection of the elastic axis, which will be applied to the wing surface nodes through a rotation and translation of the rigid links. Once we have obtained a deformed surface grid, we will use LAVA's grid deformation capabilities to deform the volume grid to conform to the new surface grid.
Case Setup
As a starting point, create a run sub-directory and generate a grid within
using run_buildGrid.sh as is done in the scripting
tutorial, or simply use the directory already
created for that tutorial. If you cannot or do not want to run that tutorial or
grid build script, the grid files relevant to this tutorial
(grid.x,grid.sur, and grid.bc) can be downloaded directly from the
scripting tutorial.
Run the init_morphing.sh script, within your chosen/created run sub-directory
(shown below). This creates a morphing sub-directory based on the (in this
case) angle of attack desired to be morphed to, then copies in the relevant
grid files along with the LAVA_morphing_ea.txt (elastic axis data),
LAVA_morphing_disp_aoa2p5.txt (bend/twist data), and LAVA_morphing.py (the
main morphing script) files needed to perform the morphing. Note that relevant
environmental variables and paths in the LAVA_morphing.py file are altered
according to the envVars.sh file entries, so ensure they are correct.
# Make a directory for the grid to have its wing morphed to 2.5 aoa position,
# copy in init grids and morping files, altering appropriately.
# This is set up to support a variety of AOA morphing cases, but each will need
# their own disp file, and only aoa 2.5 is supplied in the tutorial.
# ---------------------------------------------------------------------------- #
aoaOnes=(2)
aoaDecs=(5)
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
for ((aoaI=0; aoaI<${#aoaOnes[@]}; aoaI++)); do
morphFolder="morphedGrid_aoa${aoaOnes[$aoaI]}p${aoaDecs[$aoaI]}"
dispFile="LAVA_morphing_disp_aoa${aoaOnes[$aoaI]}p${aoaDecs[$aoaI]}.txt"
jobPrefix="LAVA_morphing_aoa${aoaOnes[$aoaI]}p${aoaDecs[$aoaI]}"
mkdir -p $morphFolder
cd $morphFolder
cp ../grid.x grid.in.x
cp ../grid.sur grid.in.sur
cp ../grid.bc grid.bc
cp $baseDir/auxFiles/LAVA_morphing.py .
cp $baseDir/auxFiles/$dispFile .
cp $baseDir/auxFiles/LAVA_morphing_ea.txt .
cp $baseDir/auxFiles/LAVA_morphing_rom_ait.pbs .
cp $baseDir/auxFiles/LAVA_morphing_tur_ath.pbs .
sed -i "/lava_suffix =/c\\lava_suffix = '$LAVA_EXE_SUFFIX'" \
LAVA_morphing.py
sed -i "/lava_lib_path =/c\\lava_lib_path = '$LAVA_LIB_DNY'" \
LAVA_morphing.py
sed -i "/disp_file =/c\\disp_file = \"$dispFile\"" \
LAVA_morphing.py
sed -i "#PBS -N/c\\#PBS -N ${jobPrefix}_rom_ait" \
LAVA_morphing_rom_ait.pbs
sed -i "/source path/c\\source $PY_VIRTUALENV_DIR" \
LAVA_morphing_rom_ait.pbs
sed -i "#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_morphing_rom_ait.pbs
sed -i "#PBS -N/c\\#PBS -N ${jobPrefix}_tur_ath" \
LAVA_morphing_tur_ath.pbs
sed -i "/source path/c\\source $PY_VIRTUALENV_DIR" \
LAVA_morphing_tur_ath.pbs
sed -i "#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_morphing_tur_ath.pbs
done
# --------------------------------------------------------------------------- #
Running
Running on the NAS Cluster
You can run the morphing either locally or on the NAS cluster. The
init_morphing.sh script will have created two example pbs scripts for use on
NAS. If you aren't running all the tutorials on NAS, push the entire morphed_*
sub grid to nas to run.
Note that these pbs scripts will modify the LAVA_morphing.py file to have the
appropriate lava_suffix value once the job submits.
The charge group IDs of the pbs scripts, as well as the path to the Python
virtual environment you need to have set up on NAS should have been filled with
the variables you have set in envVars.sh file.
Running on External Systems
To run the morphing locally, navigate to the folder created by
init_morphing.sh, and run the run_morphing.sh script shown below. This
takes roughly 15 minutes with 1 MPI rank with 55 threads.
# Assumes init_morphing.sh has been called and you are running this on local
# compute from a directory created by it.
# ---------------------------------------------------------------------------- #
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
# Activate the python virtual environment.
source $PY_VIRTUALENV_DIR
# Set the LAVA lib suffix to the value within envVars.sh
sed -i "/lava_suffix =/c\\lava_suffix = '$LAVA_EXE_SUFFIX'" \
LAVA_morphing.py
# Do the morphing (omp threads set in envVars.sh).
python LAVA_morphing.py | tee LAVA_morphing.out
# --------------------------------------------------------------------------- #
MPI Considerations
Warning
The LAVA_morphing.py script is not designed to run in parallel using MPI.
However, the LAVA dynamic libraries are generally compiled with both MPI
support and OpenMP thread support. Notably, the most computationally heavy
portion of the script is the volume mesh warping, which is performed by the
LAVA dynamic library. As such, the current tutorial will run in parallel
using OpenMP threads, but not MPI ranks. To extend this tutorial to MPI
ranks, you will need to partition the volume grid array vol_xyz across
MPI ranks and instantiate the meshWarper object on each rank with its
local portion of the volume grid. After warping is complete, you will then
need to gather the partitioned volume grid array back onto the root
processor for writing.
Morphing Python Script
This tutorial provides a single Python script, LAVA_morphing.py, which reads
in the elastic axis and displacement data, fits B-Spline curves to them, and
uses those curves to deflect the wing surface and volume grids. We will break
down the contents of this script below.
Imports
import numpy as np
import copy
from pylava.pyLAVA_spline import Curve
from pylava.pyLAVA_ioutils import (
readPlot3DGrid,
writePlot3DGrid,
getPlot3DSurfaceConnectivity,
collapseGrid,
uncollapseGrid
)
from pylava.pyLAVA_meshwarp import meshWarper
Here, we import numpy and the standard library copy module, along with
three pieces of pyLAVA:
- the
Curveclass frompylava.pyLAVA_spline, which is used to create and evaluate B-Spline curves, - a collection of Plot3D grid I/O utilities from
pylava.pyLAVA_ioutils, and - the
meshWarperclass frompylava.pyLAVA_meshwarp, which is used to deform the volume grid.
Inputs
# Set the LAVA library name and path
lava_suffix = '3D.NS1.INTEL.AVX2.HPEMPT-lib'
lava_lib_path = None # If None, Python will search your LD_LIBRARY_PATH for the LAVA Dyn
# Input files
disp_file = "LAVA_morphing_disp_aoa2p5.txt"
ea_file = "LAVA_morphing_ea.txt"
surface_file = "grid.in.sur"
vol_file = "grid.in.x"
# Output files
surf_output_file = "grid.sur"
vol_output_file = "grid.x"
# Symmetry plane
symm_pts = [[0.0, 0.0, 0.0]]
symm_norms = [[0.0, 1.0, 0.0]]
# Span direction
span_dir = [0.0, 1.0, 0.0]
# List of surface blocks that define the wing
surf_deflect_block_list = list(range(4, 21))
# List of volume blocks to warp
vol_block_list = list(range(22))
print(f"Will be warping blocks {vol_block_list}", flush=True)
This section defines all of the inputs to the script:
lava_suffixandlava_lib_path: Tell pyLAVA which compiled LAVA dynamic library to use. Both theCurveandmeshWarperclasses below load this library directly. These entries should be automatically set by the init script above and by the pbs you run with: you should not have to set them in this file.disp_file: The text file containing the spanwise bending and twist distribution. Set by the init script above.ea_file: The text file containing the coordinates of the wing's elastic axis.surface_fileandvol_file: The undeformed surface and volume grid files.surf_output_fileandvol_output_file: The names of the deflected surface and volume grid files that will be written out by this script.symm_ptsandsymm_norms: A point and normal vector defining the symmetry plane, used by the mesh warper.span_dir: The direction of the wing span, used to define the axis about which the wing will twist.surf_deflect_block_list: The list of surface grid zones that make up the wing; only these zones will be deflected.vol_block_list: The list of volume grid zones that will be warped to conform to the deflected surface.
Note
The ea_file and disp_file inputs are expected to be sampled at the same
spanwise stations, i.e., they must contain the same number of rows in the
same order. This is because the parametric locations along the elastic axis
curve, computed from ea_file, are reused directly to fit the bending and
twist curves from disp_file below.
If you want to run extra aoa displacements, you must both supply those
appropriately named extra disp files and add them to the auxFiles folder,
and then update the init_morphing.sh file to include the new aoa numbers.
Helper Function
def compute_surf(surf_pts_0, link_s, ea_curve, bend_curve, rot_curve):
"""Deflect the wing surface based on bending and rotation curves.
Args:
surf_pts_0: Original surface points
link_s: Parametric locations along the elastic axis
ea_curve: Elastic axis curve
bend_curve: Bending displacement curve
rot_curve: Rotation (twist) curve
Returns:
surf_pts: Deflected surface points
"""
surf_pts = np.zeros_like(surf_pts_0)
# Rotate and displace each surface point
for i in range(surf_pts_0.shape[0]):
# Parametric location on curve
s = link_s[i]
# Point on elastic axis curve
curveXYZ = ea_curve(s)
# Link vector from curve to surface point
linkVec = surf_pts_0[i, :] - curveXYZ
# Rotation angle (convert to radians)
ang = rot_curve(s) * np.pi / 180.0
# Create rotation matrix (rotation about y-axis)
Ry = np.array([
[np.cos(ang), 0.0, np.sin(ang)],
[0.0, 1.0, 0.0],
[-np.sin(ang), 0.0, np.cos(ang)]
])
# Rotate the link vector
linkVec = np.dot(Ry, linkVec)
# Apply rotation and bending displacement
surf_pts[i, :] = curveXYZ + linkVec
surf_pts[i, 2] += bend_curve(s)
return surf_pts
The compute_surf function computes the deflected location of a single set of
surface points, given their parametric locations (link_s) along the elastic
axis curve. For each surface point:
- The corresponding point on the elastic axis curve is evaluated at the
point's parametric location,
s. - A rigid link vector is formed between this point on the elastic axis and the original (undeflected) surface point.
- The twist curve is evaluated at
sto get the local twist angle, which is used to build a rotation matrix about the span direction (the \(y\)-axis, in this example). - The link vector is rotated by this rotation matrix.
- The deflected surface point is obtained by adding the rotated link vector to
the point on the elastic axis, then adding the local bending displacement
(evaluated from the bending curve at
s).
To demonstrate this, we first visualize a rigid link (shown in red) between a single surface point and the elastic axis (shown in blue).
The wing can be rotated by simply rotating each rigid link about the elastic axis. Similarly, translation can be applied to the wing by translating each rigid link. In the following figure, we demonstrate the application of a rotation about the elastic axis.
As previously mentioned, local bending (translation) and twist (rotation) values are obtained from the bending and twist curves.
Creating the Elastic Axis Curve
# Read and create the elastic axis curve
ea = np.loadtxt(ea_file, skiprows=1)[:, 1:].copy()
ea_curve = Curve(lava_suffix, lava_lib_path, X=ea)
ea_curve.writeTecplot("ea_curve.dat")
# Get arc length parameterization for the original data
s = ea_curve.getOrigDataParameterization()
Here, we read in the \((x,y,z)\) coordinates of the elastic axis from ea_file
and create a Curve object, ea_curve, which locally interpolates these
points. The curve is written out to a Tecplot file, ea_curve.dat, so that it
can be visualized alongside the grid, as in the following image.
We then call getOrigDataParameterization to retrieve the parametric location,
s, of each of the original elastic axis data points along the curve. These
parametric locations will be reused below to fit the bending and twist curves
at the same spanwise stations.
Fitting the Bending and Twist Curves
# Read and fit the bending displacement data
bend_data = np.loadtxt(disp_file, skiprows=1)[:, 1].copy()
bend_curve = Curve(lava_suffix, lava_lib_path, X=bend_data, s=s, k=4, nIter=100)
err = np.linalg.norm(bend_data - bend_curve(s))
print(f"Displacement Fitting Error: {err}")
# Read and fit the twist data
twist_data = np.loadtxt(disp_file, skiprows=1)[:, 2].copy()
twist_curve = Curve(lava_suffix, lava_lib_path, X=twist_data, s=s, k=4, nIter=100)
err = np.linalg.norm(twist_data - twist_curve(s))
print(f"Twist Fitting Error: {err}")
Next, we read in the bending and twist data from disp_file and fit a B-Spline
curve to each using a least-mean-squares fit (k=4, nIter=100), evaluated at
the same parametric locations, s, as the elastic axis curve. The fitting
error, the \(L_2\) norm between the raw data and the curve evaluated at s, is
printed to the screen so that you can confirm the curve is an adequate fit to
your data.
The figure below demonstrates the B-Spline fit of the bending and twist data,
along with the original data points. 
Reading and Selecting the Wing Surface Grid
# Read the surface grid
surf_nzones, surf_sizes, surf_zones = readPlot3DGrid(
surface_file, hasRM=True, hasIB=False
)
conn = getPlot3DSurfaceConnectivity(surf_sizes)
surf_xyz_0, _, surf_conn = collapseGrid(
surf_nzones, surf_sizes, surf_zones, conn=conn
)
# Extract the wing surface blocks to deform
select_surf_zones = [surf_zones[i] for i in surf_deflect_block_list]
select_surf_sizes = np.asarray([surf_sizes[i] for i in surf_deflect_block_list])
select_surf_xyz_0, _ = collapseGrid(
len(select_surf_zones), select_surf_sizes, select_surf_zones
)
We read in the full surface grid, grid.sur, and use
getPlot3DSurfaceConnectivity and collapseGrid to build a single array of
unique surface points and their connectivity, surf_xyz_0 and surf_conn.
This representation is required later by the meshWarper. From this full
surface, we then extract just the zones that make up the wing, as specified by
surf_deflect_block_list, and collapse them into their own array,
select_surf_xyz_0. Only these points will be deflected.
Deflecting the Wing Surface
# Create rigid links and compute displaced surface
link_s, _ = ea_curve.intersectPlane(select_surf_xyz_0, np.array(span_dir))
select_surf_xyz = compute_surf(
select_surf_xyz_0, link_s, ea_curve, bend_curve, twist_curve
)
# Reconstruct the surface zones
new_select_surf_zones = uncollapseGrid(
len(select_surf_zones), select_surf_sizes, select_surf_xyz
)
# Update the full surface with deflected wing blocks
new_surf_zones = copy.deepcopy(surf_zones)
for i, new_surf_zone in zip(surf_deflect_block_list, new_select_surf_zones):
new_surf_zones[i] = new_surf_zone
# Write the deflected surface
writePlot3DGrid(surf_output_file, new_surf_zones)
# Collapse the new surface for warping
surf_xyz, _ = collapseGrid(surf_nzones, surf_sizes, new_surf_zones)
For each wing surface point, we call intersectPlane on the elastic axis curve
to find the parametric location, link_s, of the plane (normal to span_dir)
that passes through that point and intersects the elastic axis curve. This
defines the rigid link between each surface point and the elastic axis. The
compute_surf helper function (discussed above) is then used to compute the
deflected wing surface points, select_surf_xyz, from these links and the
bending and twist curves. The deflected wing zones are reconstructed with
uncollapseGrid, and swapped into a copy of the full surface grid in place of
the original wing zones. This new surface grid is written out to
surf_output_file and collapsed again for use in the volume warp below.
Warping the Volume Grid
# Read and prepare the volume grid
vol_nzone, vol_sizes, vol_zones = readPlot3DGrid(
vol_file, hasRM=True, hasIB=False
)
select_zones = [vol_zones[i] for i in vol_block_list]
select_sizes = np.asarray([vol_sizes[i] for i in vol_block_list])
vol_xyz, _ = collapseGrid(len(select_zones), select_sizes, select_zones)
# Initialize the mesh warper
warper = meshWarper(
surf_xyz_0, # Original surface coordinates
surf_conn, # Surface connectivity
vol_xyz, # Volume coordinates
symm_pts=symm_pts, # Symmetry plane points
symm_norms=symm_norms, # Symmetry plane normals
suffix=lava_suffix, # LAVA DLL suffix
libPath=lava_lib_path, # LAVA DLL path
warp_options={},
)
# Warp the volume grid
new_vol_xyz = warper.warpMesh(surf_xyz)
# Reconstruct volume zones
new_vol_zones = uncollapseGrid(len(select_zones), select_sizes, new_vol_xyz)
# Update the full volume grid with warped blocks
for i, new_vol_zone in zip(vol_block_list, new_vol_zones):
vol_zones[i] = new_vol_zone
# Write the warped volume grid
writePlot3DGrid(vol_output_file, vol_zones)
Finally, we read in the volume grid, grid.x, and collapse the blocks to be
warped, as specified by vol_block_list, into a single array of points,
vol_xyz. We then instantiate the meshWarper object, giving it the
original (undeflected) surface points and connectivity, the volume points to
be warped, and the symmetry plane definition. A call to warper.warpMesh,
passing in the deflected surface coordinates, propagates the surface
deflection through the volume grid using LAVA's mesh warping algorithm. The
warped volume grid blocks are reconstructed with uncollapseGrid, swapped into
the full set of volume zones, and written out to vol_output_file.
Post-Processing
Running LAVA_morphing.py produces three output files:
surf_output_file(grid.2_50.surin this example) : The deflected surface grid, in Plot3D format.vol_output_file(grid.2_50.xin this example) : The volume grid, warped to conform to the deflected surface.ea_curve.dat: A Tecplot file containing the fitted elastic axis curve, along with its control points and the original elastic axis data.
The undeformed and deflected surface and volume grids can be viewed together in
Tecplot, or any other visualization software that supports the Plot3D format,
in conjunction with grid.x. The bending and twist fitting errors printed to
the screen during the run should also be checked to confirm that the fitted
curves are an adequate representation of your input displacement data.
Solution Pre-processing
Prior to performing solutions on the newly deformed grid, run the
run_connectivity.sh script or run on NAS as described in the connectivity
tutorial: no changes need to be made to
the connectivity files themselves because the grid files are named as expected.
Performing Design Optimization
This tutorial demonstrates how to set up and use gradient‑based design optimization with the LAVA Curvilinear solver to minimize the drag on the CRM while meeting target lift and pitching moment requirements. The optimization is performed using OpenMDAO1 and MPhys2.
We will be replicating the 5th test case from the suite provided by the AIAA Aerodynamic Design Optimization Discussion Group, though at a lower Reynolds number. Specifically, at Mach of 0.85 and Re of 5 million, we solve the following optimization problem:
The geometric design variables are visualized below:
The box below demonstrates the N2 diagram for the OpenMDAO model constructed in
this tutorial. It is interactive, so you can click on the components to see
their inputs and outputs. The entire cruise group in the model consists of
different parts of the LAVA Curvilinear framework. The aero_pre component is
LAVA's volume mesh warper which takes in a surface mesh and outputs a deformed
volume mesh. The solver component contains both the LAVA Curvilinear flow
solver and the discrete adjoint solver; it takes the volume grid coordinates
and the angle of attack as inputs, and outputs the flow state vector. The
aero_post component is LAVA's functional computation capability, which takes
in the flow field states, the volume grid coordinates, and the angle of attack,
and outputs the aerodynamic functionals of interest.
Warning
The optimization features in LAVA are still evolving, and you may encounter bugs or unexpected behavior. The steps in and results from this tutorial have been tested and are expected to work as described.
Case Setup
As a starting point, create a run sub-directory and generate a grid within
using run_buildGrid.sh as is done in the scripting
tutorial, then connect it as is done in the
connectivity tutorial, or simply use the
directory already created for those tutorials. If you cannot or do not want to
run that tutorial or grid build script, the grid files relevant to this
tutorial (grid.x.ihc, grid.bc, grid.x.b2b, panel_weights.dat (place
into overlapper sub folder), and INTOUT) can be downloaded directly from
those tutorials.
Run the init_design.sh script, within your chosen/created run sub-directory
(shown below). This creates a design sub-directory based on the components you
desire to design, then copies in the relevant python, yaml and pbs files along
with the component surface triangualations which associate grid movement, and
FFDs which control that movement. Note that relevant environmental variables
and paths in the LAVA_design.py file are altered according to the
envVars.sh file entries, so ensure they are correct. For organization, ffds
and triSurfs sub folders are created.
# Takes a list of components (comps, first line below), and makes an
# appropriate subdirectory to perform the design optimization. A design file
# tree is created and all needed files are copied in, altered if need be.
#
# Currently, the MDAO-based LAVA_design_*.py file is too granularly hard-coded
# to allow for proper comp scripting, so for now if you want to make a new
# design, you must make a new LAVA_design_*.py file in auxFiles appropriately
# named for the components. All other files need not be changed (though some
# triSurfs and ffds may need to be added).
#
# For this tutorial, only the fuse, wing, and tail together are considered.
# --------------------------------------------------------------------------- #
comps=(fuse wing tail)
compList="${comps[*]}"
comp_list=$(IFS=_; echo "${comps[*]}")
compComlist=$(IFS=, ; echo "${comps[*]}")
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
mkdir -p design_${comp_list}
cd design_${comp_list}
mkdir -p ffds
mkdir -p triSurfs
cp $baseDir/auxFiles/LAVA_design_${comp_list}.py LAVA_design.py
cp $baseDir/auxFiles/LAVA_design_postProc.py .
cp $baseDir/auxFiles/LAVA_solver_design.yaml .
cp $baseDir/auxFiles/LAVA_design_tur_ath.pbs .
cp $baseDir/auxFiles/LAVA_design_rom_ait.pbs .
sed -i "/my_lava_suffix =/c\\my_lava_suffix='$LAVA_EXE_SUFFIX'" \
LAVA_design.py
sed -i "/wallCompNamesHere/c\\ names : [$compComlist]" \
LAVA_solver_design.yaml
sed -i "/#PBS -N/c\\#PBS -N LAVA_design_${comp_list}_rom_ait" \
LAVA_design_tur_ath.pbs
sed -i "/source path/c\\source $PY_VIRTUALENV_DIR" \
LAVA_design_tur_ath.pbs
sed -i "/#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_design_tur_ath.pbs
sed -i "s/pythonX.XX/python$PYTHON_VERSION/g" \
LAVA_design_tur_ath.pbs
sed -i "/#PBS -N/c\\#PBS -N LAVA_design_${comp_list}_tur_ath" \
LAVA_design_tur_ath.pbs
sed -i "/source path/c\\source $PY_VIRTUALENV_DIR" \
LAVA_design_tur_ath.pbs
sed -i "/#PBS -W/c\\#PBS -W group_list=$GROUP_ID" \
LAVA_design_tur_ath.pbs
for ((compI=0; compI<${#comps[@]}; compI++)); do
comp="${comps[$compI]}"
compCapps=$(echo "$comp" | tr '[:lower:]' '[:upper:]')
cp $baseDir/geom/$comp/${compCapps}_TRISURF.* triSurfs/
cp $baseDir/auxFiles/LAVA_design_FFD_${comp}.xyz ffds/
done
cd triSurfs
for file in *zip*; do
unzip -q -o $file
done
# --------------------------------------------------------------------------- #
Running
Currently, this tutorial utilizes the nonlinear optimizer
SNOPT, with the Python
interface provided by
pyOptSparse3. You may try
your hand at using alternative optimizers for this problem, though your mileage
may vary. pySurf is used to deform
junctions.
Running on the NAS Cluster
You can run the design either locally or on the NAS cluster. The
init_design.sh script will have created two pbs scripts for use on NAS. If
you aren't running all the tutorials on NAS, push the entire design_* sub
directory to nas to run.
Note that the pbs script will modify the LAVA_design.py file to have the
appropriate my_lava_suffix value once the job submits.
The charge group IDs of the pbs scripts, as well as the path to the Python
virtual environment you need to have set up on NAS should have been filled with
the variables you have set in envVars.sh file.
If running on 8 Athena nodes, the design process takes roughly 56 hours for the required 270 function evaluations.
Running on External Systems
To run the design locally (not recommended due to resource requirements),
navigate to the folder created by init_design.sh, and run the run_design.sh
script shown below.
# Assumes init_design.sh has been called and you are running this on local
# compute from a directory created by it.
# ---------------------------------------------------------------------------- #
baseDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
source $baseDir/envVars.sh
# Activate the python virtual environment.
source $PY_VIRTUALENV_DIR
# Set the LAVA lib suffix to the value within envVars.sh
sed -i "/my_lava_suffix =/c\\my_lava_suffix = '$LAVA_EXE_SUFFIX'" \
LAVA_design.py
# Do the design (omp threads set in envVars.sh).
if (( N_PROC > 1 )); then
mpiproc -np $N_PROC python LAVA_design.py | tee LAVA_design.out
else
python LAVA_design.py | tee LAVA_design.out
fi
# --------------------------------------------------------------------------- #
Python Script
The main script of this tutorial is the LAVA_design.py Python script that
will have been copied into the created design sub directory, which is
responsible for running the optimization problem using OpenMDAO, MPhys, and
pyLAVA. When the init script is run, it copies in the appropriate design python
script from auxFiles according to the components you requested and renames it
sans components. We will break down the contents of this script below, which is
the example given if the fuse, wing, and tail all were to be considered
(LAVA_design_fuse_wing_tail.py). As things are currently set up, you would
have to make a new LAVA_design_*.py file for a different component set.
Imports
import openmdao.api as om
from mphys import MPhysVariables, Multipoint
from mphys.scenarios.aerodynamic import ScenarioAerodynamic
from pylava.mphys.mphys_lava import LAVABuilder
from pygeo.mphys import OM_DVGEOCOMP
from pyspline import Curve
In the imports section, we import the necessary modules from OpenMDAO, MPhys,
pyLAVA, pyGeo, and pySpline. This includes the LAVABuilder class from
pylava.mphys.mphys_lava, which is used to create the LAVA flow solver
component for MPhys.
Read YAML
# Read the YAML file for lava options
with open("LAVA_solver_design.yaml", "r") as f:
lava_options = yaml.safe_load(f)
Here, we load the YAML configuration file into a Python dictionary. The
lava.yaml file contains all the input parameters for the LAVA flow solver.
LAVA MPhys Builder
# LAVA Builder
lava_builder = LAVABuilder(lava_options, scenario="aerodynamic",
lava_suffix=my_lava_suffix,
design_surf_fams=["wing", "fuse", "tail"],
functionals=["cl", "cd", "cmy"])
lava_builder.initialize(self.comm)
MPhys leverages
builders to create the
necessary components for a multidisciplinary analysis and optimization. When
instantiating the LAVABuilder, several arguments can be passed. In this
tutorial we pass the following:
lava_options: The dictionary of options for the LAVA flow and adjoint solvers, loaded fromlava.yamlabove.scenario: The MPhys scenario to be used. We use"aerodynamic"for aerodynamic analysis.lava_suffix: Specifies which compiled LAVA dynamic library to use. This must match the LAVA installation on your system.design_surf_fams: A list of surface family names that will be used for geometric design variables. In this case, we use thewing,fuse, andtailsurface families. Note that these families are specified in thegrid.bcboundary condition file.functionals: These are the aerodynamic functionals that will be set as outputs to the LAVA OpenMDAO Group, making them available for use as objectives or constraints. In this case, we usecl,cd, andcmy(lift, drag, and pitching moment coefficients).
Since the optimization problem minimizes drag subject to lift and pitching
moment constraints, cd serves as the objective, while cl and cmy are
constraints.
MPhys Setup
# == MPhys Setup ==
# Keep DVs at the top level
self.add_subsystem('dvs', om.IndepVarComp(), promotes=['*'])
# Add mesh to subsystems
self.add_subsystem('mesh', lava_builder.get_mesh_coordinate_subsystem())
# Add the geometry component from pyGeo (multi-component FFD)
self.add_subsystem('geometry', OM_DVGEOCOMP(type='multi'))
# We're cruisin
self.mphys_add_scenario('cruise', ScenarioAerodynamic(aero_builder=lava_builder))
# Ensure that the mesh and cruise coordinates are the same
self.connect(
f"mesh.{MPhysVariables.Aerodynamics.Surface.Mesh.COORDINATES}",
f"geometry.{MPhysVariables.Aerodynamics.Surface.Geometry.COORDINATES_INPUT}")
self.connect(
f"geometry.{MPhysVariables.Aerodynamics.Surface.Geometry.COORDINATES_OUTPUT}",
f"cruise.x_aero")
In the MPhys setup portion of the Multipoint OpenMDAO Group, several steps occur:
- An independent variable component
dvsis added to hold the design variables for the optimization problem. - A component
meshis added to output the undeformed surface mesh from the LAVA solver. - A
geometrycomponent is added using pyGeo'sOM_DVGEOCOMP, which handles the geometric design variables and deformation. - The scenario's
add_scenariomethod is called to add an aerodynamic scenario to the MPhys Group. - Connections are made between components: the undeformed surface mesh flows
from
meshtogeometry, and the deformed surface mesh flows fromgeometryto the aerodynamic scenario.
Most of this setup is standard for MPhys-based aerodynamic optimization problems, which is described in more detail in the MPhys documentation.
Geometry Parameterization
FFD Setup
# == FFD Setup ==
# Wing FFD
self.geometry.nom_addComponent(
comp="wing",
ffd_file=os.path.join("ffds", "LAVA_design_FFD_wing.xyz"),
triMesh=os.path.join("triSurfs", "WING_TRISURF.cgns")
)
# Fuselage and Vertical Tail FFD
self.geometry.nom_addComponent(
comp="fuse",
ffd_file=os.path.join("ffds", "LAVA_design_FFD_fuse.xyz"),
triMesh=os.path.join("triSurfs", "FUSE_TRISURF.cgns")
)
# Horizontal Tail FFD
self.geometry.nom_addComponent(
comp="tail",
ffd_file=os.path.join("ffds", "LAVA_design_FFD_tail.xyz"),
triMesh=os.path.join("triSurfs", "TAIL_TRISURF.cgns")
)
The call to
nom_addComponent
of the OM_DVGEOCOMP object is used to add a component to the geometry setup.
See pyGeo's OM_DVGEOCOMP
documentation
for more information on this method. We add three components (wing, fuselage,
and tail), each with:
comp: The name of the component.ffd_file: The path to the Plot3D file containing the Free-Form Deformation (FFD) volume for this component. The FFD volume controls how the aerodynamic surface deforms when design variables are applied.triMesh: The path to the surface triangulation file (stored as a.cgnsfile) for this component. See the DVGeometryMulti documentation for more information on this file.
Intersection Setup
# == Intersection Setup ==
# Note: Intersections must be defined before adding the pointset
# Wing-Fuse Intersection
DVGeoMulti.addIntersection(
compA="fuse",
compB="wing",
dStarA=0.081,
dStarB=0.005,
featureCurves=["wing_LE_0_CURVE", "wing_TE_0_CURVE", "wing_TE_1_CURVE"],
project=True,
marchDir=2,
includeCurves=True,
curveEpsDict={
'intersection': 1.e-4,
'wing_LE_0_CURVE': 1.e-6,
'wing_TE_0_CURVE': 8.e-6,
'wing_TE_1_CURVE': 8.e-6,
},
)
# Tail-Fuse Intersection
DVGeoMulti.addIntersection(
compA="fuse",
compB="tail",
dStarA=0.081,
dStarB=0.027,
featureCurves=["tail_LE_0_CURVE", "tail_TE_0_CURVE", "tail_TE_1_CURVE"],
project=True,
marchDir=2,
includeCurves=True,
curveEpsDict={
'intersection': 1.e-2,
'tail_LE_0_CURVE': 1.e-6,
'tail_TE_0_CURVE': 4.e-6,
'tail_TE_1_CURVE': 4.e-6,
}
)
# NOTE: Because we are working with a 2.7% scale model of the CRM,
# the default zero cutoff for the inverse distance weighted integral
# is too large and must be reduced
for intersections in DVGeoMulti.intersectComps:
intersections.eps = 1.e-28
Intersections between components must be explicitly stated via a call to the
addIntersection
function of the DVGeometryMulti class. Here we specify two intersections:
- Wing-Fuselage Intersection: Where the wing meets the fuselage. The
parameters
dStarAanddStarBcontrol the blend distance on each component,featureCurvesspecifies important geometry features to preserve, andcurveEpsDictdefines tolerances for fitting these curves. - Tail-Fuselage Intersection: Where the horizontal tail meets the fuselage, with similar parameters to control the deformation at the junction.
These intersections ensure that when the wing or tail deforms, the fuselage surface smoothly blends with these deformations, maintaining surface continuity and proper aerodynamic shape.
Additionally, because we are working with a 2.7% scale model of the CRM, the
default inverse distance weighted integral cutoff (eps) must be reduced to
prevent numerical issues in the intersection handling.
Pointset Setup
# == Pointset Setup ==
# Add points from LAVA's design surface
points = self.mesh.mphys_get_surface_mesh()
self.geometry.nom_add_discipline_coords(
MPhysVariables.Aerodynamics.Surface.Geometry,
points, applyIC=True)
The pointset setup specifies the surface points that will be used for geometric
design variables and constraints. The call to
self.mesh.mphys_get_surface_mesh() retrieves the entire surface mesh from the
LAVA Curvilinear solver for all families previously specified in the
design_surf_fams argument of the LAVABuilder. When passing all surface
points to the OM_DVGEOCOMP component, it will automatically organize and sort
the points into the appropriate components for deformation.
Design Variables Setup
# == Design Variable Setup ==
# Wing Twist
# Create a reference axis in the wing FFD
nRefAxPts = self.geometry.nom_addRefAxis(name="wingaxis", xFraction=0.25,
alignIndex="j", comp="wing")
nTwist = nRefAxPts
# Setup the global twist DVs for the wing FFD
def wingtwist(val, geo):
for i in range(0, nRefAxPts):
geo.rot_y["wingaxis"].coef[i] = val[i]
self.geometry.nom_addGlobalDV(dvName="wingtwist", value=np.zeros((nTwist)),
func=wingtwist, comp="wing")
# Wing Shape
# Setup the local section shape DVs for the wing FFD
nLocal = self.geometry.nom_addLocalDV(dvName="wingshape", axis="z", comp="wing")
# Tail Twist
# Create a reference axis for the tail FFD
xyz = np.array([[4.6750224, 0., 0.052832], [4.6750224, 0.3, 0.052832]])
axialCurve = Curve(x=xyz[:, 0], y=xyz[:, 1], z=xyz[:, 2], k=4)
nRefAxPts_tail = self.geometry.nom_addRefAxis(name="tailaxis", curve=axialCurve,
axis="x", comp="tail")
nTwist_tail = nRefAxPts_tail
# Setup the global twist DV for the tail FFD
def tailtwist(val, geo):
for i in range(0, nRefAxPts_tail):
geo.rot_y["tailaxis"].coef[i] = val[0]
self.geometry.nom_addGlobalDV(dvName="tailtwist", value=np.zeros((1)),
func=tailtwist, comp="tail")
In this portion of the Python script, we define the geometric design variables for the optimization problem. These include:
- Wing Twist: A global twist design variable that rotates the wing about a
reference axis (at 25% chord). A reference axis is created using
nom_addRefAxis, and the global twist is applied at multiple spanwise locations. - Wing Section Shape: Local shape design variables that allow each wing section to deform in the vertical (z) direction, enabling changes to the wing's aerodynamic profile.
- Tail Angle: A global twist design variable for the tail that rotates about a specified axis. The axis is defined by a B-Spline curve created from two endpoints with the same (x, z) coordinates but spanning the full tail length in the y-direction.
Please refer to this OM_DVGEOCOMP documentation for more information on the available options for design variables.
Geometric Constraints
# == Geometric Constraint Setup ==
# Setup surface triangulation
tri_file = os.path.join("triSurfs", "WING_TRISURF.tri")
f = FortranFile(tri_file, 'r')
# Read tri-file's vertice and connectivity info
nVerts, nTri = f.read_ints()
xyz = f.read_reals(dtype='f4').reshape((nVerts, 3))
conn = f.read_ints().reshape((nTri, 3)) - 1
tri_surf = np.zeros((nTri, 3, 3))
for i in range(3):
tri_surf[:, i, :] = xyz[conn[:, i], :]
self.geometry.nom_setConstraintSurface(tri_surf, surfFormat="point-point")
# Nonlinear thickness constraint
leList = np.loadtxt(os.path.join("constraint", "LE.dat"), skiprows=1)
teList = np.loadtxt(os.path.join("constraint", "TE.dat"), skiprows=1)
self.geometry.nom_addThicknessConstraints2D("thickcon", leList, teList, nSpan=40,
nChord=30, projected=True,
compNames=['wing'])
# Add fixed LE/TE constraints
self.geometry.nom_add_LETEConstraint('tecon', 0, 'ihigh', comp='wing')
self.geometry.nom_add_LETEConstraint('lecon', 0, 'ilow', comp='wing')
In this section, geometric constraints are applied to the wing to ensure that the optimized design meets physical requirements:
- Surface Triangulation: A surface triangulation file is read to represent the reference aerodynamic surface. This is used to define the constraint surface against which other constraints are measured.
- Thickness Constraints: Nonlinear constraints that ensure the wing maintains minimum thickness between leading and trailing edge points. These constraints are applied at 40 spanwise and 30 chordwise locations, and are projected onto the aerodynamic surface.
- Leading/Trailing Edge Constraints: Fixed constraints that prevent the leading and trailing edges of the wing from moving, maintaining the geometric definition of these important features.
These constraints work together to ensure the optimized design is physically realizable while meeting the aerodynamic objectives.
OpenMDAO Setup
# == OpenMDAO Setup ==
# Add the DVs to the independent variables in OpenMDAO and connect them to pyGeo
self.dvs.add_output("aoa", val=2.6527854, units='deg')
self.connect("aoa", "cruise.lava_aoa")
self.dvs.add_output("wingtwist", val=np.zeros((nTwist)))
self.connect("wingtwist", "geometry.wingtwist")
self.dvs.add_output("wingshape", val=np.zeros((nLocal)))
self.connect("wingshape", "geometry.wingshape")
self.dvs.add_output("tailtwist", val=np.array([-0.28479275]))
self.connect("tailtwist", "geometry.tailtwist")
# Define the design variables for OpenMDAO
self.add_design_var("aoa", lower=-3.0, upper=3.5, scaler=0.3)
self.add_design_var("wingtwist", lower=-10.0, upper=10.0, scaler=0.03)
self.add_design_var("wingshape", lower=-0.1, upper=0.1, scaler=7.0)
self.add_design_var("tailtwist", lower=-5.0, upper=5.0, scaler=0.07)
# Add the aerodynamic objective and constraints
self.add_objective("cruise.cd", scaler=40.0)
self.add_constraint("cruise.cl", equals=0.5, scaler=2.0, linear=False)
self.add_constraint("cruise.cmy", equals=0.0, scaler=1.0, linear=False)
# Add the geometric constraints
self.add_constraint("geometry.thickcon", lower=1.0, scaler=1.0)
self.add_constraint("geometry.tecon", equals=0.0, scaler=1.0, linear=True)
self.add_constraint("geometry.lecon", equals=0.0, scaler=1.0, linear=True)
In this section, the OpenMDAO optimization problem is configured:
- Design Variables: The independent variable component adds output variables for angle of attack, wing twist, wing shape, and tail twist. Each design variable has specified lower and upper bounds to constrain the design space, and scalers to normalize the variables for the optimizer.
- Objective Function: The drag coefficient (
cruise.cd) is set as the objective to minimize, with a scaler of 40.0 to improve optimizer scaling. - Aerodynamic Constraints: Two equality constraints ensure that the lift
coefficient (
cruise.cl) equals 0.5 and the pitching moment coefficient (cruise.cmy) equals 0.0. - Geometric Constraints: The thickness, trailing edge, and leading edge constraints are added with appropriate bounds and scalers.
Main Execution
# Instantiate the MDAO problem
prob = om.Problem(allow_post_setup_reorder=False)
prob.model = Top()
# Set the optimizer
prob.driver = om.pyOptSparseDriver()
prob.driver.options["optimizer"] = "SNOPT"
prob.driver.opt_settings = {
"Problem type": "Minimize",
"Major feasibility tolerance": 1e-6,
"Major optimality tolerance": 1e-6,
"Hessian": "Full memory",
"Function precision": 1e-8,
"Verify level": -1,
"New superbasics limit": 400,
"Minor iterations limit": 10000,
"Iterations limit": 10000000,
"Print frequency": 1,
"Summary frequency": 1,
}
# History file for potentially restarting the optimization later
prob.driver.options['hist_file'] = 'history.db'
# Attach recorder to the driver
recorder = om.SqliteRecorder('driver_cases.db', record_viewer_data=False)
prob.driver.add_recorder(recorder)
prob.driver.recording_options['record_desvars'] = True
prob.driver.recording_options['record_constraints'] = True
prob.driver.recording_options['record_objectives'] = True
prob.setup(mode="rev")
om.n2(prob, show_browser=False, outfile='mphys_lava.html')
prob.run_driver()
In the main execution block:
- An OpenMDAO
Problemobject is instantiated with theTop()model, which contains all the components and connections defined above. - The optimizer is set to SNOPT (a sparse nonlinear optimizer) via the
pyOptSparseDriver. - SNOPT optimizer settings are configured to control convergence tolerances, iteration limits, and output verbosity.
- A history file (
history.db) is configured to allow for potential optimization restart. - A recorder is attached to the driver to capture and store all design
variables, constraints, and objectives at each optimization iteration in a
SQLite database (
driver_cases.db). - The problem setup is called with
mode="rev"to configure the system for reverse-mode (adjoint) derivatives, which is necessary for efficient gradient computation. - An interactive N2 diagram is generated and saved to
mphys_lava.html, showing the component hierarchy and variable connections in the model. - Finally,
prob.run_driver()executes the optimization, performing the iterative design optimization to minimize drag while satisfying the lift and pitching moment constraints.
Post-Processing
OpenMDAO provides functionality for post-processing optimization results. In this tutorial, we are leveraging the driver recording feature. Much more detail is provided in the OpenMDAO documentation, so we encourage you to read through that for more information.
Post-Processing using the Case Database
We will be using the following Python script extract design variable, constraint, and objective values from the optimization case history:
# ==================================================================
# === Post-Processing ==============================================
# ==================================================================
""" This script is an example of how to post-process the CRM
optimization case to extract and analyze specific design
iterations with pyLAVA.
See the documentation for more details.
you can run the script like this:
mpirun -np 2 mbind.x -t 14 python run_post.py
"""
# === Import =======================================================
from mpi4py import MPI
import os
import openmdao.api as om
from LAVA_design import Top
# ==================================================================
# == Helper Functions ==============================================
# analysis-start
def runAnalysis(prob, case, fileSuffix) :
# Get the output directory
out_dir = prob.get_outputs_dir()
# Load the case and run the model
prob.load_case(case)
prob.run_model()
# Get lava and write the surface output
lava = prob.model.cruise.coupling.aero_solver
lava.writeSurface(os.path.join(out_dir,f"surface.{fileSuffix}.plt"),
fields=["iblank", "yplus", "cp", "cf", "cfx", "cfy", "cfz"])
# analysis-end
# print-case-start
def printCase(label, case):
print(f"\n{label}")
print("-" * len(label))
print("Objectives:")
for name, val in case.get_objectives().items():
print(f" {name}: {val[0]:.8f}")
print("Constraints:")
for name, val in case.get_constraints().items():
print(f" {name}: {val[0]:.8f}")
# print-case-end
# ==================================================================
# === Main Script ==================================================
if __name__ == "__main__":
# Instantiate the MDAO problem
prob = om.Problem()
prob.model = Top()
prob.setup(mode="rev")
# reader-start
cr = om.CaseReader('LAVA_design_out/cases.sql')
# reader-end
# run-start
# Get the first function eval
case = cr.get_case(0)
runAnalysis(prob, case, "initial")
# Get the last function eval
case = cr.get_case(182)
runAnalysis(prob, case, "optimized")
# run-end
# print-start
# Print the initial and optimized objectives
if MPI.COMM_WORLD.rank == 0 :
printCase("INITIAL CASE", cr.get_case(0))
printCase("OPTIMIZED CASE", cr.get_case(182))
# print-end
# ==================================================================
This script should be run in the same way as the LAVA_design.py script, i.e.,
in an environment where pyLAVA, OpenMDAO, MPhys, and pyGeo are available. We
encourage you to go take a look at the Wing Twist Optimization using OpenMDAO
Tutorial
to read a breakdown of this post-processing script.
Optimization Results
For us, this optimization problem took 56 hours on 8 Turin Athena Nodes (8 x 256 CPUs) to complete 272 function evaluations, after which SNOPT exited with
SNOPTC EXIT 40 -- terminated after numerical difficulties
SNOPTC INFO 41 -- current point cannot be improved
This is not uncommon for a large optimization problem such as this one. Through analysis of the optimization results, iteration number 182 was chosen as the final design. The following table and figure provide a comparison between the initial design and the chosen optimized design (iteration 182).
| Initial Value | Optimized Value | |
|---|---|---|
| Drag Coefficient \(C_D\) [counts] | \(280.6\) | \(263.7\) |
| Lift Coefficient \(C_L\) | \(0.5000\) | \(0.5000\) |
| Pitching Moment Coefficient \(C_M\) | \(-5.073 \times 10^{-6}\) | \(7.484 \times 10^{-7}\) |
| Angle of Attack | \(2.653\) | \(3.500\) |
| Tail Angle | \(-0.2848\) | \(-1.109\) |
SNOPT also provides a history of the optimization process, which is visualized in the following figure.
Relevant Publications
-
Gray, J. S., Hwang, J. T., Martins, J. R. R. A., Moore, K. T., and Naylor, B. A., "OpenMDAO: An Open-Source Framework for Multidisciplinary Design, Analysis, and Optimization," Structural and Multidisciplinary Optimization, Vol. 59, No. 4, 2019, pp. 1075--1104. https://doi.org/10.1007/s00158-019-02211-z ↩
-
Yildirim, A., Jacobson, K. E., Anibal, J. L., Stanford, B. K., Gray, J. S., Mader, C. A., Martins, J. R. R. A., and Kennedy, G. J., "MPhys: A Modular Multiphysics Library for Coupled Simulation and Adjoint Derivative Computation," Structural and Multidisciplinary Optimization, Vol. 68, No. 15, 2025. https://doi.org/10.1007/s00158-024-03900-0 ↩
-
Wu, E., Kenway, G., Mader, C. A., Jasa, J., and Martins, J. R. R. A., "[pyOptSparse:]{.nocase} A Python Framework for Large-Scale Constrained Nonlinear Optimization of Sparse Systems," Journal of Open Source Software, Vol. 5, No. 54, 2020, p. 2564. https://doi.org/10.21105/joss.02564 ↩
Including Immersed Geometry
Immersed boundaries are a feature within the lavacurv solver which allows
portions of the computational domain to have a momentum penalty term applied,
effectively enforcing a wall-body-like effect on the flow if the penalty term
is strong enough. Immersed triangulated surfaces are supplied in the input
yaml, and all nodes within them are tagged as immersed. There can be multiple
surfaces and they can all have settings (see the immersedBoundaries yaml
settings).
Application of immersed boundaries is utilized mainly for two purposes:
- There are small shapes which are annoying to grid and only their downstream/bluff-body effects matter.
- There are components which intersect with other components in a manner which makes collar grid generation challenging and time consuming.
For the former purpose, a small uniformly spaced immersion box can be placed into the grid system and the immersed surface will introduce an approximation of the shape.
For the latter, we likely want comparable flow physics to be introduced by the immersed effects as a viscous wall BC, as well as integrated loads. In this case, we seek to produce 'body-fitted' immersion grids which both conform to the immersed surface as well as possible, AND have viscous wall spacing at the immersed boundary surface.
In this tutorial we will be adding a body-fitted flow-through nacelle to the body-wing-tail CRM, then using a body-fitted immersed pylon to connect it to the wing.
Body-Fitted Immersed Component Scripting
There are many strategies for scripting body-fitted immersion grids. The general idea though is to start with the fewest or simplest surface grids on portions of the immersed geometry which will be touching the fluid. Grids on the surface will be grown both inward and outward from the immersed surface so that there is viscous spacing on both sides of the immersed surface. Similarly to regular body-fitted grids, the better these grids represent the curvature of your immersed boundary the better its representation and thus your solution will be.
The pylon's immersed surface triangulation is shown below.
The CAD this surface was built on was slightly extruded to extend into the wing and pylon bodies, as seen below. Without these proper intersections, integrated loads and immersed boundary enforcement won't be correct at the components' intersections.
When considering this immersed surface, several factors influenced the initial choice of grids, which are shown below.
- The 'aft' grid (orange) fills the aft region of the pylon, and intersects with the wing component. This will be extended out from the pylon in a doubly-viscous manner. When the internals of the surface are square-like this is a good option since extension outward is easily script-able, and better fills the internal space than growing inward on all sides.
- The 'nose' grid (blue) handles the intersection with the nacelle. We don't care about what happens at the 'bottom' of the immersed surface's nose because it will be inside the nacelle geometry. We will grow inward and outward from the nose top. Grids grown inward here will just be optimized out during connectivity if they pass through the nacelle.
- The 'cusp' grid (green) is similar to the nose, but has been separated in order to prevent the nose from being hard to hyperbolically grow. Feel free to make many easy to create/grow patches on immersed surfaces to reduce grid scripting iterations.
The scripted building process for the pylon's aft section begins with re-distributing the internal aft block to be viscous in all directions but stream: we do not need to resolve the trailing edge with viscous spacing.
set npVisc 65
SrapRedist PYLON_AFT.x v.[IBP_nVolP 1] 1 -k 1 1 0 \
[list 1 -1 $npVisc $Par(ds,wall) $Par(ds,wall)]
SrapRedist v.[IBP_nVolP 1] v.[IBP_nVolP 2] 1 -l 1 1 0 \
[list 1 -1 $npVisc $Par(ds,wall) $Par(ds,wall)]
We then repeatedly take one of the sides of the block, orient it to grow in the direction of our choice, grow it, then recombine it with the original block. Below is that process with the trailing edge side (jMax), and outboard side (kMax), but this is subsequently performed with kMin, and finally lMin. Note that the TE is translated, concatenated and redistributed, while the outboard is grown to make the grown cells more uniform. The bottom (lMin side) is translated, redistributed and concatenated to get a smoothed effect more manually because it is not well posed for hyperbolic growth.
# TE
# --------
ExtractSubs v.[IBP_nVolP 2] s.[IBP_nSurP 1] [list 1 -1 -1 1 -1 1 -1]
GedTranslate s.[IBP_nSurP 1] s.[IBP_nSurP 2] \
0.0685153964825696 0.002566620622606264 -0.001506420730025947
ConcatGridsn [list s.[IBP_nSurP 1] s.[IBP_nSurP 2]] v.[IBP_nVolP 1] j 0
SrapRedist v.[IBP_nVolP 1] v.[IBP_nVolP 3] 1 j 1 5 0 \
[list 1 -1 $Par(sr) $dsJEndAftBdy $Par(ds,glb) $Par(ds,glb)]
ConcatGridsn [list v.[IBP_nVolP 2] v.[IBP_nVolP 3]] v.[IBP_nVolP 1] j 1
# --------
# Outboard side.
# --------
ExtractSubs v.[IBP_nVolP 1] s.[IBP_nSurP 1] [list 1 1 -1 -1 -1 1 -1]
SwapInd s.[IBP_nSurP 1] s.[IBP_nSurP 2] [list swapkl revk]
GenHypVolGrid s.[IBP_nSurP 2] v.[IBP_nVolP 2] \
[list \
hyptan \
specsr \
$Par(sr) \
$Par(md) \
$Par(ds,wall) \
$Par(ds,glb) \
$Par(klayer) \
] \
[list -2 -2 -2 -2] \
[list 1.5 150 3]
SwapInd v.[IBP_nVolP 2] v.[IBP_nVolP 3] [list swapkl revl]
ConcatGridsn [list v.[IBP_nVolP 1] v.[IBP_nVolP 3]] v.[IBP_nVolP 2] k 1
# --------
Once the final extended block has been created, the volumes can be pulled out using grid delineation counts found during the extension process, as shown below for the first two of the 12 aft grids. These blocks are re-oriented so that their lMin sides lie 'on' the immersed boundary to more intuitively see its shape in overgrid.
puts "\tBuilding pylon aft ..."
# --------
IBP_incVol
# --------
ExtractSubs PYLON_AFT.x v.[IBP_nVolP 1] \
[list 1 1 $npJAftBdy \
1 $npKAftIn \
1 $npLAftBot]
SwapInd v.[IBP_nVolP 1] v.[IBP_nVol] [list revl swapk]
# --------
IBP_incVol
# --------
ExtractSubs PYLON_AFT.x v.[IBP_nVolP 1] \
[list 1 $npJAftBdy -1 \
1 $npKAftIn \
1 $npLAftBot]
SwapInd v.[IBP_nVolP 1] v.[IBP_nVol] [list revl swapk]
# --------
The final aft volume set is shown below.
The nose and cusp top grids both follow the same strategy, exemplified below with the nose grids. First, grow outward from the surface. Then split the grid with overlap and extract the L1 surface of the outward volumes, flip, and grow inward.
puts "\tBuilding pylon nose ..."
# --------
GenHypVolGrid PYLON_NOSE.x v.[IBP_nVolP 1] \
[list \
hyptan \
specsr \
$Par(sr) \
$Par(md) \
$Par(ds,wall) \
$Par(ds,glb) \
$Par(klayer) \
] \
[list -5 -5 -5 -5] \
[list 1.5 150 3]
SplitToNgrids v.[IBP_nVolP 1] v.[IBP_nVolP 3] 2 k 0 7
# --------
IBP_incVol
# --------
ExtractSubs v.[IBP_nVolP 2] v.[IBP_nVol] [list 1 1 -1 1 -1 1 -1]
# --------
IBP_incVol
# --------
ExtractSubs v.[IBP_nVolP 1] v.[IBP_nVol] [list 2 1 -1 1 -1 1 -1]
# --------
IBP_incVol
# --------
ExtractSubs v.[IBP_nVolN 2] s.[IBP_nSurP 1] [list 1 1 -1 1 -1 1 1]
ReverseInd s.[IBP_nSurP 1] s.[IBP_nSurP 2] [list revk]
GenHypVolGrid s.[IBP_nSurP 2] v.[IBP_nVol] \
[list \
hyptan \
specsr \
$Par(sr) \
$Par(md) \
$Par(ds,wall) \
$Par(ds,glb) \
$Par(klayer) \
] \
[list -5 -5 -5 -5] \
[list 1.5 150 3]
# --------
IBP_incVol
# --------
ExtractSubs v.[IBP_nVolN 2] s.[IBP_nSurP 1] [list 1 1 -1 1 -1 1 1]
ReverseInd s.[IBP_nSurP 1] s.[IBP_nSurP 2] [list revk]
GenHypVolGrid s.[IBP_nSurP 2] v.[IBP_nVol] \
[list \
hyptan \
specsr \
$Par(sr) \
$Par(md) \
$Par(ds,wall) \
$Par(ds,glb) \
$Par(klayer) \
] \
[list -5 -5 -5 -5] \
[list 1.5 150 3]
# --------
The final nose and cusp grids are shown below in closeup, with the entire pylon body-fitted immersed set following.
Clearly the body-fitted immersed method takes some setup but with practice it is usually simply making some surface then growing them inward and outward (the block of the aft here was a fancier example), which is MUCH faster than planning and growing weird collar grids. To show the payoff for using this method, see the below comparison of what the pylon would look like if the immersed surface were just tagging the existing grid nodes (left) as opposed to the body-fitted immersed grid nodes (right).
Building And Connecting the Grid
We will be leveraging the power of components, using the same logic as the scripting and connectivity tutorials.
Build the grid by running the run_buildGrid_immBnd.sh script, which calls the
buildProjectGrid_nearBody_immBnd.tcl master grid script to create the
nearBody, then the octFarfield generator to generate the offBody, then
combines the two. Note that the nacelle component has a resolution box placed
around it as part of its component so that we don't have to use a different
nearBody surface triangulation for the offbody generation. Additionally, this
copies over any immersed boundaries, which should be modified in the scripts as
needed when copied over to account for parameters like pitch, etc. The naming
convention is usually immGeom_COMPNAME_SUBNAME.i.tri.
To run connectivity, follow the instructions in the connectivity tutorial,
keeping in mind that you must use the init_connectivity_immBnd.sh script
instead of init_connectivity.sh. Running connectivity locally with 55 threads
takes roughly 10.6 seconds and has 0 orphans.
B2BExtractor :
extractB2Bs : true
onlyFullB2Bs : true
...
immersedBoundaries:
-
fileName : immGeom_PYLON.i.tri
fileType : tri
bcname : pylon
...
bc :
-
names : [pylon]
type : BCWallViscous
location : offBody
Priorities become significant when adding new components to an existing system. We want the newly added body-fitted immersed grids to be kept so that the immersed geometry is well represented (it's why they're there in the first place). However, we see below on the left that simply adding them in naively causes them to be mostly removed. This is because the existing nearBody grids have a priority of at least 100. To keep them and obtain the grid optimization on the right, the priorities are updated as seen below.
overset :
zoneSpecific:
-
# All non-nose or collar near-body zones.
zones : [1, 9-22, 29-40]
priority : 100.0
-
# Non-aft-top pylon zones.
zones : [42-47, 54-61]
priority : 200.0
-
# Nacelle resolution zones.
zones : [41]
priority : 400.0
-
# All nose and collar near-body zones.
zones : [2, 3-8, 23-28]
priority : 1000.0
-
# Pylon aft top zones.
zones : [48-53]
priority : 1.0e+10
It is also important to note that while it is possible to allow immersed grids
to intersect with wall geometry, this is not the strategy employed here.
Immersed-wall component intersection is being looked into as a design feature,
and employs an immersed method which is more of a boundary condition than a
simple penalty term. In such a situation, the zones pertaining to the immersed
boundary can be stated within the immersed entry as zones during connectivity
and the solution, and they would become immersed inside the wall geometry
instead of blanked, with a special correction applied during solution. This
feature has not been extensively tested and is still experimental. Here, we
don't care if minor pylon shape errors exist very close to the intersecting
boundaries with the wing and nacelle, and so we blank any immersed grids inside
those wall shapes, but set the priorities such that they are retained very
close to the walls. Below is a picture of the grids near the wing-pylon
intersection.
The overlapper utility run after the connectivity process creates panel weights on both the walls and the immersed boundaries, and accounts for intersections between the two, as seen below in which the red lines are the intersection curves.
Running the Solver
The steps for running the solver are effectively the same as the RANS
tutorial, tutorial, but the 'init_RANS_immBnd.sh' script
is used instead of init_RANS.sh, and you plan to run on NAS you need to
additionally push any immGeom_* files (in this case just
immGeom_PYLON.i.tri) there if you weren't building the grid on NAS.
The LAVA_solver_RANS_immBnd.yaml input file has the following additions to
its LAVA_solver_RANS.yaml sibling, shown below.
immersedBoundaries:
-
fileName : ../immGeom_PYLON.i.tri
fileType : tri
bcname : pylon
updatetype : drivetozero
interpOffsetDist : 4.875e-05
timescale : 1.0e-3
timescalevaluestype : specified
timescaleintervaltype : iter
timescaleramptype : discrete
timescaleinterval : [100, 200, 300, 400]
timescalevalues : [1.0e-4, 1.0e-5, 1.0e-6, 1.0e-7]
...
bc :
-
names : [fuse, wing, tail, nacelle]
type : BCWallViscous
-
names : [pylon]
type : BCWallViscous
wallmodel : saLaw
The immersed pylon is placed in its own BC with a wall model. When calculating surface variables, it will interpolate from the solution according to the wall model law (sa in this case). Note that at intersections with other components, the cell center of intersected elements could be within the intersected body, thus making interpolation from the solution incorrect. During the overlapper panel-weight generation, interpolation locations for intersected immersed triangles are moved to guaranteed wetted locations to account for this possible inaccuracy.
The immersedBoundaries yaml sub-dict can have different entries for each
immersed surface you have defined. In this case its just the pylon. Each entry
is linked to the appropriate BC name. The interpOffsetDist is the wall-model
interpolation distance off the wetted cell center for load calculations. The
timescale settings have to do with how the momentum penalty is applied. The
smaller the timescaleValues, the more of a penalty is applied: we have found
that 1e-7 or 1e-8 is usually required to impose a wall-like effect on the flow.
The update type is how the immersed penalty is applied. Here we are pushing the
momentum to zero within the immersed region rather than hard-setting it (which
tends to be unstable). The values of the timescale also ramp over a series of
intervals, as starting out with the most aggressive momentum penalty can be
numerically unstable. Here, the final timescale is applied after timestep 400.
Upon submitting the solver, the following warning pops up:
--------------------------------------------------------------------------------------------------------------------------------------------
Warning msg on proc(0) : Could not find one or more donor cells for IB Cells and/or their offsets - writing to IBSurf_elemFailedInterps.plt.
--------------------------------------------------------------------------------------------------------------------------------------------
This means that some of the immersed surface elements with non-zero panel
weights couldn't find legal computational cells to interpolate their wall model
values from. Let's investigate why this is the case. Alter the
LAVA_solver_RANS.yaml file in your solution subdirectory by adding the
following entries to the curvsolver and overlapper sub-dictionaries:
curvsolver:
writeIBWallModelInterpNodes : true
overwriteIntegrationWeights : true
overlapper:
writeIntersections : true
This will force the solver to re-calculate the panel weights with the overlapper utility. The following files will be written in the overlapper directory:
overlap_wallElemFracs.plt: wall panel weights in a viewable format.overlap_IBElemFracs.plt: immersed panel weights in a viewable format.overlap_isects_final.dat: the intersection curves between immersed and wall geometry.IBSurf_matchLocVecs.dat: The vectors of wall model interpolation from immersed surface elements.
If we re-run the solver and open these files (along with the
IBSurf_elemFailedInterps.plt file written in the solution directory) we can
perform the following assessment. The left and right figures below show the
intersections of the pylon with the wing and nacelle, respectively. Panel
weight fractions are shown on the immersed surface, the intersection curves are
show in red, and the immersed wall model interpolation vectors are shown in
teal for elements which have non-zero integrable area. Note how the
interpolation vectors have been repositioned to a fluid location if the cell
has been intersected.
The intersection with the wing is properly (normally-ish) intersecting, through generally-orientated tri-elements. The intersection with the nacelle is along a feature curve of the triangulated surface (the triangles respect that surface), and so the intersections with the nacelle is along many triangle edges: thus the clustering of interpolation vectors near the nacelle surface. The pylon geometry intersects the nacelle properly along its length, but note how at the trailing edge the pylon geometry abuts the nacelle and is more parallel than intersecting.
The immersed elements which failed to find legal interpolations are shown below on the left. Note how they are all on the nacelle trailing edge. The intersection curves are shown in red and at the trailing edge we see that the parallel alignment has caused spurious intersections to have been found due to tolerance issues. Any integrable surface element which understands it intersects with another component will have a non-zero fraction and will attempt to find elements from which to interpolate field values. In this case, the 'intersecting' (abutting) geometry has normals pointing in different directions, and so any interpolation vectors from their elements will look inside the intersected geometry - thus the error. This is shown more clearly in the left figure below, in which the pylon geometry is red and the nacelle is grey. 'Parallel' geometry intersection tolerance uncertainty is a known issue which will be addressed at some point in the future, but is not an issue if you ensure your immersed geometries properly intersect the relevant wall geometry.
Here, these interpolation problem cells are not an issue because while their panel weights are non-zero at portions of the abutting geometry (as below - pylon left and nacelle right), the geometry should technically be non-integrable and the solver will set their integration fractions to 0 at runtime if no integration location can be found.
Solution Assessment
You can assess this solution convergence using the same interrogations performed in the RANS tutorial.
The videos below show a sweep of the converged solution's Mach and eddy viscosity ratio along the pylon, with roll-up occurring along its length indicative of the viscous and inviscid effects the pylon has on the flow within the pressurized region underneath the wing.
Tutorials
CRM Wing Body Steady RANS
A common application of the LAVA Curvilinear solver is aerodynamic performance prediction using steady-state Reynolds Averaged Navier-Stokes (RANS) analysis. In this example, the process for obtaining the steady-state solution for the wing body configuration of the Common Research Model will be laid out. The following items are:
- Structured Overset Grid System
- Connectivity
- Flow Solve
- Integrated Loads Extraction
- Cp Extraction (via Tecplot)
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver and utilities installed and your environment properly setup, see LAVA Installation Guide
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | grid file |
| grid.x.ihc | grid file with hole cutting |
| INTOUT | connectivity file |
| panel_weights.dat | connectivity panel weights |
| grid.bc | grid bc file |
| grid.b2b | grid block-to-block file |
| connectivity.yaml | connectivity input file |
| run.yaml | solver input file |
The files should be organized like this
├── grid.b2b
├── grid.bc
├── grid.x
├── grid.x.ihc
├── INTOUT
├── job_athena.pbs
├── overlapper
│ └── panel_weights.dat
└── run.yaml
Structured Overset Grid System
The structured overset grid, grid.x, for the CRM wing body configuration consists of a main fuselage (blue), fuselage nose cap (red), wing/fuselage collar (green), main wing (maroon), wing outboard cap (gold), and octree based Cartesian off-body grid (black). The system consists of 5 near-body zones, 149 off-body Cartesian zones, and a total of 19,187,657 grid points. Boundary conditions for the grid system consist of no-slip walls for each l-direction = 1 near-body grid (assuming a j,k,l grid orientation), symmetry plane boundaries are specified for all surfaces on the y=0.0 plane, and far-field Riemann invariant boundary conditions are used for the outer-boundary of the Cartesian off-body grids. All non-specified boundaries are assumed to be either overset or block-2-block boundary conditions. An example of the ASCII boundary condition specification file (grid.bc) is given below:
!----------------------------------------------------------------------------------
! Family nz jbeg,jend kbeg,kend lbeg,lend
!----------------------------------------------------------------------------------
fuse 1 1 352 1 125 1 1
symm 1 352 352 1 125 1 54
symm 1 1 352 1 1 1 54
symm 1 1 352 125 125 1 54
fuse 2 1 49 1 25 1 1
symm 2 1 49 1 1 1 54
wing 3 1 286 1 52 1 1
wing 4 1 286 1 264 1 1
wing 5 1 109 1 69 1 1
far 6 1 1 1 19 1 19
... .. .. .. .. .. .. ..
!----------------------------------------------------------------------------------
! Family nz jbeg,jend kbeg,kend lbeg,lend
!----------------------------------------------------------------------------------
fuse 1 1 352 1 125 1 1
symm 1 352 352 1 125 1 54
symm 1 1 352 1 1 1 54
symm 1 1 352 125 125 1 54
fuse 2 1 49 1 25 1 1
symm 2 1 49 1 1 1 54
wing 3 1 286 1 52 1 1
wing 4 1 286 1 264 1 1
wing 5 1 109 1 69 1 1
far 6 1 1 1 19 1 19
... .. .. .. .. .. .. ..
!----------------------------------------------------------------------------------
! Family nz jbeg,jend kbeg,kend lbeg,lend
!----------------------------------------------------------------------------------
fuse 1 1 352 1 125 1 1
symm 1 352 352 1 125 1 54
symm 1 1 352 1 1 1 54
symm 1 1 352 125 125 1 54
fuse 2 1 49 1 25 1 1
symm 2 1 49 1 1 1 54
wing 3 1 286 1 52 1 1
wing 4 1 286 1 264 1 1
wing 5 1 109 1 69 1 1
far 6 1 1 1 19 1 19
symm 6 1 19 1 1 1 19
far 6 1 19 1 19 1 1
far 7 19 19 1 19 1 19
symm 7 1 19 1 1 1 19
far 7 1 19 1 19 1 1
far 8 1 1 1 51 1 19
far 8 65 65 1 51 1 19
far 8 1 65 51 51 1 19
far 8 1 65 1 51 1 1
far 9 1 1 1 21 1 37
far 10 19 19 1 21 1 37
far 11 1 1 1 35 1 37
far 11 65 65 1 35 1 37
far 11 1 65 35 35 1 37
far 12 1 1 1 19 1 19
symm 12 1 19 1 1 1 19
far 12 1 19 1 19 19 19
far 13 19 19 1 19 1 19
symm 13 1 19 1 1 1 19
far 13 1 19 1 19 19 19
far 14 1 1 1 51 1 19
far 14 65 65 1 51 1 19
far 14 1 65 51 51 1 19
far 14 1 65 1 51 19 19
symm 15 1 69 1 1 1 35
far 15 1 69 1 35 1 1
far 16 1 1 1 19 1 21
symm 16 1 51 1 1 1 21
far 17 51 51 1 19 1 21
symm 17 1 51 1 1 1 21
far 18 1 1 1 21 1 21
far 18 129 129 1 21 1 21
far 20 1 1 1 19 1 37
symm 20 1 35 1 1 1 37
far 21 35 35 1 19 1 37
symm 21 1 35 1 1 1 37
far 22 1 1 1 21 1 37
far 23 51 51 1 21 1 37
far 24 1 1 1 19 1 21
symm 24 1 51 1 1 1 21
far 25 51 51 1 19 1 21
symm 25 1 51 1 1 1 21
far 26 1 1 1 21 1 21
far 26 129 129 1 21 1 21
symm 27 1 69 1 1 1 35
far 27 1 69 1 35 35 35
symm 28 1 69 1 1 1 37
symm 29 1 53 1 1 1 21
symm 30 1 53 1 1 1 21
symm 33 1 37 1 1 1 37
symm 34 1 37 1 1 1 37
symm 37 1 53 1 1 1 21
symm 38 1 53 1 1 1 21
symm 40 1 69 1 1 1 37
symm 41 1 69 1 1 1 37
symm 42 1 53 1 1 1 21
symm 43 1 53 1 1 1 21
symm 46 1 37 1 1 1 37
symm 47 1 37 1 1 1 37
symm 50 1 53 1 1 1 21
symm 51 1 53 1 1 1 21
symm 53 1 69 1 1 1 37
symm 54 1 69 1 1 1 37
symm 55 1 53 1 1 1 21
symm 56 1 53 1 1 1 21
symm 59 1 37 1 1 1 37
symm 60 1 37 1 1 1 37
symm 63 1 53 1 1 1 21
symm 64 1 53 1 1 1 21
symm 66 1 69 1 1 1 37
symm 67 1 69 1 1 1 37
symm 68 1 53 1 1 1 21
symm 69 1 53 1 1 1 21
symm 72 1 37 1 1 1 37
symm 73 1 37 1 1 1 37
symm 76 1 53 1 1 1 21
symm 77 1 53 1 1 1 21
symm 79 1 69 1 1 1 37
symm 80 1 69 1 1 1 37
symm 81 1 53 1 1 1 21
symm 82 1 53 1 1 1 21
symm 85 1 37 1 1 1 37
symm 86 1 37 1 1 1 37
symm 89 1 53 1 1 1 21
symm 90 1 53 1 1 1 21
symm 92 1 69 1 1 1 37
symm 93 1 69 1 1 1 37
symm 94 1 37 1 1 1 21
symm 95 1 53 1 1 1 21
symm 98 1 21 1 1 1 37
symm 99 1 21 1 1 1 37
symm 102 1 37 1 1 1 21
symm 103 1 37 1 1 1 21
symm 106 1 69 1 1 1 37
symm 107 1 101 1 1 1 37
symm 108 1 53 1 1 1 21
symm 109 1 69 1 1 1 21
symm 112 1 37 1 1 1 37
symm 113 1 37 1 1 1 37
symm 119 1 53 1 1 1 21
symm 120 1 53 1 1 1 21
symm 123 1 133 1 1 1 37
symm 125 1 165 1 1 1 37
symm 126 1 53 1 1 1 21
symm 127 1 69 1 1 1 21
symm 131 1 37 1 1 1 37
symm 132 1 37 1 1 1 37
symm 139 1 53 1 1 1 21
symm 140 1 53 1 1 1 21
symm 146 1 197 1 1 1 37
symm 148 1 293 1 1 1 37
symm 149 1 389 1 1 1 69
symm 153 1 325 1 1 1 37
The block-2-block boundary conditions can be generated using the b2bExtractor utility program using the simple command:
!----------------------------------------------------------------------------------------------------------------------------
! BlkID js je ks ke ls le DonorID djs dje dks dke dls dle tx ty tz
!----------------------------------------------------------------------------------------------------------------------------
3 1 1 1 -1 1 -1 3 -1 -1 1 -1 1 -1 1 2 3
3 -1 -1 1 -1 1 -1 3 1 1 1 -1 1 -1 1 2 3
4 1 1 1 -1 1 -1 4 -1 -1 1 -1 1 -1 1 2 3
4 -1 -1 1 -1 1 -1 4 1 1 1 -1 1 -1 1 2 3
Connectivity
Now that the structured overset grid has been generated, boundary conditions specified, and Block-2-Block boundaries determined; the last remaining step before solving the problem is determining the donor/receiver relationship for the remaining unspecified grid boundaries as well as blanking grid points in the system that are located inside the wing body geometry. This step is accomplished through task: connectivity. We begin by creating a yaml file (interp.yaml) for the task which is shown below:
grid :
curv :
gridFile : grid.x
bcfile : grid.bc
b2bfile : grid.b2b
fileType : plot3d
curvSolver :
equations : euler
task : connectivity
tileSize : [42, 42, 42]
verbose : false
integrationweights : overlapper
writerecordmarkersingrids : True
referenceConditions:
Pressure : 101325
alpha : 0.0
uMag : 1.0
temperature : 300
timeStepping :
steady : true
navierstokes:
convective:
type : upwind
overset :
optimizeoverlap : True
performholecutexplicitly : False
writenamegroupedbcs : True
writeBodyCutEdges : True
writeSurfDeviation : True
zoneSpecific:
-
zones : [1-5]
priority : 100.0
explicitBlanking :
-
type : clip
variable : y
operator : "<"
value : 0.0
bc :
-
names : [far]
type : BCfarfield
location : offbody
-
names : [symm]
type : BCSymmetryPlane
location : offbody
symplaneorigin : [0.0, 0.0, 0.0]
symplanenormal : [0.0, 1.0, 0.0]
projectnodes : true
-
names : [fuse,wing]
type : BCWallViscous
location : onbody
Once the yaml file has been created we simply run LAVACurv using the yaml input.
For instructions on how to set up your environment and use the LAVA executables
and utilities see Setup and Utilities. On the
workstation use:
-----------------------------------------------------|
--------- Fringe Reduction Orphan Analysis ----------|
-----------------------------------------------------v
nOrphans: 0
nImmersedOrphans: 0
nTotalOrphans: 0
INTOUT file containing the necessary donor information for each fringe point, overlapper/panel_weights.dat containing the integration weights for each quad surface of the wing and fuselage, and overlapper/overlap_wallElemFracs.plt which is a Tecplot file allowing you to analyze the surface integration weights.
The image above shows the integration weight for each quad with 1 representing the use of full weight from the quad, 0 represent exclusion of the quad from surface integration, and 0 < frac < 1 representing a portion of the quad being used. Note blanking of cells below a small threshold has been activated in Tecplot to make the image. The purpose of the weights is to avoid double counting in surface integrations which can happen in overlapping grid regions.
Flow Solve
Upon completion of connectivity we are now ready to solve the steady-state RANS problem. In order to perform the RANS analysis a yaml file containing the input parameters for the problem must be created, run.yaml. In this case we are solving the CRM wing body configuration at 2.7% model scale. We will go through each section of the input file, but here is the file in its entirety.
# grid-time-start
grid :
curv :
gridFile : grid.x.ihc
bcfile : grid.bc
b2bfile : grid.b2b
fileType : plot3d
interpFile : INTOUT
timeStepping :
steady : true
# grid-time-end
# curvsolver-start
curvSolver :
task : solve
equations : rans
integrationweights : overlapper
integrationweightsdir : overlapper
verbose : False
fixbadrecon : True
b2btol : 1e-8
metricexchange : True
# curvsolver-end
# ref-start
referenceConditions :
pressure : 1.5422851978407425e+05
uMag : 3.0583477205837789e+02
temperature : 3.2204000000000002e+02
alpha : 2.5
beta : 0.0
momentCenter : [3.96240762e+00, 0.0, -8.89e-06]
area : 1.3985484287039998e-01
length : 1.9099530000000001e-01
cp : 1005.00000
gamma : 1.40000000
slconst : 1.458e-6
slref : 110.400000
# ref-end
# ns-start
navierstokes :
convective :
type : upwind
riemannsolver : modifiedroe
schemeOrder : 2
interporder : 3
limiter : koren
lowspeedPreCon : none
turbulencemodel :
type : sa
userc : True
useqcr : True
usesacc : False
# ns-end
# solver-start
nonlinearSolver :
method : implicit
kind : ank
iterations : 500000
miniterations : 99
l2conv : 1e-10
CFLStart : 1.0
CFLlimit : 1000.0
CFLlimitTur : 1000.0
jacobianLag : 5
linearSolver :
tolerance : 0.1
maxTolerance : 0.5
subspaceSize : 40
matfree : False
hoswitchtol : 1.0e-4
approxViscFluxes : True
lineSearch : True
preconditioner :
type : ilu
ilufill : 0
subiter : 1
# solver-end
# converg-start
convergencecriteria :
-
quantity : cl_wing
stdtolerance : 0.00001
stdwindowIterations : 100
verbose : True
frequency : 20
-
quantity : cd_wing
stdtolerance : 0.000001
stdwindowIterations : 100
verbose : True
frequency : 20
-
quantity : cmy_wing
stdtolerance : 0.00001
stdwindowIterations : 100
verbose : True
frequency : 20
# converg-end
# bc-start
bc :
-
names : [fuse,wing]
type : BCWallViscous
-
names : [far]
type : BCFarfield
-
names : [symm]
type : BCSymmetryPlane
# bc-end
# output-start
output :
ioProcs : 0
restart :
frequency : 1000
fileName : restart
volume :
-
frequency : 100
fileName : vol
variables : ['pressure', 'velocityx', 'velocityy', 'velocityz', 'temperature', 'nut', 'eddyviscosityratio']
fileType : plot3d
surface :
-
BCTypes : [BCWallViscous]
frequency : 100
variables : [cp, cfx, cfy, cfz, yplus]
fileName : surface
fileType : plot3d
monitor :
variables : ['cl_wing', 'cd_wing', 'cmy_wing', 'maxmach', 'maxanut']
# output-end
Now we will go through each section and explain the input parameters. First we begin with the grid and time-stepping sections:
grid :
curv :
gridFile : grid.x.ihc
bcfile : grid.bc
b2bfile : grid.b2b
fileType : plot3d
interpFile : INTOUT
timeStepping :
steady : true
grid section, the name of the grid file (gridFile), boundary condition file (bcfile), block-2-block specification file (b2bfile), and the overset connectivity file (interpFile) are specified. While for steady-state analysis the time stepping section simply consists of specifying that steady is true. Specification of the task and problem type are given in the curvSolver section shown below.
curvSolver :
task : solve
equations : rans
integrationweights : overlapper
integrationweightsdir : overlapper
verbose : False
fixbadrecon : True
b2btol : 1e-8
metricexchange : True
LAVACurv solver that the task is to solve the RANS equations. Since the wing body surface contains overlapping grids the integrationweights is set to overlapper and uses the precomputed weights in the specified integrationweightsdir that were generated using task: connectivity. The fixbadrecon flag is set to true in order to get robust left/right state reconstructions. The tolerance of the B2B interfaces is set to 1.0e-8 and the metric terms are set to be exchanged at B2Bs.
Next the reference conditions are provided:
referenceConditions :
pressure : 1.5422851978407425e+05
uMag : 3.0583477205837789e+02
temperature : 3.2204000000000002e+02
alpha : 2.5
beta : 0.0
momentCenter : [3.96240762e+00, 0.0, -8.89e-06]
area : 1.3985484287039998e-01
length : 1.9099530000000001e-01
cp : 1005.00000
gamma : 1.40000000
slconst : 1.458e-6
slref : 110.400000
With the task, problem type, and reference conditions specified the next step is to choose the discretization and turbulence model:
navierstokes :
convective :
type : upwind
riemannsolver : modifiedroe
schemeOrder : 2
interporder : 3
limiter : koren
lowspeedPreCon : none
turbulencemodel :
type : sa
userc : True
useqcr : True
usesacc : False
The nonlinear and linear solver settings are described next:
nonlinearSolver :
method : implicit
kind : ank
iterations : 500000
miniterations : 99
l2conv : 1e-10
CFLStart : 1.0
CFLlimit : 1000.0
CFLlimitTur : 1000.0
jacobianLag : 5
linearSolver :
tolerance : 0.1
maxTolerance : 0.5
subspaceSize : 40
matfree : False
hoswitchtol : 1.0e-4
approxViscFluxes : True
lineSearch : True
preconditioner :
type : ilu
ilufill : 0
subiter : 1
Since we are interested in aerodynamic performance quantities and use of limiters can sometime lead to residual convergence caused by "limiter rattling" a convergencecriteria section is added to the input file:
convergencecriteria :
-
quantity : cl_wing
stdtolerance : 0.00001
stdwindowIterations : 100
verbose : True
frequency : 20
-
quantity : cd_wing
stdtolerance : 0.000001
stdwindowIterations : 100
verbose : True
frequency : 20
-
quantity : cmy_wing
stdtolerance : 0.00001
stdwindowIterations : 100
verbose : True
frequency : 20
The grid.bc file that was provided a name for particular subsets of the grid system. A boundary condition for each name is now provide in the bc section:
bc :
-
names : [fuse,wing]
type : BCWallViscous
-
names : [far]
type : BCFarfield
-
names : [symm]
type : BCSymmetryPlane
The last section of the yaml file is for output specification:
output :
ioProcs : 0
restart :
frequency : 1000
fileName : restart
volume :
-
frequency : 100
fileName : vol
variables : ['pressure', 'velocityx', 'velocityy', 'velocityz', 'temperature', 'nut', 'eddyviscosityratio']
fileType : plot3d
surface :
-
BCTypes : [BCWallViscous]
frequency : 100
variables : [cp, cfx, cfy, cfz, yplus]
fileName : surface
fileType : plot3d
monitor :
variables : ['cl_wing', 'cd_wing', 'cmy_wing', 'maxmach', 'maxanut']
Here we walk through setting up an example PBS script to run on the NASA Advanced Supercomputing (NAS) computer using Athena nodes.
The first step is to copy the grid.x.ihc, grid.bc, grid.b2b, INTOUT, overlapper/panel_weights.dat, and run.yaml
files into a working directory on Pleiades. These files can be obtained from the tutorial files section. Next,
create a PBS file named run_athena.pbs with the following contents (note this is for c-shell users, see
Setup and Utilities for other options):
#PBS -S /bin/bash
#PBS -N crm_highspeed_rans_curv
#PBS -l select=1:ncpus=256:mpiprocs=4:model=tur_ath
#PBS -l walltime=8:00:00
#PBS -q normal
#PBS -j oe
#PBS -W group_list=<your project group ID>
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
unset F_UFMTENDIAN
cd $PBS_O_WORKDIR
log_file="run.log"
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t 64 lavacurv.3D.NS1.AVX512 run.yaml |& tee -a ${log_file}
██╗ █████╗ ██╗ ██╗ █████╗
██║ ██╔══██╗██║ ██║██╔══██╗
██║ ███████║██║ ██║███████║
██║ ██╔══██║╚██╗ ██╔╝██╔══██║
███████╗██║ ██║ ╚████╔╝ ██║ ██║
╚══════╝╚═╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝
Compiled using: Intel(R) Fortran Intel(R) 64 Compiler Classic for applications running on Intel(R) 64, Version 2021.10.0 Build 20230609_000000
from git hash: 25950109856d6cf4bcc4a3eca4e2483919e5f7bd
on: Feb 02 2026 at 12:43:54
Using 4 MPI Ranks
Using 64 OpenMP Threads
-------------------------------------------------------------------------------
Warning msg on proc(2) : unset F_UFMTENDIAN, code will take care of conversion.
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
Warning msg on proc(3) : unset F_UFMTENDIAN, code will take care of conversion.
-------------------------------------------------------------------------------
Proc 0 OpenMP Mapping: Proc 1 OpenMP Mapping:
Thread: 0 Bound to CPU 0 Thread: 0 Bound to CPU 64
Thread: 1 Bound to CPU 1 Thread: 1 Bound to CPU 65
Thread: 2 Bound to CPU 2 Thread: 2 Bound to CPU 66
...
Reference State Information:
Reference Pressure = 154228.51978407
Reference U Velocity = 305.54368512282
Reference V Velocity = 0.0000000000000
Reference W Velocity = 13.340325392204
Reference Temperature = 322.04000000000
Reference UMag = 305.83477205838
Reference Q = 78001.073880796
Reference Speed of Sound = 359.80561418633
Reference Mach Number = 0.85000000000000
Angle of Attack = 2.5000000000000
Reference Density = 1.6678494845492
Reynolds Number per Unit Length = 26178654.657994
Reynolds Number using LengthRef = 5000000.0000000
Reference Viscosity = 0.19484819735724E-04
Gas Constant = 287.14285714286
Free-Stream Residual = 0.39544754297754E+07
Free-Stream Residual Vol = 0.29764345281900E-04
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Time |Nonlin | CFL | CFLTur | Wall | Flow | Tur | Step | Step | Step |LinIt |LinIt |Lin Res |Lin Res | cl_wing | cd_wing | cmy_wing | maxmach | maxanut |
| Step | Iter | | | Time | Res | Res | Phys | LS | Tur | Flow | Tur | Flow | Tur | | | | | |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 0 1.0000E+00 1.0000E+00 7.1095E-01 3.9544754E+06 4.7212672E+05 0.000 0.000 0.000 0 0 0.0000 0.0000 8.8658770E-04 6.8786915E-02 2.5606125E-03 8.5000000E-01 3.5047802E-05
1 1 1.0000E+00 1.0000E+00 1.1013E+00 3.4846740E+06 3.0849522E+05 1.000 1.000 0.497 1 1 0.0104 0.0009 2.5523647E-02 8.1611589E-02 6.3897152E-03 8.5012498E-01 3.5918015E-05
1 2 1.0000E+00 1.0000E+00 1.3990E+00 3.2955158E+06 2.1420225E+05 1.000 1.000 0.516 1 1 0.0108 0.0011 5.1159914E-02 9.5902261E-02 1.0377429E-02 8.5045699E-01 3.6741500E-05
1 3 1.0000E+00 1.0000E+00 1.6964E+00 3.2024806E+06 1.6285233E+05 1.000 1.000 0.539 1 1 0.0101 0.0013 7.1581549E-02 1.0956965E-01 1.4783543E-02 8.5114727E-01 3.7462147E-05
1 4 1.0000E+00 1.0000E+00 1.9937E+00 3.1539210E+06 1.3106140E+05 1.000 1.000 0.593 1 1 0.0094 0.0014 8.8645718E-02 1.2279513E-01 1.9736767E-02 8.5225402E-01 3.8055296E-05
1 5 1.0000E+00 1.0000E+00 2.2908E+00 3.1482853E+06 1.0862990E+05 1.000 1.000 0.618 1 1 0.0088 0.0014 1.0406476E-01 1.3517371E-01 2.3978021E-02 8.5374897E-01 3.8627304E-05
1 6 1.2500E+00 1.2500E+00 3.2468E+00 2.9424400E+06 8.8910764E+04 0.708 1.000 0.760 1 1 0.0120 0.0020 1.1482359E-01 1.4344920E-01 2.6421676E-02 8.5697602E-01 3.9476422E-05
1 7 1.2500E+00 1.2500E+00 3.5435E+00 2.7915508E+06 7.5797035E+04 0.675 1.000 0.790 1 1 0.0118 0.0021 1.2282616E-01 1.4949250E-01 2.8338686E-02 8.6249071E-01 4.0315738E-05
1 8 1.2500E+00 1.2500E+00 3.8404E+00 2.6963525E+06 6.5609225E+04 0.750 1.000 0.826 1 1 0.0116 0.0022 1.2986791E-01 1.5433585E-01 3.0046517E-02 8.6934453E-01 4.1149159E-05
1 9 1.2500E+00 1.2500E+00 4.1374E+00 2.5966370E+06 5.8861082E+04 0.550 1.000 0.853 1 1 0.0113 0.0023 1.3414624E-01 1.5665376E-01 3.0967608E-02 8.7480981E-01 4.1970270E-05
1 10 1.2500E+00 1.2500E+00 4.4345E+00 2.5191952E+06 5.3649432E+04 0.459 1.000 0.876 1 1 0.0112 0.0024 1.3750220E-01 1.5816678E-01 3.1590806E-02 8.7959105E-01 4.2777514E-05
1 11 1.5625E+00 1.5625E+00 5.3891E+00 2.3774105E+06 4.7664424E+04 0.387 1.000 0.773 1 1 0.0158 0.0035 1.4082310E-01 1.5943663E-01 3.2066649E-02 8.8514202E-01 4.3764576E-05
...
1 374 1.0000E+03 1.0000E+03 4.1159E+02 1.2072720E+00 6.0654936E-01 1.000 0.512 1.000 11 9 0.0951 0.0911 4.3664040E-01 1.5881558E-02 -1.3310519E-01 1.4240240E+00 3.6220424E-02
1 375 1.0000E+03 1.0000E+03 4.1231E+02 1.1824339E+00 9.3045291E-01 1.000 1.000 1.000 9 6 0.0999 0.0865 4.3664077E-01 1.5881496E-02 -1.3310495E-01 1.4240241E+00 3.6220400E-02
1 376 1.0000E+03 1.0000E+03 4.1368E+02 1.1505189E+00 6.6769842E-01 1.000 0.800 1.000 8 7 0.0957 0.0925 4.3664086E-01 1.5881454E-02 -1.3310473E-01 1.4240242E+00 3.6220381E-02
1 377 1.0000E+03 1.0000E+03 4.1430E+02 1.1395618E+00 5.7309372E-01 1.000 0.800 1.000 6 7 0.0948 0.0975 4.3664085E-01 1.5881418E-02 -1.3310452E-01 1.4240243E+00 3.6220368E-02
-------------------------------------------------------------------------------
Info msg on proc(0) : cl_wing mean = 4.366E-01 std = 6.173E-06
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
Info msg on proc(0) : cd_wing mean = 1.588E-02 std = 5.182E-07
-------------------------------------------------------------------------------
--------------------------------------------------------------------------------
Info msg on proc(0) : cmy_wing mean = -1.331E-01 std = 3.407E-06
--------------------------------------------------------------------------------
----------------------------------------
Info msg on proc(0) : Writing restart
----------------------------------------
solve time: 416.229598245000 sec
res time: 7.78916221568849 %
form time: 8.42328690362920 %
apply time: 22.8101039131518 %
factor time: 2.99680914706595 %
ortho time: 16.4585146603857 %
turb time: 18.6181693896217 %
Additionally the convergence history of integrated forces and moments for the wing can be monitored by looking at the 15th, 16th, and 17th column or using plotHist.py
Integrated Loads Extraction
Based on the solver settings the RANS simulation was performed until either the convergence criteria was satisfied or 10 orders of magnitude residual reduction was achieved. Based on the residual history it appears the convergence criteria was satisfied first. In order to look at the mean and standard deviation of the wing forces and moment over the final 100 nonlinear iterations, i.e. the specified convergence criteria
which will create the image above and the output
^ XX
_____ _ _ _ _ _ _ | XX
| __ \| | | | | | | (_) | | | XX
| |__) | | ___ | |_| |__| |_ ___| |_ | XXX
| ___/| |/ _ \| __| __ | / __| __| | XXX
| | | | (_) | |_| | | | \__ \ |_ | XXXX
|_| |_|\___/ \__|_| |_|_|___/\__| | XXXXXX
|
+----------------->
var: cl_wing fname: data.iter
Mean : 0.43663788091594025
Standard Deviation: 6.1972813596498045e-06
var: cd_wing fname: data.iter
Mean : 0.0158814416748356
Standard Deviation: 5.208356832364975e-07
var: cmy_wing fname: data.iter
Mean : -0.13310378319053207
Standard Deviation: 3.4237148842972003e-06
plotHist.py iter cl cd cmy cdp cdv cl_wing cd_wing cmy_wing cdp_wing cdv_wing -dumpData loads.dat -noPlot
loads.dat. The final values can be extracted with the simple unix command
Cp Extraction (via Tecplot)
Upon completion of the steady state RANS solve the surface.x, surface.q, and surface.nam files were generated. These are Plot3D grid, Plot3D function, and ASCII name files that can be loaded in Tecplot to create an image that looks like
Make sure that you have set the blanking options within Tecplot to use IBlank equal to zero with any corner. The profiles are extracted from ymin = 0.09 to ymax = 0.79 with 3 intermediate slices to generate
This test case can be modified to perform any basic steady RANS analysis on aircraft, rockets, etc.
ONERA OAT15A Hybrid RANS-LES
In this tutorial we revisit the ONERA OAT15A airfoil from the Curvilinear User Guide-QuickStart but using Hybrid RANS-LES (HRLES) to simulate the flow at a known buffet condition. This example will cover:
- Generating the Grid
- Boundary Condition and Block-2-Block File Generation
- HRLES Solver Input File
- PBS Running Example
- Example Results
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver and utilities installed and your environment properly setup, see LAVA Installation Guide
- Chimera Grid Tools (CGT) installed for optional mesh building
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | grid file |
| grid.bc | grid bc file |
| grid.b2b | grid block-to-block file |
| run.yaml | solver input file |
| run01.yaml | solver input file |
| run02.yaml | solver input file |
| job_tur_ath.pbs | job file for athena cluster |
Generating the Grid
Like the Curvilinear User Guide-QuickStart, instead of downloading the grid.x file from above you can follow the procedure for generating the grid in this section.
However, this section assumes you have Chimera Grid Tools (CGT) installed on your computer.
There are a few differences for the HRLES grid compared to the RANS grid from the QuickStart that
will be pointed out as we go. If you have not done so already, start by downloading
the grid from the AIAA Drag Prediction Workshop website.
grid_OAT15A_Deck.x.
Now copy and past the following grided input file into a file named grided.inp located in
the same location as the Plot3D grid file:
Note that in this example the input 0.5 has been replaced with 0.023. This represents the
half-span of the grid which is being set to 0.023 in order for the full span of the
grid to equal 0.2 chord = 0.046 meters. Now simply run the following CGT command:
This should generate a file named mesh.x which is equivalent to the grid.x file from
the Curvilinear User Guide-QuickStart but with the narrower span. Now we must redistribute
the 3 points in span to have 145 points in order to properly resolve the spanwise turbulent
structures using the HRLES model. This is accomplished using the CGT utility srap along with
the following input file, srap.inp
mesh.x
grid.x
4
1, 2
2, 1, 1
1, 1
1, -1, 145
1, 0.0, 0.0
2, 2
2, 1, 1
1, 1
1, -1, 145
1, 0.0, 0.0
3, 2
2, 1, 1
1, 1
1, -1, 145
1, 0.0, 0.0
4, 2
2, 1, 1
1, 1
1, -1, 145
1, 0.0, 0.0
Boundary Condition and Block-2-Block File Generation
Now that we have the grid, which is in meters, with a chord of 0.23 meters and a span of 0.046 meters, we can set up the boundary condition file.
At this point we simply need to associate a name for particular subsets of the grid. Below is the boundary condition file for this grid, grid.bc:
! Name GridNumber Jmin Jmax Kmin Kmax Lmin Lmax
!*********** *********** ***** ***** ***** ***** ***** *****
wall 1 1 -1 1 -1 1 1
far 1 1 -1 1 -1 -1 -1
far 2 1 1 1 -1 1 -1
far 2 1 -1 1 -1 -1 -1
wall 3 1 -1 1 -1 1 1
far 3 1 -1 1 -1 -1 -1
far 4 -1 -1 1 -1 1 -1
far 4 1 -1 1 -1 -1 -1
With the boundary condition file complete, the block-2-block connectivity file can be generated with the following LAVA utility program command:
This will generate the followinggrid.b2b file:
!-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
! BlkID js je ks ke ls le DonorID djs dje dks dke dls dle tx ty tz periodicTransformation
!-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 1 1 1 -1 1 -1 2 -1 -1 1 -1 1 -1 1 2 3
1 -1 -1 1 -1 1 -1 4 1 1 1 -1 1 -1 1 2 3
1 1 -1 1 1 1 -1 1 1 -1 -1 -1 1 -1 1 2 3 0.00000000000000E+00 4.60000000000000E-02 0.00000000000000E+00
1 1 -1 -1 -1 1 -1 1 1 -1 1 1 1 -1 1 2 3 0.00000000000000E+00 -4.60000000000000E-02 0.00000000000000E+00
2 -1 -1 1 -1 1 -1 1 1 1 1 -1 1 -1 1 2 3
2 1 -1 1 1 1 -1 2 1 -1 -1 -1 1 -1 1 2 3 0.00000000000000E+00 4.60000000000000E-02 0.00000000000000E+00
2 1 -1 -1 -1 1 -1 2 1 -1 1 1 1 -1 1 2 3 0.00000000000000E+00 -4.60000000000000E-02 0.00000000000000E+00
2 1 -1 1 -1 1 1 3 -1 -1 1 -1 -1 1 -3 2 1
3 1 1 1 -1 1 -1 4 1 -1 1 -1 1 1 -3 2 1
3 -1 -1 1 -1 1 -1 2 -1 1 1 -1 1 1 3 2 -1
3 1 -1 1 1 1 -1 3 1 -1 -1 -1 1 -1 1 2 3 0.00000000000000E+00 4.60000000000000E-02 0.00000000000000E+00
3 1 -1 -1 -1 1 -1 3 1 -1 1 1 1 -1 1 2 3 0.00000000000000E+00 -4.60000000000000E-02 0.00000000000000E+00
4 1 1 1 -1 1 -1 1 -1 -1 1 -1 1 -1 1 2 3
4 1 -1 1 1 1 -1 4 1 -1 -1 -1 1 -1 1 2 3 0.00000000000000E+00 4.60000000000000E-02 0.00000000000000E+00
4 1 -1 -1 -1 1 -1 4 1 -1 1 1 1 -1 1 2 3 0.00000000000000E+00 -4.60000000000000E-02 0.00000000000000E+00
4 1 -1 1 -1 1 1 3 1 1 1 -1 1 -1 3 2 -1
HRLES Solver Input File
This section discusses the input file for HRLES simulation of the ONERA OAT15A airfoil using the grid.x, grid.bc, and grid.b2b
files discussed above. We will go through each section of the YAML file, you can download the entire run.yaml along with the
aforementioned files from the Tutorial Files section.
Grid
In the grid section of the yaml we have:
grid :
curv :
gridFile : grid.x
BCFile : grid.bc
b2bfile : grid.b2b
fileType : plot3d
restartFile: restart.0000200.rst
gridFile named grid.x using the BCFile named grid.bc and
B2BFile named grid.b2b. The fileType of the grid is a Plot3D.
CurvSolver
Next is the curvSolver section:
curvSolver :
equations : rans
task : solve
integrationWeights : none
verbose : False
initializeboundarylayer : False
echorestart : False
equations are specified to be RANS and the task is to solve the equations. We also specify not
to echorestart since this is an unsteady case that will be solved for many time-steps and echoing the
stdout on every restart can become time consuming.
ReferenceConditions
In the referenceConditions section the free-stream, Sutherland constants, and reference
dimensions are specified.
referenceConditions:
pressure : 7.1840768006645056e+04
umag : 2.4094645006722962e+02
temperature : 271.0
alpha : 3.50
slconst : 0.145800000E-05
slref : 110.400000
area : 0.01058
length : 0.23
momentCenter : [0.0575, 0.0, 0.0]
pressure = 7.1840768006645056e+04 Pa,
umag = 2.4094645006722962e+02 m/s, temperature = 271.0 K, and alpha = 3.5 degrees.
The Sutherland constants are available to the user for adjustment, these values were chosen
for air at standard conditions. The reference length is set the chord = 0.23 m, area is
chord * span = 0.01058 m^2, and the momentCenter is (0.0575,0,0) m.
TimeStepping
In the timeStepping section the time-discretization and time-related parameters are specified.
timeStepping :
steady : False
dt : 9.5456895063539926e-07
gridMotion : False
method : bdf2
timeSteps : 20000
initializeAveraging : 80000
jacobianLag : 1
steady to False. The time-step dt has been chosen as
1000 time-step per Convective Time Unit (CTU) which is defined as the length of the airfoil
divided by the reference velocity magnitude. A time-implicit discretization method is selected to be bdf2 since y+ ~ 1 grids are used within the HRLES model.
By default, the run script is set to 20,000 timeSteps to keep the cost manageable for the tutorial, but this is insufficient to resolve buffet.
200,000 timeSteps are required to reach the 200 CTUs for modeling buffet.
The averaging of the variables is specified to start after 80,000 time-steps to exclude transients from the averaging.
The last option, jacobianLag, is set to 1 which means the
LHS operator used to drive the implicit dual-time stepping scheme is recomputed at the start
of every physical time-step.
NavierStokes
The discretization of the convective fluxes and the turbulencemodel are specified in the
navierstokes section:
navierstokes:
convective:
type : upwind
riemannsolver : modifiedroe
schemeOrder : 2
interpOrder : 3
limiter : koren
interiorblending : wigglestab
upwindsensor : hrlessensor
interiorZetaMin : 0.01
interiorZetaMax : 1.0
interiorZetaWS : 0.1
interiorZetaUS : 1.0
interiorZetaPow : 4.0
lowspeedPreCon : none
turbulencemodel :
type : sa
userc : False
useqcr : False
usesacc : False
mode : zdesMode7
gridLengthScale : lenScaleCubeVol
usefdextraprotection : False
lhsfacmode7 : True
type with the modifiedroe for the approximate riemannsolver. The
schemeOrder is set to 2 for second-order truncation error with interpOrder set to
3 for third-order left/right state reconstructions. The left/right state reconstructions
use a limiter set to koren since the solution contains a moving shock wave. In order
to reduce the overall dissipation of the scheme a blending between the third-order upwind
biased left/right state reconstructions and a fourth-order centered left/right state
reconstructions is performed for the velocity components. The interiorblending option
is set to use wigglestab blending which uses both a wiggle sensor along with the
specified upwindsensor set to hrlessensor. The extent of blending is controlled
with interiorZetaMin set to 0.01, so there will always be at least 1 percent upwinding.
The interiorZetaMax is set to 1.0 which allows full upwinding locally if the sensor
thinks it is necessary. The interiorZetaWS is set to 0.1 which means if an
odd-even decoupling in pressure is detected, then a minimum of 10 percent upwinding is
used. Finally, the interiorzetapow is the exponent used for the upwindsensor. This should
be an even number and the larger the number the more agressive the centering is blended
into the reconstruction. Values of 2 or 4 are typically recommended.
For the turbulencemodel we are using ZDES Mode 2 (2020). In order to achieve this specification
we choose type equal to sa or Spalart-Allmaras and we deactivate the Rotation-Curvature
correction and the QCR correction which are on by default, so userc and useqcr are set to
False. Next the mode is selected to be zdesMode7 which is the equivalent to ZDES Mode 2 (2020)
developed by the ONERA group 1. The gridLengthScale used in determining the representative local
mesh size is set to lenScaleCubeVol which is the cube-root of the local dual-cell volume and
we deactivate the usefdextrprotection since we know the mesh and time-step are sufficiently
fine for this case. Last the lhsfacmode7 is activated in order to make the LHS of the turbulence
model equation more well-behaved which using the HRLES model.
Nonlinear Solver
For the nonlinearsolver section:
nonlinearSolver :
method : implicit
kind : ank
iterations : 3
l2Conv : 1.0e-16
CFLStart : 100.0
CFLlimit : 100.0
CFLlimitTur : 100.0
CFLfromFile : True
jacobianLag : 50
usescaledresiduals : False
method is specified using an Approximate Newton Krylov ank for the kind. Only
3 sub-iterations are being used for iterations at each physical time-step. The l2conv is set
to a very small number to enforce the 3 sub-iterations. A constant CFL is maintained by setting
CFLStart, CFLlimit, and CFLlimitTur all to 100. We also set the parameter CFLfromFile to
True since this case requires a soft-start from a lower CFL, details will be covered in the next
section on running the simulation. The jacobianLag is set a large number which deactives the
recomputation of the LHS during the sub-iteration for computational efficiency. The last option,
usescaledresiduals is set to False which is the best practice for unsteady simulations. This
option is only useful if the l2conv is set to something more achievable like 1.0e-2 and the
iterations are increased, but it signals the user to monitor flowresvol as opposed to flowres
when examine the sub-iteration residual convergence.
LinearSolver
The linearsolver section:
linearSolver :
tolerance : 0.1
maxTolerance : .5
subspaceSize : 40
monitor : False
matfree : False
approxviscfluxes : True
linesearch : True
preconditioner :
ilufill : 0
subiter : 1
tolerance is set
to 0.1 meaning that only one-order of linear-system residual reduction is required before
going to the next nonlinear iteration. A maxTolerance of 0.5 is set to indicate if the
linear system was not solved sufficiently and Newton step reductions are required. The
subspace specifies the maximum number of Krylov vectors that can be used in the solve.
The monitor is set to False to supress linear solver residual output to stdout. The
matfree option is deactivated here which is the best practice for unsteady simulations and
approxviscfluxes is set to True which results in a more diagonally dominate system that
is easier to solve. The linesearch is activated which will reduce the Newton step if the
nonlinear residual is growing too fast. Finally, the preconditioning options of zero fill
level and a single pass are specified. Note the preconditioner is depended on the number
of MPI ranks specified, so if the number of ranks changes during a restart the exact
reproduction of time-history is not guaranteed.
BC File
The bc section is where the named grid sub-sets from the BCFile are associated with
a boundary condition:
Output
The final section is where the output specifications are made:
output :
ioProcs : 0
restart :
fileName : restart
frequency : 1000
volume :
-
fileName : vol
frequency : 2000
variables : [Pressure,VelocityX,VelocityY,VelocityZ,Temperature,eddyviscosityratio,Mach,shocksensor,ducrossensor,fd,fdr,fpp,fr]
fileType : plot3d
-
fileName : avg
frequency : 500000
variables : [pressureavg,velocityxavg,velocityyavg,velocityzavg,temperatureavg,eddyviscosityratioavg,uuavg,uvavg,uwavg,vvavg,vwavg,wwavg,fdavg,modstressuwransavg]
fileType : plot3d
surface :
-
BCTypes : [BCWallViscous]
frequency : 10
variables : [cp, cf, cfx, cfy, cfz, yplus]
fileName : surface
buffersize : 1000
-
BCTypes : [BCWallViscous]
frequency : 500000
variables : [cpavg, cfavg, cfxavg, cfyavg, cfzavg, yplusavg]
fileName : surfavg
monitor :
variables : [cl, maxmach, minpressure, flowresvol, turresvol]
ioprocs to 0 which means all the
MPI ranks are used for I/O. The 'restart' file will be written every frequency time-steps which is 1000 in
this case. Note that by default only three copies of the restart file are retained during a continuous simulation
meaning that if you run for all 200000 time-step in one run you will only have restart.0198000.rst,
restart.0199000.rst, and restart.0200000.rst files upon completion. The volume file, vol.???????.q will be written
every 2000 time-steps and will include the variables listed. Now the file avg.???????.q will only be written
if the simulation is stopped since the frequency is set larger than the requested timeSteps. This is because the
average variables are necessary to store in the restart file in order to continue averaging upon a restart, so they
will already be reported in the restart file as they accumulate. The restart file is standard Plot3D function file,
so it can be visualized using standard visualization tools. The surface files will be recorded every 10 time-steps,
but they will only be written once 100 time-steps worth of surface data have been stored, which is specified in
buffersize. This reduces the I/O necessary for high-frequency data increasing the performance of the solver. In
the monitor section additional variables can be specified to be reported to stdout. Note all of these variables
and more are retained in data.iter regardless of what is specified in monitor. A full list of available variables
in data.iter can be displayed using the -dispVars option in plotHist.py.
PBS Running Example
Now that we have discussed each component of the YAML input file, we will walk through setting up an example PBS
script to run on the NASA Advanced Supercomping (NAS) computer Athena. This example also covers how to soft
start a low-dissipation HRLES simulation from free-stream. Log into one of the Athena front-end nodes, make a directory named test_hrles_lava,
change into that directory, and copy the aforementioned files into that directory.
The run01.yaml and run02.yaml are similar to the run.yaml which was discussed
above. The main difference is that run01.yaml runs 100 time-steps using a CFL = 1 and run02.yaml
restarts using a CFL = 10, then we are able to restart from there using run.yaml with the full
CFL = 100. If we were to use run.yaml starting from free-stream the low-dissipation scheme combined with
the large CFL number results in the approximate Newton Krylov algorithm to reduce the Newton step to extremely
small corrections to avoid non-physical pressures and temperatures. This will lead to no sub-iteration convergence
and the solution will stay near the initial free-stream conditions never evolving in time. Using the soft start
procedure outlined here allows the approximate Newton Krylov procedure to work as expected. Since the averaging
procedure is not specified to start until after 80000 time-steps the reduced accuracy during the first
200 time-steps is irrelevant.
For c-shell users, the following PBS script was developed to run this case on Athena:
#PBS -S /bin/bash
#PBS -N oat15_buffet_curv
#PBS -l select=6:ncpus=256:mpiprocs=4:model=tur_ath
#PBS -l walltime=8:00:00
#PBS -q normal
#PBS -l site=needed=/home6+/nobackupp27
#PBS -j oe
#PBS -W group_list=<your project group ID>
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
unset F_UFMTENDIAN
cd $PBS_O_WORKDIR
export MPI_LAUNCH_TIMEOUT=60
log_file="run.log"
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t 64 lavacurv.3D.NS1.AVX512 run01.yaml |& tee -a ${log_file}
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t 64 lavacurv.3D.NS1.AVX512 run02.yaml |& tee -a ${log_file}
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t 64 lavacurv.3D.NS1.AVX512 run.yaml |& tee -a ${log_file}
run_athena.pbs in the test_hrles_lava directory.
Now run the command:
This will submit the job to the PBS system. Once the job is running you should first see a run01.out
file. As the first soft start completes the restart with larger CFL will begin and the run02.out
file will appear. Finally, after 200 time-steps, another restart will occur and the run.out file
is generated. You can run the command:
to observe the stdout history. A snapshot of the stdout is shown below:
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Time | Time | CTU |Nonlin | CFL | CFLTur | Wall | Flow | Tur | Step | Step | Step |LinIt |LinIt |Lin Res |Lin Res | cl | maxmach | minpressure | flowresvol | turresvol |
| Step | | | Iter | | | Time | Res | Res | Phys | LS | Tur | Flow | Tur | Flow | Tur | | | | | |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
51943 4.958318E-02 5.1943E+01 0 1.0000E+02 1.0000E+02 6.5588E+04 4.2045062E+04 1.2100197E+05 0.000 0.000 0.000 0 0 0.0000 0.0000 1.0443328E+00 1.3818851E+00 3.2935496E+04 5.0716726E-06 1.6926311E-06
51943 4.958318E-02 5.1943E+01 1 1.0000E+02 1.0000E+02 6.5589E+04 1.5731852E+04 1.2097664E+05 1.000 1.000 0.005 3 2 0.0481 0.0444 1.0443381E+00 1.3818596E+00 3.2934430E+04 2.9244722E-07 1.6877362E-06
51943 4.958318E-02 5.1943E+01 2 1.0000E+02 1.0000E+02 6.5589E+04 7.6575659E+03 1.2154030E+05 1.000 1.000 0.005 3 2 0.0437 0.0386 1.0443371E+00 1.3818511E+00 3.2934323E+04 1.2618181E-07 1.6998860E-06
51943 4.958318E-02 5.1943E+01 3 1.0000E+02 1.0000E+02 6.5589E+04 4.4939221E+03 1.2125186E+05 1.000 1.000 0.007 3 2 0.0338 0.0403 1.0443388E+00 1.3818500E+00 3.2934323E+04 6.7277667E-08 1.7036945E-06
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Time | Time | CTU |Nonlin | CFL | CFLTur | Wall | Flow | Tur | Step | Step | Step |LinIt |LinIt |Lin Res |Lin Res | cl | maxmach | minpressure | flowresvol | turresvol |
| Step | | | Iter | | | Time | Res | Res | Phys | LS | Tur | Flow | Tur | Flow | Tur | | | | | |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
51944 4.958413E-02 5.1944E+01 0 1.0000E+02 1.0000E+02 6.5590E+04 4.1994550E+04 1.2125186E+05 0.000 0.000 0.000 0 0 0.0000 0.0000 1.0443388E+00 1.3818500E+00 3.2934458E+04 5.0716183E-06 1.7036945E-06
51944 4.958413E-02 5.1944E+01 1 1.0000E+02 1.0000E+02 6.5590E+04 1.5699626E+04 1.2100677E+05 1.000 1.000 0.002 3 2 0.0481 0.0410 1.0443419E+00 1.3818227E+00 3.2934442E+04 2.9263630E-07 1.6897914E-06
51944 4.958413E-02 5.1944E+01 2 1.0000E+02 1.0000E+02 6.5590E+04 7.6389204E+03 1.1995413E+05 1.000 1.000 0.003 3 2 0.0439 0.0386 1.0443406E+00 1.3818186E+00 3.2934442E+04 1.2625959E-07 1.6722022E-06
51944 4.958413E-02 5.1944E+01 3 1.0000E+02 1.0000E+02 6.5590E+04 4.4730899E+03 1.2186642E+05 1.000 1.000 0.004 3 2 0.0338 0.0388 1.0443418E+00 1.3818198E+00 3.2934716E+04 6.7091333E-08 1.7027024E-06
Example Results
In this section a snaptshot of some expected results are presented.
In the figure below we have an iso-surface of q-criteria (at 43898065.6333) colored
by Mach along with an iso-surface of pressure (at 40949.23776378768). The resolved
3D turbulent structures are clearly visible behind the shock.
Since we are using ZDES Mode 2 (2020) the shielding function, fd which basically
represents the state of the modeled turbulence becomes important. In the upper-left
quadrant of the image below is a plot of fd where a value of 0 signifies that
the model is in RANS mode and value 1 signifies the model is in LES mode. We see
that the pressure side of the airfoil along with attached portion of the boundary
layer on suction side is RANS mode, while the rest of the domain is in LES mode
as desired. The advantage of the ZDES Mode 2 (2020) model over the original ZDES
Mode 2 (or DDES) model is the enhanced protection of the attached boundary layer
regardless of mesh resolution. The upper-right image shows the standard shielding
function from DDES. This indicates that the model does not stay in RANS mode
throughout the entire attached boundary layer on the suction side at the mesh
resolution. While the lower-left plot shows the enhanced protection portion of the
ZDES Mode 2 (2020) shielding function illustrating its superior ability to
protect the boundary layer. In order to stimulate the 3D turbulent structures to
form once the attached boundary layer separates, the inhibition function is
utilized. This is plotted in the lower-right sub-plot, showing nearly unit values
everywhere except at the stem of the shock intersecting the airfoil. This allows
the entire region behind the shock to be in LES mode.
The overall effect of the enhanced shielding function of the flow-field is illustrated
in the plot of the turbulent eddy viscosity ratio plotted below. Here we see nice
well-developed turbulent eddy viscosity throughout the attached boundary layer as
desired, and significantly reduced levels post-shock in the LES region of the flow.
Note this plot is using an exponential scale to highlight the lower values of the
eddy viscosity.

The ONERA OAT15 airfoil is known to buffet at this angle of attack, alpha = 3.5-degrees.
Here we plot the time-history of lift, drag, pitching moment, and maximum Mach number.
A low-frequency high-amplitude oscillation is clearly observed in each of the line plots.
This oscillation is associated with the shock moving upstream and downstream over the
suction side of the airfoil, as shown below.

Comparing the time-averaged and RMS pressures with experimental measurements shows good
overall agreement.
The time-average and RMS results from the LAVA simulation were computed using the
surface data which was output every 10 time-steps and averaged from 80000 to
200000 time-steps. The time-average shock position is predicted slightly downstream
of the experiment and a small bulge is observed downstream of the shock associated
with an over-prediction in the post-shock recirculation height. This small downstream
shift is also observed in the RMS, but the levels show good agreement within the
shock traversal region.
Relevant Publications
-
Deck, S., and Renard, N., "Towards an Enhanced Protection of Attached Boundary Layers in Hybrid RANS/LES Methods," Journal of Computational Physics, Vol. 400, 2020, p. 108970. https://doi.org/10.1016/j.jcp.2019.108970 ↩↩
JAXA Wing Body
One of the proven capabilities of the LAVA Curvilinear solver is its ability to tackle challenging supersonic applications, in particular low-boom simulations1 2 3 4. In this example, we will demonstrate how to run your first supersonic simulation of the JAXA Wing Body (JWB) geometry studied during the 2nd AIAA Sonic Boom Prediction Workship. The table of contents on the side provides an overview of the topics covered. A general procedure is followed when running a supersonic flow simulation:
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVACurv input file structure — see Curvilinear Solver Inputs
This tutorial uses lavacurv as a proxy for the appropriate executable.
Tutorial Files
Download the required files for this tutorial:
| File | Description |
|---|---|
| grid.in | grid file |
| surface.i.tri | surface triangulation |
| surface.x | surface mesh |
| grid.bc.in | grid file boundary conditions |
| grid.b2b | grid file block-to-block connectivity |
| solver.yaml | solver input file |
| connectivity.yaml | connectivity input file |
| solver.sh | solver run script |
| connectivity.sh | connectivity run script |
| interpolate_probes.yaml | interpolation input file |
| connectivity.pbs | connectivity run job |
| job_sky_ele.pbs | solver run job |
| generateProbes.py | wave form probe generation script |
| generate_probes.yaml | wave form probe generation input file |
| waveforms.sh | wave form extraction script |
The tutorial directory should be organized as follows:
├── connectivity.sh
├── grid_files
│ ├── grid.b2b
│ ├── grid.bc.in
│ └── grid.in
├── input_files
│ ├── connectivity.yaml
│ ├── generate_probes.yaml
│ ├── interpolate_probes.yaml
│ └── solver.yaml
├── pbs_scripts
│ ├── connectivity.pbs
│ └── job_sky_ele.pbs
├── solver.sh
├── waveform_utility
│ └── generateProbes.py
└── waveforms.sh
Case Details
The JWB is a 38.7 meter long wing-body configuration. This tutorial simulates the cruise conditions contained in the table below.
| Mach Number | \(1.6\) |
| Angle of Attack | \(2.3^{\circ}\) |
| Altitude | 15.76 km |
| Reynolds Number | 5.7 million per meter |
Grid System
The near-field supersonic simulation uses a specialized structured curvilinear overset grid system. This consists of:
- A near-body viscous grid system (rotated to \(2.3^{\circ}\) AoA).
- A Mach cone aligned background grid (fixed at \(0.0^{\circ}\)).
Running on a Workstation
Connectivity
Connectivity is required to perform explicit and implicit holecutting. We've provided a simple connectivity bash script that may be run to generate the holecut grid system.
Navigate to the JAXA wing body example directory:
Run the connectivity bash script:
It is highly recommend that users take time to understand each step of the process. For this reason, connectivity.sh contains detailed commentary for novice users:
#!/bin/bash
# Make a connectivity directory
mkdir -p connectivity
# Change to the connectivity directory
cd connectivity
# Symbollically link required files
ln -sf ../grid_files/grid.in
ln -sf ../grid_files/grid.bc.in
ln -sf ../grid_files/grid.b2b
ln -sf ../input_files/connectivity.yaml
# Run the connectivity executable by providing an
# input file 'connectivity.yaml' and outputting
# the results to a file called connectivity.out
$lavacurv connectivity.yaml | tee connectivity.out
After the script is finished running, your directory should reflect the following structure:
│── connectivity
│ ├── grid.b2b
│ ├── grid.bc.in
│ ├── grid.in
│ ├── grid.in.ihc
│ ├── INTOUT
│ ├── connectivity.out
│ └── overlapper
│ └── panel_weights.dat
├── connectivity.sh
├── grid_files
│ ├── grid.b2b
│ ├── grid.bc.in
│ └── grid.in
├── input_files
│ ├── connectivity.yaml
│ ├── generate_probes.yaml
│ ├── interpolate_probes.yaml
│ └── solver.yaml
├── job_sky_ele.pbs
├── pbs_scripts
│ ├── connectivity.pbs
├── solver.sh
├── waveform_utility
│ └── generateProbes.py
└── waveforms.sh
Verify that the following three files are present:
- grid.in.ihc: the holecut grid file.
- INTOUT: a binary file containing holecut information.
- overlapper/panel_weights.dat: panel weights required for surface integration.
Check the output file connectivity.out:
Find the following lines in the output:
Here we observe that there are 47 orphans. This number may vary in future releases. To eliminate these orphans or determine the cause, we recommend visit the LAVA Curvilinear connectivity documentation.
Flow Solver
After performing connectivity, the LAVA Curvilinear flow solver has all the required files necessary to run this case. To simplify the process, we have provided a bash script solve.sh to set up the flow solver directory and appropriately call the executable. The contents of solve.sh are provided below:
#!/bin/bash
# Make a flow solver directory
mkdir -p solver
cd solver
# Symbollically link required files
ln -sf ../connectivity/grid.in.ihc
ln -sf ../connectivity/overlapper
ln -sf ../connectivity/INTOUT
ln -sf ../grid_files/grid.bc.in
ln -sf ../grid_files/grid.b2b
ln -sf ../input_files/solver.yaml
# Run the flow solver by providing an input file
# solver.yaml and outputting the results to a file solver.out
$lavacurv solver.yaml | tee run.out
Execute the flow solver script:
This is a large grid system with nearly 10 million nodes, therefore a powerful workstation is required to run this efficiently. Instead it is recommended to run this simulation on a large cluster in parallel.
Running on the NAS Cluster
In this section, we provide template PBS scripts for running this case on NAS clusters. Start by navigating to the JAXA wing body example directory:
PBS Scripts
Below are example PBS scripts for running connectivity and the solver on Skylake nodes on the NAS Electra cluster.
Connectivity PBS script:
#PBS -S /bin/bash
#PBS -N jaxa_wing_body_curv_connectivity
#PBS -l select=1:ncpus=40:mpiprocs=2:model=sky_ele
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
export F_UFMTENDIAN
cd $PBS_O_WORKDIR
# Load required modules
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Define thread pinning executable (recommended usage on NAS: mbind.x)
export MBIND_EXE="/u/scicon/tools/bin/mbind.x"
# Export number of threads (ncpus)
export OMP_NUM_THREADS=40
# Create connectivity directory
mkdir -p connectivity
cd $PBS_O_WORKDIR/connectivity
# Symbollically link required files
ln -sf ../grid_files/grid.in
ln -sf ../grid_files/grid.bc.in
ln -sf ../grid_files/grid.b2b
ln -sf ../input_files/connectivity.yaml
# Run connectivity (serial for deterministic results)
${MBIND_EXE} -t ${OMP_NUM_THREADS} lavacurv.3D.NS1.AVX2 connectivity.yaml | tee connectivity.out
Flow solver PBS script:
#PBS -S /bin/bash
#PBS -N jaxa_wing_body_curv
#PBS -l select=5:ncpus=40:mpiprocs=2:model=sky_ele
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
log_file="run.log"
export F_UFMTENDIAN
cd $PBS_O_WORKDIR
#Load required modules
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Define thread pinning executable (recommended usage on NAS: mbind.x)
export MBIND_EXE="/u/scicon/tools/bin/mbind.x"
# Export number of threads (ncpus/2)
export OMP_NUM_THREADS=20
# Create a flow solver directory
mkdir -p solver
cd $PBS_O_WORKDIR/solver
# Symbollically link required files
ln -sf ../connectivity/grid.in.ihc
ln -sf ../connectivity/INTOUT
ln -sf ../connectivity/overlapper
ln -sf ../grid_files/grid.bc.in
ln -sf ../grid_files/grid.b2b
ln -sf ../input_files/solver.yaml
# Run flow solver
mpiexec -npernode 2 ${MBIND_EXE} -t ${OMP_NUM_THREADS} lavacurv.3D.NS1.AVX2 solver.yaml 2>&1 |& tee -a ${log_file}
Before submitting these cases to run, you must edit the following entries in pbs_scripts/connectivity.pbs and job_sky_ele.pbs:
- #PBS -W group_list=<your project group ID>
- export LAVA_EXE=/path/to/LAVA/executable
- export MBIND_EXE=/path/to/thread/pinning/executable
PBS Script Submittal
To run these cases, you must first submit the connectivity PBS script:
As stated in the connectivity section, we expect 47 orphans to be present in the grid system. After the connectivity has successfully completed, submit the flow solver PBS script:
Monitoring Jobs on NAS
To monitor your submittals on NAS, we recommend the following command:
Post-Processing
In this section, we provide guidance in post-processing supersonic CFD data for the JWB.
Flow Solver Convergence
To monitor the flow convergence, we utilize LAVA's Python utility plotHist.py.
Go to the flow solver output directory:
Plot the flow and turbulence residual for each iteration:
The data may be saved to a Tecplot file as follows:
Waveform Extraction
For low-boom supersonic applications, we are often interested in overpressure waveforms, \(\frac{\Delta p}{p_\infty}\), at various radial locations and azimuthal angles. The following two-step procedure is presented for retrieving these waveforms:
- Generate discrete line probes
- Interpolate data
To generate line probes, we utilize a provided LAVA utility, generateProbes.py, that may be modified for use with other supersonic cases. This utility is available within this tutorial's file structure in the waveform_utility directory.
Required input file for generateProbes.py:
probes:
number_points: 1801
phi_start: 0.0
phi_end: 90.0
number_angles : 3
mach : 1.4
tau_start : -0.1
tau_end : 2.5
body_length : 38.7
height_over_length: 0.5
output:
probe_filename : waveforms.x
A script is provided to perform the two-step waveform extraction procedure:
#!/bin/bash
mkdir -p waveforms
cd waveforms
# Flow solver grid and solution
ln -sf ../solver/grid.in.ihc
ln -sf ../solver/vol.q
# Input files
ln -sf ../input_files/generate_probes.yaml
ln -sf ../input_files/interpolate_probes.yaml
# Generate line probes
python ../waveform_utility/generateProbes.py generate_probes.yaml
# Interpolate volume data to probes
./interpolator interpolate_probes.yaml | tee interp.out
Note
interpolator is the name of the LAVA Curvilinear interpolation executable.
Execute the script:
Check that the following files were generated:
These are plot3D grid files containing the line probes seperated into zones (waveforms.x) and the corresponding interpolated pressure (waveforms.q). Below is a plot of the resulting overpressure waveform.
Relevant Publications
-
Housman, J. A., Kenway, G. K., Jensen, J. C., and Kiris, C. C., "Efficient Near-Field to Mid-Field Sonic Boom Propagation Using a High-Order Space Marching Method," American Institute of Aeronautics; Astronautics, 2019. https://doi.org/10.2514/6.2019-3487 ↩
-
Duensing, J. C., Jensen, J. C., Housman, J. A., Piotrowski, M. G., Kenway, G. K., Maldonado, D., Sozer, E., and Kiris, C. C., "Structured Overset and Unstructured Grid Simulations for the Third AIAA Sonic Boom Prediction Workshop," American Institute of Aeronautics; Astronautics, 2021. https://doi.org/10.2514/6.2021-0471 ↩
-
Ashby, C. P., Lowe, B. M., Housman, J. A., and Duensing, J. C., "Anisotropic Mach Cone Aligned Mesh Adaptation for Low Boom Simulations," AIAA Journal, Vol. 62, No. 6, 2024, pp. 2076--2094. https://doi.org/10.2514/1.j063351 ↩
-
Neuhoff, S., Ashby, C., Housman, J., and Duensing, J. C., "Enhanced Simulation Techniques in Predicting Sonic Boom Loudness Using CFD," Computers & Fluids, Vol. 300, 2025, p. 106759. https://doi.org/10.1016/j.compfluid.2025.106759 ↩
Rotor in Hover
One of the features of the LAVA Curvilinear solver that make it attractive for simulating rotating turbomachinery applications is its sliding mesh technique implementation. In this example, we will go through a simple yet elucidating example on how to set up a case involving a rotating rotor in hover. The geometry consists of two NACA0012 rotor blades, and includes a connecting hub wall. This simplified setup involves boundary conditions that replicate relevant ones for turbomachinery simulations. The following general procedure is followed when running a simulation involving the sliding mesh capability:
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVACurv input file structure — see Curvilinear Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | grid file |
| grid.bc | grid file boundary conditions |
| grid.b2b | grid file block-to-block connectivity |
| connectivity.yaml | connectivity input file |
| solver.yaml | solver input file |
| connectivity.pbs | connectivity NAS cluster PBS file |
| solver.pbs | solver NAS cluster PBS file |
| connectivity.sh | connectivity utility bash script |
| solve.sh | solver utility bash script |
The tutorial files provided expect the following directory structure:
├── rotor_naca0012/
│ └── curv/
│ └── connectivity.sh
│ └── solve.sh
│ └── input/
│ └── connectivity.yaml
│ └── solver.yaml
│ └── meshes/
│ └── grid.b2b
│ └── grid.bc
│ └── grid.x
│ └── pbs/
│ └── connectivity.pbs
│ └── solver.pbs
Sliding Mesh Setup
In order for the sliding mesh implementation to perform correctly, it is necessary to ensure that a few criteria are satisfied in the sliding mesh interface that separates the static and rotating grid zones. For a more in-depth review of the sliding mesh implementation within the LAVA solver, please refer to Section III.E. in Fernandes et al. (2023)1.
The following criteria relating to nodes present in the sliding mesh interface must be met:
- Must be shared by both zones in relative motion to one another, i.e., grids connected via a sliding mesh interface must be block-to-block, point-matched at the interface at the start of the simulation;
- Must be exactly circumferential, resulting in a set of ring-like nodes across the interface;
- Must be equally spaced in the circumferential direction along each of the ring-like nodes.
For these reasons, it is generally recommended that users start from a set of two-dimensional, point-matched domains representing a slice of the grid in the circumferential direction and then perform a revolving operation around the rotation axis with equally-spaced nodes to generate the three-dimensional grid blocks that share the sliding mesh interface. This process is visualized in the images shown below.
Another aspect that is important to consider when building the sliding mesh interface blocks relates to the boundary condition that one intends to apply at these blocks. This is especially relevant for viscous wall boundary conditions (BCWallViscous), since wall boundary conditions defined in rotating blocks also rotate with the block. This means that these viscous walls will impart rotational momentum to the boundary layer, unless specified to do otherwise.
Let's go back to our example to understand why this might be important to consider when designing the grid. The image below shows the surfaces (all of which are viscous walls) in our computational domain, color-coded for easy identification. Grey surfaces belong to stationary blocks, while colored surfaces belong to rotating blocks. An important distinction is made here between the green and red surfaces, however. While the green surfaces remain stationary, the red ones rotate with the blades.
One can accomplish this behavior by setting the wall velocities of the green surfaces explicitly in their boundary condition definition (grid.bc file, which you may access here):
BC:
-
names: [rotor, hub, hub-rotating]
type: BCWallViscous
-
names: [hub-static]
type: BCWallViscous
wallVelocity: [0., 0., 0.]
where the following boundary condition labels were applied:
rotor: blade surfaces, shown in red, which rotate with the block;hub: stationary hub surfaces belonging to blocks that do not rotate, shown in grey;hub-rotating: rotating hub surfaces, belonging to blocks that rotate, shown in red;hub-static: stationary hub surfaces, belonging to blocks that rotate, shown in green.
Having this flexibility can be important given that in real-world scenarios the interface between stationary and rotating walls can be placed close to the blade, and one may want to have the rotating blocks extend further away from the blade such that no overset occurs at the sliding mesh interface.
With these ideas in mind, the grid system that was generated for this example is shown below via two slices in the X and Y planes. Note the location of the sliding mesh interfaces, shown in magenta.
Running on a Workstation
Environment Setup
Let's begin by defining a convenient environment. Define the path to the appropriate LAVA executable and LAVA Curvilinear examples directory and store them in environment variables LAVA_EXE and LAVA_CURV_EXAMPLES, respectively.
For bash:
export LAVA_EXE=/path/to/LAVA/executable
export LAVA_CURV_EXAMPLES=/path/to/LAVA/curvilinear/examples
Grid Connectivity
Grid connectivity is required to perform explicit and implicit hole-cutting. We have provided a simple connectivity bash script that may be used to generate the hole-cut grid system.
Navigate to the Rotor in Hover example directory:
Run the connectivity bash script, shown below.
It is highly recommended that users take time to understand each step of the process. For this reason, connectivity.sh contains detailed comments for beginner users.
#!/bin/bash
# Make a connectivity directory
mkdir -p connectivity/
# Change to the connectivity directory
cd connectivity/
# Symbollically link required files
ln -sf ../meshes/grid.x
ln -sf ../meshes/grid.bc
ln -sf ../meshes/grid.b2b
ln -sf ../input/connectivity.yaml
# Set the number of OpenMP threads before running
OMP_NUM_THREADS_0=${OMP_NUM_THREADS}
export OMP_NUM_THREADS=8
# Run the connectivity executable by providing an
# input file 'connectivity.yaml' and output
# the results to a file called connectivity.out
lavacurv.3D.NS1.AVX2 connectivity.yaml | tee connectivity.out
# Reset the number of OpenMP threads after running
export OMP_NUM_THREADS=${OMP_NUM_THREADS_0}
# Return to original directory
cd ../
Check the output file connectivity.out, and find the following lines in the output:
Here we observe that there are 0 orphans. In future releases, this number may change. This is generally the most desirable scenario, and we recommend referring to the connectivity documentation in case orphans appear for cases you may be setting up from scratch.
Verify that you have the following files in the connectivity/ directory:
grid.x.ihc: Plot3D grid file with anIBlankfield for blanking purposes;INTOUT: binary file containing hole-cut information;overlapper/panel_weights.dat: panel weights required for surface loads integration.
At this stage, we recommend opening the hole-cut grid system grid.x.ihc, either using Chimera Grid Tools or another compatible external software package, for a final sanity check on the quality of the grid system and the optimized hole cut.
Flow Solver
After running grid connectivity, the LAVA Curvilinear flow solver has all the required files necessary to run the case. To simplify the process, we have provided a bash script solve.sh to set up the flow solver directory and appropriately call the executable. The contents of solve.sh are provided below.
#!/bin/bash
# Make a flow solver directory
mkdir -p solver/
# Change to the solver directory
cd solver/
# Symbollically link required files
ln -sf ../connectivity/grid.x.ihc
ln -sf ../connectivity/INTOUT
ln -sf ../meshes/grid.bc
ln -sf ../meshes/grid.b2b
ln -sf ../input/solver.yaml
# Set the number of OpenMP threads before running
OMP_NUM_THREADS_0=${OMP_NUM_THREADS}
export OMP_NUM_THREADS=8
# Run the flow solver by providing an input file
# 'solver.yaml' and output the results to a
# file called 'solver.out'
mpiexec -np 4 --bind-to none lavacurv.3D.NS1.AVX2 solver.yaml | tee solver.out
# Reset the number of OpenMP threads after running
export OMP_NUM_THREADS=${OMP_NUM_THREADS_0}
# Return to the original directory
cd ../
This script utilizes the solver.yaml file as input to the flow solver. Let's go over some of the settings particular to setting up an unsteady sliding mesh case. The rotating frequency \(f\) of the blades for this case is 7.9375 Hz. For demonstration purposes, we chose a coarse time-step corresponding to performing 63 time-steps per blade
revolution, calculated via
and we will run for 30 revolutions (timeSteps : 1890). Looking over the rotatingMesh section of the input solver.yaml file, we see:
rotatingMesh:
-
zones : [1-20,22-24]
omega : -49.87278337573797
axis1 : [0.0, -1.0, 0.0]
axis2 : [0.0, 1.0, 0.0]
This is where we define which zones in the grid system are rotating. We have defined two sets of zones, namely 1-20 (corresponding to the rotor blade zones), and 22-24 (corresponding to the hub zones that encompass the blades). We define the rotation axis along the Y direction with a vector defined by two points axis1 and axis2, and the rotational velocity omega (in units of rad/s) around that axis following the right hand rule. Note the negative sign in the rotational velocity for this case.
To run the example case:
Running on the NAS Cluster
Although this grid is small, it serves as a great test case to familiarize oneself with running unsteady simulations on a cluster. In this section, we provide templates (PBS scripts) for running this case on the NAS clusters.
First, download the files at the top of the page and transfer them to a directory you can access on the NAS cluster. Make sure to set the environment variable LAVA_CURV_EXAMPLES to point to the root directory holding those files following the structure described at the top of the page. The example below shows how to set an environment variable on a command line configured to use the bash scripting languages.
For bash:
Navigate to the Rotor in Hover example root directory:
PBS Scripts
The $LAVA_CURV_EXAMPLES/rotor_naca0012/curv/pbs directory contains templates for running this case on Skylake nodes on the NAS Electra cluster. For more information on setting up PBS jobs on NAS using different architecture nodes, please refer to NASA's High-End Computing Capability (HECC) website.
Connectivity PBS script:
#PBS -S /bin/bash
#PBS -N rotor_in_hover_curv_connectivity
#PBS -l select=1:ncpus=40:mpiprocs=2:model=sky_ele
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<enter_group_id>
#PBS -q normal
cd $PBS_O_WORKDIR
# Unset INTEL endian-ness
export F_UFMTENDIAN
# Load required modules
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Export number of threads (ncpus)
export OMP_NUM_THREADS=40
# Create connectivity directory
mkdir -p connectivity
cd $PBS_O_WORKDIR/connectivity
# Symbolically link required files
ln -sf ../meshes/grid.x
ln -sf ../meshes/grid.bc
ln -sf ../meshes/grid.b2b
ln -sf ../input/connectivity.yaml
# Run connectivity (serial for deterministic results)
mbind.x -t 40 lavacurv.3D.NS1.AVX2 connectivity.yaml | tee connectivity.out
Flow solver PBS script:
#PBS -S /bin/bash
#PBS -N rotor_naca0012_curv
#PBS -l select=2:ncpus=40:mpiprocs=2:model=sky_ele
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
log_file="run.log"
cd $PBS_O_WORKDIR
# Unset INTEL endian-ness
export F_UFMTENDIAN
# Load required modules
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Export number of threads (ncpus/2)
export OMP_NUM_THREADS=20
# Create a flow solver directory
mkdir -p solver
cd $PBS_O_WORKDIR/solver
# Symbolically link required files
ln -sf ../connectivity/grid.x.ihc
ln -sf ../connectivity/INTOUT
ln -sf ../connectivity/overlapper
ln -sf ../meshes/grid.bc
ln -sf ../meshes/grid.b2b
ln -sf ../input/solver.yaml
# Run flow solver
mpiexec -npernode 2 mbind.x -t 20 lavacurv.3D.NS1.AVX2 solver.yaml 2>&1 |& tee -a ${log_file}
Before submitting these cases to the NAS queue, make sure to edit the following entries in pbs/connectivity.pbs and job_sky_ele.pbs:
#PBS -W group_list=<enter_group_id>export LAVA_EXE=/path/to/LAVA/executable
PBS Script Submission
To run these cases, you must first submit the connectivity PBS script. This assumes you are on one of the NAS Pleiades Front End (PFE) nodes. Refer to the NASA HECC website for details on submitting cases to run on Electra Skylake nodes. Start by going inside the pbs/ sub-directory and then submit the connectivity.pbs PBS script:
Check the output file connectivity.out, and find the following lines in the output:
Here we observe that there are 0 orphans. In future releases, this number may change. This is generally the most desirable scenario, and we recommend referring to the connectivity documentation in case orphans appear for cases you may be setting up from scratch.
Verify that you have the following files in the connectivity/ directory:
grid.x.ihc: Plot3D grid file with anIBlankfield for blanking purposes;INTOUT: binary file containing hole-cut information;overlapper/panel_weights.dat: panel weights required for surface loads integration.
At this stage, we recommend opening the hole-cut grid system grid.x.ihc, either using Chimera Grid Tools or another compatible external software package, for a final sanity check on the quality of the grid system and the optimized hole cut.
After connectivity has sucessfully completed, submit the flow solver PBS script:
Tip
To monitor your job submissions on NAS, we recommend the following command:
For some front-ends on the NAS systems the commandqstat may not be recognized. Try nas_qstat instead if that's the case.
Post-Processing
In this section, we provide guidance on post-processing the simulation data for the Rotor in Hover example.
Flow Solver Convergence
To monitor the flow convergence, we utilize LAVA's Python utility plotHist.py. Refer to the LAVA Utilities page for more details on how to use this tool. Go to the flow solver output directory:
Plot the flow and turbulence residual for each iteration:
For unsteady simulations we recommend looking at the scaled residuals flowresvol and turresvol. The data may be saved to a Tecplot file for further post-processing:
Looking at the residual drop range for flowresvol, we notice a variation from 10-4 to 10-6, corresponding to a flow residual drop of two orders of magnitude at each linear iteration step. Under normal circumstances we would want to have this value drop closer to four orders of magnitude, but given the tutorial nature of this case we will proceed with the current setup. This residual drop can easily be accomodated by lowering the time-step further.
Rotor Loads Convergence
Looking at the convergence history for the rotor loads along the Y axis, as well as the Y moment coefficient, via
Tip
When dealing with unsteady simulation data, use the -hasSubIter option to tell plotHist to just take the final value at the end of the nonlinear iteration cycle at each time-step when plotting.
we see the loads stabilize after just 500 iterations, corresponding to roughly 8 revolutions.
If we then average the unsteady loads over the last 10 revolutions, via
plotHist.py -F output/data.iter timestep cfy_rotor cmy_rotor -doSubplot -hasSubIter -xRange 1260 1890 -showMean -showStd
we obtain the following averaged quantities from plotHist:
var: cfy_rotor fname: output/data.iter
Mean : 122.26683446101217
Standard Deviation: 9.795246145105448
var: cmy_rotor fname: output/data.iter
Mean : 34.00284666639238
Standard Deviation: 1.104313237812058
Relevant Publications
-
Fernandes, L. S., Housman, J. A., Kenway, G. K., Stich, G.-D., and Kiris, C. C., "Fan Noise Predictions of the NASA Source Diagnostic Test Using Unsteady Simulations with LAVA Part i: Near-Field Aerodynamics and Turbulence," American Institute of Aeronautics; Astronautics, 2023. https://doi.org/10.2514/6.2023-0793 ↩
CRM Wing Body Discrete Adjoint
The LAVA Curvilinear solver includes a discrete adjoint capability that enables efficient sensitivity analysis for aerodynamic shape optimization and design studies1. By solving the adjoint equations corresponding to a given flow solution, the solver computes gradients of user-specified functionals—such as lift or drag—with respect to design variables. This sensitivity information is essential for gradient-based optimization, allowing designers to understand how small changes in geometry or flow conditions affect performance metrics.
In this tutorial, we will demonstrate how to use the LAVA Curvilinear executable to solve the discrete adjoint for the drag coefficient of the CRM Wing Body configuration. We will also briefly discuss visualization of the adjoint field and surface shape sensitivities.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Completed the CRM Steady RANS tutorial to obtain a converged flow solution for the CRM Wing Body configuration.
Tutorial Files
Make and navigate to a working directory of your choosing for this tutorial.
mkdir -p /path/to/lava_tutorials/crm_discrete_adjoint
cd /path/to/lava_tutorials/crm_discrete_adjoint
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x.ihc | Grid file |
| grid.b2b | Block-to-block file |
| grid.bc | Boundary condition file |
| INTOUT | Interpolation and connectivity data |
| panel_weights.dat | Surface integration weights |
| adj.yaml | LAVA solver input file |
Additionally, you will need the restart.rst file generated from the flow solve described in the CRM Steady RANS tutorial! Go ahead and copy (or link) that file into this working directory.
Why do we need the restart.rst file?
Adjoint solutions require a converged flow field as input. The LAVA Curvilinear executable does not solve the flow (or primal) problem as part of the adjoint run. Instead, it expects a previously computed flow solution to be provided via a restart or initialization file.Arrange the downloaded files in the following structure:
crm_discrete_adjoint/
├── adj.yaml
├── grid.x.ihc
├── grid.b2b
├── grid.bc
├── INTOUT
├── restart.rst
└── overlapper/
└── panel_weights.dat
Solver Setup
There's no "setup" per se we need to do for the adjoint solver (other than having that converged flow solution in restart.rst), but we will take a moment to review the adj.yaml input file and point out the key differences between this input file and the one used for the flow solve in the CRM Steady RANS tutorial.
Most of this YAML file mirrors the structure used in the CRM Steady RANS tutorial, with four key differences.
The adjoint solver requires a precomputed flow field. This is provided via the initFile entry:
restart.rst file contains the converged flow solution and is generated during the flow solve described in the CRM Steady RANS tutorial.
We have also changed the task input to perform an adjoint solve:
The adjoint section defines the adjoint solver settings,
adjoint :
method : exact
objectives :
- name : cd
preconditioner :
ilufill : 1
subIter : 3
linearSolver :
tolerance : 1e-6
solver : gcrodr
subSpaceSize : 200
recycleSize : 40
iterMax : 3000
iterativeRefinement : True
scaleAdjointOutput : True
-
method: Specifies the adjoint formulation. Here,exactuses the full linearization of the flow residual, providing high-fidelity sensitivities. Alternatively, we could specifyapproxto use a first-order approximation of the linearization of the flow residual. This latter approach is much faster to solve but provides inaccurate sensitivities. -
objectives: Lists the functionals for which sensitivities are desired. In this case, we compute sensitivities of the drag coefficient (cd). -
preconditionerandlinearSolver: Configure the iterative solver used to solve the adjoint system. Thegcrodrsolver is chosen for its ability to recycle Krylov subspaces, improving convergence for large-scale problems. Thetolerancesets the convergence threshold for the adjoint residual, whilesubSpaceSizeandrecycleSizecontrol the size and reuse of the Krylov basis.iterMaxlimits the number of iterations.iterativeRefinementis enabled to reduce walltime of the adjoint solve, this approach uses single precision arithmetic to solve the linear system, but formulates the adjoint problem in a delta form to obtain a double precision adjoint solution. -
scaleAdjointOutput: If set to True, the adjoint solution written to file will be scaled by the metric Jacobian. This is useful for visualization purposes (e.g., in Tecplot), but should not be used for quantitative analysis or gradient computations, as the scaling alters the physical meaning of the adjoint values.
output section controls what data is written during the adjoint solve. The adjoint subsection enables writing the adjoint solution (write), the adjoint right-hand side (writeRHS), and the residual (writeResidual) for diagnostic and visualization purposes.
Running
Running on the NAS Cluster
Aitken Supercomputer
The following PBS script can be used to run this example on the NAS cluster using Aitken Rome Nodes.
#PBS -S /bin/bash
#PBS -N crm_rans_adj_curv
#PBS -l select=2:ncpus=128:mpiprocs=4:model=rom_ait
#PBS -l walltime=2:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
# Modules and Environments
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA
log_file="adj.out"
mpiexec -np 8 mbind.x -t 32 lavacurv.3D.NS1.AVX2 adj.yaml 2>&1 |& tee -a ${log_file}
Important
You must replace enter_group_id with your actual group or project ID in job.pbs before submitting this job.
Athena Supercomputer
The following PBS script can be used to run this example on the NAS cluster using Athena Turin Nodes.
#PBS -S /bin/bash
#PBS -N test_crm_discrete_adjoint
#PBS -l select=1:ncpus=256:mpiprocs=4:model=tur_ath
#PBS -l walltime=2:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Run LAVA
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t 64 lavacurv.3D.NS1.AVX512 adj.yaml | tee adj.out
Running on External Systems
Assuming you have properly installed the LAVA executables on your system, you can run the adjoint solver by passing the adj.yaml file to the LAVA Curvilinear executable that corresponds to your systems architecture.
As a place holder, we will refer to this executable as lavacurv.SUFFIX, where SUFFIX corresponds to the suffix for the LAVA executable that is compatible with your system.
For example, if your system uses OpenMPI, the Intel compiler, and has AVX512 vectorization capabilities, you would use the lavacurv.3D.NS1.INTEL.AVX512.OPENMPI executable, thus SUFFIX equal to 3D.NS1.INTEL.AVX512.OPENMPI.
For a single MPI rank, you can run the following command,
For multiple MPI ranks, you can run the following command,
Memory Usage
The adjoint solver can be memory intensive, especially for large meshes. If you are running into memory limitations on your local system, try modifying the adjoint inputs in adj.yaml to the following options to reduce the memory footprint of the adjoint solve,Standard Output
Sample output from the run will look like this
Reading Init file...
Restart used the following fields: pressure velocityx velocityy velocityz temperature nut
------------------------------------------------------------------------
Info msg on proc(0) : Normalized Flow Residual Norm : 0.2955024E-06
------------------------------------------------------------------------
Linres: 0 0.99999998
Linres: 1 0.88974621
Linres: 2 0.83413786
Linres: 3 0.80653798
Linres: 4 0.79508971
Linres: 5 0.78711652
Linres: 6 0.77275690
Linres: 7 0.77226066
Linres: 8 0.77222221
Linres: 9 0.76951587
Linres: 10 0.76763634
Normalized Flow Residual Norm tells you the ratio of the residual norm for the flow field you provided to LAVA (in this case through the initFile: restart.rst entry) divided by the residual norm of a flow field set to freestream variables. A normalized residual norm larger than expected may indicate that the reference parameters or flux options you provided in the adj.yaml for the adjoint solve may be different than those used for the flow solve.
Subsequently, the Linres iterations indicate the residual norm for the current iteration of the linear solver. If using the iterativeRefinement option, these residual norms are for the single precision linear system of the delta form of the adjoint residual. Intermittently, you'll see outputs like the following.
Linres: 177 0.99695055E-02
---------------------------------------------------------------------------------------
Info msg on proc(0) : Adjoint double precision residual norm: 0.99698517164196E-02
---------------------------------------------------------------------------------------
Linres: 0 0.99999997
Linres: 1 0.96653929
Post-Processing
Adjoint Convergence
Similar to the flow solver, the adjoint solver also writes a file containing convergence information with the file name adjoint_*.iter, where * is the name of the functional or functionals specified in the adj.yaml file.
Currently, however, this file is only populated after the adjoint solver has finished.
We can use the plotHist tool to plot this file. First we will display the variables inside,
$> plotHist -F adjoint_cd.iter -dispVars
^ XX
_____ _ _ _ _ _ _ | XX
| __ \| | | | | | | (_) | | | XX
| |__) | | ___ | |_| |__| |_ ___| |_ | XXX
| ___/| |/ _ \| __| __ | / __| __| | XXX
| | | | (_) | |_| | | | \__ \ |_ | XXXX
|_| |_|\___/ \__|_| |_|_|___/\__| | XXXXXX
|
+----------------->
adjres
iter
walltime
adjres, the solver iteration iter, and the wall time walltime. To plot the convergence of the residual with respect to the iterations, we use the following command,
Visualizing the Adjoint Field
Thanks to the fact that we had adjoint: True set in the output section of the adj.yaml, at the end of the adjoint solve we had the file adjoint.q.
This is a plot3d function file which contains the adjoint solution for all the flow and turbulence residual equations.
In this example, because we are solving the RANS equation with the one equation SA turbulence model, our adjoint solution has 6 variables: 5 corresponding to the RANS equations, and 1 corresponding to the turbulence model.
Plotting the adjoint can be done with Tecplot or any other software that allows you to visualize plot3d grid and function files.
In this example, we visualize the grid.x.ihc and adjoint.q files using Tecplot.
The first thing you may notice when opening these files is that the adjoint field on the boundaries (including the surface) is zero! Fear not. Due to the fact that LAVA uses a strong implementation of the boundary conditions, the governing flow equations are not solved at nodes that lie on boundaries. As a result, these nodes do not possess a residual value and hence an adjoint solution.
Because of this, visualizing the adjoint can be tricky. The following image demonstrates a slice of the adjoint solution for the mass conservation equation (also referred to as the density adjoint) a little bit off of the symmetry plane at constant y=0.01.
Make sure that you have set the blanking options within Tecplot to use IBlank equal to zero with any corner.
In this slice, we can make out the block boundaries in the adjoint solution. Once again, fear not.
This is an artifact of the overset implementation for LAVA.
Similar to nodes that lie on the boundary, receiver nodes in overset regions in LAVA do not have a residual nor an adjoint value.
Looking at this slice, we can see there is a strong sensitivity of the drag functional to perturbations in the residual through the stagnation streamline coming off of the nose of the fuselage at an angle of 2.5 degrees, i.e. the angle of attack specified for the freestream parameters.
One may also choose to use Tecplot's Iso-Surface capability to visualize the adjoint.
Creating an iso-surface for the mass conservation adjoint at a constant value of -0.01 provides use with the following visualization.
This iso-surface makes the direction of the sensitivity of the drag functional to perturbations in the residual even clearer.
Surface Gradients
Warning
Currently, the surfgradient output is very slow to compute depending on the size of the mesh. This is due to the mesh deformation tree that must be constructed in order to contract the functional sensitivities to the surface.
Sometimes, you may want to convert the adjoint into an actual gradient to visualize the total sensitivity of the a functional with respect to the geometry of your model. In mathematical terms, this total sensitivity is computed using the adjoint with the following equation,
\(\frac{d J}{d x} = \frac{\partial J}{\partial x} + \Psi^T \frac{\partial R}{\partial x}\)
where \(J\) is the functional (the drag coefficient in this example), \(x\) is the vector of surface node coordinates, \(\Psi\) is the adjoint vector, and \(R\) is the flow solver residual vector.
The total sensitivity can be directly output by the LAVA adjoint solver, however it currently requires that the proper inputs be specified in the adj.yaml prior to running the adjoint solver.
The output section in the adj.yaml is modified to the follow,
output :
ioProcs : 0
adjoint :
write : True
writeRHS : True
writeResidual : True
surfgradient :
- filename : surfGrad.plt
families : [fuse,wing]
surfgradient subsection which specifies surface sensitivity output, where filename sets the output file name and families defines which surface zones (e.g., fuse, wing) to include in the gradient extraction. The resulting file surfGrad.plt contains the total sensitivity information on the surface \(\frac{dJ}{dx}\), where \(J\) is the functional of interest (the drag coefficient in this example), and \(x\) is the vector of x-, y-, z-coordinates on the surface.
Warning
Currently, any surface not specified in the families list is assumed to deform. If you have, for example, a wind tunnel model with walls that would not deform in a shape optimization context, then they should be specified in the list of families.
You must call the LAVA executable with this modified adj.yaml to obtain the surfGrad.plt file. As warned above, the process of obtaining the surface gradients may be slow, I recommend going to get a coffee or tea while you wait. The resulting surfGrad.plt file is a Tecplot file which contains the surface sensitivities. Plotting the surface sensitivities in the z-direction (zSurfGrad) provides the following visualization.
Thus, we see that the drag coefficient is, unsurprisingly, most sensitive to perturbations in the geometry of the wing.
Relevant Publications
-
Lowe, B. M., Ashby, C. P., Koch, J. R. L., Craig Penner, D. A., Housman, J. A., and Duensing, J. C., "Towards Aerodynamic Shape Optimization Using an Immersed Boundary Overset Grid Method," American Institute of Aeronautics; Astronautics, July2024. https://doi.org/10.2514/6.2024-4229 ↩
Aerodynamic Analysis using pyLAVA
The goal of this tutorial is to replicate the aerodynamic analysis performed in the CRM Steady RANS tutorial using the Python interface to LAVA Curvilinear, pyLAVA. We will be demonstrating how to set up and run a flow solve using pyLAVA, as well as how to use some of the post-processing capabilities in pyLAVA to retrieve functionals and write solution files.
The LAVA class from the pyLAVA package is a python interface to the
LAVA Curvilinear framework. Some functionality that the LAVA class can perform includes, but is not limited to:
- initializing the flow solver
- perform a flow solve
- perform an adjoint solve
- write volume solutions
- deform the mesh
- evaluate user-specified functionals
- compute functional gradients
- so much more!
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Python 3.9 or above installed on your system
Environment Setup
For this example we will be using pyLAVA. See this documentation for information on setting up pyLAVA. This tutorial relies on Python packages listed in the Aerodynamic Analysis Requirements section.
We will be leveraging mpi4py in this tutorial, so I encourage you to include it in your Python environment.
However, if you are unable to use mpi4py on your system, you can still run this tutorial with a single MPI rank without mpi4py by remove the lines from mpi4py import MPI and comm=MPI.COMM_WORLD from the run_pylava.py script and running with a single MPI rank.
Tutorial Files
Make and navigate to a working directory of your choosing for this tutorial.
mkdir -p /path/to/lava_tutorials/crm_steady_rans_pylava
cd /path/to/lava_tutorials/crm_steady_rans_pylava
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x.ihc | Grid file |
| grid.b2b | Block-to-block file |
| grid.bc | Boundary condition file |
| INTOUT | Interpolation and connectivity data |
| panel_weights.dat | Surface integration weights |
| run.yaml | LAVA solver input file |
| run_pylava.py | Python script for the analysis |
Arrange the downloaded files in the following structure:
crm_steady_rans_pylava/
├── run_pylava.py
├── run.yaml
├── grid.x.ihc
├── grid.b2b
├── grid.bc
├── INTOUT
└── overlapper/
└── panel_weights.dat
Mesh setup
This tutorial uses the same grid as the one used in the CRM Steady RANS tutorial. The structured overset grid for the CRM wing body configuration consists of a main fuselage (blue), fuselage nose cap (red), wing/fuselage collar (green), main wing (maroon), wing outboard cap (gold), and octree based Cartesian off-body grid (black). The system consists of 5 near-body zones, 149 off-body Cartesian zones, and a total of 19,187,657 grid points. Boundary conditions for the grid system consist of no-slip walls for each l-direction = 1 near-body grid (assuming a j,k,l grid orientation), symmetry plane boundaries are specified for all surfaces on the y=0.0 plane, and far-field Riemann invariant boundary conditions are used for the outer-boundary of the Cartesian off-body grids. All non-specified boundaries are assumed to be either overset or block-2-block boundary conditions.
Solver Setup
The flow solver options are set using the run.yaml file.
The flow solver is run through the Python run script run_pylava.py.
Below, we break down the contents of these files.
Flow Solver Options
The run.yaml used in this tutorial file contains a standard set of options to run a RANS simulation in LAVA Curvilinear.
You can see all the flow solver options that you can define on this page.
Python Script
Now, let's break down the run_pylava.py script to understand how to use pyLAVA to run a flow solve.
Imports
Fairly straighforward, here we import thepylava and yaml packages.
Read YAML
Here, we have Python read the filerun.yaml. The returned object
lava_options is a dictionary containing all the options
that we will be using for LAVA.
💡 Tip: Modifying the options in Python
If you wanted to modify any options without changing the run.yaml file, you can do so after this line in the python script. An example may be if we were to add the line to modify the convergence tolerance to 1e-8 for the flow solver. However, any modification to the lava_options dictionary *after* the LAVA class is instantiated will have no impact on the flow solver options. All options are only passed to the flow solver when the LAVA class is first instantiated.Solver Instantiation
# Setup the aero solver instance
AeroSolver = LAVA(lava_options,
comm=MPI.COMM_WORLD,
suffix="3D.NS1.INTEL.AVX2.OPENMPI-lib")
Setting the suffix
When instantiating the LAVA Class, we have to tell it which LAVA dynamic library to use. This is done through the suffix argument.
The suffix is a string which is appended to the name of the LAVA dynamic library.
For example, if the suffix is INTEL.OMP, then the LAVA dynamic library that will be used is liblavacurv.INTEL.OMP.so.
You, the user, are responsible for setting the suffix to the correct value that corresponds to the compiled version of LAVA you want to use.
Solve
A direct call toAeroSolver() runs the flow solver!
Specifically, it makes a call
to the approximate-Newton-Krylov (ANK) solver in the lavacurv
framework. Thus, it solves the flow problem using the user-provided
options in the lava_options dictionary used to
instantiate the AeroSolver object.
Retrieving Functionals
# Evaluate some functionals
funcs = AeroSolver.evalFunction(['cl','cd'])
# Print the functionals to screen
if MPI.COMM_WORLD.rank == 0:
print(f"C_L : {funcs['cl'][0]}")
print(f"C_D : {funcs['cd'][0]}")
evalFunction function allows for the evaluation of a functional
of interest. Any surface-integration-based values (e.g. \(C_L\), \(C_D\)) can be obtained using this method.
These must be given to evalFunction as a list of strings.
A dictionary is returned which contains the resulting values for the functionals.
In this example, \(C_L\) can be retreived from the dictionary with the command
funcs['cl'].
Writing Volume Files
# Write out the volume file
AeroSolver.writeVolSolution(
filename = "vol_pylava.q",
filetype="plot3d",
fields=["pressure", "velocityx", "velocityy", 'velocityz', "temperature", "nut"]
)
vol.q as a plot3d function file.
When it comes to writing surface files, pyLAVA uses a different capability compared to the normal LAVA executable.
Due to its roots in design analysis, pyLAVA leverages a "design surface", which must first be built before it can be used to write solution files. Design surfaces can be constructed from any collection of domain boundaries, probes, or immersed boundaries.
Writing Surface Files
# Write out the surface
AeroSolver.buildDVSurfaces(families=["fuse", "wing", "symm"])
AeroSolver.writeSurface(
filename = "surface_pylava.plt",
fields=["iblank", "pressure", "velocityx", "velocityy", 'velocityz', "temperature", "nut"]
)
fuse and wing families and the symmetry plane symm; these name were all originally specified in the grid.bc file as boundary condition families.
Currently, the writeSurface capability in LAVA only writes to Tecplot binary files.
Note
The family names given to buildDVSurfaces must match those given in the grid.bc file. If you are unsure of the family names, you can always open the grid.bc file and check.
Running
Running on the NAS Cluster
Aitken Supercomputer
First, modify the suffix argument in the run_pylava.py file to contain the following,
The following PBS script can be used to run this example on the NAS cluster using Aitken Rome Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_rans_pylava_rom_curv
#PBS -l select=2:ncpus=128:mpiprocs=4:model=rom_ait
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# Set MPI environment variable
export MPI_NUM_MEMORY_REGIONS=0
cd $PBS_O_WORKDIR
# Run optimization script
log_file="run.log"
mpiexec -np 8 mbind.x -t 32 python run_pylava.py |& tee -a ${log_file}
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
mpi4py required for Aitken Supercomputer
We have found that when running on the Aitken Supercomputer, the line
must be the first line in therun_pylava.py script for the script to run properly.
If this line is not the first line, the Python command will stall.
Athena Supercomputer
First, modify the suffix argument in the run_pylava.py file to contain the following,
The following PBS script can be used to run this example on the NAS cluster using Athena Turin Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_rans_pylava
#PBS -l select=1:ncpus=256:mpiprocs=4:model=tur_ath
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# Set environment variables for MPI and OMP
export MPI_NUM_MEMORY_REGIONS=0
export OMP_NUM_THREADS=64
export OMP_PLACES=cores
export OMP_PROC_BIND=close
#Solver
mpiexec -np 4 --ppn 4 --cpu-bind depth --depth 64 python run_pylava.py | tee run.out
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
Warning
At the time of writing, we have had difficulty using mpi4py across Turin nodes. Thus, you may currently only be capable of running this tutorial on a single Turin node.
Running on External Systems
Modify the suffix argument in the run_pylava.py file to match the suffix for the LAVA Dynamic Library that is compatible with your system.
Additionally, if the path to the LAVA Dynamic Library is not included in the LD_LIBRARY_PATH environment variable, then you will need to include the libPath argument when instantiating the LAVA class to specify the path to the LAVA Dynamic Library on your system. Together, these should look something like the following inside of your run_pylava.py file:
AeroSolver = LAVA(lava_options,
comm=MPI.COMM_WORLD,
suffix='lava_dynamic_library_suffix_for_your_system',
libPath='/path/to/lava/dynamic/library')
If you created a Python virtual environment following the directions in the environment setup instructions above, make sure to activate that environment in your terminal:
For a single MPI rank, you can run the following command,
For multiple MPI ranks, you can run the following command,
Proper Thread Binding for OpenMPI
When running with OpenMPI, proper thread binding may require additional flags for optimal performance. We have found that the following command ensures correct binding:
export OMP_NUM_THREADS=28
mpirun -np 4 --map-by slot:PE=$OMP_NUM_THREADS --bind-to hwthread python run_pylava.py | tee run.out
OMP_NUM_THREADS based on the number of threads you want to use.
Standard Output
During the preprocessing steps and flow solve, you will get the same screen output as from the executable. At the end of the output, you'll see the functionals written to screen,
Post-Processing
Thanks to the calls to writeVolSolution and writeSurface, we obtain a volume file vol_pylava.q and surface file surface_pylava.plt, respectively. The former is a plot3d function file which can be opened in conjunction with grid.x with any visualization software that handles plot3d format. The surface file is a Tecplot binary format.
Airfoil shape optimization
LAVA's curvilinear solver incorporates many features that make it a good tool for gradient-based optimization12. In this tutorial we outline the how to optimize an airfoil in transonic flight starting from a NACA 0012 using LAVA. In some sense, airfoil optimization is the simplest form of aerodynamic shape optimization. In fact, the mesh used for this tutorial is small enough that you could probably use a laptop to run this case.
Warning
The optimization features in LAVA are still evolving, and you may encounter bugs or unexpected behavior. The steps in and results from this tutorial have been tested and are expected to work as described.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVACurv input file structure — see Curvilinear Solver Inputs
- pyLAVA python environment setup on your computer — see pyLAVA Setup and Requirements
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| naca0012_rans.x | grid file |
| naca0012_rans.bc | grid file boundary conditions |
| naca0012.b2b | grid file block-to-block connectivity |
| run.yaml | solver input file |
| opt.yaml | optimization input file |
| run_opt.py | optimization run script |
| ffd.xyz | FFD parameterization mesh |
create a directory that has the files structured like this
├── ffd
│ └── ffd.xyz
├── meshes
│ ├── naca0012_rans.bc
│ └── naca0012.b2b
│ └── naca0012_rans.x
├── opt.yaml
├── run_opt.py
└── run.yaml
Environment Setup
For this example we will be using pyLAVA. See this documentation for information on setting up pyLAVA. This tutorial relies on Python packages listed in the Optimization Requirements section.
Once this is complete, make and navigate to a working directory of your choosing for this tutorial.
Hereon, we will assume that you are working from this directory.Mesh setup
The mesh is an O-grid with an off-wall spacing of 2e-6 which corresponds to a y+ of roughly 1. In total, it has only 38 thousand nodes. LAVA curvilinear only reads 3D meshes, so the mesh is a 2D mesh extruded by 1 cell to make it 3D. There is no need to run connectivity before running this case, because the mesh has no overset regions.
Note
The run scripts provided expect the mesh to be placed in a subdirectory called meshes
B2B file
To specify the connection between block faces used by the O-grid topology you will need a B2b file.
!----------------------------------------------------------------------------------------------------------------------------
! BlkID js je ks ke ls le DonorID djs dje dks dke dls dle tx ty tz
!----------------------------------------------------------------------------------------------------------------------------
1 1 1 1 -1 1 -1 1 -1 -1 1 -1 1 -1 1 2 3
1 -1 -1 1 -1 1 -1 1 1 1 1 -1 1 -1 1 2 3
BC file
This file gives family names to the surfaces of the block.
We have 3 families, wall for the viscous wall of the airfoil, far for the farfield, and sym for the two symmetry planes.
We apply symmetry boundary conditions to the planes in the "span-wise" direction of the airfoil even though it is one cell thick.
!----------------------------------------------------------------------------------
! Family nz jbeg,jend kbeg,kend lbeg,lend
!----------------------------------------------------------------------------------
wall 1 1 -1 1 -1 1 1
far 1 1 -1 1 -1 -1 -1
sym 1 1 -1 1 1 1 -1
sym 1 1 -1 -1 -1 1 -1
Solver Setup
The solver is set up and run through a python run script.
Flow Solver Options
The run.yaml file contains a standard set of options to run a RANS simulation in LAVA Curvilinear.
You can see all the flow solver options that you can define on this page.
Optimization Options
The opt.yaml file contains the options specific to the optimization problem we are solving.
You can see all the optimization options that you can define on this page.
Let's break down the contents of opt.yaml by section in this particular example.
objective
In this tutorial we are going to use coefficient of drag as our objective function.
You can use any functional that LAVA outputs as an objective function or any weighted combination of functions as well.
Since we expect the drag to stay around order 1e-2, we set the scale of the objective function to bring it up to approximately order 1.
This is common practice in optimization and generally helps the optimizer.
objective :
name: drag
functionals :
- func : cd
weight : 1.0
scale: 100.0
optimizer :
name: SLSQP
options:
IFILE: SLSQP.out
lava
pyLAVA imports the dynamic library from LAVA to pass information directly to routines on the Fortran layer.
So that pyLAVA can find the library, we must specify the path and suffix of the shared library object if it is not already on our LD_LIBRARY_PATH.
Required Modifications to opt.yaml
You will need to update opt.yaml file to provide the correct lava.suffix entry for your architecture.
For example, at the time of writing, on the NAS cluster, the module LAVA provides the
LAVA dynamic libraries liblavacurv.3D.NS1.INTEL.AVX2.HPEMPT-lib.so and liblavacurv.3D.NS1.INTEL.AVX512.HPEMPT-lib.so.
The suffix in this case is 3D.NS1.INTEL.AVX2.HPEMPT-lib or 3D.NS1.INTEL.AVX512.HPEMPT-lib.
You must enter one of these in the lava.suffix entry in opt.yaml depending on the architecture of the machine you are running on.
designVars
The optimizer modifies the design through the design variables.
There are two categories of design variables aero and ffd.
In the aero category we specify that we want to modify the angle of attack and supply lower and upper bounds of the variable.
If one excludes a bound the variable will be unbounded in that direction.
Next under the ffd category we add variable to control the shape of the airfoil.
Specifically we add spanwiseLocal design variables that move in the y-direction.
This type of design variable applies the same change to every station of the FFD in the spanindex direction.
This is useful here because our FFD and mesh are actually 3D, but we would like the design variables to act 2-dimensionally.
designVars :
aero :
- name : alpha
value : 1.5
lower : 0.0
upper : 10.0
scale : 1.0
ffd :
- name: airfoil_ffd
filename: ./ffd/ffd.xyz
families: ['wall']
spanwiseLocal:
name: local
lower : -0.05
upper : 0.05
scale : 1.0
axis : 'y'
spanindex: 'k'
constraints
The constraints are perhaps the most important section.
Without proper constraints it is unlikely that you will get a useable design.
Under the aero section we can constrain any of the functional from the flow solve.
In this case we are constraining cl to be at the target by setting the lower and upper bounds equal to the target, 0.5.
Next we apply pinnedLeTe constraints, which prevents the shape variables from skewing the airfoil to add a net twist.
More precisely, these options add a linear constraint to ensure the shape variables do not move the leading or trailing edge points by specifying that the design variables there have to move in equal and opposite directions.
One can also specify geometric contraints via pyLAVA's wrapping of pyGeo 3.
We start by specifying a surface family name that we would like to use for geometric constraints, in this case wall.
This surface is used by the volume and thickness constraints, which measure the internal volume and thickness of the airfoil.
Both constraints require a list of points at the leading and trailing edge.
See the addVolumeConstraint and addThicknessConstraints2D in the pyGeo documentation for more details on these constraints.
constraints :
aero :
- name : cl_con
functionals :
- func : cl
weight : 1.0
upper : 0.5
lower : 0.5
pinnedLeTe:
- volID: 0
faceID: iLow
topID: 'k'
# start: 0
# end: 1
- volID: 0
faceID: iHigh
topID: 'k'
surfaces:
- name: wall
volume:
- leList: [[1.0e-3, 0, 1.0e-1], [1.0e-3, 0, 0.9]]
teList: [[0.999 , 0, 1.0e-1], [0.999, 0, 0.9]]
nSpan: 2
nChord: 100
lower: 1.0
surfaceName: wall
thickness:
- leList: [[1.0e-3, 0, 1.0e-1], [1.0e-3, 0, 0.9]]
teList: [[0.999 , 0, 1.0e-1], [0.999, 0, 0.9]]
nSpan: 2
nChord: 10
lower: 0.1
upper: 3.0
surfaceName: wall
optimizer
This section is used to specify which optimizer from pyOptSparse4 we would like to use and any associated options to pass to that optimizer.
We are using SLSQP for this example because it is freely available, but SNOPT is the preferred optimizer.
objective :
name: drag
functionals :
- func : cd
weight : 1.0
scale: 100.0
optimizer :
name: SLSQP
options:
IFILE: SLSQP.out
output
Setting outputDir will direct the output defined in this section to another location.
This section also allows you to modify the optimization monitor file that is used to track the progress of the optimization.
Additionally, one can specify what types of solutions are written to disk after an optimization iteration.
In this tutorial we write both volume and surface files.
Be aware that for cases with larger meshes and more complex optimization problems, writing the volume solution out at every step can consume lots of storage.
output :
outputDir: Output
monitor :
filename: optMonitor.txt
variables: [cd,cl]
surface :
- first: True
frequency: 1
variables: [cp, cfx]
volume :
- first : True
frequency: 1
variables: [pressure, cp, mach]
designVars:
- variables: [alpha, local]
frequency : 1
first : True
print : True
history :
filename : history.hst
Python Script
The run_opt.py script orchestrates the optimization process.
Let us discuss the specific sections of the script below.
First, We take a run.yaml that we could use to run the solver from the command line and load the solver options into our optimization script.
We have defined the options relevant to the optimization in a YAML file as well.
Both of these YAML files are loaded in as python dictionaries.
You can modify entries in the options dictionaries directly in python. In fact, you could define all your options in a dictionary rather than loading that dictionary from a YAML file. This can be useful when you only intend to use LAVA via pyLAVA and want to keep all your options inside the runscript. In this tutorial, we modify the output directory of the solver data to be the same as the output directory of the optimization data. Additionally, we disable the output of restart, surface, and volume data during a CFD solution, since we want to write output after the solution for each optimization iteration.
# Read the YAML file name for lava
with open("run.yaml", "r") as f:
lava_options = yaml.safe_load(f)
with open("opt.yaml", "r") as f:
opt_options = yaml.safe_load(f)
# set the output directory to be the same for run data and optimization data
outputDir = opt_options['output']['outputDir']
lava_options['curvsolver']['outputDir'] = outputDir
# modify the options to disable output during ducring the convergence of a single CFD solve.
lava_options['output']['restart'] = {'frequency': -1}
lava_options['output']['surface'] = [{'frequency': -1}]
lava_options['output']['volume'] = [{'frequency': -1}]
These options for the solver and optimization are passed to optLAVA to create an object that manages the optimization process.
# Instantiate the class
solver = optLAVA(lava_options, opt_options)
# Initialize the optimization problem
solver.initOptimization(opt_options)
# this gives a visual summary of the design variables, objective, and constraints
solver.optProb.printSparsity()
# Optimize
sol = solver()
# Check Solution
if (solver.comm.rank == 0):
print(sol)
solver.AeroSolver.writeSurface(f"{outputDir}/surface.final.plt", fields=['cp', 'cfx'])
Running on the NAS cluster
Below is an example run script where we load the LAVA module which add pyLAVA to our python path. We also source a virtual environment that has DVGeo and pyOptsparse installed.
Note
You will have to install the packages outlined in the Optimization Requirements and set the python environment accordingly. Your script will not exactly match how we activated the environment.
The lava dynamic library, liblavacurv.SUFFIX.so, must either be on your LD_LIBRARY_PATH or specified in the opt.yaml.
#!/bin/bash
#PBS -S /bin/bash
#PBS -N airfoil_opt_curv
#PBS -l walltime=02:00:00
#PBS -l select=1:ncpus=512:mpiprocs=4:model=tur_ath
#PBS -q normal
#PBS -W group_list=<your project group ID>
#PBS -j oe
# Load LAVA module
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# activate your python environment!
# this will be specific to you!
source path/to/virtual_env/bin/activate
# Set environment
export OMP_NUM_THREADS=128
# Change to working directory
cd $PBS_O_WORKDIR
# Run LAVA (4 MPI ranks per node, 128 threads each)
log_file="run.log"
mpiexec -ppn 4 --cpu-bind none mbind.x -cs -t $OMP_NUM_THREADS \
python run_opt.py 2>&1 |& tee -a ${log_file}
Post-Processing
Optimization Progress
While the optimization is running you can monitor progress of drag and lift coefficients by looking at the optMonitor.txt file in the Output directory.
This file contains information about each optimization iteration including whether the mesh and flow solves were successful, the number of flow iterations taken, the final flow residual, and the value of the functions specified in the monitor section of opt.yaml.
------------------------------------------------------------------------------------------------------
| Function | Mesh | Flow | Flow | Flow | | |
| Eval | Success | Success | Iterations | Residual | cd | cl |
------------------------------------------------------------------------------------------------------
1 True True 373 9.859862e-13 0.029727241 0.5000219
2 True True 708 9.646269e-13 0.10150295 -0.32082938
3 True True 490 9.707289e-13 0.026195402 0.25636632
4 True True 375 9.742539e-13 0.015624216 0.46630009
5 True True 541 9.380633e-13 0.10999449 -0.20661778
The history.hst file generated in the Output directory is an Sqlite database created by pyOptSparse that contains the history of the design variables and functions.
You can use pyOptSparse's OptView module to plot the design variable and function history.
The command
Visualizing the optimized shape
To visualize the progression of the optimization you can load all the output surfaces files into Tecplot.
By default, Tecplot interprets each optimization iteration as a different time step making it easy to flip between designs.
Something similar can be achieved in Paraview by loading in the output files as a "stack".
The optimized airfoil should have a maximum thickness that is further aft relative to the baseline.

Relevant Publications
-
Lowe, B. M., Ashby, C. P., Koch, J. R. L., Craig Penner, D. A., Housman, J. A., and Duensing, J. C., "Towards Aerodynamic Shape Optimization Using an Immersed Boundary Overset Grid Method," American Institute of Aeronautics; Astronautics, July2024. https://doi.org/10.2514/6.2024-4229 ↩
-
Chau, T., Anibal, J. L., Lowe, B. M., Machado, L. M., and Duensing, J. C., "High-Fidelity Aeropropulsive Assessment of Distributed Electric Propulsion and Boundary Layer Ingestion for the SUSAN Electrofan," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-1275 ↩
-
Hajdik, H. M., Yildirim, A., Wu, E., Brelje, B. J., Seraj, S., Mangano, M., Anibal, J. L., Jonsson, E., Adler, E. J., Mader, C. A., Kenway, G. K. W., and Martins, J. R. R. A., "[pyGeo]{.nocase}: A Geometry Package for Multidisciplinary Design Optimization," Journal of Open Source Software, Vol. 8, No. 87, 2023, p. 5319. https://doi.org/10.21105/joss.05319 ↩
-
Wu, E., Kenway, G., Mader, C. A., Jasa, J., and Martins, J. R. R. A., "[pyOptSparse:]{.nocase} A Python Framework for Large-Scale Constrained Nonlinear Optimization of Sparse Systems," Journal of Open Source Software, Vol. 5, No. 54, 2020, p. 2564. https://doi.org/10.21105/joss.02564 ↩
Wing Twist Optimization
LAVA's curvilinear solver incorporates many features that make it a good tool for gradient-based optimization12. This tutorial demonstrates gradient‑based twist optimization of the CRM wing to minimize drag while meeting target lift and pitch‑moment requirements under transonic cruise conditions1. Concretely, the objective is to reduce \(C_D\) subject to \(C_L = 0.5\) and \(C_{My} \le -0.17\) at \(M=0.8\) and \(Re=22.2\times10^6\).
Warning
The optimization features in LAVA are still evolving, and you may encounter bugs or unexpected behavior. The steps in and results from this tutorial have been tested and are expected to work as described.
Looking for a more advanced example?
Interested in a more comprehensive tutorial? We also provide a wing–body–tail trim case, where the aircraft is trimmed by adjusting both the angle of attack and the tail rotation to achieve a target lift coefficient and zero pitching moment. To access this advanced tutorial, please contact jared.c.duensing@nasa.gov.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Python 3.9 or above installed on your system
Environment Setup
For this example we will be using pyLAVA. See this documentation for information on setting up pyLAVA. This tutorial relies on Python packages listed in the Optimization Requirements section.
Tutorial Files
Make and navigate to a working directory of your choosing for this tutorial.
Hereon, we will assume that you are working from this directory.Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | Grid file |
| grid.b2b | Block-to-block file |
| grid.bc | Boundary condition file |
| ffd.xyz | Free-form deformation volume file |
| lava.yaml | LAVA solver input file |
| opt.yaml | LAVA optimization input file |
| run_opt.py | Python script for optimization |
Arrange the downloaded files in the following structure:
crm_wing_opt/
├── lava.yaml
├── opt.yaml
├── run_opt.py
├── meshes/
│ ├── grid.x
│ ├── grid.b2b
│ └── grid.bc
└── ffd/
└── ffd.xyz
Mesh setup
In this tutorial, we will be solving for the flow around the CRM-Wing only geometry from test case 4 of the AIAA Aerodynamic Design Optimization Discussion Group. The grid was originally published by Lyu et al.3 and made available through the following source.
CRM: Common Research Model grid files
Source: Mendeley Data DOI: 10.17632/7jnyjdbvf9/1
Licensed under CC BY 4.0
Original authors: Zhoujie Lyu, Gaetan K. W. Kenway, Joaquim R. R. A. Martins
Solver Setup
The solver and optimization problem are set up through two YAML files, and run through a Python run script:
lava.yaml: Contains the flow solver options for LAVA Curvilinear.opt.yaml: Contains the optimization problem definition and options.run_opt.py: A Python script that orchestrates the optimization process.
The remainder of this section will break down the contents of these files.
Flow Solver Options
The lava.yaml file contains a standard set of options to run a RANS simulation in LAVA Curvilinear.
You can see all the flow solver options that you can define on this page.
Optimization Options
Required Modifications to opt.yaml
You will need to update opt.yaml file to provide the correct lava.suffix entry for your architecture.
For example, at the time of writing, on the NAS cluster, the module LAVA provides the
LAVA dynamic libraries liblavacurv.3D.NS1.INTEL.AVX2.HPEMPT-lib.so and liblavacurv.3D.NS1.INTEL.AVX512.HPEMPT-lib.so.
The suffix in this case is 3D.NS1.INTEL.AVX2.HPEMPT-lib or 3D.NS1.INTEL.AVX512.HPEMPT-lib.
You must enter one of these in the lava.suffix entry in opt.yaml depending on the architecture of the machine you are running on.
Performing optimization using the optLAVA class requires an additional YAML file to define the optimization problem.
You can see all the optimization options that you can define on this page.
We further break down the contents of this file below.
Objective Functions Section
Here we specify that the objective function for this problem is the drag coefficient (\(C_D\)).
LAVA Section
# LAVA Dynamic Library options
lava :
suffix : 3D.NS1.INTEL.AVX2.OPENMPI-lib # LAVA dynamic library suffix name (libsuperlava.SUFFIX.so)
The suffix entry specifies the partial name of the LAVA library that we will be linking to. The library is typically called liblavacurv.SUFFIX.so.
Python will search your LD_LIBRARY_PATH for this library.
However, if you do not want liblavacurv.SUFFIX.so to exist in your LD_LIBRARY_PATH, you can also provide the absolute or relative path to the library through an entry called libpath in this portion of the opt.yaml file.
Design Variable Options Section
# Design variable options
designVars :
# Freeform deformation-based design variables
ffd:
- name : wingffd # Unique name for this FFD
filename : ffd/ffd.xyz #file path to plot3d ascii file containing FFD
families : [wall] # list of BCs to include in this FFD; family names correspond to LAVA's grid.BC file
axialCurve : # Define an "axial curve" about which the wing can twist
- name : wingaxis # unique name for curve
xFraction : 0.25 # fraction along x-axis where the curve will be placed in the FFD
alignIndex : j # ijk index which the curve will follow
twist : # Define the twist design variables
name : twist # Unique name for the design variable
curve : wingaxis # Name of the curve about which to twist
axis : y # Axis of rotation for twist
lower : -10. # Lower bound
upper : 10. # Upper bound
scale : 1.0 # Scaling factor
Here, we are introducing an FFD section into our design variables options which will tell optLAVA that we are using an FFD-based geometric parameterization. Within the FFD section, user can specify multiple FFDs, but here we only use one for the wing.
Several things need to be specified for the FFD:
- name: Unique name for the FFD
- filename: path to the FFD file
- families: List of BCs to include in this FFD
In this specific yaml, we also specify an axial curve about which the wing can twist. We also specify the twist design variables.
Constraint Options Section
# Constraint options
constraints :
# Aerodynamic constraints
aero :
- name : cl # Name of aerodynamic functional
upper : 0.5 # Upper bound
lower : 0.5 # Lower bound (if equal to upper bound, an equality constraint is used)
scale : 2.0 # Scaling factor
- name : cmy
upper : Null
lower : -0.17
scale : 1.0
This section defines the constraints in our optimization problem. In this specific problem, we only have aerodynamic constraints, namely \(C_L = 0.5\) and \(C_{My} \le -0.17\).
Optimizer-Specific Options Section
These options are given directly to pyOptSparse4 for the optimization problem. They are case sensitive.
Output Options Section
# Output options
output :
outputDir: Output # Output directory
monitor : # Optimization monitor options
filename: optMonitor.txt # File name for optimization monitor
variables: [cl, cd, cmy] # Vars and functionals we want to monitor (fairly limited right now)
surface : # Surface output options (writes a .plt file)
- frequency : 1 # Frequency of output (measured in function evals)
variables: [cp] # Aerodynamic field variables we want written on the surface
volume : # Volume output options (writes a .x and .q file)
- frequency : 1 # Frequency of output (measured in function evals)
filetype: plot3d # Output file type
variables : [pressure, velocityx, velocityy, velocityz, temperature, nut] # Aerodynamic field variables
history : # pyOptSparse history file
filename : history.hst # file name
Similar to the LAVA flow solve yaml, user can specify surface and volume outputs during the optimization. The frequency for these files is based on the functional evaluation number and all files are written to the directory specified by the option outputDir. In addition, the history filename is given to pyOptSparse which will generate the history database for the optimization problem. This history database can be used to restart the optimization job.
During the optimization, the user can choose to have certain quantities written to a certain file at each functional evaluation. In this section, the user specifies the filename and the variables that they want written.
Python Script
This tutorial will make use of the aformentioned Python script to run the optimization problem. We will break down the contents of this script below.
Imports
In this line, we import theoptLAVA class. This class allows for easy interfacing with pyOptSparse and pyGeo5. It also reads the optimization yaml provided by the user and creates the optimization problem based on this.
Read YAML
# Read the YAML file name for lava options
with open("lava.yaml", "r") as f:
lava_options = yaml.safe_load(f)
# Read in the YAML file for optimization options
with open("opt.yaml", "r") as f:
opt_options = yaml.safe_load(f)
Here, we load in the yaml into python dictionary. The lava.yaml file contains the inputs for the LAVA flow solver. The opt.yaml contains inputs for the optimization problem. Inputs to the opt.yaml will be discussed further below.
Solver Instantiation
# Instantiate the class
solver = optLAVA(lava_options, opt_options, comm=MPI.COMM_WORLD)
# Initialize the optimization problem
solver.initOptimization(opt_options)
-
The LAVA flow solver is initialized.
-
A pyGeo object is created (if we have specified geometric design variables).
-
The geometric design variables are setup in the pyGeo object.
-
Geometric constraints are also setup in the pyGeo object.
The initOptimization call sets up the pyOptSparse object. It adds the objective function and constraints as well as the design variables to the optimization problem in the pyOptSparse object.
Optimization
When the solver is called, this runs the optimization problem and returns the solution from pyOptSparse. When printed, the solution will show objective, constraints and design variable values.Running
Running on the NAS Cluster
Aitken Supercomputer
Modify the lava.suffix entry in the opt.yaml file to contain the following,
The following PBS script can be used to run this example on the NAS cluster using Aitken Rome Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_wing_opt_curv
#PBS -l select=1:ncpus=128:mpiprocs=4:model=rom_ait
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# This is to be safe (communication bug with the infiniband)
export MPI_NUM_MEMORY_REGIONS=0
# Run optimization script
log_file="run.log"
mpiexec -np 4 mbind.x -t 32 python run_opt.py 2>&1 |& tee -a ${log_file}
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
To run this case, submit the optimization PBS script:
Aitken Supercomputer
Modify the lava.suffix entry in the opt.yaml file to contain the following,
The following PBS script can be used to run this example on the NAS cluster using Aitken Rome Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_wing_opt_curv
#PBS -l select=1:ncpus=128:mpiprocs=4:model=rom_ait
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# This is to be safe (communication bug with the infiniband)
export MPI_NUM_MEMORY_REGIONS=0
# Run optimization script
log_file="run.log"
mpiexec -np 4 mbind.x -t 32 python run_opt.py 2>&1 |& tee -a ${log_file}
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
Warning
At the time of writing, we have had difficulty using mpi4py across Rome nodes. Thus, you may currently only be capable of running this tutorial on a single Rome node.
To run this case, submit the optimization PBS script:
Running on External Systems
Modify the suffix argument in the opt.yaml file to match the suffix for the LAVA Dynamic Library that is compatible with your system.
Additionally, if the path to the LAVA Dynamic Library is not included in the LD_LIBRARY_PATH environment variable, then you will need to add the libPath input in opt.yaml. Together, these should look something like the following inside of your opt.yaml file:
lava :
suffix : lava_dynamic_library_suffix_for_your_system # LAVA dynamic library suffix name (liblavacurv.SUFFIX.so)
libpath : /path/to/lava/dynamic/library # Path to LAVA dynamic library
LD_LIBRARY_PATH environment variable, then you can omit the libpath input and simply ensure that the suffix entry matches the suffix for the LAVA Dynamic Library that is compatible with your system.
If you created a Python virtual environment following the directions in the environment setup instructions above, make sure to activate that environment in your terminal:
For a single MPI rank, you can run the following command,
For multiple MPI ranks, you can run the following command,
Note
When running with OpenMPI, proper thread binding may require additional flags for optimal performance. We have found that the following command ensures correct binding:
export OMP_NUM_THREADS=28
mpirun -np 4 --map-by slot:PE=$OMP_NUM_THREADS --bind-to hwthread python run_opt.py | tee run.out
OMP_NUM_THREADS based on the number of threads you want to use.
Post-Processing
Optimization Progress
While the optimization is running you can monitor progress of the drag, lift, and pitching moment coefficients by looking at the optMonitor.txt file in the Output directory.
This file contains information about each optimization iteration including whether the mesh and flow solves were successful, the number of flow iterations taken, the final flow residual, and the value of the functions specified in the monitor section of opt.yaml.
-----------------------------------------------------------------------------------------------------------------------
| Function | Mesh | Flow | Flow | Flow | | | |
| Eval | Success | Success | Iterations | Residual | cl | cd | cmy |
-----------------------------------------------------------------------------------------------------------------------
1 True True 115 9.459043e-13 0.51075711 0.023217536 -0.18329909
2 True True 115 8.514144e-13 0.50010363 0.022865142 -0.17011882
3 True True 115 8.005533e-13 0.50000001 0.02286176 -0.17000001
The history.hst file generated in the Output directory is an Sqlite database generated by pyOptSparse that contains the history of the design variables and functions.
You can use pyOptSparse's OptView module to plot the design variable and function history.
The command
Visualizing the Optimized Shape
Throughout the optimization, surface and volume outputs are written to the Output directory at each functional evaluation because we specified an output frequency of 1 in the opt.yaml file.
These surface and volume files can be vizualized using Tecplot or other similar software.
However, we will also discuss how to extract design variables from the history file and generate surface and volume outputs at specified design iterations.
The following script is used for this purpose:
run_post.py
# ==================================================================
# === Post-Processing ==============================================
# ==================================================================
""" This script is an example of how to post-process the wing twist
optimization case to extract and analyze specific design iterations
with pyLAVA.
See the documentation for more details.
you can run the script like this:
mpirun -np 2 mbind.x -t 14 python run_post.py
"""
# === Import =======================================================
from mpi4py import MPI
import yaml
from pylava.pyLAVA_optimization import optLAVA
from pyoptsparse import History
# ==================================================================
# === Helper Functions =============================================
# helper-start
def runAnalysis(x, fileSuffix):
# Deform the mesh to match these DVs
solver._setDVs(x)
# Solver the flow
solver.AeroSolver(resetIter=True)
# Write the optimized volume and surface
solver.AeroSolver.writeVolGrid(f"volume.{fileSuffix}.x")
solver.AeroSolver.writeVolSolution(f"volume.{fileSuffix}.q", "plot3dSoln", ['pressure'])
solver.AeroSolver.writeSurface(f"surface.{fileSuffix}.plt",
fields=["iblank", "yplus", "cp", "cf", "cfx", "cfy", "cfz"])
# helper-end
# ==================================================================
# === Run ==========================================================
# Read the YAML file name for lava options
with open("lava.yaml", "r") as f:
lava_options = yaml.safe_load(f)
# Read in the YAML file for optimization options
with open("opt.yaml", "r") as f:
opt_options = yaml.safe_load(f)
# Instantiate the class
solver = optLAVA(lava_options, opt_options, comm=MPI.COMM_WORLD)
# hist-start
# Read the history file using pyOptSparse's History Class
hist = History("Output/history.hst", flag="r")
vals = hist.getValues()
# hist-end
# run-start
# Set the DVs to the first iteration
# and call the helper function above to solve the flow and
# write the geometry + solution
dvDict = {'wingffd_twist' : vals['wingffd_twist'][0]}
runAnalysis(dvDict, "initial")
# Set the DVs to the last iteration
# and call the helper function above to solve the flow and
# write the geometry + solution
dvDict = {'wingffd_twist' : vals['wingffd_twist'][-1]}
runAnalysis(dvDict, "optimized")
# run-end
# ==================================================================
Let us break down the contents of this script below.
Helper Function
def runAnalysis(x, fileSuffix):
# Deform the mesh to match these DVs
solver._setDVs(x)
# Solver the flow
solver.AeroSolver(resetIter=True)
# Write the optimized volume and surface
solver.AeroSolver.writeVolGrid(f"volume.{fileSuffix}.x")
solver.AeroSolver.writeVolSolution(f"volume.{fileSuffix}.q", "plot3dSoln", ['pressure'])
solver.AeroSolver.writeSurface(f"surface.{fileSuffix}.plt",
fields=["iblank", "yplus", "cp", "cf", "cfx", "cfy", "cfz"])
optLAVA class, calls the flow solver (AeroSolver, which is an instance of the LAVA class from pylava), and generates volume and surface files with the corresponding suffix given by the user.
Reading History File
# Read the history file using pyOptSparse's History Class
hist = History("Output/history.hst", flag="r")
vals = hist.getValues()
getValues function returns a dictionary of data for each optimization iteration.
Generating Outputs at Specified Iterations
# Set the DVs to the first iteration
# and call the helper function above to solve the flow and
# write the geometry + solution
dvDict = {'wingffd_twist' : vals['wingffd_twist'][0]}
runAnalysis(dvDict, "initial")
# Set the DVs to the last iteration
# and call the helper function above to solve the flow and
# write the geometry + solution
dvDict = {'wingffd_twist' : vals['wingffd_twist'][-1]}
runAnalysis(dvDict, "optimized")
dvDict for a specified optimization iteration (the first 0 and the last -1), and we call the helper function to generate surface and volume outputs at these iterations.
The results will the be the following files, which can be opened in Tecplot or any other similar software:
surface.initial.plt
volume.initial.q
volume.initial.x
surface.optimized.plt
volume.optimized.q
volume.optimized.x
You can tighten the optimization tolerance and rerun the optimization for lower drag at the expense of more function evaluations. For example, to change the optimality tolerance from the defaul of 1e-6 to 1e-8 you would set the options like this.
Relevant Publications
-
Lowe, B. M., Ashby, C. P., Koch, J. R. L., Craig Penner, D. A., Housman, J. A., and Duensing, J. C., "Towards Aerodynamic Shape Optimization Using an Immersed Boundary Overset Grid Method," American Institute of Aeronautics; Astronautics, July2024. https://doi.org/10.2514/6.2024-4229 ↩↩
-
Chau, T., Anibal, J. L., Lowe, B. M., Machado, L. M., and Duensing, J. C., "High-Fidelity Aeropropulsive Assessment of Distributed Electric Propulsion and Boundary Layer Ingestion for the SUSAN Electrofan," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-1275 ↩
-
Lyu, Z., Kenway, G. K. W., and Martins, J. R. R. A., "Aerodynamic Shape Optimization Investigations of the Common Research Model Wing Benchmark," AIAA Journal, Vol. 53, No. 4, 2015, pp. 968--985. https://doi.org/10.2514/1.J053318 ↩
-
Wu, E., Kenway, G., Mader, C. A., Jasa, J., and Martins, J. R. R. A., "[pyOptSparse:]{.nocase} A Python Framework for Large-Scale Constrained Nonlinear Optimization of Sparse Systems," Journal of Open Source Software, Vol. 5, No. 54, 2020, p. 2564. https://doi.org/10.21105/joss.02564 ↩
-
Hajdik, H. M., Yildirim, A., Wu, E., Brelje, B. J., Seraj, S., Mangano, M., Anibal, J. L., Jonsson, E., Adler, E. J., Mader, C. A., Kenway, G. K. W., and Martins, J. R. R. A., "[pyGeo]{.nocase}: A Geometry Package for Multidisciplinary Design Optimization," Journal of Open Source Software, Vol. 8, No. 87, 2023, p. 5319. https://doi.org/10.21105/joss.05319 ↩
Wing Twist Optimization using OpenMDAO
LAVA's curvilinear solver incorporates many features that make it a good tool for gradient-based optimization12. This tutorial demonstrates how to set up and run a gradient‑based twist optimization of the CRM wing using OpenMDAO3 and MPhys4 using the LAVA Curvilinear flow solver. Specifically, we replicate the optimization problem presented in the wing twist optimization tutorial, where we aim to minimize drag while meeting target lift and pitch‑moment requirements under transonic cruise conditions. Concretely, the objective is to reduce \(C_D\) subject to \(C_L = 0.5\) and \(C_{My} \le -0.17\) at \(M=0.8\) and \(Re=22.2\times10^6\).
Warning
The optimization features in LAVA are still evolving, and you may encounter bugs or unexpected behavior. The steps in and results from this tutorial have been tested and are expected to work as described.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Python 3.9 or above installed on your system
Environment Setup
For this example we will be using pyLAVA. See this documentation for information on setting up pyLAVA. This tutorial relies on Python packages listed in the OpenMDAO-based Optimization Requirements section.
Additionally, geometric parameterization will rely on pyGeo5, so please install the following packages as well
| Package Name | Package Site | Description | Tested Version |
|---|---|---|---|
pyspline |
link | Python tools for B-spline curves, surfaces, volumes | 1.5.3 |
pygeo |
link | Object-oriented geometry framework for MDO and CAD. | 1.17.0 |
Tutorial Files
Make and navigate to a working directory of your choosing for this tutorial.
mkdir -p /path/to/lava_tutorials/crm_wing_opt_openmdao
cd /path/to/lava_tutorials/crm_wing_opt_openmdao
Download the input files for this tutorial:
| File | Description |
|---|---|
| grid.x | Grid file |
| grid.b2b | Block-to-block file |
| grid.bc | Boundary condition file |
| ffd.xyz | Free-form deformation volume file |
| lava.yaml | LAVA solver input file |
| run_om_opt.py | Python script for optimization |
Arrange the downloaded files in the following structure:
crm_wing_opt_openmdao/
├── lava.yaml
├── run_om_opt.py
├── meshes/
│ ├── grid.x
│ ├── grid.b2b
│ └── grid.bc
└── ffd/
└── ffd.xyz
Mesh setup
In this tutorial, we will be solving for the flow around the CRM-Wing only geometry from test case 4 of the AIAA Aerodynamic Design Optimization Discussion Group. The grid was originally published by Lyu et al.6 and made available through the following source.
CRM: Common Research Model grid files
Source: Mendeley Data DOI: 10.17632/7jnyjdbvf9/1
Licensed under CC BY 4.0
Original authors: Zhoujie Lyu, Gaetan K. W. Kenway, Joaquim R. R. A. Martins
Solver Setup
The solver is set up through a YAML files, and the optimization problem is run through a Python run script:
lava.yaml: Contains the flow solver options for LAVA Curvilinear.run_om_opt.py: A Python script that orchestrates the optimization process.
Note
OpenMDAO-based optimizations do not require a separate opt.yaml file, as was required in other tutorials.
All optimization options are specified directly in the python script using OpenMDAO's API.
The remainder of this section will break down the contents of these files.
Flow Solver Options
The lava.yaml file contains a standard set of options to run a RANS simulation in LAVA Curvilinear.
You can see all the flow solver options that you can define on this page.
Python Script
This tutorial will make use of the following Python script to run the optimization problem:
We will break down the contents of this script below.
Imports
import openmdao.api as om
from mphys import Multipoint, MPhysVariables
from mphys.scenarios.aerodynamic import ScenarioAerodynamic
from pylava.mphys.mphys_lava import LAVABuilder
from pygeo.mphys import OM_DVGEOCOMP
In the imports section, we import the necessary modules from OpenMDAO, MPhys, pyLAVA, and pyGeo.
This includes the LAVABuilder class from pylava.mphys.mphys_lava, which is used to create the LAVA flow solver component for MPhys.
Read YAML
# Read the YAML file name for lava options
with open("lava.yaml", "r") as f:
lava_options = yaml.safe_load(f)
Here, we load in the yaml into python dictionary. The lava.yaml file contains the inputs for the LAVA flow solver.
LAVA MPhys Builder
# LAVA Builder
lava_builder = LAVABuilder(lava_options, scenario="aerodynamic",
lava_suffix='3D.NS1.INTEL.AVX2.OPENMPI-lib',
design_surf_fams=["wall"],
functionals=["cl","cd","cmy"])
lava_builder.initialize(self.comm)
LAVABuilder, several arguments can be passed. In this tutorial we pass the following:
lava_options: The dictionary of options for the LAVA flow solver.scenario: The MPhys scenario to be used. In this case, we are using theScenarioAerodynamicclass for aerodynamic analysis.design_surf_fams: A list of surface family names that will be used for geometric design variables. In this case, we are using thewallsurface family for twist optimization. Note that the families are specified in thegrid.bcfile.functionals: These are the aerodynamic functionals that will be set as outputs to the LAVA OpenMDAO Group, thus making them available to OpenMDAO, either to connect to other components or to use as objectives/constraints in an optimization problem. In this case, we are usingcl,cd, andcmy.
MPhys Setup
# # == MPhys Setup ==
# Keep DVs at the top level
self.add_subsystem("dvs", om.IndepVarComp(), promotes=["*"])
# Add mesh to subsystems
self.add_subsystem('mesh', lava_builder.get_mesh_coordinate_subsystem())
# Add the geometry component from pyGeo
self.add_subsystem("geometry", OM_DVGEOCOMP(
file=os.path.join("ffd","ffd.xyz"), type="ffd"))
# We're cruisin
self.mphys_add_scenario("cruise", ScenarioAerodynamic(aero_builder=lava_builder))
# Ensure that the mesh and cruise coordinates are the same
self.connect(
f"mesh.{MPhysVariables.Aerodynamics.Surface.Mesh.COORDINATES}",
f"geometry.{MPhysVariables.Aerodynamics.Surface.Geometry.COORDINATES_INPUT}"
)
self.connect(
f"geometry.{MPhysVariables.Aerodynamics.Surface.Geometry.COORDINATES_OUTPUT}",
"cruise.x_aero")
Here, in the MPhys setup portion of the Multipoint OpenMDAO Group, several steps occur:
- We add an independent component
dvs, which will hold the design variables for the optimization problem. - We add a component
mesh, which outputs the undeformed surface mesh. - We add a component
geometry, which is a pyGeoOM_DVGEOCOMPcomponent that will handle the geometric design variables and constraints. - We call the Multipoint Group's
add_scenariomethod to add an aerodynamic scenario to the MPhys Group. - We connect the undeformed surface mesh vectors between the
meshandgeometrycomponents, and we connect the deformed surface mesh vectors between thegeometrycomponent and the aerodynamic scenario.
Most of this setup is standard for MPhys-based aerodynamic optimization problems, which is described in more detail in the MPhys documentation.
Configure
def configure(self) :
"""
Create the aero problem here
"""
# Create the geometric DVs
points = self.mesh.mphys_get_surface_mesh()
# Add pointset to pyGeo's FFD
self.geometry.nom_add_discipline_coords(MPhysVariables.Aerodynamics.Surface.Geometry, points)
# == Geometry Setup ==
# Create a reference axis
nRefAxPts = self.geometry.nom_addRefAxis(name="c4", xFraction=0.25, alignIndex="k")
nTwist = nRefAxPts
# Setup the global twist variable
def twist(val, geo) :
for i in range(0, nRefAxPts) :
geo.rot_z["c4"].coef[i] = val[i]
self.geometry.nom_addGlobalDV(dvName="twist", value=np.zeros((nTwist)), func=twist)
# Add the DVs to the independent vars and connect them
self.dvs.add_output("twist", val=np.zeros((nTwist)))
self.connect("twist", "geometry.twist")
# Define the design variables for openMDAO
self.add_design_var("twist", lower=-10.0, upper=10.0, scaler=1.0)
# Add the aerodynamic objective and constraint
self.add_objective("cruise.cd", scaler=1.0)
self.add_constraint("cruise.cl", equals=0.5, scaler=1.0, linear=False)
self.add_constraint("cruise.cmy", lower=-0.17, scaler=1.0, linear=False)
Run Optimization
# Instantiate the MDAO problem
prob = om.Problem(allow_post_setup_reorder=False)
prob.model = Top()
# Set the optimizer
prob.driver = om.ScipyOptimizeDriver()
prob.driver.options["optimizer"] = "SLSQP"
prob.driver.opt_settings = {
"IFILE": "SLSQP.out"
}
# Attach recorder to the driver
recorder = om.SqliteRecorder('cases.sql')
prob.driver.add_recorder(recorder)
prob.setup(mode="rev")
prob.run_driver()
Running
Running with MPI
This tutorial provides NAS Cluster PBS scripts configured to run on a single MPI rank. All CPUs on the compute nodes are still utilized through OpenMP threading.
This setup is intended to simplify running the tutorial.
If you want to run with multiple MPI ranks, you must install
petsc4py, as required by OpenMDAO.
Running on the NAS Cluster
Aitken Supercomputer
First, modify the lava_suffix entry in the run_om_opt.py file to contain the following,
lava_builder = LAVABuilder(lava_options, scenario="aerodynamic",
lava_suffix='3D.NS1.INTEL.AVX2.HPEMPT-lib',
The following PBS script can be used to run this example on the NAS cluster using Aitken Rome Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_wing_opt_om_curv
#PBS -l select=1:ncpus=128:mpiprocs=1:model=rom_ait
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
log_file="run.log"
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# This is to be safe (communication bug with the infiniband)
export MPI_NUM_MEMORY_REGIONS=0
# Run optimization script
mpiexec -np 1 mbind.x -t 128 python run_om_opt.py 2>&1 |& tee -a ${log_file}
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
To run this case, submit the optimization PBS script:
Aitken Supercomputer
First, modify the lava_suffix entry in the run_om_opt.py file to contain the following,
lava_builder = LAVABuilder(lava_options, scenario="aerodynamic",
lava_suffix='3D.NS1.INTEL.AVX512.CRAYMPICH-lib',
...
The following PBS script can be used to run this example on the NAS cluster using Aitken Turin Nodes.
job.pbs
#PBS -S /bin/bash
#PBS -N crm_wing_opt_om_curv
#PBS -l select=1:ncpus=128:mpiprocs=1:model=rom_ait
#PBS -l walltime=02:00:00
#PBS -j oe
#PBS -W group_list=<your project group ID>
#PBS -q normal
log_file="run.log"
cd $PBS_O_WORKDIR
# Modules and Environments
module purge
# Load the module for LAVA
module use /swbuild/LAVA/LAVA_modules
module load LAVA
# Source the virtual environment which contains all
# the necessary python packages for optimization.
# The user is responsible for creating this virtual env
source path/to/virtual_env/bin/activate
# This is to be safe (communication bug with the infiniband)
export MPI_NUM_MEMORY_REGIONS=0
# Run optimization script
mpiexec -np 1 mbind.x -t 128 python run_om_opt.py 2>&1 |& tee -a ${log_file}
Important
You must edit job.pbs before submitting this job, specifically:
- Replace
enter_group_idwith your actual group or project ID. - Replace
path/to/virtual_envwith the path to your Python virtual environment that contains the required Python packages.
To run this case, submit the optimization PBS script:
Running on External Systems
Modify the lava_suffix entry in the run_om_opt.py file to match the suffix for the LAVA Dynamic Library that is compatible with your system.
Additionally, if the path to the LAVA Dynamic Library is not included in the LD_LIBRARY_PATH environment variable, then you will need to include the lava_lib_path argument when instantiating the LAVABuilder to specify the path to the LAVA Dynamic Library on your system. Together, these should look something like the following inside of your run_om_opt.py file:
lava_builder = LAVABuilder(lava_options, scenario="aerodynamic",
lava_suffix='lava_dynamic_library_suffix_for_your_system',
lava_lib_path='/path/to/lava/dynamic/library',
...
LD_LIBRARY_PATH environment variable, then you can omit the lava_lib_path argument and simply ensure that the lava_suffix entry matches the suffix for the LAVA Dynamic Library that is compatible with your system.
If you created a Python virtual environment following the directions in the environment setup instructions above, make sure to activate that environment in your terminal:
For a single MPI rank, you can run the following command,
For multiple MPI ranks, you can run the following command,
Note
When running with OpenMPI, proper thread binding may require additional flags for optimal performance. We have found that the following command ensures correct binding:
export OMP_NUM_THREADS=28
mpirun -np 4 --map-by slot:PE=$OMP_NUM_THREADS --bind-to hwthread python run_om_opt.py | tee run.out
OMP_NUM_THREADS based on the number of threads you want to use.
PETSc Requirement
You may recall from the OpenMDAO-based Optimization Requirements discussion that PETSc is required by OpenMDAO for running with multiple MPI ranks. Just wanted to make sure you were aware.
Post-Processing
OpenMDAO provides functionality for post-processing optimization results. In this tutorial, we are leveraging the driver recording feature. Much more detail is provided in the OpenMDAO documentation, so we encourage you to read through that for more information.
Post-Processing using the Case Database
We will be using the following Python script extract design variable, constraint, and objective values from the optimization case history:
run_om_post.py
# ==================================================================
# === Post-Processing ==============================================
# ==================================================================
""" This script is an example of how to post-process the wing twist
optimization case to extract and analyze specific design iterations
with pyLAVA.
See the documentation for more details.
you can run the script like this:
mpirun -np 2 mbind.x -t 14 python run_post.py
"""
# === Import =======================================================
from mpi4py import MPI
import os
import openmdao.api as om
from run_om_opt import Top
# ==================================================================
# == Helper Functions ==============================================
# analysis-start
def runAnalysis(prob, case, fileSuffix) :
# Get the output directory
out_dir = prob.get_outputs_dir()
# Load the case and run the model
prob.load_case(case)
prob.run_model()
# Get lava and write the surface output
lava = prob.model.cruise.coupling.aero_solver
lava.writeSurface(os.path.join(out_dir,f"surface.{fileSuffix}.plt"),
fields=["iblank", "yplus", "cp", "cf", "cfx", "cfy", "cfz"])
# analysis-end
# print-case-start
def printCase(label, case):
print(f"\n{label}")
print("-" * len(label))
print("Objectives:")
for name, val in case.get_objectives().items():
print(f" {name}: {val[0]:.8f}")
print("Constraints:")
for name, val in case.get_constraints().items():
print(f" {name}: {val[0]:.8f}")
# print-case-end
# ==================================================================
# === Main Script ==================================================
if __name__ == "__main__":
# Instantiate the MDAO problem
prob = om.Problem()
prob.model = Top()
prob.setup(mode="rev")
# reader-start
cr = om.CaseReader('run_om_opt_out/cases.sql')
# reader-end
# run-start
# Get the first function eval
case = cr.get_case(0)
runAnalysis(prob, case, "initial")
# Get the last function eval
case = cr.get_case(-1)
runAnalysis(prob, case, "optimized")
# run-end
# print-start
# Print the initial and optimized objectives
if MPI.COMM_WORLD.rank == 0 :
printCase("INITIAL CASE", cr.get_case(0))
printCase("OPTIMIZED CASE", cr.get_case(-1))
# print-end
# ==================================================================
This script should be run in the same way as the run_om_opt.py script, i.e., in an environment where pyLAVA, OpenMDAO, MPhys, and pyGeo are available.
Let us break down the contents of this script below.
Important
This Python script must be run in the same directory as the run_om_opt.py script in order to import the Top class, which is the OpenMDAO Model used for the optimization.
Analysis Helper Function
def runAnalysis(prob, case, fileSuffix) :
# Get the output directory
out_dir = prob.get_outputs_dir()
# Load the case and run the model
prob.load_case(case)
prob.run_model()
# Get lava and write the surface output
lava = prob.model.cruise.coupling.aero_solver
lava.writeSurface(os.path.join(out_dir,f"surface.{fileSuffix}.plt"),
fields=["iblank", "yplus", "cp", "cf", "cfx", "cfy", "cfz"])
run_om_post.py, will be run_om_post_out.
Print Helper Function
def printCase(label, case):
print(f"\n{label}")
print("-" * len(label))
print("Objectives:")
for name, val in case.get_objectives().items():
print(f" {name}: {val[0]:.8f}")
print("Constraints:")
for name, val in case.get_constraints().items():
print(f" {name}: {val[0]:.8f}")
Case Reader
In this line of code, we use OpenMDAO's Case Reader to read the case database generated during the optimization.Run Analysis
# Get the first function eval
case = cr.get_case(0)
runAnalysis(prob, case, "initial")
# Get the last function eval
case = cr.get_case(-1)
runAnalysis(prob, case, "optimized")
runAnalysis helper function to run the aerodynamic analysis and write out the surface geometry.
This will generate the following files in the run_om_post_out directory:
Print Functionals
# Print the initial and optimized objectives
if MPI.COMM_WORLD.rank == 0 :
printCase("INITIAL CASE", cr.get_case(0))
printCase("OPTIMIZED CASE", cr.get_case(-1))
printCase helper function to print out the objective and constraint values for the initial and optimized designs.
The final output to screen is:
INITIAL CASE
------------
Objectives:
cruise.cd: 0.02321754
Constraints:
cruise.cl: 0.51075711
cruise.cmy: -0.18329909
OPTIMIZED CASE
--------------
Objectives:
cruise.cd: 0.02268790
Constraints:
cruise.cl: 0.50000000
cruise.cmy: -0.17000034
Together with the surface.initial.plt and surface.optimized.plt files, we can visualize the initial and optimized wing shapes along with their corresponding functional values.

Relevant Publications
-
Lowe, B. M., Ashby, C. P., Koch, J. R. L., Craig Penner, D. A., Housman, J. A., and Duensing, J. C., "Towards Aerodynamic Shape Optimization Using an Immersed Boundary Overset Grid Method," American Institute of Aeronautics; Astronautics, July2024. https://doi.org/10.2514/6.2024-4229 ↩
-
Chau, T., Anibal, J. L., Lowe, B. M., Machado, L. M., and Duensing, J. C., "High-Fidelity Aeropropulsive Assessment of Distributed Electric Propulsion and Boundary Layer Ingestion for the SUSAN Electrofan," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-1275 ↩
-
Gray, J. S., Hwang, J. T., Martins, J. R. R. A., Moore, K. T., and Naylor, B. A., "OpenMDAO: An Open-Source Framework for Multidisciplinary Design, Analysis, and Optimization," Structural and Multidisciplinary Optimization, Vol. 59, No. 4, 2019, pp. 1075--1104. https://doi.org/10.1007/s00158-019-02211-z ↩
-
Yildirim, A., Jacobson, K. E., Anibal, J. L., Stanford, B. K., Gray, J. S., Mader, C. A., Martins, J. R. R. A., and Kennedy, G. J., "MPhys: A Modular Multiphysics Library for Coupled Simulation and Adjoint Derivative Computation," Structural and Multidisciplinary Optimization, Vol. 68, No. 15, 2025. https://doi.org/10.1007/s00158-024-03900-0 ↩
-
Hajdik, H. M., Yildirim, A., Wu, E., Brelje, B. J., Seraj, S., Mangano, M., Anibal, J. L., Jonsson, E., Adler, E. J., Mader, C. A., Kenway, G. K. W., and Martins, J. R. R. A., "[pyGeo]{.nocase}: A Geometry Package for Multidisciplinary Design Optimization," Journal of Open Source Software, Vol. 8, No. 87, 2023, p. 5319. https://doi.org/10.21105/joss.05319 ↩
-
Lyu, Z., Kenway, G. K. W., and Martins, J. R. R. A., "Aerodynamic Shape Optimization Investigations of the Common Research Model Wing Benchmark," AIAA Journal, Vol. 53, No. 4, 2015, pp. 968--985. https://doi.org/10.2514/1.J053318 ↩
Unstructured User Guide
Introduction
The unstructured solver within LAVA solves the Navier-Stokes equations on arbitrary polyhedral unstructured meshes. The solver supports various numerical schemes and models for Reynolds-Averaged Navier-Stokes (RANS) equations or Large-Eddy Simulations (LES). A high-level overview of its capabilities compared to other LAVA solvers is provided in the LAVA Introduction; a list of publications is maintained on the Publications page.
New users can get a first simulation running in minutes with the Quick Start.
We will briefly go over the available numerical schemes and capabilities here. For more details, please see:
- LAVA WMLES High-Lift Results (2025)
- LAVA Voronoi Mesher for WMLES (2024)
- Gradient Calculation Methods on Polyhedral Meshes (2014)
Grids
The unstructured solver is designed to work with unstructured grids of arbitrary cell types. This includes standard types such as tetrahedra, hexahedra, pyramids and prisms. However, the cell-centered formulation works best with cell types with 6 or more faces as this improves the stencil width, leading to better accuracy and robustness.
LAVA release includes the LAVA Voronoi Mesher, a parallel and automated mesher that can generate high-quality Voronoi meshes that are particularly suited for scale-resolving applications which demand low dissipation fluxes. The Voronoi mesher also has early support for anisotropic wall layers that can support wall resolved RANS applications, although this feature is still under development. More details about the Voronoi mesher can be found here:
The solver also supports externally generated grids as long as they are provided in arbitrary polyhedral cell type CGNS format with a single volume zone. How the grid file is read and transformed, how degenerate cells are detected and filtered, and how periodic domains are set up is documented in Grid Setup.
Numerical Scheme
LAVA unstructured uses a finite-volume discretization with a density-based compressible formulation. Primitive variables \(Q=[p,u,v,w,T,Y_i]\) are stored at cell centers.
Up to \(2^\textrm{nd}\) order spatial accuracy is supported for both the convective and diffusive terms. Explicit time integration (\(2^\textrm{nd}\), \(3^\textrm{rd}\) or \(4^\textrm{th}\) order accurate) is typically used for LES and WMLES applications while implicit time integration (\(2^\textrm{nd}\) order accurate) for RANS and URANS applications with dual time-stepping. For implicit simulations, an ILU preconditioned GMRES linear solver is utilized. The time integrators, gradient reconstruction, convective schemes and model options are documented in Time Integration and Numerical Schemes.
Turbulence Models
- Spalart-Allmaras turbulence model for RANS closure
- Constant coefficient Vreman subgrid scale model for LES closure
- Musker's and blended-log wall models
- A momentum/energy penalty based flow tripping
Multi-species
LAVA Unstructured supports multi-species mixtures. However, the species are inert, i.e. chemical reactions are not supported. Multi-species diffusion is handled via effective mixture viscosity, without multi-component diffusion.
Conjugate Heat Transfer
Conjugate heat transfer simulations where solid heat conduction is solved tightly coupled with fluid flow. Solid heat conduction is modeled in 1D only, in the wall normal direction. This disregards solid heat conduction in transverse directions and only recommended where the normal direction heat conduction is expected to be dominant. A separate mesh for the solid is not required. It is activated through the wall boundary condition.
Moving Grids
Grid domains can undergo prescribed rigid-body motion (constant or sinusoidal rotation and translation), documented in Rigid Body Motion.
In-situ Post Processing
Several in-situ post-processing options are available — see Output and Probes:
- Loads: Output integrated force and moments over user defined groups of boundary surfaces
- Point probes: Probe flow variables at given set of point coordinates
- Line probes: Probe flow variables along user defined lines
- Surface probes: Sample flow variables on to user supplied triangulated surfaces
- Iso-surfaces: Compute iso-surfaces of primitive and derived flow quantities (e.g. Q-criterion, density gradient magnitude...) and write as triangulated surfaces
- Cut-planes: Sample flow variables on to user defined cut planes
-
Sub-volume: Output volume solution for user defined subsets of the domain
-
Ffowcs Williams–Hawkings (FWH) acoustics: in progress, upcoming release
Hardware
LAVA unstructured is compatible with Intel, AMD and ARM based CPU systems as well as NVIDIA GPU systems. Implicit solutions (e.g. RANS) is currently only supported on CPU systems.
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.NS1build). - The LAVA Voronoi mesher installed, see the Voronoi Installation Guide.
- Python with matplotlib for the
plotHist.pyutility, 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
with the corresponding pressure field
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):
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 nameselects one of the analytic initial conditions built into the solver — no restart or geometry files needed.timerequests an unsteady run for 20 convective time units with an adaptive time step atcfl = 0.8.reference conditionsset the nondimensionalization: with \(V_0 = 1\), the reference temperature gives Mach 0.1, and the referencelengthof \(1/(2\pi)\) makes one convective time unit (thectumonitor column) equal to one classic Taylor–Green time unit.fluidpoints totg.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
unstblock:gridnames the mesh file — see Grid Setup.periodictells the solver that the mesh was built periodic by the Voronoi mesher (do lava voro periodic = true) and gives the box extents — see Periodic. NoBC_Nblocks are needed, since the periodic mesh has no boundary zones.explicitpicks the explicit third-order strong-stability-preserving Runge–Kutta scheme — see Explicit Stepping.convective termsselect thekeepblendscheme, the recommended low-dissipation scheme for scale-resolving simulations: a kinetic-energy and entropy preserving flux blended with an upwind flux where theducrosmodsensor detects compressibility effects — on this coarse grid a dissipative scheme would visibly damp the vortices. See Convective Terms.navier stokesswitches the viscous terms on.outputwrites a monitor line every 10 steps (with the integrated kinetic energy fromflow_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):
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:
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:
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\):
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:
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:
You now have a running LAVA Unstructured setup. From here:
- the mesher for real geometry: Voronoi Mesh Generator
- the full input reference: General Setup, Grid Setup, Time Integration and Numerical Schemes, Boundary Conditions, Output and Probes
- cases with geometry: the Diamond Airfoil tutorial
Unstructured Solver Inputs
Unstructured Solver Inputs
Input File Syntax
LAVA utilizes a plain-text input file to specify solver options. The input file is organized in several sections.
Info
All the inputs are interpreted in standard SI units
Most inputs have default values built into the code and can be skipped from the input file if default value is acceptable.
The input file is case-insensitive, with the exception of string entries such as file names. In addition, most white spaces are disregarded with the exception of carriage return.
Input entries are separated by either a semicolon ";" or carriage return. To illustrate, let's look at two examples:
is equivalent to
Note that the order of entries are swapped in the second example.
The file is organized in nested sections that encapsulate logical groups of inputs together. The sections are denoted with a section name followed by an opening curly brace "{" and ending with a closing curly brace "}". Here is an example:
This example shows a section and has one input entry as well as two nested sections both of which have their own inputs entries.
Like ordinary input entries, the order of sections in the input file is not important as long as the nesting hierarchy is correct.
The last piece of relevant syntax is the numbered sections that are utilized to construct numbered lists, suffixed by an underscore "_" followed by item number. One example usage is listing of boundary conditions for the unstructured solver:
Vector entries (or lists) are denoted using brackets:
Lists follow the same format as vectors:
Note that you can specify ranges (inclusive) with dashes as above.
Comment lines can be added to the input file using hash signs # either
in a separate line or in-line with the code:
Fluid Section
The fluid, either a single species, or a mixture of species is specified in the
fluid section:
This example uses perfect air as an equivalent single-species gas. The code is distributed with a database of common gas species. The database is stored in individual "species files" that contain gas properties such as molecular weight, specific heat ratio, viscosity (or Sutherland coefficients), Prandtl number etc...
Available fluid species are: air_perfect, h (hydrogen), o (oxygen), h2,
o2, oh,h2o (water vapor),co and co2. Users can create their own species
definitions.
For multi-species problems, you can specify the mixture composition instead of single species such as:
Info
LAVA currently does not support reacting flows.
Reference Conditions Section
Reference conditions list the reference flow quantities (typically the freestream conditions in external flow problems) as well as the reference area, length and angles (pitch and yaw) in airplane coordinates. These values are used in initial and boundary conditions (unless different conditions are explicitly specified). They are also used to normalize force and moment coefficients.
The reference conditions need to properly specify the thermodynamic state and
velocity field. Typically two of the three thermodynamic quantities (density,
pressure and temperature) need to be specified. Specifying all three of
them will result in an error message as it is an over-specification.
In addition, velocity vector or speed and angles are typically specified.
Here are a few example ways to specify the reference conditions:
reference conditions {
pressure = 1.e5
temperature = 300
velocity = [100.,0.,0.]
area = 1.0
length = 1.0
# If using multi-species, list the mass fractions of each species
mass fractions = [1,0,0]
}
use std atmosphere = true.
reference conditions {
use standard atmosphere = true # false by default
std altitude = 1000
velocity = [100.,0.,0.]
area = 1.0
length = 1.0
# If using multi-species, list the mass fractions of each species
mass fractions = [1,0,0]
}
Info
The thermodynamic condition description for multi-phase is slightly different than for single and multi-species. Please refer to the Cartesian Multiphase Solver page for details.
By default, reference area and length values are unity (1.0) and can be skipped if normalized forces are not needed. Instead of the velocity, we can utilize Mach number and flow angles:
Note that alpha and beta are pitch and yaw angles in degrees. This assumes
that the model is in the airplane coordinate frame (+x: from nose to tail,
+y: along the right wing, +z: from airplane towards the ground). These angles do not
transform the model, but rather set the freestream direction so that the model
is at the desired angles relative to the freestream. Positive alpha
corresponds to pitch up, while positive beta corresponds to yaw towards right.
The following coordinate transform is used in the code to transform
the reference velocity vector to a Cartesian frame.
For launch-vehicle simulations, the flow angle can be specified via alpha, angle of attack, and phi, the roll angle.
This assumes that the rocket model is aligned in the x axis, this +x being from windward to leeward. phi=0 corresponds to
incoming flow aligned to the x-z plane. alpha then indicates the rotation of the incoming flow on the -y axis and phi
the rotation of the incoming flow on the -x axis.
The following coordinate transform is used in the code to transform
the reference velocity vector to a Cartesian frame.
Another way to specify the reference conditions is by using Reynolds number, Mach number and temperature:
Note that thelength is the reference length used in the Reynolds number
definition.
Yet another way to specify the reference conditions is by using dynamic pressure, Mach number, and standard atmosphere.
Using this requires the flag use std atmosphere = true.
reference conditions {
use std atmosphere = true
dynamic pressure = 70000
Mach = 1.4
alpha = 4
beta = 2
}
When the reference length and reference area are specified, the force and moment coefficients (if load output is requested) are normalized using these reference values. For external aircraft aerodynamics, the reference length typically corresponds to the mean aerodynamic chord, while the reference area corresponds to the main wing planform area.
For correct normalization of the rolling and yawing moment coefficients, the aircraft span should be provided as an additional reference quantity. Users may optionally specify the span in the input file. If the span is not provided, the code issues a warning. In this case, the rolling and yawing moment coefficients are normalized using the reference length (typically the mean aerodynamic chord) as a fallback. It is the user's responsibility to ensure that the appropriate normalization is applied if span-based moment coefficients are required.
The dx input represents a characteristic grid spacing value, often indicating the cell size (in meters) in the finest region of the grid. It is not required (default value is 1), but it can make life easier when setting up some of the other input sections (e.g. trip lines, relative grid spacing w.r.t. dx). The role of dx will be described in relevant sections that make use of this parameter.
For multi-species runs, species mass fractions should be specified:
Time Section
The time section specifies whether the run is steady or unsteady, and if unsteady, sets up the extents of step size for the time integration.
In the simplest case of steady runs, the section can be skipped all together or the section can be used just to explicitly state a steady setup:
For unsteady runs, several other entries become revelant. The following example setups
up a case that will run for 1000 time steps with a constant dt.
Alternatively, you can specify stop condition in terms of total time integrated. You can also choose to start the time integration from a non-zero inital time:
Yet another convenient and common way to specify time integration bounds is by utilizing CTUs (Convective Time Unit). A CTU is simply the non-dimensional time normalized by reference flow velocity magnitue and the reference length as specified in the Reference Conditions Section.
Time step size can be specified in terms of CFL instead of a fixed dt as used above. The specifed cfl number is interpreted as the maximum allowed CFL in the whole domain and the corresponding dt value is adjusted automatically.
Here initial cfl value is used in the start-up and cfl gradually climbs until the specified cfl number is met.
Sync clock — uniform sampling with CFL-driven sub-steps (cartesian & unstructured, explicit)
A CFL-driven dt is efficient but makes output snapshots unevenly spaced in physical time, which breaks
FFT-based post-processing (spectra) and makes animations from AMR runs play at varying speed.
The sync clock gives both: the solver keeps taking CFL-limited (or fixed-dt) sub-steps, but they are
clipped so simulation time lands exactly on multiples of a fixed sync step dt_s.
The sync clock is specified in exactly one of four ways, together with exactly one sub-step driver
(cfl or dt):
time {
steady = false
finish ctu = 300
cfl = 2.5 # sub-step driver: cfl (adaptive) or dt (fixed), exactly one
sync steps per ctu = 100 # dt_s = reference time / 100 ... or one of:
# sync dt = 1.646e-4 # dt_s in seconds
# sync ctu = 0.01 # dt_s as a fraction of a CTU
# sync freq = 1.0e5 # sampling rate in Hz (dt_s = 1/f)
}
Notes:
- The sync step size should be larger than the sub-step
dt; if it is smaller, every step lands on a mark and the run behaves like a fixed-dtrun atdt_s. - The landing step of each sync interval takes a clipped (possibly much smaller) dt, so its true CFL
is below the target — always stable. The
maxcflmonitor column always reports the actual measured per-cell maximum, so it dips on landing steps by exactly the clip ratio and sits at the target on interior steps; it never exceeds thecflcondition. Internally the CFL controller pairs each measurement with the dt it was measured at, so the clip cannot make dt overshoot the target on the step after a landing. - Two step counters exist in sync runs:
ntcounts the actual RK sub-steps (as always), andntscounts completed sync steps. The monitor gains thents,dtratio(dt/dt_s) andsubsteps(sub-steps per sync step) columns — only in sync runs; without sync inputs, behavior and output are identical to before. All three columns are always written to the monitor.iterfile; on screen,ntsandsubstepsappear automatically right next tontin sync runs, whiledtratiois shown only if added to the monitorvariableslist. number of stepscontinues to countnt(a safety bound on compute). An unstructured run ends onfinish time/finish ctuby sync step: it stops once the sync step of the mark nearest the finish time is complete,nts = round((finish - start) / dt_s). A finish time off the marks draws a warning and ends the run up to half a sync step early or late. A Cartesian run terminates on physical time, which is a sync mark by construction when composed from CTU inputs.- In sync runs, the snapshot and probe output intervals count sync steps and those outputs only
ever fire on the uniformly spaced marks: volume, surface, isosurface, restart, and the
point/line/surface probes. Output files are labeled with the sync step (so
Cart.vol.000000040.hdf5is at exactly40 * dt_s), probe rows are tagged with the sync step, and volume/CGNS file headers carry async_dtattribute — probe and snapshot series are uniformly spaced in physical time, ready for FFT post-processing without resampling. The per-step series keep counting RK sub-steps (nt) exactly as without the sync clock: the monitor, theloadsinterval (rows labeled withnt) and theflow statsinterval (which feeds the monitor columns) — sointerval = 1samples every sub-step, marks or not. output buffer snapshots(default 100) sets the per-rank snapshot budget buffered between flushes of buffered surface/isosurface output; the automatic memory-pressure fallback still applies.- If a sync run terminates between marks (the
number of stepssafety bound tripped), the forced final volume/surface/probe writes are skipped — an off-grid sample must not enter the uniform series — while the forced final restart is still written, labeled with the RK step (nt) so it never overwrites an at-mark restart file. An unstructured run ending viafinish time/finish ctualways lands on a mark, as does a Cartesian one with those composed from CTU inputs, and the final writes proceed as usual. - Restart files store the sync state, so a restart with the same sync clock resumes the uniform
series exactly, mid-interval included. Changing the sync clock across a restart (e.g.
sync steps per ctu100 -> 300) starts a new sampling segment: the sync stepntsis re-derived from the restart time on the new mark grid, the first step lands on the next new mark, and a warning reports the old and new counts (plus a note when the restart time is not on the new grid, in which case the first interval is partial and the series is uniform from the next mark on). Run such a segment in a new directory: files are labeled withnts, whose scale changes (a decreasing count would overwrite the previous segment's files, and the solver warns). The.itercompanions of the restart file (monitor, bc stats) are read from the restart file's own directory. Two other ways to start a fresh segment from a checkpoint:restart { file = ...; reset time = true; reset nt = true }restarts the physical time, the step counters and the sync step at zero and starts new monitor series (no companion files needed), and an initial-condition file (ic_1 { file = <restart hdf5> }) reads only the flow field. - Cartesian AMR: in sync runs
regrid interval(and theregrid interval on/offwindow) counts sync stepsntsinstead ofnt, and a regrid only ever fires on a step that starts exactly on a sync mark — the mesh never changes inside a sync interval.
- Supported for the cartesian and unstructured solvers with explicit time stepping (subcycling is
not supported). The scheduler's
do dtsets the sub-step dt that the sync clock clips to the marks.
Unstructured Specific Inputs
Unstructured specific inputs are grouped within the unst {} section. Every following section here should be included within it.
The unstructured-specific inputs are documented across the following pages:
- Grid Setup: grid file and transformations, mesh diagnostics and problem cells, periodic domains
- Time Integration and Numerical Schemes: explicit and implicit stepping, gradients, convective schemes, Navier-Stokes and turbulence options, wall function
- Boundary Conditions: the
BC_N { }blocks
- Rigid Body Motion: prescribed motion of grid domains
- Output and Probes: monitor, loads, restart, volume and surface output, probes, time averaging
The remaining unst { } sections are described below.
Grid
The grid { } block names the CGNS grid file and its transformations; diagnostics { } and periodic { }
control mesh-quality filtering and periodic domains. They are documented on their own page: Grid Setup.
Time Integration and Numerical Schemes
The explicit { }, implicit { }, convergence { }, gradient { }, convective terms { }, navier stokes { },
turbulence { } and wallfunction { } blocks are documented on their own page:
Time Integration and Numerical Schemes.
Restarting
To resume runs, all you need to do is point to the restart file location as:
The restart files (also referred to as checkpoint files) are saved periodically in restart directory created by the code under the run directory. The interval at which the restart files are created can be specified by users. The details are provided in restart output options section.
If the specified restart file is not found, the solver will print a message and proceed with a fresh start instead of aborting. This allows the same input file to be used for both initial runs and restarts — if the restart file does not yet exist, the simulation simply starts from scratch. If restart is not desired at all, you can skip or comment out this section.
Additional restart controls are:
restart {
file = ./restart/Unst_restartLatest.hdf5
# Set physical time to 0 on restart
reset time = true
# Set the time step number to 0 on restart
reset nt = true
}
Initial Conditions
Initial condition specification is optional. If not provided, the code will simply initialize the flow to reference conditions specified in Reference Conditions.
If a different initialization is needed, it can be specified through a numbered list:
# Specify pressure, set the rest using reference conditions
IC_1 {pressure = 5e5}
# Specify temperature, set the rest using reference conditions
IC_2 {temperature = 500}
# If density is specified, another thermodynamic quantity (either pressure or temperature)
# also needs to be specified
IC_3 {density = 2; temperature = 300}
# Velocity vector can be specified
IC_4 {velocity = [100,10,0]}
# Or Mach number along with alpha and beta angles
IC_5 {Mach=0.5; alpha=6; beta=2}
# Specify mass fractions for multi-species
IC_6 {mass fractions = [1,0,0]}
All the above statements will apply the conditions listed in the entire domain. To initialize a sub-volume differently, you can specify a custom box region with position vectors of the two opposing corners:
The example above will first apply the reference conditions in the entire domain. Then it will overwrite the pressure in the unit box region specified. The IC's are applied sequentially, i.e. the entries further down in the IC's list will overwrite the previous ones if there is overlap.A restart file (that is consistent with the current mesh) can also be used as an initial condition via:
IC_1 {
file = initialCondition.h5
# Optionally, you can apply smoothing to the file being read as initial condition via:
apply smoothing passes = 2 # default is 0
}
This feature is useful when starting a simulation from another solution interpolated onto the current grid (which can be done using unst_interpolator tool)
Warning
Note that if the file method is used, no other initial conditions can be specified.
Artificial Boundary Layer
Artificial boundary layer options will linearly scale the velocity down to zero at walls, creating a less harsh start-up. For isothermal walls, same linear scaling can be applied to the temperature field.
Warning
This option, while available, should be avoided for large scale LES cases, as it requires distance function to be computed for the entire volume which is otherwise not needed.
artificial boundary layer {
apply velocity = true
apply thermal = true
# Distance from the wall (in meters) that the linear scaling is applied to
height = 1
wall temperature = 500 # K
}
Sponge
Sponge zones can be used to dampen the flow in specified rectangular regions. In these zones, the order of accuracy will be reduced.
Multiple sponge regions can be defined by incrementing the number after sponge_
Trip Lines
Trip lines exert a penalty method source term that attempts to trigger boundary layer transition to turbulence. The source terms are applied only at select cells within certain distance of the lines. Lines are also broken into dash/dot or on/off pattern that apply the trip terms in an intermittent fashion along the line, similar to how trip dots are commonly implemented in reality.
# This determines the strength of the trip lines
# The lower the value, the stronger the trip source penalties are
# In the lower limit, a value of 1 would bring the flow to full stop
# where trip is active
trip time relaxation = 40. # a factor of dt
trip_line_1 {
# dxscale should indicate the local grid resolution (where this trip line is)
# with respect to the dx value set at the reference section
dxscale = 1
# Begin/end coordinates of the line segment
begin = [0,1,1]
end = [1,2,3]
# The segment variables below are relative to the local grid spacing
# In this example, the trips will be on for approximately 2 cells
# and off for approximately 3 cells along the line
# The on segments will mark cells whose centers are within 0.9 * dx
# from the line
# These variables can be skipped in favor of defaults
segment length = 2 # default
segment skip = 3 # default
segment radius = 0.9 # default
# The straight trip line specified here will be projected to the
# surface using projection method. By default, the line will be projected
# to the closets surface
# Options are : none, closest, vector
projection method = closest # default
# max distance is an optimization parameters, entering the something
# slightly larger than the expected farthest distance (from trip line to the geometry)
# will improve start-up performance
projection max distance = 3
}
trip_line_2 {
dxscale = 4
begin = [1,0,0]
end = [2,0,0]
# Another projection method is vector, for which the line
# is projected along a specified vector direction until a surface is
# encountered
projection method = vector
projection vector = [0,1,0] # y-axis
}
# Circular trip curve
trip_line_3 {
dxscale = 2
# Instead of a straight line, the trip location can also be drawn as a circle
# with the specified center coordinates and radius
center = [1,0,0]
radius = 2
# The circle can also be projected to the surface
projection method = closest
projection max distance = 1
}
Tip
In typical practice, it is recommended to use defaults for segmenting parameters. In addition, the inputs may be made more compact by inlining each trip, for example:
Tip
The solver will output the final projected trip lines (in tecplot and vtk line formats) into the trips directory under the run directory. It is highly recommended to verify the trip setup by plotting the lines overlaid on the surface geometry.
Rigid Body Motion
Prescribed rigid-body motion of grid domains (rigidbodymotion_N { }) is documented on its own page:
Rigid Body Motion.
Boundary Conditions
The boundary conditions (BC_N { } blocks, one per boundary zone of the grid file) are documented on their
own page: Boundary Conditions.
Output
Monitor, flow statistics, loads, restart output, volume/surface/iso-surface output, the probes, and time averaging are documented on their own page: Output and Probes.
Grid Setup
The grid { }, diagnostics { } and periodic { } blocks inside unst { } describe the mesh the solver
runs on: where it comes from and how it is transformed, how degenerate cells are detected and filtered,
and how periodic domains are set up. Meshes are typically generated with the
LAVA Voronoi Mesher; any polyhedral CGNS grid can be used.
Grid File and Transformations
The grid is expected to be in CGNS format, written as arbitrary polyhedrals (even if the grid is made up of only standard element types). Only a single volume zone is supported while each following surface zone is interpreted as a separate boundary condition (BC).
The grid file name is specified as:
Note that the specified grid file (or a symbolic link to it) needs to be present in the same directory as the input file. Otherwise, you can enter the full file path.
Multiple grid files can be specified. The solver will automatically merge the multiple grids and associate each with a domain id.
A grid file may also contain several volume zones; each zone becomes its own domain. Domains are numbered in (file, zone) order, so one multi-zone file is equivalent to the same zones supplied as separate single-zone files.
Some basic grid transformation operations are possible within the grid file. See the examples below:
grid {
file = grid.cgns
# Scale the grid by a factor of 2
transform_1 {function=scale; factor=2}
# Translate the grid 1 unit length in x direction
transform_2 {function=translate; distance=[1,0,0]}
# Rotate the grid 90 degrees around y axis with an origin of (0,0,0); the axis may be any nonzero vector
transform_3 {function=rotate; center=[0,0,0]; axis=[0,1,0]; angle=90}
# Convert 1-cell thick (essentially 2D) grid into axisymmetric (wedge shape)
# Depth is assumed to be in the depth direction, while y-coordinate is the height.
transform_4 {function=axisymmetric; y_center=0, y_tolerance=1.e-6, angle=5}
}
Info
Everything else in the input file and the case setup need to be with respect to the already transformed grid.
The transformations are applied in the given order. You can list as many transformations as needed. If no transformations are needed, the transform inputs can be skipped.
The unstructured solver operates on "tiles" of cells for computational efficiency. Size of these tiles, i.e. approximately how many cells there should be in each tile, can be specified as:
The tile size affects the computational performance of the code, and its optimum value depends on the type of grid and the architecture of the system being used. There are built-in default "best practices" for several NAS systems so you may choose to skip specifying a tile size in favor of the defaults. In general, especially if you are running large scale cases, it is best to experimentally determine the best choice for tile size.Additional partitioning controls are available to customize the METIS partitioning algorithm used for tile creation:
grid {
file = grid.cgns
tile size = 1024
# Enable cell-based weighting during partitioning
# When true, uses number of faces per cell as weight for load balancing
# When false, treats all cells with equal weight (default: false)
do partition weights = false
# Choose partitioning method for tile creation
# true: Use graph-based partitioning (cell-to-cell connectivity)
# false: Use dual mesh partitioning (face-based connectivity) (default: false)
do graph tile partition = false
}
These partitioning options are optional and control how METIS creates computational tiles. The do partition weights option defaults to false, meaning all cells are treated with equal weight during partitioning. When enabled, it uses the number of faces per cell as a weight, which can improve load balancing by accounting for computational cost differences between cell types (e.g., tetrahedra vs hexahedra). The do graph tile partition option also defaults to false, using dual mesh partitioning where faces are treated as nodes. When set to true, it switches to graph-based partitioning using direct cell-to-cell adjacency, which typically produces higher quality partitions but may have different performance characteristics depending on mesh topology.
Note
If the unstructured mesh in question was a Voronoi tessellation of the computational domain created by the LAVA Voronoi Mesher (see the Voronoi Mesh Generator section for details), then the coordinates of the cell generating points, i.e. seeds, are provided in the mesh file. In this case, the user has the choice to read the seed coordinates information from the *.cgns file, the choice to use these coordinates instead of the cell centroids and the choice to use the location where the line segment between two neighboring seeds intersect their respective face instead of the face centroid as the flux exchange location. Additionally, the user can choose to include a correction to green-gauss gradient operator exclusive to Voronoi-type meshes. This correction was explained by Volker Springel in his 2009 paper. These behaviors are controlled by the following parameters, all of which are disabled by default.
By default, grid diagnostics is active (see the Diagnostics section for details).
Diagnostics
At runtime, solver will analyze the grid to determine problem cells. In most cases, these are cell that are deemed degenerate or problematic for solver stability. The cells marked as problem are filtered out, meaning they are not solved for. Instead, they are updated at each step by averaging their neighbor values. A summary of how many cells were filtered is provided at run time.
The diagnostics metrics and default threshold values are specified as listed below. Note that the defaults are designed to catch the most severe problems and have been calibrated to ensure solver robustness. In most cases, keeping the default values are recommended. If you are using defaults, this section or any default entry is not required to be present in the input file.
diagnostics {
# Maximum allowed angle (in degrees) between face normal and
# the vector connecting the two adjacent cell centers
max nonorthogonality angle = 90.
# Maximum order of magnitue change of volume between adjacent cells
max volume change order = 4.
# Checks accuracy of cell gradient stencil/weights vs a linear function
# The error is normalized and specified as percentage.
max gradient error = 1.e3
# Check convexity of cells
do convexity check = true
# Check if a cell is watertight
max green gauss error = 1e-8 # 1e-3 for FLOAT executable
# Check if all faces have a valid neighbor cell
# if the face is not a BC and a neighbor face was not found, abort the run
do face neighbor check = true;
# Check how skewed the angle from cell-centroid-to-neighbor
# versus the cell-centroid-to-face-centroid vector is. Input in degrees,
# between 0 and 180. The default 0 flags no face: give a threshold when
# turning the check on.
do neighbor face angle check = false
min face centroid angle = 0
# Check how close the cell centroid is to its faces. Diagnostic is normalized
# as (min face dist)/(max face dist) for a pair of cells on either side
# of a face, so the threshold is between 0 and 1. The default 0 flags no
# face: give a threshold when turning the check on.
do face dist growth check = false
min face dist growth = 0
# Check isotropy of the cell. Closer to 1 means perfectly isotropic.
do iso factor check = false
min iso factor = 0.25
# If the following is set as nonzero, then cell diagnotics are tracked into
# histograms with the given number of bins and output as CSV files.
# There is one CSV file per test, stored in
# the folder "diagnostics" under the file names
#
# face_planarity.csv, face_orthogonality.csv, cell_convexity.csv,
# face_alignment.csv, cell_size_filtering.csv, volumetric_jump.csv,
# green_gauss.csv, gradient_err.csv, face_neighbor_angle.csv,
# face_equidistant.csv, and cell_isotropy.csv.
#
# The green_gauss.csv is given in log scale. The cell_size_filtering.csv
# always uses 10% filter size bin widths, matching the terminal output.
histogram bins = 0
# If the following is activated, user manually mark additional problem cells
# by listing their global ids (ids as in the provided grid file) in an ASCII file
#problem cell file = problemcells.txt
#
# When enabled, write the geometry and flow solution of any problem cells to
# volume/Unst.problemCells.<step>.cgns at every startup (fresh start and restart).
# On an abort triggered by robust mode, the file is named
# volume/ABORT_Unst.problemCells.<step>.cgns instead.
# Output is skipped automatically if no problem cells exist.
# This option is TRUE by default
dump problem cells = false
}
Tip
At every startup, if any problem cells are found, the solver automatically writes their geometry and flow solution to volume/Unst.problemCells.<step>.cgns. This file can be opened in ParaView to visually inspect where the problematic cells are located in the mesh.
Warning
If you encounter a segfault during problem cell output, please try tunring it off and running again.
Another use of the diagnostics for runs using explicit time integration is to filter-out cells that are too small. The filtered cells do not contribute to CFL computation and do not cause time step size restrictions. By default, each filtered cell is merged with a neighbouring cell into a single control volume (agglomeration); a filtered cell that cannot be merged is treated like the other problem cells. You can leave this unspecified if not using explicit time integration.
diagnostics {
# Specify minimum cell size intended when grid was created
target size filter = 4e-3
# The solver places the filter between half the target size and the target size, where the
# tail of undersized cells ends (size filter method = knee, the default), and never filters
# more than this percentage of the cells. With size filter method = percent, it raises the
# filter from the minimum size toward the target size as far as this percentage allows.
max percent filtered = 0.05 # default
# You can also manually specify a hard cut-off for the minimum allowed cell size; cells
# below it are always filtered. By default, it is half of the target size filter
min size filter = 2e-3
}
Periodic
The domain can be setup as periodic in x,y,z directions. However the grid must be built with special considerations in one of two ways. One option is to apply extra grid cell padding (at least two cells thick on both periodic ends) to act as periodic fringe exchange locations. Ideally, these padding cells, when shifted in the periodic direction by the domain width, should match interior cells perfectly on the other end. There are tools to mirror and extrude the cells to fit this criteria. Alternatively, the connectivity between cells at the periodic boundary must be correctly accounted for during the mesh generation step. This can be achieved in the LAVA Voronoi mesher, for example, by creating ghost periodic cells with the correct parent id where necessary. The end product is a seamless periodic domain generation.
If the first option is chosen and the grid is prepared, inputs for periodic setup are:
periodic {
# Activate periodicity in y-direction
do y = true
# Interior domain bounds in periodic direction
ymin = -0.0325
ymax = 0.0325
# In case periodic fringes do not exactly overlap with donor cells,
# perform interpolation
do interpolation = false # default
# Test the periodic setup by performing an interpolation
# for coordinates and checking linear exactness
# false by default
do test projection = true
}
The example above is only for y-direction. Periodicity can be activated in other directions at the same time. Here is an example for a triple periodic setup:
periodic {
# Activate periodicity in all 3 directions
do x = true
do y = true
do z = true
# Interior domain bounds in periodic direction
xmin = -0.5
xmax = 0.5
ymin = -0.5
ymax = 0.5
zmin = -0.5
zmax = 0.5
}
Alternatively, if the periodicity was included in the mesh generation process in a way that correctly accounts for the periodicity and connectivity of the cells, then the user should inform the domain boundaries in each axial direction and turn on the face translation corrections via the following parameters:
Time Integration and Numerical Schemes
This page covers the blocks inside unst { } that control how the equations are integrated in time
and discretized in space: the explicit and implicit time integrators, the gradient reconstruction,
the convective schemes, the Navier-Stokes and turbulence model options, and the wall function.
Explicit Stepping
Explicit time stepping is available for unsteady simulations, typically used for WMLES or LES.
explicit {
# Specify the type of Runge-Kutta time integration scheme
# Options: rk1, rk4, ssprk22, ssprk32, ssprk33, ssprk53
method = ssprk33 # default
}
Implicit Stepping
Implicit stepping options for either steady simulations, or pseudo-time stepping unsteady simulations are specified in the implicit section.
implicit {
# method options are either 1st order accurate backward differencing formula (BDF1) or
# the second order version BDF2. The default is BDF2
# This option is not relevant for steady runs and can be skipped.
method = BDF2
# Number of implicit iterations.
# For steady runs, this is the maximum number of iterations
# For unsteady runs, this is the maximum number of sub-iterations for each time step
number of steps = 10000
# Specify CFL value
CFL = 10
}
In most cases, we favor using adaptive local CFL time stepping. This allows the code to try larger step sizes while adjusting as needed. Adaptive stepping generally improves robustness and results in faster convergence.
implicit {
...
# Allow CFL to adaptively vary between min and max
adaptive {
min CFL = 0.5
# [default = 1e4]
max CFL = 1e4
# In cases where turbulence model is used, CFL for
# turbulence model equations can be limited differently
# [default = max CFL]
max CFL turbulence = 1e4
# Steady runs: linearize the flow equations matrix free
# once no CFL cures a stall [default = true]
matrix free on stall = true
}
}
}
The adaptive CFL starts at min CFL and is updated after every implicit step:
- While the steady residual falls, the CFL grows by up to 1.5 times per step, in proportion to the share of the update the step took (the line-search step length and the per-cell change limits below).
- A step that raises the residual by more than 10% halves the CFL. A rejected step, after a failed line search or linear solve, cuts it to a quarter. Above 70% of the CFL that failed, the CFL then grows by at most 5% per step, or 1.5 times once the residual falls by more than half per step. That ceiling relaxes by 2% per step.
- When convergence stalls (the residual falls by less than 3% per step over three steps) and the line search shortened every one of those steps, the CFL descends by 20% per step. The descent remembers the CFL that gave its best convergence rate. Once ten steps have passed without a better rate and the residual has fallen, on average, less than half as fast as at the best rate, the CFL returns there, so a stall that a lower CFL does not cure does not drag the CFL down to
min CFL. - In a steady run, a stall that no CFL cures means the assembled Jacobian no longer gives a usable Newton direction. Once the residual is below 1% of its initial value, the flow equations then switch to a matrix-free linearization: GMRES applies the Jacobian of the full second-order residual by finite differences, preconditioned with the assembled Jacobian, so each GMRES iteration costs one residual evaluation. The switch happens when the descent returns to its best CFL, or when the line search shortened or rejected at least 18 of the last 20 steps while the residual fell by less than 3% per step on average. It lasts for the rest of the run, carries over to a restart, and is announced in the log.
matrix free on stall = falsekeeps the assembled Jacobian throughout. - Each cell also has its own factor on the pseudo-time step. It shrinks in cells whose update the change limits clip and regrows where they do not, so a few stiff cells do not hold the CFL of the whole domain down. With dual time stepping, these factors and the convergence history restart with every physical time step.
max CFL is a safety limit: the adaptive CFL does not need it to converge.
Following are some options for the evaluation of Jacobian and the non-linear convergence
implicit {
...
# Compute the jacobian analytically (approximate) or numerically (via finite difference)
jacobian method = numerical # numerical (default) or analytical
# Interval of implicit steps at which the jacobian is updated
jacobian interval = 5 # default
# For numerical Jacobians, we can use the Q vector to automatically
# determine the choice of epsilon. This input controls that option.
do auto epsilon = true #default
# If auto epsilon set false, then instead read an input epsilon value.
jacobian epsilon = 1.e-6 # default
}
By default, the Jacobian is numerical: it is evaluated by finite differencing the RHS operator, so it accounts for the second order MUSCL reconstruction and the actual flux function, and supports deep convergence. The analytical option uses the analytical derivative of the van Leer convective flux instead. It is cheaper to evaluate, but approximate: it ignores the second order reconstruction, which can limit the depth of convergence. The epsilon value is what is used to perturb primitive variables (normalized by reference quantities) when computing finite difference (numerical) Jacobians. It is computed automatically by default, but may be set to a fixed value if desired.
Finally, you may choose to activate a line search algorithm for the non-linear implicit iterations to find asymptotic convergence path.
implicit {
...
# Whether to use line search [default = true for steady, false for dual-time]
do line search = true
# Maximum relaxation factor for line search updates
max relax = 1. # default
}
The line search is on by default for steady runs and off for dual-time (unsteady) runs. It is what keeps a lagged Jacobian usable, so it pairs with the jacobian interval = 5 default; with a dual-time inner loop the interval is back at 1 and the line search only costs an extra residual per sub-iteration. max relax adjusts what portion of the line search update to advance the solution with.
Convergence Criteria
Convergence tolerances for implicit iterations can be specified as:
convergence {
test continuity only = true #default
relative tolerance = 1.e-6
absolute tolerance = 1.e-12
}
The values are L2 error norms either relative to the first iteration (normalized),
or in absolute (non-normalized) sense. The implicit iterations are deemed converged when all L2 error norms for all the equations meet either the relative or absolute criteria. If the test continuity only flag is set to true (default value), L2 error norm of only the continuity equation is considered as convergence criteria.
If these inputs are not provided, the code will simply perform the full number of steps specified in the implicit section regardless of convergence level.
Gradients
Gradients feed both the MUSCL reconstruction of the convective terms and the viscous fluxes. They are specified in the gradient section:
gradient {
# Cell gradient reconstruction method [options = gglex, lsqr, gg | default = gglex]
method = gglex
# Exponent p in the least-squares weight w = 1/|dx|^p [default = 2]
lsqr weight exponent = 2
# Fall back to Green-Gauss above this estimated condition number [default = 1.e8]
lsqr max cond = 1.e8
}
method = gglex is Green-Gauss with corrected face averages and is the default. It is linear-exact on any mesh — a linear field is differentiated exactly — while keeping the surface-sum form, so it costs essentially the same as plain Green-Gauss. method = lsqr is a least-squares fit over the face neighbors and is also linear-exact. However, it is not recommended for high anisotropic meshes such as wall prism layers over curved surfaces. method = gg is Green-Gauss with a plain arithmetic face average, which is not linear-exact.
Convective Terms
Convective flux options are specified in the convective terms section. Three different convective schemes can be setup; MUSCL, CENTRALQ and KEEPBLEND, latter two of which are low dissipation schemes to be used in scale-resolving simulations (i.e. LES and WMLES).
MUSCL Scheme
The traditional \(2^\mathrm{nd}\) order MUSCL scheme with limited gradient reconstruction can be setup with:
convective terms {
# Convective flux scheme (options = MUSCL, CentralQ, KEEPBLEND) [default = MUSCL]
scheme = MUSCL
# MUSCL reconstruction order [options = 1,2 | default = 2]
order = 2
# Limiter [options = none, minmod, minmod soft, rminmod, rvlmc | default = none]
limiter = rminmod
# Only for rminmod and rvlmc: leave faces without a shock unlimited [default = true]
# false limits every face (see Limiter options)
limiter gate = true
# Only active for minmod soft, the overshoot parameter will allow normalized
# overshoots of the specified amount. In this example, it is set to 5%
limiter overshoot = 0.05
# Blended (U-MUSCL) reconstruction [range = 0 to 1 | default = 1/3]
# 1/3 minimizes dispersion error; 0 reproduces the plain MUSCL reconstruction
reconstruction kappa = 0.33333333333333333
# Flux function [options = roep,ausmpw+,hrslau2,rusanov,hllec,hlleclm | default = ausmpw+]
flux function = ausmpw+
}
ausmpw+ for runs with explicit time integration and for implicit runs at supersonic speeds or with dual time stepping, and hlleclm for steady implicit runs of low-speed viscous flows, where it converges faster and is more accurate in the low-Mach regions. At high Mach numbers, we recommend adding extra dissipation (see High Mach Simulations section).
hlleclm is the HLLEC flux with a low-Mach correction. Selecting it sets hllcmalimit = 0.1 and hllcphifloor = 0.3 by default: the first is the Mach number below which the low-Mach branch engages, the second the floor on its dissipation scaling, which is what keeps the flux stable on stretched viscous meshes. Both can be overridden in the same section. The hlle/hllec/hlleclm family is implemented on the CPU only and is rejected with an error on a GPU run.
roep option stands for preconditioned Roe flux function, which has additional options:
convective terms {
...
flux function = roep
# Entropy fix method
# 0: No entropy fix
# 1: Entropy fix version 1
# 2: Entropy fix version 2 (default)
ientropy = 2 # default
# Activate low-speed preconditioning
# 1: No preconditioning (default)
# 2: Local inviscid velocity
# 3: Constant beta
iprecon = 0 # default
# For iprecon = 2, beta is a measure of local Mach number (but w.r.t to the reference speed of sound)
# Local speed of sound is scaled according to this Mach number
beta = 1. # default
# Epsilon threshold for eigen values in entropy fix
eigeps = 0.5 # default
}
limiter is only required for transonic or supersonic cases to preserve monotonicity around discontinuities, and defaults to none.
Limiter options
minmod is the long-standing option and is retained unchanged. It compares the reconstructed face increment against the jump to the neighbor cell only, which means it does not limit at the foot of a shock, where the upstream side is flat and the downstream side is not. In practice this shows up as an overshoot at shocks.
rminmod and rvlmc remove both problems. They reconstruct the missing upstream information from the cell's own gradient, so they apply a genuine two-sided test without reading any additional cells and without any extra memory. Both also release themselves automatically on faces carrying no shock. This gate measures the pressure jump across each face against the local \(\rho c^2\): a face whose pressure jump is under 1% of \(\rho c^2\) is left unlimited, and the limiter is fully applied above 3%. Shocks and compressions carry a pressure jump, while shear layers and boundary layers carry none, so smooth flow and boundary layers are reconstructed at full order without needing a shock sensor. Contacts (a temperature or composition jump at uniform pressure, such as a plume boundary) are caught by the density jump instead: the limiter is applied where \(|\rho_R-\rho_L|/(\rho_L+\rho_R)\) exceeds 0.05 and fully above 0.1. Faces next to a cell clipped to the minimum pressure are always limited. The two-sided test sees a face increment only along the line between the two cell centroids; where the increment is carried mostly across that line, as on skewed or curved near-wall cells, the test is discounted accordingly, so it cannot switch such an increment on and off from one implicit iteration to the next. They differ only in how aggressively they limit:
| Limiter | Shock capture | Robustness |
|---|---|---|
minmod |
Sharp, but overshoots | Baseline |
rminmod |
No overshoot, slightly wider shock | Most robust of the three |
rvlmc |
No overshoot, sharp shock | Least robust on strong 3D shocks |
rminmod is the recommended starting point for supersonic and hypersonic cases. Choose rvlmc if shock thickness matters more than robustness for your case, and be prepared to fall back to rminmod if a strong bow shock proves difficult.
Slip lines without a significant density jump (for example the slip line behind a Mach stem) are reconstructed without a limiter and can show some overshoot. If that causes trouble, set limiter gate = false (default true): the limiter is then applied on every face, at the cost of also limiting smooth flow and boundary layers, which can stall steady implicit convergence.
limiter gate applies only to rminmod and rvlmc; setting it to false with any other limiter stops with an input error.
Reconstruction kappa
reconstruction kappa blends the usual gradient extrapolation with an interpolation toward the neighbor cell. The default is 1/3; setting reconstruction kappa = 0 gives the plain MUSCL reconstruction. The default 0.33333333333333333 cancels the leading dispersion error of the second-order scheme, which improves how well the solver preserves waves over long distances. It affects only the reconstructed states used by the upwind flux, so for KEEPBLEND the kinetic-energy-preserving central flux is untouched.
Values between 0 and 1 are accepted. 1 is excluded because it removes the upwind dissipation entirely.
Scale-Resolving Simulations
Scale-resolving simulations require reduced dissipation numerics to preserve smaller turbulent fluctuations that are at a comparable scale to individual grid cells. LAVA unstructured offers two different low dissipation schemes: CENTRALQ and KEEPBLEND. Both of them utilize blending sensors to selectively reduce dissipation in smooth flow regions (free of shocks) where turbulent fluctuations are present.
Upwind Blending Sensors
These sensors dictate where and to what degree the scheme deploys upwind dissipation. There are a variety of sensor options:
convective terms {
# Sensor(s) that determine the amount of central Q blending or flux blending,
# and how much of the limiter is applied
# Options: ducros, ducrosmod, strain, strainmod,
# limiter, neumann
# More than one sensor can be activated through the list below
upwind blending sensors = [ducrosmod, limiter]
# For ducrosmod and strainmod sensors, this parameter adjust the localization of the sensor
# as a multiplier for the enstrophy term
# Higher values represent more localization (i.e. less dissipation)
# A value of 1 recovers original formulation, e.g. ducrosmod becomes the standard ducros sensor
upwind sensor enstrophy factor = 100 # [default]
# Limits of blending
# 0: no upwind (full central), 1: full upwind
upwind blending min = 0. # default: 0
upwind blending max = 1. # default: 1
# Same limits but only applied at wall adjacent faces
wall upwind blending min = 0. # default: 0
wall upwind blending max = 0. # default: 1
}
The sensors are combined by taking the maximum, and the result drives the central-versus-upwind blend, which is what sets how much upwind dissipation the scheme deploys. T
strain and strainmod are protection sensors rather than shock sensors: they return 1 (full upwind) in irrotational flow and fall toward 0 only where the flow is genuinely rotational, so a resolved vortex is handed to the central scheme while the rest of the field stays upwind. ducros and ducrosmod are the opposite sense and fire where the dilatation dominates the rotation, rising continuously out of the dead band rather than switching. They are symmetric in the sign of the dilatation, so they fire on strong expansions as well as on compressions; that is deliberate, because in this solver the sensor sets how much upwind dissipation is deployed and a strong expansion needs it too. Pairing a strain sensor with neumann is the intended setting for a supersonic scale-resolving case: outside vortices and shocks the scheme is upwind, inside a resolved vortex it is central.
The blend weight itself can be inspected directly by requesting the upwind volume-output variable.
CENTRALQ Scheme
This scheme blends left and right reconstructed primitive flow variables based on the upwind sensor. The details can be found in Sozer et al.1. Example usage is shown below:
convective terms {
scheme = CentralQ
order = 2
limiter = minmod
# Pick which Q components to centralize (options: p,u,v,w,t)
central components = [p,u,v,w]
upwind blending sensors = [ducrosmod]
flux function = ausmpw+
}
Note that you have the option to individually centralize primitive variables via central components specification. In the example usage, we have excluded t which stands for temperature. This results in a more stable and smooth scheme compared to full centralization.
CENTRALQ approach results in a low dissipation scheme suitable for LES. However, convective scheme dissipation can be further reduced by using the KEEPBLEND scheme which is the current recommended best practice.
KEEPBLEND Scheme
Instead of blending reconstructed primitive variables at flux faces, KEEPBLEND scheme computes two individual fluxes: i) A non-dissipative kinetic energy and entropy preserving (KEEP) flux (our implementation is approximately entropy preserving), and ii) A dissipative upwind flux. The two fluxes are then blended based on the choice of the upwind sensor. More details about this scheme can be found in Sozer et al.2. This scheme will always centralize all flux components, so the central components input is not used. order and limiter only affect the MUSCL reconstruction of the dissipative flux. An example usage is shown below:
convective terms {
scheme = KEEPBLEND
# MUSCL reconstruction order [default = 2]
order = 2
limiter = minmod
upwind blending sensors = [ducrosmod]
flux function = ausmpw+
}
High Mach Simulations
At high Mach numbers, shocks can develop numerical artifacts, especially if they are not perfectly aligned to the mesh. To remedy this, use the add shock dissipation = true option which employs a shock sensor to detect the shock locations and selectively add extra dissipation.
convective terms {
# This will employ a shock sensor to add extra dissipation near shocks
# extra dissipation is computed with Rusanov flux and blended into the
# flux function selection above
add shock dissipation = true # [default: false]
}
ducrosmod or strainmod upwind blending sensors, we recommend setting upwind sensor enstrophy factor = 1 to provide additional robustness at high Mach numbers.
Navier-Stokes Options
This section sets up the option for integrating the Navier-Stokes equations. For explicit time integration, the options are:
navier stokes {
# Switch between viscous or inviscid
viscous = true #default
# Following flow variables are clipped from below and top
# according to the limits specified. These are not required
maximum mach = 2
minimum density = 1e-20
minimum pressure = 0.1
maximum pressure = 1e20
minimum temperature = 0.1
maximum temperature = 1e20
}
The minimum and maximum limits of the flow quantities act in various ways. min/max pressure and tempeature are checked during MUSCL reconstruction. If the robust mode is active, these quantities along with maximum Mach number are also used to test for the health of time integration as described in the robust mode section.
For implicit runs, there are a few other inputs, all or most of which can be omitted in favor of using defaults.
navier stokes {
...
# Maximum number of GMRES linear solver iterations
maximum iterations = 40 #default
# Maximum number of Krylov vectors computed with GMRES algorithm.
subspace size = 40 # default same as "maximum iterations"
# Relative (normalized) convergence tolerance for GMRES
# The linear solver iterations will stop when this level is met
relative tolerance = 1.e-2 #default
# Absolute (non-normalized) converfence tolerance for GMRES
# The linear solver iterations will stop when this level is met
absolute tolerance = 1.e-20 # default
# If the linear solver residual exceeds the maximum tolerance, the adaptive CFL
# grows by at most 5% per step above 70% of the CFL of that step
maximum tolerance = 0.5 # default
# If the linear solver residual is above the failure tolerance,
# the implicit step is considered to have failed and the update is rejected
# The adaptive CFL is cut to a quarter
failure tolerance = 0.8 # default
# Within each implicit iteration, expected density change in each cell
# is checked before the linear solver. Cells that will likely exceed the
# value specified below (20% change allowance) will trigger a reduction
# in their CFL (hence step size).
density change threshold = 0.2 # default
# Similar to above but operates on primary flow variables (p,u,v,w,T) and
# applied after the linear solver.
q change threshold = 0.2 # default
# The Jacobian calculation algorithm may be chosen separately for Navier-Stokes
# and turbulence. To override the setting specified in the implicit input section,
# specify the equation below.
jacobian method = numerical # numerical (default) or analytical
}
Robust Mode
Note
Some features of the robust mode is currently only supported for explicit time integration
In rare cases where solver is unstable, you can turn on the robust mode. In this mode, at every time integration step (or Runge-Kutta integrator stage), the solver will test the solution update against the Mach, density, pressure and temperature limits as specified in the navier stokes section. If any of these criteria are violated, the solver will attempt to recover by applying a smoothing operator to the problematic cells and repeating the step by using dissipative numerics for those cells for the repeated step only.
expert {
robust mode = true # false by default
max bomb recovery attempts = 5
# Permanently add the crashing cell to the problem cell list
mark bomb cells as problem = false
# When enabled, write the geometry and flow solution of the offending tiles to
# volume/bombTiles.cgns on abort
# This option is TRUE by default
dump bomb tiles = false
}
If the stability issue persists after max bomb recovery attempts consecutive attempts, the solver will abort the solution and write out the problematic tile solutions to volume/bombTiles.cgns file.
If mark bomb cells as problem = true, the cells experience the stability issue are permanently added to the problem list and are no longer solved for.
Tip
On abort, the solver writes volume/ABORT_Unst.problemCells.<step>.cgns containing the flow solution at the time of abort. If mark bomb cells as problem = true is set in the input file, the cell that caused the crash will also be a part of the problem cell list. Open this file in ParaView and use the Process Unst Mask filter from the LAVAParaviewPlugin (please refer to the plugin documentation here) to extract more details about the cell.
Warning
In implicit simulations, robust mode only considers the maximum mach specification in the navier stokes section. mark bomb cells as problem and max bomb recovery attempts inputs are not used.
Turbulence Options
LAVA unstructured can currently use Spalart Allmaras (SA) turbulence model and it's various variants for RANS and URANS simulations.
turbulence {
# Available options: [sa,sa-des,sa-ddes,sa,sa-qcr,sa-qcr-rc,sa-rc]
model = sa
# If using qcr variations, pick which version (options: 2000, 2013, 2013-v)
# 2013-v = QCR2013 with vorticity instead of strain in the extra term (NASA TMR QCR2013-V)
qcr version = 2000
# Maximum number of GMRES linear solver iterations
maximum iterations = 40 # default
# Maximum number of Krylov vectors computed with GMRES algorithm.
subspace size = 40 # default same as "maximum iterations"
# Relative (normalized) convergence tolerance for GMRES
# The linear solver iterations will stop when this level is met
relative tolerance = 1.e-2 # default
# Absolute (non-normalized) convergence tolerance for GMRES
# The linear solver iterations will stop when this level is met
absolute tolerance = 1.e-20 # default
# If the linear solver residual is above the failure tolerance, the turbulence
# update is rejected and retried at a quarter of the turbulence CFL. At the
# minimum CFL, the turbulence variable is left unchanged for that step
failure tolerance = 0.5 # default
# Limit ratio of eddy viscosity to laminar viscosity
viscosity ratio limit = 1e6 #default
# Limit change of turbulence variable to 20% in each implicit iteration
# this guides the adaptive implicit stepping
change threshold = 0.2 # default
# Lower limit for SA working variable
minimum nut = 1e-12 # default
# Turbulent Prandtl number
Pr = 0.9 # default
# Turbulent Schmidt number
Sc = 0.9 # default
# The Jacobian calculation algorithm may be chosen separately for Navier-Stokes
# and turbulence. To override the setting specified in the implicit input section,
# specify the equation below.
jacobian method = numerical # numerical (default) or analytical
}
For LES, subgrid scale model is also specified in this section.
turbulence {
# SGS model (options: none, vreman, smag)
sgs model = vreman
# SGS constant for Vreman, default is 0.07
# but for unstructured solver, best practice is using 0.08
sgs const = 0.08
}
Wall Function
Wall function is supported for both WMLES and RANS simulations. However, the implicit RANS solver doesn't currently account for wall function Jacobians, leading to decreased stability and lower CFL requirements.
wall function {
# Pick wall function, options: musker (default), reichardts, blendedlog, rough
type = blendedlog
# If using rough wall model, specify the roughness in meters
# 0.25e-6m : highly polished
# 0.50e-6m : polished
# 3.33e-6m : painted
roughness = 0.5e-6
# If activates, this will make the wall function switch between
# modeled wall stress and no-slip boundary condition depending on
# a wall turbulence sensor. When the sensor indicates laminar,
# no-slip will be used
do transition = false # default
# Adjusts the threshold where the sensor decides between laminar and turbulent
# The smaller the number, the earlier the transition
transition threshold = 0.05 # default
}
References
-
Sozer, E., Ghate, A. S., Kenway, G. K., Barad, M. F., Sousa, V. C., and Kiris, C. C., "Evaluation of Voronoi Meshes for Large Eddy Simulations of High Lift Aerodynamics," American Institute of Aeronautics; Astronautics, 2023. https://doi.org/10.2514/6.2023-0255 ↩
-
Sozer, E., Barad, M. F., Housman, J. A., Cadieux, F., Sousa, V., Dumlupinar, E., Saurabh, K., Ravikumar, K., and Duensing, J. C., "LAVA WMLES Results for the 5th High-Lift Prediction Workshop," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-0887 ↩
Boundary Conditions
Boundary conditions are specified in the form of a numbered list, where the order must match the boundary zones in the CGNS grid file:
The order of the boundary conditions (BC's) needs to be consistent with the order of BC's zones in the grid file. A list of BC zones in the grid file can be obtained using the tool unst_gridInfo.Available BC types are wall, wallfunction, symmetry, centerline, inlet, outlet, farfield, exact, nozzle and distributed. Each is explained below with their options.
Wall
Wall type boundaries can either impose no-slip or slip conditions, specified with the kind statement:
The wall BC is treated as adiabatic by default. You can change the
thermal behavior by either specifying a temperature (for isothermal wall) or a heat
transfer rate (for fixed heat transfer wall). The heat transfer rate qdot should be
given in [W/m^2] units. A positive qdot indicates energy being added to the domain (heating).
Conjugate fluid/solid heat conduction (solved in 1D rays in the wall normal direction, dicretized through the solid thickness) modeling can be activated through wall boundary conditions. This model needs wall material properties and thickness as inputs.
BC_1 {
type = wall
temperature = 300 # Used as initial condition
conjugate solid = Steel_ASTM_A572_Grade50.sol
# Number of points (uniformly distributed) in the solid ray
solid number of points = 300
solid thickness = 0.02
solid output stride = 10 # Output every 10th conjugate ray
}
The format of the conjugate solid material file is explained here.
Wall motion
By default a wall moves with the grid it belongs to: in a domain with rigid body motion the no-slip velocity is the local grid velocity, in a fixed domain it is zero. wall motion states the absolute motion of a wall that differs from its grid's:
BC_1 {type=wall; wall motion = stationary} # fixed in the inertial frame although its grid rotates
BC_6 {type=wall; wall motion = motion_1} # follows rigid body motion_1 although its grid is fixed
BC_7 {type=wall; wall velocity = [10, 0, 0]} # constant velocity (m/s, inertial frame); also "wall motion = velocity"
Options: grid (default), stationary (aliases none, fixed), motion_<k> (any rigid body motion block, rotation or translation, constant or sinusoidal), and velocity. axisymmetric (alias revolution) is still accepted for old input files and ignored with a warning: the wall moves with its grid. The prescribed motion sets the tangential wall velocity. The wall-normal velocity depends on the option:
gridandvelocity: the wall face moves with its grid (a blade, a hub or spinner turning with its zone, a translating belt), so its normal velocity is the grid's — the standard moving-wall condition.stationaryandmotion_<k>: the wall moves differently from its grid, which is only possible when the surface maps onto itself under the grid motion; the wall gets no normal velocity. The solver checks this at setup and prints a warning for a wall that is not a surface of revolution about the rotation axis, or, in a translating zone, not parallel to the translation: such a wall would let mass through its moving faces.
The setting applies to wall and wallfunction boundaries alike (the wall model sees the slip relative to the prescribed wall velocity).
Wallfunction
Wall function is an alternative wall boundary condition that applies a wall model:
The default behavior of the wall function is controlled through the wallfunction section in the input file. However you can customize the wall function type and roughness settings for each BC as:
Symmetry
Symmetry BC has no additional inputs.
Centerline
For axisymmetric simulations:
Please see grid transformation section for more details on how to set up an axisymmetric simulation.
Farfield
This is characteristics based inlet/outlet farfield condition for all speeds. If no options are given, it will use the reference conditions as farfield values.
You can also set the farfield conditions to be different than reference conditions:
You can specify either two of the thermodynamic quantities: pressure, temperature and density.
Inlet
Inlet is a flexible type that will activate the proper boundary condition based on what is specified. Several different inlet implementations are available as detailed below. Before specific details, here are some common inlet options that are shared:
BC_1 {
type=inlet;
# Mass fractions are only needed for multi-species simulations.
massfractions=[0.233, 0.767] # For 2 species
# For turbulence models
eddyviscosityratio=3.0;
# Optional sponge layers to dampen reflections
spongelayers=2;
}
Velocity inlet
If velocity is specified, velocity inlet BC is activated:
BC_1 {
type=inlet;
# Required
velocity=[100,0,0]; # m/s
# One of these options is required for subsonic inlet
density=1.225; # kg/m^3
#pressure=101325; # Pascal
#temperature=300; # Kelvin
}
A subsonic inflow takes four of its five characteristic waves from the boundary data (velocity and one
thermodynamic quantity); the fifth leaves the domain and brings the interior's \(p + \rho c\, u_n\), which
completes the boundary state. With temperature, that wave sets the static pressure.
Stagnation inlet
Stagnation conditions (total pressure/temperature) can be used as:
Mass flow inlet
BC_1 {
type=inlet;
mdot=0.1; # kg/(m^2.s) (positive for inflow)
# One of these options is required for subsonic inlet
density=1.225; # kg/m^3
#temperature=300; # Kelvin
# A supersonic inlet needs the full state
#pressure=101325; # Pascal, together with temperature
}
As for the velocity inlet, the wave leaving the domain completes the boundary state: with temperature it
sets the static pressure and, through the density, the velocity that carries the mass flux; with density it
sets the static pressure. A pressure alone is refused: that wave can call for an outflow at any given inlet
pressure.
Outlet
Outlet is a flexible type that will activate the proper boundary condition based on what is specified. Several different outlet implementations are available as detailed below.
BC_1 {
type=outlet;
# One of these options is required for subsonic outlet
pressure=101325; # Pascal
#temperature=300; # Kelvin
#density=1.225; # kg/m^3
# If none of the above options are specified,
# the outlet extrapolated everything from inside
# This is only valid for supersonic outlets
# Optional sponge layers to dampen reflections
spongelayers=2;
}
Additional controls are offered through the kind options:
# Handle reverse flow by damping
BC_1 {type=outlet; kind=dampreverse}
# Prevent reverse flow
BC_1 {type=outlet; kind=noreverse}
# Force supersonic outlet conditions
BC_1 {type=outlet; kind=forcesupersonic}
Mach outlet
You can set either fixed local or average Mach number as outlet conditions:
Exact
Applies an exact solution from the specified exact flow option:
Nozzle
The nozzle boundary condition is mainly used for launch simulations where the boundary condition is applied to the nozzle exit. It also comes with a few physics options to improve stability and control the output. A basic boundary condition can be specified via the following:
where the nozzle boundary condition takes an input file filename which has several supported file types datafiletype described below. Like the above boundary conditions, they are applied to a component on the triangulation specified by components. In a multispecies simulation, you must also specify ispecies which corresponds to the 0 based index of the mixture in the fluid section for which species the nozzle will eject.
A complete list of all the options is provided below, along with default options where applicable:
Main Options:
| Variable | Description |
|---|---|
| filename | (Required) The filename of the describing boundary condition file |
| datafiletype | (Required) The type of datafile. 0 is a steady (constant) ascii file. 1 is radially varying constant ascii file, 2 is unsteady but constant in space ascii file, 3 is unsteady radially varying binary, 4 is unsteady radially varying ascii file |
| ispecies | (Required for multispecies/multiphase) Specifies the component of mixture for the nozzle to eject. |
| nozzlecenter | (Optional) Specifies the coordinates of the nozzle center |
| nozzlenormal | (Optional) Specifies the normal for the boundary condition to be applied on |
| radiusdirection | (Optional) Unit vector in global coordinates used for projected-radius lookup: abs((x-nozzlecenter)·radiusdirection). When omitted, the default radial distance from nozzlecenter is used. Useful for planar/slot injection profiles. |
| asciilinetimestart | (Required) Only used for datafiletype=4. Specifies the line number to start reading the file. |
| asciilinetimestop | (Required) Only used for datafiletype=4. Specifies the line number to stop reading the file. |
| asciilinetimeskip | (Optional) Only used for datafiletype=4. Specifies the stride at which to read lines from the file. Default is 1. |
| asciilinereadspecies | (Optional) Only used for datafiletype=4. Bool for whether this file contains species information as well. Default is false. |
| numberofradialpoints | (Required) Only used for datafiletype=4. Specifies the number of radial points in the file. |
Note
The mixture state prescribed when asciilinereadspecies=true takes precedent over ispecies. In this case, ispecies is disregarded by the reader.
Ramp Options:
| Variable | Description |
|---|---|
| rampsteps | (Optional) Will linearly warmup the nozzle based on rampsteps number of timesteps by taking a linear combination of the reference Q and the user specified conditions in filename. Default is 0 (no step ramping). |
| rampnton | (Optional) The timestep number to turn the ramping on. Nozzle will be off prior to this timestep. (Only used with rampsteps). Default is -1. |
| ramptimestart | (Optional) If rampsteps is not turned on, the other ramping option is using simulation time. This is the same linear warmup between ramptimestart and ramptimestop. Before ramptimestart the nozzle is off if it is specified. Default is no time ramping. |
| ramptimestop | (Optional) The simulation end time to ramping. |
| timeshift | (Optional) Timeshift can be used to shift the nozzles in time relative to the simulation time. This is compatible with ramping. Default is 0. |
Note
One should only use (rampsteps and rampnton) or (ramptimestart and ramptimestop). They will not work in a combined fashion.*
Physics Options:
| Variable | Description |
|---|---|
| multiphaseequilibrium | (Optional) Only used in cartesian + multiphase. This computes multiphase equilibrium on the boundary condition. Default is false. |
| dostagnation | (Optional) Apply stagnation inlet boundary conditions. Not supported for multiphase. Default is false. |
| doautomaticsonicinlet | (Optional) Only used when dostagnation = false. If the boundary condition goes below subsonic speed, we get pressure from the interior. This keeps the velocity at the inlet >= mach 1. Not supported for multiphase. Default is false. |
| dothroatsonicinlet | (Optional) Only used when dostagnation = true. Forces the pressure to be sonic + 1%. Not supported for multiphase. Default is false. |
Projected Radius Option (radiusdirection)
By default, nozzle profile lookup uses the geometric radius from nozzlecenter.
When radiusdirection is provided, the lookup coordinate is projected onto that direction:
r_lookup = abs((x - nozzlecenter) · radiusdirection)
This enables planar/slot style injection profiles where variation is only along one direction.
Notes:
- radiusdirection is interpreted in global/cartesian coordinates.
- The input vector is normalized internally.
- A zero-length vector is invalid and will trigger an input error.
- If omitted, behavior remains the legacy radial-distance lookup.
Example slot-style setup (vary profile along y only):
BC_1 {
type = nozzle
datafiletype = 1
components = [1]
filename = nozzle_slot_profile.dat
ispecies = 0
nozzlecenter = [0.0, 0.0, 0.0] # Can be omitted. Solver will derive from geometry for each component
radiusdirection = [0.0, 1.0, 0.0]
}
ASCII Data Format
datafiletype = 0 or 1: steady, radially constant or varying, ascii file: radius(m) Pressure(Pa) Temperature(K) u_normal(m/s) u_radial(m/s)
datafiletype = 2: unsteady, radially constant, ascii file: time(s) Pressure(Pa) Temperature(K) u_normal(m/s) u_radial(m/s)
Info
Lines starting with # are omitted by the parser for datafiletype = 0, 1, 2.
datafiletype = 4: unsteady, radially varying, ascii file: line_number time(s) radius_x(m) radius_y(m) [radius_z(m)] Pressure(Pa) u_normal(m/s) u_radial(m/s) [u_azimuthal(m/s)] Temperature (m) [Species Mass Fractions]
Note
The format of datafiletype = 4 depends on the dimension of the configuration. The extra fields radius_z(m) and u_azimuthal(m/s) are required when running with 3D and must be omitted when running with 2D. Currently, the field u_azimuthal(m/s) is disregarded in the nozzle bc, however, it must still be present in the nozzle data file. Also, the fiels Species Mass Fractions are only present when asciilinereadspecies = true. Also, note that no comments are allowed in this file type format.
An example of a type-4 nozzle data base is shown below for the configuration asciilinetimestart = 0; asciilinetimestop = 30; asciilinetimeskip = 10; asciilinereadspecies = true:
0 -10000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
20 10000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
20 10000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
20 10000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
20 10000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
30 20000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
30 20000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
30 20000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
30 20000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
Distributed
Distributed boundary conditions use externally-defined flow data that is mapped to boundary faces. It uses surface solution files typically sampled from a previous solution. Currently cgns format is supported.
BC_1 {
type=distributed;
# Required: File containing distributed BC data
filename=path/to/distributed_data.cgns;
# Optional: Transform coordinates from data file to simulation
scalecoords=[1.0,1.0,1.0]; # Scale coordinates [default=[1,1,1]]
translatecoords=[0.0,0.0,0.0]; # Translate coordinates [default=[0,0,0]]
rotatecoordsdeg=[0.0,0.0,0.0]; # Rotate coordinates in degrees [default=[0,0,0]]
# Optional: Transform velocities from data file to simulation
scalevelocity=[1.0,1.0,1.0]; # Scale velocity components [default=[1,1,1]]
translatevelocity=[0.0,0.0,0.0]; # Translate velocities [default=[0,0,0]]
rotatevelocitydeg=[0.0,0.0,0.0]; # Rotate velocities in degrees [default=[0,0,0]]
}
For unsteady distributed boundary conditions, use the following format:
BC_1 {
type=distributed;
isunsteady=true;
# Required: Time step range and format specification
ntlo=1000; # First time step to use
nthi=2000; # Last time step to use
ntskip=10; # Interval between time steps
numdigits=6; # Number of digits in filename formatting
prefix="data_"; # Prefix for filenames
suffix=".cgns"; # Suffix for filenames
# Optional: Transform specifications as in steady case
scalecoords=[1.0,1.0,1.0];
# ... other transform options
}
The distributed BC files should contain flow variables that are mapped to boundary faces using either nearest-point sampling or interpolation. For unsteady boundary conditions, the solver will interpolate between time steps as needed.
Note
Files for unsteady BCs are expected to follow the naming pattern: prefix + formatted_time_step + suffix For example: with prefix="data_", numdigits=6, suffix=".cgns", and time step 1000, the file would be "data_001000.cgns"
Warning
Distributed boundary conditions are computationally expensive and not supported when using GPU acceleration.
Rigid Body Motion
Rigid Body Motion
This section describes the grid motion capabilities available in the LAVA Unstructured solver, beginning with rigid-body motion. Rigid-body motion alters the position and orientation of the computational grid while preserving its original geometry. Although grid point coordinates vary over time, the relative distances, connectivity, and topology of the mesh remain unchanged. Consequently, geometric quantities such as cell volumes and face areas remain constant throughout the simulation.
Rigid-body motion can be prescribed as either translation or rotation. Each type can be specified as a constant motion (constant translational or angular velocity) or as a sinusoidal oscillation. This capability defines the movement of different grid domains and is essential for simulations involving moving components. It is also critical for stability analysis and unsteady aerodynamic simulations involving prescribed single-degree-of-freedom (1-DOF) motions, including forced-oscillation roll, pitch, yaw, surge, sway, and plunge.
Each grid file specified in the Grid File and Transformations section Grid File and Transformations is indexed sequentially starting from 1, based on its order in the grid definition list. Support for prescribed combined translation/rotation motions, as well as general six-degree-of-freedom (6-DOF) free-flight simulations, is currently under testing.
You can define multiple motion groups, each identified by a unique index (e.g., rigidbodymotion_1, rigidbodymotion_2). Each motion group is then assigned to one or more domains, though each domain may belong to only one motion group.
Below are four structured examples demonstrating how to configure rigid-body motion in the unst.input file:
Constant Speed Rotation
The following example configures a grid domain for a constant-rate rotational motion. This is typically used for a spinning rotor or propeller, or for a vehicle undergoing a constant-rate pitch ramp to change the angle of attack at equal intervals:
rigidbodymotion_1 {
# List of domain IDs this motion applies to
domains = [1]
# Type of motion
type = rotation
# Rotation axis (will be normalized)
axis = [0,1,0]
# Center of rotation
center = [0,0,0]
# Angular speed in radians per second
angular speed = 10.0
}
Sinusoidal Rotation
For oscillating motions, you can define a sinusoidal rotation. The angular speed parameter is replaced by amplitude and a rate given as either frequency or omega.
rigidbodymotion_1 {
# List of domain IDs this motion applies to
domains = [1]
# Type of motion
type = rotation
# Kind of rotation
kind = sinusoidal
# Rotation axis (will be normalized)
axis = [0,1,0]
# Center of rotation
center = [0,0,0]
# Amplitude of oscillation in degrees
amplitude = 10.0
# Oscillation rate: frequency in Hz, or use "omega" in rad/s instead
frequency = 5.0
}
Rotation Axis Definition
By default the axis is given directly by axis and center (axis definition = center_axis). Alternatively, you may define the axis by two points using axis definition = tail_head: the axis line runs from axis tail to axis head, with axis tail used as the pivot. Provide either axis/center or axis tail/axis head, not both.
rigidbodymotion_1 {
domains = [1]
type = rotation
axis definition = tail_head
# Pivot / start of the axis line
axis tail = [0,0,0]
# End of the axis line (direction = head - tail)
axis head = [0,1,0]
angular speed = 10.0
}
Constant Translation
A constant translation moves the domain at a fixed velocity vector.
rigidbodymotion_1 {
domains = [1]
type = translation
# Constant velocity vector in m/s
translation velocity = [0.5,0,0]
}
Sinusoidal Translation
A sinusoidal translation oscillates the domain about its initial position.
rigidbodymotion_1 {
domains = [1]
type = translation
kind = sinusoidal
# Per-axis peak displacement in meters
amplitude = [0,0.1,0]
# Oscillation rate: frequency in Hz, or use "omega" in rad/s instead
frequency = 2.0
}
Motion Window
Any motion block can be limited to a time window. Before the window starts the domain holds its starting pose; after the window ends it holds the pose reached at the end. The phase of a sinusoidal motion is measured from the window start, so the oscillation always starts at zero. Without these keys the motion runs from t = 0 with no end.
rigidbodymotion_1 {
domains = [1]
type = rotation
kind = sinusoidal
axis = [0,1,0]
center = [0.25,0,0]
amplitude = 2.0
frequency = 10.0
# Hold still until t = 0.05 s (e.g. to develop the steady flow), then start oscillating
motion start time = 0.05
# Stop after 3 periods and hold that pose; omit for no end
motion end time = 0.35
}
The window can also be given in convective time units, motion start ctu and motion end ctu, when the reference
time is set. Use seconds or CTU for each end, not both.
Initial Attitude
If the body is meshed already turned, initial attitude tells the loads how it sits in the grid. The mesh and the
motion are not changed. With alpha = 0 in the reference conditions, the aerofoil below, meshed 4° nose up, reports
alpha_<group> = 4 plus the pitch motion, and the same body-axis and wind-axis loads as the unturned aerofoil at
alpha = 4.
rigidbodymotion_1 {
domains = [1]
type = rotation
kind = sinusoidal
axis = [0,1,0]
center = [0.25,0,0]
amplitude = 2.0
frequency = 10.0
# [roll, pitch, yaw] in degrees: meshed 4 deg nose up; optional, default [0, 0, 0]
initial attitude = [0, 4, 0]
}
Rotating Non-Inertial Frame
With noninertial = true, a rotation does not move the mesh: the domain is solved in a frame turning with it
(multiple reference frame, MRF). Velocities stay absolute (laboratory frame), the convective flux is taken
relative to the frame (Ω × r), and the momentum equation gets one source, −ρ Ω × u. Use it for a problem that is
steady in the rotating frame, for example an isolated rotor in axial flow.
rigidbodymotion_1 {
domains = [1]
type = rotation
axis = [1,0,0]
center = [0,0,0]
# rad/s (= 2000 rpm; or use "rpm")
angular speed = 209.44
# Solve in the rotating frame; the mesh does not move
noninertial = true
}
- Only
type = rotation; anything else stops with an error. Bothkind = constantandkind = sinusoidal(a frame oscillating about its axis) work, with or without a motion window: the absolute-velocity form needs no further source for a time-varying rate. - The far field is fixed in grid axes, so the freestream should be along the frame axis; otherwise a warning says the run models a freestream turning with the frame.
initial attitudeis ignored for a frame (warning). Loads groups in a frame use the grid axes as body axes; see Loads on moving bodies.
The parameters are:
- domains: A list of domain IDs that will be subjected to this motion. Each domain can only be assigned to one motion group.
zone: The name of a grid zone to move, as an alternative todomains(give one or the other, not both). The name is resolved to its domain once the grid is read.
type: The type of motion,rotationortranslation.kind: Kind of motion,constantorsinusoidal.axis definition: How the rotation axis is specified,center_axis(default) ortail_head(rotation only).axis: A 3D vector defining the axis of rotation (center_axismode). This vector will be normalized by the solver.center: A 3D vector specifying the center point of the rotation in meters (center_axismode).axis tail,axis head: Two 3D points in meters defining the rotation axis line (tail_headmode).angular speed: The speed of rotation in radians per second (for constant speed rotation).rpm: The constant rotation speed in revolutions per minute (signed), as an alternative toangular speed. Exactly one of the two must be given for a constant rotation.amplitude: For sinusoidal rotation, the peak angular amplitude in degrees. For sinusoidal translation, a 3D vector of peak displacements in meters.frequency: The oscillation frequency in Hz (for sinusoidal motion).omega: The oscillation angular frequency in radians per second, as an alternative tofrequency. Exactly one offrequencyoromegamust be given for a sinusoidal motion.translation velocity: A 3D velocity vector in m/s (for constant translation).motion start time,motion end time: Optional time window of the motion in seconds (ormotion start ctu,motion end ctuin convective time units). See motion window.noninertial:trueto solve this rotation as a rotating reference frame instead of moving the mesh (defaultfalse). See rotating non-inertial frame.initial attitude:[roll, pitch, yaw]in degrees (default[0, 0, 0]): how the body sits in the grid as meshed. It affects the loads only — the mesh is not moved and the motion is unchanged. The body axes of every loads group carried by this motion are the grid axes turned by yaw about z, then pitch about y, then roll about x, the same way the freestream is built fromalphaandbeta. A model meshed 4° nose up, run atalpha = 0, therefore reportsalpha_<group> = 4and the same body-axis and wind-axis loads as the unturned model atalpha = 4. The motion then carries the body from this attitude, so a sinusoidal pitch oscillates about the meshed angle. Ignored (with a warning) for a non-inertial frame and for a block that moves no mesh. See Loads on moving bodies.
For translation, the user-defined moment center follows the path of the moving body, ensuring that moment integration remains consistent with the body's current position.
Warning
Prescribed translation and rotation (both constant and sinusoidal) are supported. Combined translation/rotation motions, as well as general six-degree-of-freedom (6-DOF) free-flight simulations, are currently undergoing testing.
In progress
This documentation will be published with an upcoming release.
Output and Probes
All the output settings are organized under output {} section.
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).
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 |
If running the implicit solver, there are a few additional monitor variables available:
Note
For residual norms ICOMP index below refers to the equation number:
0: Continuity, 1-2-3: Momentum, 4: Energy, >=5: Species mass fractions
For DQ norms, ICOMP index below refers to the primitive variables:
0: Pressure, 1-2-3: U-V-W velocity components, 4: Temperature, >=5: Species mass fractions
| Variable | Description |
|---|---|
| l0resICOMP | L0 Residual norm (absolute) |
| l2resICOMP | L2 Residual norm (absolute) |
| l0resrICOMP | L0 Residual norm (normalized by first step value) |
| l2resrICOMP | L2 Residual norm (normalized by first step value) |
| l0dqICOMP | L0 Primitive variable change norm (absolute) |
| l2dqICOMP | L2 Primitive variable change norm (absolute) |
| l0dqrICOMP | L0 Primitive variable change norm (normalized by first step value) |
| l2dqrICOMP | L2 Primitive variable change norm (normalized by first step value) |
| l0turbres | L0 Residual norm for turbulence equation (absolute) |
| l2turbres | L2 Residual norm for turbulence equation (absolute) |
| l0turbresr | L0 Residual norm for turbulence equation (normalized by first step value) |
| l2turbresr | L2 Residual norm for turbulence equation (normalized by first step value) |
| lambdap | Under-relaxation factor for Navier-Stokes equations |
| lambdatur | Under-relaxation factor for turbulence equation |
| lambdals | Under-relaxation factor for line search |
| linits | Number of linear solver (GMRES) iterations for Navier-Stokes equations |
| linres | Linear solver (GMRES) residual for Navier-Stokes equations |
| linitsturb | Number of linear solver (GMRES) iterations for turbulence equation |
| linresturb | Linear solver (GMRES) residual for turbulence equation |
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]
}
}
Loads on moving bodies
In 3D, a loads group on a body moved by a rigid body motion block (rotation or translation, constant or sinusoidal) or lying in a non-inertial frame also reports its loads in the body's own axes and in its wind axes. The body of a group is the motion of the zones its walls belong to. A group holding walls of more than one body is reported with a warning; its body-axis loads stay in the reference frame and its wind axes come from the reference freestream. Groups on fixed walls keep the laboratory axes and write only the standard columns. In 2D the loads stay in laboratory axes.
- Body axes: the grid axes at the starting pose (x, y, z of the mesh as read), turned by the motion block's
initial attitudeif given, and then carried by the motion. In a non-inertial frame the grid axes are the body axes. - Moment centre: the group's
moment centeris a body-fixed point. The laboratory moments (Mx_<group>…) are taken about it as given, moved with a translation. The body-axis and wind-axis moments are taken about the point as the body has carried it. - Relative wind: the reference freestream (
alpha,betaand the reference velocity) minus the body's velocity at the moment centre (translation velocity plus Ω × r; in a non-inertial frame, the frame's Ω × r). - Wind axes: D along the relative wind, S the body y axis less its D part, L = D × S.
alpha_<group>andbeta_<group>are the angles of the relative wind in body axes, in degrees. With no relative wind, or the wind along the body y axis, the referencealphaandbetaare used.
| Monitor column | Meaning |
|---|---|
FL_<group>, FD_<group>, FS_<group> (and _inv_, _visc_) |
lift, drag and side force in the group's wind axes |
Fxb_<group>, Fyb_<group>, Fzb_<group> |
force in body axes |
Mxb_<group>, Myb_<group>, Mzb_<group> |
moment in body axes, about the carried moment centre |
Mroll_w_<group>, Mpitch_w_<group>, Myaw_w_<group> |
moment about D, S and L |
alpha_<group>, beta_<group> |
angles of the relative wind in body axes (degrees) |
C…b_<group>, CM…b_<group>, CMroll_w_<group> … |
the same, normalized, when normalize = true |
The body-axis and wind-axis moments are the same moment vector about the same point, split along different axes,
so their magnitudes agree. At beta_<group> = 0, S is the body y axis: Mpitch_w equals Myb, while roll and yaw
mix by the angle α (Mroll_w = Mxb cos α + Mzb sin α, Myaw_w = −Mxb sin α + Mzb cos α). The laboratory
moments Mx_<group> … are taken about the moment centre as given, so for a rotating body they also differ from the
body-axis moments by the shift of that point. D points downstream and L = D × S, so Mroll_w and Myaw_w have the
opposite sign to the flight-mechanics wind axes (x into the wind, z down); pitch has the same sign.
The columns below the standard ones are written only for groups on a moving body or in a non-inertial frame. A fixed
group's body axes are the laboratory axes, so its body-axis loads are Fx_<group> … Mz_<group>, and its wind axes come
from the reference free stream: the reference alpha and beta, or, when the reference conditions give phi or a
velocity vector, the angles of that velocity vector. Its FL, FD, FS follow that direction, and a wind-axis
moment is the laboratory moment projected on the axis, e.g. the roll moment about D = (cos α cos β, −sin β, sin α cos β):
Mroll_w = Mx cos α cos β − My sin β + Mz sin α cos β.
Two consequences, both checked to round-off: a model meshed turned in the grid and run with initial attitude set
to that turn reports the same loads as the unturned model at the matching alpha/beta; a body translating at a
constant velocity reports the same loads as the fixed body in the freestream of the matching relative wind. A
plunging aerofoil therefore reports the plunge-induced angle of attack in alpha_<group>.
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
}
}
Output file names
Snapshot files carry the output step in their name (the sync step when sync steps per ctu or sync dt is set),
and a link named after the same stem with Latest in place of the step points to the newest one. Probes are
numbered as their input sections are: surface probe_3 writes 003.*, line probe_12 writes 012.*, and the
lines of a multiline line probe file are numbered from 1 after the probe number.
| Output | Files | Latest link |
|---|---|---|
| Volume | volume/Unst.vol.<step>.cgns, subsets volume/sub<NN>.Unst.vol.<step>.cgns |
Unst.volLatest.cgns, sub<NN>.Unst.volLatest.cgns |
| BC surface | surface/Unst.surf.<step>.cgns |
surface/Unst.surfLatest.cgns |
| Iso-surfaces | isosurface/surf<NN>_<contour>[_isoVal<value>]_Color<fields>_<step>.<format> |
isosurface/surf<NN>_<contour>[_isoVal<value>]_Color<fields>Latest.<format> |
| Surface probes | surf_probe/<NNN>.Unst.<step>.<format> |
surf_probe/<NNN>.UnstLatest.<format> |
| Integrated quantities | surf_probe/<NNN>.mass_flux.dat, one history per probe |
|
| Line probes | line_probe/[<name>.]<NNN>[_<MMM>].Unst.<step>.line; binary: line_probe/[<name>.]<NNN>.Unst.line, one file per probe |
line_probe/[<name>.]<NNN>[_<MMM>].UnstLatest.line |
| Point probes | point_output/<NNN>.points.<variable>.dat, one history per variable |
|
| Restart | restart/Unst_restart.<step>.hdf5 |
restart/Unst_restartLatest.hdf5 |
The histories (point probe tables, integrated quantities) hold a row per output; a restarted run drops the rows from its first output step on before appending, so each output appears once.
Volume
Volume output writes the selected flow variables to a CGNS solution file at each output step, linked to a grid file that holds the grid.
The cells, faces and nodes of the volume and of its subsets (box and plane) are numbered in the order of the
grid's global ids, so the files hold the same grid and solution on any number of ranks. Each solution file
<prefix>.<step>.cgns (Unst.vol or sub<NN>.Unst.vol) links to a grid file <prefix>.meshLink.<step>.cgns, named
after the step of the first solution that uses it. A run links its solutions to the latest earlier grid file when
that file holds the same grid, recognized by a fingerprint of its contents stored in it, as on a restart on any number
of ranks; otherwise it writes the grid at its first output. A subset cutting moving zones writes a grid with every
output. The grid files hold the grid as the solver uses it, moved by the grid's transform inputs, and leave out
the nodes of the grid file that no face uses.
output {
volume {
# Whether to write out an volume file at the start of simulations (initial conditions)
write initial = false
# Currently only cgns format is supported
format = cgns # default
# Interval of output (unsteady: time step, steady: pseudo-step)
interval = 10000
# List of variables to output
variables = [q,qstats,density,mach,problem,sponge,upwind,cellmask,trip]
}
}
In addition to the full volume output, you can also output a subset of the domain. Currently, two different types of subset are supported. They are described below along with the supporting options required:
box: Output all the cells inside a box defined by box vertices 'lo' and 'hi'. The 'lo' parameter defines the minimum x,y,z coordinates of the box, while 'hi' defines the maximum x,y,z coordinates.- On unstructured grids with zones that move with a rigid body motion, the box stays fixed in the lab: the cells are selected again at every output at their lab positions and written there, so every output of the subset writes its own grid file.
plane: Output the whole cells a plane passes through. The plane is defined bypoint, any point on the plane, andnormal, the direction perpendicular to the plane (it does not need to be normalized), as for surface probe and iso-surface cut planes.origin, the name of earlier releases forpoint, is still read with a deprecation warning. A cell is written when it has nodes on both sides of the plane, a node on the plane counting as the side opposite to the normal, so a plane lying on cell faces writes one layer of cells and a cell the plane only touches at a node or an edge is not written. A node counts as on the plane when it lies within the roundoff of its coordinates of it (2^16 units of roundoff, about 7e-12 of its coordinates' magnitude), as nodes a mesher meant to put on the plane do; the side of each node is decided exactly.cliploandcliphi(optional) keep only the cells whose centroid lies in that box.include zones(optional) restricts the cut to the listed grid zones, by CGNS zone name or 1-based index.- In a zone that moves with a rigid body motion, the plane stays fixed in the lab: the cells are selected again at every output and written at their lab positions, so every output of the subset writes its own grid file.
Where an iso-surface cutplane slices the cells into polygons and interpolates the solution onto them, a plane subset keeps the cells whole, with exactly the values the solver holds in each cell: use it to inspect mesh resolution, the tile and partition structure, or a stencil or a limiter cell by cell. ParaView calls this selection a crinkle slice and applies the same rule. To see the cells, open the file with the CGNS reader and show it as Surface With Edges.
volume {
# Whether to write out a volume file at the start of simulations (initial conditions)
write initial = false
# Currently only cgns format is supported
format = cgns # default
# Interval of output (unsteady: time step or sync step, steady: pseudo-step)
interval = 10000
# List of variables to output
variables = [q,qstats,density,mach,problem,sponge,upwind,cellmask,trip]
subset_1 {
type = box
lo = [0.1, 0, 0.1] # Minimum coordinates [x_min, y_min, z_min]
hi = [1.0, 0.5, 1.0] # Maximum coordinates [x_max, y_max, z_max]
interval = 500 # Output interval specific to this subset
}
subset_2 {
type = plane
normal = [0, 0.5, 0.5] # Direction vector perpendicular to the plane
point = [1.0, 0., 0.1] # A point located on the plane
cliplo = [-2.0, -0.5, -1.0] # (Optional) For clipping plane: Minimum coordinates [x_min, y_min, z_min]
cliphi = [2.0, 0.5, 1.0] # (Optional) For clipping plane: Maximum coordinates [x_max, y_max, z_max]
interval = 100 # Output interval specific to this subset
}
}
The variables, write initial and format inputs are shared across all subsets. Each subset can have its own output interval that differs from the main volume interval. A subset's files are named after the volume's with sub<NN>. in front, NN the subset number: volume/sub01.Unst.vol.<step>.cgns on unstructured grids.
Tip
For large simulations, using subsets can significantly reduce storage requirements and post-processing time.
Full list of volume output variable options:
| Variable | Description |
|---|---|
| pressure | |
| velocity | All velocity components |
| temperature | |
| massfractions | Species mass fractions, only supported for multi-species |
| q | All of the above primitive flow variables |
| qstats | Time average and statistics of the flow field |
| density | |
| viscosity | laminar dynamic viscosity |
| nut | SA turbulence model working variable |
| eddyviscosity (or mut) | |
| mach | Mach number |
| umag | Velocity magnitude |
| vorticity | VorticityX, VorticityY, VorticityZ (or xvorticity, yvorticity, zvorticity for one) |
| vortmag | VortMag, the vorticity magnitude |
| qcriterion | QCriterion, 0.5 (|W|² - |S|²) of the velocity gradient |
| lambda2 | Lambda2, the middle eigenvalue of S² + W², negative in a vortex core |
| densitygradmag | DensityGradMag, the density gradient magnitude |
| distancefunction | Distance from walls |
| limiter | MUSCL slope limiter for each flow variable |
| upwind | Upwind/central blending sensor field, 0: central, 1: upwind |
| volume | Volume of each cell |
| dx | Cell size, the cube root of the cell volume |
| centroid | All 3 centroid coordinates for each cell |
| lsmooth | Smoothed length scale for each cell |
| residuals | All residuals (implicit only) |
| massresidual | Continuity equation residual implicit only |
| xmomresidual | X-momentum residual (implicit only) |
| ymomresidual | Y-momentum residual (implicit only) |
| zmomresidual | Z-momentum residual (implicit only) |
| energyresidual | Energy equation residual (implicit only) |
| nutresidual | SA turbulence model residual |
| dtau | Pseudo-time step size |
| sponge | Binary field indicating where sponging is active |
| trip | Binary field indicating where trips are active |
| thin | Binary field indicating whether a cell is marked as thin |
| problem | Binary field indicating whether a cell is marked as problem |
| problem_gg | Binary field indicating whether a cell failed Green-Gauss check |
| id | partition id for each cell |
| processor | rank owning each cell |
| tiles | tile id for each cell |
| domain | domain id for each cell |
| motion | motion id for each cell (-1: stationary) |
| cellmask | Cell bit mask |
Surface
Surface output writes one CGNS file per output, surface/Unst.surf.<step>.cgns, with a zone per boundary condition,
BC_<n>:<name>, holding its faces as polygons and the selected variables at the faces in solution solution;
include bcs limits the zones to the listed BCs (numbered from 1). A file holds the state of the step in its name,
and the faces of moving zones are where they are at that step. The files are gathered on rotating ranks and buffered
like the surface probes, written at the next flush, or with doparallel = true written in parallel by every rank (see
Buffered surface outputs); output buffer interval surf = 0 writes each gathered one at once.
With split grid and solution = true, the geometry goes in a grid file written at the first output of the run,
Unst.surf.meshLink.<step>.cgns after the step of that output, and each solution file links to the grid file of its
run. The linked geometry is that of the run's first output, also for
moving zones.
output {
surface {
# Whether to write out an initial file at the start of simulations (initial conditions)
write initial = false
# Interval of output (unsteady: time step, steady: pseudo-step)
interval = 10000
# List of variables to output
variables = [q,qstats,density,mach,cf,yplus]
# Link the solution files to a grid file written once per run instead of holding the geometry
split grid and solution = false
# The only format of the unstructured surface output
format = cgns
}
}
BC Statistics Output
At every surface output step, area-averaged boundary condition statistics are appended to surface/bc_stats.iter, a continuous binary file in the same format as monitor/unst.data.iter. A human-readable mapping of BC indices to names is written once to surface/bc_name_map.txt.
The following quantities are recorded per boundary condition (prefixed BC1_, BC2_, etc.):
| Column | Description |
|---|---|
step, time |
Simulation step and time |
BCN_area |
Total boundary face area (m²) |
BCN_pressure |
Area-averaged pressure (Pa) |
BCN_u, BCN_v, BCN_w |
Area-averaged velocity components (m/s) |
BCN_temp |
Area-averaged temperature (K) |
BCN_y0, BCN_y1, ... |
Area-averaged species mass fractions (multi-species only) |
BCN_mach |
Area-averaged Mach number |
BCN_mdot |
Area-averaged mass flux (kg/(m²·s)) |
BCN_tauw_x/y/z |
Area-averaged wall shear stress components (Pa) |
BCN_heatflux |
Area-averaged heat flux (W/m²) |
BCN_hflux_min, BCN_hflux_max |
Min/max heat flux over the boundary (W/m²) |
When mach-driven pressure BCs are active, per-BC pressure history is written to surface/mach_driven_pressure_BCN.iter with columns step, mach_ave, pressure_ave.
Both bc_stats.iter and mach_driven_pressure_BCN.iter support restart continuation: history is automatically preserved across restart segments.
Full list of surface output variable options:
| Variable | Description |
|---|---|
| pressure | |
| velocity | All velocity components |
| temperature | |
| massfractions | Species mass fractions, only supported for multi-species |
| q | All of the above primitive flow variables |
| density | |
| mach | Mach number |
| viscosity | laminar dynamic viscosity |
| conductivity | thermal conductivity |
| specificheat | Cp |
| dtau | Pseudo-time step size |
| mdot | Mass flux (kg/(m^2.s), positive: inflow) |
| qdot | Heat flux (W/m^2, positive: inflow) |
| tauw | Wall shear stress (vector components) |
| cf | Surface skin friction coefficient (vector components) |
| pcoef | Surface pressure coefficient |
| yplus | Wall yplus value (zero on boundaries other than walls) |
| nut | SA turbulence model working variable |
| facemask | Face bit mask |
| cellmask | Cell bit mask |
| qavg | Time-averaged primitive flow variables |
| qstats | Time average and statistics of the flow field |
| tauwavg | Time average of wall shear stress (vector components) |
| yplusavg | Time average of wall yplus value (zero off walls) |
| turbulence | Turbulence sensor |
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.
Note
LAVA unstructured writes iso-surfaces as cgns (the default), vtk or vtp, gathered on one rank and buffered; doparallel = true writes a cgns iso-surface in parallel by every rank (see Buffered surface outputs). The errormetric contour and color field are not supported.
Note
An iso-surface file holds the solution of the step in its name: _000000000 is the initial condition.
Note
Iso-surfaces and cut planes are extracted on CPU runs as well as on GPU runs. On CPU runs the tiles are tetrahedralized once at startup and the surfaces are extracted with marching tetrahedra.
Surface Probe
Surface probes sample the flow on a cut plane or on a triangulated surface read from a file. Each probe is
written to its own file in the surf_probe directory at its interval, named as in
Output file names. Every file holds its grid and its solution.
By default, surface probes sample the primitive flow variables (p, u, v, w, T, Y) and, in a turbulent run, the
turbulence variable; variables selects others (see Probe variables). Every probe writes an InOut variable: 1 where the value was found
inside the mesh, 0 for a point outside it, which takes the value at its nearest boundary point. On grids with moving zones, see
Probes and moving zones. The volume time averages of the run are added with
output qstats = true.
Cut planes
A cut plane is given by a point on it, point, and its normal, normal, in any direction and of any
length; numplanes evenly spaced parallel planes run from point to pointhi. Iso-surface cut planes and
volume plane subsets take the same point and normal. 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.
output {
surface probe_1 {
point = [0, 0.1, 0] # a point on the plane
normal = [0, 1, 0] # the plane normal
interval = 10
}
surface probe_2 {
point = [0.5, 0.5, 0.5]
normal = [1, 1, 1] # any direction, of any length
interval = 10
}
surface probe_3 {
point = [0, 0, 0.1]
pointhi = [0, 0, 0.9]
numplanes = 3 # planes evenly spaced from point to pointhi
normal = [0, 0, 1]
interval = 10
}
surface probe_4 {
point = [0, 0.1, 0]
normal = [0, 1, 0]
crinkle = true # the mesh faces separating the two sides
interval = 10
}
}
The plane cuts every cell it passes through into a polygon, so the polygons tile the plane's section of
the mesh with no gaps, across cells and ranks. A node on the plane counts as below it: a plane
lying on cell faces gives one polygon per face, from the cells above, and cells the plane only touches
at a node or an edge give none. A node within the roundoff of its coordinates of the plane (about 7e-12 of
their magnitude) counts as on it, so a plane through a layer of faces whose nodes the mesher stored up to
roundoff off the plane, such as a symmetry plane of a Voronoi lattice, still gives one polygon per face. A
plane through a moving zone is cut again at every output, at the zone's position at that time. The polygons of a probe with several planes are tagged by plane index in
the plane field.
With crinkle = true, the probe writes mesh faces in place of the polygons: the faces between a cut cell
and a cell entirely below the plane (every node below or on it), oriented toward the positive side. They
form a staircase within one cell below the plane, reaching the domain boundary, with no new geometry; a
plane on cell faces gives those faces.
The values are interpolated from the cell the plane cuts and its neighbours, by a least-squares fit that
is exact for a linear field: with the default data location = face at each polygon's centroid, and
with data location = node at the vertices. Crinkle faces are interpolated at their centroids from
their cut cell.
Note
Each cut cell gives one polygon per closed loop of its section. Faces whose edges do not match (a hanging node listed by one face but not by its neighbour) leave loose ends, which are joined; the run reports how many cells needed it. A cell whose section has a hole is written as the outer polygon and the hole as separate polygons, the hole oriented against the plane normal, so the hole's area is subtracted in the integrated quantities but shows filled in a viewer.
Surfaces read from a file
output {
surface probe_5 {
# Specify file, the format is determined by extension
# Supported formats: tri, fro, cgns, vtk, p3d
file = probe_triangulation.cgns
interval = 100 # Interval of output
# Where to sample data, either face center or nodes (vertices)
data location = face # default, options: face, node
# Optionally transform the probe triangulation. The operations are applied in the order: 1. rotation, 2. scale, 3. translate
rotate = [90.,0.,0.]
scale = [2.,1.,1.]
translate = [1., 1. ,1.]
format = cgns
variables = [q, problem, sponge, upwind, limiter] # the flow and the cell status
output integrated = true # Output integrated quantities like fluxes through the surface probe
}
}
The values are interpolated at the face centers or at the nodes. The component number of each triangle
is written in the component field.
Formats
The format option selects cgns or vtk for any probe; doparallel = true writes a cgns probe in parallel by
every rank instead of gathered (see Buffered surface outputs). Surfaces read from a file can also be written
as fwh, a specialized format for high frequency sampling of acoustic surfaces that holds only the face
values of p, u, v, w and T without the grid (it needs data location = face), or as p3d, a Plot3D
function file of the node values of p, u, v, w and T on the zones of a p3d input (it needs
data location = node).
Integrated quantities
Integrated quantities are requested by setting output integrated = true. Each probe keeps one history,
surf_probe/<probe index>.mass_flux.dat, with a row per output for every component of a surface read from a
file, or every plane of a cut plane probe. Its first line, starting with #, names the columns:
| Column | Quantity |
|---|---|
| 1 | Output step (the sync step when sync steps per ctu or sync dt is set) |
| 2 | Time |
| 3 | Component number, or plane index |
| 4 | Area |
| 5 | Mass flux |
| 6, 7 | Mass flux weighted total pressure and total temperature |
| 8 | Gross mass flux, the sum of the absolute mass flux of every face |
| 9, 10 | Mass flux weighted and area weighted Mach number |
| 11 | Area weighted pressure |
| 12-14 | Mass flux weighted velocity components |
| 15-17 | Area weighted velocity components |
A restarted run drops the rows from its first output step on and appends, so the history holds each output once.
The gross mass flux and the area weighted averages stay meaningful when the net mass flux is near zero. They are summed over the faces from the values
interpolated at the face centers, so they need data location = face, the default. The area of a cut
plane is its section's area along the plane normal (for crinkle faces, their area projected on it), and
the mass flux is positive along the normal.
Moving surfaces and rotating frames
The mass flux is the flux through the surface as it moves: at each face, the density times the velocity relative to the face, ρ (u − w) · A, where w is the velocity of the face at its center.
- A surface at rest in the lab has w = 0, and the mass flux is ρ u · A.
- A surface fixed in a moving frame (
frame = motion_Non a moving mesh, see Probes and moving zones) moves with that frame: w is the frame's velocity, Ω × r for a rotation and the translation velocity for a translation. - A face in the zones of a rotating non-inertial frame (
noninertial = true) turns with that frame, w = Ω × r, whatever frame the surface was given in. The mesh of such a frame does not move: its coordinates turn with the frame, so a surface placed in them turns too. A face in a stationary zone next to it, as on a plane crossing both, stays at rest.
This is the mass flux the solver conserves: its convective flux through every mesh face uses the same relative velocity, so the mass flux through a closed surface balances in a flow that is steady in the frame. Taken with the absolute velocity instead, the flux through a closed surface would not balance wherever the density varies, since ∮ ρ (Ω × r) · dA = ∫ (Ω × r) · ∇ρ dV. It also makes the result independent of how the rotation is modelled: a rotor run as a non-inertial frame, and the same rotor run on a rotating mesh with the surface in its frame, give the same mass flux.
The weighted averages take this mass flux as their weight and average the absolute flow quantities: the total pressure, total temperature, Mach number and velocity are those of the flow in the lab, not relative to the surface. In the zones of a non-inertial frame, the velocity components are along the frame's axes, which turn with it.
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];
}
Warning
By default, each line probe output is written to an ASCII formatted file with one file per time step. This can quickly generate numerous files, potentially causing file system issues.
To mitigate this, a binary file format can be used by setting write binary to true. This creates a single binary file per line probe that contains data for all timesteps, significantly reducing the number of files created during your simulation.
For visualization and analysis, you can use the plotLineProbe.py tool, which is specifically designed to read and process these binary files.
When restarting simulations, the code handles existing binary line probe files:
- It checks if the current line probe definition matches the existing file
- If definitions match and restart time step is consistent, it simply appends new data
- If definitions match but restart time step differs, it creates a backup of the original file and prepends existing data up to the restart point in a new file
- If definitions don't match, it creates a copy of the existing file and starts a new file with the current definition
This robust handling ensures data integrity across simulation restarts while preserving your previous results.
Averaged quantities can be requested by setting the option output qstats to true.
output {
line probe_1 {
...
output qstats = true # Output averaged quantities sampled on to the probe
}
}
Wall-Normal BL Probe
Line probes support a wall normal mode for boundary layer profiling. Instead of specifying a start/end pair, you supply one or more seed coordinates; the solver projects each seed onto the nearest no-slip or wall-function boundary face and grows a wall-normal ray of sample points outward to a specified height.
Seed specification — a single seed can be given inline with start; multiple seeds are read from a plain ASCII file (one x y z per line):
output {
line probe_2 {
wall normal = true
file = seeds.dat # one "x y z" per line; omit to use start = [x,y,z]
height = 0.1 # outer extent of each ray in solver length units
interval = 500
output qstats = true
name = bl_probe
}
}
Ray discretization — choose one of two modes:
Uniform — evenly spaced points including the foot at h = 0:
Geometric — first cell height ds0, each subsequent step multiplied by growth rate (default 1.2) until height is reached; the final point is snapped to height. The actual number of points is determined automatically.
Optional keys:
| Key | Type | Default | Description |
|---|---|---|---|
wall bc names |
string list | all wall BCs | Restrict BVH projection to BCs matching these names |
flip normal |
bool | false | Flip the wall-outward normal direction |
output qstats |
bool | false | Include time-averaged quantities (requires volume time averaging) |
name |
string | line_probeN |
Base name for the output file |
Output file format:
BL probe files are written in Tecplot ASCII multi-zone format. One zone is created per seed; the zone title carries the 0-based seed index (T="seed_0", T="seed_1", …). Each zone header stores the projected foot coordinates as AUXDATA:
| AUXDATA key | Description |
|---|---|
x_foot, y_foot, z_foot |
Projected wall face centroid coordinates |
Data columns (one row per sample point):
nt time x y z [variables] InOut height tau_w_inst rho_w_inst mu_w_inst [tau_w_avg rho_w_avg mu_w_avg]
height— wall-normal distance from the foot (0 at the projected wall face centroid)tau_w_inst/tau_w_avg— instantaneous and time-averaged wall shear stress magnitude at the foot (constant within a zone)rho_w_inst/rho_w_avg— density at the foot, instantaneous and time-averagedmu_w_inst/mu_w_avg— dynamic viscosity at the foot, instantaneous and time-averaged- Avg columns (
tau_w_avg,rho_w_avg,mu_w_avg) are present only whenoutput qstats = true
On the first output step, two Tecplot equation files are written to the line_probe/ directory:
bl_inner_scale_inst.eqn— computesu_tau,nu_w,y+,u+,v+,w+from the instantaneous foot columnsbl_inner_scale_avg.eqn— same using_avgcolumns; also adds<uu>+through<vw>+from qstats
Load via Data → Alter → Specify Equations → Load in Tecplot.
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.
Alternatively, points can be output to the iter file and be plotted using plotHist.py tool by:
By default, point probes sample the primitive flow variables(p,u,v,w,T,Y_i), and variables selects others
(see Probe variables), along with an InOut variable indicating whether the query point was detected inside the fluid domain or out. A point outside the domain takes the value interpolated at its nearest boundary point, from the boundary cell and its BC ghost; line probes do the same. Optionally, you can output the Mach number as:
Averaged quantities can be requested by setting the option output qstats to true.
output {
point probe_1 {
...
output qstats = true # Output averaged quantities sampled on to the probe
}
}
Probe variables
Point, line and surface probes write the variables their variables list names, in its order, followed by
InOut unless the list places inout elsewhere:
| Entry | Written as | Source |
|---|---|---|
q (default) |
Pressure, UVel, VVel, WVel, Temperature, MassFraction_\<species> | interpolated |
pressure, velocity, uvelocity, vvelocity, wvelocity, temperature, massfractions |
the corresponding part of q |
interpolated |
nut |
Nut (Spalart-Allmaras) | interpolated |
qstats, qavg, pavg, ..., reynoldsstress, tke, totalpressureavg |
the volume time averages: pavg, uavg, ... | interpolated |
density, rho |
Density | from the interpolated state |
mach, machnumber |
Mach | from the interpolated state |
umag |
Umag | from the interpolated state |
viscosity, mu |
Viscosity | from the interpolated state |
conductivity, lambda |
Conductivity | from the interpolated state |
specificheat |
SpecificHeat (at constant pressure) | from the interpolated state |
soundspeed, sound |
SoundSpeed | from the interpolated state |
totalpressure, ptot |
TotalPressure (isentropic) | from the interpolated state |
problem, sponge |
problem, sponge: 1 in a problem cell or a sponge zone, 0 elsewhere | interpolated |
upwind |
upwind: the upwind blend weight, averaged over the cell's faces | interpolated |
limiter |
limiter_0, ..., limiter_\<NUMQ-1>: the limiter of each primitive variable, averaged over the cell's faces | interpolated |
vorticity, xvorticity, yvorticity, zvorticity |
VorticityX, VorticityY, VorticityZ | interpolated gradient field |
vortmag |
VortMag | interpolated gradient field |
qcriterion |
QCriterion | interpolated gradient field |
lambda2 |
Lambda2 | interpolated gradient field |
densitygradmag |
DensityGradMag | interpolated gradient field |
volume |
volume: the volume of the cell holding the point | the cell's |
dx |
DX: the size of the cell holding the point, the cube root of its volume | the cell's |
inout |
InOut | 1 inside the mesh, 0 outside |
output {
point probe_1 {
file = points.dat
variables = [pressure, density, mach] # writes Pressure, Density, Mach and InOut
}
}
The derived variables are evaluated from the interpolated pressure, velocity, temperature and mass fractions,
which are first kept within their bounds; for a field that varies linearly, the interpolated state is exact.
The time averages are those of the volume averaging, so they need a time averaging block; they are zero
until the averaging starts. Any other entry stops the run. The file and column names are the volume output's
(Mach, InOut, Nut, MassFraction_<species>). Binary point probe files (.q) hold the primitive
variables, and their .qstats companions the time averages, whatever the list.
A surface probe whose files feed a distributed boundary condition must hold the primitive variables and then the
turbulence variable, in that order, which its default list does; an explicit list has to start with q, nut.
The gradient fields (vorticity, vortmag, qcriterion, lambda2, densitygradmag) are evaluated in each cell
from its gradient stencil, the one the solver reconstructs with, in the laboratory frame: the vorticity components
are those of the lab axes in moving zones too. They are computed only at the steps an output lists them, and only
the fields listed; probes interpolate the cell values. S and W are the symmetric and antisymmetric parts of the
velocity gradient. In a cell beside a wall the gradient includes the BC ghost state.
The cell status (problem, sponge, upwind, limiter) comes from the residual of the step the probe samples
in, at the state the probe samples. output cell status = true on a surface probe is deprecated: it adds the four
entries the list lacks, with a warning. The interpolated cell status is kept between 0 and 1, the range of every
cell's flags and blend weights, where the fit overshoots between cells.
volume and dx are those of the cell holding the point, as the volume output writes them, not interpolated; a point
outside the mesh takes the boundary cell its values come from, and a point on a face between two cells takes one
of them.
Probes and moving zones
On a grid with zones moved by a rigid body motion, every point, line and surface probe is fixed in a frame,
set with frame:
lab(the default): the probe stays where it is in the lab. A point inside a moving zone samples whichever cell of that zone passes over it at the output time.motion_N, or the name of a moving zone: the probe moves with that motion. Its coordinates are given in the zone's own (stored) coordinates, those of the grid file, and it samples the same place of the zone at every output. Points in other zones, which move relative to it, are located again at every output.
output {
point probe_1 {
file = rotor_points.dat
frame = motion_1 # the points turn with motion_1
}
line probe_1 {
start = [0.2, 0, 0]
end = [0.8, 0, 0]
number of points = 31 # frame = lab by default: the line stays in the lab
}
}
In the zones of a rotating non-inertial frame (noninertial = true), the mesh does not move and its coordinates
are those of the frame, which turn with it. A probe point there therefore stays at rest in that frame, whatever
frame it is given: a point cannot be held still in the lab in coordinates that turn. The run warns when a probe
given in another frame has points or faces in such zones; frame = motion_N, naming the non-inertial frame's
motion, states it and silences the warning. For the mass flux of surfaces in those zones, see
Moving surfaces and rotating frames.
Cost
A point is found once, at setup, in the zones at rest in its frame. A point covered by a zone that moves
relative to its frame is located again at every output: a search over that zone's cells, a new
interpolation stencil and a reduction over the ranks. The cost grows with the number of such points, not
with the grid, but a probe in the lab frame with many points inside moving zones costs more per output than
the same probe in the zones' own frame (motion_N), whose points are found once.
- Written coordinates: ASCII line probe files and surface probe files give each point at its lab position at the output time. Binary line probe files keep the coordinates given, in the probe's frame, in their header.
- Cut planes (
surface probewithpoint): a plane in a moving frame turns with it and is sliced again at every output. - Wall-normal line probes follow the zone of their wall, whatever its motion;
framedoes not apply to them. - Integrated quantities of a surface probe need a surface at rest in the lab.
relative velocity, which Cartesian probes accept, is not available for unstructured probes.
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 unstructured line and point probes, time-averaged statistics are interpolated from the
volume average, so qstats on a probe requires volume time averaging to be active.
Voronoi Mesh Generator
The LAVA Voronoi mesh generation software creates polyhedral-cell tessellations for two- and three-dimensional computational domains. It also supports the subtraction of complex geometries through a clipping process, enabling the generation of body-fitted unstructured meshes. The mesher is designed for both shared and distributed memory parallelism.
The software is centered on the concept of the Voronoi cell. Given a collection of seeds \(\{{\bf s}_1,{\bf s}_2,\dots,{\bf s}_n\}\subseteq{\mathbb R}^d\), a \(d\)-dimensional Voronoi cell \(V_k\) is a subset of \({\mathbb R}^d\) of the form \(V_k = \{{\bf x}\in{\mathbb R}^d \ :\ {\rm for\ every}\ j\neq k,\ \|{\bf x}-{\bf s}_k\|_2\leq \|{\bf x}-{\bf s}_j\|_2\}\). In other words, \(V_k\) is a convex polyhedral cell which encompasses the region where points are closer to its generating seed \(s_k\) than any other seed in the domain.
Voronoi meshes have intrinsic properties that make them desirable for solving discretized governing equations. For example, faces are orthogonal to the vector connecting the two generating seeds on either side of the face and are also located midway between the seed points on either side. For a detailed presentation of the Voronoi tessellation properties and the current mesher's algorithms, see Sousa et al.1.
Installation
Please refer to LAVA Voronoi Installation Guide for detailed instructions on acquiring and installing the Voronoi mesher.
Voronoi Mesher Inputs
Voronoi mesher uses a text-based input file in yaml format. In addition, geometry definition is provided to the mesher as a discrete triangulation.
Global parameters
We define the spacing between seeds in each refinement region relative to a reference length scale. This approach enables control of the overall mesh resolution and density through a single parameter. Once the user is satisfied with the point distribution at a given mesh density, generating coarser or finer meshes for a consistent refinement study becomes straightforward—simply adjust the reference length scale. For example, to use a reference length of 0.125, include the following in your input file:
Tip
If one sets the finest refinement region relative spacing to 1, then the reference length specified here will correspond to the length scale of the smallest cells, excluding potentially split cells, in the final mesh.
The Voronoi mesher can generate either a 2D Voronoi mesh with a single layer of cells or a fully 3D Voronoi mesh. In 3D mode, if the seed spacing in a given refinement region exceeds the thickness of the computational domain in one direction, only a single seed is placed at the domain's center along that axis. To toggle between 2D and 3D meshing, use the 2d input parameter. Moreover, the user can choose if the domain thickness in the \(z\)-axis is to remain with the prescribed z-extent (computational domain is defined as cube region) or if it will be made unitary by using the unitaryZmesh input. This parameter is only relevant when 2D mode is active.
#set to false for a 3d mesh.
2d: false
#controls dimensionality of domain width in 2D mode.
unitaryZmesh: true
Note
2D meshes are currently hardcoded to be aligned with the \(z\)-axis. If the user wants to build a 2D mesh of an airfoil, for example, the triangulation describing the surface shape needs to be aligned with the \(z\)-direction. The final mesh can be transformed, i.e. rotated, translated or scaled, before running the simulation in the unstructured solver.
Generating fully three-dimensional meshes can be computationally expensive. During the mesh design phase, users often need to iterate on refinement region layouts and seed densities. To streamline this process, the tool includes a 2d_plane_output option. This feature allows users to define an arbitrary plane, restrict seeding to a single cell layer normal to that plane, and produce a surface mesh that approximates a slice through the full 3D mesh. Additionally, this option can be used to generate planar triangulations whose density reflects that of the final mesh. These triangulations can be used for sampling the solution when running the unstructured solver. This cross sectional mesh tool is controlled by the following input section:
Here, the active parameter controls whether the tool is enabled or disabled. The triangulate parameter controls the output format, if it is active, the generic Voronoi polygons will be triangulated and the final output will be composed of triangles only. In the case it is inactive, the output will consist of generic polygons that will approximate the slicing of a full 3D mesh by the chosen plane. Finally, the plane can be specified by the normalVector and pointInPlane parameters.
Finally, the user can control whether they wish to treat any of the coordinate directions as periodic with the periodicDir parameter. The entries correspond to the \(x\), \(y\), and \(z\) axes, respectively. When a direction is set to true, seeds near the boundary in that direction are mirrored across the opposite boundary as ghost-seeds during the graph-generation step, ensuring seamless periodic connectivity at the domain edges.
Note
The LAVA Unstructured solver has a flag (do lava voro periodic) that needs to be active to correctly account for the periodicity when a mesh built under these circumstances is used in a simulation.
Point cloud parameters
The Voronoi mesher can either generate a new point cloud from scratch based on refinement regions defined in the input file, or it can initialize the Voronoi graph from an existing set of points provided by the user. When a point cloud is loaded from a file, the seeding process is bypassed. This behavior is controlled using the following parameter:
If read_points_from_file is set to true, then the mesher loads the filename contained in the following parameter:
If read_points_from_file is set to false, the mesher performs seeding and writes two point cloud files to disk.
unsmoothed.csv: Exported immediately after seeding, before point metadata is added and before Lloyd smoothing is applied.smoothed_final.csv: Written after metadata has been added and Lloyd iterations have smoothed the point distribution.
The output files can be saved in either binary or csv format, depending on user preference. The file type is controlled using the following setting:
Part of the process of generating the point cloud data structure involves labeling points with various metadata. These are related to identifying points close to the geometry in the case where the user has included a wall region and to identifying points to be smoothed. The information contained in this metadata is necessary for the correct usage of the Voronoi mesher but, if the user wants to restart the mesher from a point cloud file where this information has already been computed, for example, smoothed_final.csv, then they can skip this process by setting do_pointCloud_labeling to false:
# User may specify false if a previously labeled smoothed point cloud is used.
do_pointCloud_labeling: false
Initially, the volume transition between refinement regions of different cell spacing is abrupt. This volume jump can be smoothed by performing iterations of the Lloyd algorithm for generating centroidal Voronoi cells. To control the number of iterations, use the following input option.
Note
In the applications we have attempted so far, 10 iterations seem to be enough to get a gradual volume transition between regions. A more extensive study on the influence of the number of Lloyd iterations still needs to be performed.
Following are some optional parameters for the case when the user would want to generate near-wall anisotropic meshes. For detailed usage with wall refinements, see the anisotropic near-wall spacing section.
Warning
Anisotropic meshing capability is currently under development and should be considered preliminary.
# User may specify either isotropic (default) or anisotropic.
near_wall_cell_type: anisotropic
# The number of surface smoothing iterations after curved surfaces
# are deemed sufficiently discretized
num_wall_pnt_lloyd_iters: 2
# Largest allowable angle between two anisotropic seeding rays.
# If angle is larger than that then the space between these rays
# is populated with extra anisotropic seeds at `max_ray_angle` intervals
max_ray_angle: 10
max_ray_angle are detected and a fan of rays at max_ray_angle intervals is seeded with the discontinuity at its origin. The anisotropic rays grow until the underlying Voronoi cells are isotropic and the remaining computational domain is seeded in an isotropic fashion. For this approach to work, a minimum discretization level is required at curved features of the geometry. These features are automatically detected and refined prior to the extra surface smoothing iterations indicated in num_wall_pnt_lloyd_iters being conducted.
Distributed memory parallelism parameters
The current implementation of distributed memory parallelism leverages the Voronoi tessellation capabilities of the mesher itself. A separate, superseding, Voronoi tessellation with one cell per MPI rank is used to separate the computational domain into geometrically defined regions which contain approximately the same number of cells in each of them. Load-balancing in terms of the number of cells is achieved by using an algorithm inspired by Fu et al. 2, where an update for the seed of the load-balancing diagram is found by blending two procedures: the Centroidal Voronoi Tessellation (CVT) and the Voronoi Particle (VP) dynamics. In order to set this blending ratio and a threshold for what mean deviation from perfect balance is acceptable, use the following inputs:
#convergence criterion for load balancing
load_balancing_rms_threshold: 0.05
#blending between CVT and VP algorithms in load balancing
load_balancing_blending: 0.8
#max number of iterations in load balancing if convergence is not met
load_balancing_max_iter: 2000
The load_balancing_blending parameter controls the blend between VP and CVT methods, with valid values ranging from 0 to 1. A value of 0.8 means 80% VP and 20% CVT. The load_balancing_rms_threshold represents the acceptable RMS deviation from perfect load balance, expressed as a fraction (e.g., 0.05 = 5% deviation).
Note
The values shown here are default values that have been successfully used in various cases. Users should not need to modify these parameters under normal circumstances.
Since the Voronoi graph is fully defined by the location of the seed generating points, the partition can be saved in the same way as a point cloud file was. The inputs related to loading a previously defined partition are shown hereafter:
#specify true if user wants to restart from a previously defined partition.
read_partition_from_file: true
#partition point cloud file name
partitionPCfile: partitionPC.csv
Expert
There are additional parameters intended for advanced users or developers:face_connectivity_check, recompute_local_graph_every and dist_coeff.
The face_connectivity_check option enables a debugging feature that verifies whether every non-wall cell face is correctly associated with a neighboring cell. This check helps catch issues where global connectivity may be lost in the locally generated graphs on each rank.
The recompute_local_graph_every parameter is used to speed up the parallel Lloyd smoothing process by skipping the update of ghost seeds at every iteration. While this may lead to slight differences in the final smoothed point cloud compared to a single-rank run, the deviations are generally minimal due to the small incremental movements of seeds during each iteration.
Lastly, the dist_coeff parameter expands the ghost cell buffer around each partition. This is used to ensure the proper global connectivity information is retained for split ghost cells.
Two diagnostics help locate rank-boundary faces that end up without a counterpart on the neighbouring rank (see the border-face report below):
ghost_symmetry_diagnostic(0,1or2; default0): checks the ghost exchange of the final mesh build.1reports every cell adjacency at a rank boundary whose seed is missing from the neighbouring rank's ghosts;2also adds the missing seeds as ghosts and rebuilds the local graph. 3D only; it adds a few minutes at scale. The environment variableLAVA_GHOST_DIAGoverrides it.orphan_face_dump(defaultfalse): prints every border face that ends up without a counterpart, with its cells, and writes OBJ files of the face and its cells (orphandiag_*.obj). Setting the environment variableLAVA_ORPHAN_DUMPhas the same effect.
These parameters are specified in yaml format as shown below:
#specify true if user wants to check if all faces have neighbors.
face_connectivity_check: false
#do lloyd smoothing without recomputing true local graph for N iterations, then recompute it
recompute_local_graph_every: 1
#distance multiplier when trying to find ghost cells.
#value needs to be >= 1.
dist_coeff: 1.5
#check the ghost exchange of the final mesh: 0 off, 1 report, 2 report and repair.
ghost_symmetry_diagnostic: 0
#print and dump (OBJ) border faces without a counterpart on the neighbouring rank.
orphan_face_dump: false
Note
Every distributed-memory run reports its rank-boundary faces in a Border-face report line of the log. Orphan faces have no counterpart on the neighbouring rank. They are removed, which leaves the cells next to them open, and a WARNING line gives the largest opening (in m² and as a fraction of its cell's face area); they indicate a defect and should be zero. Faces dropped as negligible (smaller than 1e-9 of the face area of each cell they bound, mostly from exactly symmetric seed lattices) or as degenerate (fewer than three distinct vertices) are removed by design and leave every cell closed.
Refinement regions
Because a Voronoi tessellation is fully described by the distribution of points inside the domain of interest, the task of generating a high-quality mesh is simplified to placing seeds strategically and in a somewhat automated fashion. The process begins by defining the computational domain that bounds the Voronoi tessellation, followed by populating it with refinement regions. Each region is assigned a characteristic length scale that determines the base spacing between seed points. This length scale is inversely proportional to the number of cells in each region. Refinement regions can overlap and, when that occurs, the region with the smallest length scale is given priority.
The following region types are supported in the current Voronoi mesher:
cube
- name: rectangular_prism_example
type: cube
seed: bodycentered
smoothing_layers: 3
spacing_rel: [4, 4, 4]
distance: [10.0, 5.0, 7.5]
center: [0.0, 0.0, 0.0]
angles: [0.0, 0.0, 0.0]
telescoping_refinement:
- spacing_growth: 2
num_points_per_layer: 8
max_spacing_rel: 100
Each region has a name that will be used to identify it in the log file. The name parameter is arbitrary. The type parameter is used to distinguish the region's category. In this case, its type is a cube. The initial seeding is done in lattices and it is controlled by the seed parameter. The valid options for seeding patterns are cartesian, bodycentered, facecentered, or hexprism.
The choice of seeding pattern determines the resulting Voronoi cell shapes:
cartesian: Produces cubic cells (regular hexahedra) (left)bodycentered: Body-centered-cubic (BCC) lattice, produces truncated octahedra (middle)facecentered: Face-centered-cubic (FCC) lattice, produces rhombic dodecahedra (right)hexprism: Produces hexagonal prisms
Every region optionally has smoothing_layers. This defines the number of seed layers, starting from the boundary between regions, that will be targeted for Lloyd smoothing.
The spacing between neighboring seeds in the lattice is determined by multiplying spacing_rel in the corresponding coordinate axes with reference_length input number. Alternatively, the user may specify an absolute spacing value by using spacing_abs instead. This is not encouraged since it decouples the region from the reference_length parameter and makes it harder to conduct consistent mesh refinement studies.
Warning
Despite the input supporting different seed spacing in the different axial directions, the mesher has only been tested with isotropic seeding at this point. Therefore the spacing entries for each axis should be the same currently.
The distance parameter controls how the three \((x_1,x_2,x_3)\) axes of the bounding cube are scaled into a general rectangular prism in absolute values. The vector center determines the center point of the box. The angles parameter controls the rotation, in degrees, of the region relative to its own coordinate axes.
Note
A refinement region of type: cube is volumetric, i.e. it defines a region of space where all the seeds inside this region will have the same spacing.
Finally, the telescoping_refinement input section allows the user to smoothly transition the refinement region into the freestream. If this section is provided, the mesher will generate a series of layers, each with a thickness corresponding to a user-defined number of cells, set by the num_points_per_layer parameter. In each successive layer, the seed spacing increases according to the spacing_growth factor. This process continues until the seed spacing reaches the user-specified max_spacing_rel value. Alternatively, a max_spacing_abs can be provided also.
Warning
The max_spacing_rel may not exceed the spacing of the freestream value used when specifying the computational domain bounding box.
The figure below illustrates the effect for a refined cube region inside a coarse freestream. The left panel shows the resulting Voronoi cells (a single-cell-layer case for clarity): each telescoping layer doubles the cell size (spacing_growth: 2) until the freestream spacing is reached. The right panel compares the prescribed layer spacing (blue) with the spacing of the resulting mesh (green): the Lloyd iterations smooth each jump locally, over roughly smoothing_layers cells on either side of the layer interface.
ellipsoid
The type: ellipsoid region can be used to define either spherical or ellipsoidal volumes, within which seeds are placed using a user-defined spacing. The distance parameter is used to scale the axes of a sphere into an axis-aligned ellipsoid. If the same value is used for the 3 entries, then it is a sphere and the value is its radius.
- name: ellipsoid_example
type: ellipsoid
seed: bodycentered
smoothing_layers: 3
spacing_rel: [8, 8, 8]
distance: [2, 2, 2]
center: [1.0, 2.0, 3.0]
angles: [0.0, 0.0, 0.0]
telescoping_refinement:
- spacing_growth: 2
num_points_per_layer: 8
max_spacing_rel: 100
All the other parameters in this region input block have the same use and meaning as previously described in cube.
The distance entries are the semi-axes of the axis-aligned ellipsoid, before any rotation by angles:
frustum
In order to specify a cylinder, cone, or frustum shaped seeding region, use the frustum region type.
- name: frustum_example
type: frustum
seed: bodycentered
smoothing_layers: 2
axis_start: [1, 0, 2]
axis_end: [-1, 0, -2]
radius_start: 0.75
radius_end: 0.5
inner_radius_start: 0.5
inner_radius_end: 0.25
spacing_rel: [1, 1, 1]
telescoping_refinement:
- spacing_growth: 2
num_points_per_layer: 8
max_spacing_rel: 100
Many of the options for the frustum region are similar to those used for the cube or ellipsoid types. A frustum is defined by a central axis, which starts at axis_start and ends at axis_end. These points determine both the direction and the length of the frustum along its axis. The shape is formed by two circular faces, each perpendicular to this axis. The radius of the circle at axis_start is given by radius_start, and the radius at axis_end is specified by radius_end—both provided as absolute values. If the two radii are equal, the shape becomes a cylinder. Additionally, the frustum can be made hollow by specifying inner radii using inner_radius_start and inner_radius_end.
The cross-section does not have to be circular. Elliptical faces are specified by replacing a radius key with its *_ellipse variant, e.g. radius_start_ellipse: [a, b], giving distinct axis lengths in the local \(y\) and \(z\) directions (the same works for radius_end and the inner radii). Setting num_sides: N (with \(N \geq 3\); the default 0 keeps the smooth shape) replaces the circle or ellipse with a regular N-sided polygon: 4 produces rectangular ducts, 8 octagonal ones, and increasing N approaches the elliptical shape again. The polygon is scaled by the same two axis lengths, so with unequal values it becomes anisotropic in the same way an ellipse does. Its size can be given in two conventions:
- With the
radius_*keys, the polygon's vertices lie on the circle or ellipse those radii describe, with the first vertex on the local \(+y\) axis. - With the width keys
width_start/width_end(scalar or[wy, wz], used instead of the corresponding radius keys), the size is measured flat-to-flat as half-widths, and a flat face is aligned with the local \(+y\) axis:num_sides: 4with widths gives an axis-aligned rectangle with exactly those half-widths.inner_width_start/inner_width_endsize a polygonal hole the same way.
The optional phase_angle parameter (in degrees) rotates the polygon about the axis away from these default orientations. Contradictory inputs are rejected: a width key together with its corresponding radius key, or width keys or phase_angle without a polygonal cross-section (num_sides \(\geq 3\)).
A rectangular duct is therefore simply:
- name: rectangular_duct_example
type: frustum
seed: bodycentered
smoothing_layers: 2
axis_start: [-0.5, 0, 0]
axis_end: [0.5, 0, 0]
num_sides: 4
width_start: [0.3, 0.2]
width_end: [0.3, 0.2]
spacing_rel: [1, 1, 1]
Note
With unequal axis lengths and \(N \neq 4\) the affinely scaled polygon's sides are not of equal length — the natural generalization, exactly as a circle stretches into an ellipse.
telescoping_frustum
In jet noise prediction simulations, we have observed that abrupt changes in cell volume near the shear layer can impact far-field noise predictions. We also identified an opportunity to gradually increase cell size with distance from the jet source to reduce computational cost without compromising accuracy. To support this, we developed a specialized region type—telescoping_frustum—which provides finer control over cell volume transitions along a user-defined frustum axis. This region allows the user to specify a spacing_growth factor and control layer thickness through the num_points_per_layer parameter.
In standard regions, seed lattices are aligned with a global origin, enabling seamless overlap between regions that share the same spacing. However, this can lead to slight inconsistencies in spacing at region boundaries. The telescoping_frustum is the only region type where the seeding lattice is not aligned to the global axis. Instead, its layer origins are carefully positioned to maintain consistent spacing across region boundaries.
Additionally, this region type includes an option for radial_refinement, allowing for a smooth transition between the refined volume and the freestream spacing of the surrounding computational domain. It works on the same principle as the telescoping_refinement section present in previous region type definitions, using spacing_growth, num_points_per_layer, and max_spacing_rel (or max_spacing_abs) parameters to control the gradual transition in cell size.
- name: telescoping_frustum_example
type: telescoping_frustum
seed: bodycentered
smoothing_layers: 2
frustum:
- axis_start: [0.7, 0.0, 0.0]
axis_end : [1.75, 0.0, 0.0]
radius_start: 0.75
radius_end : 0.95
inner_radius_start: 0.25
inner_radius_end : 0.11
spacing_start_rel: [1, 1, 1]
spacing_end_rel: [4, 4, 4]
spacing_growth: 1.2
num_points_per_layer: 25
radial_refinement:
- spacing_growth: 2
num_points_per_layer: 5
max_spacing_rel: 100
The figure below shows a meridional slice through the cells of an annular telescoping frustum (each cell shaded by the axial layer it belongs to) next to the prescribed layer structure: the seed spacing grows along the axis from spacing_start_rel toward spacing_end_rel at the rate set by spacing_growth, one layer per num_points_per_layer cells, while the radial_refinement layers grade the spacing outward into the freestream.
The cross-section of a telescoping_frustum follows the same rules as the frustum region: num_sides, phase_angle, the *_ellipse radius variants, and the width keys may all be used inside the frustum subsection. This allows, for example, a rectangular (num_sides: 4) duct whose cell spacing grows along the axis — the telescoping segments and the radial_refinement transition all inherit the polygonal cross-section. The initial seed distributions below (before Lloyd smoothing) show a rectangular and an octagonal duct cross-section against their prescribed shapes, and the axial spacing growth of the rectangular telescoping duct:
wall
A type: wall region allows the user to introduce a geometric surface into the mesh. This surface is imported as a triangulation via the trifile parameter, with support for three file formats: *.fro, *.cgns and *.i.tri. The triangulation must meet two key requirements: it must be watertight (i.e., fully closed), and all surface normals should be consistently oriented in the same direction. The triangulation included here will be used as clipping surface and its boundaries will be included in the final mesh definition.
Note
Many meshers require input triangulations where triangle sizes are on the same order of magnitude as the final mesh cells. In contrast, the current Voronoi mesher only needs an accurate representation of the geometry’s curved features. Flat regions, for instance, can be captured using just two triangles without any loss of accuracy.
Note
The LAVA Voronoi mesher supports multiple instances of the wall region. However, whenever possible, it is recommended to use a single closed triangulation that defines the full geometry of interest. Unnecessary intersecting surfaces increase computational overhead and can lead to clipping failures in edge cases not yet addressed by the LAVA team.
Here is an example of an input block for a wall region:
- name: wall_region_example
type: wall
trifile: triangulation_example.cgns
smoothing_layers: 4 #Controls Lloyd smoothing of seed layers adjacent to the wall geometry
project_layers: 2
seed_toward_normal: true
directional_seeding: false
face_merge_angle : 30
#---start expert inputs---#
angle_exceptions:
- face_merge_angle: 5
components: 3, 4
- face_merge_angle: 15
components: 5
check_subcomponents: false
tangential_plane_pert_factor: 0.01
do_triangulation_checks: true
do_export_gap_triangles: false
#----end expert inputs----#
#---start optional inputs---#
rotate:
- center: [0.0, 0.0, 0.0]
axis: [0, 0, 1]
angle: 45.0
translate: [1.0, 0.0, 0.0]
#---end optional inputs---#
refinements:
- name: example_ref_1
seed: bodycentered
smoothing_layers: 2 #Controls Lloyd smoothing at boundaries between refinement levels
level_points_per_thickness: 8
level_spacing_inner_rel: 2
level_spacing_outer_rel: 100
level_spacing_growth_rate: 2
components: 3-5
#----start optional anisotropic inputs----#
initial_wall_normal_spacing_rel: 0.01
wall_normal_spacing_growth_rate: 1.2
#----end optional anisotropic inputs----#
#---start expert inputs---#
remove_1st_wall_layer_extra_points: true
#---end expert inputs---#
- name: example_ref_2
seed: bodycentered
smoothing_layers: 2
num_levels: 2
level_spacings_rel: [1, 2]
level_thicknesses: [0.25, 0.25]
components: 2
There are five key parameters associated with a wall region that casual users should understand: smoothing_layers, project_layers, seed_toward_normal, directional_seeding, and face_merge_angle.
smoothing_layers: Determines how many layers of seeds near the geometry will be smoothed using the Lloyd iteration process.project_layers: Specifies how many layers of seeds will be adjusted in the wall-normal direction to ensure their spacing remains consistent with the region’s target seed spacing.seed_toward_normal: Defines which side of the triangulation represents the fluid domain and which represents the solid. This controls where seeds are added or removed and dictates which portions of the mesh are clipped away during the geometry subtraction phase.directional_seeding: Determines whether wall-distance-based refinement regions should expand in all directions regardless of surface normal orientation, or only if the direction pointed to by the surface normal should be taken into account. Ifdirectional_seedingis set totruethen only the direction that points towards the fluid domain, given in combination of the surface normal orientation and theseed_toward_normalparameter, is considered valid for in region tests.face_merge_angle: Sets a threshold, in degrees, for merging neighboring triangles based on the similarity of their normals. Triangles with normal vectors within this angular threshold are treated as part of the same smooth surface and will be merged during the clipping process. This classification is performed on a component-by-component basis. Therefore, if the loaded triangulation is already divided into different regions, these divisions will be preserved in the final mesh.
Expert
Expert users have extra parameters that could be added to a wall region definition. These are the angle_exceptions input section, the check_subcomponents parameter, the tangential_plane_pert_factor, do_triangulation_checks, and do_export_gap_triangles.
angle_exceptions: This input section enables the user to apply different face merge angle criteria to different components. For instance, in an iced wing application, the user may wish to use distinct criteria for the iced region compared to the smooth areas of the wing. Multiple exceptions can be added within this section, with each entry consisting of its ownface_merge_angleand a list ofcomponentsto which this angle threshold applies.check_subcomponents: In rough triangulations, such as those for accreted ice, the algorithm used to classify smooth regions (referred to as subcomponents) may create a subcomponent where two triangles share only a single vertex. This situation can cause issues for the clipper algorithm. The check_subcomponents parameter determines whether an additional check is performed during the classification step to identify and handle this single-vertex triangle neighbor case.tangential_plane_pert_factor: The projection step might create equidistant seeding patterns that may lead to degenerate cases during the Voronoi seed generation. A tangential random perturbation of the projected layers is performed to remove degeneracies. Thetangential_plane_pert_factordefines the maximum magnitude of this perturbation as a fraction of the local seed spacing.do_triangulation_checks: When the mesher reads a triangulated surface, it automatically performs a suite of integrity checks—verifying that the surface is watertight, consistently oriented, and free of degenerate connectivity—and attempts to correct any orientation inconsistencies it finds. This behavior is controlled bydo_triangulation_checks(defaulttrue). Disabling it skips the checks and simply populates the triangle neighbor data structure, which can be useful to reduce startup time when the triangulation is already known to be valid. As part of these checks, the mesher also verifies that the wall-normal gap available between facing surfaces is larger than the first-layer wall-normal spacing for each component, emitting a warning if any component fails.do_export_gap_triangles: A debug companion to the gap check described above (defaultfalse). When set totrue, the mesher writes one OBJ file per offending component containing the source triangle, the opposing hit triangle, and a line segment connecting their centroids at the measured gap distance. These files can be loaded in a visualization tool to quickly locate and fix the problematic region of the triangulation.
Casual users should not add these entries to their input file. Their default values should be valid for most cases.
Optional
rotateandtranslate: These allow the user to apply a rigid body transformation to the loaded triangulation before it is used.rotatetakes a sub-section withcenter(3-element array),axis(3-element array), andangle(scalar, in degrees).translatetakes a 3-element array[dx, dy, dz]. At most one instance of each is currently supported. When both are specified, the rotation is always applied first, followed by the translation.
Each wall region has a refinements input section. The refinements section is responsible for introducing seeding regions based on the distance to the triangulation introduced in trifile in the computational domain. This section is composed of blocks of two types that have shared and specific parameters. In the previously added wall example block there are two refinement sections: example_ref_1 and example_ref_2. Both of them have the following common parameters: name, seed, smoothing_layers and components, which are defined hereafter:
name: Arbitrary string used to identify the region in the logfile.seed: Seeding pattern. See cube region for a more thorough description.smoothing_layers: Determines how many layers of seeds between refinement region boundaries will be smoothed using the Lloyd iteration process.components: Determines which sections of the triangulation will be used as a basis for the distance calculation to determine the boundaries of each refinement region. Components may be added as numbers, "components: 1, 2, 3", as intervals, "components: 1-3" or by name, for example, "components: slat, main, flap".
Expert
Expert users have access to an additional parameter that can be added to the refinement
section of the wall region: remove_1st_wall_layer_extra_points.
This parameter controls whether points marked as belonging to the first wall layer —
and that only have neighbors also in the first wall layer — are removed from the point
cloud. Under normal circumstances, removing these extra points is recommended. However,
in regions where small gaps exist relative to the local seed spacing, there may not be
room for other points to be assigned to additional wall layers, and unnecessary removals
can occur. For example, this behavior was observed when meshing a wing with horn ice accretion and its value was set to false, turning off the default behavior.
Tip
If the user does not know the component numbers and/or names, they may run the mesher and stop execution after the triangulation is read and its contents are output to the screen or logfile. One example output is:
Reading triangulation from crmhl-2dcut.igs.cgns
CGNS lib version : 4200
CGNS file version : 4
Done reading
Number of nodes : 82190
Number of triangles : 164368
Number of components : 4
.... PID: 1 name: slat
.... PID: 2 name: main
.... PID: 3 name: side
.... PID: 4 name: flap
Finished reading triangulation file: crmhl-2dcut.igs.cgns
Anisotropic Near-Wall Spacing (Optional)
Optional
In the refinement section, the user has the option of specifying the wall-normal spacing in the near-wall region and its growth via the following parameters: initial_wall_normal_spacing_rel and wall_normal_spacing_growth_rate, respectively. Note that the value chosen for initial_wall_normal_spacing_rel must be smaller than the isotropic distance between seeds introduced in the level_spacing_inner_rel parameter. These values are only relevant if near_wall_cell_type is set to anisotropic in the Point cloud parameters section.
The parameters in the two types of refinement section blocks differ based on how they define distance-based seeding volumes.
In example_ref_1, a telescoping strategy is used. A sequence of nested regions is generated, each with a thickness determined by the number of points per layer, controlled by level_points_per_thickness. The refinement begins near the surface, using the initial spacing specified by level_spacing_inner_rel. As each subsequent layer is created, the local spacing increases by a factor defined by level_spacing_growth_rate. This process continues until the spacing reaches the value given in level_spacing_outer_rel.
Warning
The level_spacing_outer_rel may not exceed the spacing of the freestream value used when specifying the computational domain bounding box.
In contrast, example_ref_2 adopts a manual specification approach. It defines the number of refinement levels using num_levels, and explicitly provides the relative spacings and absolute thicknesses for each level via the level_spacings_rel and level_thicknesses parameters, respectively.
All seed spacing parameters that end with _rel are relative to the reference_length parameter discussed in the Global parameters section of this manual. If the user wants to introduce absolute spacing values, they may change the ending to _abs.
Tip
The telescoping strategy used in example_ref_1 is the LAVA group’s preferred approach for generating wall-modeled LES meshes. When this method is applied, globally refining the mesh by halving the reference_length results in approximately a fourfold increase in the total number of cells. In contrast, using the approach in example_ref_2 leads to about an eightfold increase under the same refinement. The increase is smaller in the first strategy because both the seed spacing and the layer thicknesses are reduced simultaneously.
If the user wants to specify a cylinder as a triangulated surface they do not need to provide the triangulation file for it. The user can simply define the parameter trifile as cylinder and define the cylinder via simple geometric and discretization parameters. The cylinder can be specified using either: (center, axis, height, radius) or (axis_begin, axis_end, radius). The angle_resolution parameter (in degrees) controls the circumferential discretization: smaller values create more triangles around the cylinder's perimeter for a smoother surface. A sample cylindrical wall region input is as follows:
- name: cylinder_example
type: wall
seed_toward_normal: true
trifile: cylinder
geom_parameters:
- center: [-0.256326208, -0.256326208, 0.053750000]
axis: [0, 0, 1]
radius: 0.2
height: 0.025
angle_resolution: 2
smoothing_layers: 4
project_layers: 2
face_merge_angle: 5
refinements:
- name: cylinder_ref
seed: bodycentered
smoothing_layers: 3
level_points_per_thickness: 4
level_spacing_inner_rel: 16
level_spacing_outer_rel: 1000
level_spacing_growth_rate: 2
tri
A type: tri region allows users to define arbitrary shapes using triangulated surfaces. These surfaces can serve as boundaries for volumetric refinement regions or as the basis for distance-based seeding. Unlike wall regions, multiple tri regions may be included and the triangulation files in them do not need to form watertight surfaces—provided the volumetric_seeding section is omitted. One common use case for an open triangulated surface is marking the approximate location of a shock, enabling targeted refinement based on distance.
Most parameters in a tri region mirror those of a wall region. The key distinction is the optional volumetric_seeding block, which is used when the user wants to fill the interior of a closed triangulated surface with a uniform seed spacing. This input block type may be omitted otherwise. Each volumetric_seeding section includes four parameters: name, seed, smoothing_layers, and spacing_rel, all of which have been described earlier in this manual.
An example input block for a tri region is included hereafter:
- name: user_defined_tri_region_example
type: tri
seed_toward_normal: false
trifile: other_triangulation_example.cgns
refinements:
- name: tri_dist_refinement_example
seed: bodycentered
smoothing_layers: 2
level_points_per_thickness: 8
level_spacing_inner_rel: 2
level_spacing_outer_rel: 100
level_spacing_growth_rate: 2
components: 1
volumetric_seeding: # if this section is included, triangulation must be closed.
- name: user_def_volume_example
seed: bodycentered
smoothing_layers: 2
spacing_rel: 1
Yaml input examples
In this section, examples of complete input files are included.
Warning
If one inspects the files, they will note that the first entry in the region: input block is always an axis-aligned cube region. This is mandatory. The first region is what defines the computational domain's bounding box and the freestream refinement level.
Note
Example surface triangulation files are provided for the multielement airfoil and OAT15a cases. The simple volumetric seeding option does not require a triangulation. For the round jet case, a triangulation is not included; however, the roundjet.yml file is provided as an example of how to configure a telescoping_frustum region.
References
-
Sousa, V., Rodgers, A. K., Sriram, K., Sozer, E., Barad, M. F., Stich, G.-D., Cadieux, F., and Duensing, J., "LAVA Voronoi Mesher for Wall-Modeled Large-Eddy Simulations," American Institute of Aeronautics; Astronautics, July2024. https://doi.org/10.2514/6.2024-4306 ↩
-
Fu, L., Hu, X. Y., and Adams, N. A., "A Physics-Motivated Centroidal Voronoi Particle Domain Decomposition Method," Journal of Computational Physics, Vol. 335, 2017, pp. 718--735. https://doi.org/https://doi.org/10.1016/j.jcp.2017.01.051 ↩
Tutorials
Supersonic Flow Over a Diamond Airfoil
This inviscid steady flow test problem is relevant for sonic-boom simulations. The diamond airfoil is placed at zero degrees angle of attack in a Mach 1.5 freestream flow in the +X direction.
Mach number contours showing shock structure around the diamond airfoil.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| diamond_airfoil_tri.fro | Diamond airfoil surface triangulation file |
| voro_diamond_airfoil.yml | Voronoi meshing input file |
| unst_diamond_airfoil.inputs | Solver input file |
| job_tur_ath.pbs | Sample PBS file that generates the mesh and runs the solver on NAS Athena nodes |
Directory Setup
Create a working directory for this tutorial and place all of the downloaded files in it. The mesh is generated and the solver runs in this directory:
Warning
If you run on NAS systems, replace the #PBS -W group_list=<your project group ID> line in the PBS file with the group id you will use.
Meshing
The diamond airfoil problem is solved on a 400 m × 400 m domain. The farfield cells are configured with 100 m spacing between cell seeds. The airfoil center is placed at the computational domain origin (x,y,z)=(0,0,0). Six frustum refinement regions (three above, three below) are positioned to track the shocks emanating from the airfoil.
Note
LAVA unstructured solver does not support true 2D meshes. For 2D simulations, we create 3D meshes with a single cell in the depth direction.
On NAS systems, the provided PBS file generates the mesh before it runs the solver (see Running the Simulation). On a workstation, generate the mesh in the case directory:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
This generates voro_diamond_airfoil.cgns, the mesh the solver input file reads.
Solver Inputs
For a detailed description of all solver input parameters, see the Unstructured Solver Inputs section.
This test case uses an inviscid flow model with a \(2^{\textrm{nd}}\)-order
MUSCL scheme, the AUSMPW+ flux function, and the rminmod limiter, the recommended starting point for supersonic flows (see Limiter options):
convective terms {
scheme = MUSCL
order = 2
limiter = rminmod
flux function = ausmpw+
}
navierstokes {
viscous = false
}
Since this is a steady-state case, the implicit solver options control the pseudo-time marching algorithm. The Jacobian of the residual (derivative of the Euler equations with respect to fluid variables) is estimated by finite differences (numerical Jacobian, the default). The Jacobian is updated every 5 pseudo-time steps, and the line search, which is on by default for steady cases, keeps the lagged Jacobian effective. The local CFL number starts at 1 and the solver adapts it from step to step; the input sets no maximum CFL, so the default safety limit of \(10^4\) applies (see Implicit Stepping):
implicit {
number of steps = 1000
jacobian method = numerical
jacobian interval = 5
adaptive {
min cfl = 1.
}
}
The simulation stops once the continuity equation residual has dropped by 8 orders of magnitude:
The boundary conditions for this problem are:
# BC_1, BC_2, BC_3, BC_4 : Four edges of the diamond.
# BC_5 : zmin (Symmetric since case is 2D)
# BC_6 : ymin
# BC_7 : xmin
# BC_8 : ymax
# BC_9 : xmax
# BC_10 : zmax
BC_1 {type = wall; kind = slip}
BC_2 {type = wall; kind = slip}
BC_3 {type = wall; kind = slip}
BC_4 {type = wall; kind = slip}
BC_5 {type = symmetry}
BC_6 {type = farfield}
BC_7 {type = farfield}
BC_8 {type = farfield}
BC_9 {type = farfield}
BC_10 {type = symmetry}
Running the Simulation
The following example is for NAS Athena (AMD Turin) nodes. From pfe, log in to the Athena front end (athfe01) and submit the PBS script, which generates the mesh and then runs the solver on one node:
Note
Make sure to inspect and alter the provided PBS file for your system. The Running On NAS Guide lists the setup for the other NAS node types.
Not yet available on GPU
The GPU solvers do not currently support the implicit solver used in this tutorial. If you try to use the GPU executable it may fail with a runtime error.
On a workstation, generate the mesh as shown in Meshing and launch the solver from the case directory:
Executable Names
The unstructured solver executable name varies by architecture. See the LAVA Installation Guide for details.
This example uses 2 MPI ranks with 10 OpenMP threads each (total of 20 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)line_probe/- Ascii files for data along the line probes (###.Unst.#########.line)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
You can visualize the residual and CFL histories using the plotHist.py utility:
These plot the L2 norm of the continuity equation residual and the CFL number versus pseudo-time step number on a logarithmic scale. For a detailed overview of plotHist, see the plotHist documentation. Your convergence history should be similar to:
The continuity equation residual drops by 8 orders of magnitude in about 190 pseudo-time steps. The CFL number grows from 1 while the steps succeed; between steps 19 and 33, while the residual stalls near \(10^{-1}\), the controller cuts it back several times, then it grows steadily and reaches the \(10^4\) limit at step 126.
References
[1] Nemec, Marian, Michael Aftosmis, and Mathias Wintzer. "Adjoint-based adaptive mesh refinement for complex geometries." 46th AIAA Aerospace Sciences Meeting and Exhibit. 2008.
Double Mach Reflection
This classical benchmark case for shock capturing schemes involves a planar shock traveling at \(\textrm{Mach}=10\) impinging on a \(30^\circ\) wedge. The case is set up as proposed by Woodward and Colella 1. The rectangular domain extends from \([0,4]\times[0,1]\) with the initial shock positioned at an angle such that it impinges on the bottom boundary at \(x=1/6\).
The simulation uses an ideal gas with \(\gamma=1.4\) and \(C_p=3.5\), with pre-shock conditions of \(\rho=1.4\) and \(p=1\).
Figure 1: Density at \(t=0.2\) with the 30 density contours from 1.731 to 20.92 of Woodward and Colella; the thick line marks the reflecting wall
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| voro_double_mach.yml | Voronoi meshing input file |
| unst_double_mach.inputs | Solver input file |
| job_mil_ait.pbs | Sample PBS file that generates the mesh and runs the solver on NAS Aitken Milan nodes |
Directory Setup
Create a working directory for this tutorial and place all of the downloaded files in it. The mesh is generated and the solver runs in this directory:
Warning
If you run on NAS systems, replace the #PBS -W group_list=<your project group ID> line in the PBS file with the group id you will use.
Meshing
The double Mach problem is solved on a \(4\times1\) rectangular domain. The mesh is configured to use isotropic cells of size \(0.01\), generating regular hexagonal prism cells throughout the domain except at boundaries where cells are clipped.
Note
LAVA unstructured solver does not support true 2D meshes. For 2D simulations, we create 3D meshes with a single cell in the depth direction
Voronoi meshing inputs are explained in detail in the Voronoi Meshing section. This case involves a simple rectangular domain without additional geometry, so only the .yml file shown above is required.
On NAS systems, the provided PBS file generates the mesh before it runs the solver (see Running the Simulation). On a workstation, generate the mesh in the case directory:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
This generates voro_double_mach.cgns, the mesh the solver input file reads.
Solver Inputs
For a detailed description of all solver input parameters, see the Unstructured Solver Inputs section.
The solver input file begins by specifying the exact flow name as doublemach. LAVA incorporates several specialized initial and boundary conditions through these "exact" specifications, which are typically used for standard benchmark problems that require conditions beyond simple free-stream or box region initializations. For this problem, the initialization involves an oblique shock impinging on the wedge at \(x=1/6\). The boundary conditions at the inlet, wedge wall, and upper boundary are automatically configured for this test case through the "exact" methods.
The boundary conditions are specified as follows:
# BC_1 : zmin
# BC_2 : ymin
# BC_3 : xmin
# BC_4 : ymax
# BC_5 : xmax
# BC_6 : zmax
BC_1 {type = symmetry }
BC_2 {type = exact }
BC_3 {type = exact }
BC_4 {type = exact }
BC_5 {type = outlet }
BC_6 {type = symmetry }
sod species, named after the classical Sod shock tube problems that use the same fluid properties:
The sod species is provided with the LAVA release as part of the built-in species database. The corresponding sod.spec file does not need to be present in your working directory since it is part of the LAVA database. However, if you place a sod.spec file in your run directory, it will take precedence over the database version.
The mesh file is specified as the CGNS file generated by the Voronoi mesher:
This test case uses an inviscid flow model with a \(2^{\textrm{nd}}\)-order MUSCL scheme, the AUSMPW+ flux function, and the rminmod limiter (see Limiter options):
convective terms {
order = 2
limiter = rminmod
flux function = ausmpw+
}
navierstokes {
viscous = false
}
The simulation uses unsteady time integration with \(3^{\textrm{rd}}\)-order accurate explicit time stepping, a constant time step of \(2\times10^{-4}\), and runs for 1000 time steps (total simulation time of \(0.2\) seconds).
Refer to the complete solver input file and the Unstructured Solver Inputs documentation for detailed explanations of all parameters.
Running the Simulation
The following example is for NAS Aitken AMD Milan nodes. From pfe, log in to the Milan front end (afe01) and submit the PBS script, which generates the mesh and then runs the solver on one node:
Note
Make sure to inspect and alter the provided PBS file for your system. The Running On NAS Guide lists the setup for the other NAS node types.
On a workstation, generate the mesh as shown in Meshing and launch the solver from the case directory:
Executable Names
The unstructured solver executable name varies by architecture. See the LAVA Installation Guide for details.
This example uses 2 MPI ranks with 10 OpenMP threads each (total of 20 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)line_probe/- ASCII files containing flow field data along user-defined lines
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. The ######### in filenames is the output step, zero-padded to 9 digits (the sync step when sync steps per ctu or sync dt is set; see Output file names). Surface files contain solution fields on boundary surfaces. For convenience, LAVA also creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
Visualization
Start by loading Unst.volLatest.cgns in your visualization software to examine the final solution, then load earlier time steps as needed to study the flow evolution.
References
-
Woodward, P., and Colella, P., "The Numerical Simulation of Two-Dimensional Fluid Flow with Strong Shocks," Journal of Computational Physics, Vol. 54, No. 1, 1984, pp. 115--173. https://doi.org/10.1016/0021-9991(84)90142-6 ↩
Laminar Flow over Circular Cylinder
Mach number contours at time \(t=1.824\) s (about 122 convective time units).
This unsteady flow simulation is a validation case for laminar vortex shedding behind a cylinder at Reynolds number \(Re=150\). A detailed description of this case can be found at the GRC validation page.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| voro_cylinder_2d.yml | Voronoi meshing input file |
| unst_cylinder_2d.inputs | Solver input file |
| job_tur_ath.pbs | Sample PBS file that generates the mesh and runs the solver on NAS Athena nodes |
Directory Setup
Create a working directory for this tutorial and place all of the downloaded files in it. The mesh is generated and the solver runs in this directory:
Warning
If you run on NAS systems, replace the #PBS -W group_list=<your project group ID> line in the PBS file with the group id you will use.
Meshing
The laminar cylinder case uses a 200m × 200m domain with refinement in the wake of a unit cylinder. The cylinder center is placed at the origin (x,y,z)=(0,0,0). A triangulated parametrization of the cylinder is generated on-the-fly, a special feature for cylindrical geometries. The wake refinement is implemented as a telescoping frustum. See the Voronoi mesher refinement region documentation for details on refinement options.
Note
LAVA unstructured solver does not support true 2D meshes. For 2D simulations, we create 3D meshes with a single cell in the depth direction.
On NAS systems, the provided PBS file generates the mesh before it runs the solver (see Running the Simulation). On a workstation, generate the mesh in the case directory:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
This generates voro_cylinder_2d.cgns, the mesh the solver input file reads.
Solver Inputs
Please inspect the provided tutorial solver input file: unst_cylinder_2d.inputs. For a detailed description of all solver input parameters, see the Unstructured Solver Inputs section.
The physical time step is \(7.296\times 10^{-4}\) s, about 0.049 convective time units (CTU, based on the cylinder diameter and the freestream velocity). At the expected Strouhal number \(St\approx0.18\), this resolves one vortex shedding period with about 110 time steps. The 2500 steps cover about 122 CTU: the wake starts symmetric, and shedding, triggered by round-off, sets in after about 35 to 50 CTU and becomes periodic about 50 CTU later.
This viscous test case uses a \(2^{\textrm{nd}}\)-order MUSCL scheme with the AUSMPW+ flux function and no limiter. Time integration uses the implicit BDF2 dual time stepping scheme with numerical Jacobian and adaptive local time stepping. The local CFL number starts at 5 and the solver adapts it from one dual-time iteration to the next; the input sets no maximum CFL, so the default safety limit of \(10^4\) applies (see Implicit Stepping). Maximum dual-time iterations are set as 16:
implicit {
jacobian method = numerical
method = bdf2
number of steps = 16
adaptive {
min CFL = 5.
}
}
The dual time step iteration convergence is governed by:
The case is viscous and laminar. The linear solver uses its defaults, up to 40 GMRES iterations to a relative tolerance of \(10^{-2}\), and the change thresholds that limit the per-iteration update are relaxed to 50%:
The boundary conditions for this problem are:
#Cylinder
BC_1 {type = wall; kind = noslip}
#Z min
BC_2 {type = symmetry}
#Y min
BC_3 {type = farfield}
#X min
BC_4 {type = farfield}
#Y max
BC_5 {type = farfield}
#X max
BC_6 {type = farfield}
#Z max
BC_7 {type = symmetry}
Running the Simulation
The following example is for NAS Athena (AMD Turin) nodes. From pfe, log in to the Athena front end (athfe01) and submit the PBS script, which generates the mesh and then runs the solver on one node:
Note
Make sure to inspect and alter the provided PBS file for your system. The Running On NAS Guide lists the setup for the other NAS node types.
On a workstation, generate the mesh as shown in Meshing and launch the solver from the case directory:
Executable Names
The unstructured solver executable name varies by architecture. See the LAVA Installation Guide for details.
This example uses 2 MPI ranks with 32 OpenMP threads each (total of 64 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
The drag coefficient values are saved in the monitor file. You can plot the history of the drag coefficient \(\mathrm{C_D}\) with respect to convective time units (CTU) using the plotHist.py utility; -xRange leaves out the impulsive start:
Once shedding is periodic, the drag coefficient oscillates around \(\mathrm{C_D}\approx1.33\) at twice the shedding frequency, and the side force gives \(St\approx0.18\).
You can visualize the continuity equation L2 residual norm history with:
Within each time step, the dual-time iterations reduce the continuity residual by 3 orders of magnitude, typically in 6 or 7 iterations.
For a detailed overview of plotHist, see the plotHist documentation.
References
[1] NASA Glenn Research Center, "Laminar Flow over a Circular Cylinder," Available: https://www.grc.nasa.gov/www/wind/valid/lamcyl/Study1_files/Study1.html
[2] B.N. Rajani, A. Kandasamy, Sekhar Majumdar, "Numerical simulation of laminar flow past a circular cylinder," Applied Mathematical Modelling, Volume 33, Issue 3, 2009,Pages 1228-1247, ISSN 0307-904X, https://doi.org/10.1016/j.apm.2008.01.017.
Multielement Airfoil RANS
The 2D multielement airfoil is a Reynolds-Averaged Navier-Stokes (RANS) verification case from the NASA Langley Research Center's Turbulence Modeling Resource. This case simulates flow over a 2D, high-lift configuration airfoil with slat, main and flap elements at \(\textrm{Mach}=0.2\), \(\textrm{Re}=5\times10^6\), and \(\alpha=16^{\circ}\).
Mach number contours around the three-element high-lift configuration.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| crmhl-2dcut-triangulation.cgns | Surface geometry triangulation |
| voro_mea2d.yml | Voronoi meshing input file |
| unst_mea2d.inputs | Solver input file |
| job_mil_ait.pbs | Sample PBS file that generates the mesh and runs the solver on NAS Aitken Milan nodes |
Directory Setup
Create a working directory for this tutorial and place all of the downloaded files in it. The mesh is generated and the solver runs in this directory:
Warning
If you run on NAS systems, replace the #PBS -W group_list=<your project group ID> line in the PBS file with the group id you will use.
Meshing
The Voronoi meshing input for the multielement airfoil specifies a 1000m × 1000m domain. The three-element airfoil assembly (slat, main element, and flap) is positioned at the domain center. Anisotropic Voronoi cells are generated along the airfoil surfaces with a spacing growth rate of 1.25. Outside the anisotropic region, spacing transitions from fine to coarse through 8 cell-thick layers until the farfield is reached.
Note
LAVA unstructured solver does not support true 2D meshes. For 2D simulations, we create 3D meshes with a single cell in the depth direction.
On NAS systems, the provided PBS file generates the mesh before it runs the solver (see Running the Simulation). On a workstation, generate the mesh in the case directory:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
This generates voro_mea2d.cgns, the mesh the solver input file reads.
Note
The provided Voronoi input file will generate a coarser mesh than required for mesh insensitive results. You can reduce the reference_length parameter in the voro_mea2d.yml for finer meshes.
Solver Inputs
For a detailed description of all solver input parameters, see the Unstructured Solver Inputs section.
The mesh is generated in the \(x\)-\(y\) plane with a single cell in \(z\). The angle of attack turns the freestream in the \(x\)-\(z\) plane and lift is measured normal to it in that plane, so the grid is rotated by \(90^{\circ}\) about the \(x\) axis when it is read, which puts the airfoil in the \(x\)-\(z\) plane (see Grid File and Transformations):
grid {
file = voro_mea2d.cgns
transform_1 {function = rotate; center = [0, 0, 0]; axis = [1, 0, 0]; angle = 90}
}
This input file omits the time section, and so the simulation is assumed steady. The implicit section controls solver options for the Newton-Krylov algorithm. The local CFL number starts at 1 and the solver adapts it from step to step; the input sets no maximum CFL, so the default safety limit of \(10^4\) applies (see Implicit Stepping). The numerical Jacobian (the default) is updated every 5 iterations, and the line search keeps the lagged Jacobian effective:
implicit {
number of steps = 500
jacobian method = numerical
jacobian interval = 5
do line search = true
adaptive {
min cfl = 1.
}
}
The simulation stops once the continuity equation residual has dropped by 7 orders of magnitude:
A \(\mathrm{2}^\mathrm{nd}\) order accurate MUSCL (default) convective scheme is used with the HLLE-CLM flux function, which is better behaved than AUSMPW+ for numerical Jacobian construction. No limiter is needed at this subsonic condition. The hllcmalimit and hllcphifloor values shown are the hlleclm defaults (see Convective terms):
convective terms {
order = 2
limiter = none
reconstruction kappa = 0.3333333333333333
# hlleclm rather than the default ausmpw+: ausmpw+ does not converge this high-lift case
flux function = hlleclm
hllcmalimit = 0.1
hllcphifloor = 0.3
}
The simulation is viscous. The linear solver uses its defaults, up to 40 GMRES iterations to a relative tolerance of \(10^{-2}\):
minimum density specification improved the behavior during impulsive start.
See the Navier-Stokes section of the unstructured input documentation for more details on these options.
Spalart-Allmaras (SA) turbulence model is used:
Aerodynamic force/moment integrations are setup for each airfoil element as well as a collective group. See the loads section of the unstructured input documentation for more details on loads integration.
loads {
interval = 1
moment center = [0.25, 0., 0.]
normalize = true
gauge = true;
group_1 {
name = all
include = [1, 2, 3]
}
group_2 {
name = slat
include = [1]
}
group_3 {
name = main
include = [2]
}
group_4 {
name = flap
include = [3]
}
}
The boundary conditions are as follows:
# BC_1 : slat
# BC_2 : main
# BC_3 : flap
# BC_4 : zMin
# BC_5 : yMin
# BC_6 : xMin
# BC_7 : yMax
# BC_8 : xMax
# BC_9 : zMax
BC_1 {type = wall}
BC_2 {type = wall}
BC_3 {type = wall}
BC_4 {type = symmetry}
BC_5 {type = farfield}
BC_6 {type = farfield}
BC_7 {type = farfield}
BC_8 {type = farfield}
BC_9 {type = symmetry}
Running the Simulation
The following example is for NAS Aitken AMD Milan nodes. From pfe, log in to the Milan front end (afe01) and submit the PBS script, which generates the mesh and then runs the solver on one node:
Note
Make sure to inspect and alter the provided PBS file for your system. The Running On NAS Guide lists the setup for the other NAS node types.
On a workstation, generate the mesh as shown in Meshing and launch the solver from the case directory:
Executable Names
The unstructured solver executable name varies by architecture. See the LAVA Installation Guide for details.
This example uses 2 MPI ranks with 32 OpenMP threads each (total of 64 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
Monitoring Convergence
You can visualize the residual history using the plotHist.py utility:
This plots the L2 norm of the continuity equations and SA turbulence model residual versus pseudo-time step number on a logarithmic scale. For a detailed overview of plotHist, see the plotHist documentation. Your convergence history should be similar to:
The continuity equation residual drops by 7 orders of magnitude in about 230 iterations. The SA model residual first rises, peaking around iteration 50, and then falls below \(10^{-5}\).
To verify force/moment convergence, you can plot the iterative history of the lift coefficient with:
References
NASA Langley Research Center, "2D Multielement Airfoil - Turbulence Modeling Resource," Available: https://turbmodels.larc.nasa.gov/multielementverif.html
Onera M6 Wing RANS
The Onera M6 wing is a Reynolds-Averaged Navier-Stokes (RANS) validation case from the NASA Langley Research Center's Turbulence Modeling Resource. This classic transonic flow test case features a swept wing with shock-boundary layer interaction.
Symmetry plane Mach contours
An arbitrary polyhedral type mesh generated with STAR-CCM+ is provided.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| onera_m6.cgns | Arbitrary polyhedral mesh |
| unst_onera_m6.inputs | Solver input file |
| job_tur_ath.pbs | Sample PBS file for the solver run on NAS Athena nodes |
| cp_cuts.yml | Input file for the \(C_P\) cut extraction tool |
| exp_case_2308.dat.gz | Experimental data to compare the \(C_P\) cuts against |
| plot_cp_sections.py | Python script to plot the \(C_P\) cut data against experiments |
Directory Setup
Create a working directory for this tutorial:
Place all of the downloaded tutorial files in the case directory and unpack the experimental data:
Solver Inputs
Reference conditions are set up for a \(\mathrm{Mach}=0.84\), \(\mathrm{Re}=14.6\times10^6\) at an angle of attack of \(\alpha=3.06^\circ\):
reference conditions {
mach = 0.84
Re = 14.6e6
alpha = 3.06
temperature = 300
beta = 0.
length = 0.649749105896 # Mean Aerodynamic Chord (MAC)
area = 0.757500689023 # Semi-span area
}
The implicit solver is utilized with numerical Jacobians, updated every 5 iterations (the default). The local CFL number starts at 1 and the solver adapts it from step to step; the input sets no maximum CFL, so the default safety limit of \(10^4\) applies (see Implicit Stepping):
The simulation stops once the continuity equation residual has dropped by 7 orders of magnitude:
\(2^\mathrm{nd}\) order MUSCL scheme with the rminmod limiter is used for the convective fluxes:
Spalart-Allmaras turbulence model is used. The linear systems of the Navier-Stokes and the turbulence model equations use the default linear solver settings, up to 40 GMRES iterations to a relative tolerance of \(10^{-2}\):
The boundary conditions are as follows:
# BC_1 : farfield
# BC_2 : symmetry
# BC_3 : wing
BC_1 {type = farfield}
BC_2 {type = symmetry}
BC_3 {type = wall}
The output section includes integrated loads on the wing:
loads {
interval = 1
moment center = [0., 0., 0.]
normalize = true
gauge = true;
group_1 {name = wing; include = [3]}
}
This configuration computes integrated loads for the wing. See the loads section of the unstructured input documentation for more details on loads integration.
Running the Simulation
The following example is for running on NAS's Athena system using AMD Turin nodes. From pfe, log in to the Athena front end (athfe01) and submit the PBS script.
Note
Make sure to inspect and alter the provided pbs file for your system. If you are using NAS resources, make sure to set the group_list to the correct value.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
Monitoring Convergence
You can visualize the residual history using the plotHist.py utility:
This plots the L2 norm of the residual versus pseudo-time step number on a logarithmic scale. For a detailed overview of plotHist, see the plotHist documentation. Your convergence history should be similar to:
The run stops at the relative tolerance of \(10^{-7}\) after about 160 steps. Near \(2\times10^{-6}\) the residual stops falling at any CFL: in the cells that close the boundary layer at the trailing edge, the assembled Jacobian no longer gives a good Newton direction. The solver then switches the flow equations to a matrix-free linearization, here at step 141, and reports it in the log (Implicit: the flow linearization is matrix free from step ...; see Implicit Stepping). Each GMRES iteration then costs one residual evaluation, so the few steps after the switch are slower. The integrated forces converge well before the residual does:
Pressure Coefficient Along Span Cuts
The computeSurfaceCuts.py script provided with LAVA can be used to process line cuts of surface data along user-defined span locations:
Please see the computeSurfaceCuts.py documentation for more details about the tool usage if needed.
The script will write-out:
surface/cutdata.dat- File containing pressure and skin friction coefficient data along the cuts, from the latest surface solutionsurface/figures/surface_plot.png- Image depicting cut locations (see below)
Once the cut data is extracted, the plots against the experimental data can be produced with the provided script:
This will create \(C_P\) comparison plots at all 7 span locations under the cp_plots directory. Two of the generated plots are shown below:
References
NASA Langley Research Center, "ONERA M6 Wing - Turbulence Modeling Resource," Available: https://turbmodels.larc.nasa.gov/onerawingnumerics_val.html
JAXA Wing Body RANS
The JAXA Wing Body was part of the Sonic Boom Prediction Workshop 2 (SBPW2) test cases.
This Reynolds-Averaged Navier-Stokes (RANS) simulation involves the JAXA Wing Body at \(\mathrm{Mach}=1.6\), \(\mathrm{Re}=5.7\times10^6\) and \(\alpha=2.3067^\circ\) where the angle of attack is built-in to the geometry. More details about the case can be found in the README document.
The near field mesh generated with STAR-CCM+ is provided. The mesh is extruded with Mach-aligned prism cells using a LAVA utility.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| jaxa_wing_body.cgns | Near-field mesh, arbitrary polyhedral (6.0 GB) |
| jwb_extrude.inputs | Input file for the Mach-aligned extrusion tool |
| jaxa_wing_body_extruded.cgns | Optional: the near-field mesh with the Mach-aligned extrusion, ready for the solver (9.6 GB) |
| unst_jaxa_wing_body.inputs | Solver input file |
| job_tur_ath.pbs | Sample PBS file for the solver run on NAS Athena nodes |
Directory Setup
Create a working directory for this tutorial with separate folders for meshing and simulation:
Place the downloaded files in the appropriate folders:
jaxa_wing_body.cgns→meshing/jwb_extrude.inputs→meshing/unst_jaxa_wing_body.inputs→run/jaxa_wing_body_extruded.cgns, if you downloaded it →run/
If you are running on NASA's NAS systems, also place the PBS scripts:
job_tur_ath.pbs→run/
Warning
Make sure to replace the #PBS -W group_list=<your project group ID> line with the correct group id you will use
Meshing
The near-field mesh is generated using STAR-CCM+ with arbitrary polyhedral cell type. Prism layers at wall boundaries start with the first layer cell centers located at ~ \(3\times10^{-4}\) m. The airplane is enclosed in a tight cylindrical outer boundary:
To propagate the near-field boom signal to the mid-field with minimal signal dissipation, a Mach-aligned extrusion from the near-field cylindrical outer boundary is performed. If you downloaded the extruded mesh, it is the result of this step and you can continue with the Solver Inputs.
Executable Names
The executable name varies by architecture. See the LAVA Installation Guide for details.
This will create the extruded mesh and save it as jaxa_wing_body_extruded.cgns which we will use for the solution. Link this file to the run directory:
Solver Inputs
The run is set up as steady with implicit time integration. The local CFL number starts at 1 and the solver adapts it from step to step; the input sets no maximum CFL, so the default safety limit of \(10^4\) applies (see Implicit Stepping). Numerical Jacobians are used for the Navier-Stokes and the turbulence model equations.
The simulation stops once the continuity equation residual has dropped by 7 orders of magnitude, or below \(10^{-12}\) in absolute terms:
\(2^\mathrm{nd}\) order MUSCL scheme with the HLLE-CLM flux function and the rminmod limiter is used for the convective fluxes:
Spalart-Allmaras turbulence model is used. The linear systems of both the Navier-Stokes and the turbulence model equations are solved with up to 40 GMRES iterations to a relative tolerance of \(10^{-3}\):
navier stokes {
viscous = true
maximum iterations = 40
relative tolerance = 1.e-3
}
turbulence {
model = sa
maximum iterations = 40
relative tolerance = 1.e-3
}
To extract the on-track boom signature at \(2.55\) body lengths below the airplane, we set up a line probe:
lineprobe_1 {
# On track, H/L = 2.55
start = [114., -1e-6, -98.8635];
end = [172., -1e-6, -98.8635];
number of points = 1000;
interval = 500;
}
For the downstream outflow boundary condition, a sponge layer is added to avoid reflections:
# BC_1 : domain.plane
# BC_2 : domain.outer_cylinder
# BC_3 : domain.symmetry
# BC_4 : domain.outflow
# BC_5 : domain.inflow
BC_1 {type = wall}
BC_2 {type = farfield}
BC_3 {type = symmetry}
BC_4 {type = farfield; sponge layers = 1}
BC_5 {type = farfield}
Running the Simulation
The following example is for running on NAS's Athena system using AMD Turin nodes. From pfe, log in to the Athena front end (athfe01) and submit the PBS script.
Note
Make sure to inspect and alter the provided pbs file for your system. If you are using NAS resources, make sure to set the group_list to correct value.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)line_probe/- Flow field data along line probes defined in the input file (001.Unst.#########.lineforline probe_1)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
Monitoring Convergence
To view the relative residual and CFL histories, use the plotHist tool.
plotHist.py ns l2resr0 l2turbresr0 -doLogy -showGrid major
plotHist.py -doLogy ns cfl -showGrid major
The continuity residual reaches the relative tolerance of \(10^{-7}\) after 176 steps. The adaptive CFL climbs to about 3,000 in the first 20 steps, is cut back to between about 300 and 1,200 while the residual levels off, then grows to the \(10^4\) safety limit by step 135; the turbulence model's CFL (cfltur) follows the same history. The line probe is also written at the end of the run, whatever its output interval.
Line Probe
The line probe output is an ASCII file with the variables defined in the file header. The on-track boom signature at the end of the run can be plotted by calculating \(\Delta P/P_{\infty} = (P-P_{\infty})/P_{\infty}\):
The reference quantities to be used for normalization are output to screen and captured into the run.log file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reference Conditions:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.... Reference Pressure = 2.7461575525871865e+02
.... Reference u-velocity = 4.7206975934000525e+02
.... Reference v-velocity = -0.0000000000000000e+00
.... Reference w-velocity = 0.0000000000000000e+00
.... Reference Temperature = 2.1665000000000001e+02
.... Reference Mach = 1.6000000000000001e+00
.... Reference Speed of Sound = 2.9504359958750325e+02
.... Reference Density = 4.4165290347451249e-03
.... Reference Enthalpy (specific) = 2.1762681414387736e+05
.... Reference Gamma = 1.3999999999999999e+00
.... Reference Cp = 1.0045087197963413e+03
.... Reference Area = 3.2799999999999997e+01
.... Reference Length = 3.8700000000000003e+01
.... Reference Span = not defined
.... Reference Time = 8.1979409259567870e-02
.... Reference DX = 1.0000000000000000e+00
.... Reference Thermal Conductivity = 2.0313233035308541e-02
.... Reference Dynamic Viscosity (mu) = 1.4155440211209772e-05
.... Reference Kinematic Viscosity = 3.2051052081505617e-03
.... Reference Reynolds Number = 5.7000000000000000e+06
.... Reference Dynamic Pressure = 4.9211143342362402e+02
Genesis Capsule WMLES
Density gradient magnitude in logarithmic scale on the \(y=0\) crinkle surface probe at 100 CTU
This tutorial outlines a Wall-Modelled Large Eddy Simulation (WMLES) setup of the Genesis sample return capsule as tested in the Aeroballistic Research Facility at Eglin AFB. The test details and results are summarized by Cheatwood et al.1. Although ballistic test flight speed varies during the trajectory, the simulation is setup based on an average \(\textrm{Mach}=1.44\), \(\textrm{Re}=2.3\times10^6\) condition. Model geometry for the simulation is setup as full scale whereas the ballistic test was done with \(0.047\) scale model.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| genesis_capsule_surface_tri.cgns | Surface geometry triangulation |
| voro_genesis_capsule.yml | Voronoi meshing input file |
| unst_genesis_capsule.inputs | Solver input file |
| job_gh200.pbs | Sample PBS file for the solver run on NAS GH200 nodes |
Directory Setup
Create a working directory for this tutorial with separate folders for meshing and simulation:
Place the downloaded files in the appropriate folders:
voro_genesis_capsule.yml→meshing/genesis_capsule_surface_tri.cgns→meshing/unst_genesis_capsule.inputs→run/
If you are running on NASA's NAS systems, also place the PBS scripts:
job_gh200.pbs→run/
Warning
Make sure to replace the #PBS -W group_list=<your project group ID> line with the correct group id you will use
Meshing
The Voronoi meshing input for the Genesis capsule specifies a telescoping refinement zone around the whole capsule, a finer wall layer on the front shell, shoulder and side, and a cylindrical wake refinement region reaching about 3.6 diameters behind the capsule. The zones gradually coarsen towards the farfield, which lies about 4D upstream of the nose, 8D to each side and 17D behind the capsule.
To generate the mesh using the LAVA Voronoi generator, navigate to the meshing/ directory and generate the mesh:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
PBS Setup on NAS
If running on NAS systems, ensure that you have read the Running On NAS Guide for example PBS setup scripts.
Note
The provided Voronoi input file will generate a coarser mesh than required for mesh insensitive results. You can reduce the reference_length parameter in the voro_genesis_capsule.yml for finer meshes, and adjust reference dx and diagnostics target size filter parameters in the solver inputs for finer resolution.
This generates voro_genesis_capsule.cgns in the current directory. Link this file to the run directory:
Solver Inputs
The simulation runs for finish ctu convective time units (CTU, based on the capsule diameter) using a \(3^\mathrm{rd}\) order accurate explicit time integration. The sync steps per ctu entry sets a sync clock: the CFL-limited time steps are clipped so that the solution lands exactly on 40 evenly spaced marks per CTU, and the snapshot and probe output intervals count these sync steps, so the outputs are uniformly spaced in time (see Sync clock).
time {
steady = false
finish ctu = 100
initial cfl = 0.05
cfl = 2.
sync steps per ctu = 40 # outputs land on uniformly spaced marks, 40 per CTU
}
unst {
explicit {
method = ssprk33
}
}
The diagnostics section filters cells that are smaller than intended, up to max percent filtered percent of the cells, so that they do not restrict the explicit time step. By default, each filtered cell is merged with a neighbouring cell into a single control volume (see Diagnostics). The target size filter is the smallest cell the Voronoi sizing regions place, the reference_length of the provided voro_genesis_capsule.yml Voronoi input file.
The KEEPBLEND scheme, which blends a kinetic energy preserving central flux and a MUSCL reconstructed upwind flux is utilized. The upwind blending is controlled by two sensors. strain keeps the scheme upwind wherever the flow is irrotational and hands over to the central flux only inside resolved vortical structures in the wake. neumann adds full upwinding at the bow shock. This pairing is the intended setting for a supersonic scale-resolving case (see Convective Terms): outside vortices and shocks the scheme is upwind, inside a resolved vortex it is central.
convective terms {
scheme = KEEPBLEND
order = 2
limiter = rminmod
flux function = ausmpw+
upwind blending sensors = [strain, neumann]
}
Flow Field Outputs
Two surface probes sample the flow on planes through the capsule axis. The first slices every cell the \(z=0\) plane cuts into a polygon, the default; the second writes the mesh faces just below the \(y=0\) plane (crinkle = true), which keeps the original cell faces of the mesh visible (see Surface Probe):
# Plane z = 0: every cell it cuts, sliced into a polygon, every CTU
surface probe_1 {
point = [0., 0., 0.]
normal = [0., 0., 1.]
variables = [q, mach, densitygradmag]
interval = 40
}
# Plane y = 0 as the mesh faces just below it (crinkle), every CTU
surface probe_2 {
point = [0., 0., 0.]
normal = [0., 1., 0.]
crinkle = true
variables = [q, mach, densitygradmag]
interval = 40
}
A Q-criterion iso-surface shows the vortical structures of the near wake. Gathered outputs are buffered in memory and written together; output buffer interval isos sets how often the buffered iso-surfaces are written (see Buffered surface outputs):
# Buffered iso-surfaces are written together every 20 CTU
output buffer interval isos = 800
# Q-criterion iso-surface in the near wake, every 5 CTU
isosurfaces_1 {
contour = qcriterion
isovalue = 1e5 # about (U/D)^2
colorfields = [umag]
interval = 200
clipbox_1 { lo = [0.5, -2., -2.]; hi = [7., 2., 2.] }
}
Running the Simulation
Following example is for running on NAS's GH200 system. From pfe front-end, login to Cabeus Grace Hopper front end (cghfe01 or cghfe02) and submit the PBS script.
The provided PBS file runs one MPI rank per GPU on four nodes; the 27 million cells of the mesh take about 40 seconds per CTU, so the 100 CTU run in under an hour and a half including the output.
Note
Make sure to inspect and alter the provided pbs file for your system. If you are using NAS resources, make sure to set the group_list to correct value.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
volume/- Volume solution files in CGNS format (Unst.vol.#########.cgns, each linking to the grid fileUnst.vol.meshLink.#########.cgns)surface/- Surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)surf_probe/- Surface probe output: the \(z=0\) slice (001.Unst.#########.cgns) and the \(y=0\) crinkle faces (002.Unst.#########.cgns)isosurface/- Q-criterion iso-surface of the near wake (surf01_qcriterion_isoVal*_ColorUmag_#########.cgns)
The volume files contain the complete flow field solution and can be visualized using tools such as ParaView or Tecplot. For convenience, LAVA creates symbolic links (volume/Unst.volLatest.cgns, surface/Unst.surfLatest.cgns) that always point to the most recent solution files.
Drag Convergence
The integrated drag is written to the monitor file. Plot the drag coefficient over convective time with the plotHist.py utility. -xRange leaves out the impulsive start, and -checkConv shades the initial transient it detects, marks the mean and standard deviation of the rest of the run and prints a statistical report with the uncertainty of the mean (see the plotHist documentation):
The drag relaxes slowly while the wake develops and settles after about 50 CTU, then fluctuates around \(C_D \approx 1.42\) with a standard deviation of about 0.003. The transient takes half of the 100 CTU run and the drag decorrelates over several CTU, so the rest of the run holds only a handful of independent samples: -checkConv reports the mean as not yet converged and suggests how much longer to run. A larger finish ctu, restarting from the last restart file, tightens the statistics.
Near-Wake Vortices
The Q-criterion iso-surface at 100 CTU, colored by velocity magnitude, with the half facing the viewer cut away at \(y=0\). The shear layer separates at the shoulder and encloses a slow recirculation region behind the capsule; downstream, the wake fills with fine turbulent structures:
References
-
Cheatwood, F., Winchenbach, G., Hathaway, W., and Chapman, G., "Dynamic Stability Testing of the Genesis Sample Return Capsule," 38th aerospace sciences meeting and exhibit. https://doi.org/10.2514/6.2000-1009 ↩
CRM-HLS WMLES (HLPW6 Case 1)
Q-criterion iso-surface, \(Q=10^5\,\mathrm{s}^{-2}\), colored by Mach number at 60 CTU
This tutorial sets up a Wall-Modelled Large Eddy Simulation (WMLES) of Case 1 of the 6th AIAA High Lift Prediction Workshop (HLPW6) with the LAVA Unstructured solver and the LAVA Voronoi mesher. The geometry is the simplified high-lift common research model (CRM-HLS), built from a constant sectional profile cut of the full configuration CRM-HL. The geometry includes the main element, a slat, a semi-span flap and several slat bracklets. The flow conditions are \(\mathrm{Mach}=0.2\) and \(\mathrm{Re}=3.55\times10^6\) based on the mean aerodynamic chord, at an angle of attack of \(\alpha=30^{\circ}\).
Mesh resolution
The tutorial uses the coarse L9 mesh level so that it runs in about six hours on two GPU nodes. The best-practice level for this case is L11, whose finest surface spacing is 4x smaller. The mesh levels differ only in the reference_length of the Voronoi input file (see Voronoi Meshing), reference dx and diagnostics target size filter parameters of the unstructured solver inputs.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- LAVA Voronoi mesher installed — see Voronoi Installation Guide
- Basic familiarity with LAVA input file structure — see Unstructured Solver Inputs
Tutorial Files
Download the input files for this tutorial:
| File | Description |
|---|---|
| CRM_HLS_HLPW6_TC1_v3_voro.cgns | Surface geometry triangulation |
| voro_hlpw6_case1_L9.yml | Voronoi meshing input file |
| voro_rom.pbs | Sample PBS file for Voronoi mesh generation on NAS Rome nodes |
| unst_hlpw6_case1.inputs | Solver input file |
| bl_seeds.dat | Wall points of the boundary-layer profiles |
| job_gh200.pbs | Sample PBS file for the solver run on NAS GH200 nodes |
Directory Setup
Create a working directory for this tutorial with separate folders for meshing and simulation:
Place the downloaded files in the appropriate folders:
CRM_HLS_HLPW6_TC1_v3_voro.cgns→meshing/voro_hlpw6_case1_L9.yml→meshing/voro_rom.pbs→meshing/unst_hlpw6_case1.inputs→run/bl_seeds.dat→run/job_gh200.pbs→run/
Warning
Make sure to replace the #PBS -W group_list=<your project group ID> line in the PBS files with the group id you will use.
Meshing
Geometry and Componenting
The geometry is defined by a watertight surface triangulation in CGNS format. Its components define the surface sizing regions of the mesher, the boundary condition regions of the solver and the force/moment integration groups. The wing root is extruded past the symmetry plane (\(y=0\)) so that the geometry intersects the domain boundary cleanly; that extrusion is component 1 and is clipped away by the mesher. The remaining components become the wall boundaries of the volume mesh:
The surface triangulation only has to represent the geometry and carry the componenting. A common practice is to keep its edges no longer than half of the finest Voronoi spacing.
Voronoi Meshing
The domain is a box from \(-150\) to \(150\) m in \(x\), \(-75\) to \(75\) m in \(z\), and \(0\) to \(150\) m in \(y\), where \(y=0\) is the symmetry plane:
- name: farfield
type: cube
seed: bodycentered
spacing_rel: [10000, 10000, 10000]
distance: [300, 150, 150]
center: [0, 75, 0]
The mesh is refined towards the geometry in two parts. The fine-telescope refinement covers every component with telescoping layers that start at twice the reference_length, hold 8 cells across each layer and double the spacing from one layer to the next. The xfine-inner refinement adds a 4-cell layer at the reference_length itself on the flap upper surface and cove, the brackets, the wing tip, the wing upper surface and leading edge, and the slat (components 3-6 and 8-10):
refinements:
- name: fine-telescope
seed: bodycentered
smoothing_layers: 3
level_points_per_thickness: 8
level_spacing_inner_rel: 2
level_spacing_outer_rel: 10000
level_spacing_growth_rate: 2
components: 1-10
- name: xfine-inner
seed: bodycentered
smoothing_layers: 3
level_points_per_thickness: 4
level_spacing_inner_rel: 1
level_spacing_outer_rel: 1
level_spacing_growth_rate: 2
components: 3-6,8-10
All spacings are relative to reference_length, so the mesh levels are set by that single parameter. The provided file uses the L9 level, \(1.488\) mm, about one 512th of the mean aerodynamic chord, which gives about 15.6 million cells; the input file lists the L10 and L11 values as comments.
The view below shows the Voronoi cells around the slat and the main-element leading edge, on a spanwise plane through a slat bracket. The cells on the near side of the plane are removed, and the whole cells that cross it are shown, colored by the instantaneous Mach number; the walls behind the plane are gray:
Generate the mesh in parallel. On NAS Rome nodes, the L9 mesh takes about 45 minutes on the two nodes the provided PBS file requests:
Executable Names
The Voronoi executable name varies by architecture. See the Voronoi Installation Guide for details.
This generates voro_hlpw6_case1_L9.cgns. Link it to the run directory:
Solver Inputs
For a detailed description of all solver input parameters, see the Unstructured Solver Inputs section. The input file is set up in SI units, at the scale of the wind-tunnel model: the reference length is the mean aerodynamic chord.
reference conditions {
mach = 0.2
Re = 3.55e6
temperature = 288.15 # K
alpha = 30
beta = 0.00
length = 7.62000000E-01 # m, mean aerodynamic chord
area = 1.39354560E+00 # m2
}
The simulation runs for finish ctu convective time units (CTU, based on the mean aerodynamic chord) with a \(3^\mathrm{rd}\) order explicit Runge-Kutta scheme at a CFL number of 2.5. The sync steps per ctu entry sets a sync clock: the time steps are clipped so that the solution lands exactly on 100 evenly spaced marks per CTU, and the snapshot and probe output intervals count these sync steps (see Sync clock). On the L9 mesh one CTU takes about 5400 time steps.
time {
steady = false
finish ctu = 60
initial cfl = 0.05
cfl = 2.5
sync steps per ctu = 100 # outputs land on uniformly spaced marks, 100 per CTU
}
Cells smaller than intended would restrict the explicit time step. The target size filter is the reference_length of the mesh, and the cells the filter flags are merged with a neighbouring cell into a single control volume (see Diagnostics); on the L9 mesh 160 cells are merged this way and no problem cells remain.
diagnostics {
target size filter = 1.48828125E-03 # the mesher's reference_length
max percent filtered = 0.05
}
Numerics and Models
The KEEPBLEND scheme blends a kinetic energy preserving central flux with a MUSCL reconstructed upwind flux. The strain sensor keeps the scheme upwind where the flow is irrotational and hands over to the central flux inside resolved vortical structures (see Convective Terms). The subgrid scale eddy viscosity is modelled with the constant coefficient Vreman model. The walls use the blendedlog wall function. With do transition = true the wall function detects the level of resolved turbulence next to each wall face: below the transition threshold the face switches to a no-slip condition, above it the face takes the turbulent wall stress of the wall function (see Wall Function).
convective terms {
scheme = KEEPBLEND
order = 2
limiter = rminmod
flux function = ausmpw+
upwind blending sensors = [strain]
}
navierstokes {
viscous = true
}
turbulence {
sgs model = vreman
sgs const = 0.08
}
wall function {
type = blendedlog
do transition = true
transition threshold = 0.05
}
Outputs
The time averages start once the initial transient has passed. With the exponential method, samples older than the 20 CTU window have a diminishing influence (see Time Averaging):
The boundary surfaces carry the instantaneous and the time-averaged wall quantities; turbulence is the resolved turbulence level the wall function detects at each wall face:
# Boundary surfaces with the time averages every 10 CTU
surface {
interval = 1000
variables = [q, mach, tauw, pcoef, cf, qavg, yplusavg, tauwavg, turbulence]
}
The forces and moments are integrated over all wall components together (wing) and, with do individual comps = true, over each component separately:
# Integrated forces and moments (time steps)
loads {
moment center = [8.84128280E-01, 0.0, 0.0]
interval = 10
normalize = true
gauge = true
do individual comps = true
group_1 {name = wing; include = [1-9]}
}
A wall-normal line probe samples boundary-layer profiles at the wall points listed in bl_seeds.dat, seven surface probes slice the flow at spanwise stations, and a Q-criterion iso-surface shows the vortical structures (see Output and Probes). Gathered outputs are held in memory and written together at the interval output buffer interval surf sets:
# Wall-normal boundary-layer profiles at the points listed in bl_seeds.dat, every CTU
line probe_1 {
wall normal = true
file = bl_seeds.dat # one "x y z" per line
height = 0.0762 # length of each profile (m)
initial spacing = 0.0001860351565 # spacing of the profile points (m)
growth rate = 1.
interval = 100
output qstats = true
name = bl_probe
}
# Spanwise stations: every cell the plane y = const cuts, sliced into a polygon, every CTU
surface probe_1 {point = [0., 0.025, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
surface probe_2 {point = [0., 0.050, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
surface probe_3 {point = [0., 0.781168653, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]} # through a slat bracket
surface probe_4 {point = [0., 1.000, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
surface probe_5 {point = [0., 1.250, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
surface probe_6 {point = [0., 1.500, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
surface probe_7 {point = [0., 1.750, 0.]; normal = [0, 1, 0]; interval = 100; variables = [q, mach, qstats]}
# Buffered surface and probe outputs are written together every 10 CTU
output buffer interval surf = 1000
# Q-criterion iso-surface colored by Mach number, every 10 CTU
isosurfaces_1 {contour = qcriterion; isovalue = 1e5; colorfields = [mach]; interval = 1000}
Boundary Conditions
# BC_1 : flap_lower
# BC_2 : flap_upper
# BC_3 : flap_cove
# BC_4 : brackets
# BC_5 : wing_tip
# BC_6 : wing_lower
# BC_7 : wing_upper
# BC_8 : wing_le_upper
# BC_9 : slat
# BC_10 : zMin
# BC_11 : yMin
# BC_12 : xMin
# BC_13 : yMax
# BC_14 : xMax
# BC_15 : zMax
BC_1 {type = wallfunction}
BC_2 {type = wallfunction}
BC_3 {type = wallfunction}
BC_4 {type = wallfunction}
BC_5 {type = wallfunction}
BC_6 {type = wallfunction}
BC_7 {type = wallfunction}
BC_8 {type = wallfunction}
BC_9 {type = wallfunction}
BC_10 {type = farfield}
BC_11 {type = symmetry}
BC_12 {type = farfield}
BC_13 {type = farfield}
BC_14 {type = farfield}
BC_15 {type = farfield}
Running the Simulation
The following example is for NAS GH200 nodes. From a pfe front end, log in to a Cabeus Grace Hopper front end (cghfe01 or cghfe02) and submit the PBS script:
The provided PBS file runs one MPI rank per GPU on two nodes. On the L9 mesh one CTU takes about 6 minutes of wall-clock time, so the 60 CTU take about six hours.
PBS Setup on NAS
If running on NAS systems, ensure that you have read the Running On NAS Guide for example PBS setup scripts.
Output and Results
LAVA creates several subdirectories to organize the simulation output:
surface/- Boundary surface solution files and boundary condition statistics (Unst.surf.#########.cgns,bc_stats.iter)surf_probe/- The spanwise station slices (001.Unst.#########.cgnsto007.Unst.#########.cgns)line_probe/- The boundary-layer profiles (bl_probe.001.Unst.#########.line)isosurface/- The Q-criterion iso-surface (surf01_qcriterion_isoVal*_ColorMach_#########.cgns)restart/- Restart files for continuing simulations (Unst_restart.#########.hdf5)monitor/- Time-stepping and iteration monitoring data (Unst.data.iter)
With the sync clock, the number in the snapshot and probe file names is the sync step, 100 per CTU.
Force and Moment Convergence
The integrated loads are written to the monitor file. Plot the lift, drag and pitching moment coefficients over convective time with the plotHist.py utility. -xRange leaves out the impulsive start, and -checkConv shades the initial transient it detects, marks the mean and standard deviation of the rest of the run and prints a statistical report with the uncertainty of each mean (see the plotHist documentation):
The transient lasts about 15 to 20 CTU; the lift overshoots before it settles and the pitching moment settles last. The time averages of the surface and probe outputs start at CTU 30, after this transient.
Surface Flow
The instantaneous streamwise skin friction coefficient on the upper surfaces at the last output:
The resolved turbulence level the wall function detects shows where the boundary layers are turbulent. The faces below the transition threshold of 0.05, where the no-slip condition is used, are black:
The spanwise station slices carry the instantaneous and the time-averaged flow. The slice through the slat bracket:
References
AIAA High Lift Prediction Workshop 6, "Test Cases," Available: https://aiaa-hlpw.org/HLPW6/cases
Cartesian User Guide
Introduction
The Cartesian solver within LAVA solves the compressible Navier-Stokes equations on blocks of cubic cells with octree-type refinement. Objects embedded in the mesh are accounted for via a sharp immersed boundary ghost-cell method. The solver supports numerical schemes geared toward performing wall-modeled large-eddy simulations (WMLES). A high-level overview of its capabilities compared to other LAVA solvers is provided in the LAVA Introduction; a list of publications is maintained on the Publications page.
New users can get a first simulation running in minutes with the Quick Start.
Grids
The grid is a block-structured forest of octrees: the domain is divided into boxes of cubic cells, locally refined with a fixed 2:1 ratio between levels. Meshing is fully automatic and happens inside the solver — there is no separate meshing step:
- Automatic initial mesh generation based on user-defined surface and volume zones with target cell sizes, including telescoping refinement regions
- Automatic and on-the-fly error-metric based adaptive mesh refinement
Grid setup, refinement regions, and adaptive refinement are documented in Block-Structured Octree Meshing.
Numerical Scheme
The solver uses a conservative finite difference discretization of the compressible Navier-Stokes equations with explicit Runge-Kutta time integration. The convective scheme first interpolates cell-centered primitive variables (pressure, velocity, temperature, species mass fractions) to face centers with upwind/downwind biased stencils. The interpolated left and right primitive state vectors are then blended together based on physics-based and grid-based sensors to achieve lower numerical dissipation. The face flux is then computed with an approximate Riemann solver. Higher order and lower dispersion is achieved via the hybrid weighted compact non-linear scheme (HWCNS) approach which augments the face fluxes with the physical fluxes at surrounding nodes (overall stencil remains the same). We also offer a kinetic energy and entropy preserving (KEEP) scheme variant where the non-dissipative flux is blended with an approximate Riemann solver flux using a choice of sensors.
Turbulence Models
- Constant coefficient Vreman subgrid scale model for LES closure
- Musker's and blended-log wall models
- Flow tripping via localized source terms
Multi-species and Multi-phase
- Multi-species (non-reacting) capability
- Multi-phase (non-reacting) capability — see the Cartesian Multiphase Solver
Additional Models
- Actuator zone propulsion model
- Support for thin porous surfaces via a Darcy-Forchheimer immersed boundary condition
- Fluid-structure interaction with geometrically nonlinear shell and beam elements
In-situ Post Processing
Several in-situ post-processing options are available — see Output and Probes:
- Loads: integrated forces and moments over custom user-defined component groups
- Solution sampling on cut planes, point clouds, lines, or arbitrary triangulations
- Iso-surfaces of primitive and derived flow quantities (e.g. Q-criterion, density gradient magnitude) output as triangulated surfaces
- Separate output of volume (parallel) and surface (buffered or parallel) solutions
Hardware
LAVA Cartesian is compatible with Intel, AMD and ARM based CPU systems as well as NVIDIA GPU systems.
Quick Start
This guide takes you through your first LAVA Cartesian simulation in a few minutes: the Taylor–Green vortex, a canonical transition-to-turbulence case in a periodic box. It needs no geometry, no mesh refinement, and 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 Cartesian executable (any
3D NS1build). - Python with matplotlib for the
plotHist.pyutility.
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
with the corresponding pressure field
We run the classic configuration of Carton de Wiart et al. (2014): Reynolds number 1600, Mach number 0.1, on a uniform \(64^3\) grid — a deliberately coarse resolution where the quality of the numerical scheme is visible.
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 lands at \(t^* = 9.0\) as in the reference DNS, with its magnitude a few percent high, which is the expected coarse-grid behavior. Grid and scheme refinement studies are what the rest of the documentation is for.
Tutorial Files
Download the two input files into a working directory:
| File | Description |
|---|---|
| tgv.inputs | solver input file |
| tg.spec | gas/species definition (sets the viscosity, i.e. the Reynolds number) |
The Input File
The complete input file:
# LAVA Cartesian quick start: the Taylor-Green vortex.
# A periodic box with no geometry; the initial condition is built into the solver.
exact flow name = taylorgreenvortex
time {
steady = false
number of steps = 7900 # roughly 20 convective time units at CFL 0.8
cfl = 0.8
}
solver defaults {
explicit { method = ssprk33 } # 3rd-order strong-stability-preserving Runge-Kutta
}
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)
}
cartesian {
convective terms {
scheme = hwcns # low-dissipation central scheme
fluxfunction = ausmpw+
limiter = none
centralcomponents = [q]
fluxorder = 2
}
navier stokes {
viscous = true
viscous order = 2
}
output {
monitor {
interval = 10
variables = [nt, time, ctu, dt, maxcfl, maxmach, integratedke, integratedentropy, mups]
}
flow_stats {
interval = 10
}
surface probe_1 { # mid-plane cut for visualization
point = [0.5, 0.5, 0.5]
normal = [0, 0, 1]
interval = 500
variables = [q]
format = vtk
}
isosurfaces_1 { # Q-criterion iso-surface, colored by velocity magnitude
contour = qcriterion
isovalue = 5.0
colorfields = [umag]
interval = 500
format = vtk
}
}
bcs {
domain face type lo = [periodic, periodic, periodic]
domain face type hi = [periodic, periodic, periodic]
}
grid {
number of levels = 1
first level dimension = [64^3]
domain min = [0.0, 0.0, 0.0]
domain max = [1.0, 1.0, 1.0]
max box size = 8
}
}
Walking through it block by block:
exact flow nameselects one of the analytic initial conditions built into the solver — no restart or geometry files needed.timerequests an unsteady run with an adaptive time step atcfl = 0.8; the step count corresponds to roughly 20 convective time units.solver defaultspicks the explicit third-order strong-stability-preserving Runge–Kutta scheme.reference conditionsset the nondimensionalization: with \(V_0 = 1\), the reference temperature gives Mach 0.1, and the referencelengthof \(1/(2\pi)\) makes one convective time unit (thectumonitor column) equal to one classic Taylor–Green time unit. The referencelengthanddxalso scale relative grid inputs — see The Three Spacing Inputs.fluidpoints totg.spec, a calorically perfect gas with a constant viscosity of \(1/1600\) — which is the Reynolds number definition for this nondimensionalization.convective termsselect the low-dissipation central scheme (hwcns); on this coarse grid a dissipative scheme would visibly damp the vortices.outputwrites a monitor line every 10 steps (with the integrated kinetic energy fromflow_stats), a mid-plane cut, and a Q-criterion iso-surface colored by velocity magnitude every 500 steps for visualization. Cut planes can also be extracted through the iso-surface machinery withcontour = cutplane— see Output and Probes.bcsmake all six domain faces periodic.gridbuilds a uniform single-level \(64^3\) lattice on the unit cube — the outside-in grid specification described in Block-Structured Octree Meshing. Everything on that page (refinement regions, telescoping, AMR) starts from exactly this kind of block.
Running the Case
From the working directory, run on two MPI ranks with a few OpenMP threads each (any lavacart 3D NS1 executable works; adjust the name to your build):
On CPUs this small case takes on the order of 10 minutes depending on the machine and build (reduce number of steps for a faster first look); on a single GPU it finishes in about two minutes — see below. While it runs, the monitor table reports the state every 10 steps (this excerpt is from the GPU variant):
=========================================================================================================================
Time | Time | CTU | Time | Max | Max | Integrated | Integrated | Million |
step | (s) | (Non-dim T) | step size | CFL | Mach | Kinetic | Entropy | Updates/Sec |
(200) | | | (s) | | | Energy | | n=10 |
-------------------------------------------------------------------------------------------------------------------------
nt | time | ctu | dt | maxcfl | maxmach | integratedke | integratedentropy | mups |
=========================================================================================================================
0 0.0000e+00 0.0000 1.2500e-02 0.8000 0.0996 7.8540e-01 2.2202e+01 0.0020 CFL_GPU FlowStats_GPU inputs^2 iso opt surf
10 4.0320e-03 0.0253 4.0320e-04 0.8000 0.0997 7.8532e-01 2.2202e+01 51.0310 CFL_GPU^10 FlowStats_GPU write-iso-buff-1 write-surf-buff-1
20 8.0641e-03 0.0507 4.0321e-04 0.8000 0.0997 7.8525e-01 2.2202e+01 39.3684 CFL_GPU^10 FlowStats_GPU
30 1.2096e-02 0.0760 4.0321e-04 0.8000 0.0998 7.8518e-01 2.2202e+01 25.2952 CFL_GPU^10 FlowStats_GPU
40 1.6128e-02 0.1013 4.0321e-04 0.8000 0.0998 7.8510e-01 2.2202e+01 57.3858 CFL_GPU^10 FlowStats_GPU
Running on a GPU
LAVA Cartesian also runs on NVIDIA GPUs. Add an (empty) gpu { } block inside the cartesian { } section and use a GPU executable from an NVIDIA tarball (see Available Executables):
In this example the single-GPU run sustained about 22 million cell updates per second (the mups monitor column) — roughly an order of magnitude faster than the CPU run of this small case, and the gap grows with grid size. GPU-specific tuning knobs are described under GPU Options.
Checking the Run
The monitor history is stored in monitor/Cart.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:
The figure below shows the integrated kinetic energy of this run and its decay rate \(-\mathrm{d}KE/\mathrm{d}t\) — the classic Taylor–Green result: the energy is nearly conserved while the vortices merely deform, then transition sets in and the dissipation peaks near \(t^* \approx 9\):
The mid-plane cuts written by the surface probe land in surface_probe/ as VTK files (view them in ParaView, or post-process them in Python). The z-vorticity on the mid-plane shows the smooth initial vortex array breaking down into small-scale turbulence:
The isosurfaces_1 block extracts a Q-criterion iso-surface in situ (also as VTK, into isosurface/). At \(t^* = 0\) it shows the smooth initial vortex structure — later snapshots show it rolling up into the dense tangle of worm vortices behind the dissipation peak:
You now have a running LAVA Cartesian setup. From here:
- add refinement regions and adaptive meshing: Block-Structured Octree Meshing
- the full input reference: General Setup, Boundary Conditions, Output and Probes
- cases with geometry: the Diamond Airfoil tutorial
Cartesian Solver Inputs
Cartesian Solver Inputs
Input File Syntax
LAVA utilizes a plain-text input file to specify solver options. The input file is organized in several sections.
Info
All the inputs are interpreted in standard SI units
Most inputs have default values built into the code and can be skipped from the input file if default value is acceptable.
The input file is case-insensitive, with the exception of string entries such as file names. In addition, most white spaces are disregarded with the exception of carriage return.
Input entries are separated by either a semicolon ";" or carriage return. To illustrate, let's look at two examples:
is equivalent to
Note that the order of entries are swapped in the second example.
The file is organized in nested sections that encapsulate logical groups of inputs together. The sections are denoted with a section name followed by an opening curly brace "{" and ending with a closing curly brace "}". Here is an example:
This example shows a section and has one input entry as well as two nested sections both of which have their own inputs entries.
Like ordinary input entries, the order of sections in the input file is not important as long as the nesting hierarchy is correct.
The last piece of relevant syntax is the numbered sections that are utilized to construct numbered lists, suffixed by an underscore "_" followed by item number. One example usage is listing of boundary conditions for the unstructured solver:
Vector entries (or lists) are denoted using brackets:
Lists follow the same format as vectors:
Note that you can specify ranges (inclusive) with dashes as above.
Comment lines can be added to the input file using hash signs # either
in a separate line or in-line with the code:
Fluid Section
The fluid, either a single species, or a mixture of species is specified in the
fluid section:
This example uses perfect air as an equivalent single-species gas. The code is distributed with a database of common gas species. The database is stored in individual "species files" that contain gas properties such as molecular weight, specific heat ratio, viscosity (or Sutherland coefficients), Prandtl number etc...
Available fluid species are: air_perfect, h (hydrogen), o (oxygen), h2,
o2, oh,h2o (water vapor),co and co2. Users can create their own species
definitions.
For multi-species problems, you can specify the mixture composition instead of single species such as:
Info
LAVA currently does not support reacting flows.
Reference Conditions Section
Reference conditions list the reference flow quantities (typically the freestream conditions in external flow problems) as well as the reference area, length and angles (pitch and yaw) in airplane coordinates. These values are used in initial and boundary conditions (unless different conditions are explicitly specified). They are also used to normalize force and moment coefficients.
The reference conditions need to properly specify the thermodynamic state and
velocity field. Typically two of the three thermodynamic quantities (density,
pressure and temperature) need to be specified. Specifying all three of
them will result in an error message as it is an over-specification.
In addition, velocity vector or speed and angles are typically specified.
Here are a few example ways to specify the reference conditions:
reference conditions {
pressure = 1.e5
temperature = 300
velocity = [100.,0.,0.]
area = 1.0
length = 1.0
# If using multi-species, list the mass fractions of each species
mass fractions = [1,0,0]
}
use std atmosphere = true.
reference conditions {
use standard atmosphere = true # false by default
std altitude = 1000
velocity = [100.,0.,0.]
area = 1.0
length = 1.0
# If using multi-species, list the mass fractions of each species
mass fractions = [1,0,0]
}
Info
The thermodynamic condition description for multi-phase is slightly different than for single and multi-species. Please refer to the Cartesian Multiphase Solver page for details.
By default, reference area and length values are unity (1.0) and can be skipped if normalized forces are not needed. Instead of the velocity, we can utilize Mach number and flow angles:
Note that alpha and beta are pitch and yaw angles in degrees. This assumes
that the model is in the airplane coordinate frame (+x: from nose to tail,
+y: along the right wing, +z: from airplane towards the ground). These angles do not
transform the model, but rather set the freestream direction so that the model
is at the desired angles relative to the freestream. Positive alpha
corresponds to pitch up, while positive beta corresponds to yaw towards right.
The following coordinate transform is used in the code to transform
the reference velocity vector to a Cartesian frame.
For launch-vehicle simulations, the flow angle can be specified via alpha, angle of attack, and phi, the roll angle.
This assumes that the rocket model is aligned in the x axis, this +x being from windward to leeward. phi=0 corresponds to
incoming flow aligned to the x-z plane. alpha then indicates the rotation of the incoming flow on the -y axis and phi
the rotation of the incoming flow on the -x axis.
The following coordinate transform is used in the code to transform
the reference velocity vector to a Cartesian frame.
Another way to specify the reference conditions is by using Reynolds number, Mach number and temperature:
Note that thelength is the reference length used in the Reynolds number
definition.
Yet another way to specify the reference conditions is by using dynamic pressure, Mach number, and standard atmosphere.
Using this requires the flag use std atmosphere = true.
reference conditions {
use std atmosphere = true
dynamic pressure = 70000
Mach = 1.4
alpha = 4
beta = 2
}
When the reference length and reference area are specified, the force and moment coefficients (if load output is requested) are normalized using these reference values. For external aircraft aerodynamics, the reference length typically corresponds to the mean aerodynamic chord, while the reference area corresponds to the main wing planform area.
For correct normalization of the rolling and yawing moment coefficients, the aircraft span should be provided as an additional reference quantity. Users may optionally specify the span in the input file. If the span is not provided, the code issues a warning. In this case, the rolling and yawing moment coefficients are normalized using the reference length (typically the mean aerodynamic chord) as a fallback. It is the user's responsibility to ensure that the appropriate normalization is applied if span-based moment coefficients are required.
The dx input represents a characteristic grid spacing value, often indicating the cell size (in meters) in the finest region of the grid. It is not required (default value is 1), but it can make life easier when setting up some of the other input sections (e.g. trip lines, relative grid spacing w.r.t. dx). The role of dx will be described in relevant sections that make use of this parameter.
For multi-species runs, species mass fractions should be specified:
Time Section
The time section specifies whether the run is steady or unsteady, and if unsteady, sets up the extents of step size for the time integration.
In the simplest case of steady runs, the section can be skipped all together or the section can be used just to explicitly state a steady setup:
For unsteady runs, several other entries become revelant. The following example setups
up a case that will run for 1000 time steps with a constant dt.
Alternatively, you can specify stop condition in terms of total time integrated. You can also choose to start the time integration from a non-zero inital time:
Yet another convenient and common way to specify time integration bounds is by utilizing CTUs (Convective Time Unit). A CTU is simply the non-dimensional time normalized by reference flow velocity magnitue and the reference length as specified in the Reference Conditions Section.
Time step size can be specified in terms of CFL instead of a fixed dt as used above. The specifed cfl number is interpreted as the maximum allowed CFL in the whole domain and the corresponding dt value is adjusted automatically.
Here initial cfl value is used in the start-up and cfl gradually climbs until the specified cfl number is met.
Sync clock — uniform sampling with CFL-driven sub-steps (cartesian & unstructured, explicit)
A CFL-driven dt is efficient but makes output snapshots unevenly spaced in physical time, which breaks
FFT-based post-processing (spectra) and makes animations from AMR runs play at varying speed.
The sync clock gives both: the solver keeps taking CFL-limited (or fixed-dt) sub-steps, but they are
clipped so simulation time lands exactly on multiples of a fixed sync step dt_s.
The sync clock is specified in exactly one of four ways, together with exactly one sub-step driver
(cfl or dt):
time {
steady = false
finish ctu = 300
cfl = 2.5 # sub-step driver: cfl (adaptive) or dt (fixed), exactly one
sync steps per ctu = 100 # dt_s = reference time / 100 ... or one of:
# sync dt = 1.646e-4 # dt_s in seconds
# sync ctu = 0.01 # dt_s as a fraction of a CTU
# sync freq = 1.0e5 # sampling rate in Hz (dt_s = 1/f)
}
Notes:
- The sync step size should be larger than the sub-step
dt; if it is smaller, every step lands on a mark and the run behaves like a fixed-dtrun atdt_s. - The landing step of each sync interval takes a clipped (possibly much smaller) dt, so its true CFL
is below the target — always stable. The
maxcflmonitor column always reports the actual measured per-cell maximum, so it dips on landing steps by exactly the clip ratio and sits at the target on interior steps; it never exceeds thecflcondition. Internally the CFL controller pairs each measurement with the dt it was measured at, so the clip cannot make dt overshoot the target on the step after a landing. - Two step counters exist in sync runs:
ntcounts the actual RK sub-steps (as always), andntscounts completed sync steps. The monitor gains thents,dtratio(dt/dt_s) andsubsteps(sub-steps per sync step) columns — only in sync runs; without sync inputs, behavior and output are identical to before. All three columns are always written to the monitor.iterfile; on screen,ntsandsubstepsappear automatically right next tontin sync runs, whiledtratiois shown only if added to the monitorvariableslist. number of stepscontinues to countnt(a safety bound on compute). An unstructured run ends onfinish time/finish ctuby sync step: it stops once the sync step of the mark nearest the finish time is complete,nts = round((finish - start) / dt_s). A finish time off the marks draws a warning and ends the run up to half a sync step early or late. A Cartesian run terminates on physical time, which is a sync mark by construction when composed from CTU inputs.- In sync runs, the snapshot and probe output intervals count sync steps and those outputs only
ever fire on the uniformly spaced marks: volume, surface, isosurface, restart, and the
point/line/surface probes. Output files are labeled with the sync step (so
Cart.vol.000000040.hdf5is at exactly40 * dt_s), probe rows are tagged with the sync step, and volume/CGNS file headers carry async_dtattribute — probe and snapshot series are uniformly spaced in physical time, ready for FFT post-processing without resampling. The per-step series keep counting RK sub-steps (nt) exactly as without the sync clock: the monitor, theloadsinterval (rows labeled withnt) and theflow statsinterval (which feeds the monitor columns) — sointerval = 1samples every sub-step, marks or not. output buffer snapshots(default 100) sets the per-rank snapshot budget buffered between flushes of buffered surface/isosurface output; the automatic memory-pressure fallback still applies.- If a sync run terminates between marks (the
number of stepssafety bound tripped), the forced final volume/surface/probe writes are skipped — an off-grid sample must not enter the uniform series — while the forced final restart is still written, labeled with the RK step (nt) so it never overwrites an at-mark restart file. An unstructured run ending viafinish time/finish ctualways lands on a mark, as does a Cartesian one with those composed from CTU inputs, and the final writes proceed as usual. - Restart files store the sync state, so a restart with the same sync clock resumes the uniform
series exactly, mid-interval included. Changing the sync clock across a restart (e.g.
sync steps per ctu100 -> 300) starts a new sampling segment: the sync stepntsis re-derived from the restart time on the new mark grid, the first step lands on the next new mark, and a warning reports the old and new counts (plus a note when the restart time is not on the new grid, in which case the first interval is partial and the series is uniform from the next mark on). Run such a segment in a new directory: files are labeled withnts, whose scale changes (a decreasing count would overwrite the previous segment's files, and the solver warns). The.itercompanions of the restart file (monitor, bc stats) are read from the restart file's own directory. Two other ways to start a fresh segment from a checkpoint:restart { file = ...; reset time = true; reset nt = true }restarts the physical time, the step counters and the sync step at zero and starts new monitor series (no companion files needed), and an initial-condition file (ic_1 { file = <restart hdf5> }) reads only the flow field. - Cartesian AMR: in sync runs
regrid interval(and theregrid interval on/offwindow) counts sync stepsntsinstead ofnt, and a regrid only ever fires on a step that starts exactly on a sync mark — the mesh never changes inside a sync interval.
- Supported for the cartesian and unstructured solvers with explicit time stepping (subcycling is
not supported). The scheduler's
do dtsets the sub-step dt that the sync clock clips to the marks.
Cartesian Specific Inputs
Cartesian specific inputs are grouped within the cartesian {} section. Every following section here should be included within it.
Numerical Scheme
HWCNS (scheme = hwcns, the default) is the convective scheme of LAVA Cartesian. It is a version of the Hybrid Weighted Compact Non-linear Scheme 1. The face fluxes are computed using the numerical flux (approximate Riemann solver) of the user's choice using the interpolated left and right states. To reduce numerical dissipation, the interpolation of the primitive variables to the right and left side of the face is blended using physics-based and grid-based sensors such that in turbulent flow regions away from solution discontinuities the interpolation operator is mostly centered and the left and right states are nearly identical. To achieve higher order when requested (e.g. flux order = 4), the final flux becomes a weighted combination of the numerical fluxes at the cell faces (edges) and cell-center (nodes) physical fluxes.
The definition of the convective numerical scheme is listed as follows
convective terms
{
scheme = hwcns
flux order = 4
interp order = 3
central components = [q]
upwind blending sensors = [neumann, strain]
limiter = weno3js
fluxfunction = hllec
}
upwind blending sensors (default [none]):
-
flux ordercontrols the overall order of the flux finite-difference scheme. Options are{2,4}. -
interp ordercontrols the order of left and right states interpolation. Options are{1,2,3}.
Info
The default value of interp order depends on the value of flux order in the following manner: default interp order = min(3,flux order).
-
central componentscontrols the set of primitive variables whose interpolation are blended with a central interpolation scheme. It is a list, possible items and their meanings are{none, q: full state vector, p: pressure, t: temperature, y: mass fractions, u: x-velocity, v: y-velocity, w: z-velocity}. -
upwind blending sensorscontrols the sensor(s) used to remove the central contribution in the left/right interpolated states. The sensors are added additively. It is a list, possible items are{none, ducros, strain, laplacian, weno, neumann}. The blending of the interpolation with linear weights is done based onstrainwhereas the rest are considered shock sensors and affect the blending of interpolated states with non-linear weights. Choosing none will result in what is effectively centered interpolation with linear weights (non-dissipative). The default is[none];[neumann, strain]is recommended. -
upwind sensor strain noise floorandupwind sensor ducros noise floor(defaults1.5e-6andFLT_EPSILON, about1.19e-7) are the noise floors of thestrainandducrossensors, in units of \((c/\Delta x)^2\). The strain floor is subtracted from the enstrophy thestrainsensor sees, so weak vorticity reads as none and the face stays upwind, and the ducros floor is added to theducrosdenominator, so weak dilatation does not switch on the non-linear reconstruction. Both keep the sensors from flickering cell to cell where the flow is quiet.0removes a floor, leaving the sensor a bare ratio of the two gradient invariants, which round-off can switch where the flow is quiet, so results then vary from run to run. The two act in opposite directions: the strain floor adds dissipation to weak vortices, the ducros floor removes non-linear switching in near-irrotational flow. Both are re-read with the input file, so they can be changed while a run is going.
Warning
Only the laplacian and weno sensors are available for multiphase.
-
limitercontrols the use of non-linear interpolation scheme for the left/right-biased values. Options are{none, minmod, weno3js, weno3op}. Whennoneis selected, the MUSCL scheme is used for interpolation. The default isweno3js. -
flux functioncontrols which approximate Riemann solver is used for the nodal flux calculation. Options are{ausmpw+, hllec, keepghlle, laxfried}.
Warning
Only the hllec flux function is supported for multispecies and multiphase.
fictghostsextrapordersets how the fictitious ghost cells next to immersed boundaries are extrapolated before the face interpolation. Options are{0, 1}: constant (the default) and linear.
Per-level convective options
A single convective terms {} block applies to every grid level. To vary the scheme options by
level, replace it with numbered convective terms group_1 {}, convective terms group_2 {}, ...
blocks, each declaring the inclusive level range it covers with level start and level end:
convective terms group_1
{
level start = 0 # coarse levels: extra dissipation
level end = 1
scheme = hwcns
flux function = ausmpw+
upwind blending min = 0.8
}
convective terms group_2
{
level start = 2 # finest level: run the low-dissipation scheme
level end = 2
scheme = hwcns
flux function = ausmpw+
upwind blending min = 0.0
}
The example shows the usual arrangement: the coarser levels carry the extra dissipation, and the finest level — where the mesh resolves the features of interest — is left as clean as possible.
The blocks must cover every level exactly once — a level claimed twice or not at all is an error.
Note that level start and level end default to 0 and "all levels", so every block must set
both. The single-block and grouped forms are mutually exclusive: if a plain convective terms {}
block is present, the grouped blocks are ignored.
Warning
Options that select the compiled flux kernel must be identical on every level: scheme,
flux function, limiter, fictghostsextraporder, addshockdissipation, dodensityinterp,
the low-Mach Riemann options, and any combination of scheme/flux order that changes the
stencil width. Setting one of these differently between levels is a hard error naming the
option and the levels involved.
The options that can differ between levels are the run-time coefficients:
upwind blending min/max, wall upwind blending min/max, upwind blending farfield,
upwind blending finetocoarse, upwind blending wiggle, upwind blending corners,
next to trapped first order, upwind blending sensors, upwind sensor enstrophy factor,
upwind sensor strain noise floor, upwind sensor ducros noise floor, laplacian shock threshold,
limiter overshoot, central components, flux order and interp order. Raising
upwind blending min on the coarse levels is the usual way to add dissipation there.
Keeping a block out of the scheduler
When the run-time scheduler is enabled (do schedule = true in the inputs updating {} block) it
overwrites order and upwind blending min from the schedule file. By default it overwrites
them in every convective block, which would wipe out the per-level dissipation set above the
moment the first schedule entry fires.
Set schedule = false in a block to hold that block's order and upwind blending min at their
deck values. The scheduler then drives only the blocks that leave schedule at its default of
true:
convective terms group_1
{
level start = 0 # coarse levels: dissipation pinned by the deck
level end = 1
upwind blending min = 0.8
schedule = false
}
convective terms group_2
{
level start = 2 # finest level: the scheduler drives this one
level end = 2
upwind blending min = 0.0
schedule = true # the default; shown here for contrast
}
Notes:
scheduledefaults totrue. A deck that never mentions it behaves exactly as before — the scheduler drives every level.- The flag applies to the values restored from a restart file as well, so a restarted run keeps a pinned block pinned.
scheduleis the only per-block option that is not a flux coefficient; unlike the options listed above, it may differ between levels without restriction.- Setting
schedule = falsein every block while the scheduler drivesorderorupwind blending minleaves those schedule-file columns with nothing to write; LAVA warns rather than silently discarding them. - Do not confuse it with
do schedulein theinputs updating {}block, which turns the scheduler on or off for the whole run.
Per-level convective options apply to the Cartesian solver only; the unstructured solver accepts
a single convective terms {} block.
Geometry
The geometry {} block (inside cartesian {}) defines the immersed boundary surfaces used for the Ghost Cell Method. Surfaces are specified as one or more surface groups named surfaces_1, surfaces_2, etc.
Basic syntax
cartesian {
geometry
{
surfaces_1
{
file name = my_surface.fro
scale = [1.0^3] # optional
rotate deg = [0, 0, 0] # optional, degrees
translate = [0, 0, 0] # optional
read binary = false # optional: false = ASCII, true = binary
}
surfaces_2 { ... }
}
}
Supported geometry file formats
File format is inferred from the file extension. The following table lists supported formats and whether they are read in ASCII or binary.
| Extension | Format | Dimension | ASCII | Binary |
|---|---|---|---|---|
.fmt |
fmt | 2D | ✓ | |
.vtk |
VTK | 2D, 3D | ✓ | |
.dat |
ASCII | 2D | ✓ | |
.i.tri |
tri | 3D | ✓ | ✓ |
.fro |
fro | 3D | ✓ | |
.cgns |
CGNS | 3D | ✓ |
Use the readbinary parameter in each surfaces_N block to match the file format: readbinary = false for ASCII, readbinary = true for binary. Default is false (ASCII).
Using STL geometries
If your geometry is available as one or more STL files, you can convert them into a supported surface format using the stl_converter utility; see the stl_converter tool documentation for details.
Per-surface parameters
Options for each surfaces_N block when using file-based geometry:
-
file name(required): Path to the geometry file. Format is inferred from the extension; see the supported formats table above. -
scale: Scale factor applied when reading the file. Real or[x, y, z]; a single value is applied uniformly. Default:[1, 1, 1]. -
rotatedeg: Rotation in degrees about the coordinate axes. Format:[x, y, z]. Default:[0, 0, 0]. -
translate: Translation applied after scale and rotation. Format:[x, y, z]. Default:[0, 0, 0]. -
readbinary: Set tofalsefor ASCII input,truefor binary. Must match the actual file format. Default:false.
Moving Geometry
Prescribed body motion and the whole-domain moving grid are documented on their own page: Rigid Body Motion.
Block-Structured Octree Meshing
The grid { } block controls the octree grid generation and adaptive mesh refinement:
domain and level setup, refinement regions (tag boxes, cylinders, telescoping frusta),
and the AMR strategies. Since the grid setup is central to every Cartesian case, it is
documented on its own page: Block-Structured Octree Meshing.
Inputs Updating and Schedule Files
The inputs updating {} section lets you re-read the main input file during a run so you can tweak settings on the fly instead of stopping and restarting. On top of this manual workflow, you can optionally attach a schedule file to automate changes (e.g. ramping AMR levels, dx, CFL, or scheme order) within a single simulation as the flow evolves.
inputs updating block
The inputs updating section is defined at the top level of the input file (outside cartesian {}):
inputs updating {
interval = 1000 # how often to re-read the schedule
do schedule = true # enable scheduling
schedulefile = schedule.dat # relative or absolute path
trigger = ctu # nt | time | ctu
do cfl = false # schedule CFL number
do dt = false # schedule explicit time step
do levels = true # schedule number of AMR levels
do max cells = false # schedule AMR cell-count cap
do ref dx = false # schedule reference dx (dx-based regime)
do order = false # schedule convective scheme order
do upwind blending min = true # schedule minimum upwind blending
}
interval: The time step interval of which the inputs file will be completely read again.do schedule: Switch for scheduling.schedulefile: Name/path of the schedule file.trigger:nt: schedule is keyed on time step number.time: schedule is keyed on physical time (seconds).ctu: schedule is keyed on convective time unitsdo cfl/do dt/do levels/do max cells/do ref dx/do order/do upwind blending min:- These booleans specify which quantities are controlled by the schedule file.
Schedule file format
The schedule file is a plain whitespace-separated table of numbers with no header or comments. Each row has the form:
The presence of each column are determined entirely by the inputs updating do ... bools:
The first column is always the trigger value. Subsequent columns appear only if the corresponding do ... flag is true, and always in this fixed order:
1. do cfl → CFL (cfl)
2. do dt → time step (dt)
3. do levels → maximum tagging level (levels, a 0-based level index; the level ladder itself is fixed at startup and requests beyond it are clamped; a change forces a full regrid)
4. do max cells → maximum total AMR cells (maxcells) for threshold based AMR; a change forces a full regrid
5. do ref dx → reference spacing (ref.dx; overrides the dx in the reference conditions section for the rest of the run, and a change forces a full regrid)
6. do order → convective scheme flux order
7. do upwind blending min → convective terms { upwind blending min = ... }
How the scheduled reference spacing and level cap interact with the grid setup and the refinement tagging is described in The Three Spacing Inputs.
For example, if you choose trigger = ctu, do levels = true, and do upwind blending min = true, each row has three columns:
To see a tutorial that utilizes scheduled inputs see the High Lift Prediction Workshop 5 (HLPW5) Common Research Model–High Lift (CRM-HL) case, which uses a schedule file to run a grid refinement study in a single run.
Initial Conditions
Initial condition specification is optional. If not provided, the code will simply initialize the flow to reference conditions specified in Reference Conditions.
If a different initialization is needed, it can be specified through a numbered list:
# Specify pressure, set the rest using reference conditions
IC_1 {pressure = 5e5}
# Specify temperature, set the rest using reference conditions
IC_2 {temperature = 500}
# If density is specified, another thermodynamic quantity (either pressure or temperature)
# also needs to be specified
IC_3 {density = 2; temperature = 300}
# Velocity vector can be specified
IC_4 {velocity = [100,10,0]}
# Or Mach number along with alpha and beta angles
IC_5 {Mach=0.5; alpha=6; beta=2}
# Specify mass fractions for multi-species
IC_6 {mass fractions = [1,0,0]}
All the above statements will apply the conditions listed in the entire domain. To initialize a sub-volume differently, you can specify a custom box region with position vectors of the two opposing corners:
The example above will first apply the reference conditions in the entire domain. Then it will overwrite the pressure in the unit box region specified. The IC's are applied sequentially, i.e. the entries further down in the IC's list will overwrite the previous ones if there is overlap.Near-Geometry Stagnation Initialization (Robust Startup)
For immersed-boundary simulations, all cells in boxes near the geometry can be initialized to stagnation (total) conditions using the near geom stagnation option. The purpose of this initialization is to soften the startup by zeroing out the velocity near the geometry and adjusting pressure and temperature to their total (stagnation) values, which can significantly improve robust startup behavior during the initial transient. It computes:
Optionally, corner_1 and corner_2 can be specified to restrict the stagnation initialization to a sub-region of the domain. Without them, the stagnation transform applies to all near-geometry cells in the entire domain:
When near geom stagnation = true is set on an IC block, no other thermodynamic or velocity parameters are allowed in that block — the base state comes entirely from the reference conditions.
Not supported for multiphase
IC Ordering Matters
IC blocks are evaluated in numbered order. A stagnation IC is only activated when both conditions are met: the cell is near the immersed geometry and it is within the stagnation IC's box bounds (the entire domain if no corners are specified). If either condition is not satisfied, the stagnation IC is skipped and the remaining IC blocks continue to be evaluated. Once a stagnation IC activates, it converts the current base state to total conditions and no further ICs are checked.
Stagnation IC listed first (recommended for most cases) — near-geometry cells within the stagnation box get stagnation conditions. All other cells skip the stagnation IC and fall through to subsequent ICs:
# Near-geometry cells get stagnation; all others skip this IC
IC_1 { near geom stagnation = true }
# Non-near-geometry cells (and those outside the stagnation box) can still receive custom conditions
IC_2 { pressure = 1e4; temperature = 300; velocity = [20,20,0]; corner_1 = [-2,-2,0]; corner_2 = [0,0,0] }
Stagnation IC listed last — custom ICs are evaluated first. Cells that match a custom box region receive those conditions and stop. Near-geometry cells that didn't match any earlier IC receive stagnation conditions based on the reference state:
# Custom conditions applied first in the box region
IC_1 { pressure = 1e4; temperature = 300; velocity = [20,20,0]; corner_1 = [-2,-2,0]; corner_2 = [0,0,0] }
# Near-geometry cells not matched above get stagnation of reference state
IC_2 { near geom stagnation = true }
Stagnation IC with corners — restricts the stagnation initialization to a specific region. Only near-geometry cells inside the specified box receive stagnation conditions; near-geometry cells outside fall through to subsequent ICs:
# Only near-geometry cells within this box get stagnation
IC_1 { near geom stagnation = true; corner_1 = [-0.5,-0.5,0]; corner_2 = [1.5,0.5,0] }
# Near-geometry cells outside the stagnation box, and all other cells, receive these conditions
IC_2 { pressure = 1e4; temperature = 300; velocity = [100,0,0] }
Info
The thermodynamic condition description for multi-phase is slightly different than for single and multi-species. Please refer to the Cartesian Multiphase Solver page for details.
Restarting
To resume runs, all you need to do is point to the restart file location as:
The restart files (also referred to as checkpoint files) are saved periodically in restart directory created by the code under the run directory. The interval at which the restart files are created can be specified by users. The details are provided in restart output options section.
If the specified restart file is not found, the solver will print a message and proceed with a fresh start instead of aborting. This allows the same input file to be used for both initial runs and restarts — if the restart file does not yet exist, the simulation simply starts from scratch. If restart is not desired at all, you can skip or comment out this section.
Additional restart controls are:
restart {
file = ./restart/Cart_restartLatest.hdf5
# Set physical time to 0 on restart
reset time = true
# Set the time step number to 0 on restart
reset nt = true
}
Boundary Conditions
Immersed (wall) and domain boundary conditions are documented on their own page: Boundary Conditions.
Trip Lines
Trip lines exert a penalty method source term that attempts to trigger boundary layer transition to turbulence. The source terms are applied only at select cells within certain distance of the lines. Lines are also broken into dash/dot or on/off pattern that apply the trip terms in an intermittent fashion along the line, similar to how trip dots are commonly implemented in reality.
# This determines the strength of the trip lines
# The lower the value, the stronger the trip source penalties are
# In the lower limit, a value of 1 would bring the flow to full stop
# where trip is active
trip time relaxation = 40. # a factor of dt
trip_line_1 {
# dxscale should indicate the local grid resolution (where this trip line is)
# with respect to the dx value set at the reference section
dxscale = 1
# Begin/end coordinates of the line segment
begin = [0,1,1]
end = [1,2,3]
# The segment variables below are relative to the local grid spacing
# In this example, the trips will be on for approximately 2 cells
# and off for approximately 3 cells along the line
# The on segments will mark cells whose centers are within 0.9 * dx
# from the line
# These variables can be skipped in favor of defaults
segment length = 2 # default
segment skip = 3 # default
segment radius = 0.9 # default
# The straight trip line specified here will be projected to the
# surface using projection method. By default, the line will be projected
# to the closets surface
# Options are : none, closest, vector
projection method = closest # default
# max distance is an optimization parameters, entering the something
# slightly larger than the expected farthest distance (from trip line to the geometry)
# will improve start-up performance
projection max distance = 3
}
trip_line_2 {
dxscale = 4
begin = [1,0,0]
end = [2,0,0]
# Another projection method is vector, for which the line
# is projected along a specified vector direction until a surface is
# encountered
projection method = vector
projection vector = [0,1,0] # y-axis
}
# Circular trip curve
trip_line_3 {
dxscale = 2
# Instead of a straight line, the trip location can also be drawn as a circle
# with the specified center coordinates and radius
center = [1,0,0]
radius = 2
# The circle can also be projected to the surface
projection method = closest
projection max distance = 1
}
Tip
In typical practice, it is recommended to use defaults for segmenting parameters. In addition, the inputs may be made more compact by inlining each trip, for example:
Tip
The solver will output the final projected trip lines (in tecplot and vtk line formats) into the trips directory under the run directory. It is highly recommended to verify the trip setup by plotting the lines overlaid on the surface geometry.
GPU Options
GPU-specific computational options can be configured in the gpu section to optimize performance on GPU hardware.
gpu {
# [Optional] Number of threads per block for GPU kernels
threadsperblock = 512
# [Optional] Maximum fraction of shared memory allowed to be used
# Controls memory allocation strategy on GPU
maxSharedMemoryAllowedFactor = 1.0
# [Optional] Whether to use shared memory for primitive variables (Q)
# Can improve performance by reducing global memory access
overrideusesharedq = true
# [Optional] How device-resident allgatherv collectives hand their buffers to MPI
# Leave unset; see the note below
allgathervtransport = auto
# [Optional] Optimize the GPU kernels at the start of each run (default true)
autotune = true
}
These options control the GPU execution parameters:
-
threadsperblock: (Optional) Sets the number of CUDA threads per block. When left unset by the user the default value is set to the optimal thread block size based on the GPU architecture and problem characteristics.
-
maxSharedMemoryAllowedFactor: (Optional) Controls the maximum fraction of available shared memory that can be utilized. Values should be between 0.0 and 1.0, where 1.0 allows full shared memory usage.
-
overrideusesharedq: (Optional) Enables the use of shared memory for storing primitive flow variables (pressure, velocity, temperature, etc.) within GPU thread blocks. This can significantly improve performance by reducing global memory bandwidth requirements. This option is currently only applicable to the cartesian solver.
-
allgathervtransport: (Optional) One of
auto(default),stagedordevice. Controls how an allgatherv whose buffers live in GPU memory is handed to MPI:devicepasses the device pointer straight to MPI, whilestagedcopies the data through pinned host memory first so MPI only ever sees host pointers. Which is faster depends on the machine's MPI and GPUDirect configuration and on the shape of the exchange — how many ranks take part and how unevenly the data is spread across them — not on the case, soautodetermines it at runtime.With
auto, the first time a given exchange is performed LAVA times both transports on that exchange and reuses the faster one from then on. The measurement costs a handful of extra gathers, once, and is reported in the log:[I] ParallelOps::allgatherv: timing both transports for a new call configuration (5046480 B per rank over 8 ranks, 8 extra gathers). Measurement 1 this run.The result is remembered per exchange, so a few of these lines near the start of a run are expected — one for each distinct exchange. They should stop once every exchange has been measured.
Note
You should not need to set allgathervtransport. Set it explicitly only as a last resort — if you suspect an allgatherv exchange is performing poorly and want to pin one transport to compare against the other.
The other reason to set it is if those measurement lines keep appearing throughout a run instead of stopping. That means the exchanges are changing shape on every call, so nothing can be reused and the measurement cost is paid repeatedly; LAVA warns about this after 32 measurements. Setting allgathervtransport to staged or device pins one transport and skips measuring altogether.
- autotune: (Optional)
true(default) times the GPU kernels' launch configurations at the start of each run and keeps the fastest.falseuses the default configurations. On the Cartesian solver, maxthreadsperblock and minblockspermultiprocessor, given together, fix the configuration instead.
Note
These GPU options are only relevant when running LAVA with GPU acceleration enabled. The optimal settings may vary depending on your specific GPU
Output
Monitor, flow statistics, loads, restart output, volume/surface/iso-surface output, the probes, and time averaging are documented on their own page: Output and Probes.
References
-
Deng, X., "New High-Order Hybrid Cell-Edge and Cell-Node Weighted Compact Nonlinear Schemes," 20th AIAA computational fluid dynamics conference, 2011. https://doi.org/10.2514/6.2011-3857 ↩
Block-Structured Octree Meshing
This page documents the grid { } block of the Cartesian solver inputs: the octree grid fundamentals, the two approaches to sizing the grid, user-prescribed refinement regions, and solution-based adaptive mesh refinement. For the remaining input sections see General Setup.
Basic Octree Grid Setup
LAVA Cartesian gridding is achieved with a block-structured adaptive mesh refinement (AMR) approach using a forest of octrees. The domain is divided into a Cartesian lattice of grid points grouped into boxes, and locally refined by a factor of 2 between coarse and finer levels of refinement. Refinement can be targeted by user-prescribed regions (geometry components and volumetric tag regions) and/or driven dynamically by solution-based error metrics — both are described further down this page.
We define "boxes" as groups of cells, each containing \(N^d\) cells where \(d\) represents the spatial dimension and \(N\) is max box size. We recommend using max box size = 8, so each box contains \(8^3 = 512\) cells in 3D (or \(8^2 = 64\) cells in 2D). Mesh refinement is applied at the box level; thus, all cells within a box share the same refinement level—if any cell in a box requires refinement, the entire box is refined.
A Uniform Single-Level Grid
The simplest grid is a single-level uniform lattice:
grid
{
number of levels = 1
max box size = 8
first level dimension = [256^3]
domain min = [0., 0., 0.]
domain max = [ 1., 1., 1.]
}
Here we define a grid of 256 cells in each spatial dimension on a 3D domain, resulting in a uniform grid with \(256^3 = 16,777,216\) cells in total. The domain extends from \([0,0,0]\) to \([1,1,1]\), and with a box size of 8, each box contains \(8^3 = 512\) cells. Since only one refinement level (number of levels = 1) is specified, the entire grid maintains a uniform refinement level throughout the domain. It's important to note that first level dimension must evenly divide by max box size. If specifying a non-cubic domain (or non-square in 2-dimensions) grids the cells must remain cubes, so \(dx = dy = dz\). We also showcase a common shorthand used in input files, where [256^3] is equivalent to explicitly writing out [256,256,256].
The sketch below shows the cell/box relationship for a smaller example (32 cells per side, boxes of 8):
Refinement Levels and Nesting
Additional levels refine the grid locally with a fixed refinement ratio of 2: each successive level halves the cell spacing relative to its parent, and fine levels nest inside coarser ones. The following diagram illustrates how refinement levels relate to each other:
Sizing the Grid: Inside-Out or Outside-In
Beyond the uniform example above, every case has to answer the same question: which grid quantities do you prescribe, and which do you let the solver derive? There are two approaches:
- Option 1 — inside-out (geometry-centric). You prescribe the finest cell spacing — the quantity you actually care about near the geometry — plus a target farfield distance. The solver derives the number of levels and the coarse-grid dimensions to reach the farfield; the domain extent is rounded to fit the box and level arithmetic. The finest spacing is exact, the extent is approximate.
- Option 2 — outside-in (domain-centric). You prescribe the exact domain extents, the coarse-grid lattice, and the level budget. The finest achievable spacing is a consequence. The extent is exact, the finest spacing falls out.
Option 1: Inside-Out — Prescribe the Finest Spacing
If you specify finestdx or finestdx_rel, the solver will automatically determine the number of refinement levels and grid dimensions to achieve the requested finest cell size.
grid {
finestdx = 0.002
targetrelativefarfielddistance = [100, 100, 100] # Optional: farfield distance relative to reference length
targetfarfielddistance = [100, 100, 100] # Optional: absolute farfield distance
domainorigin = [0.0, 0.0, 0.0] # Optional: shifts the assembled domain
aligndomainfacetoorigin = [none, lo, none] # Optional: anchor a domain face at the origin (halves the domain)
maxboxsize = 8
}
finestdx: Target finest cell size (required for minimal input).finestdx_rel: Replacesfinestdxif present. Target finest cell size factor relative to the referencedx(defined in the reference section).targetrelativefarfielddistance: Farfield distance relative to reference length (overridestargetfarfielddistanceif present).targetfarfielddistance: Absolute farfield distance.aligndomainfacetoorigin: Per directionnone,lo, orhi. Withnonethe domain is centered on the origin and its total length in that direction is \(2\times\) the farfield distance. Withlo(hi) the low (high) domain face is placed exactly at the origin and the domain extends only to one side, with length equal to the farfield distance — the domain is halved, which is the natural setup for symmetry planes and ground planes.domainorigin: Shifts the assembled domain by this point, i.e. the domain center (or the aligned face) ends up atdomainorigininstead of the coordinate origin.
Note
The placement keys (targetfarfielddistance, domainorigin, aligndomainfacetoorigin) belong to the inside-out approach only, where the solver assembles the domain around the geometry. In the outside-in approach the domain placement is given directly and exactly by domainmin / domainmax.
Option 2: Outside-In — Prescribe the Domain and Level Budget
Alternatively, you can specify the grid dimensions and number of levels directly:
grid {
firstleveldimension = [128, 128, 128] # Number of cells in each direction on the coarsest grid
numberoflevels = 3
domainmin = [0.0, 0.0, 0.0]
domainmax = [1.0, 1.0, 1.0]
maxboxsize = 8
}
firstleveldimension: Number of cells in each direction on the coarsest grid (must be a multiple ofmaxboxsize).numberoflevels: Number of AMR levels.domainmin,domainmax: Physical extents of the domain.
The finest spacing follows from the level budget:
Common Grid Keys and Constraints
The following keys apply to either sizing approach:
maxboxsize: Number of cells per box per direction. Recommended value: 8 (i.e., \(8^3 = 512\) cells/box in 3D). Must be at least 4 if using refinement.grid_scale: Global scale factor (default: 1.0) applied to every geometric length in thegridsection:finestdx, the farfield targets, the domain extents and origin, and all tag-region coordinates, radii, and spacings. Useful when the geometry is modeled in different units than the flow problem. It multiplies the final values — i.e. after any*_relscaling by the referencedx— and does not modify the referencedxitself.
Constraints to keep in mind:
- All grid dimensions must be integer multiples of
maxboxsize. - For periodic boundary conditions, at least 2 boxes per direction are required.
- The refinement ratio between levels is fixed at 2.
- Cells must be isotropic (\(dx = dy = dz\)); if the aspect ratio is not unity and
nonunitokis not set, the code will stop with an error.
The Three Spacing Inputs
Spacing appears in three different places of the input file, and mixing up their roles is the most common source of confusion in the Cartesian grid setup:
dxin thereference conditionssection — the reference spacing. A pure scale factor: every*_relspacing key (dx_relof tag regions,finestdx_rel,dx_max_relof a telescoping frustum, ...) is multiplied by it. Absolute keys (dx,finestdx,dx_max) ignore it entirely.finestdxin thegridsection — the ladder builder. Used only at startup, in the inside-out approach, to construct the level ladder: the number of levels, the domain extents, and the per-level spacings. It takes no part in any tagging decision — tagging compares each cell's level spacing against the tag's requesteddxand refines until the request is met or the ladder (or the tagging cap) ends. Its only connection to tagging is that it defines what "finest" means fordx = 0.0tags.- The schedule file (
inputs updating) — runtime control. Two schedule columns interact with the spacings:- The
ref_dxcolumn (do ref dx = true) overwrites the referencedxwhile the run advances. On every update interval the input file is completely re-read and all*_relspacings are re-derived from the scheduled value. Once the scheduler has set the referencedx, thedxin thereference conditionssection is ignored for the rest of the run. A change in the scheduled value forces a full regrid at the next opportunity, independent ofregridinterval. - The
levelscolumn (do levels = true) moves the maximum tagging level (maxtagginglevel, a 0-based level index) — it does not add or remove actual levels. The level ladder is fixed at startup; a request beyond the ladder is clamped with a warning. Like a scheduledref_dxchange, a change of the cap (or of a scheduledmaxcellsbudget) forces a full regrid at the next step rather than waiting forregridintervalto elapse — regridding must still be enabled (regrid interval> 0).
- The
The two combinations that come up most often:
- Absolute-
dxtags with a levels-only schedule ("add a level every N CTUs"): the tags keep the spacing they request throughout — raising thelevelscolumn simply lets them reach the finer ladder levels that were capped before, with the regrid happening right at the scheduled step. The referencedxnever changes. dx_reltags with aref_dxschedule (grid sequencing): halving the scheduled referencedxhalves everydx_rel-based tag spacing at the next update interval and triggers the regrid. This is the mechanism behind single-run grid refinement studies (see the schedule file documentation and the CRM-HL tutorial).
Warning
The level ladder is built before the first schedule row is applied, from the grid section and the file's reference dx. When scheduling ref_dx down toward a fine target, make sure the startup ladder is already deep enough for the finest scheduled spacing (e.g. size finestdx or number of levels for the final target) — tags finer than the ladder's finest level are silently clamped to it.
User-Prescribed Refinement Regions
Refinement can be targeted to specific regions of the domain by tagging. The diagram below illustrates the main tagging methods:
A few conventions shared by all tag regions:
- Each region requests a target spacing with
dx, or withdx_relas a factor relative to the referencedx(defined in the reference section). Settingdx = 0.0requests the finest resolution available, defined either byfinestdxor the maximum number of refinement levels. - Regions are enumerated per type —
tagboxes_1,tagboxes_2,tagcylinders_1, … — and any combination of types and counts may be used together. - Every region accepts an optional activation window
nton/ntoff: the region only tags whilenton\(\le\)nt\(\le\)ntoff(time step count), which is useful for startup refinement that should later be released. - For inspection, the prescribed tag points, boxes, cylinders, and spheroids are dumped as VTK files into the
tags/directory of the run.
Component Tagging
Refinement regions can be tied to the input geometry using the component numerical values of the surface triangulation (see the Geometry section). For example:
component tagging_1 { components = [1, 5]; dx = 0.0 }
component tagging_2 { components = [2]; dx_rel = 8 }
The first section refines the cells adjacent to the surfaces of components 1 and 5 to the finest available resolution; the second refines the cells around component 2 to \(8\times\) the reference dx. Optionally, type = edge restricts the tagging to the components' feature edges instead of the full surfaces (type = component is the default).
Tag Boxes
Refinement can be targeted within explicitly defined rectangular regions (tagboxes):
This specifies a rectangular region from lo to hi coordinates, refined to a grid spacing (dx) of 0.4 (dx_rel works as well).
Tag Cylinders
Cylindrical refinement regions can be defined using the tagcylinders parameter. Each cylindrical region is specified with the following parameters:
tagcylinders_1 { lo = [0, 0, 0]; hi = [3, 0, 0]; radius = 2.24517; radius hi = 3.367785; dx = 0.0325 }
dx(ordx_rel): Target spacing inside the region;dx_relis multiplied by the referencedx.lo: Coordinates of the cylinder's bottom center point.hi: Coordinates of the cylinder's top center point.radius: Radius at the cylinder's bottom (lopoint).radiusinner: Inner radius at the cylinder's bottom, defining a hollow cylindrical region. Defaults to0.0if not specified.radiushi: Radius at the cylinder's top (hipoint). Defaults to the bottom radius (radius) if not specified.radiushiinner: Inner radius at the cylinder's top, defining the upper inner radius of a hollow cylindrical region. Defaults to the bottom inner radius (radiusinner) if not specified.
Note
Make an inner cutout comfortably larger than the AMR boxes of the refinement levels it must survive on: refinement acts on whole boxes and tags are grown by regridgrowtags cells, so a hole only one or two boxes wide fills in and can appear as if the inner radius were ignored. For n-gon cross sections the radii are circumradii, i.e. the flat-to-flat half-width of the cutout is only \(r\cos(\pi/n)\).
Since radius and radiushi may differ, a tag cylinder is in general a conical frustum. The cross section does not have to be circular:
radiusminor,radiushiminor,radiusinnerminor,radiushiinnerminor: Minor-axis radii of an elliptical cross section, one per radius above. Each defaults to its corresponding (major) radius, which recovers the circular cross section. The major radii span the first transverse direction of the axis frame and the minor radii the second; the frame convention matches the LAVA Voronoi mesher'sfrustumregion, so identical inputs produce identical shapes in both meshers.num_sides:0(default) keeps the circular/elliptical cross section; a value>= 3replaces it with a regular n-gon whose circumradius is given by the radii above (stretched by the major/minor aspect ratio).phase_angle: Rotation of the n-gon about the axis in degrees. With the default of0the first vertex sits on the major axis — sonum_sides = 4gives a square standing on its corner (a rhombus). To align the flats with the axes — e.g. an axis-aligned rectangular duct — setphase_angle = 45fornum_sides = 4(in general \(180/\)num_sides). Requiresnum_sides >= 3.
For example, an axis-aligned rectangular duct: a square cross section stretched to a 3:2 major/minor aspect ratio, with phase_angle = 45 placing the flats on the axes — the shape shown in the telescoping-frustum figures below:
tagcylinders_2 {
dx = 0.02
lo = [0.0, 0.0, 0.0]
hi = [3.0, 0.0, 0.0]
radius = 0.6; radiushi = 0.9 # major radii at the lo and hi caps
radiusminor = 0.4; radiushiminor = 0.6 # minor radii: elliptical 3:2 aspect
num_sides = 4 # square cross section...
phase_angle = 45.0 # ...with its flats aligned to the axes
}
The radius and phase conventions are identical to the Voronoi mesher's frustum region:
Note
The flat-to-flat width keys shown in the middle panel are currently a Voronoi-mesher-only input; the Cartesian tag cylinders use the radius (circumradius) keys.
Elliptical and n-gon cross sections require a 3D build.
Tag Spheroids
Ellipsoidal refinement regions are defined with tagspheroids, using axis-aligned semi-axes (or a scalar radius for a sphere):
dx(ordx_rel): Target spacing inside the region;dx_relis multiplied by the referencedx.center: Center point of the spheroid.semiaxes: Semi-axes along the coordinate directions; all equal recovers a sphere.radius: Scalar alternative tosemiaxesfor a sphere.
Telescoping Frustum
For jet-type simulations the cell size should grow gradually along the plume to avoid abrupt cell-volume changes near the shear layer while keeping the cell count affordable. Instead of hand-stacking tag cylinders, a telescope_axial sub-section turns a single tag cylinder definition into a telescoping frustum: refinement layers march from the lo cap along the axis, and every layer doubles the grid spacing (matching the 2:1 refinement ratio of the Cartesian octree) until the requested maximum spacing is reached. The layer thickness is specified in AMR blocks of the layer's own spacing, so layers align naturally with the block structure. The coarsest layer extends to the hi cap. The finest layer always starts at the lo cap, and there is no ordering requirement between the two points — swapping lo and hi reverses the telescoping direction, and the axis may point in any direction. The outer, inner, major, and minor radii of each layer are interpolated linearly along the enclosing frustum definition, so annular (hollow) and n-gon telescopes work the same way as plain tag cylinders. This is the Cartesian counterpart of the Voronoi mesher's telescoping_frustum region; the octree's automatic 2:1 grading replaces that region's explicit radial_refinement rings.
tagcylinders_1 {
dx = 0.04 # spacing of the first (finest) layer at the lo cap
lo = [-0.5, 0.0, 0.0]
hi = [ 3.0, 0.0, 0.0]
radius = 0.6; radiushi = 0.9 # frustum envelope; inner/minor radii and num_sides work as usual
telescope_axial {
dx_max = 0.16 # coarsest spacing; dx_max_rel is also supported
num_boxes_per_layer = 2 # layer thickness = 2 AMR blocks of the layer's dx
}
}
dx_max(ordx_max_rel): Spacing of the coarsest layer; layer spacing doubles from the tag cylinder'sdxuntil this value.num_boxes_per_layer: Thickness of each layer in AMR blocks (max box sizecells) of that layer's spacing.num_boxes_per_layer_growth(default1): Factor applied to the box count of each subsequent layer, rounded to the nearest integer and never below one block. Since the spacing doubles per layer, the default of1doubles the physical layer thickness each time;0.5keeps the physical thickness (approximately) constant along the axis;2quadruples it.stretch_ratio: Alternative tonum_boxes_per_layer(specify exactly one). Emulates a smooth geometric stretching with the given ratio, as familiar from curvilinear meshing: the number of cells over which such a stretching doubles the spacing, \(\ln 2/\ln r\), is converted to the equivalent whole number of blocks per layer. For example,stretch_ratio = 1.05gives \(14.2\) cells \(\approx 2\) blocks of 8. Because of the rounding the achieved effective ratio differs from the request (it is reported in the log); very aggressive ratios saturate at one block per layer.
Outward Telescoping
Any tag box, cylinder, or spheroid can carry a telescope_outward {} sub-section. The base region keeps its spacing, and dilated copies of the shape wrap it on all sides with the spacing doubling per layer until dx_max is reached — after the last layer the octree's automatic 2:1 grading takes over toward the freestream. A box grows by the layer offset at all corners; a cylinder grows its radii and extends its axis (an annular cutout shrinks and eventually closes); a spheroid grows its semi-axes. This is the Cartesian counterpart of the Voronoi mesher's telescoping_refinement section, and it controls how much volume every intermediate refinement level occupies instead of leaving only the minimal nesting buffer.
tagboxes_1 {
lo = [-1, -1, -1]; hi = [1, 1, 1]; dx = 0.02
telescope_outward {
dx_max = 0.16 # coarsest layer spacing; dx_max_rel also supported
num_boxes_per_layer = 2 # or stretch_ratio; num_boxes_per_layer_growth optional
}
}
The layering keys (dx_max/dx_max_rel, num_boxes_per_layer, stretch_ratio, num_boxes_per_layer_growth) work exactly as for the telescoping frustum. The telescoping is resolved once at input time into ordinary tag regions, so regridding sees no additional machinery — the generated layers are visible in the tags/ VTK dumps.
Tag Points
Pointwise tagging can also be utilized (remember, the entire box will be subject to the smallest tagged cell).
Adaptive Mesh Refinement Setup
The Cartesian solver supports solution-based AMR tagging using a variety of error metrics and field-based thresholds. These options allow you to refine the mesh dynamically in regions where the solution exhibits sharp gradients or other features of interest.
Regridding Cadence
The following grid-section keys control how often the grid adapts:
regridinterval: Number of steps between regridding operations; larger is better for performance.regridintervalon,regridintervaloff: Control regridding intervals for on/off cycles.regridgrowtags: Grows the refined region around geometry tags by the given number of cells.regridgrowerrormetrictags: Grows the refined region around error-metric tags by the given number of cells.
Quick-Start Examples
Solution-based AMR with user-specified thresholds:
grid {
finest dx = 0.008 # finest level based approach
targetrelativefarfielddistance = [200,100^2] # distance from origin to farfield BC in units of reference length
aligndomainfacetoorigin = [none, none, none]
max box size = 8
regrid interval = 100 # number of time steps between regrids, larger is better for performance
regridgrowtags = 2 # increases amount of refined boxes around geometry by 2 cells
solution based amr
{
method = user
errormetric_1 {type=smallscaleenergy; weight=1.0}
errormetricgeomdistancescalingreflength = 22.5
errormetricthresholds = [0.0000125, 0.000025, 0.00005, 0.000125, 0.00025, 0.0005, 0.00100, 0.0025, 0.005, 0.01, 0.04, 0.12, 0.24, 0.48, 0.96]
regridgrowerrormetrictags = 1
}
}
The same setup with automatically determined thresholds:
grid {
finest dx = 0.008 # finest level based approach
targetrelativefarfielddistance = [200,100^2] # distance from origin to farfield BC in units of reference length
aligndomainfacetoorigin = [none, none, none]
max box size = 8
regrid interval = 100 # number of time steps between regrids, larger is better for performance
regridgrowtags = 2 # increases amount of refined boxes around geometry by 2 cells
solution based amr
{
method = auto
errormetric_1 {type=smallscaleenergy; weight=1.0}
errormetricgeomdistancescalingreflength = 22.5
regridgrowerrormetrictags = 1
}
}
Specifying Error Metrics
The specification of error metrics is achieved through enumerated subsections errormetric_* {} within the solution based amr {} subsection. For example, two error metrics may be specified as follows:
grid
{
solution based amr
{
errormetric_1 {type = laplacianp; weight = 0.5}
errormetric_2 {type = laplaciant; weight = 0.5}
}
}
Options include:
typeError metric name. Default:smallscaleenergy.weightWeight to apply to the specified error metric across all levels. Default: 1.0weightsperlevelArray of length equal to the number of AMR levels, specifying the weight to use on each level. If bothweightandweightsperlevelare provided, thenweightsperlevelwill be used. Default: [1.0,1.0,...,1.0]
Types of error metrics:
-
laplacianpRefine based on the Laplacian of pressure. -
laplacianu,laplacianv,laplacianwRefine based on the Laplacian of velocity components (u, v, w). -
laplaciant(single phase only) Refine based on the Laplacian of temperature. -
smallscaleenergyRefine based on small-scale energy content. -
leonardstressmagRefine based on the Leonard stress magnitude. -
chuenergynormRefine based on the Chu energy norm. -
vortrelRefine based on relative vorticity magnitude. -
tkeRefine based on turbulent kinetic energy (TKE). -
prmsRefine based on pressure RMS. -
heatreleaserate(reacting flows only) Refine based on the heat release rate. -
maxmixing(multispecies only) Refine based on maximum mixing fraction.
Thresholds, Budgets, and Metric Accumulation
The solution based amr {} subsection accepts the following options:
methodAMR thresholding method. Options include:user: Users must provide thresholds viaerrormetricthresholdfinestorerrormetricthresholds.auto: Refinement and coarsening thresholds are automatically determined using distribution thresholding.-
none: Solution-based AMR is turned off. -
errormetricthresholdfinestSet fixed error metric threshold per level based on the value for which the mesh should be refined to the finest available. The thresholds for coarsening and refinement for each level will then be automatically populated using the ratio to obtain the next coarsest refinement levelerrormetricthresholdratiowhich defaults to 0.5 to reduce mesh size as much as possible with minimal impact to solution accuracy -
errormetricthresholdminMin allowed threshold for solution based amr tagging. This is to avoid chasing non-physical error metrics. Default is 0.001. -
errormetricthresholdsSet fixed error metric thresholds per level (overrides the above if present). -
thresholddomainextentSpecifies whether to use the maximum or mean error as the maximum possible threshold value. Options:maxerror(use max error as the upper bound of threshold domain, default)meanerror(use mean error as the upper bound of the threshold domain)
-
maxcellsMaximum total number of cells. This limit is enforced when either user-specified thresholds or automated distribution thresholds are estimated to result in a total cell count exceeding the number specified. Example:maxcells = 150000000. -
maxcellstoleranceThe convergence criteria for the max cells constraint. For example, if 0.01 is specified, then we terminate the search when we have a set of thresholds that are 1% below the specified cell limit. Default:0.015. -
maxitercelllimitsearchThe maximum number of iterations to perform when searching for error thresholds that satisfy the imposedmaxcellsconstraint. Default:50. -
maxmemorypercenthostThe maximum percentage of host memory to utilize. This parameter is used at each adaptation cycle to generate an approximate limit on the number of cells we can afford to increase our grid size by. Default:80. -
maxmemorypercentgpuThe maximum percentage of GPU memory to utilize. This parameter is used at each adaptation cycle to generate an approximate limit on the number of cells we can afford to increase our grid size by. Default:80. -
enforcemaxmemorylimitAdjusts the user-specifiedmaxcellsparameter if memory usage will exceedmaxmemorypercenthostandmaxmemorypercentgpu. Warning this capability is currently under development and may result in undesired behavior. Default:false. -
errormetrictimemethodControls how error metrics are accumulated in time. Options:ins(instantaneous, default)avg(time average)max(maximum over time)
-
errormetricexponentialmovingaveragewindow,errormetricexponentialmovingaveragewindowctuWindow length for the exponential moving average (used iferrormetrictimemethod = avg). Thectuvariant is in convective time units; without the suffix the value is in physical time (seconds). The equivalent...timescale/...timescalectukeys are also accepted. -
errormetricresetonregridIf true, resets error metrics on each regrid. -
errormetricradialscalepoint,errormetricradialscalepowEnable and control radial scaling of error metrics. -
errormetricgeomdistancescalingreflengthReference length (\(d_0\)) for geometric distance scaling in error metrics, in meters. Scales down the error metric computed by \(1/2^{d/d_0}\) to avoid refining wakes and bow shocks all the way to the edge of the computational domain where they likely no longer affect quantities of interest. -
errormetricdogpuIf true, compute error metrics on GPU (requires at least one threshold to be set). -
errormetricstatsintervalInterval (in steps) to update error metric statistics
Notes:
- If the solution based amr section is NOT present, then no solution-based AMR is performed.
- If solution based amr is present, then the default for method is auto.
Regional Error-Metric Scaling
The error metric can be scaled inside user-defined regions, e.g. to suppress solution-based refinement in areas that are known to be uninteresting (sponge zones, far wakes), or to weight it up in areas of interest. Inside a region the metric is multiplied by its errormetricscale factor (default 0.0, i.e. solution-based refinement is fully suppressed there); the regions also accept the nton / ntoff activation window.
Boxes are defined directly in the grid section, and cylinders inside the solution based amr subsection with the full tag cylinder shape syntax:
grid
{
errormetricscaleboxes_1 { lo = [10, -5, -5]; hi = [40, 5, 5]; errormetricscale = 0.0 }
solution based amr
{
errormetricscalecylinders_1 { lo = [0,0,0]; hi = [8,0,0]; radius = 2.0; errormetricscale = 0.25 }
}
}
Wall-Resolution Based Refinement
Refinement can also be driven by the resolved wall spacing of geometry components. The thresholds are specified as arrays of length equal to the number of AMR levels (except the base level):
refineypluscomps = [ 1-9, 10]components to use for y-plus based refinementrefineyplusthreshold = [1000^9,200]yplus threshold levels for the components
Additional Options
dumpinitgridsonly: If true, only writes initial grid and exits — useful for iterating on the grid setup without running the solver.maxtagginglevel: Maximum AMR level for tagging/refinement (default: highest level).minlevel: Minimum AMR level (default: 0).prunecoveredboxes: If true, removes boxes fully covered by finer grids.
Boundary Conditions
Immersed Boundary Conditions
The LAVA Cartesian solver uses the Ghost Cell Method (GCM) for immersed boundary treatment, where ghost cells inside the body are assigned interpolated values from the fluid side to enforce boundary conditions. For details on the GCM approach, see Mittal et al.1 and for how we deal with thin geometry see Nakahashi et al.2.
Available types are: wall, inlet, outlet, nozzle,distributed, ref.
Available wall kinds are: no-slip,slip,wmpartialslip,porous,adiabatic,isothermal,wallstressmodel,musker,reichardt,blendedlog,wmnoslip,rough,roughrandom,wmslip,wmisothermal.
Available inlet kinds are: mdot,nozzle
Available outlet kinds are (optional): noreverse,dampreverse,forcesupersonic
Multiple kinds are possible for certain combinations, for example our recommended Immersed BC for WMLES:
The shorthand below is equivalent (when no velocity kind is specified,slip is assumed automatically; specifying wmpartialslip without wallstressmodel auto-adds wallstressmodel):
The available velocity treatments at an immersed wall are:
no-slip: classical Dirichlet (u = u_body) at the wall. Used for fully wall-resolved viscous simulations.slip: inviscid wall (u·n = u_body·n, tangential Neumanndu_t/dn = 0).wmpartialslip: wall-model-based partial slip. The immersed-boundary ghost-cell tangential velocity is determined by a linear reconstruction through the matching point (at off-wall distanced1) and the wall-model profile value at y⁺ =partialslipheight(default 100, deep in the log layer). This is an attempt at making the tangential velocity wall-normal gradient for the convective terms more consistent with the viscous stress correction that uses the wall function predicted wall shear stress. No wall-normal velocity is still imposed as inslip(u·n = u_body·n). When the transition sensor detects laminar flow ortau_w ≈ 0, the BC collapses tono-slip. Requireswallstressmodeland a wall-model law (blendedlogis the default).
Where, the wall stress model options include:
# Pick wall function, kind options: musker (default), reichardts, blendedlog, rough
kind = blendedlog
# If using rough wall model, specify the roughness in meters
# 0.25e-6m : highly polished
# 0.50e-6m : polished
# 3.33e-6m : painted
roughness = 0.5e-6
# Anchor y+ for wmpartialslip reconstruction (y+ units, default = 100)
partialslipheight = 100
mdot Immersed Boundary Condition:
This boundary condition allows the user to prescribe the inflow with thermodynamic conditions, and mass flow rate. A sample setup is shown below:
type = inlet
kind = [mdot]
mdot = 193.1277 # Mass flow rate in kg/s
area = 0.162647 # Injection area in m2 (3D) or m (2D)
#pressure = 1e5 # Optional pressure parameter
temperature = 300
massfractions = [0.992442,1e-8,1e-8,0.007558] # If running with MS
components = [2] # List of components to apply this BC
pressure parameter can be prescribed to enforce a pressure along the inlet. This can be useful to model over/underexpanded inlet flows. However, for such configuration, it is recommended to use the nozzle boundary condition instead. When pressure is not prescribed, the solver will extrapolate pressure from the interior.
Info
To easily switch between 3D and 2D modes, mdot and area can be kept the same, since only their ratio is considered in the code.
Info
The thermodynamic condition description for multi-phase is slightly different than for single and multi-species. Please refer to the Cartesian Multiphase Solver page for details.
outlet Immersed Boundary Condition:
This boundary condition lets flow leave the domain through an immersed surface, such as an engine inlet face or the exit of an internal duct. The outlet surface must be a separate component of the geometry, so that the surrounding walls can keep their own boundary condition. A sample setup is shown below:
BC_1 {
type = wall
kind = [wallstressmodel,blendedlog]
components = [1] # walls (WMLES)
}
BC_2 {
type = outlet
mach = 0.5 # target local Mach number normal to the surface
components = [2] # outlet surface
}
| Parameter | Description |
|---|---|
| mach | Target local Mach number. The pressure is set from the image-point pressure by the isentropic ratio between the target Mach number and the local normal Mach number; temperature is extrapolated. Where the local flow is reversed or supersonic, a slip wall is applied instead. |
| pressure | Static pressure. Density follows from the extrapolated entropy. Ignored where the local flow is supersonic. |
| temperature | Static temperature. Pressure follows from the extrapolated entropy. Ignored where the local flow is supersonic. |
| density | Density. Pressure follows from the extrapolated entropy. Ignored where the local flow is supersonic. |
Specify only one of these. If several are given, mach takes precedence, then pressure, temperature and density. If none is given, the full state is extrapolated. Pressures are clipped to the solver's minimum and maximum limits.
The optional kinds change the treatment where the flow is reversed (entering the domain through the outlet surface) or subsonic:
noreverse: apply a slip wall where the flow is reversed.dampreverse: on reversed points, raise the boundary pressure to the isentropic total pressure for the local normal Mach number, to oppose backflow.forcesupersonic: on subsonic points, lower the boundary pressure by0.5*rho*(a - u_n)^2to drive the flow toward sonic.
The wall model is applied only to wall components with wallstressmodel; outlet components get no wall model.
Warning
- The unstructured solver's
averagemachoption (one uniform back-pressure from the area-averaged Mach number) is not available in Cartesian. Withmach, the back-pressure varies over the surface with the local Mach number; check the area-averaged Mach number and mass flow rate in your results. - With
mach, reversed points are always treated as slip walls, sodampreversehas no effect andnoreverseis redundant. This differs from the unstructured solver, which keeps the Mach-driven pressure on reversed points. - Single species only; multispecies is not supported.
nozzle Immersed Boundary Condition:
The nozzle boundary condition is mainly used for launch simulations where the boundary condition is applied to the nozzle exit. It also comes with a few physics options to improve stability and control the output. A basic boundary condition can be specified via the following:
where the nozzle boundary condition takes an input file filename which has several supported file types datafiletype described below. Like the above boundary conditions, they are applied to a component on the triangulation specified by components. In a multispecies simulation, you must also specify ispecies which corresponds to the 0 based index of the mixture in the fluid section for which species the nozzle will eject.
A complete list of all the options is provided below, along with default options where applicable:
Main Options:
| Variable | Description |
|---|---|
| filename | (Required) The filename of the describing boundary condition file |
| datafiletype | (Required) The type of datafile. 0 is a steady (constant) ascii file. 1 is radially varying constant ascii file, 2 is unsteady but constant in space ascii file, 3 is unsteady radially varying binary, 4 is unsteady radially varying ascii file |
| ispecies | (Required for multispecies/multiphase) Specifies the component of mixture for the nozzle to eject. |
| nozzlecenter | (Optional) Specifies the coordinates of the nozzle center |
| nozzlenormal | (Optional) Specifies the normal for the boundary condition to be applied on |
| radiusdirection | (Optional) Unit vector in global coordinates used for projected-radius lookup: abs((x-nozzlecenter)·radiusdirection). When omitted, the default radial distance from nozzlecenter is used. Useful for planar/slot injection profiles. |
| asciilinetimestart | (Required) Only used for datafiletype=4. Specifies the line number to start reading the file. |
| asciilinetimestop | (Required) Only used for datafiletype=4. Specifies the line number to stop reading the file. |
| asciilinetimeskip | (Optional) Only used for datafiletype=4. Specifies the stride at which to read lines from the file. Default is 1. |
| asciilinereadspecies | (Optional) Only used for datafiletype=4. Bool for whether this file contains species information as well. Default is false. |
| numberofradialpoints | (Required) Only used for datafiletype=4. Specifies the number of radial points in the file. |
Note
The mixture state prescribed when asciilinereadspecies=true takes precedent over ispecies. In this case, ispecies is disregarded by the reader.
Ramp Options:
| Variable | Description |
|---|---|
| rampsteps | (Optional) Will linearly warmup the nozzle based on rampsteps number of timesteps by taking a linear combination of the reference Q and the user specified conditions in filename. Default is 0 (no step ramping). |
| rampnton | (Optional) The timestep number to turn the ramping on. Nozzle will be off prior to this timestep. (Only used with rampsteps). Default is -1. |
| ramptimestart | (Optional) If rampsteps is not turned on, the other ramping option is using simulation time. This is the same linear warmup between ramptimestart and ramptimestop. Before ramptimestart the nozzle is off if it is specified. Default is no time ramping. |
| ramptimestop | (Optional) The simulation end time to ramping. |
| timeshift | (Optional) Timeshift can be used to shift the nozzles in time relative to the simulation time. This is compatible with ramping. Default is 0. |
Note
One should only use (rampsteps and rampnton) or (ramptimestart and ramptimestop). They will not work in a combined fashion.*
Physics Options:
| Variable | Description |
|---|---|
| multiphaseequilibrium | (Optional) Only used in cartesian + multiphase. This computes multiphase equilibrium on the boundary condition. Default is false. |
| dostagnation | (Optional) Apply stagnation inlet boundary conditions. Not supported for multiphase. Default is false. |
| doautomaticsonicinlet | (Optional) Only used when dostagnation = false. If the boundary condition goes below subsonic speed, we get pressure from the interior. This keeps the velocity at the inlet >= mach 1. Not supported for multiphase. Default is false. |
| dothroatsonicinlet | (Optional) Only used when dostagnation = true. Forces the pressure to be sonic + 1%. Not supported for multiphase. Default is false. |
Projected Radius Option (radiusdirection)
By default, nozzle profile lookup uses the geometric radius from nozzlecenter.
When radiusdirection is provided, the lookup coordinate is projected onto that direction:
r_lookup = abs((x - nozzlecenter) · radiusdirection)
This enables planar/slot style injection profiles where variation is only along one direction.
Notes:
- radiusdirection is interpreted in global/cartesian coordinates.
- The input vector is normalized internally.
- A zero-length vector is invalid and will trigger an input error.
- If omitted, behavior remains the legacy radial-distance lookup.
Example slot-style setup (vary profile along y only):
BC_1 {
type = nozzle
datafiletype = 1
components = [1]
filename = nozzle_slot_profile.dat
ispecies = 0
nozzlecenter = [0.0, 0.0, 0.0] # Can be omitted. Solver will derive from geometry for each component
radiusdirection = [0.0, 1.0, 0.0]
}
ASCII Data Format
datafiletype = 0 or 1: steady, radially constant or varying, ascii file: radius(m) Pressure(Pa) Temperature(K) u_normal(m/s) u_radial(m/s)
datafiletype = 2: unsteady, radially constant, ascii file: time(s) Pressure(Pa) Temperature(K) u_normal(m/s) u_radial(m/s)
Info
Lines starting with # are omitted by the parser for datafiletype = 0, 1, 2.
datafiletype = 4: unsteady, radially varying, ascii file: line_number time(s) radius_x(m) radius_y(m) [radius_z(m)] Pressure(Pa) u_normal(m/s) u_radial(m/s) [u_azimuthal(m/s)] Temperature (m) [Species Mass Fractions]
Note
The format of datafiletype = 4 depends on the dimension of the configuration. The extra fields radius_z(m) and u_azimuthal(m/s) are required when running with 3D and must be omitted when running with 2D. Currently, the field u_azimuthal(m/s) is disregarded in the nozzle bc, however, it must still be present in the nozzle data file. Also, the fiels Species Mass Fractions are only present when asciilinereadspecies = true. Also, note that no comments are allowed in this file type format.
An example of a type-4 nozzle data base is shown below for the configuration asciilinetimestart = 0; asciilinetimestop = 30; asciilinetimeskip = 10; asciilinereadspecies = true:
0 -10000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
0 -10000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
10 1.000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
20 10000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
20 10000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
20 10000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
20 10000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
30 20000 0.000 0 0 10000 1000 0 0 1500 0. 0. 1. 0.
30 20000 0.500 0 0 40000 1000 0 0 1500 0. 0. 1. 0.
30 20000 1.000 0 0 80000 1000 0 0 1500 0. 0. 1. 0.
30 20000 1.965 0 0 110000 1000 0 0 1500 0. 0. 1. 0.
Domain Boundary Conditions
Absent user inputs, the farfield domain boundary conditions are set automatically based on reference conditions (e.g. Reynolds, Mach, temperature, alpha, beta).
We recommend using the automatically generated farfield boundary conditions for most external flow cases, when used with typical CFD best practices (domain should extend 50-100 body lengths in each direction).
However, for internal flows or half-span models, it may be necessary to specify farfield boundary conditions manually.
The 6 domain face boundary conditions are specified as follows, where type and kind are given. Each entry in the arrays corresponds to the x, y, and z directions respectively (index 0, 1, 2). The lo arrays define the boundary condition on the minimum face of each direction, and hi on the maximum face.
domain face type lo = [inlet ,wall , inlet]
domain face kind lo = [subsonic ,slip , subsonic]
domain face type hi = [outlet ,extrapolation, outlet]
domain face kind hi = [subsonic ,constant , subsonic]
inlet, wall, outlet, extrapolation, ref, periodic.
Available inlet kinds are: subsonic,mdot
Available wall kinds are: no-slip,slip
Available outlet kinds are: subsonic
Available extrap kinds are: constant,linear
For half-span models, the equivalent mirror boundary condition type is wall with kind slip. Periodic boundary conditions are supported but not recommended for thin strips of airfoils or wings because it severely limits the ability to coarsen away from the airfoil: due to its forest of octree design, we currently require at least 3 boxes across the smallest domain direction on the coarsest level. If thin periodic airfoils/wings is your primary use case, we suggest using LAVACurv or LAVAUnst as they are better suited to this type of task.
-
R. Mittal, H. Dong, M. Bozkurttas, F. M. Najjar, A. Vargas, and A. von Loebbecke, "A versatile sharp interface immersed boundary method for incompressible flows with complex boundaries," Journal of Computational Physics, vol. 227, pp. 4825–4852, 2008. ↩
-
Nakahashi, Kazuhiro. "Immersed boundary method for compressible Euler equations in the building-cube method." 20th aiaa computational fluid dynamics conference. 2011. ↩
Rigid Body Motion
Rigid Body Motion
Prescribed motion in the Cartesian solver is defined in numbered motion_N blocks and attached
by name either to immersed geometry — surfaces_N { motion name = <name> }, the body moves through
the fixed mesh — or to the whole mesh with moving grid motion = <name> in the cartesian section,
the ALE moving-grid mode in which every cell moves with the body.
motion_1 {
name = rotor # referenced by surfaces_N { motion name = rotor } or moving grid motion = rotor
type = prescribed # prescribed (default) | deformer | freeflight
method = constantrotation # pointangle (default) | velocityomega | constantrotation
rpm = 5400.0 # or angular speed = <rad/s>; signed, right-hand rule about axis
axis = [0, 0, 1] # 3D: required for a whole-domain moving grid
rotation center = [0, 0, 0]
}
name(required): the name other sections use to reference the motion.type:prescribed(default),deformer(structural deformation model) orfreeflight(free flight, configured in afreeflight { }sub-block). The rest of this section covers prescribed motion.method:pointangle(default) andvelocityomegaread a tabulated motion history fromfilename(velocityomegacolumns:t, vx, vy, vz, omegax, omegay, omegaz);constantrotationis analytic and needs no file — give exactly one ofangular speed(rad/s) orrpm, both signed by the right-hand rule aboutaxis.rotation center(default: the origin),axis(3D, normalized by the solver),translateandscale points(geometry transformation applied with the motion),scale angles,trans angles deg/trans angles radandyaw pitch roll = true(pointangleonly: scaling and offset of the tabulated angles, and the 3D rotation order),do inverse = true(apply the inverse motion).
In progress
This documentation will be published with an upcoming release.
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.
Cartesian Multiphase Solver
Theory guide
In LAVA, the multiphase model is the 4-eq Homogeneous Relaxation Model (HRM). This model assumes instantaneous mechanical and temperature relaxation between the species. When solved directly with stiffened-gas EOS for the liquid species, the numerical solution can fail for extreme cases with strong shocks and cavitation. This is due to the non-monotonic behavior of the speed of sound in a liquid/vapor mixture (see the formulation by Wood).
Thus, the LAVA solver employs a robust fractional method for time-stepping of the HRM model. Specifically, the 5-eq model of Allaire et al. (Allaire's model) is employed for the first hyperbolic step. In Allaire's model, the temperature of the species can be distinct from one another, resulting in the expansion of the thermodynamic degree of freedom (HRM: pressure, density, mass fractions; Allaire's: pressure, density, mass fractions, volume fractions). In the limit of infinitely fast temperature relaxation, an algebraic step is employed to relax the mixture into a single common temperature via modification of pressure and volume fractions 1. It is shown here that the Allaire's model + thermo-relaxation recovers the solution of the HRM model.
The model is further augmented with an approximate phase transfer model by Chiapolino et al.2.
A key consequence of the transition to Allaire's model for the hyperbolic step is that temperature information of all species must be present for consistency. This means that all mass and volume fractions must be strictly nonzero. In practice, we employ positivity-preserving limiters (PP) to enforce that partial densities and volume fractions are bounded from below by EPS = 1e-10 for double and 1e-6 for single precision. Input thermodynamic conditions are automatically adjusted so that this bound is met.
Specific Inputs
Mixture
Similar syntax to multi-species (MS), but first species must be liquid, and second species must be its corresponding vapor (optional), then the gas species in any order.
Navier Stokes
Options for the governing equations are set in this section.
navier stokes
{
viscous = false # required for MP. Default false
phase transition = true # Default false
use approximate solver = true # Default true
}
-
Viscous flow is not supported with MP yet.
-
phase transitioncontrols whether to perform phase transfer calculation or not. Then,use approximate solvercontrols whether to use the approximate model by Chiapolino et al. or perform root finding to exactly satisfy the Gibbs free energy balance.
Reference Conditions
The full set of thermodynamic variables required to specify the multiphase mixture is: pressure, temperature, and mass fractions.
reference conditions {
pressure = 1e5
temperature = 300.
mass fractions = [0.1, 0.1, 0.8]
multiphase equilibrium = true # default is false
# Other non-thermodynamic reference properties...
}
multiphase equilibrium = true, the first two components of the mass fractions vector will be recomputed so that the two liquid and vapor species have the same Gibbs free energy, i.e., the phases are in equilibrium with one another. This option is recommended when running with phase transition = true, see Navier Stokes.
Warning
For multiphase, there is no default values for the thermodynamic properties. The user must specify the complete state via one of the combinations above.
Initial Conditions
The user can specify regions in the domain where the initial conditions are modified from the reference condition. Details of this can be found in the Cartesian inputs documentation page. Multiphase requires more thermodynamic state information as described in Reference Conditions. Some examples of an initial condition patch for launch pad simulation, where we define a region of standing water, is shown below:
-
Fully-prescribed state
ic_1 { corner_1 = [-64.6, -1.0] corner_2 = [ 0.0, 1.6] velocity = [0.0,0.0,0.0] pressure = 101325.000000 temperature = 300. multiphase equilibrium = true # Optional option to specify phase eq. Default is false mass fractions = [9.9999997964053133e-01, 3.5946861473104996e-10, 1.0000000000000000e-08, 1.0000000000000000e-08] } -
Modified state, where pressure field is omitted since it is the same as the reference condition
ic_1 { corner_1 = [-64.6, -1.0] corner_2 = [ 0.0, 1.6] velocity = [0.0,0.0,0.0] temperature = 300. multiphase equilibrium = true # Optional option to specify phase eq. Default is false mass fractions = [9.9999997964053133e-01, 3.5946861473104996e-10, 1.0000000000000000e-08, 1.0000000000000000e-08] }
The extra option multiphase equilibrium controls whether the mass fraction of the IC state is modified to satisfy phase equilibrium.
Standing Water Exact Q
For launch pad simulations, when prescribing an IC patch for the standing water, the standing water Exact Q option can be employed to spatially smooth the transition between the IC patch and the reference condition in the rest of the domain.
Here, theinterface thickness is a required input (in meters) that dictates the thickness of the transition layer between the IC patch and the surrounding. The blending between IC and reference conditions is accomplished in the following manner, depending on the setting phase transition in Navier Stokes:
- The blending is done on pressure, temperature, and mass fractions. Volume fractions are recomputed to match the single mixture temperature. Furthermore, if
phasetransition = true, then the liquid/vapor compositions are also recomputed to achieve phase equilibrium.
Immersed Boundary Conditions
Wall Conditions
Since viscous=true is not supported with MP, only slip adiabatic wall is supported
mdot Inlet Condition
In the MP solver, the mdot inlet condition is typically used for aerated water injection. In contrast to the MS and NS1 case, the method for prescribing the thermodynamic condition of the injected flow is slightly different, with the addition of the multiphaseequilibrium option.
Info
To maintain robustness of the injected flows, LAVA will automatically modify the prescribed mass/volume fractions if needed to ensure that PP bounds are not violated.
BC_1 {
type = inlet
kind = [mdot]
temperature = 300
multiphaseequilibrium = true # Default false
massfractions = [0.992442,1e-8,1e-8,0.007558]
# Other non-thermodynamic inputs...
}
Nozzle Boundary Conditions
BC_1
{
type = nozzle
datafiletype = 4
dostagnation = false
multiphaseequilibrium = true
components = [56]
timeshift = 0.0
asciiLineTimeStart = 0
asciiLineTimeStop = 1
asciiLineTimeSkip = 1
asciiLineReadSpecies = true
nozzle normal = [-0.9999416651122017, -0.010795763249607787, 3.4331981600350204E-4]
numberofradialpoints = 200
filename = rd181_exitplane.dat
ispecies = 2
}
multiphaseequilibrium = true is used to specify whether the injected state is required to be at phase equilibrium or not.
Recommended Compositional Inputs
- Automatic adjustments are in place to ensure that the specified state does not violate PP bounds. These guarantee features is available for reference condition, initial conditions with/without standing water exact Q, mdot Immersed BC, and nozzle BC.
- Even then, to ensure robustness and avoid any unseen edge cases, make sure that each component of input mass fractions are at least 1e-8.
References
-
Wong, M. L., Angel, J. B., Barad, M. F., and Kiris, C. C., "A Positivity-Preserving High-Order Weighted Compact Nonlinear Scheme for Compressible Gas-Liquid Flows," Journal of Computational Physics, Vol. 444, 2021, p. 110569. https://doi.org/10.1016/j.jcp.2021.110569 ↩
-
Chiapolino, A., Boivin, P., and Saurel, R., "A Simple and Fast Phase Transition Relaxation Solver for Compressible Multicomponent Two-Phase Flows," Computers & Fluids, Vol. 150, 2017, pp. 31--45. https://doi.org/https://doi.org/10.1016/j.compfluid.2017.03.022 ↩
Tutorials
Supersonic Flow Over a Diamond Airfoil
This tutorial provides new LAVA Cartesian users with an introductory two-dimensional problem that is small enough to be run on almost any computer.
Problem description
Mach 1.5 flow over a two-dimensional diamond airfoil. This is relevant for sonic boom prediction and showcases the classic shock/expansion pattern around an airfoil (oblique shocks and expansion fans), visible in the pressure and density fields.
Learning goals:
- Learn how to set up LAVA Cartesian input deck to run inviscid flow past a 2D simple geometry
- Learn how to use the basics of the error metric based adaptive mesh refinement (AMR) capability using two AMR paradigms:
- a fixed error-metric threshold configuration in
run.inputs - a distribution-based threshold configuration with a cell-count target in
run_auto.inputs
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Cartesian Solver Inputs
Tutorial Files
The inputs and geometry files can be downloaded here and we will describe the components of it in this tutorial.
| File | Description |
|---|---|
| run.inputs | Solver input file (fixed-threshold AMR) |
| run_auto.inputs | Solver input file (distribution-based AMR thresholds) |
| diamond.fmt | Diamond airfoil surface definition |
| line_probe_viz.py | Line plot extraction script |
Mesh Setup
The Diamond Airfoil case uses LAVA Cartesian’s immersed-boundary method and AMR grid. The airfoil surface is loaded from diamond.fmt and rotated in the input:
This applies a 45° in-plane rotation to the diamond airfoil. The purpose of this rotation is to align the resulting shocks with the Cartesian mesh directions and is optional, but does affect the accuracy of the results.
The overall domain size and the baseline refinement setup are set in the grid { ... } block. In this case, finest dx = 0.01 sets the smallest target cell size and targetrelativefarfielddistance = [200^3] places the farfield boundaries far away (in units of the reference length). Refinement is forced around the immersed geometry (tag all geometry = true) and is also enforced in a fixed fine box around the airfoil (tagboxes_1 with dx = 0.0, requesting the finest available spacing). This fixed box ensures the near-body region remains well resolved regardless of the error-metric tagging state.
grid
{
finest dx = 0.01
targetrelativefarfielddistance = [200^3]
# diamond-grid_amr-start
regrid interval = 100
max box size = 8
tag all geometry = true
solution based amr
{
method = user
error metric time method = ins
error metric stats interval = 100
error metric threshold finest = 0.025
error metric threshold ratio = 0.5
regridgrowerrormetrictags = 1
errormetric_1
{
type = laplacianp
weight = 1.0
}
}
# diamond-grid_amr-end
#fine box over entire airfoil and nearby
tagboxes_1
{
lo = [-0.55, -0.55]
hi = [ 0.55, 0.55]
dx = 0.0
}
}
AMR Settings
For this problem, the goal of using AMR is to automatically capture the shock and expansion physics accurately without manually specifying refinement regions away from the airfoil. We illustrate two AMR paradigms using the two input files provided:
run.inputsuses a fixed error-metric threshold.run_auto.inputsuses distribution-based thresholding.
All the figures and results in this tutorial are generated with run.inputs, however, run_auto.inputs is provided as an alternative configuration that targets a similar mesh automatically, using the same error-metric machinery. The AMR concepts below apply to both paradigms; the only difference is whether you choose thresholds directly (run.inputs) or let the solver infer them from the distribution of the error metric (run_auto.inputs) as documented in the Cartesian solver input reference.
AMR operates on boxes with size specified by the max box size input parameter. Here, we utilize the recommended size, max box size = 8, which specifies that each box will contain \(8^2\) cells. The second parameter of interest is regrid interval which determines how often to adapt the mesh. This parameter presents a significant tradeoff: set it too low and the computational cost increases significantly, or set it too high and risk having the physical features of the flow move beyond the refinement regions during its evolution. Considering this as a shock evolution problem rather than a steady state one, and we set regrid interval to a fairly low value in order to accurately capture shock motion. In line with this approach, we want the error metric to reflect the instantaneous state of the solution so we set error metric time method = ins instead of using any kind of time-averaging.
With this choice, we only require the error metric to be computed at the regrid interval and thus set error metric stats interval = regrid interval. To avoid having to adapt the mesh at every time step, we provide a buffer of the size of one box \(8^2\) cells through the parameter regrid grow error metric tags = 1.
Increasing this parameter to 2 could potentially allow us to increase the regrid interval and perhaps reduce overall turnaround time.
Conversely, we do not recommend reducing regrid grow error metric tags without reducing regrid interval because that would increase the likelihood that an important feature is poorly resolved during time steps between regrid intervals.
AMR may be configured to target geometry, a desired yplus value, or solution-based error metrics. Often, a combination of all three is used. To specify solution-based AMR, we must include a solution based amr {} subsection. Error metrics are specified within the solution based amr {} section through enumerated subsections as follows:
For this case we choose, we set type = laplacian p. This sets the error metric to the Jameson-Schmidt-Turkel (JST) pressure-based discontinuity sensor 1. The second parameter weight = 1.0 sets a constant weight for each level of the Cartesian mesh. If we wanted to use two error metrics, we could do the following:
laplacian p and laplacian t quantities.
Fixed-threshold AMR (run.inputs)
Refinement and coarsening are controlled through thresholds. These may be specified within the solution based amr {} section as follows:
In run.inputs we set method = user. In this case, two parameters determine the refinement and coarsening criteria: error metric threshold finest and error metric threshold ratio. The first (error metric threshold finest) refers to the error metric value beyond which we want covered with the finest mesh available.
The second (error metric threshold ratio) determines the range of values that should be captured by each subsequently coarser mesh resolution level in the AMR tree structure.
For example, error metric threshold finest = 0.05 will refine all boxes that have at least one cell for which the error metric value is equal to or larger than 0.05 to the finest available mesh resolution level of finest dx = 0.01 meters.
And error metric threshold ratio = 0.5 means that the second finest mesh level will be used for values ranging from 0.025 to 0.05, the third finest 0.0125 to 0.025, and so on until the coarsest level is reached.
The ratio should theoretically be set based on the order of accuracy of the error metric, which should ideally mirror the overall order of accuracy of the solution scheme.
The JST pressure-based discontinuity sensor is based on a second order discretization of the Laplacian operator.
However, shock capturing schemes tend to reduce to somewhere between second and first order accuracy at strong shocks, and so will the error metric based on that solution.
The other consideration is that using error metric threshold ratio = 0.25 could also yield a larger overall cell count spread over a larger area.
We recommend you play with these parameters and inspect the resulting mesh to get a feel for how they affect solution accuracy and turnaround time.
Distribution-based AMR (run_auto.inputs)
In the distribution-based approach used in run_auto.inputs, you do not specify error metric threshold finest explicitly. Instead, you set method = auto and set a global cell-count cap with max cells = 600000 inside the grid block.
The solver then scans the instantaneous error-metric distribution and automatically selects refinement/coarsening thresholds that approximately satisfy the requested cell budget, using the same regrid interval, error metric time method, and tagging growth options as in the fixed-threshold case.
This is useful when you care more about keeping the mesh size under control than about matching a particular error-metric value.
Outside the fixed refinement regions like the tag box setup above, AMR in both paradigms is driven by refinement sensors so the mesh can follow flow features as the solution evolves. The mesh is rebuilt periodically using regrid interval, which specifies the number of timesteps between AMR regridding operations. Smaller values track moving features more tightly at higher computational cost, while larger values reduce regridding cost but can allow features to drift relative to the refined region between regrids.
Important Remarks
Refinement aggressiveness is governed by the error metric thresholds. Decreasing them makes refinement easier to trigger (more refined cells and less coarsening), while increasing them makes refinement harder to trigger. The thresholds are interpreted level-by-level: when the (instantaneous, in this case) error metric exceeds the threshold corresponding to refining from a given level, that region is tagged to refine to the next finer level. When it falls below the coarsening criterion, it becomes eligible to coarsen on the next regrid. The difficulty in AMR is knowing which thresholds to choose, which is not a solved problem. Therefore, it is recommended to try the distribution-based thresholding (method = auto) procedure for an easy startup mode. We only warn that this may result in a rapidly growing cell count, which is why we recommend constraining the growth by providing a max cells input parameter.
regrid interval = 100
max box size = 8
tag all geometry = true
solution based amr
{
method = user
error metric time method = ins
error metric stats interval = 100
error metric threshold finest = 0.025
error metric threshold ratio = 0.5
regridgrowerrormetrictags = 1
errormetric_1
{
type = laplacianp
weight = 1.0
}
}
The figure below shows a visualization of the grid (refinement boxes and cells) used for this case:
This is a zoomed-out view of the domain colored by pressure, showing how the refinement tags follow shocks/expansions far from the airfoil. The black outlines are the boxes which each contains \(8^2\) cells.
Flow / Solver Settings
The free-stream state is set in reference conditions:
The free-stream direction is controlled by alpha and beta, which rotate the incoming flow direction relative to the +x axis. In 2D cases, beta sets the in-plane inflow angle; here beta = -45 gives a 45° incidence relative to +x.
This case is inviscid (viscous = false), so the main features are compressibility-driven shocks/expansions rather than boundary-layer physics:
We recommend to use our default settings for the convective flux which are robust but not too dissipative.
convective terms
{
scheme = hwcns # variant of the Hybrid Weighted Compact Non-linear Scheme, https://arc.aiaa.org/doi/pdf/10.2514/6.2011-3857
flux function = hllec # Robust Harten-Lax-Leer-Einsfeldt-Contact approximate Riemann solver (https://doi.org/10.1007/BF01414629)
fluxorder = 4 # formally 3rd or 4th order convective terms via nodal flux blending with face fluxes
interporder = 3 # third order left and right state interpolation to the face
limiter = weno3op # 3rd order Weighted Essentially Non-Oscillatory interpolation with optimal accuracy, https://epubs.siam.org/doi/pdf/10.1137/19M1260396
upwind blending sensors = [weno] # use WENO-type sensor on density to detect stencils with discontinuities and use upwind there and central otherwise
central components = [q] # blend all primitive variables between upwind and central interpolation based on upwind blending sensors
}
Time integration uses a five-stage, third order explicit strong-stability preserving Runge-Kutta method (SSPRK53) with CFL-based time stepping set just below the stability limit of the method:
time
{
steady = false
#number of steps = 10000
number of steps = 1500
cfl = 2.5
}
# diamond-time-end
# diamond-solver_defaults-start
solver defaults
{
explicit {method = ssprk53}
}
Running the Simulation
From the run directory, launch the solver:
Executable Names
The Cartesian solver executable name varies by architecture. See the LAVA Installation Guide for details.
This example uses 2 MPI ranks with 64 OpenMP threads each (total of 128 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Outputs
The output { ... } block controls what gets written and how often. monitor { ... } prints a set of runtime diagnostics (for example timestep/time, max CFL, block/cell counts, throughput, and memory usage) at a fixed interval, which is useful for quickly checking stability and performance during the run. This case writes volume/surface fields, restart files, and a 1D line probe. interval is the number of timesteps between each written file.
output
{
timeaveraging { start ctu = 0.695 }
monitor{
interval = 100
variables = [nt,time, dt,maxcfl,blocks_1*,numcells,mups,memory,elapsed,cl_airfoil,cd_airfoil]
}
loads
{
name = airfoil
include = [1]
normalize = true
interval = 100
}
volume
{
interval = 1000
variables = [q,mach,density,mask,wenoshocksensor,errormetric]
}
surface
{
variables = [q,mach,density]
interval = 1000
}
restart
{
interval = 10000
}
# diamond-line_probe-start
line probe_1 {start = [-2.0, 4.0];end = [2.0, 4.0];number of points = 100;interval = 100}
# diamond-line_probe-end
}
Post Processing
The figure below is a rendering of the pressure over the diamond airfoil. You can see the high-pressure shock pattern on the compression side and the low-pressure pattern on the expansion side.
Line probe comparison
As shown in Nemec et al. 2, a convenient way to compare solutions is to extract a 1D line probe and plot its pressure profile. The line probe used in this case is defined in run.inputs as:
The corresponding outputs are written under line_probe/ (e.g. line_probe/000.Cart.*.line).
The plot below was generated by line_probe_viz.py, which overlays the pressure profile from several timesteps. This provides a simple way to show the solution converging toward a steady state. By timestep 5000
the profile is already almost exactly matching the timestep 10000 result.
Relevant Publications
-
Jameson, A., Schmidt, W., and Turkel, E., "Numerical Solution of the Euler Equations by Finite Volume Methods Using Runge Kutta Time Stepping Schemes," 14th fluid and plasma dynamics conference. https://doi.org/10.2514/6.1981-1259 ↩
-
Nemec, M., Aftosmis, M., and Wintzer, M., "Adjoint-Based Adaptive Mesh Refinement for Complex Geometries," 46th AIAA aerospace sciences meeting and exhibit. https://doi.org/10.2514/6.2008-725 ↩
High-Lift Common Research Model (CRM-HL) WMLES
This tutorial applies the LAVA Cartesian solver on High Lift Prediction Workshop 5 (HLPW5) high-lift aircraft configuration 2.4 to demonstrate a complex immersed-boundary setup (many components) with component-based refinement. It also demonstrates different wall boundary conditions, and a scheduled mesh refinement progression driven by schedule.dat. The schedule enables on-the-fly control of many solver parameters through a small table keyed by convective time units (CTU). The schedule decreases the minimum mesh spacing available from 32 mm to 4 mm in sequence controlling the number of CTUs spent on each mesh resolution. This is an advanced capability that can be leveraged to run something akin to a grid refinement study with "warm starts" in a single simulation. For a true independent ("cold start") grid refinement study, we recommend performing 3 or more separate simulations only changing the reference dx parameter and using finest dx_rel=1 where dx is successively reduced by factors ranging from \(2^{-\frac{1}{3}}\) to \(2^{-1}\).
Our group's work on the \(5^{th}\) high lift prediction workshop has been published by Sozer et al.1 and you can find a detailed summary of our results as well as methodology in that work.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Cartesian Solver Inputs
Tutorial Files
The inputs and geometry files can be downloaded here and we will describe the components of it in this tutorial.
| File | Description |
|---|---|
| run.inputs | Solver input file |
| schedule.dat | Schedule file |
| run.pbs | PBS job script |
| 2p4_ONERA_LDG_v28.fro | Surface representation |
Reference conditions
The flow conditions are specified in the reference conditions { ... } block:
reference conditions {
mach = 0.2
Re = 5.9e6
temperature = 288.15 # K
alpha = 19.7 # deg
beta = 0.00
length = 7.00532 # m
area = 191.844778 # Half Sref m2
dx = 16e-3
}
When alpha and beta are specified (in degrees), the flow is set up in standard airplane coordinate frame (+x downstream, +y right wing, +z toward ground). alpha is the angle of attack (pitch angle), and beta is the sideslip angle (yaw angle). This case is setup with a high angle of attack near the maximum lift of alpha = 19.7 and no sideslip beta=0.0.
Geometry and Boundary Conditions
The high-lift geometry is loaded as an immersed surface triangulation:
The triangulation contains many labeled components (wing, flap system, slats, fuselage sections, nacelles, tails, etc.). In run.inputs, the component list is recorded as comments next to the geometry block. These component IDs are used directly to assign wall treatments and target grid spacings.
Wall boundary conditions are defined per component using two groups:
BC_1:kind = [slip, wallstressmodel, blendedlog]BC_2:kind = [slip, wallstressmodel, wmnoslip]
bcs
{
BC_1{type = wall; kind = [slip,wallstressmodel,blendedlog];components = [1-13,15-33]}
BC_2{type = wall; kind = [slip,wallstressmodel,wmnoslip]; components = [14]}
ibmethod = gcm
gcmtype = imagedist
}
Most components (components = [1-13,15-33]) use the blendedlog wall-model law, which blends viscous-sublayer and logarithmic behavior in an approximation of Musker's wall function to compute wall stress. The slats (components = [14]) use the wmnoslip variant, which applies a linear no-slip law for the wall-stress evaluation. In both cases the ghost-cell treatment is slip-based (zero normal velocity) and only the wall-model law used to compute the stress differs.
The immersed-boundary method uses ibmethod = gcm with gcmtype = imagedist, which enforces the wall-normal velocity using an image-distance construction and is a good default for static geometries (not moving or deforming with respect to the Cartesian background grid).
Domain Boundary Conditions
The outer-domain faces are defined separately from the immersed-surface wall treatment. These boundary conditions apply to the outer boundaries of the Cartesian domain, while the immersed geometry (aircraft) uses separate wall boundary conditions defined in the bcs section.
domain face type lo = [inlet ,wall , inlet]
domain face kind lo = [subsonic ,slip , subsonic]
domain face type hi = [outlet ,extrapolation, outlet]
domain face kind hi = [subsonic ,constant , subsonic]
These entries specify the boundary condition on each low/high face in the x, y, and z directions of the Cartesian domain. For this case: - x-direction: subsonic inlet at upstream (x-lo) and subsonic outlet at downstream (x-hi) - y-direction: slip wall at y-lo (symmetry plane) and constant extrapolation at y-hi (far-field) - z-direction: subsonic inlet at bottom (z-lo) and subsonic outlet at top (z-hi)
Grid Setup
The Cartesian domain and near-body resolution targets are configured in the grid { ... } block:
grid {
finest dx = 0.004
targetfarfielddistance = [1048.576, 1048.576, 524.288]
aligndomainfacetoorigin = [none, lo, none]
max box size = 8
component tagging_1 {components = [2,6,10,14,15,16,18 ];dx = 0.004;type = component }
component tagging_2 {components = [1,3-5,7-9,11-13,17,19,22-28,30-33];dx = 0.008;type = component }
component tagging_3 {components = [20-21 ];dx = 0.016;type = component }
...
}
align domain face to origin = [none, lo, none] ensures the domain starts at y=0 with the symmetry plane boundary condition. Component tagging enforces near-body target spacings by component ID (e.g., 4 mm on selected high-interest parts, 8 mm on most components, and 16 mm on selected fuselage components). This provides deterministic near-body resolution before solution-based refinement drives additional AMR.
AMR Controls
Regridding cadence and solution-based AMR are configured in the grid { ... } block. The main control is the solution based amr { ... } block:
regrid interval = 5000
solution based amr
{
method = auto
max cells = 930000000 # AMR control: limits the number of cells within +/- 5%
errormetricgeomdistancescalingreflength = 1.0
errormetrictimemethod = avg # AMR control: use time-averaged error metric for mesh adaptation
errormetricexponentialmovingaveragewindowctu = 5.0 # AMR control: EMA window for error metric averaging in CTU
errormetricstatsinterval = 10 # AMR control: how often to update statistics from instantaneous error metric
regridgrowerrormetrictags = 1 # AMR control: pad boxes scheduled for refinement by 1 to allow longer intervals
errormetricthresholdratio = 0.5
errormetric_1
{
type = smallscaleenergy
weight = 1.0
}
}
The solution based amr block uses method = auto, which sets refinement and coarsening thresholds automatically from the distribution of the defined error metric(s) (distribution thresholding). max cells caps the total number of cells (here 930M at the finest schedule level); this value is also updated from schedule.dat at each level transition, so the cap increases with the number of active levels (e.g., 50M at 10 levels, 175M at 11, 580M at 12, 930M at 13). Limiting cells in this way keeps the run tractable while allowing the mesh to grow as new refinement levels are unlocked.
The small-scale energy error metric (errormetric_1 { type = smallscaleenergy; weight = 1.0 }) detects unresolved turbulent kinetic and internal energy fluctuations. The error metric is time-averaged (errormetrictimemethod = avg) to make adaptation less sensitive to instantaneous noise. errormetricexponentialmovingaveragewindowctu = 5.0 sets the exponential moving average window to 5 convective time units (CTU), giving more weight to recent values. errormetricstatsinterval = 10 controls how frequently the instantaneous error metric is computed and its time-average updated.
errormetricgeomdistancescalingreflength = 1.0 scales the error metric down with distance from the geometry (scaling factor = 1/2^(distance/reflength)), preventing refinement of far-field features like shocks all the way to the domain boundary.
errormetricthresholdratio = 0.5 defines the ratio between successive refinement levels: each coarser level uses a threshold that is half the next finer level, creating a graded refinement structure. Tag growth (regridgrowerrormetrictags = 1) pads refinement regions by one layer of boxes (8^3 cells) to support longer regrid intervals.
errormetric is written in the volume outputs so you can visualize it alongside the AMR boxes and tune the error-metric weight and threshold ratio.
Scheduled startup with schedule.dat
This case demonstrates scheduled updating of inputs during time stepping using a CTU-triggered schedule. The inputs updating block at the top of run.inputs enables re-reading inputs at a fixed step interval and applying scheduled changes: do levels = true and do maxcells = true apply the number of active refinement levels and the solution-based AMR cell cap from the schedule file; do upwind blending min = true applies the upwind blending minimum. The schedule is triggered by trigger = ctu and read from schedulefile = schedule.dat.
The schedule file (schedule.dat) contains:
00.0 10 50000000 0.1
005.0 10 50000000 0.05
010.0 10 50000000 0.0
030.0 11 175000000 0.05
035.0 11 175000000 0.0
050.0 12 580000000 0.05
055.0 12 580000000 0.0
070.0 13 930000000 0.025
075.0 13 930000000 0.0
Each row has the form ctu finest_level max_cells upwind_blending_min. The run starts at 10 levels with a maximum of 50 million cells and increases to 13 levels in stages, with the cell cap raised at each transition (e.g., 175M at 11 levels, 580M at 12, 930M at 13). When transitioning from 10 to 11 levels (at CTU 30.0), the 11th level of refinement is unlocked and the AMR max cells limit is updated from the schedule, allowing the mesh to grow to that level. Similarly, transitions to 12 and 13 levels unlock those refinement levels and their corresponding cell caps. At each level increase, upwind blending min is temporarily raised (0.05 or 0.025) for improved numerical stability during the transition, then returned to zero once the transients caused by the refinement have been convected downstream.
Numerics and turbulence model
The key numerics for this case are:
convective terms{
scheme = hwcns
flux order = 4
interp order = 3
central components = [none]
upwind blending sensors = [ducros]
fluxfunction = keepg hlle
limiter = none
}
turbulence {
sgs model = vreman
}
scheme = hwcns: Hybrid Weighted Compact Non-linear Scheme (HWCNS). Blends central and upwind discretizations using weighted compact interpolation with sensor-based blending, reducing dissipation in smooth regions while remaining robust near discontinuities.fluxfunction = keepg hlle: Kinetic-Energy and Entropy Preserving flux with Geometric mean (KEEPG) combined with the HLLE (Harten-Lax-van Leer-Einfeldt) approximate Riemann solver. The KEEPG part uses geometric mean averaging for density and internal energy to preserve kinetic energy and maintain entropy consistency, while HLLE provides robust dissipation at shocks and strong gradients.flux order = 4: fourth-order flux finite-difference discretization using face fluxes.interp order = 3: third-order left/right state reconstruction. Withlimiter = none, this gives higher-order upwind-biased interpolation for the HLLE flux.central components = [none]: required with KEEPG HLLE flux function because we are blending a central flux (KEEPG) with a purely upwind flux (HLLE) using the upwind blending sensors.upwind blending sensors = [ducros]: Ducros sensor controls blending toward upwind fluxes in regions of strong compression or high divergence/vorticity ratio (e.g., shocks and strong vortices).limiter = none: strictly uses linear interpolation weights for the HLLE flux to reduce numerical dissipation for this nominally low Mach flow
Turbulence modeling uses the Vreman subgrid-scale (SGS) model, consistent with a wall-modeled LES (WMLES) framework.
Trip lines (transition forcing)
This case includes 12 trip lines located on the wing upper surface, nacelle (inner/outer), nacelle pylon, horizontal tail leading edge (upper/lower), vertical tail leading edge, and fuselage nose. These replicate the experimental trip configuration so that the boundary layer transitions at the intended locations before the LES model captures the turbulent flow development.
trip_line_1 {dxscale=1.0
begin=[2.546070E+01,3.052050E+00,4.729215E+00]
end=[2.618612E+01,3.971736E+00,4.802266E+00]
segmentlength=2
segmentskip=3
segmentradius=0.9
projectionmethod=closest
projectionmaxdistance=3}
A trip line applies a penalty source term to cells within a small distance of the line, analogous to physical trip dots/strips used in wind-tunnel experiments. The line is segmented into active/inactive sections (via segmentlength and segmentskip) to create a dashed pattern, and it can be projected onto the nearest surface (projectionmethod = closest).
The parameter trip time relaxation = 40. controls the strength of the trip forcing. The trip applies a momentum source term that opposes the local velocity, with a relaxation time scale of trip time relaxation × dt. Lower values of trip time relaxation result in a shorter relaxation time, producing a larger source term and thus stronger, more aggressive forcing.
Outputs (monitor, volume/surface, probes, loads)
The output { ... } block controls what is written and how often. The key outputs in this tutorial include:
monitor: runtime diagnostics (CFL, Mach, forces/moments, grid/box counts, performance)volume: flow fields pluserrormetricand sensors (useful for AMR tuning)surface: wall-model related fields and flow variables on the immersed surface- cut-plane “surface probes”: multiple x- and y-normal planes for section analysis
isosurfaces_*: planar cuts and Q-criterion isosurfaces written as VTKloads: integrated aerodynamic coefficients on the full airplane, wing, tail, and wing+fuse groupings
Relevant lines from run.inputs:
output {
output buffer interval isos = 10000
output buffer interval surf = 10000
time averaging { start ctu = 14; method = exponential; window ctu = 10.0 }
The output buffer interval parameters control how frequently buffered outputs are written to disk. Setting output buffer interval isos = 10000 and output buffer interval surf = 10000 means isosurface and surface outputs are buffered in memory and written every 10,000 steps, reducing I/O overhead for high-frequency outputs.
The time averaging block sets the schedule for statistical averaging of the flow fields. Averaging itself is enabled by listing the averaging tokens (qstats, qavg, ...) in the variables list of the volume and surface outputs; LAVA then writes averaged volume files alongside the instantaneous ones, and adds the surface statistics as extra columns of the ordinary surface files. Time averaging begins at start ctu = 14. method = exponential uses an exponential moving average instead of a simple cumulative time average, giving more weight to recent values, and window ctu = 10.0 sets the effective averaging window length to 10 convective time units.
monitor
{
reset if missing = true
interval = 100
variables = [nt, ctu, dt, maxcfl,maxmach, cl_airplane,cd_airplane,cmy_airplane,blocks_1*,numcel*,wallt,mups,mups_max, mups_long, elapsed, memory_gpu]
}
volume {
interval = 100000
variables = [q, density, mach,mask, errormetric, vorticity, strainsensor, ducrossensor]
}
surface { variables = [q,wallmodel,qstats]; interval = 1000 }
# cut planes
surface probe_1 {point = [27.81, 0,0];normal = [1, 0, 0];interval = 1000 }
surface probe_2 {point = [30.099, 0,0];normal = [1, 0, 0];interval = 1000 }
surface probe_3 {point = [32.38, 0,0];normal = [1, 0, 0];interval = 1000 }
surface probe_4 {point = [37.72, 0,0];normal = [1, 0, 0];interval = 1000 }
surface probe_5 {point = [44.07, 0,0];normal = [1, 0, 0];interval = 1000 }
surface probe_6 {point = [0, 20.19,0];normal = [0, 1, 0];interval = 1000 }
surface probe_7 {point = [0, 5.08,0];normal = [0, 1, 0];interval = 1000 } #A
surface probe_8 {point = [0, 7.76,0];normal = [0, 1, 0];interval = 1000 } #B
surface probe_9 {point = [0, 10.18,0];normal = [0, 1, 0];interval = 1000 } #C
surface probe_10 {point = [0, 12.6,0];normal = [0, 1, 0];interval = 1000 } #D
surface probe_11 {point = [0, 15.15,0];normal = [0, 1, 0];interval = 1000 } #E
surface probe_12 {point = [0, 17.96,0];normal = [0, 1, 0];interval = 1000 } #F
surface probe_13 {point = [0, 20.76,0];normal = [0, 1, 0];interval = 1000 } #G
surface probe_14 {point = [0, 23.18,0];normal = [0, 1, 0];interval = 1000 } #H
surface probe_15 {point = [0, 26.37,0];normal = [0, 1, 0];interval = 1000 } #I
surface probe_16 {point = [0, 28.92,0];normal = [0, 1, 0];interval = 1000 } #J
isosurfaces_1{ point = [0,7.76,0]; normal = [0,1,0]; format = vtk; interval = 1000; colorfields = [errormetric] }
isosurfaces_2{ point = [0,7.76,0]; normal = [0,1,0]; format = vtk; interval = 1000; colorfields = [densitygradmag] }
isosurfaces_3{ contour = qcriterion; isovalue = 1e6; format = vtk; interval = 5000; colorfields = [umag] }
isosurfaces_4{ contour = qcriterion; isovalue = 1e5; format = vtk; interval = 5000; colorfields = [umag] }
restart {
interval = 20000
}
flow_stats { }
loads {
moment center = [33.67786,0.0,4.51993]
interval = 100
# Provide non-dimensional force and moments
normalize = true
# Use gauge pressure (p-p_ref) in pressure forces
gauge = true
group_1 {
name = airplane
include = [1-28,30-33]
}
group_2 {
name = wing
include = [1-19]
}
group_3 {
name = tail
include = [24-28,30-33]
}
group_4 {
name = wing_fuse
include = [1-23]
}
}
}
Running on the NAS cluster (PBS)
LAVA has several build variants (depending on solver capabilities and hardware). This tutorial case should be run with the NS1 3D executable. See the installation guide for more details and picking an executable for your hardware.
This case was run on A100 nodes on the NAS Cabeus cluster. This tutorial includes an example PBS script (run.pbs) that targets those GPUs.
Post-processing
Example results from the HLPW5 simulation are shown below.
Figure 1: Skin friction coefficient on the wing
Top-down view of the wing showing the coefficient of friction distribution in the streamwise (x) direction.
Figure 2: Q-criterion isosurface
Q-criterion isosurface (isovalue = 100,000) colored by Mach number, showing vortical structures in the flowfield.
Figure 3: Time history of aerodynamic coefficients and mesh growth
Time history showing a 2×2 panel. The top left panel shows the lift coefficient from the loads_1 group (airplane), which includes components [1-28,30-33]. The top right panel shows the drag coefficient from the same airplane group. The bottom left panel shows the pitching moment coefficient (C_My) on the airplane. The bottom right panel shows the number of cells, demonstrating the scheduled mesh refinement in action as levels increase from 10 to 13, reaching approximately one billion cells on the fine mesh at 70 CTU.
This plot can be generated using the following command from the run directory:
plotHist.py -F monitor/Cart.data.iter ctu cl_airplane cd_airplane cmy_airplane numcells -doSubplot -xRange 10 100
Figure 4: Lift coefficient zoom (80–100 CTU)
Zoomed-in time history of the airplane lift coefficient from 80 to 100 CTU, showing the mean lift achieved on the finest mesh level of 2.637.
This plot can be generated using:
Relevant publications
-
Sozer, E., Barad, M. F., Housman, J. A., Cadieux, F., Sousa, V., Dumlupinar, E., Saurabh, K., Ravikumar, K., and Duensing, J. C., "LAVA WMLES Results for the 5th High-Lift Prediction Workshop," American Institute of Aeronautics; Astronautics, 2025. https://doi.org/10.2514/6.2025-0887 ↩
Genesis Capsule
Genesis was a NASA sample-return probe that collected a sample of solar wind particles and returned them to Earth for analysis. A simplified outer mold line of the Genesis Sample Return Capsule was reconstructed from an available publication 1, matching the ballistic test configuration from the Aeroballistic Research Facility at Eglin AFB summarized by Cheatwood et al.2.
The purpose of this tutorial is to illustrate how to set up the LAVA Cartesian solver with a set of robust options for supersonic flows and to expose users to more detailed inputs of the error metric based AMR capability. This tutorial sets up a wall-modelled large-eddy simulation (WMLES) of Mach 1.44, \(\mathrm{Re}=2.3\times10^6\) flow over a full-scale Genesis aeroshell using the LAVA Cartesian solver (immersed boundary + AMR). These conditions correspond to the average ballistic test conditions, but here the model is simulated at full scale rather than the \(0.047\)-scale wind-tunnel model. The inputs file can be downloaded here and we will describe the components of it in this tutorial.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Cartesian Solver Inputs
Tutorial Files
The inputs and geometry files can be downloaded here and we will describe the components of it in this tutorial.
| File | Description |
|---|---|
| run.inputs | Solver input file |
| run.pbs | PBS job script (NAS A100 GPUs) |
| genesisCapsuleCoarse.fro | Surface representation |
Mesh Setup
The Genesis capsule is simulated with LAVA Cartesian’s immersed-boundary + AMR grid. The surface geometry is loaded in the geometry { ... } block:
scale parameter is used to increase the size of the scale model to match the size of Genesis which was 1.477 m.
The overall domain placement and the finest target spacing are set in the grid { ... } block. This case uses a target finest spacing of finest dx = 0.0036925 corresponding to 400 cells per capsule diameter (minimum recommended free shear layer and wake resolution), and places the farfield boundaries at 50 reference lengths from the origin in each direction (target relative far field distance = [50^3]). Here the exponential 50^3 is a short hand and is expanded to 50,50,50 which is the far field distance in each spatial dimension. The domain is shifted upstream/downstream using domain origin (in meters) and align domain face to origin so that the inflow boundary is upstream of the capsule while leaving a long downstream region for the wake.
grid {
finest dx = 0.0036925
target relative far field distance = [50^3]
domain origin = [-50, 0, 0]
align domain face too rigin = [lo, none, none]
}
Refinement regions (geometry tagging + bow-shock region)
Refinement near the vehicle is prescribed using component tagging, which assigns different target spacings to different parts of the geometry:
component tagging_1 {components = [1-2]; dx_rel = 1.01;type = component }
component tagging_2 {components = [3-5]; dx_rel = 2.01;type = component }
Here, components 1–2 correspond to the heat shield, and components 3–5 correspond to the backside of the vehicle. Maintaining the finest level of refinement over the leading edge of the vehicle is recommended to capture the boundary layer growth over the heat shield.
In addition, we input a cylindrical refinement region that extends in front of and behind the capsule to ensure the development of the bow shock and the aeroshell wake is captured even when the regrid interval is set to a large value to avoid the significant cost of frequent mesh adaption. With a coarse mesh and infrequent regridding, the bow shock could otherwise be severely under-resolved.
AMR
AMR operates on boxes with size specified by the max box size input parameter. Here, we utilize the recommended size, max box size = 8, which specifies that each box will contain \(8^3\) cells.
regrid interval sets how often the mesh will adapt. AMR may be configured to target geometry, a desired yplus value, or solution-based error metrics. Often, a combination of all three is used. To specify solution-based AMR, we must include a solution based amr {} subsection. With method = auto, refinement and coarsening criteria are based on the distribution of the chosen error metric rather than a user-specified threshold, which avoids having to prescribe and tune threshold values. The max cells parameter places an approximate upper bound on the total number of cells (within a small tolerance) so that adaptation does not exceed a desired problem size. Error metrics are specified within the solution based amr {} section through enumerated subsections as follows:
This case uses the small-scale energy error metric adapted to compressible flows from Toosi & Larsson3. The weights for each level are set to a constant value of 1.0, since we are only using one error metric. We expect flow past a blunt object to reach a statistically stationary state, and so we want to ensure the resulting mesh also reaches a stationary state at the same rate. To this effect, the error metric is time-averaged using error metric time method = avg. error metric exponential moving average window ctu sets the window length over which the error metric will be averaged using an exponential filter, and error metric stats interval sets the timestep interval at which the error metric is computed and its time-average updated. We recommend that the error metric be computed and averaged every 10 steps as a good compromise between accuracy and computational cost.
regrid grow error metric tags pads the regions flagged by the error metric before boxes are refined, which helps keep moving features refined between regrid cycles. error metric geom distance scaling ref length scales the error metric down away from the geometry so the bow shock and turbulent wake are not refined all the way to the edge of the computational domain.
max box size = 8
regrid interval = 500
solution based amr
{
method = auto
max cells = 150000000
error metric time method = avg
error metric exponential moving average window ctu = 1.0
error metric stats interval = 10
error metric geom distance scaling ref length = 1.0
error metric threshold ratio = 0.5
regrid grow error metric tags = 1
errormetric_1
{
type = small scale energy
weight = 1.0
}
}
Flow Conditions
The free-stream is specified in the reference conditions block. This case runs Mach 1.44 with a Reynolds number of \(2.3\times 10^6\).
reference conditions {
mach = 1.44
Re = 2.3e6
temperature = 292.81
alpha = 0.
beta = 0.
length = 1.47702127659574E+00
area = 1.71341823346392E+00
dx = 0.007385
}
Solver Settings
Time integration uses an explicit strong-stability-preserving Runge–Kutta scheme (SSPRK53) with CFL-based time stepping; SSPRK53 is stable up to a CFL of about 2.63.
time {
initial cfl = 0.5
cfl = 2.5
compute cfl interval = 10
number of steps = 10000000
finish ctu = 100.
}
solver defaults {
explicit { method = ssprk53 }
}
For the convective discretization, we use the default HWCNS scheme with 4th-order fluxes and 3rd-order interpolation (flux order = 4, interp order = 3) and blend centrally interpolated primitive variables via central components = [q]. Relative to the Cartesian defaults, this case mainly tweaks the shock-capturing pieces by using upwind blending sensors = [ducros] and choosing a more dissipative flux function flux function = laxfried for robustness around shocks and immersed boundaries.
navier stokes { viscous = true }
convective terms
{
scheme = hwcns
flux order = 4
interp order = 3
central components = [q]
upwind blending sensors = [ducros]
limiter = weno3js
flux function = laxfried
}
turbulence { sgs model = vreman }
For turbulence modeling, turbulence { sgs model = vreman } turns on the Vreman subgrid-scale model, which is a single coefficient model.
This case also uses a wall-model boundary condition on the immersed surface components:
wmpartialslip is a wall-model-based partial slip: the wall-function tangential profile is evaluated at the image point and its analytical slope is used to linearly extend the tangential velocity from the image point to the GCM ghost cell, while the wall-normal velocity is treated as in slip (zero through the surface). At low y+ this collapses to no-slip; at high y+ it behaves slip-like, consistent with the chosen wall-function law. wallstressmodel adds modeled wall shear stress and blendedlog selects the blended log-law variant used by the wall model. The shorthand kind = [wallstressmodel, blendedlog] is equivalent — when no velocity kind is specified, wmpartialslip is assumed automatically.
Outputs
The output { ... } block controls what gets written and how often. monitor { ... } prints a set of runtime diagnostics at a fixed timestep interval. It is used to track stability and trends in CFL, Mach, temperature, and force coefficients during the run.
monitor
{
interval = 100
variables = [nt,time,dt,ctu,maxcfl,maxmach,maxtemperature,cl_aeroshell,cs_aeroshell,cd_aeroshell,cmy_aeroshell,blocks_1*,wallt,mups,numcells, elapsed]
}
loads { ... } computes integrated forces and moments on selected surface groups. interval sets the reporting timestep interval and moment center sets the reference point for moments. normalize = true outputs non-dimensional coefficients. gauge = true uses \(p - p_\mathrm{ref}\) for pressure forces.
loads {
interval = 100
moment center = [0, 0, 0]
normalize = true
gauge = true
group_1 { name = aeroshell; include = [1-5] }
group_2 { name = aeroshell_front; include = [1-2] }
group_3 { name = aeroshell_back; include = [3-5] }
}
isosurfaces_* can write either a cut plane or a true iso-surface. A cut plane is defined by point and normal and is colored by the fields of colorfields. A true iso-surface is defined by contour and isovalue and can be colored by another colorfield. format and interval control the file format and dump cadence. Here isosurfaces 1-3 are cut planes and 4 is a true iso surface.
isosurfaces_1{ point = [0^3] ; normal = [0,1,0]; format = vtk; interval = 500; colorfields = [q, density, mach] }
isosurfaces_2{ point = [0^3] ; normal = [0,1,0]; format = vtk; interval = 500; colorfields = [errormetric] }
isosurfaces_3{ point = [0^3] ; normal = [0,1,0]; format = vtk; interval = 500; colorfields = [densitygradmag] }
isosurfaces_4{ contour = qcriterion; isovalue = 1e5; format = vtk; interval = 5000; colorfields = [umag] }
Running on the NAS cluster (PBS)
LAVA has several build variants (depending on solver capabilities and hardware). This tutorial case should be run with the NS1 3D executable. See the installation guide for more details and picking an executable for your hardware.
This case is configured for the NAS GPU partition using 8 A100 nodes via the gpu_normal queue:
#PBS -q gpu_normal
#PBS -l select=8:ncpus=128:ngpus=4:model=mil_a100:mem=500GB,place=scatter:excl
#PBS -l walltime=3:00:00
The example PBS script (run.pbs) included with this tutorial sets up the LAVA environment and launches the NS1 3D Cartesian solver (single-precision floating point) with 4 MPI ranks per node and 32 OpenMP threads per rank:
module purge
module use /swbuild/LAVA/LAVA_modules
module load LAVA
export MPI_USE_CUDA=1
export CUDA_VISIBLE_DEVICES=0,1,2,3
export OMP_PLACES=cores
export OMP_PROC_BIND=true
exec=$(which lavacart.3D.NS1.FLOAT)
mpiexec -N 4 mbind.x -t 32 $exec run.inputs |& tee run.log
Post-Processing
The loads block defines an aeroshell group that includes all surface components (group_1 { name = aeroshell; include = [1-5] }), and with normalize = true the integrated drag on this group is reported as a coefficient cd_aeroshell. This coefficient is written to the monitor file and lets us inspect how the aeroshell drag converges over convective time. After the run, we can use plotHist.py to plot the drag history and its time-averaged value:
plotHist.py -F monitor/Cart.data.iter ctu cd_aeroshell
plotHist.py -F monitor/Cart.data.iter ctu cd_aeroshell -xRange 40 100 -showMean
The first command plots the full drag history versus convective time, while the second zooms in from 40 to 100 CTU and overlays a running mean to highlight the approach to a statistically stationary drag level; in this case the mean drag over that window is approximately \(C_D \approx 1.428\).
Figure: Error metric used for AMR refinement from isosurfaces_2, with AMR boxes overlaid. The large refinement region from tagcylinders_1 is visible, and additional AMR refinement follows the bow shock.
Figure: Schlieren-like visualization using \(|\nabla \rho|\), the magnitude of the density gradient, from isosurfaces_3.
Relevant Publications
-
Desai, P. N., and Lyons, D. T., "Entry, Descent, and Landing Operations Analysis for the Genesis Entry Capsule," Journal of Spacecraft and Rockets, Vol. 45, No. 1, 2008, pp. 27--32. https://doi.org/10.2514/1.30024 ↩
-
Cheatwood, F., Winchenbach, G., Hathaway, W., and Chapman, G., "Dynamic Stability Testing of the Genesis Sample Return Capsule," 38th aerospace sciences meeting and exhibit. https://doi.org/10.2514/6.2000-1009 ↩
-
Toosi, S., and Larsson, J., "Anisotropic Grid-Adaptation in Large Eddy Simulations," Computers & Fluids, Vol. 156, 2017, pp. 146--161. https://doi.org/https://doi.org/10.1016/j.compfluid.2017.07.006 ↩
Multiphase Shock Droplet Interaction
This tutorial introduces the multiphase capability of LAVA via a shock-droplet interaction configuration. The multiphase capability of LAVA Cartesian has been used for many years to simulate the acoustics and pressure loads of space vehicle launch environments relevant to NASA and its partners. For further information on the multiphase solver, please refer to the Cartesian multiphase input documentation.
Prerequisites
Before starting this tutorial, ensure you have:
- LAVA solver installed and accessible — see LAVA Installation Guide
- Basic familiarity with LAVA input file structure — see Cartesian Solver Inputs
- Familiarity with multiphase LAVA input file structure — see Cartesian Multiphase Solver
Tutorial Files
The inputs and geometry files can be downloaded here and we will describe the components of it in this tutorial.
| File | Description |
|---|---|
| run.inputs | Solver input file |
| liq_h2o.spec | Liquid water species file |
| vap_h2o.spec | Water vapor species files |
| air.spec | Air species file |
Initial Condition
The shock-droplet interaction case employs a special routine to set up the initial condition where a planar shock wave with Ma = 1.47 is located just ahead of a spherical droplet with diameter D = 4.8mm. This special initial condition is specified by
Note
exact flow name selects a pre-built initial condition implemented in the solver code (not user-definable from inputs). For the supported ways to prescribe initial conditions, see the Initial Conditions sections in Cartesian Solver Inputs and Cartesian Multiphase Solver.
The figure below shows a slice through \(z = 0\) of the initial condition for this case. Density gradient magnitude is visualized to show the locations of the shock and droplet.
Figure 1: \(z = 0\) slice of initial condition, colored by density gradient magnitude.
Reference Settings
reference conditions
{
# Flow state
velocity = [100.0,0.0,0.0]
pressure = 101325.0
temperature = 298.
massfractions = [0.5, 0.25, 0.25]
multiphaseequilibrium = true
# Geometric and grid parameters
length = 4.8e-3 # Diameter of droplet
dx = 2e-4 # Reference grid spacing, 24 points across droplet diameter
#dx = 1e-4 # Use this if you have enough compute resources, 48 points across droplet diameter
}
shockdropletpaper.
The geometry and grid parameters are important since we want to define our Cartesian grid based on the droplet diameter and a desired grid spacing. The reference grid spacing defined here is a very convenient knob for changing the resolution of the simulation. dx = 2e-4 is currently selected, and is recommended if you are running this tutorial on a workstation. If you have access to server-grade GPUs, you can try dx = 1e-4 to get more a refined solution. This tutorial is designed to take up ~0.5 hour of wall time when running with either (a) dx = 2e-4 on a workstation with 2x RTX4090 GPUs or (b) dx = 1e-4 on a cluster with 8x A100 GPUs.
Fluid Model
The species involved in the multiphase mixture is specified as follows
Here, the species correspond to their respective species .spec files, which must reside in either the common LAVA database or in the current folder. In this simulation, we consider a water droplet in air. We also include phase transition in the analysis, so a vapor species for water is also required.Info
For multiphase simulation, the liquid species must always be the first species. If phase transition is active, then its corresponding vapor must always be the second species.
The navier stokes block in this section controls viscosity and phase transition:
navier stokes
{
viscous = false # viscosity is not implemented for multiphase, so this must be false
phase transition = true # false by default
}
Info
viscosity is not implemented for multiphase
Solver Settings
The key numerics options for this case are:
convective terms
{
scheme = hwcns
central components = [q]
upwind blending sensors = [weno]
limiter = weno3js
flux order = 4
interp order = 3
flux function = hllec
}
scheme = hwcnswithcentral components = [q]: uses a hybrid centered scheme on the full primitive state.limiter = weno3jsandupwind blending sensors = [weno]: blends toward upwind/WENO where needed for stability near strong gradients.flux function = hllec: uses the HLLC-family approximate Riemann solver (hllec) for the face flux.
See the Cartesian multiphase input documentation for more details on these settings.
Mesh Setup
The full grid specification is as follows
grid
{
finest dx_rel = 1 # Relative to dx
targetrelativefarfielddistance = [100^3] # Relative to ref length
max box size = 8
tagboxes_1
{
lo = [-24e-3, -24e-3, -24e-3]
hi = [ 50e-3, 24e-3, 24e-3]
dx_rel = 2
}
tagboxes_2
{
lo = [-12e-3, -12e-3, -12e-3]
hi = [ 40e-3, 12e-3, 12e-3]
dx_rel = 1
}
}
Here, we employ the finest-level-first approach for grid specification.
finest dx_rel = 1specifies that the finest resolution tracks 1 to 1 with the reference dx we set in the reference conditions section.targetrelativefarfielddistance = [100^3]specifies that the domain size is 100 times the reference length (which is the droplet diameter)
Tip
Above we utilize a shorthand commonly used in LAVA inputs files [100^3] which can be used for any array input which expands to [100,100,100]
max box size = 8is the recommended size of a single box in the oct-tree representation of the grid
The main computational region around the droplet is defined by two tag boxes, where we set the lo and hi corners of the tag boxes, along with dx_rel, which is the desired maximum grid sizing allowed in these boxes, compared to the reference dx.
Overall, defining the mesh in this manner allows us to change the overall resolution of the simulation with a single knob -- the reference dx.
Running the Simulation
From the run directory, launch the solver:
Executable Names
The Cartesian solver executable name varies by architecture. See the LAVA Installation Guide for details. Furthermore, the solver configuration 3D.NS3.MP is required for this tutorial. This means we use the 3D multiphase solver for three species.
This example uses 2 MPI ranks with 64 OpenMP threads each (total of 128 cores). The |& tee run.log command saves a copy of the screen output to the run.log file for later reference. Adjust the MPI ranks and thread count based on your available resources.
Outputs
The two main outputs we will look at from this simulation is a cut-plane and an iso-contour of the liquid mass fraction to visualize the topology of the droplet
surface probe_1 {
point = [1e-6,1e-6,1e-6]
normal = [0, 0, 1]
variables = [q,density,mach]
interval = 100
format = vtk
}
# lava 3D: index 5 for liquid mass fraction (q vector is p, u, v, w, T, Y1, Y2, Y3, note that we use 0-index)
isosurfaces_1{
contour = q;
qcompcontouring=5;
isovalue = 0.4;
colorfields = [q, mach, density];
interval = 100;
format=vtk
}
Tip
When specifying a cut plane at exactly a cell boundary, some solution regions maybe missing from the surface probe output. To avoid this bug, the cut point is slightly jiggled away from [0,0,0] into [1e-6,1e-6,1e-6].
Post-Processing
We show visualizations of the solution at the simulation final time at t=0.5 ms for the grid resolution with dx = 1e-4 (see Reference Settings).
The first visualization is the center cut-plane, colored by Mach number. The slow moving heavy liquid fluid can be observed in this view, along with the flow features of a wake region behind the droplet.
Figure 2: \(z = 1e-6\) slice of solution at t=0.5 ms, colored by Mach number.
The second visualization an iso-contour of liquid mass fraction = 0.4, colored by pressure. The deformation and break up of the droplet can be observed in this view.
Figure 3: Iso-contour of liquid mass fraction = 0.4, colored by pressure, at t=0.5 ms.
Contact Us
Contact Us
The LAVA community forum is the best way to contact the LAVA team about an issue.
You can also email urgent or private matters to the lava-contact@nas.nasa.gov mailing list, which redirects to the LAVA development team leads (NASA civil servants).
Please also use this mailing list to direct any inquiries or issues that may involve CUI or ITAR/EAR data.
Warning
Never send classified information to either the community forum or email list!
The forum is ideal for:
- Non-sensitive uncontrolled data (never ITAR, CUI, or classified content)
- LAVA bug reporting and troubleshooting
- Questions about solver setup, input files, and meshing
- Sharing tips, tricks, and best practices
- Announcements and release discussions
The email list is ideal for:
- Sharing issues that can not be reproduced on a non-proprietary geometry
- Communicate directly with LAVA leads about a proprietary or sensitive concern
- Requests for seminars or workshops
- Questions about potential collaboration
LAVA Community Forum
Visit the LAVA Community Forum
The LAVA Community Forum is an independent discussion platform built on Discourse. It is the main channel of communication between users and the LAVA development team and the best place for users to post questions or comments about the code.
Community Operated
This forum is operated by the LAVA community to facilitate communications between users and contributors. It is NOT an official NASA system. Do not post sensitive, export-controlled, proprietary, or restricted information. Moderators reserve the right to delete content or remove access without notice. Any views or opinions expressed on the forum are those of the individual participants and do not represent the positions of NASA.
Why a Community Forum?
We are trying to make things easier by hosting questions and answers in one place where everyone can see them. The intention is to create a knowledge base by accumulating solutions and discussions over time. Furthermore, we will update posts with new answers as the code evolves.
How to Join
The forum uses an invite-only registration process. This is not to exclude anyone — we welcome all LAVA users. The invitation step simply helps us keep the community focused, reduce spam, and ensure that members have an active Software Usage Agreement (SUA) on file.
We have set up a streamlined process to make joining as quick and easy as possible:
-
Step 1 — Request Access
When you visit the community forum for the first time you will be prompted to fill out a short form with your name, organization, and SUA details. It only takes a couple of minutes.
-
Step 2 — Get Approved
Your request is reviewed by an administrator. Most requests are processed within a few business days.
-
Step 3 — Receive Your Invite
Once approved, a Discourse invitation link will be sent directly to your email. Click the link and you're in!
Already have an invitation?
If you already received an invitation email, you can go directly to the forum from that link.
Our Team
LAVA is developed by a team of NASA civil servants and contractors within the Computational Aerosciences Branch at NASA Ames Research Center.
LAVA Leadership
Jared Duensing
LAVA Team Lead
Jeff Housman
Curvilinear Lead
Emre Sozer
Unstructured Lead
Mike Barad
Cartesian Lead
Gerrit-Daniel Stich
Contractor Lead
LAVA Development Team
Alexander Aghili
Josh Anibal
Chase Ashby
Francois Cadieux
Timothy Chau
Chris DeGrendele
Ercan Dumlupinar
Luis Fernandes
James Jensen
James Koch
Brandon Lowe
Nguyen Ly
Olivia Martin
David Craig Penner
Kiran Ravikumar
Bram Rodgers
Victor Sousa

























































































































































































