Restructure README for impact and fix broken doc links#1151
Merged
sbryngelson merged 17 commits intoMFlowCode:masterfrom Feb 16, 2026
Merged
Restructure README for impact and fix broken doc links#1151sbryngelson merged 17 commits intoMFlowCode:masterfrom
sbryngelson merged 17 commits intoMFlowCode:masterfrom
Conversation
- Add tagline and hero blockquote (Gordon Bell, 200T grid points, exascale) - Promote shock-droplet image to hero position - Add "Why MFC?" section with 6 key differentiators - Streamline "Try MFC" with direct Codespace link and first-simulation command - Remove redundant Getting Started section (Codespaces detail, macOS from-source) - Deduplicate citation block and star CTA (each appeared twice) - Move star history chart to bottom - Fix 3 broken doc links: md_examples, md_running, md_getting-started Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
Contributor
ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughReworked documentation (README.md, docs/index.html, docs/.../expectedPerformance.md): introduced exascale/Gordon Bell Prize-focused hero, updated metadata and badges (with alt text), condensed Getting Started/Examples/Why MFC content, consolidated weak-scaling imagery and platform references, removed/relocated star-history blocks, and applied assorted formatting and caption fixes. No public API changes. (42 words) Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
codeant-ai
bot
added
the
size:M
Contributor
|
CodeAnt AI finished reviewing your PR. |
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
README.md (2)
9-45:⚠️ Potential issue | 🟡 MinorAdd
alttext to badge images for accessibility/linting.The HTML
<img>badges in the header block lackaltattributes, which triggers MD045 and hurts accessibility.✅ Example fix (apply to each badge image in this block)
- <img src="https://img.shields.io/github/actions/workflow/status/mflowcode/mfc/test.yml?style=flat&label=Tests&color=slateblue%09"/> + <img src="https://img.shields.io/github/actions/workflow/status/mflowcode/mfc/test.yml?style=flat&label=Tests&color=slateblue%09" alt="Tests status"/>🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@README.md` around lines 9 - 45, The README header's badge <img> elements (the images inside the top <p align="center"> block, e.g., the shields.io and codecov.io badges) are missing alt attributes which triggers MD045; add meaningful alt="" text to each <img> tag (e.g., alt="Tests badge", alt="Contributors badge", alt="Slack badge", alt="License badge", alt="Codecov badge", alt="Contributing guide badge", alt="Docs badge", alt="Discussions badge", alt="Codespaces badge", alt="DockerHub badge", alt="Homebrew badge") so every badge image has an accessible description while preserving existing href/src attributes.
187-192:⚠️ Potential issue | 🟡 MinorFix list indentation consistency.
The GPU scaling sub-list uses inconsistent indentation, which trips MD005. Normalize the indent to match sibling list items.
📐 Example fix
- * \>33K AMD GPUs (MI250X) on [OLCF Frontier](https://www.olcf.ornl.gov/frontier/) - * \>10K NVIDIA GPUs (V100) on [OLCF Summit](https://www.olcf.ornl.gov/summit/) + * \>33K AMD GPUs (MI250X) on [OLCF Frontier](https://www.olcf.ornl.gov/frontier/) + * \>10K NVIDIA GPUs (V100) on [OLCF Summit](https://www.olcf.ornl.gov/summit/)🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In `@README.md` around lines 187 - 192, The nested GPU scaling bullets under the "* GPU compatible on NVIDIA..." section have inconsistent indentation causing MD005 failures; normalize the indenting so each sibling list item uses the same leading spaces (align the sub-list items like "* >43K AMD APUs (MI300A) on [LLNL El Capitan]" and the other three entries to the same indentation level under the parent "* Ideal weak scaling..." bullet), ensuring consistent use of either two or four spaces for each sub-list level throughout the block.
🤖 Fix all issues with AI agents
Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In `@README.md`:
- Around line 74-79: The README uses the Linux-only $(nproc) in the example
command ("./mfc.sh run examples/3d_shockdroplet/case.py -n $(nproc)") which
breaks on macOS; update the examples (including the other occurrence around
lines 116-118) to use a portable CPU-count fallback such as using getconf
_NPROCESSORS_ONLN or sysctl -n hw.ncpu as a fallback, or add a short note
showing both variants for Linux and macOS (e.g., "Linux: $(nproc) | macOS:
$(sysctl -n hw.ncpu)" or a single command with fallback), and ensure the README
text references the chosen command by name so users on macOS/Windows know the
alternative.
- Around line 216-225: The citation badge images in the README (the <img>
elements with src values
"https://img.shields.io/badge/DOI-10.1016/j.cpc.2026.110055-thistle.svg",
"https://zenodo.org/badge/DOI/10.5281/zenodo.17049757.svg", and
"https://img.shields.io/github/stars/MFlowCode/MFC?style=flat&color=maroon")
lack alt attributes and trigger MD045; add concise, descriptive alt attributes
to each <img> (for example: alt="DOI 10.1016/j.cpc.2026.110055", alt="Zenodo DOI
10.5281/zenodo.17049757", alt="GitHub stars for MFlowCode/MFC") so each badge
has accessible alt text while keeping the surrounding <a> links intact.
- Around line 9-45: The README header's badge <img> elements (the images inside
the top <p align="center"> block, e.g., the shields.io and codecov.io badges)
are missing alt attributes which triggers MD045; add meaningful alt="" text to
each <img> tag (e.g., alt="Tests badge", alt="Contributors badge", alt="Slack
badge", alt="License badge", alt="Codecov badge", alt="Contributing guide
badge", alt="Docs badge", alt="Discussions badge", alt="Codespaces badge",
alt="DockerHub badge", alt="Homebrew badge") so every badge image has an
accessible description while preserving existing href/src attributes.
- Around line 187-192: The nested GPU scaling bullets under the "* GPU
compatible on NVIDIA..." section have inconsistent indentation causing MD005
failures; normalize the indenting so each sibling list item uses the same
leading spaces (align the sub-list items like "* >43K AMD APUs (MI300A) on [LLNL
El Capitan]" and the other three entries to the same indentation level under the
parent "* Ideal weak scaling..." bullet), ensuring consistent use of either two
or four spaces for each sub-list level throughout the block.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the README for greater impact by leading with MFC's Gordon Bell Prize finalist status and exascale achievements. The changes improve readability and fix three broken documentation links that would have resulted in 404 errors.
Changes:
- Adds hero blockquote highlighting Gordon Bell Prize finalist status and exascale performance
- Introduces "Why MFC?" section with six key differentiators
- Streamlines "Try MFC" section with direct installation paths and first simulation example
- Fixes broken documentation links (
md_examples→examples,md_running→running,md_getting-started→getting-started) - Removes redundant Getting Started section (detailed macOS walkthrough, Codespaces instructions)
- Deduplicates citation block and star CTA
- Moves star history chart to bottom of README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In `@README.md`:
- Line 44: The Homebrew badge image tag is missing an alt attribute which harms
accessibility; update the img element for the Homebrew badge (the <img
src="https://img.shields.io/badge/homebrew-mflowcode%2Fmfc%2Fmfc-brown?logo=homebrew&style=flat"
/> entry) to include a descriptive alt value (for example "Homebrew:
mflowcode/mfc/mfc" or similar) so screen readers can convey the badge meaning.
- Around line 191-192: The two list items starting with ">33K AMD GPUs (MI250X)
on OLCF Frontier" and ">10K NVIDIA GPUs (V100) on OLCF Summit" have inconsistent
indentation compared to sibling list entries—normalize them by replacing any
leading tabs with the same number of spaces used by the rest of the list (or
align to the established markdown nesting level), ensuring both lines use
identical spacing so the list renders consistently.
…caling plot Add 2025 Gordon Bell Prize Finalist tagline to hero section, OpenGraph and Twitter Card meta tags for link sharing, GitHub stars badge, updated SEO meta description, and replace Frontier+Summit scaling plots with a single three-machine weak scaling figure (El Capitan, Frontier, Alps). Fix LLNL typo and add El Capitan to compute resources footer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
Verify each finding against the current code and only fix it if needed.
In `@docs/index.html`:
- Line 210: The sentence "MFC computations use OLCF Frontier, Summit, and
Wombat; LLNL LC El Capitan, Tuolumne, and Lassen; and many ACCESS-CI systems" is
missing a trailing period—update that string in the HTML (the sentence in docs
index content) to end with a period by appending "." so it matches punctuation
style of surrounding sentences.
In `@README.md`:
- Line 126: Update the README where "SPEChpc" first appears by expanding the
abbreviation and/or adding a link: replace or augment the first occurrence of
"SPEChpc" (the token in the sentence that currently reads "MFC is a SPEChpc
benchmark candidate...") with "SPEChpc (SPEC High Performance Computing,
SPEChpc)" or "SPEChpc (see https://www.spec.org/hpc2021/)" so readers see the
full name or a reference on first use.
🧹 Nitpick comments (1)
🤖 Fix all nitpicks with AI agents
Verify each finding against the current code and only fix it if needed. In `@README.md`: - Line 126: Update the README where "SPEChpc" first appears by expanding the abbreviation and/or adding a link: replace or augment the first occurrence of "SPEChpc" (the token in the sentence that currently reads "MFC is a SPEChpc benchmark candidate...") with "SPEChpc (SPEC High Performance Computing, SPEChpc)" or "SPEChpc (see https://www.spec.org/hpc2021/)" so readers see the full name or a reference on first use.README.md (1)
126-126: Consider adding the SPEChpc abbreviation expansion on first use."SPEChpc" may not be immediately familiar to all readers. A brief expansion or link (e.g., to spec.org) would help.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 126, Update the README where "SPEChpc" first appears by expanding the abbreviation and/or adding a link: replace or augment the first occurrence of "SPEChpc" (the token in the sentence that currently reads "MFC is a SPEChpc benchmark candidate...") with "SPEChpc (SPEC High Performance Computing, SPEChpc)" or "SPEChpc (see https://www.spec.org/hpc2021/)" so readers see the full name or a reference on first use.
Add alt attributes to all badge <img> tags for accessibility (MD045). Normalize GPU scaling sub-list indentation from mixed tabs/spaces to consistent 4-space indent. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
logo2.png does not exist in docs/res/, causing broken social previews. Use banner.png which is a known-good asset. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added a link to GitHub assets in the README.
Remove the static shockdrop.png in favor of the embedded shedding water droplet simulation video, which auto-plays and loops on GitHub. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Updated link to the largest known public CFD simulation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace per-system Frontier SVG with new combined GPU weak scaling PNG covering El Capitan (MI300A), Frontier (MI250X), and Alps (GH200). Mark Summit-era sections as historical. Fix typos. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use <div> instead of <p> for proper centering of video element. Add controls attribute as fallback when autoplay is blocked. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update "Is this really exascale?" with combined El Capitan/Frontier/Alps weak scaling plot. Remove Discussions badge since Discussions is disabled. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🤖 Fix all issues with AI agents
Verify each finding against the current code and only fix it if needed.
In `@docs/documentation/expectedPerformance.md`:
- Around line 170-175: The <img> tag referencing weakscaling.png is missing an
alt attribute (violates MD045); update the <img
src="../res/weakScaling/weakscaling.png" style="width:60%; border-radius:
10pt"/> to include a concise, descriptive alt="..." value (e.g., alt="Weak
scaling performance plot of MFC on El Capitan, Frontier, and Alps showing high
efficiency") so the image is accessible and the MD045 lint rule is satisfied.
🧹 Nitpick comments (1)
🤖 Fix all nitpicks with AI agents
Verify each finding against the current code and only fix it if needed. In `@docs/documentation/expectedPerformance.md`: - Around line 170-175: The <img> tag referencing weakscaling.png is missing an alt attribute (violates MD045); update the <img src="../res/weakScaling/weakscaling.png" style="width:60%; border-radius: 10pt"/> to include a concise, descriptive alt="..." value (e.g., alt="Weak scaling performance plot of MFC on El Capitan, Frontier, and Alps showing high efficiency") so the image is accessible and the MD045 lint rule is satisfied.docs/documentation/expectedPerformance.md (1)
170-175: Add alt text to the weak-scaling image.The new
<img>tag lacksalt, which fails MD045 and hurts accessibility.♿️ Suggested fix
-<img src="../res/weakScaling/weakscaling.png" style="width:60%; border-radius: 10pt"/> +<img src="../res/weakScaling/weakscaling.png" alt="GPU weak scaling on El Capitan, Frontier, and Alps" style="width:60%; border-radius: 10pt"/>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/documentation/expectedPerformance.md` around lines 170 - 175, The <img> tag referencing weakscaling.png is missing an alt attribute (violates MD045); update the <img src="../res/weakScaling/weakscaling.png" style="width:60%; border-radius: 10pt"/> to include a concise, descriptive alt="..." value (e.g., alt="Weak scaling performance plot of MFC on El Capitan, Frontier, and Alps showing high efficiency") so the image is accessible and the MD045 lint rule is satisfied.
Generate inverted-grayscale dark variant of weak scaling plot while preserving colored data points. Use <picture> element for automatic light/dark mode switching, matching the star history chart pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Doxygen docs site uses a dark theme, so the dark variant of the weak scaling plot matches better. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fix outdated 'init' subcommand references to 'new' in the Toolchain table and tab completion note. Remove duplicate shock-droplet run command and visualization text already covered in Try MFC section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
Comment on lines
+47
to
+49
| <div align="center"> | ||
| <video src="https://github.com/user-attachments/assets/4ad20dc2-0920-4ba0-9c95-0949768f8332" width="700" controls autoplay loop muted playsinline></video> | ||
| </div> |
Contributor
There was a problem hiding this comment.
Suggestion: Replace the temporary GitHub attachment URL for the video with a relative path to a video file committed to the repository to prevent the link from breaking. [possible issue, importance: 7]
Suggested change
| <div align="center"> | |
| <video src="https://github.com/user-attachments/assets/4ad20dc2-0920-4ba0-9c95-0949768f8332" width="700" controls autoplay loop muted playsinline></video> | |
| </div> | |
| <div align="center"> | |
| <video src="docs/res/readme_showcase.mp4" width="700" controls autoplay loop muted playsinline></video> | |
| </div> |
| - **CSCS Alps**: NVIDIA GH200 GPUs | ||
|
|
||
| <img src="../res/weakScaling/frontier.svg" style="height: 50%; width:50%; border-radius: 10pt"/> | ||
| <img src="../res/weakScaling/weakscaling-dark.png" style="width:60%; border-radius: 10pt"/> |
Contributor
There was a problem hiding this comment.
Suggestion: Add an alt attribute to the <img> tag to provide descriptive text for screen readers and improve accessibility. [general, importance: 4]
Suggested change
| <img src="../res/weakScaling/weakscaling-dark.png" style="width:60%; border-radius: 10pt"/> | |
| <img src="../res/weakScaling/weakscaling-dark.png" alt="Weak scaling performance on exascale GPUs" style="width:60%; border-radius: 10pt"/> |
|
|
||
| <p align="center"> | ||
| <img src="docs/res/orifice.png" alt="Orifice Example" width="700"/><br/> | ||
| <img src="docs/res/orifice.png" alt="Acoustic wave through orifice" width="700"/><br/> |
Contributor
There was a problem hiding this comment.
Suggestion: Add the loading="lazy" attribute to the <img> tag to defer loading of the offscreen image and improve initial page load performance. [general, importance: 3]
Suggested change
| <img src="docs/res/orifice.png" alt="Acoustic wave through orifice" width="700"/><br/> | |
| <img src="docs/res/orifice.png" alt="Acoustic wave through orifice" width="700" loading="lazy"/><br/> |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Summary
md_examples→examples,md_running→running,md_getting-started→getting-startedTest plan
CodeAnt-AI Description
Lead README with impact statement and simplify getting-started flow
What Changed
Impact
✅ Clearer project intro for new visitors✅ Shorter path to run the first simulation (one-click Codespace + single run command)✅ Fewer dead links when navigating docs💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by CodeRabbit