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

Author: sbryngelson

.typos.toml

@@ -28,6 +28,7 @@ choises = "choises"   # appears in comment explaining validation purpose
 ordr = "ordr"         # typo for "order" in "weno_ordr" - tests param suggestions
 unknwn = "unknwn"     # typo for "unknown" - tests unknown param detection
 tru = "tru"           # typo for "true" in "when_tru" - tests dependency keys
+PNGs = "PNGs"
 
 [files]
-extend-exclude = ["docs/documentation/references*", "docs/references.bib", "tests/", "toolchain/cce_simulation_workgroup_256.sh", "build-docs/"]
+extend-exclude = ["docs/documentation/references*", "docs/references.bib", "tests/", "toolchain/cce_simulation_workgroup_256.sh", "build-docs/", "build/", "build_test/"]

CLAUDE.md

@@ -108,6 +108,7 @@ IMPORTANT: Follow this loop for ALL code changes. Do not skip steps.
 YOU MUST run `./mfc.sh precheck` before any commit. This is enforced by pre-commit hooks.
 YOU MUST run tests relevant to your changes before claiming work is done.
 NEVER commit code that does not compile or fails tests.
+NEVER use heredocs for git commit messages. Use simple `git commit -m "message"` instead.
 
 ## Architecture
 

docs/documentation/case.md

@@ -651,7 +651,7 @@ To restart the simulation from $k$-th time step, see @ref running "Restarting Ca
 
 The table lists formatted database output parameters. The parameters define variables that are outputted from simulation and file types and formats of data as well as options for post-processing.
 
-- `format` specifies the choice of the file format of data file outputted by MFC by an integer of 1 and 2. `format = 1` and `2` correspond to Silo-HDF5 format and binary format, respectively.
+- `format` specifies the choice of the file format of data file outputted by MFC by an integer of 1 and 2. `format = 1` and `2` correspond to Silo-HDF5 format and binary format, respectively. Both formats are supported by `./mfc.sh viz` (see @ref visualization "Flow Visualization"). Silo-HDF5 requires the h5py Python package; binary has no extra dependencies.
 
 - `precision` specifies the choice of the floating-point format of the data file outputted by MFC by an integer of 1 and 2. `precision = 1` and `2` correspond to single-precision and double-precision formats, respectively.
 

docs/documentation/getting-started.md

@@ -204,6 +204,24 @@ MFC is **unit-agnostic**: the solver performs no internal unit conversions. What
 
 The only requirement is **consistency** — all inputs must use the same unit system. Note that some parameters use **transformed stored forms** rather than standard physical values (e.g., `gamma` expects \f$1/(\gamma-1)\f$, not \f$\gamma\f$ itself). See @ref sec-stored-forms for details.
 
+## Visualizing Results
+
+After running post_process, visualize the output directly from the command line:
+
+```shell
+# List available variables
+./mfc.sh viz examples/2D_shockbubble/ --list-vars --step 0
+
+# Render a pressure snapshot
+./mfc.sh viz examples/2D_shockbubble/ --var pres --step 1000
+
+# Generate a video
+./mfc.sh viz examples/2D_shockbubble/ --var pres --step all --mp4
+```
+
+Output images and videos are saved to the `viz/` subdirectory of the case.
+For more options, see @ref visualization "Flow Visualization" or run `./mfc.sh viz -h`.
+
 ## Helpful Tools
 
 ### Parameter Lookup

docs/documentation/running.md

@@ -73,6 +73,14 @@ using 4 cores:
 ./mfc.sh run examples/2D_shockbubble/case.py -t simulation post_process -n 4
 ```
 
+- Visualizing post-processed output:
+
+```shell
+./mfc.sh viz examples/2D_shockbubble/ --var pres --step 1000
+```
+
+See @ref visualization "Flow Visualization" for the full set of visualization options.
+
 ---
 
 ## Running on GPUs

docs/documentation/troubleshooting.md

@@ -37,6 +37,7 @@ This guide covers debugging tools, common issues, and troubleshooting workflows
 ./mfc.sh run case.py -v        # Run with verbose output
 ./mfc.sh test --only <UUID>    # Run a specific test
 ./mfc.sh clean                 # Clean and start fresh
+./mfc.sh viz case_dir/ --list-vars --step 0  # Inspect post-processed data
 ```
 
 ---
@@ -457,6 +458,47 @@ Common issues:
 
 ---
 
