AirSketcher Manual

Understanding the Solver Phases

AirSketcher uses a hybrid approach, automatically transitioning between two distinct simulation phases. Understanding these phases will help you know exactly when to record your data and when to stop the simulation.

Phase 1: Pseudo-Transient (Mean Flow & Force Stabilization) When you first click Run, the solver focuses on quickly establishing the basic, stable flow field around your obstacles. During this phase, it applies numerical techniques to force the mass flow to balance and the overall pressure field to settle.

Phase 2: Full Transient (Wake Phase & Vortex Shedding)

Once the mean flow achieves stability, the solver automatically disables its artificial stabilization controls—specifically the mass flow “outlet servo” and momentum correction. It turns these off because artificial constraints suppress natural fluid motion. Instead, it activates the “Wake Phase” and introduces slight physical perturbations into the flow. This allows natural, time-dependent fluid phenomena—like the von Kármán vortex street—to develop behind your objects.

Monitoring Convergence & UI Indicators

Watch the Residuals panel in the plot window. It shows how stable and balanced the numerical solution is while the simulation is running. The colored LED dots give a quick health check of the flow calculation.

What are residuals?
A residual is a measure of how much the solution is still changing from one solver iteration to the next.

In simple terms:
large residual = the flow field is still changing
small residual = the flow field is becoming stable

AirSketcher tracks residuals for the main solved fields: horizontal velocity, vertical velocity, and pressure.

Residuals do not directly mean “percent error compared with reality.” Instead, they show whether the CFD equations are settling into a consistent solution. A simulation can start with high residuals because the solver is still building the flow field from the initial condition. As the flow stabilizes, residuals should generally decrease.

When to Record Aerodynamic Data (Cd & Cl)

If your primary goal is to find the Drag (Cd) and Lift (Cl) coefficients of your design, you should pay attention to Phase 1.

1. Wait for the “Converged” Message: When residuals drop and mass balance is achieved, AirSketcher will notify you that the flow field has converged.
2. Wait for the “ΔCd Stabilised” Pop-up: As the simulation continues, the solver continuously monitors the change in your drag coefficient. Once |ΔCd| stays below 0.05% for several consecutive checks, a message will pop up saying: “ΔCd has gradually reached ~0%. Aerodynamic forces appear stable.”
3. Record Your Data: This is the optimal time to record your Cd and Cl values. Once the simulation enters the Wake Phase (Phase 2), these values will naturally begin to oscillate as vortices shed off the back of your object.

When to Stop the Simulation

• To get aerodynamic data: You can safely click Stop right after you record your Cd and Cl values from the “ΔCd Stabilised” prompt.
• To observe wake behavior: If you want to see how the air tumbles and sheds behind your object, leave the simulation running. Once you see the “🌪️ WAKE ENABLED” toast notification, the solver is actively cultivating the wake. Allow it to run for a while longer to watch the beautiful, dynamic vortex shedding develop in the visualizer. Stop it whenever you are satisfied with the visual results.

Sketch & Tools

From top to bottom:

• Undo: Reverse or reapply your latest actions.
  
• Draw: Create geometry using freehand or brushes.
  
• Draw Line: Click to draw straight lines.
  
• Draw Rectangle: Draw rectangle shapes.
  
• Eraser: Remove selected geometry.
  
• Eraser All: Remove all geometry on the canvas.

Image Tools

Bottom Three Icons:

• Image Processor: Launch the Image Processor and Windrose Locator module.
  
• Import Processed Image: Load the processed image from the Image Processor back onto the canvas.
  
• Save Processed Image: Save the currently drawn domain/obstacles as a temporary file named saved_drawing.pkl (used for restarting or post-processing).

Slip Wall / Symmetry Boundary means:

• No flow through the wall: Perpendicular velocity is zero (v = 0).
• Frictionless sliding: No shear stress along the wall (zero gradient of parallel velocity and pressure).

Use this for testing designs in confined, wind tunnel-like conditions where flow cannot expand vertically.

Wind Tunnel Mode (ON)
┌────────────────────────────┐
│       Slip Wall (Top)      │
│  → → → → → → → → → → →     │
│  → → → → → → → → → → →     │   Flow direction →
│  → → → → → → → → → → →     │
│     Slip Wall (Bottom)     │
└────────────────────────────┘

When Wind Tunnel Mode is OFF: Open Boundary

If Wind Tunnel Mode is disabled, the top and bottom boundaries apply freestream (open) conditions instead.

• Flow can expand: Perpendicular velocity is allowed to float (zero-gradient), relieving domain blockage.
• Anchored to environment: Parallel velocity is anchored to the ambient freestream velocity, and pressure is set to zero (ambient atmospheric gauge pressure).

This is ideal for simulating open-air scenarios, like outdoor aerodynamics or buildings, where the air can freely displace around an object.

Open / Freestream Boundary (OFF)
┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
     ↑↑↑ Flow can expand ↑↑↑
  → → → → → → → → → → → → → → →
  → → → → → → → → → → → → → → →
     ↓↓↓ Flow can expand ↓↓↓
┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈

Velocity Profile Formula

The wind speed follows a power law:
$u(y) = U_{\text{ref}}\left(\dfrac{y}{H}\right)^{\alpha}$

Where - $u(y)$: velocity at height $y$
- $U_{\text{ref}}$: reference velocity at height $H$
- $H$: reference height (often the inlet top)
- $\alpha$: shear exponent (controls profile steepness)

ABL Profile (ASCII-safe for Zettlr)

U(y)
|               o  <- U_ref
|               o
|              o
|             o
|           o
|          o
|        o
|      o
|   o
+-------------------------------------- y
0                                      H

Higher $\alpha$ values produce stronger shear near the ground (steeper gradient at small $y$).

Typical $\alpha$ by Terrain

When to Use an ABL Inlet

⚠️ This setup is intended exclusively for 2D side-view simulations!

• Wind over buildings, hills, or terrain
  
• Urban wind comfort / natural ventilation studies

UI Controls (Expert Options ▶ Simulation Tools)

• AMR Enabled: The master toggle for adaptive meshing (enabled by default).

How it works

• ROI-driven refinement: A Region of Interest (ROI) is detected around geometry/flow features (obstacles, porous polygons, and blower zones are treated as fluid so the ROI grows around them).
• Fine inside, coarse outside: Inside the ROI, we keep every row/column; outside, four log-spaced strips (bottom/top/left/right) place cells dense near the ROI and stretched toward the domain edges using smooth exponential spacing.
• Edges preserved: The first/last rows and columns of the full domain are always included.
• Auto coarsening guard: A coarsening “factor” is auto-selected from a small set so at least ~5% of cells remain outside the ROI in both directions. If none fits, AMR is disabled with a warning.

What gets remapped

• All flow fields (velocity, pressure, turbulence)
• Obstacles, porosity, and blower forcing
• The computational grid
• A one-time snapshot of the original full-resolution grid (for easy revert or post-processing)

When it runs / skips

• Controlled by the AMR Enabled UI checkbox in the Expert Options.
• Skips if:
  • AMR is disabled
  • no ROI is found
  • no suitable factor is found
  • memory error occurs

Stability tips (pseudo-transient)

