Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
105 commits
Select commit Hold shift + click to select a range
562919f
Add `./mfc.sh viz` command for CLI visualization of post-processed ou…
sbryngelson Feb 21, 2026
97f3bc7
Fix viz: validate variable name and fix lint/spelling issues
sbryngelson Feb 21, 2026
4d6cc7a
Fix MP4 frame directory to use output path instead of case directory
sbryngelson Feb 21, 2026
a1e5515
Fix Silo-HDF5 reader to parse Named Datatype structure correctly
sbryngelson Feb 22, 2026
a9fb166
Fix multi-processor assembly and Silo data ordering
sbryngelson Feb 22, 2026
b6e4c2f
Use imageio-ffmpeg for MP4 rendering instead of system ffmpeg
sbryngelson Feb 22, 2026
e008f85
Add documentation for ./mfc.sh viz command
sbryngelson Feb 22, 2026
9f7da71
Address code review feedback from CodeRabbit
sbryngelson Feb 22, 2026
c5e683e
Fix --step input validation and clarify inclusive range in docs
sbryngelson Feb 22, 2026
a239780
Guard LogNorm against non-positive data in log-scale rendering
sbryngelson Feb 22, 2026
a4940dc
Harden readers and CLI error handling
sbryngelson Feb 22, 2026
ae3e48d
Add viz to CLI reference doc generation categories
sbryngelson Feb 22, 2026
cbfd749
Harden binary reader: EOF check, header validation, varname union, st…
sbryngelson Feb 22, 2026
838c826
Fix MP4 opts mutation, frame cleanup safety, silo skip warning
sbryngelson Feb 22, 2026
938fc74
Harden viz: record validation, error handling, and robustness
sbryngelson Feb 22, 2026
33721e8
Guard LogNorm against NaN data, harden frame cleanup
sbryngelson Feb 22, 2026
010e3de
Fix KeyError in MP4 rendering and require --step for render
sbryngelson Feb 23, 2026
8708571
Use MFCException instead of sys.exit, remove imageio from deps
sbryngelson Feb 24, 2026
06e3dc8
Fix frame cleanup race, value0 guard, and clean up warnings imports
sbryngelson Feb 24, 2026
2adf585
Replace deprecated imageio.get_writer with imageio.mimwrite
sbryngelson Feb 24, 2026
99b5b75
Add h5py/imageio deps, cmap completion, quick-start guide, simplify i…
sbryngelson Feb 24, 2026
ff89b90
Suppress ffmpeg diagnostic noise in MP4 output
sbryngelson Feb 25, 2026
c8bd1a5
Fix AttributeError: numpy.void has no .get(), use [] indexing
sbryngelson Feb 25, 2026
12a71f0
Expand --cmap completion to full matplotlib colormap list
sbryngelson Feb 25, 2026
4b65c13
Add --interactive mode: Dash web UI for 3D/2D/1D visualization
sbryngelson Feb 25, 2026
d26623c
Fix interactive viz freezing: switch sliders to updatemode=mouseup
sbryngelson Feb 25, 2026
7901c68
Fix 3D aspect ratio and add blast wave example
sbryngelson Feb 25, 2026
197d1ca
Revert example changes from previous commit
sbryngelson Feb 25, 2026
b66dbda
Add variable picker to interactive viz UI
sbryngelson Feb 25, 2026
3e0eb8d
Fix precheck failures in interactive.py
sbryngelson Feb 25, 2026
7ef8823
Add tiled 1D rendering, grid lines, and adaptive 2D figsize
sbryngelson Feb 26, 2026
e5c9c1a
Use LaTeX-style fonts and math-mode axis labels in plots
sbryngelson Feb 26, 2026
3d10bb9
Validate timestep in --list-vars before assembly
sbryngelson Feb 26, 2026
db19ff4
Add LaTeX label lookup for MFC variable names in plots
sbryngelson Feb 26, 2026
499274c
Add viz unit tests with checked-in 1D/2D/3D fixture data
sbryngelson Feb 26, 2026
45afb8b
Merge remote-tracking branch 'origin/master' into viz-fast
sbryngelson Feb 26, 2026
d94f437
Fix ghost-cell dedup, 3D memory guard, and interactive host binding
sbryngelson Feb 26, 2026
32cbd52
Add terminal TUI (--tui) for 1D/2D interactive visualization
sbryngelson Feb 26, 2026
4b78bf1
Fix MP4 memory usage and remove cmcrameri-dependent colormaps
sbryngelson Feb 26, 2026
667ca10
Add log scale, freeze range, and autoplay to TUI
sbryngelson Feb 26, 2026
2498a0f
Fix Python 3.10+ compatibility and packaging issues
sbryngelson Feb 26, 2026
42d0923
Add sensible defaults to ./mfc.sh viz flags
sbryngelson Feb 26, 2026
fb065bc
Improve viz error messages: colormap validation, step hints, missing …
sbryngelson Feb 26, 2026
b63d392
Add TUI section to viz docs and update defaults
sbryngelson Feb 26, 2026
085437e
Fix log scale: add 1D support, fix TUI vmin clamping, add log indicators
sbryngelson Feb 26, 2026
12e09fa
Remove [log] suffix from PNG/video colorbar labels
sbryngelson Feb 26, 2026
911b10a
Add TUI frozen indicator; fix spell check scanning build_test/
sbryngelson Feb 26, 2026
3fec6f1
Address review: bounded caches, MP4 cleanup, avoid double-read
sbryngelson Feb 26, 2026
caacd92
Add unit tests for _steps_hint, _validate_cmap, TUI cache, and log scale
sbryngelson Feb 26, 2026
189dc24
Raise on missing processor files instead of silently skipping
sbryngelson Feb 26, 2026
85c715e
Fix dedup large-domain math, add --host flag, add multi-rank assembly…
sbryngelson Feb 26, 2026
a84b3f3
Move viz deps to optional extra; install on first ./mfc.sh viz
sbryngelson Feb 26, 2026
1d12175
Address Claude Code review: bounded caches, MP4 cleanup, avoid double…
sbryngelson Feb 26, 2026
45070f9
Add render_2d_tiled: tile all variables for 2D --var all
sbryngelson Feb 26, 2026
59086c7
Add comma-list and ellipsis step syntax to --step
sbryngelson Feb 26, 2026
dc02a34
Fix MP4 frame-size inconsistency from bbox_inches='tight'
sbryngelson Feb 26, 2026
475bfd7
Fix MP4 uniform frame size: scan all frames for max dims
sbryngelson Feb 26, 2026
412f36a
Address review: normalize MP4 frames to RGB; test negative _dedup dec…
sbryngelson Feb 26, 2026
7d04f9a
TUI 2D: preserve physical domain aspect ratio in heatmap
sbryngelson Feb 26, 2026
a67bc37
Remove legacy viz scripts and viz_legacy module; fix lint for viz extras
sbryngelson Feb 27, 2026
9f0f3dc
Add timeout to viz deps install subprocess
sbryngelson Feb 27, 2026
7db60f8
Use MFCException in tui.py; remove 2>/dev/null from lint.sh
sbryngelson Feb 27, 2026
42797c6
Merge branch 'master' into viz-fast
sbryngelson Feb 27, 2026
4924a13
Address bot review: sentinels, seaborn, dep cleanup, TUI docs, guards
sbryngelson Feb 27, 2026
3363995
Fix bot review findings #5 and #7
sbryngelson Feb 27, 2026
ac585c4
Address PR review findings: thread safety, precision, error handling,…
sbryngelson Feb 27, 2026
c4ca836
fix
sbryngelson Feb 27, 2026
4929904
Improve viz CLI help text: modes, tiled layout, quick-start, arg desc…
sbryngelson Feb 27, 2026
076fb55
fix bot reviews
sbryngelson Feb 27, 2026
ec1a822
fixes
sbryngelson Feb 27, 2026
a51ed6d
Address Claude review: cache clear() API and MP4 error handling
sbryngelson Feb 27, 2026
d8b0a41
viz: overlay Lagrange bubble positions on 2D/3D plots
sbryngelson Feb 27, 2026
8740b96
viz: add Lagrange bubble overlay to interactive Dash mode
sbryngelson Feb 27, 2026
e11b493
viz: overlay Lagrange bubble circles in TUI heatmap
sbryngelson Feb 27, 2026
800327e
viz: enforce 5s minimum MP4 duration when fps is not specified
sbryngelson Feb 27, 2026
8b217ec
viz: default --mp4 to all steps (like --interactive/--tui)
sbryngelson Feb 27, 2026
ae45ed1
viz: address bot review findings (encoding, lint sentinel, cmap, MP4 …
sbryngelson Feb 28, 2026
25afc74
viz: add value-level silo/binary consistency test and --step format r…
sbryngelson Feb 28, 2026
e1a4842
viz: tui improvements — background loading, Digits, Sparkline, click …
sbryngelson Feb 28, 2026
629a782
viz: tui — drop sparkline, fix click via get_content_offset
sbryngelson Feb 28, 2026
1396f68
viz: tui — fix click via @on(Click,'#plot') + screen coords
sbryngelson Feb 28, 2026
39bc185
viz: tui — fix click-to-value: on_mouse_up, ALLOW_SELECT=False, visib…
sbryngelson Feb 28, 2026
ed7e39d
viz: dynamic colorbar label width to prevent truncation of long values
sbryngelson Feb 28, 2026
3c0a82a
viz: fix colorbar label width to 11 chars for negative scientific not…
sbryngelson Feb 28, 2026
87602fd
viz: fix silent bubble warning, slice-index/value guard, binary seek …
sbryngelson Feb 28, 2026
2820047
viz: warn on dual format dirs, improve step-mismatch error, restore a…
sbryngelson Feb 28, 2026
b21a24c
viz: fix analyze.py variable names and Cantera 3.2 deprecation warnings
sbryngelson Feb 28, 2026
b0acc7c
viz: fix analyze.py variable names, Cantera deprecation warnings, cur…
sbryngelson Feb 28, 2026
dcd04ef
viz: fix ellipsis n_requested count; add 2-rank ghost-cell assembly f…
sbryngelson Feb 28, 2026
9ac8874
ci: move test_viz from pre-commit hook to CI-only
sbryngelson Feb 28, 2026
ed8328e
ci: move test_viz from pre-commit hook to CI-only
sbryngelson Feb 28, 2026
a44a898
viz: fix vmin=0 bug, narrow exception handling, improve MP4 error msg
sbryngelson Feb 28, 2026
7726418
viz: make viz deps non-optional; add half-precision msg; tighten step…
sbryngelson Feb 28, 2026
b95c245
viz: dark-theme interactive UI, scientific notation colorbars, SSH tu…
sbryngelson Feb 28, 2026
6b772ee
viz: improve SSH tunnel help text, add chmod 700 for sockets dir
sbryngelson Feb 28, 2026
f56520f
viz: simplify SSH tunnel help, show user@host format
sbryngelson Feb 28, 2026
adfcdc7
viz: add port-in-use troubleshooting hint to SSH tunnel help
sbryngelson Feb 28, 2026
5b8d16e
viz: make TUI the default mode, add --png flag for image output
sbryngelson Mar 1, 2026
9491519
viz: replace schlieren with always-available vars in examples
sbryngelson Mar 1, 2026
a49ceba
viz: clarify which CLI options apply to which output modes
sbryngelson Mar 1, 2026
6321994
viz: add viz to primary commands list in main help
sbryngelson Mar 1, 2026
d1ccb3d
viz: color section headers yellow in Key Options help
sbryngelson Mar 1, 2026
64257b4
viz: limit rendering/slice CLI opts to --png/--mp4 only
sbryngelson Mar 1, 2026
ced26e4
viz: warn when --slice-* flags are ignored in --interactive mode
sbryngelson Mar 1, 2026
e72dfd9
Merge branch 'master' into viz-fast
sbryngelson Mar 1, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .typos.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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/"]
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/documentation/case.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
18 changes: 18 additions & 0 deletions docs/documentation/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions docs/documentation/running.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 42 additions & 0 deletions docs/documentation/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

---
Expand Down Expand Up @@ -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:
Expand Down
203 changes: 198 additions & 5 deletions docs/documentation/visualization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading
Loading