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.

$> plotHist.py [xvar] [yvar1 yvar2 ...]

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.

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:

$> CGNS_to_LAVA.py <cgns_file> [options]

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 format
• mesh.b2b — block connectivity and transform data in LAVA B2B format
• mesh.x — Plot3D binary grid coordinates (X, Y, Z for each zone)

What the tool extracts:

1. Zone mapping: Builds zone-name to zone-ID mapping
2. Boundary conditions: Reads ZoneBC/PointRange and FamilyName
3. If FamilyName is missing, a default name is generated
4. Connectivity: Reads ZoneGridConnectivity receiver/donor ranges and transform vectors
5. Grid coordinates: Reads CoordinateX/Y/Z under GridCoordinates

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:

$> lava_to_cgns <run_file>

Where:

• run_file: LAVA input/run file containing the curvilinear grid setup (including grid.curv.gridFile and BC/connectivity references)

Output:

• Writes a CGNS file named from the input Plot3D grid file root:
• if grid.curv.gridFile = mygrid.x, output is mygrid.cgns

What the tool does:

1. Initializes MPI and reads options from the provided run file
2. Reads curvilinear grid metadata and BC/connectivity information
3. Loads Plot3D coordinates from grid.curv.gridFile
4. Writes zones, coordinates, BCs, and block connectivity to CGNS

Examples:

$> lava_to_cgns curv_case.inputs

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:

$> cgns_polyformat inputFile.cgns [outputFile.cgns]

Where:

• inputFile.cgns: The input CGNS file with standard mixed elements
• outputFile.cgns: (Optional) The name for the output file. If not provided, the tool will append "_poly" to the input filename

Process:

1. Reads the input CGNS file structure and connectivity
2. Creates a dual graph representation using METIS
3. Identifies cell faces and their connections
4. Preserves all boundary conditions from the original file
5. 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:

$> unst_brick_cgns ni nj nk xmin ymin zmin xdim ydim zdim [perturb_type]

Where:

• ni nj nk: Number of nodes in the x, y, and z directions
• xmin ymin zmin: Minimum coordinates of the brick domain
• xdim ydim zdim: Dimensions of the brick in x, y, and z directions
• perturb_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 nodes
• random: Applies random perturbations to all interior nodes
• random_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:

$> unst_extrude_cgns input_file.txt

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:

1. 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
   

2. stretchtranslate - Extrudes in specified direction with stretching

   method = stretchtranslate
   direction = [1.0, 0.0, 0.0] # Extrusion direction vector
   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
   

3. translate - Extrudes uniform layers in specified direction

   method = translate
   direction = [1.0, 0.0, 0.0] # Extrusion direction vector
   distance = 1.0              # Total extrusion distance
   numberoflayers = 20         # Number of extrusion layers
   

Output Modes:

• merged: Creates a new CGNS file containing both the original grid and the extruded region
• extrusiononly: 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:

$> unst_interpolator  reference_grid reference_restart target_grid target_restart

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_interpolator  input_file

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:

$> unst_mirror_cgns input_file.txt

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 file
• mirror_bc: Boundary condition number to mirror across
• domain_bc: Boundary condition number that will be at the interface between original and mirrored domains
• direction: 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:

1. Reads the input CGNS file
2. Identifies the mirror plane based on the specified boundary
3. Creates a mirrored copy of the grid across this plane
4. Optionally creates periodic connections between the original and mirrored domains
5. Performs a Gauss flux check to validate the resulting mesh
6. 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+:

$> python unst-gridinfo.pyz inputGridFile.cgns

First-run behavior. The first time you run the tool on a given machine, it sets itself up automatically:

1. Creates a private virtual environment at ~/.local/share/unst-gridinfo/venv (override with XDG_DATA_HOME).
2. Installs its small dependency set (h5py, numpy) into that venv.
3. 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:

$> rm -rf ~/.local/share/unst-gridinfo

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:

$> plotLineProbe.py -F probe.line [options]

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 pressure
• uavg, vavg, wavg: Average velocity components
• tavg: Average temperature
• tauwXavg, tauwYavg, tauwZavg: Average wall shear stress components
• cpavg: Average pressure coefficient (computed from pavg)
• cfavg: Average skin friction coefficient (computed from wall shear stress)

