Add CLI visualization command (./mfc.sh viz)

[sbryngelson]

Summary

Adds ./mfc.sh viz — a built-in CLI visualization command for rendering post-processed MFC output directly from the terminal. No ParaView or VisIt required.

Features

• Format support: Binary (format=2) and Silo-HDF5 (format=1) with automatic detection
• Multi-processor assembly: Reads per-rank output files and stitches them into a global grid, handling ghost cell overlap
• Rendering modes:
  • 1D line plots and tiled all-variable plots
  • 2D colormaps (pcolormesh) and tiled all-variable plots
  • 3D midplane slices (configurable axis, index, or coordinate value)
  • MP4 video generation from timestep ranges (streamed frame-by-frame to avoid OOM)
• Interactive mode: --interactive launches a Dash/Plotly web UI with live controls for slice position, isosurface thresholds, volume rendering, colormap, log scale, vmin/vmax, variable switching, and timestep playback
• Terminal TUI: --tui launches a fully keyboard-driven terminal UI (works over SSH, no browser/port-forwarding needed) with:
  • 1D line plots and 2D heatmaps rendered in-terminal
  • space autoplay, ,/. step navigation, ↑/↓ variable selection
  • l log scale toggle, f freeze color range, c cycle colormap
• Rendering options: --cmap, --vmin/vmax, --dpi, --log-scale, --slice-axis/value/index, --mp4, --fps
• Data exploration: --list-steps and --list-vars to inspect available data before plotting

Usage

# Explore available data
./mfc.sh viz case_dir/ --list-steps
./mfc.sh viz case_dir/ --list-vars --step 0

# Render a PNG
./mfc.sh viz case_dir/ --var pres --step 1000

# Generate an MP4 video
./mfc.sh viz case_dir/ --var pres --step 0:10000:500 --mp4

# 3D slice at z midplane
./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis z

# Interactive web UI (use --step to limit steps for large 3D cases)
./mfc.sh viz case_dir/ --interactive
./mfc.sh viz case_dir/ --var pres --step 0:5000:100 --interactive

# Terminal TUI (SSH-friendly, no browser required)
./mfc.sh viz case_dir/ --tui

Architecture

toolchain/mfc/viz/
├── viz.py           # CLI entry point — parses args, dispatches to readers + renderers
├── reader.py        # Binary format reader + multi-processor assembly (ProcessorData/AssembledData)
├── silo_reader.py   # Silo-HDF5 reader via h5py
├── renderer.py      # matplotlib PNG rendering + imageio MP4 generation
├── interactive.py   # Dash/Plotly web UI with Catppuccin dark theme
├── tui.py           # Textual/plotext terminal TUI (1D/2D, SSH-friendly)
├── _step_cache.py   # Thread-safe bounded FIFO step cache (shared by TUI and interactive)
└── test_viz.py      # Unit tests with checked-in 1D/2D/3D fixture data

Other changes

• CLI integration: VIZ_COMMAND in commands.py, dispatch in main.py (skips cmake check)
• toolchain/mfc/viz.py (old mfc.viz.Case API) and its dependent example scripts (nD_perfect_reactor/analyze.py, nD_perfect_reactor/export.py, 1D_reactive_shocktube/viz.py, 1D_inert_shocktube/viz.py) removed; superseded by ./mfc.sh viz
• Documentation: expanded visualization.md, added quick-start to getting-started.md, viz examples in running.md, troubleshooting section
• requires-python = ">=3.10" added to pyproject.toml
• Viz-specific dependencies moved to [project.optional-dependencies] viz — not installed by default, auto-installed on first ./mfc.sh viz run

Dependencies

• imageio + imageio-ffmpeg for portable MP4 encoding
• h5py for Silo-HDF5 reading
• dash>=2.0 + plotly for interactive mode
• textual>=0.47.0 + textual-plotext + plotext for TUI mode

Correctness notes

• Multi-rank assembly: Ghost-cell deduplication normalizes by domain extent (12 sig digits relative to extent) — correct for both micro-scale and large-scale (extent > 1e12) domains
• Thread safety: _step_cache uses a threading.Lock for safe concurrent access from Dash callbacks; reads happen before eviction so a failed read never discards a valid cache entry
• Interactive/TUI step selection: An explicit --step is honoured so users can limit the loaded set for large 3D cases that would otherwise exceed the 50-step memory limit
• MP4 encoding: Frames normalized to even pixel dimensions (yuv420p requirement), RGB-converted; KeyboardInterrupt still triggers temp-dir cleanup

Test plan

• 1D binary case: ./mfc.sh viz <1d_case> --var pres --step 0
• 2D multi-rank: ./mfc.sh viz <2d_case> --var pres --step 0:1000:100 --mp4
• 3D multi-rank with slicing: ./mfc.sh viz <3d_case> --var pres --step 0 --slice-axis z
• Silo-HDF5 format: ./mfc.sh viz <silo_case> --var pres --step 0
• Interactive mode: ./mfc.sh viz <case> --interactive
• TUI mode: ./mfc.sh viz <case> --tui
• --list-vars and --list-steps info commands