+## Visualization Issues
+
+### "No 'binary/' or 'silo_hdf5/' directory found"
+
+**Cause:** Post-processing has not been run, or the case directory path is wrong.
+
+**Fix:**
+1. Run post_process first:
+   ```bash
+   ./mfc.sh run case.py -t post_process
+   ```
+2. Verify the path points to the case directory (containing `binary/` or `silo_hdf5/`)
+
+### "Variable 'X' not found"
+
+**Cause:** The requested variable was not written during post-processing.
+
+**Fix:**
+1. List available variables:
+   ```bash
+   ./mfc.sh viz case_dir/ --list-vars --step 0
+   ```
+2. Ensure your case file enables the desired output (e.g., ``prim_vars_wrt = 'T'``, ``cons_vars_wrt = 'T'``)
+
+### "h5py is required to read Silo-HDF5 files"
+
+**Cause:** The case was post-processed with `format=1` (Silo-HDF5) but `h5py` is not installed.
+
+**Fix:**
+- Install h5py: `pip install h5py`
+- Or re-run post_process with `format=2` in your case file to produce binary output
+
+### Visualization looks wrong or has artifacts
+
+**Possible causes and fixes:**
+1. **Color range:** Try setting explicit `--vmin` and `--vmax` values
+2. **Wrong variable:** Use `--list-vars` to check available variables
+3. **3D slice position:** Adjust `--slice-axis` and `--slice-value` to view the correct plane
+
+---
+
 ## Getting Help
 
 If you can't resolve an issue:

docs/documentation/visualization.md

@@ -2,13 +2,206 @@
 
 # Flow visualization
 
-A post-processed database in Silo-HDF5 format can be visualized and analyzed using Paraview and VisIt.
-After the post-processing of simulation data (see section @ref running "Running"), a directory named `silo_hdf5` contains a silo-HDF5 database.
-Here, `silo_hdf5/` includes a directory named `root/` that contains index files for flow field data at each saved time step.
+After running `post_process` on a simulation (see @ref running "Running"), MFC produces output in either Silo-HDF5 format (`format=1`) or binary format (`format=2`).
+These can be visualized using MFC's built-in CLI tool or external tools like ParaView and VisIt.
 
-### Visualizing with Paraview
+---
 
