Troubleshoot Airflow Simulation
Use this guide when an airflow field, baked-field package, or coupled physics run behaves differently from the engineering expectation. Start with identity, units, geometry, and source settings before changing solver or runtime parameters.
Prerequisites
Collect the following evidence before troubleshooting:
- scene, geometry, field, and run IDs;
- solver path, version, resolution, run window, and hardware;
- coordinate system, units, domain bounds, and boundary settings;
- air-source configuration and input provenance;
- solid-surface or voxel preview;
- field visualization and agreed section profiles;
- moving-object properties and runtime settings;
- error message, warning, or unexpected metric;
- baseline or previously accepted result when available.
Triage flow
Quick symptom map
| Symptom | First checks |
|---|---|
| Flow crosses a wall or cover | Geometry version, scale, thin surfaces, voxel resolution, and boundary assignment. |
| Flow stops or reflects at an open region | Domain opening, inlet or outlet treatment, solid mask, and domain extent. |
| Flow direction is reversed | Source direction vector, scene transform, coordinate handedness, and unit conversion. |
| Field becomes unstable | Source scaling, time step, model stability range, boundary treatment, and grid resolution. |
| Candidate order changes with grid size | Grid convergence at decision locations and near critical surfaces. |
| Baked field does not match the reviewed field | Field version, origin, grid spacing, orientation, scaling, and interpolation bounds. |
| Object moves in an unexpected direction | Surface normals, relative velocity, mass properties, center of mass, and force sign. |
| Force or torque has sharp spikes | Sampling density, object contact events, step size, field boundary crossing, and limits. |
| PhysX and Newton produce different outcomes | Runtime version, collision representation, contact settings, step size, and aggregate decision metrics. |
Check identity and coordinates
Confirm that every artifact belongs to the same scenario version. Compare the USD scene origin, solver-domain origin, field origin, object transforms, and runtime coordinate system. Verify length, velocity, mass, force, torque, and time units.
A coordinate or unit mismatch can preserve a plausible picture while producing incorrect sampling and object response. Capture a known reference point in both the scene and field to verify alignment.
Check geometry and the solid representation
Compare the visual scene with the geometry used by the airflow solver. Inspect thin covers, narrow gaps, open edges, inverted surfaces, duplicated surfaces, and objects close to the domain boundary. Review the solid mask or voxel preview from several viewpoints.
When important geometry is thinner than the selected grid, either simplify it into a resolvable engineering representation or increase resolution in the affected region. Record the change as a new geometry and field version.
Check domain and boundary settings
Confirm that the domain includes the region needed for source development, interaction, and downstream review. Inspect each wall, opening, inlet, and outlet assignment. Compare a larger-domain run when a boundary may be influencing the region of interest.
Use agreed section profiles to detect reflection, clipping, unexpected acceleration, or loss near a boundary. Keep boundary assumptions visible in the result package.
Check the air-source definition
For each source, verify position, direction, effective opening, active state, scaling, and provenance. Visualize source origin and direction in the same coordinate frame as the scene. Compare a single-source run with the multi-source run when interaction is difficult to explain.
Apply calibration changes through a versioned record. Preserve the original value, calibrated value, evidence, and approved operating range.
Check solver and field quality
Review stability, residual behavior, conservation, sampling window, and convergence at the metrics used for the decision. Compare analytical and GPU LBM results at agreed locations where both methods are expected to show the same broad direction.
Use coarse, medium, and fine grids when the result is sensitive to resolution. Keep a study in review when the decision metric has not stabilized.
Check baked-field reuse
Confirm field ID, version, origin, dimensions, grid spacing, units, scaling, and valid bounds before loading a baked field. Sample known points and compare them with the reviewed source field. Check behavior just inside and outside the field boundary.
Create a new baked-field version when geometry, sources, domain, solver settings, scaling, or calibration changes.
Check force, torque, and runtime behavior
Validate the object geometry, surface normals, sampling points, mass, inertia, center of mass, collision representation, step size, and force or torque limits. Review the airflow field independently from object contact behavior.
PhysX and Newton can differ in contact, collision, and numerical stepping. Reproduce the issue with the smallest useful scenario, then compare aggregate outcomes such as orientation distribution, path completion, force range, or process result. Record runtime-specific settings with the evidence.
Expected output
Troubleshooting should end with a root-cause category, affected versions, evidence reviewed, correction or owner, rerun result, and prevention note. A corrected result receives a new version and retains the earlier evidence.
Validation checklist
- Scene, geometry, field, object, and runtime versions are aligned.
- Coordinate systems and units are verified with a known reference point.
- Solid geometry and boundary assignments match the intended domain.
- Source settings and calibration evidence are traceable.
- Solver stability and decision-metric convergence are reviewed.
- Baked-field metadata and sample values match the approved source field.
- Runtime-specific contact and stepping settings are recorded.
- The correction is confirmed with the same review locations and metrics.
Failure handling
| Outcome | Next action |
|---|---|
| Geometry or coordinate issue confirmed | Correct the scene or engineering representation, create new versions, and rerun. |
| Boundary or source issue confirmed | Update the versioned configuration and repeat field validation. |
| Solver result remains sensitive | Increase evidence, refine the model, or escalate to a dedicated engineering study. |
| Runtime-only difference confirmed | Tune and validate the affected runtime while preserving the reviewed airflow field. |
| Root cause remains unresolved | Escalate with the complete evidence package and a minimal reproducible scenario. |