• AMR can increase local CFL numbers away from the ROI. If using aggressive time stepping, enable the soft convective limiter (automatically tighter with AMR) and/or the velocity-based convective cap.
• These small guards usually prevent cases that are stable without AMR from diverging with it.

After enabling

• The simulation grid is updated to the adaptive resolution.
• The view refreshes immediately (AMR grid indicator + streamline preview).

Note: AMR is not turned off by porous/blower zones; instead, they are included in the ROI so refinement accurately captures their effects.

Draft Mode (Coarse) / Concept AMR

Draft Mode (labeled in the UI as ↳ Draft Mode (Coarse)) is a fast-pass, low-resolution sub-feature of Adaptive Mesh Refinement. When a quick “concept” or draft of the flow is needed without waiting for a highly accurate calculation, this mode is ideal for rapid prototyping.

Key Behaviors

• Reduces Resolution: It significantly drops the global resolution parameter to speed up the engine.
• Speeds up Simulation: Because the grid is substantially coarser, the math engine has far fewer cells to calculate, delivering much faster visual feedback.
• Dependency: It strictly relies on the master AMR Enabled toggle being active. If standard AMR is turned off, this concept/draft mode is automatically disabled and locked to prevent conflicts.

Reynolds number ($Re$) is approximated by:

$$Re = \frac{\rho \cdot U \cdot L}{\mu}$$ where: - $\rho$ = air density
- $U$ = wind speed
- $L$ = characteristic length (e.g., building width, car length)
- $\mu$ = air viscosity

When Should You Use This?

Only use Scale Input Wind Speed when your geometry is a scaled-down physical model (wind-tunnel model, miniature, or blueprint at reduced scale).

Example:
You are simulating a 1:50 scale car from a wind-tunnel test. Draw the car length on screen, enter the real car’s length + real wind speed (or target Re), and the tool instantly sets the correct simulation inlet speed so the flow behaves exactly like the full-size vehicle.

This is essential because flow patterns (laminar vs turbulent, separation, drag) depend on the Reynolds number. Without scaling, a small model at full speed produces completely wrong results.

When You Don’t Need It

If your geometry is already modeled at true 1:1 real-world size, skip this tool completely.
Just type the actual wind speed directly into the inlet field.
Using scaling on a 1:1 model would give incorrect (too low) velocities.

How to Use (Interactive Tool)

1. Click the Scale Input Wind Speed button.
2. Click once on the canvas to start a measurement line, then click again to finish it (any direction — length is measured correctly).
3. The tool automatically detects the drawn length in simulation units.
4. A clean dialog appears — fill in:
   • Real Characteristic Length (m) — e.g., actual building height or car length in real life.
   • Choose one of two modes:
     • Target Wind Speed (m/s) → enter the real-world wind speed
       
     • Target Reynolds Number (Re) → enter the desired Re (recommended for wind-tunnel validation)
5. Click OK — the inlet velocity is instantly calculated and filled into the speed field (automatically capped at 500 m/s for numerical stability).

The tool handles everything for you — no manual math required.

Summary

• ✅ Use this for any scaled model (wind-tunnel, miniatures, blueprints)
  
• ❌ Skip this for full 1:1 real-world geometry
  
• One-click line measurement + smart dialog = perfect Re matching in seconds

Now your scaled simulations will match real-world physics automatically!

Opening the Zone Editor

Open the Porous and Blower Zone tool from the ‘Expert Options’ menu.

The editor contains:

• A large polygon-drawing area
• A 2-D plan view simulation checkbox
• Draw new zone
• Edit zone values
• Undo last zone
• Clear all zones

To draw a zone:

1. Click Draw new zone.
2. Click around the required boundary.
3. Click the first point again to close the polygon.
4. Select the required zone type:
   • % for direct porosity
   • Tree symbol for LAI
   • Blower symbol for directed air injection
5. Enter the required zone properties.
6. Click Apply.

Press Esc to cancel an unfinished polygon.

Porous Zones

Porous zones represent regions that allow air to pass through while reducing its momentum.

Typical applications include:

• Trees and vegetation
• Hedges
• Porous fences
• Screens
• Perforated barriers
• Semi-open architectural elements
• Simplified porous media

A porous zone can be defined using either:

• Porosity (%)
• Leaf Area Index (LAI)

The selected value is assigned to every grid cell inside the polygon.

Direct Porosity Input

Porosity can be entered from 0% to 100%.

• 100% porosity represents an open region with no porous blockage.
• Lower values represent progressively stronger airflow resistance.
• Values approaching 0% represent a nearly impermeable zone.

The fractional porosity is:

$$\phi = \frac{\text{Porosity (\%)}}{100}$$

where $0\le\phi\le1$.

The editor stores the porous-zone value as a percentage. The zone label displays its porosity and an equivalent LAI value.

LAI Input

Leaf Area Index (LAI) represents the one-sided leaf area per unit ground area.

Higher LAI values generally represent denser vegetation and stronger airflow resistance.

The LAI entry must be zero or positive.

The editor converts LAI to equivalent porosity using:

$$\text{Porosity (\%)} = 100e^{-0.5\,\mathrm{LAI}}$$ or, in fractional form: $$\phi = e^{-0.5\,\mathrm{LAI}}$$ The equivalent LAI can be recovered from a non-zero porosity using: $$\mathrm{LAI} = -2\ln(\phi)$$

This allows zones entered using direct porosity and zones entered using LAI to use a common stored porosity representation.

Plan View and Section View

The 2-D plan view simulation checkbox controls how vegetation drag is interpreted by the solver.

Typical Tree LAI Ranges

The LAI dialog contains a scrollable reference list of typical vegetation ranges.

These values are general guidance only. Actual LAI varies with species, age, season, climate, pruning, irrigation, planting density, and measurement method.

Use measured or site-specific LAI data whenever available.

Blower Zones

Blower zones represent regions that add directed airflow to the simulation.

Typical applications include:

• Mechanical fans
• Supply-air diffusers
• Ventilation ducts
• Jet outlets
• Exhaust or supply openings
• Local air-moving equipment

Each blower zone requires:

• Direction angle
• Speed in m/s

The blower speed must be greater than zero.

Blower Direction

The blower-direction dial uses the following orientation:

The angle can be selected by:

• Clicking the circular direction dial
• Dragging the dial arm
• Using the four direction presets
• Using the keyboard arrow keys while the dial is focused
• Holding Shift while using the arrow keys for larger angular changes

Angles are stored in the range:

$$0^\circ\le\theta<360^\circ$$

Blower Velocity Components

For a specified blower speed $V$ and direction $\theta$, the velocity components are:

$$u_b = V\cos\theta$$

$$v_b = V\sin\theta$$

where:

• $V$ is the blower speed in $\mathrm{m/s}$
• $\theta$ is the blower direction measured from the positive horizontal axis
• $u_b$ is the horizontal velocity component
• $v_b$ is the vertical velocity component

Every grid cell inside the blower polygon is assigned to that blower zone.

The editor stores:

• The grid cells inside the polygon
• The blower angle
• The blower speed

The blower zone is displayed with its zone number, angle, and speed.