-Paraview is an open-source interactive parallel visualization and graphical analysis tool for viewing scientific data.
+## Quick visualization with `./mfc.sh viz`
+
+MFC includes a built-in visualization command that renders images and videos directly from post-processed output — no external GUI tools needed.
+
+### Basic usage
+
+```bash
+# Launch the terminal UI (default mode)
+./mfc.sh viz case_dir/
+
+# Launch with a specific variable pre-selected
+./mfc.sh viz case_dir/ --var pres
+```
+
+The command auto-detects the output format (binary or Silo-HDF5) and dimensionality (1D, 2D, or 3D).
+By default it launches an interactive terminal UI that works over SSH.
+Use `--interactive` for a browser-based UI (supports 3D), `--png` to save images, or `--mp4` for video.
+
+### Exploring available data
+
+Before plotting, you can inspect what data is available:
+
+```bash
+# List all available timesteps
+./mfc.sh viz case_dir/ --list-steps
+
+# List all available variables at a given timestep
+./mfc.sh viz case_dir/ --list-vars --step 0
+```
+
+### Timestep selection
+
+The `--step` argument accepts several formats:
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Single | `--step 1000` | One timestep |
+| Range | `--step 0:10000:500` | Start:end:stride (inclusive) |
+| Last | `--step last` | Most recent available timestep |
+| All | `--step all` | Every available timestep |
+
+### Rendering options
+
+Customize the appearance of plots:
+
+```bash
+# Custom colormap and color range
+./mfc.sh viz case_dir/ --var rho --step 1000 --png --cmap RdBu --vmin 0.5 --vmax 2.0
+
+# Higher resolution
+./mfc.sh viz case_dir/ --var pres --step 500 --png --dpi 300
+
+# Logarithmic color scale
+./mfc.sh viz case_dir/ --var pres --step 1000 --png --log-scale
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--cmap` | Matplotlib colormap name | `viridis` |
+| `--vmin` | Minimum color scale value | auto |
+| `--vmax` | Maximum color scale value | auto |
+| `--dpi` | Image resolution (dots per inch) | 150 |
+| `--log-scale` | Use logarithmic color scale | off |
+| `--output` | Output directory for images | `case_dir/viz/` |
+
+### 3D slicing
+
+For 3D simulations, `viz` extracts a 2D slice for plotting.
+By default, it slices at the midplane along the z-axis.
+
+> [!NOTE]
+> To limit memory use, 3D batch rendering is capped at 500 timesteps and
+> `--interactive` mode at 50. Use `--step start:end:stride` to stay within
+> these limits when processing many steps.
+
+```bash
+# Default z-midplane slice
+./mfc.sh viz case_dir/ --var pres --step 500 --png
+
+# Slice along the x-axis at x=0.25
+./mfc.sh viz case_dir/ --var pres --step 500 --png --slice-axis x --slice-value 0.25
+
+# Slice by array index
+./mfc.sh viz case_dir/ --var pres --step 500 --png --slice-axis y --slice-index 50
+```
+
+### Video generation
+
+Generate MP4 videos from a range of timesteps:
+
+```bash
+# Basic video (10 fps)
+./mfc.sh viz case_dir/ --var pres --step 0:10000:100 --mp4
+
+# Custom frame rate
+./mfc.sh viz case_dir/ --var rho --step all --mp4 --fps 24
+
+# Video with fixed color range
+./mfc.sh viz case_dir/ --var rho --step 0:5000:50 --mp4 --vmin 0.1 --vmax 1.0
+```
+
+Videos are saved as `case_dir/viz/<varname>.mp4`.
+The color range is automatically computed from the first, middle, and last frames unless `--vmin`/`--vmax` are specified.
+
+### Tiled 1D rendering
+
+For 1D cases, omitting `--var` (or passing `--var all`) renders all variables in a single tiled figure:
+
+```bash
+# Tiled plot of all variables at the last timestep
+./mfc.sh viz case_dir/ --step last --png
+
+# Equivalent explicit form
+./mfc.sh viz case_dir/ --var all --step last --png
+```
+
+Each variable gets its own subplot with automatic LaTeX-style axis labels.
+Tiled mode is available for 1D and 2D data. For 3D data, omitting `--var` auto-selects the first variable.
+
+### Interactive mode
+
+Launch a browser-based interactive viewer with `--interactive`:
+
+```bash
+./mfc.sh viz case_dir/ --interactive
+
+# Custom port
+./mfc.sh viz case_dir/ --interactive --port 9000
+```
+
+The interactive viewer provides a Dash web UI with:
+- Variable and timestep selection
+- Live plot updates
+- Pan, zoom, and hover inspection
+
+> [!NOTE]
+> Interactive mode requires the `dash` Python package.
+
+### Terminal UI (TUI)
+
+The default mode launches a live terminal UI that works over SSH with no browser or port-forwarding needed:
+
+```bash
+./mfc.sh viz case_dir/
+
+# Start with a specific variable pre-selected
+./mfc.sh viz case_dir/ --var pres
+```
+
+The TUI loads all timesteps and renders plots directly in the terminal using Unicode block characters.
+It supports 1D and 2D data only (use `--interactive` for 3D).
+
+**Keyboard shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| `.` / `→` | Next timestep |
+| `,` / `←` | Previous timestep |
+| `Space` | Toggle autoplay |
+| `l` | Toggle logarithmic scale |
+| `f` | Freeze / unfreeze color range |
+| `↑` / `↓` | Select variable (in sidebar) |
+| `c` | Cycle colormap |
+| `q` | Quit |
+
+### Plot styling
+
+Axis labels use LaTeX-style math notation — for example, `pres` is labeled as \f$p\f$, `vel1` as \f$u\f$, and `alpha1` as \f$\alpha_1\f$.
+Plots use serif fonts and the Computer Modern math font for consistency with publication figures.
+
+### Format selection
+
+The output format is auto-detected from the case directory.
+To override:
+
+```bash
+./mfc.sh viz case_dir/ --var pres --step 0 --format binary
+./mfc.sh viz case_dir/ --var pres --step 0 --format silo
+```
+
+> [!NOTE]
+> Reading Silo-HDF5 files requires the `h5py` Python package.
+> If it is not installed, you will see a clear error message with installation instructions.
+> Alternatively, use `format=2` (binary) in your case file to produce binary output, which has no extra dependencies.
+
+### Complete option reference
+
+Run `./mfc.sh viz -h` for a full list of options.
+
+---
+
+## Visualizing with ParaView
+
+ParaView is an open-source interactive parallel visualization and graphical analysis tool for viewing scientific data.
+Post-processed data in Silo-HDF5 format (`format=1`) can be opened directly in ParaView.
 Paraview 5.11.0 has been confirmed to work with the MFC databases for some parallel environments.
 Nevertheless, the installation and configuration of Paraview can be environment-dependent and are left to the user.