Skip to content

Commit 3f59e87

Browse files
authored
Update README: theming, capabilities, and cleanup (#1129)
Update README: fix star chart theming, add missing capabilities, trim toolchain section
1 parent 1c96f96 commit 3f59e87

1 file changed

Lines changed: 17 additions & 42 deletions

File tree

README.md

Lines changed: 17 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,11 @@
4646

4747
<p align="center">
4848
<a href="https://star-history.com/#MFlowCode/MFC&Date">
49-
<img src="https://api.star-history.com/svg?repos=MFlowCode/MFC&type=Date&theme=dark" alt="Star History Chart" width="600"/>
49+
<picture>
50+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=MFlowCode/MFC&type=Date&theme=dark" />
51+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=MFlowCode/MFC&type=Date" />
52+
<img src="https://api.star-history.com/svg?repos=MFlowCode/MFC&type=Date&theme=dark" alt="Star History Chart" width="600"/>
53+
</picture>
5054
</a>
5155
</p>
5256

@@ -70,7 +74,7 @@ MFC runs at exascale on the world's fastest supercomputers:
7074

7175
**Welcome!**
7276
MFC simulates compressible multi-phase flows, [among other things](#what-else-can-this-thing-do).
73-
It uses metaprogramming and is short (20K lines) and portable.
77+
It uses metaprogramming and is short (~40K lines of Fortran) and portable.
7478
MFC conducted the largest known CFD simulation at <a href="https://arxiv.org/abs/2505.07392" target="_blank">200 trillion grid points</a>, and 1 quadrillion degrees of freedom (as of September 2025).
7579
MFC is a 2025 Gordon Bell Prize Finalist.
7680

@@ -199,53 +203,19 @@ then you can build MFC and run the test suite!
199203
```
200204
And... you're done!
201205

202-
## Toolchain Features
203-
204-
The `mfc.sh` script provides a comprehensive toolchain for building, running, and testing MFC:
206+
## Toolchain
205207

206208
| Command | Description |
207209
|---------|-------------|
208210
| `./mfc.sh build` | Build MFC and its dependencies |
209-
| `./mfc.sh run case.py` | Run a simulation case |
211+
| `./mfc.sh run case.py` | Run a simulation case (interactive or batch: SLURM/PBS/LSF) |
210212
| `./mfc.sh test` | Run the test suite |
211213
| `./mfc.sh validate case.py` | Check a case file for errors before running |
212214
| `./mfc.sh init my_case` | Create a new case from a template |
213215
| `./mfc.sh clean` | Remove build artifacts |
214216
| `./mfc.sh interactive` | Launch interactive menu-driven interface |
215217

216-
### Quick Start Workflow
217-
218-
```bash
219-
./mfc.sh init my_first_case # Create a new case from template
220-
./mfc.sh validate my_first_case/case.py # Validate the case file
221-
./mfc.sh build -j $(nproc) # Build MFC
222-
./mfc.sh run my_first_case/case.py # Run the simulation
223-
```
224-
225-
### Case Templates
226-
227-
Create new cases quickly with built-in templates:
228-
229-
```bash
230-
./mfc.sh init --list # List available templates
231-
./mfc.sh init my_case -t 2D_minimal # Create 2D case
232-
./mfc.sh init my_case -t example:1D_sodshocktube # Copy from examples
233-
```
234-
235-
### Shell Completion
236-
237-
Enable tab completion for commands and options:
238-
239-
```bash
240-
# Bash
241-
source toolchain/completions/mfc.bash
242-
243-
# Zsh (add to fpath)
244-
fpath=(path/to/MFC/toolchain/completions $fpath)
245-
autoload -Uz compinit && compinit
246-
```
247-
248-
You can learn more about MFC's capabilities [via its documentation](https://mflowcode.github.io/documentation/index.html) or play with the examples located in the `examples/` directory (some are [shown here](https://mflowcode.github.io/documentation/md_examples.html))!
218+
Run `./mfc.sh <command> --help` for detailed options, or see the [full documentation](https://mflowcode.github.io/documentation/index.html). Tab completion for bash and zsh is auto-installed after you have run `./mfc.sh generate` (or any non-`init` command) at least once. Play with the examples in `examples/` ([showcased here](https://mflowcode.github.io/documentation/md_examples.html)).
249219

250220
The shock-droplet interaction case above was run via
251221
```shell
@@ -282,13 +252,16 @@ We also scale ideally to >98% of LLNL El Capitan.
282252
* Complex/arbitrary geometries via immersed boundary method
283253
* STL geometry files supported
284254
* Surface tension for multiphase cases
285-
* Sub-grid dynamics
286-
* Euler-Euler particle models for bubble dynamics and similar
287-
* Euler-Lagrange bubble dynamics
255+
* Sub-grid bubble dynamics
256+
* Euler-Euler volume-averaged bubble models
257+
* Euler-Lagrange particle tracking
258+
* Quadrature-based moment methods (QBMM)
288259
* Viscous effects (high-order accurate representations)
260+
* Hypoelastic and hyperelastic material models
289261
* Ideal and stiffened gas equations of state
290262
* Body forces
291263
* Acoustic wave generation (one- and two-way sound sources)
264+
* Chemistry and multi-species transport via [Pyrometheus](https://github.com/pyrometheus/pyrometheus)
292265
* Magnetohydrodynamics (MHD)
293266
* Relativistic Magnetohydrodynamics (RMHD)
294267

@@ -323,7 +296,9 @@ We also scale ideally to >98% of LLNL El Capitan.
323296
* \>33K AMD GPUs (MI250X) on [OLCF Frontier](https://www.olcf.ornl.gov/frontier/)
324297
* \>10K NVIDIA GPUs (V100) on [OLCF Summit](https://www.olcf.ornl.gov/summit/)
325298
* Near compute roofline behavior
299+
* Compile-time case optimization (hard-codes parameters for significant speedup)
326300
* RDMA (remote data memory access; GPU-GPU direct communication) via GPU-aware MPI on NVIDIA (CUDA-aware MPI) and AMD GPU systems
301+
* Built-in profiling support (NVIDIA Nsight Compute/Systems, AMD rocprof)
327302
* Optional single-precision computation and storage
328303

329304
### Software robustness and other features

0 commit comments

Comments
 (0)