Coordinate convention
An angle of $0^\circ$ points to the right and an angle of $90^\circ$ points upward in the displayed CFD domain.

Blower Cross-Section

The volume-balance calculation does not use the complete polygon area as the blower opening.

Instead, it calculates the polygon width perpendicular to the blower direction.

For blower $i$, the perpendicular unit vector is:

$$\hat{\mathbf{n}}_{\perp,i} = \begin{bmatrix} -\sin\theta_i\\ \cos\theta_i \end{bmatrix}$$ Each blower-cell position is projected onto this direction: $$s = x\left(-\sin\theta_i\right) + y\cos\theta_i$$ The blower cross-sectional width is estimated from: $$W_{\perp,i} = s_{\max}-s_{\min}$$ One grid-resolution allowance is added in the perpendicular direction so that very thin blower polygons still have a finite effective width: $$W_{\mathrm{eff},i} = \max \left( W_{\perp,i}+\Delta n_i, \Delta n_i \right)$$ where: $$\Delta n_i = \sqrt{ \left(-\sin\theta_i\,\Delta x\right)^2 + \left(\cos\theta_i\,\Delta y\right)^2 }$$

This produces a more appropriate flow estimate than multiplying blower speed by the full polygon area.

Blower Flow Estimate

For a two-dimensional simulation with a unit out-of-plane depth, the estimated volume flow from blower $i$ is:

$$Q_i = V_i W_{\mathrm{eff},i}(1\ \mathrm{m})$$ The total blower flow is: $$Q_{\mathrm{blower,total}} = \sum_i Q_i$$

where:

• $V_i$ is the speed of blower $i$
• $W_{\mathrm{eff},i}$ is its effective cross-sectional width
• Unit depth is assumed outside the two-dimensional plane

The resulting flow is reported in $\mathrm{m^3/s}$ per assumed one-metre depth.

Open Inlet Area

The volume-balance tool examines the leftmost boundary of the domain and identifies the inlet cells that are open fluid.

The open inlet height is calculated from the local vertical grid spacing:

$$H_{\mathrm{inlet,open}} = \sum_{j\in\mathrm{open}}\Delta y_j$$ Assuming a unit out-of-plane depth: $$A_{\mathrm{inlet}} = H_{\mathrm{inlet,open}}(1\ \mathrm{m})$$

This means solid portions of the left boundary are excluded from the available inlet area.

If the open boundary cannot be determined, the calculation falls back to the full domain height.

Suggested Inlet Velocity

The editor calculates a suggested inlet velocity using:

$$U_{\mathrm{inlet,suggested}} = \frac{ 3Q_{\mathrm{blower,total}} }{ A_{\mathrm{inlet}} }$$

where:

• $Q_{\mathrm{blower,total}}$ is the estimated combined blower flow
• $A_{\mathrm{inlet}}$ is the open inlet area
• The factor of $3$ is the application’s built-in recommendation multiplier

The editor reports:

• Total estimated blower flow
• Open inlet height
• Open inlet area
• Suggested left-boundary inlet velocity

The calculated value is printed in the console and, when the inlet-speed field is available, inserted into that field automatically.

Important
The suggested inlet velocity is a setup aid. It is not a general conservation law and should not replace checking mass balance, boundary conditions, or solver convergence.

Review the recommendation whenever blower zones are added, removed, resized, rotated, or assigned a different speed.

Editing and Removing Zones

The editor provides the following zone-management controls:

• Edit zone values — opens the zone-value editor
• Undo last zone — removes the most recently added porous or blower zone
• Clear all zones — removes all defined zones
• Esc — cancels the currently active polygon drawing

Zones are tracked in creation order, allowing the most recently created zone to be removed reliably.

Zone Labels

Porous-zone labels display:

• Zone number
• Porosity percentage
• Equivalent LAI

Blower-zone labels display:

• Blower-zone number
• Direction angle
• Speed in $\mathrm{m/s}$

These labels are visual aids and do not create additional solver regions.

Recommended Workflow

1. Open the Porous and Blower Zone editor.
2. Select whether the model represents a plan view or vertical section.
3. Draw porous vegetation, fences, or screens.
4. Enter direct porosity or LAI.
5. Draw any blower regions.
6. Set each blower’s direction and speed.
7. Review the zone labels.
8. Review the suggested inlet velocity.
9. Edit or undo zones if required.
10. Run the CFD simulation.
11. Check velocity contours, pressure contours, flow balance, and convergence.
12. Adjust zone values if the resulting flow resistance or air injection is unrealistic.

Modeling Guidance

• Use direct porosity for screens, fences, and simplified porous materials.
• Use LAI for vegetation when suitable LAI information is available.
• Select plan view for site layouts and section view for vertical canopy cross-sections.
• Avoid drawing extremely thin polygons that contain too few grid cells.
• Refine the mesh around small porous or blower zones.
• Use measured fan discharge velocity when available.
• Check that the blower direction matches the intended physical flow direction.
• Treat the suggested inlet velocity as a recommendation, not an automatic guarantee of flow balance.
• Verify that the solution remains stable after adding strong blower zones or very low-porosity regions.
• Use site-specific vegetation and equipment data whenever possible.

Drawing-tool behavior

• Select — select, move, scale, or rotate the loaded image.
• Pencil — draw freehand geometry.
• Line — draw a straight segment.
• Arrow — draw a directional arrow.
• Rectangle — draw a rectangular boundary.
• Ellipse — draw an ellipse or circular boundary.
• Erase Edge — paint through imported or detected image edges.
• Erase Draw — remove geometry that was added with the drawing tools without changing the loaded image.

Hold Shift while using Line or Arrow to snap the direction horizontally, vertically, or diagonally.

All drawing and edge-erasing edits remain attached to the image when it is moved, scaled, or rotated. Visible edits are included in the simulation export.

Entering coordinates

Enter coordinates as:

latitude, longitude

Example:

40.7128, -74.0060

You can use normal Ctrl+V paste. On supported Windows systems, right-clicking the coordinate field also inserts the current plain-text clipboard value directly.

Click Fetch Windrose to begin retrieval.

The software:

1. searches nearby weather stations;
2. checks the closest stations until a usable wind-data file is found;
3. extracts valid wind direction and speed records;
4. generates a Wind Rose;
5. retrieves map tiles centered on the entered location;
6. overlays the Wind Rose on the map;
7. reports the selected station name and its approximate distance from the requested coordinates.

An Internet connection is required for remote wind data and map tiles.

Recommended alignment workflow

1. Load the geometry image.
2. Fetch the Wind Rose for the required coordinates.
3. Rotate the floorplan overlay on the Wind Rose until it matches the intended real-world site orientation.
4. Select the required wind direction using either:
   • a compass button around the Wind Rose; or
   • the scrollable wind-direction wheel on the left.
5. Confirm the resulting orientation on the main geometry canvas.
6. Export the geometry.

The wheel and the compass buttons remain synchronized.

When a direction is selected:

• the selected direction means wind coming from that compass sector;
• the Wind Rose overlay preserves the chosen real-world site orientation;
• the main-canvas geometry rotates automatically so that the chosen wind direction is represented by the fixed left-to-right CFD inlet.

