Add visual example for Poisson bracket

[anjor]

Background

The Poisson bracket tests verify correctness numerically, but visual examples help understand:

• Physical interpretation of {f,g} as advection operator
• Effect of dealiasing on high-k modes
• Differences between analytical and random fields

Tasks

• Create examples/poisson_bracket_demo.py script
• Visualize 2D example: f=sin(x), g=cos(y), {f,g}=-cos(x)sin(y)
  • Plot f, g, and {f,g} as 2D heatmaps
  • Show quiver plot of ∇f and ∇g
  • Annotate with cross product interpretation
• Show effect of dealiasing:
  • Compute bracket with and without dealiasing
  • Plot difference and high-k mode content
• Compare smooth vs random fields:
  • Show why random fields have larger numerical errors
  • Visualize spectral content (1D energy spectra)
• Add to documentation as tutorial

Visual Output

examples/
├── poisson_bracket_demo.py
└── figures/
    ├── analytical_bracket.png       # sin/cos example
    ├── dealiasing_effect.png        # with/without comparison
    └── random_field_spectra.png     # spectral content

Related

• Issue Step 4: Poisson Bracket #4 (Poisson bracket implementation)
• Issue Document numerical error budget for Poisson bracket #36 (error budget documentation)

[anjor]

Status Check ✓ Still needed - No implementation yet

Current State

• No examples/poisson_bracket_demo.py exists
• Poisson bracket tests exist (test_physics.py) but are numerical only
• No visual/pedagogical examples

Context

This would be a pedagogical/documentation enhancement, not a functionality issue. The physics is working correctly; this would help users understand it.

Value Proposition

Visual examples would help users understand:

1. Physical interpretation: {f,g} as advection of g by flow derived from f
2. Dealiasing effect: High-k modes are zeroed, preventing aliasing instability
3. Numerical error: Why random fields have larger errors than analytical fields

Suggested Visualizations

1. Analytical bracket example

f = sin(x), g = cos(y)  
{f,g} = -cos(x)sin(y)  # Exact analytical result

# Plots:
- 2D heatmaps of f, g, {f,g}
- Quiver plot showing ∇f, ∇g
- Annotate with ẑ·(∇f × ∇g) interpretation

2. Dealiasing demonstration

# Compute with and without dealiasing
bracket_no_dealias = poisson_bracket_3d(..., dealias=False)  
bracket_with_dealias = poisson_bracket_3d(..., dealias=True)

# Plots:
- Difference map
- 1D energy spectrum showing high-k zeroing
- Time series showing aliasing instability without dealiasing

3. Smooth vs random fields

# Compare analytical (few modes) vs random (broadband)
# Show why random fields accumulate more FFT error

# Plots:
- Energy spectrum E(k) for both
- Error vs k (random fields worse at high k)

Related Issues

• Issue Document numerical error budget for Poisson bracket #36 - Error budget documentation (complementary)
• Could reference examples from this issue

Dependencies

None - independent enhancement

Priority

Low - Nice pedagogical tool, but not needed for research. Current test suite validates correctness; this would just visualize it nicely.

Suggested timing: After core physics features done, before writing methods paper.

Keeping open - useful documentation enhancement. 📊