Instantaneous Quantities:

• pcoef: Instantaneous pressure coefficient (extracted directly or computed from pressure)
• Cf: Instantaneous skin friction coefficient vector (automatically split into Cfx, 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:

1. Time Extraction: Automatically reads time from CGNS file (TimeIterValues/TimeValues)
2. Plane Rotation: Rotates cutting plane origins and normals to match surface position
3. Coordinate Transform: Transforms intersection coordinates back to fixed reference frame for consistent plotting
4. 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

plane:
  equation: [0, 1, 0, -0.5]  # ax + by + cz + d = 0 (y = 0.5 plane)

Component Specification:

Boundary components can be specified with ranges for convenience:

bc_comps_to_cut: [1, 2, 3-5, 7, 9-12]  # Expands to [1, 2, 3, 4, 5, 7, 9, 10, 11, 12]

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/UnstLatest.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 Cf vector into Cfx, Cfy, Cfz, and Cf_mag components
• Coefficient Calculation: Computes cpavg from pavg and cfavg from 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/C for 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 cut
• surface_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:

$> python tri2stl.py <input.tri> <output.stl>

Where:

• input.tri: Input triangulated mesh file in .tri format
• output.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:

$> stl_converter.<LAVA_POSTFIX> config.yaml

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), or tri (Fortran binary i.tri with record markers)
  • filename: Output file path
• options:
  • weld_tolerance: Vertex welding tolerance. Set to 0 (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 search
  • scale: 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., from tri2stl)
• 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_3 section per component. Includes a component cell-centered field
• VTK: Binary polydata mesh with a component cell 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:

$> compareArray.py <file1> <file2> <icolLo> <icolHi> [eps] [absEps]

Where:

• file1: First input file
• file2: Second input file
• icolLo: 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 > eps and absError > 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 PASS summary and returns exit code 0.
• If any selected column fails:
• writes diff.log containing abs(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:

$> compareHist.py <file> <reference_file> [options]

Required arguments:

• file: History file to test
• reference_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 > relTol and absError > 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 PASS summary and returns exit code 0.
• 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:

$> pltCompare.py [options] <x_var> <y_var> <file1> [file2] [...]
$> pltCompare.py --help

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:**

$> plotSurface.py $> plotSurface.py --help

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:

output/ ├── cpavg/ │ ├── file1_cpavg.png │ ├── file2_cpavg.png │ └── surface_cpavg.mp4 └── cfavg/ ├── file1_cfavg.png └── surface_cfavg.mp4

**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-green
• plasma: Perceptually uniform purple-orange-yellow
• RdBu_r: Red-blue diverging colormap (good for Cp visualization)
• coolwarm: Blue-white-red diverging colormap
• jet: 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:

$> bc2mcr.py <bcfile>

Where:

• bcfile: Boundary-condition file containing entries in the format: name gridNum jMin jMax kMin kMax lMin lMax

What the tool does:

1. Reads each BC record from bcfile (ignoring blank lines and lines starting with !)
2. Determines which zone face(s) each BC corresponds to (low/high in J, K, or L directions)
3. Merges opposite faces into a combined "both" direction when applicable
4. Generates <bcfile>.mcr that:
5. renames each Tecplot zone using BC names found for that zone
6. sets I/J/K surface ranges and SurfacesToPlot to 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:

1. In ParaView, go to Tools → Manage Plugins
2. Click Load New… and select LAVAParaviewPlugin.py
3. To load it automatically on startup, expand the plugin entry and check Auto Load

Applying a filter:

1. Select your dataset in the Pipeline Browser
2. Go to Filters → Search (or Filters → Alphabetical) and search for Process Cart Mask or Process Unst Mask
3. In the Properties panel, use the BitwiseValue dropdown to select the mask flag to extract
4. Click Apply — the selected flag is added as a new cell data array visible in the display and color-by menus
5. 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:

1. With the mask filter selected in the Pipeline Browser, go to Filters → Common → Threshold (or search for Threshold)
2. Set the Scalars dropdown to the extracted array (e.g. PROBLEM_SIZE, PROBLEM_GG, PROBLEM_GRAD)
3. Set the threshold range to [1, 1] to select only cells where that bit is set
4. 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.