For example, selecting SE means wind coming from the southeast. The solver inlet still remains on the left; the main-canvas geometry is rotated to reproduce the equivalent exposure.

The neutral default is W, because wind coming from the west already corresponds to flow entering from the left and moving toward the right.

Features

• Colormap Customization
  Input your own min/max values to stretch or compress the contour color scale. This is especially useful when:

  • Focusing on low-velocity boundary layers
  • Comparing different cases side-by-side

• Interactive Hover Tooltips
  Hover anywhere on the plot to view:

  Vmag:  Velocity Magnitude (m/s)
   Vx:    Horizontal Component (m/s)
   Vy:    Vertical Component (m/s)
   P:     Static Pressure (Pa)

• Line Probe Tool
  Draw custom line probes to sample flow data across any two points. You’ll get:

  • Velocity & pressure plots
  • Vx/Vy component plots
  • Mass flow per segment
  • Exportable data tables

Usage Tips

• Use “Apply” to rescale the color range.
• Use “Streamlines”, “Particle Tracking”, or “Qi Flow” to explore complementary visualizations.
• Use “Report” to get an instant summary of your current simulation results.

📌 Notes

• Velocity in enclosed regions is automatically masked to avoid misleading visuals.
• Results are interpolated back onto the original grid, ensuring visual consistency.
• Watermark adapts brightness automatically for visibility across any background.

When to Use Streamlines

• Understand overall flow patterns and recirculation zones
  
• Visualize how wind moves around buildings, terrain, or objects
  
• Extract precise velocity profiles along any line (great for validation or reporting)
  
• Compare flow behavior with/without AMR or different inlet conditions

How to Open

Click the Streamlines button in the Results panel (or use the toolbar icon).
A new window appears with a large, publication-ready visualization.

Main Visual Features

• Streamlines automatically colored by local velocity (m/s) using a beautiful aero/journal colormap
  
• Optional velocity vectors (arrows)
  
• Dark or Light theme (toggle anytime)
  
• Background mist effect for depth (in dark mode)
  
• Full Matplotlib toolbar (zoom, pan, save as PNG/PDF, etc.)

Controls (bottom bar)

• Density slider — controls how many streamlines are drawn (0.5 = sparse, 3.0 = very dense)
  
• Vector Length slider — scales arrow size when vectors are enabled
  
• Show/Hide Vectors — toggle velocity arrows on/off
  
• Switch Theme — Dark ↔︎ Light (journal quality)
  
• ⌖ Line Probe — activates the powerful profiling tool
  
• ✖ Clear All — removes probe lines and tooltips

Line Probe Tool (real time)

1. Click ⌖ Line Probe (button turns yellow).
   
2. Click and drag anywhere on the streamline map to draw a measurement line.
   
3. Release the mouse — a graph instantly appears showing:
   • |V| (velocity magnitude) — thick black line
     
   • u (horizontal) — red dashed
     
   • v (vertical) — blue dashed

Graph information displayed: - Total line length (m)
- Average velocity along the line
- Flux integral ∫|V|·ds (m²/s)

Fitted Equations (shown below the graph): - Automatic polynomial curve fitting with R² values
- Equations can be copied with right-click → Copy

Extra actions in probe window: - Export CSV — saves distance, u, v, |V| data
- Copy Graph — copies the plot image to clipboard (ready for reports)

Right-click anywhere on the main streamline map to clear all tooltips instantly.

Tip: Use the Line Probe on critical sections (e.g., above a roof, through a gap between buildings, or along a pedestrian path) to get exact numbers for your analysis or validation.

This tool turns raw simulation data into clear, presentation-ready flow insights in seconds.

Available Pressure Fields

The visualization can display three pressure quantities:

• Static Pressure Difference

$$\Delta p=p-p_\infty$$

• Dynamic Pressure

$$p_{\mathrm{dyn}} = \frac{1}{2}\rho\left(u^2+v^2\right)$$ - Total Pressure $$p_{\mathrm{total}} = \Delta p+p_{\mathrm{dyn}}$$

where:

• $p$ is the local static pressure
• $p_\infty$ is the upstream reference pressure
• $p_{\mathrm{dyn}}$ is the local dynamic pressure
• $p_{\mathrm{total}}$ is the displayed total pressure
• $\rho$ is the fluid density
• $u$ and $v$ are the local velocity components

The upstream reference pressure is calculated from the median pressure in a central fluid region near the inlet. Solid cells and invalid regions are excluded from this calculation.

Key Features

• Static, Dynamic, and Total Pressure Modes
  Radio buttons allow switching between static pressure difference, dynamic pressure, and total pressure.

• Pressure Contours
  High-resolution colour shading displays the selected pressure field. Static and total pressure use a diverging scale centred on zero, while dynamic pressure uses a non-negative scale.

• Optional Isolines
  Black isolines can be shown over the coloured pressure field. Isolines are enabled by default.

• Contour Detail Control
  The contour-density slider provides a range of 5–250 levels. Use fewer levels for a clean overview or more levels for detailed pressure-gradient inspection.

• Value Tooltips
  Left-click a valid fluid location to display the local value of the currently selected pressure field. Multiple tooltips may be placed on the plot. Right-click clears all tooltips.

• Porous and Blower Zones
  Porous and blower regions are displayed when the corresponding overlay functionality is available.

• Line Probe
  Draw a line through the pressure field to inspect the pressure profile and calculate a raw two-dimensional pressure-force estimate normal to the selected line.

• Box Probe
  Draw a rectangular probe to inspect pressure around its complete perimeter and calculate raw front, back, upper, and lower pressure contributions.

How to Open and Use

Click the Pressure Contours button in the Results panel.

A large pressure-analysis window opens with the contour plot on the left and the analysis controls on the right.

Available controls:

• Contour Levels slider
• Show Geometry checkbox
• Show Isolines checkbox
• Static Pressure radio button
• Dynamic Pressure radio button
• Total Pressure radio button
• ⌖ Line Probe button
• ⬜ Box Probe button
• Live Aero Data panel
• Manual drag-calibration controls

Line Probe Tool

1. Click ⌖ Line Probe.
2. The button changes to ⌖ Exit Line Probe.
3. Click and drag a line across the pressure field.
4. Release the mouse button.
5. The probe-results window updates automatically.

The Line Probe window shows:

• Pressure or selected-field value along the line
• Distance measured from the start of the line
• Filled positive and negative pressure areas
• Total line length
• Average absolute pressure value
• Integrated scalar pressure for each valid line segment
• Raw two-dimensional $F_x$ and $F_y$ estimates
• Resultant force direction
• Hover tooltips showing distance and pressure
• Save Full Window button
• Copy Image button

The force estimate is calculated from:

$$I_p=\int_{\mathrm{line}}p(s)\,\mathrm{d}s$$

The integrated value is resolved normal to the selected line:

$$F_x=I_p n_x$$

$$F_y=I_p n_y$$

where $\hat{\mathbf{n}}=(n_x,n_y)$ is the unit normal to the probe line.

Important
The Line Probe reports a raw two-dimensional diagnostic result. It is not the same as the automatically calculated aerodynamic force around a complete obstacle boundary.

