432 Common Pitfalls Ac2d69a1

Common Stability Pitfalls

Overview

This document catalogs frequent stability failures and their fixes. Use this as a diagnostic guide when simulations blow up.

Pitfall Categories

CFL/Fourier Violations

Symptom: Exponential Growth

Pattern: Solution grows exponentially, values reach 10^30+ within a few steps.

Cause: Time step exceeds stability limit.

Diagnosis:

python3 scripts/cfl_checker.py --dx YOUR_DX --dt YOUR_DT --diffusivity YOUR_D --velocity YOUR_V --dimensions YOUR_D

Fix:

1. Reduce dt to meet all limits
2. Or switch to implicit scheme
3. Or increase dx (reduces resolution)

Symptom: Oscillations Then Blow-up

Pattern: Solution develops 2dx oscillations that grow unbounded.

Cause: Central differences for advection-dominated problems.

Fix:

1. Use upwind scheme for advection terms
2. Or add artificial diffusion
3. Or use flux limiters (TVD schemes)

Stiffness Issues

Symptom: Extremely Small Time Steps

Pattern: Adaptive stepping reduces dt to 10^-15 or smaller.

Cause: Stiff system with widely separated time scales.

Diagnosis:

python3 scripts/stiffness_detector.py --eigs=FAST_EIGENVALUE,SLOW_EIGENVALUE

Fix:

1. Use implicit or IMEX scheme
2. Identify and treat stiff terms implicitly
3. Use BDF, Radau, or Rosenbrock methods

Symptom: Correct Results But Very Slow

Pattern: Simulation runs but takes millions of small steps.

Cause: Explicit scheme on stiff problem.

Fix: Same as above - switch to stiff solver.

Boundary Condition Issues

Symptom: Instability at Boundaries

Pattern: Blow-up starts at domain edges.

Causes:

1. Incompatible BC with interior scheme
2. Reflection of outgoing waves
3. Wrong-sided stencil at boundaries

Fixes:

Symptom: Spurious Waves from Boundaries

Pattern: Waves emanate from boundaries into domain.

Cause: Non-physical boundary treatment.

Fix:

1. Use characteristic BCs for hyperbolic problems
2. Implement proper Neumann/Robin conditions
3. Add buffer zones

Initialization Issues

Symptom: Immediate Blow-up

Pattern: Solution diverges within first 1-10 steps.

Causes:

1. Initial condition violates conservation
2. Discontinuous IC with central schemes
3. IC incompatible with BCs

Fixes:

Symptom: Transient Spike Then Settling

Pattern: Large values early, then stabilizes.

Cause: IC not in equilibrium with dynamics.

Fix:

1. Ramp parameters gradually (see time-stepping skill)
2. Use smaller dt during startup
3. Pre-condition IC to equilibrium

Numerical Precision Issues

Symptom: Late-Time Instability

Pattern: Stable for many steps, then suddenly diverges.

Causes:

1. Accumulating round-off error
2. Loss of conservation
3. Condition number degradation

Fixes:

Symptom: Checkerboard Pattern

Pattern: Alternating high/low values in 2dx wavelength.

Cause: Odd-even decoupling (central schemes without stabilization).

Fix:

1. Add small diffusion
2. Use staggered grids
3. Apply filtering

Multi-Physics Coupling Issues

Symptom: Instability When Coupling

Pattern: Each physics stable alone, unstable when coupled.

Causes:

1. Operator splitting error
2. Incompatible time scales
3. Conservation violation at interface

Fixes:

Setup Mistakes

Unit Mixing

Pattern: Inconsistent results or immediate blow-up.

Cause: Mixing units (e.g., dx in microns, v in m/s).

Fix: Convert all quantities to consistent units before computing.

Mesh Refinement

Pattern: Instability after mesh refinement.

Cause: Reusing old dt after refining (dx changed).

Fix: Recompute dt after any mesh change.

Anisotropic Grids

Pattern: Instability in one direction.

Cause: Using dx but ignoring smaller dy.

Fix: Use smallest grid spacing for stability calculations.

Diagnostic Workflow

When simulation blows up:

1. WHERE does it start?
   ├── Boundaries → Check BC implementation
   ├── Interior → Check CFL/Fourier
   └── Everywhere → Check IC or stiffness

2. WHEN does it start?
   ├── Immediately → IC or gross CFL violation
   ├── After some time → Gradual instability or round-off
   └── At specific event → Check event handling

3. HOW does it manifest?
   ├── Exponential growth → Linear instability
   ├── Oscillations → Dispersion or central diff issue
   └── Checkerboard → Odd-even decoupling

Prevention Checklist

Before running:

• Verify CFL/Fourier with cfl_checker.py
• Check stiffness ratio if multiple scales
• Validate IC satisfies BCs
• Test with smaller dt first
• Enable conservation monitoring

During run:

• Monitor max/min values
• Track residuals or energy
• Watch for early warning signs
• Log dt changes (if adaptive)

Quick Fixes by Symptom