Document dimensions, stored-parameter conventions, and strengthen doc linter

[sbryngelson]

User description

Summary

Documentation (equations.md):

• Adds Section 1b: "Units, Dimensions, and Non-Dimensionalization" — explains the unit-agnostic flow solver vs. non-dimensional bubble dynamics
• Documents reference scale conventions and a complete non-dimensionalization table for all bub_pp% parameters
• Adds "Stored Parameter Conventions" section clarifying that fluid_pp%gamma = 1/(γ-1), fluid_pp%pi_inf = γπ∞/(γ-1), and fluid_pp%Re(1) = 1/μ
• Adds "Common Material Values" reference table with pre-computed stored forms for Air, Helium, Water (Tait), and Water (LeMetayer)
• Includes worked code examples for air-water simulation setup and viscous cases
• Explains the two different viscosity parameters (fluid_pp%Re(1) vs bub_pp%mu_l) and their distinct roles
• Fixes misleading EOS description in Section 3.1 to show transformed notation

Doc linter (lint_docs.py) — new checks:

• check_unpaired_math: catches unpaired \f$ and unbalanced \f[/\f]
• check_doxygen_commands_in_backticks: flags Doxygen block commands inside backtick spans
• check_single_quote_in_backtick: flags single quotes in single-backtick spans (Doxygen rendering bug)
• check_amsmath_in_doxygen_math: flags AMSmath-only commands (\dfrac, \tfrac, etc.) that may not render
• Fix @ref/@page regex to support hyphenated IDs

Doxygen rendering fixes:

• Fix all % → %% escaping in backtick spans throughout equations.md (47 occurrences)
• Fix \dfrac → \frac (AMSmath not reliably loaded by MathJax config)
• Fix 6 single-quote-in-backtick issues across case.md, contributing.md, testing.md

CI:

• Add "Lint Docs" step to CI lint-gate (was only in local ./mfc.sh precheck)

Test plan

• Documentation builds successfully with Doxygen
• All equations render correctly with MathJax
• Stored parameter values verified against Fortran source and example cases
• Doc linter passes locally and in CI
• All CI checks pass

🤖 Generated with Claude Code

---

CodeAnt-AI Description

Document units, non-dimensionalization, and stored-parameter conventions; add targeted doc-lint checks and run them in CI

What Changed

• Added a new "Units, Dimensions, and Non-Dimensionalization" section to the Equations and Getting Started docs that:
  • Explains the solver is unit-agnostic for normal runs and warns that all inputs must share the same unit system.
  • Documents that several parameters are stored in transformed forms (e.g., gamma stored as 1/(γ-1), pi_inf scaled by γ/(γ-1), viscosity stored as inverse) and provides a table of common materials and worked examples.
  • Documents that sub-grid bubble models require fully non-dimensional inputs, lists reference scales, and gives the non-dimensional form required for every bub_pp parameter.