The Line Probe is useful for examining pressure across a wake, narrow gap, roofline, jet, channel, or selected structural section.

Box Probe Tool

1. Click ⬜ Box Probe.
2. Click and drag a rectangular region over the pressure field.
3. Release the mouse button.
4. The probe window displays the pressure around the unwrapped box perimeter.

The perimeter starts at the top-left corner and proceeds counter-clockwise through:

• Left or front face
• Bottom face
• Right or back face
• Top face

The Box Probe reports:

• Pressure around the complete box perimeter
• Front-face pressure contribution
• Back-face pressure contribution
• Lower-face pressure contribution
• Upper-face pressure contribution
• Raw two-dimensional drag estimate
• Raw two-dimensional lift estimate

The approximate box-force balance is:

$$F_x=F_{\mathrm{left}}-F_{\mathrm{right}}$$

$$F_y=F_{\mathrm{bottom}}-F_{\mathrm{top}}$$

The Box Probe is intended as a local momentum-balance diagnostic. Its raw results do not include the aerodynamic corrections or coefficient processing used by the Aero Data panel.

Probe Position Adjustment

After drawing a Line Probe or Box Probe, use the keyboard arrow keys to move the complete probe in small increments:

• Up Arrow: move upward
• Down Arrow: move downward
• Left Arrow: move left
• Right Arrow: move right

This allows precise positioning without redrawing the probe.

Automatic Aerodynamic Analysis

The software detects the largest suitable obstacle contour near the main simulation region and estimates aerodynamic loading from its surface-pressure distribution.

For closed bodies, outward normals are determined from the contour winding direction. For open or boundary-touching bodies, the software samples both sides of each segment to identify the fluid-facing normal.

Pressure is sampled a short distance outside the solid boundary using the original pressure field. A mild along-surface filter reduces grid-scale interpolation noise without clipping pressure coefficients.

The surface-relative pressure is:

$$\Delta p_s=p_s-p_\infty$$

where:

• $p_s$ is the sampled surface pressure
• $p_\infty$ is the median upstream reference pressure

The pressure-force contribution from each boundary segment is:

$$\mathrm{d}\mathbf{F}=-\Delta p_s\,\hat{\mathbf{n}}\,\mathrm{d}s$$

The total pressure force per unit span is:

$$\mathbf{F}_p = \oint_{\partial\Omega} -\Delta p_s\,\hat{\mathbf{n}}\,\mathrm{d}s$$

where:

• $\hat{\mathbf{n}}$ is the outward body-normal vector
• $ds$ is the boundary-segment length
• $\partial\Omega$ is the detected obstacle boundary

Because the simulation is two-dimensional, force is reported per unit depth with units of N/m.

Pressure-only integration
Directly integrated forces include pressure loading but do not include viscous wall-shear stress.

Closed and Open Contours

A small contour gap—such as the finite trailing-edge gap of an airfoil—may be closed automatically when its endpoints are separated by only a few grid cells.

A large opening, such as the lower boundary of a ground-contacting vehicle, remains open. In this situation:

• Pressure drag can still be estimated from the exposed surface.
• Lift is reported as N/A unless the wetted contour is closed and at least 95% of the surface has valid pressure samples.

This prevents incomplete lower-surface data from producing a misleading lift coefficient.

Freestream Reference Values

The freestream pressure and velocity are measured from valid fluid cells in the central inlet region.

By default, the software prefers the measured inlet speed. If a reliable measured value is unavailable, it uses the configured inlet velocity as a fallback.

The freestream dynamic pressure is:

$$p_{\mathrm{dyn},\infty} = \frac{1}{2}\rho U_\infty^2$$

where:

• $p_{\mathrm{dyn},\infty}$ is the freestream dynamic pressure
• $\rho$ is the fluid density
• $U_\infty$ is the measured or configured freestream velocity

The Aero Data panel identifies whether $U_\infty$ came from the measured inlet, configured inlet, or fallback value.

Automatic Pressure-Scale Check

For bluff bodies, the software compares the pressure rise near the forward stagnation region with the velocity-based dynamic pressure.

At a stagnation point:

$$p_{\mathrm{stag}}-p_\infty \approx p_{\mathrm{dyn},\infty}$$

If the pressure and velocity scales differ substantially, the integrated bluff-body force can be automatically rescaled. Small differences are ignored because grid interpolation and stagnation-point sampling do not produce exact equality.

This automatic scaling is not applied to airfoil cases handled by the optional airfoil polar model.

Wind-Tunnel Blockage Correction

When Wind Tunnel Mode is active, the software can apply a blockage correction based on:

$$B=\frac{H}{L_y}$$

where:

• $H$ is the projected body height
• $L_y$ is the domain height
• $B$ is the blockage ratio

The implemented correction uses solid and wake contributions:

$$\epsilon_{\mathrm{solid}}=\frac{1}{2}B^2$$

$$\epsilon_{\mathrm{wake}} = \frac{1}{4}\max(C_D,0)B$$

$$K_B = \frac{1} {\left(1+\epsilon_{\mathrm{solid}}+\epsilon_{\mathrm{wake}}\right)^2}$$

The correction factor is limited to a minimum value of $0.4$.

Use Wind Tunnel Mode only when the simulation represents a confined test section. Do not apply blockage correction to an open outdoor-flow domain.

Airfoil Detection and Angle of Attack

The software estimates the principal geometry axis and uses it as the chord direction. A closed body with a sufficiently small thickness-to-chord ratio is classified as an airfoil.

For detected airfoils:

• The chord direction is calculated from the principal geometry axis.
• Angle of attack is determined from the detected geometry.
• A clockwise nose-up orientation is positive by default.
• A GUI angle-of-attack override is used only when explicitly enabled.
• Bluff bodies and geometries without a reliable chord direction report angle of attack as N/A.

Aerodynamic Coefficients

The software reports coefficients using both projected height and chord length.

Reynolds Number

The software calculates:

$$Re_H=\frac{U_\infty H}{\nu}$$

$$Re_c=\frac{U_\infty c}{\nu}$$

where $\nu$ is the kinematic viscosity.

The displayed Reynolds-number reference is selected automatically:

• User reference length, when one is supplied
• Height for very thick or bluff bodies
• Maximum dimension for moderately thick bodies
• Chord for thin bodies and airfoils

Aero Data Panel

The live Aero Data panel displays:

• Reynolds number and its selected reference length
• Angle of attack and its source
• Aerodynamic-result source
• Pressure drag in N/m
• Lift in N/m, when valid
• Height-based $C_D$, $C_L$, and $L/D$
• Chord-based $C_D$, $C_L$, and $L/D$
• Freestream velocity and its source
• Active manual-calibration multiplier

Right-click the panel or press Ctrl+C to copy its contents.

Manual Drag Calibration

A trusted experimental or reference drag coefficient can be entered in the Correct Cd field.

• Set [H] calibrates against the height-based drag coefficient.
• Set [c] calibrates against the chord-based drag coefficient.
• Reset removes the manual calibration.

The software calculates a multiplier:

$$k=\frac{C_{D,\mathrm{target}}}{C_{D,\mathrm{current}}}$$

This multiplier is applied consistently to displayed force and coefficient values. When calibration is active, the Aero Data text changes colour and displays the multiplier.

Use manual calibration only when reliable experimental or reference data are available.

How to Interpret the Pressure Plot

• High positive static pressure in front of an object usually indicates stagnation, where airflow slows and pushes against the surface.
• Negative static pressure around corners, roof edges, or curved upper surfaces usually indicates suction and local acceleration.
• Large pressure differences across a body generally indicate increased aerodynamic loading.
• Alternating pressure regions in a wake may indicate unsteady separation or vortex shedding.
• Strong pressure gradients through gaps may indicate jetting, channeling, or local flow acceleration.
• High dynamic pressure indicates regions of high local flow speed.
• Reduced total pressure downstream can indicate energy loss through separation, mixing, or porous resistance.

Accuracy Tips

• Maintain at least approximately 5 body heights of clearance from walls when possible.
• Keep the body away from the inlet and outlet boundaries.
• Allow the simulation to stabilize before recording aerodynamic values.
• Confirm that residuals, mass balance, and coefficient changes are stable.
• Treat Line Probe and Box Probe forces as raw two-dimensional diagnostics.
• Treat pressure-integrated aerodynamic values as pressure-only estimates.
• Remember that lift is unavailable when the wetted contour is incomplete.
• Use manual calibration only with trusted experimental or reference data.
• Check the source label in the Aero Data panel to determine whether results came from pressure integration or the optional airfoil polar.

General Particle Tracking

General Particle Tracking visualises the solved flow using animated tracer particles. It is intended for examining flow direction, recirculation, stagnation, ventilation paths, and the influence of obstacles or porous regions.

Qualitative Smoke Overlay

Enable Smoke overlay to replace the individual tracer dots with a continuous plume-style visualization.

When the smoke overlay is active:

• Moving tracer dots are hidden
• Stuck-particle dots are hidden
• The smoke field remains based on the same tracer-particle positions
• Particle inlet and exclusion-editing controls are temporarily disabled

The smoke overlay is qualitative and unitless. It does not represent a physical pollutant concentration in $\mu\mathrm{g/m^3}$.

PM2.5 Pollution Analyzer

The PM2.5 Pollution Analyzer is a scenario-screening tool that transports weighted PM2.5 particles through the current horizontal velocity field and reconstructs a modeled airborne concentration field in $\mu\mathrm{g/m^3}$.

Important
The PM2.5 Analyzer is not a certified regulatory dispersion model, monitoring instrument, or legal compliance tool. Results depend on the airflow solution, emission assumptions, source factors, grid scale, mixing assumptions, and reporting height. Source rates should be calibrated using trusted site data whenever possible.

PM2.5 Transport Model

Each computational particle carries:

• Horizontal position $(x,y)$
• Reporting and settling height $z$
• Total particle mass
• PM2.5 mass
• Source colour
• First-order removal coefficient
• Settling velocity
• Consecutive stagnation count

Horizontal particle motion follows the solved velocity field:

$$\frac{dx}{dt}=u(x,y)$$

$$\frac{dy}{dt}=v(x,y)$$

The implementation uses midpoint velocity sampling and CFL-based substeps to reduce numerical wall crossing.

A small stochastic displacement represents unresolved mixing:

$$x_{k+1} = x_k+u\Delta t+\eta_x$$

$$y_{k+1} = y_k+v\Delta t+\eta_y$$

The stochastic mixing term is a scenario-model parameter rather than a complete atmospheric turbulence model.

PM2.5 Sources