• Fixed multiple inline/backtick markdown renderings across docs (converted single backtick spans where needed) and clarified parameter descriptions in case.md and testing.md so examples render correctly.
• Extended the documentation linter with new checks that catch user-visible doc problems:
  • Detect unpaired inline/display math delimiters and unbalanced display math blocks.
  • Flag Doxygen block commands inside backtick spans, single quotes inside single-backtick spans, and AMSmath-only commands that may not render.
  • Improved @ref/@page parsing to accept hyphenated IDs and collect {#id} anchors.
• Added a "Lint Docs" step to CI so doc formatting and Doxygen/math rendering issues are detected in pull requests.

Impact

✅ Clearer parameter guidance to avoid misconfigured simulations
✅ Fewer Doxygen/math rendering surprises in documentation
✅ Docs linting runs in CI to catch doc errors before merge

💡 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:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

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:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

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.

[codeant-ai]

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 ·
Reddit ·
LinkedIn

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Dimensionality The table states bub_pp%M_v and bub_pp%M_g (molar masses) are “already dimensionless (no scaling)”. Molar mass is typically dimensional (kg/mol), so this should be double-checked against how the code uses these fields (e.g., whether they are expected as ratios to a reference molar mass, or used only in dimensionless combinations). If they are dimensional in code, the documentation should specify the required scaling or units explicitly. | `bub_pp%gam_v` | Vapor heat capacity ratio | Already dimensionless (no scaling) | | `bub_pp%gam_g` | Gas heat capacity ratio | Already dimensionless (no scaling) | | `bub_pp%M_v` | Vapor molar mass | Already dimensionless (no scaling) | | `bub_pp%M_g` | Gas molar mass | Already dimensionless (no scaling) | Consistency The definitions of Ca, Eu, Web, and Re_inv should be validated against src/common/m_helper.fpp to ensure they match exactly what’s implemented (including any implicit reference scaling). In particular, Eu defined as p0ref is nonstandard naming (Euler number usually involves rho*u^2), so it may be clearer to either justify this convention explicitly (given the chosen u0) or rename/remove Eu if it is not actually used in the bubble model equations. | Dimensionless group | Definition | Code variable | Computed from | |---|---|---|---| | \f$\text{Ca}\f$ (Cavitation number) | \f$p_{0,\text{ref}} - p_v\f$ | `Ca` | `bub_pp%p0ref - bub_pp%pv` | | \f$\text{Eu}\f$ (Euler number) | \f$p_{0,\text{ref}}\f$ | `Eu` | `bub_pp%p0ref` | | \f$\text{We}_b\f$ (bubble Weber number) | \f$1/\sigma\f$ | `Web` | `1 / bub_pp%ss` | | \f$\text{Re}_{\text{inv}}\f$ (inverse bubble Reynolds number) | \f$\mu_l\f$ | `Re_inv` | `bub_pp%mu_l` | These groups are computed in `src/common/m_helper.fpp` (lines 143--194). Because the bubble equations use these dimensionless numbers directly, **all** `bub_pp%` parameters must be provided in non-dimensional form by the user. The code does not perform any internal non-dimensionalization of these inputs. Scope Clarification The statement that “all bub_pp% parameters must be provided in non-dimensional form” is strong and likely correct for the bubble model path, but it would be good to confirm whether any bub_pp% entries are treated as dimensional anywhere (or are only used to form dimensionless groups internally). If there are exceptions, documenting them would prevent user confusion and mis-specified cases. These groups are computed in `src/common/m_helper.fpp` (lines 143--194). Because the bubble equations use these dimensionless numbers directly, **all** `bub_pp%` parameters must be provided in non-dimensional form by the user. The code does not perform any internal non-dimensionalization of these inputs.

[coderabbitai]

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added detailed documentation on units, dimensions, and non-dimensionalization for bubble models; stored EOS/fluid parameters gamma and pi_inf are documented as transformed values (Gamma_k, Pi_infty_k). CI now runs a docs linter, and the docs linter skip set for equations.md was updated.

Changes

Cohort / File(s)	Summary
Documentation: Equations & Non-Dimensionalization docs/documentation/equations.md	Added subsection "1b: Units, Dimensions, and Non-Dimensionalization"; clarified unit-agnostic solver, mandatory non-dimensionalization for bubble models, transformed storage of gamma→Gamma_k and pi_inf→Pi_infty_k, updated related sections and examples.
CI: Workflow .github/workflows/test.yml	Added a new "Lint Docs" step calling python3 toolchain/mfc/lint_docs.py in the Lint Gate job (documentation linting).
Tooling: Docs Linter toolchain/mfc/lint_docs.py	Updated per-file skip set: for docs/documentation/equations.md added "bub_pp%%" to skip parameter-reference checks.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add comprehensive equations documentation #1136 — Related prior PR that added docs/documentation/equations.md and corresponding linting changes; strongly connected to the current docs and lint adjustments.

Suggested labels

Review effort 4/5, size:XXL

Poem

🐇 I hop through pages, tidy and quick,
Gamma turns Gamma, pi finds its trick,
Scales stack neatly, examples sing,
Lint checks follow with a gentle spring,
A rabbit winks — docs ready to kick.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into master
Title check	✅ Passed	The title accurately summarizes the main changes: documenting dimensions and stored-parameter conventions, plus strengthening the doc linter with new checks.
Description check	✅ Passed	The pull request description is comprehensive and well-structured, covering all major changes to documentation, linter, CI, and testing with clear rationale.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/documentation/equations.md`:
- Around line 91-94: The docs line saying "`bub_pp%M_v`" and "`bub_pp%M_g`" are
"Already dimensionless (no scaling)" is misleading; update the description to
explain these are physical molar masses that do not need reference-scale
normalization because they only appear in dimensionless ratios. Change the text
for bub_pp%M_v and bub_pp%M_g to something like "Physical molar mass — used only
in dimensionless ratios (e.g., M_g/M_v, M_v/(M_g - M_v)); must be provided in
consistent units" so readers know they are not truly dimensionless but don't
require scaling.

[Copilot]

Pull request overview

Adds a new “Units, Dimensions, and Non-Dimensionalization” section to the equations reference to clarify how MFC treats units in the flow solver vs. the sub-grid bubble models, including reference-scale conventions and a worked non-dimensionalization example for bubble cases.

Changes:

• Documented that the core flow solver is unit-agnostic, while bubble dynamics are implemented in non-dimensional form.
• Added reference-scale definitions and a non-dimensionalization table for bub_pp% inputs, plus guidance for flow parameters when bubbles are enabled.
• Explained the distinct roles of fluid_pp%Re(1) (macroscopic viscous stress) vs bub_pp%mu_l (bubble-wall damping), and included a case.py example.

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="toolchain/mfc/lint_docs.py">

<violation number="1" location="toolchain/mfc/lint_docs.py:577">
P2: Inline code spans containing `\f$` or `\f[ ... \f]` will be treated as real math delimiters and can trigger false-positive lint errors. Strip inline code spans before counting delimiters, similar to the math-syntax check.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="toolchain/mfc/lint_docs.py">

<violation number="1" location="toolchain/mfc/lint_docs.py:373">
P2: Removing the built-in "cli-reference" page ID will make check_page_refs report an error for existing docs (e.g., readme.md uses @ref cli-reference). Keep this auto-generated page ID in the allowlist so the linter doesn’t fail.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[codeant-ai]

CodeAnt AI is running Incremental review

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI Incremental review completed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 44.07%. Comparing base (b104aea) to head (ec9bfb9).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1150   +/-   ##
=======================================
  Coverage   44.07%   44.07%           
=======================================
  Files          70       70           
  Lines       20431    20431           
  Branches     1974     1974           
=======================================
  Hits         9004     9004           
  Misses      10291    10291           
  Partials     1136     1136           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codeant-ai]

CodeAnt AI is running Incremental review

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI Incremental review completed.