{width=20 Open the Editor tab to add or manage pollutant sources.

Available source types include:

• Traffic (Light)
• Diesel Truck
• Construction
• Industry Stack
• Wildfire

To add a source:

1. Select the source type.
2. Click Add Source.
3. Left-click to place polygon vertices.
4. Right-click to finish the polygon.
5. Start or resume the simulation.

Each source has:

• Total emission rate in $\mu\mathrm{g/s}$
• PM2.5 fraction
• Removal or decay coefficient
• Settling velocity
• Initial height bias
• Display colour
• Per-zone emission multiplier

The PM2.5 emission rate is:

$$R_{\mathrm{PM2.5}} = R_{\mathrm{total}}f_{\mathrm{PM2.5}}$$

where:

• $R_{\mathrm{total}}$ is the configured total emission rate
• $f_{\mathrm{PM2.5}}$ is the PM2.5 mass fraction

The PM2.5 mass emitted over one timestep is:

$$\Delta m_{\mathrm{PM2.5}} = R_{\mathrm{PM2.5}}\Delta t$$ The source list also displays the source area and PM2.5 flux: $$\Phi_{\mathrm{PM2.5}} = \frac{R_{\mathrm{PM2.5}}}{A_{\mathrm{source}}}$$

Each source polygon includes a multiplier from approximately $0.1$ to $8.0$. Changing this multiplier changes the source emission rate without altering the base source definition.

Filters

Use Add Filter to draw a green filter polygon.

Particles entering a filter polygon are removed from the airborne population. Their mass is recorded in the filter portion of the audit ledger.

The current implementation treats a filter polygon as complete removal. It does not apply a fractional filter efficiency.

Filters can be deleted individually from the active source and filter list.

Zone of Interest

The blue dashed Zone of Interest defines the region used for:

• Mean concentration
• Spatial 95th percentile
• Maximum concentration
• Exposed-area percentage
• Time-averaged WHO comparison
• PDF report statistics

A default central Zone of Interest is created when no user-defined zone exists.

To replace it:

1. Open the Editor tab.
2. Click Redraw Zone.
3. Left-click to define the polygon vertices.
4. Right-click to finish the polygon.

If no valid Zone of Interest is available, statistics are calculated over the full modeled domain.

Reporting Modes

Two reporting modes are available.

Concentration Heatmap

Enable Show Concentration Heatmap (2D) to display the reconstructed airborne PM2.5 concentration field.

Deposited, collided, filtered, vented, decayed, culled, and deleted mass are excluded from the airborne concentration field.

Reading Local PM2.5 Values

Left-click the map in normal viewing mode to display:

• The selected reporting mode
• Local modeled PM2.5 concentration in $\mu\mathrm{g/m^3}$

A blue dashed circle marks the tooltip location.

Right-click clears all concentration tooltips.

Tooltip values are sampled from the reconstructed concentration grid rather than directly from the nearest visible particle.

Use Ctrl+mouse wheel to zoom the PM2.5 map around the cursor position.

Dashboard Statistics

The Simulated Exposure panel reports statistics for the current Zone of Interest or, when unavailable, the full domain.

Displayed values include:

• Typical concentration — arithmetic zone mean
• High concentration — spatial 95th percentile
• Highest local concentration — maximum grid-cell concentration
• Area at or above 15 $\mu\mathrm{g/m^3}$ — exposed-area percentage

The exposed-area percentage is:

$$A_{\mathrm{exposed}} = 100 \frac{N\left(C\ge15\right)} {N_{\mathrm{valid}}}$$

where:

• $N(C\ge15)$ is the number of reporting cells at or above $15\ \mu\mathrm{g/m^3}$
• $N_{\mathrm{valid}}$ is the number of valid cells in the reporting region

The PDF report additionally includes the 95th percentile among exposed cells.

Important
Spatial P95 and maximum concentration describe hotspot severity. They are not used as WHO compliance metrics.

WHO Guideline Comparison

The WHO panel compares the time-averaged regional mean with the WHO 2021 PM2.5 24-hour guideline of:

$$15\ \mu\mathrm{g/m^3}$$

The annual guideline shown for reference is:

$$5\ \mu\mathrm{g/m^3}$$

An annual result cannot be established from a short scenario simulation.

Before 24 simulated hours are completed, the WHO panel is labelled:

PRELIMINARY — X of 24 hours simulated

After 24 simulated hours, the panel reports either:

• AT OR BELOW WHO 24-HOUR GUIDELINE
• ABOVE WHO 24-HOUR GUIDELINE

The WHO comparison uses a time-averaged regional mean. It does not use spatial P95 or maximum concentration as the comparison metric.

Simulation Speed

Three simulated-time speeds are available:

• 1× Normal — best for inspecting particle motion
• 5× Fast — default accelerated mode
• 20× WHO Fast — faster simulated-time accumulation for long-duration screening

The acceleration control performs additional complete model steps between graphical redraws. Each model step retains the normal timestep and CFL-based substepping.

Actual runtime depends on:

• Particle count
• Number and strength of sources
• Grid dimensions
• Computer performance
• Heatmap and display workload

PM2.5 Mass Tracking

The model records PM2.5 mass through several pathways:

• Airborne — mass currently carried by active particles
• Source buckets — emitted mass waiting to be assigned to particles
• Filtered — mass removed by filter polygons
• Vented — mass that leaves the domain
• Collided — mass removed after entering solid obstacle cells
• Deposited — mass removed after remaining in a low-speed wall-proximate region
• Decayed — mass removed by first-order decay
• Culled — administrative population-control mass, when required
• Deleted — mass associated with a source deleted during a simulation

The PM2.5 mass balance is:

$$M_{\mathrm{emitted}} \approx M_{\mathrm{airborne}} + M_{\mathrm{source\ buckets}} + M_{\mathrm{filtered}} + M_{\mathrm{vented}} + M_{\mathrm{collided}} + M_{\mathrm{deposited}} + M_{\mathrm{decayed}} + M_{\mathrm{culled}} + M_{\mathrm{deleted}}$$ The audit residual is: $$\varepsilon_{\mathrm{audit}} = 100 \frac{ M_{\mathrm{emitted}}-M_{\mathrm{accounted}} }{ M_{\mathrm{emitted}} }$$

A residual near zero indicates internally consistent bookkeeping.

The on-screen technical panel shows:

• Collided mass
• Deposited mass
• Filtered mass
• Vented mass
• Simulated time

The complete audit is included in the PDF report.

PM2.5 Line Probe

Click PM2.5 Probe to open the interactive line-probe tool.

To use it:

1. Click PM2.5 Probe.
2. Click and drag a line across the main PM2.5 map.
3. Release the mouse button.
4. Review the concentration profile in the probe window.
5. Press Esc or close the probe window to exit probe mode.

The probe reports:

• Line length
• Length-weighted mean concentration
• Spatial P95 along the line
• Maximum concentration
• Concentration-distance integral
• A concentration profile graph

The concentration-distance integral is:

$$I_C = \int C(s)\,\mathrm{d}s$$ Its units are: $$\mu\mathrm{g/m^2}$$

The line integral is not inhaled dose and is not pollutant mass flow.

Calculating dose would require breathing rate and exposure time. Calculating mass flow would require velocity and a physical cross-sectional area.

The probe window includes:

• Export numeric data (CSV)
• Copy graph (clipboard)

The CSV file contains:

• Sample index
• Distance along the line
• Model coordinates
• PM2.5 concentration
• Line mean
• P95
• Maximum
• Concentration-distance integral

Description

Click Description to open detailed documentation covering:

• Purpose and scope
• Reporting modes
• Source parameters
• Transport assumptions
• Concentration reconstruction
• WHO interpretation
• Line-probe interpretation
• Mass auditing
• Limitations and references

The description is formatted for printing. Use the browser’s Print command and select Save as PDF if a separate description document is required.

PDF Report

Click PDF Report to generate and save a professional PM2.5 scenario-screening report.

The report includes:

• Executive summary
• Current model snapshot
• Reporting mode
• Zone of Interest
• Mean, P95, maximum, and exposed-area statistics
• WHO 24-hour comparison status
• Source inventory
• PM2.5 emission rates and fluxes
• Mass-balance audit
• Canyon and reporting configuration
• Model methodology
• Interpretation guidance
• Limitations and disclaimers

The report clearly identifies preliminary and projected WHO results.

Important
The generated report supports scenario comparison, design discussion, and ESG documentation. It does not convert the simulation into a certified regulatory assessment.

Performance and Stability

The PM2.5 Analyzer includes several performance safeguards:

• Maximum active-particle population
• Weighted particles representing finite pollutant mass
• Mass-preserving population reduction when particle count becomes excessive
• Decimated particle display
• Concentration-grid resolution limits
• Heatmap updates less frequently than physics updates
• CFL-based transport substeps
• Accelerated simulated-time modes

For improved performance:

• Use moderate source multipliers during setup.
• Pause the simulation while editing source factors.
• Disable the heatmap temporarily when inspecting particle motion.
• Use 20× WHO Fast only when rapid simulated-time accumulation is needed.
• Review the audit residual after long runs or major source changes.

Recommended Uses

Use General Particle Tracking for:

• Fast airflow visualization
• Recirculation and stagnation studies
• Qualitative ventilation comparison
• Particle inlet-path studies
• Porous-zone flow inspection

Use the PM2.5 Pollution Analyzer for:

• Source-location comparisons
• Filter-placement studies
• Before-and-after design comparisons
• Identification of modeled PM2.5 hotspots
• Near-ground exposure screening
• Street-canyon scenario studies
• Sustainability and ESG documentation
• Planning areas for monitoring or higher-fidelity modeling

Scope reminder
Both modes share the same solved velocity field. General Particle Tracking provides qualitative flow visualization, while the PM2.5 Analyzer adds scenario-based mass transport, modeled concentration reconstruction, exposure statistics, WHO guideline comparison, and structured reporting.

Steps

1. Start Probe
   Click Line Probe, then draw a polyline along the path you want to sample.

2. Reference Scaling (distance calibration)

   • If your domain axes are already 1:1 in meters, press OK in the dialog. No calibration is needed.
   • If your domain is scaled from pixels, CAD, or an image, draw a short reference line over a feature with a known real-world length, then enter that length in meters.
   • This sets the meters-per-unit scale so distances, mass flow rate, and integrated values are computed correctly.

Common integrated values
∫ U ds = integral of velocity
∫ U² ds = integral of velocity squared
∫ U³ ds = integral of velocity cubed

3. Auto Plots
   The tool automatically generates:
   • Velocity Magnitude vs Distance
   • Static Pressure vs Distance
   • Vx and Vy Components vs Distance
   • Mass Flow per Segment
   Distance is shown in meters using the scale from Step 2.

Mass-flow relation
ṁ = ρ × Vₙ × A

where: - ṁ is mass flow rate - ρ is fluid density - Vₙ is velocity normal to the line segment - A is the segment area, or effective segment width in the 2-D model

4. Interactive Table
   Shows sampled data:
   • X
   • Y
   • V
   • P
   • Vx
   • Vy
   • ṁ
5. Save
   Export the composite PNG plot.

Graph (Line Probe) Description

This section explains what each line-probe graph shows and how the summary numbers are computed.

You draw a polyline, and the tool resamples the field along its arc length from the start point to the end point.

Symbols used in this section

• s = distance along the polyline
• L = total polyline length
• Δsᵢ = local segment length
• uₓ = x-direction velocity component
• uᵧ = y-direction velocity component
• U = velocity magnitude

Velocity magnitude definition
U = sqrt(uₓ² + uᵧ²)

Example: Using a Near-Surface Line Probe and ∫ U³ ds for Sand Transport

Goal: Estimate along-line aeolian sand transport over 2-D topography using Bagnold-style cubic velocity scaling and the line-probe metric ∫ U³ ds.

Workflow

1. Run a simulation: Ensure velocity and pressure fields are fully established.
2. Open AI Analysis: Click Report / AI Analysis. A new window opens showing the current velocity map.
3. Draw the ROI: Drag a rectangle over the core area you want analyzed. Click Confirm ROI.
4. Pick POIs (points to sample): Click on the plot to drop one or more POIs. They will be numbered automatically. Click Confirm Points of Interest.
5. Name the POIs: A Name Zones window appears. Rename them using clear engineering labels such as Inlet Corner, Work Zone, Return Exhaust, or Filter Face. Click Submit.
6. Enter ESG & Comparison Data: An Energy & Carbon Inputs window appears.
   • Enter baseline operating data such as Fan Power (kW), Operating Hours, Baseline CFM, Electricity Tariff, and Grid Emission Factor.
   • Use After CFM only when a measured or known post-improvement airflow value is available.
   • Leave After CFM blank when comparing design-stage simulations and allowing AirSketcher to estimate performance from the r trends.
   • Cross-Design Comparison: Load up to two saved .pkl state files to directly compare alternative designs against the current baseline.
   • Click Use Values, or click Skip to leave ESG values as N/A.
7. Save the PDF: Choose a filename. AirSketcher generates the PDF in a high-contrast Soft Grid theme, creates a bundle folder, and automatically opens the folder.

What the Report Includes

• 1. Executive Summary & Introduction: Quick directional statistics including ROI mean/variance, key percentiles (P10/P50/P90), best/worst POI percentages, main flow direction, and reversed-flow area fractions.
• 2. Methodology & Theory: A clear layout of the solver configuration, featuring identically sized Governing Equations: Continuity, Momentum, PPE, and Spalart–Allmaras. The section also includes an ASCII boundary-condition sketch and automatically adds Porous/Blower equations, ABL profiles, and AMR mesh illustrations when active.
• 3. Results:
  • 3.1 Velocity & Streamlines: Side-by-side maps using the same color scale, with the ROI box and POI markers cleanly overlaid.
  • 3.2 ROI Statistics: Histogram and Cumulative Distribution Function (CDF) of velocity within the selected ROI.
  • 3.3 & 3.4 POI Data: Data tables and bar charts comparing velocity and static pressure at each named POI.
• 4. Energy & Carbon Savings (ESG-Ready):
  • 4.1 Calculations: Translates flow improvements into hard numbers using Fan Affinity Laws, Outdoor-Air (OA) reduction estimates, and Thermostat Setpoint shifts.
  • 4.2 Savings: Breaks down Fan, OA, and Setpoint savings into kWh/yr, Cost/yr, and tCO2e/yr.
  • 4.3 Cross-Design Comparison: If .pkl files are loaded, this section compares them using a CFM proxy ratio, r. It generates a Standard Table for downstream/supply POIs and an Upstream Table using a pressure-drop proxy for return, exhaust, filter, and suction-side evaluation.
  • 4.4 Energy ROI Interpretation Guide: Adds a deeper explanation of when airflow changes represent real energy savings, when they indicate resistance penalties, and which calculation recipe should be used.
• 5. Conclusions: Explains how to interpret the performance ratio r based on whether POIs are upstream or downstream of the fan. It also provides actionable engineering next steps for design optimization, fan control, resistance reduction, and ESG reporting.

Section 4 Extension: Energy ROI Interpretation Guide

The Energy & Carbon section should be interpreted using one central rule:

AirSketcher does not save energy automatically. It identifies the aerodynamic opportunity. Energy is saved only when the design is improved and the controls are adjusted to use that improvement.

This distinction is important because low airflow can mean two very different things.

Outputs

• PDF Report: The final document, styled in a professional BlueGray palette with zebra-striped tables.
• Bundle Folder: Auto-created next to the PDF. It contains all high-resolution PNG images used in the report, plus a report_insert.docx or .md file so the findings can be copied into company documents.
• AI Pack (.json): A single compressed JSON file containing arrays, grid data, boundary conditions, and embedded images. This can be provided to an AI assistant to generate a custom engineering summary based on the raw CFD data.

Notes & Tips

• Mandatory POIs: You must pick at least one POI to proceed. Grouping POIs with the exact same name will automatically average them together as a Zone in the final tables.
• Use Clear POI Names: Names such as Supply Target, Return Intake, Filter Face, Worker Zone, and Exhaust Hood make the final report easier to interpret.
• Downstream vs Upstream Matters: Use downstream interpretation for supply and occupied-zone performance. Use upstream interpretation for return, exhaust, suction, filter, and hood evaluation.
• Auto-Estimated OA: If the Outdoor-air after field is left blank and a comparison .pkl file is provided, the report can estimate a conservative OA reduction based on ROI variance and P10 dead-zone improvement, capped at 20%.
• Interpreting Proxy Ratio r: An r > 1 downstream usually means better delivery to the target zone. An r > 1 upstream can mean higher pressure drop or resistance, which may be bad. The Conclusions section explains this distinction for client-facing interpretation.
• Energy Requires Action: Energy savings are only realized when the aerodynamic improvement is paired with an operational change, such as fan speed reduction, resistance removal, outdoor-air adjustment, or thermostat setpoint change.

How QFI Works

• $|V| = \sqrt{u^2 + v^2}$
  
• $V_{\text{opt}} = 1.2$ m/s (target)
  
• $\sigma = 0.6$ m/s (tolerance)

Formulas:

• Smoothness
  $$S = \frac{1}{1 + \nabla |V|}$$

• Comfort
  $$V_s = \exp\left(-\frac{(|V| - V_{\text{opt}})^2}{2\sigma^2}\right)$$

• Qi-Flow Index
  $$QFI = S \times V_s$$

Room Classification

Tips for Qi-Aligned Flow

• Break long corridors with buffer zones (read more)
• Allow air to circulate in loops between zones (read more)
• Favor gentle curves over sharp corners (read more)
  
• Enable Refine Flow for natural transitions
  
• Consider adding trees or vegetation zones in outdoor or semi-enclosed areas to introduce soft flow resistance and improve harmony (read more)