Add comprehensive equations documentation

[sbryngelson]

User description

User description

Fixes #318

Type of change

• Bug fix
• New feature
• Refactor
• Documentation
• Other: describe

Testing

How did you test your changes?

CI

Checklist

• I added or updated tests for new behavior
• I updated documentation if user-facing behavior changed

See the developer guide for full coding standards.

---

PR Type

Documentation

---

Description

• Added comprehensive 847-line equations reference document (docs/documentation/equations.md) covering all physics models solved by MFC, organized into 18 sections with detailed mathematical formulations and LaTeX equations

• Created new BibTeX bibliography file (docs/references.bib) with 60+ citations organized by topic to support automated documentation generation

• Standardized citation format across documentation files (case.md, visualization.md) from inline HTML anchors to Doxygen \cite commands for consistency

• Replaced manually maintained reference list with automated Doxygen-generated bibliography in docs/documentation/references.md

• Configured Doxygen (Doxyfile.in) and CMake (CMakeLists.txt) to process BibTeX citations automatically

• Updated documentation index (readme.md) to include reference to new equations documentation

• Added docs/references.bib to spell-checker exclusions (.typos.toml)

---

Diagram Walkthrough

flowchart LR
  A["equations.md<br/>847-line reference"] --> B["Doxygen<br/>Bibliography System"]
  C["references.bib<br/>60+ citations"] --> B
  D["case.md<br/>Updated citations"] --> B
  E["visualization.md<br/>Updated citations"] --> B
  B --> F["Automated<br/>Documentation"]
  G["Doxyfile.in<br/>Configuration"] --> B
  H["CMakeLists.txt<br/>Build Integration"] --> B

Loading

File Walkthrough

	Relevant files
Documentation	6 files equations.md Comprehensive equations reference documentation for MFC    docs/documentation/equations.md Added comprehensive 847-line equations reference document covering all physics models solved by MFC Organized into 18 sections including governing PDEs, equations of state, viscous stress, bubble dynamics, elasticity, phase change, chemistry, MHD, and numerical methods Includes detailed mathematical formulations with LaTeX equations and cross-references to source files Documents input parameters that activate each physics module +847/-0  case.md Standardize citation format to Doxygen \cite commands        docs/documentation/case.md Updated 40+ citation references from inline HTML anchor format to Doxygen \cite command format Changed references like [Author (Year)](@ref references) to \cite AuthorYY format Maintains all original citation content while improving documentation consistency Affects sections on viscosity, Riemann solvers, WENO schemes, boundary conditions, and bubble models +34/-34  references.bib Add comprehensive BibTeX bibliography for documentation    docs/references.bib Created new BibTeX bibliography file with 60+ citations for MFC documentation Organized references into categories: governing equations, equations of state, bubble dynamics, elasticity, surface tension, chemistry, MHD, IGR, acoustic sources, Riemann solvers, WENO/spatial reconstruction, time integration, boundary conditions, immersed boundary, low Mach corrections, and MFC papers Includes complete author, title, journal/publisher, volume, pages, and year information Supports Doxygen's \cite command for automatic bibliography generation +592/-0  references.md Replace manual references with Doxygen-generated bibliography docs/documentation/references.md Replaced 74-line manually maintained reference list with automated Doxygen bibliography Simplified to two lines directing users to Doxygen-generated bibliography via \ref citelist Eliminates manual reference maintenance and ensures consistency with BibTeX source +2/-70    visualization.md Standardize visualization documentation citations                docs/documentation/visualization.md Updated 2 citation references from HTML anchor format to Doxygen \cite command format Changed [Author (Year)](@ref references) to \cite AuthorYY for Coralic15 and Meng16 +1/-1      readme.md Add equations reference to documentation index                      docs/documentation/readme.md Added new reference link to @ref equations pointing to comprehensive equations documentation Inserted as first item in the Reference section before existing parameters and CLI references +1/-0
Configuration changes	3 files Doxyfile.in Configure Doxygen to use BibTeX bibliography file                docs/Doxyfile.in Added CITE_BIB_FILES configuration variable pointing to references.bib Enables Doxygen to process BibTeX citations and generate bibliography automatically +1/-1      CMakeLists.txt Configure CMake to pass bibliography to Doxygen                    CMakeLists.txt Added CMake variable DOXYGEN_CITE_BIB_FILES pointing to docs/references.bib Passes BibTeX file path to Doxygen configuration during build +1/-0      .typos.toml Exclude BibTeX file from spell-checking                                    .typos.toml Added docs/references.bib to the extend-exclude list in typos configuration Prevents spell-checker from scanning BibTeX file entries +1/-1

---

Summary by CodeRabbit

• Documentation
  • Added a comprehensive equations reference covering models, EOS, numerical methods, and solver options.
  • Switched documentation to use a centralized BibTeX bibliography and updated citation style across docs.
  • Improved citation rendering so references display author prefixes and link to the full bibliography.
• Tools
  • Enhanced doc linting to validate citation keys and parameter references.
• Chores
  • Removed an automatic recommendation so the "mhd" parameter no longer implies "hyper_cleaning."

---

CodeAnt-AI Description

Add comprehensive equations reference and integrate BibTeX citations into generated documentation

What Changed

• Added a new, comprehensive Equations reference (docs/documentation/equations.md) documenting every physics model and the input parameters that enable them
• Added a centralized BibTeX file (docs/references.bib) and switched documentation to Doxygen \cite citations so the bibliography is generated and clickable in the docs
• Post-processing step inserts "Author et al. [N]" prefixes into generated HTML citations so references display author names before citation numbers
• Documentation tooling updated: Doxygen and CMake now include the BibTeX file and invoke the postprocess script; the docs linter now checks that \cite keys exist and that parameter names referenced in equations.md match the project's parameter registry
• Minor doc updates: replaced inline HTML citation links with Doxygen \cite in various pages, updated visualization references, and excluded the new BibTeX file from the spell-checker

Impact

✅ Clearer equations reference for users selecting physics models
✅ Clickable, centralized bibliography in generated docs
✅ Fewer broken or missing citations and parameter references detected by CI

💡 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

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds centralized BibTeX citation support and documentation content: a new bibliography, Doxygen integration and post-processing, documentation citation conversions and a comprehensive equations reference; tooling and linting updated to validate citation keys and parameter references; a small params dependency tweak.

Changes

Cohort / File(s)	Summary
Build / Doxygen integration CMakeLists.txt, docs/Doxyfile.in	Adds DOXYGEN_CITE_BIB_FILES into docs generation, runs docs/postprocess_citations.py after Doxygen, and requires Python3 interpreter for the docs step. Updates Doxyfile template to accept the bib placeholder.
Bibliography docs/references.bib	New, large BibTeX file with many categorized references for use by Doxygen citations.
Postprocessing & lint tooling docs/postprocess_citations.py, toolchain/mfc/lint_docs.py	New script to prepend author names to Doxygen citation links; linting extended to parse BibTeX keys and validate \cite keys and parameter references in docs. Exposes new functions for parsing and checking citation/parameter keys.
Documentation content docs/documentation/equations.md, docs/documentation/case.md, docs/documentation/visualization.md, docs/documentation/references.md, docs/documentation/readme.md	Adds a comprehensive equations reference; converts many bracketed references to LaTeX \cite style; replaces itemized references with a pointer to the bibliography and adds Equations to the docs index.
Misc / Config .typos.toml, toolchain/mfc/params/definitions.py	Excludes the bibliography from typo checks; removes the mhd parameter's when_true recommendation for hyper_cleaning (dependency entry cleared).

Sequence Diagram(s)

sequenceDiagram
  participant CI as CI / Developer
  participant CMake as CMake (GEN_DOCS)
  participant Doxy as Doxygen
  participant HTML as HTML output
  participant Post as Postprocess script
  participant Lint as lint_docs

  CI->>CMake: configure & generate docs (DOXYGEN_CITE_BIB_FILES)
  CMake->>Doxy: run Doxygen (produces raw HTML)
  Doxy->>HTML: write HTML files with CITEREF_<key> links
  CMake->>Post: invoke Python3 docs/postprocess_citations.py on HTML dir
  Post->>HTML: rewrite citation links to include author prefixes
  CI->>Lint: run toolchain/mfc/lint_docs.py
  Lint->>Post: validate that `\cite` keys exist in docs/references.bib

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Add developer guide, streamline PR template, AI reviewers #1134 — Related changes to documentation linting/tooling and citation/BibTeX checks.
• Quality of life improvements for MFC toolchain #1118 — Related Doxygen/GEN_DOCS changes and docs-generation flow adjustments.
• Auto-generate description labels and extend DEPENDENCIES schema #1133 — Related edits to parameter definitions/schema (overlaps with mhd dependency changes).

Suggested reviewers

• wilfonba

Poem

🐇 I hop through BibTeX fields with cheer,
Names and years now tidy and clear.
Equations gathered, citations in line,
Doxygen and Python make references shine.
A rabbit's small dance — docs now sincere. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	All changes are within scope: documentation additions (equations.md, references.bib), citation standardization (case.md, visualization.md), build/configuration updates (CMakeLists.txt, Doxyfile.in), linting tools (lint_docs.py), and minor configuration changes (.typos.toml). One unrelated change detected: dependency update to 'mhd' parameter in definitions.py.	Review whether the 'mhd' parameter dependency change in toolchain/mfc/params/definitions.py is intentional or should be reverted to stay focused on documentation objectives.
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add comprehensive equations documentation' accurately summarizes the main change: introduction of comprehensive equations reference documentation.
Linked Issues check	✅ Passed	The PR directly addresses issue #318 by adding comprehensive equations documentation (equations.md) with detailed mathematical formulations, nondimensional forms, input parameter mappings, and cross-references to source code.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into master
Description check	✅ Passed	The pull request description comprehensively covers all required template sections: fixed issue (#318), type of change (Documentation), testing method (CI), and updated documentation checklist item.

_{✏️ 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.}

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 318 - Partially compliant Compliant requirements: Make documentation more explicit about what equations MFC solves. Non-compliant requirements: Document how the equations appear in nondimensional form and help users choose consistent input values. Clarify parameter interpretation/mapping (e.g., Reynolds number vs inverse viscosity such as Re vs Re_inv, and velocity-scale computations used in code). Requires further human verification: Validate that the newly documented equations (per-model) match the implemented equation sets selected by model_eqns and related toggles (e.g., alt_soundspeed, relax, mhd, igr) across the codebase. Confirm the documentation site build renders equations.md correctly (MathJax/LaTeX, Doxygen \cite, and the \ref citelist bibliography output). Confirm the new citation workflow (BibTeX + Doxygen) works end-to-end in CI and in local doc builds across supported environments.

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Correctness The new equations reference is extensive and touches many physics modules; several formulas/parameter mappings are easy to get subtly wrong. In particular, verify nondimensional interpretations and parameter naming consistency with actual inputs (e.g., Re_inv vs Reynolds number wording, riemann_solver IDs, low-Mach option semantics, MHD riemann_solver numbering, and any model-specific assumptions like relaxation “applied at each RK stage”). Ensure each section’s equations align with what MFC actually advances (conserved variables, source terms, and closures) to avoid misleading guidance. @page equations Equations # MFC: Comprehensive Equations Reference This document catalogs every equation solved by MFC, organized by physical model. Each section notes the input parameter(s) that activate the corresponding physics module and cross-references the relevant source files. For full citations of MFC papers, see @ref papers. Foundational references for each model are cited inline; see the \ref citelist "Bibliography" for full details. --- ## 1. Overview MFC solves the compressible Navier-Stokes equations (or Euler equations when viscosity is off) in a finite volume framework. The general semi-discrete form is: \f[\frac{\partial \mathbf{q}}{\partial t} + \nabla \cdot \mathbf{F}(\mathbf{q}) + \mathbf{h}(\mathbf{q})\,\nabla \cdot \mathbf{u} = \mathbf{s}(\mathbf{q})\f] where: - \f$\mathbf{q}\f$ is the conservative variable vector, - \f$\mathbf{F}\f$ is the flux tensor, - \f$\mathbf{h}(\mathbf{q})\,\nabla \cdot \mathbf{u}\f$ contains non-conservative terms (volume fraction advection), - \f$\mathbf{s}(\mathbf{q})\f$ is the source vector (bubbles, body forces, chemistry, etc.). The parameter `model_eqns` (1, 2, 3, or 4) selects the governing equation set. **Key source files:** `src/simulation/m_rhs.fpp` (RHS evaluation), `src/common/m_variables_conversion.fpp` (EOS and variable conversion). --- ## 2. Governing PDEs ### 2.1 Five-Equation Model (`model_eqns = 2`) The primary workhorse model (\cite Allaire02). The state vector is: \f[\mathbf{q} = \bigl(\alpha_1 \rho_1,\;\alpha_2 \rho_2,\;\ldots,\;\rho u_1,\;\rho u_2,\;\rho u_3,\;\rho E,\;\alpha_1,\;\alpha_2,\;\ldots\bigr)^T\f] **Continuity** (one per component): \f[\frac{\partial (\alpha_i \rho_i)}{\partial t} + \nabla \cdot (\alpha_i \rho_i\,\mathbf{u}) = 0\f] **Momentum:** \f[\frac{\partial (\rho \mathbf{u})}{\partial t} + \nabla \cdot \bigl(\rho\,\mathbf{u} \otimes \mathbf{u} + p\,\mathbf{I} - \boldsymbol{\tau}^v\bigr) = 0\f] **Energy:** \f[\frac{\partial (\rho E)}{\partial t} + \nabla \cdot \bigl[(\rho E + p)\,\mathbf{u} - \boldsymbol{\tau}^v \cdot \mathbf{u}\bigr] = 0\f] **Volume fraction advection:** \f[\frac{\partial \alpha_i}{\partial t} + \mathbf{u} \cdot \nabla \alpha_i = K\,\nabla \cdot \mathbf{u}\f] where the \f$K\f$ term enforces interface conditions via the Wood sound speed: \f[K = \frac{\rho_2 c_2^2 - \rho_1 c_1^2}{\displaystyle\frac{\rho_1 c_1^2}{\alpha_1} + \displaystyle\frac{\rho_2 c_2^2}{\alpha_2}}\f] Setting `alt_soundspeed = .true.` enables the \f$K\f$ correction (\cite Kapila01, with Wood sound speed). Setting `alt_soundspeed = .false.` uses the Allaire variant without the \f$K\f$ correction, which is conservative but does not strictly obey the second law of thermodynamics. **Mixture rules:** \f[1 = \sum_i \alpha_i, \qquad \rho = \sum_i \alpha_i \rho_i, \qquad \rho e = \sum_i \alpha_i \rho_i e_i\f] ### 2.2 Six-Equation Model (`model_eqns = 3`) Allows pressure disequilibrium between phases (\cite Saurel09). **Continuity and momentum:** Same as the five-equation model. **Separate phasic internal energy:** \f[\frac{\partial (\alpha_i \rho_i e_i)}{\partial t} + \nabla \cdot (\alpha_i \rho_i e_i\,\mathbf{u}) + \alpha_i p_i\,\nabla \cdot \mathbf{u} = -\mu\,p_I\,(p_2 - p_1) - \alpha_i\,\boldsymbol{\tau}_i^v : \nabla \mathbf{u}\f] **Volume fraction:** \f[\frac{\partial \alpha_1}{\partial t} + \mathbf{u} \cdot \nabla \alpha_1 = \mu\,(p_1 - p_2)\f] **Interfacial pressure:** \f[p_I = \frac{z_2\,p_1 + z_1\,p_2}{z_1 + z_2}, \qquad z_i = \rho_i\,c_i\f] Infinite pressure relaxation is applied at each Runge-Kutta stage to drive toward pressure equilibrium. **Mixture speed of sound:** \f[c^2 = \sum_k Y_k\,c_k^2\f] With phase change (`relax = .true.`), additional source terms appear in the phasic energy and volume fraction equations: - **Pressure relaxation:** \f$\mu\,\delta p\f$ where \f$\delta p = p_1 - p_2\f$ - **Thermal transfer:** \f$Q = \theta\,(T_2 - T_1)\f$ - **Mass transfer:** \f$\dot{m} = \nu\,(g_2 - g_1)\f$ (Gibbs free energy difference) See Section 8 (Phase Change) below for details. ### 2.3 Other Model Variants - `model_eqns = 1`: **Gamma/pi_inf model** — simplified single-fluid formulation using mixture \f$\gamma\f$ and \f$\pi_\infty\f$ directly without tracking individual volume fractions (\cite Johnsen08). - `model_eqns = 4`: **Four-equation model** — reduced model from the six-equation system after full pressure-temperature equilibrium relaxation (Tait-like compressible liquid). --- ## 3. Equations of State ### 3.1 Stiffened Gas EOS (\cite Menikoff89; \cite LeMetayer04) The primary closure for each phase: \f[p_k = (\gamma_k - 1)\,\rho_k\,e_k - \gamma_k\,\pi_{\infty,k}\f] Equivalently: \f[e_k = \frac{p_k + \gamma_k\,\pi_{\infty,k}}{(\gamma_k - 1)\,\rho_k}\f] **Total energy relation:** \f[\rho E = \Gamma\,p + \Pi_\infty + \frac{1}{2}\rho\,|\mathbf{u}|^2 + q_v\f] where MFC internally tracks the transformed thermodynamic quantities: \f[\Gamma_k = \frac{1}{\gamma_k - 1}, \qquad \Pi_{\infty,k} = \frac{\gamma_k\,\pi_{\infty,k}}{\gamma_k - 1}\f] and the mixture rules are arithmetic averages of these transformed quantities: \f[\Gamma = \sum_i \frac{\alpha_i}{\gamma_i - 1}, \qquad \Pi_\infty = \sum_i \frac{\alpha_i\,\gamma_i\,\pi_{\infty,i}}{\gamma_i - 1}, \qquad q_v = \sum_i \alpha_i\,\rho_i\,q_{v,i}\f] The pressure is recovered from the total energy as: \f[p = \frac{\rho E - \frac{1}{2}\rho\,|\mathbf{u}|^2 - \Pi_\infty - q_v}{\Gamma}\f] **Phasic speed of sound:** \f[c_k = \sqrt{\frac{\gamma_k\,(p + \pi_{\infty,k})}{\rho_k}}\f] **Wood mixture sound speed:** \f[\frac{1}{\rho\,c^2} = \sum_k \frac{\alpha_k}{\rho_k\,c_k^2}\f] Input parameters per fluid: `gamma` (\f$\gamma_k\f$), `pi_inf` (\f$\pi_{\infty,k}\f$), `cv` (\f$c_{v,k}\f$), `qv` (\f$q_{v,k}\f$), `qvp` (\f$q'_{v,k}\f$). ### 3.2 Ideal Gas EOS (Chemistry, `chemistry = .true.`) For reacting gas mixtures: \f[p = \frac{\rho\,R_u\,T}{W}, \qquad W = \left(\sum_m \frac{Y_m}{W_m}\right)^{-1}\f] Temperature is obtained from the internal energy by Newton iteration: \f[e_g - \sum_m e_m(T)\,Y_m = 0\f] **Species internal energy from enthalpy:** \f[e_m(T) = \frac{\hat{h}_m(T) - R_u\,T}{W_m}\f] **NASA polynomial enthalpies** (\cite McBride93)**:** \f[\frac{\hat{h}_m}{R_u\,T} = \frac{C_0}{T} + \sum_{r=1}^{5} \frac{C_r\,T^{r-1}}{r}\f] --- ## 4. Viscous Stress Tensor (`viscous = .true.`) **Newtonian viscous stress (no bulk viscosity by default):** \f[\boldsymbol{\tau}^v = 2\,\eta\left(\mathbf{D} - \frac{1}{3}\,\text{tr}(\mathbf{D})\,\mathbf{I}\right)\f] where the strain rate tensor is: \f[\mathbf{D} = \frac{1}{2}\bigl(\nabla \mathbf{u} + (\nabla \mathbf{u})^T\bigr)\f] **With bulk viscosity:** \f[\tau_{ij} = \mu\left(\frac{\partial u_i}{\partial x_j} + \frac{\partial u_j}{\partial x_i}\right) + \left(\zeta - \frac{2\mu}{3}\right)\delta_{ij}\,\frac{\partial u_k}{\partial x_k}\f] **Cartesian components:** \f[\tau_{xx} = \mu\left(2\,\frac{\partial u}{\partial x} - \frac{2}{3}\nabla\cdot\mathbf{u}\right), \qquad \tau_{xy} = \mu\left(\frac{\partial u}{\partial y} + \frac{\partial v}{\partial x}\right)\f] and similarly for all other components. Cylindrical coordinate formulations include additional \f$1/r\f$ terms. **Viscosity averaging:** \f[\frac{1}{\text{Re}_\text{mix}} = \sum_j \frac{\alpha_j}{\text{Re}_j}\f] Input parameters: `Re_inv` (shear and volume Reynolds numbers per fluid). Inconsistency The updated narrative and tables introduce potential parameter/feature mismatches that should be double-checked against the code: the low_Mach description references applicability to riemann_solver = 1 and 2 while the table labels corrections as “for HLLC”; the MHD riemann_solver numbering differs between documentation sections; and new citations (e.g., \cite Cao24) must correspond to actual BibTeX keys. These inconsistencies can confuse users and should be reconciled with the actual runtime options. | `ic_eps` | Real | Interface compression threshold (default: 1e-4) | | `ic_beta` | Real | Interface compression sharpness parameter (default: 1.6) | | `riemann_solver` | Integer | Riemann solver algorithm: [1] HLL*; [2] HLLC; [3] Exact*; [4] HLLD (only for MHD) | | `low_Mach` | Integer | Low Mach number correction for HLLC Riemann solver: [0] None; [1] Pressure (\cite Chen22); [2] Velocity (\cite Thornber08) | | `avg_state` | Integer | Averaged state evaluation method: [1] Roe average*; [2] Arithmetic mean | | `wave_speeds` | Integer | Wave-speed estimation: [1] Direct (\cite Batten97); [2] Pressure-velocity* (\cite Toro13) | | `weno_Re_flux` | Logical | Compute velocity gradient using scalar divergence theorem | | `weno_avg` | Logical | Arithmetic mean of left and right, WENO-reconstructed, cell-boundary values | | `dt` | Real | Time step size | | `t_step_start` | Integer | Simulation starting time step | | `t_step_stop` | Integer | Simulation stopping time step | | `t_step_save` | Integer | Frequency to output data | | `t_step_print` | Integer | Frequency to print the current step number to standard output (default 1) | | `cfl_adap_dt` | Logical | CFL based adaptive time-stepping | | `cfl_const_dt` | Logical | CFL based non-adaptive time-stepping | | `cfl_target` | Real | Specified CFL value | | `n_start` | Integer | Save file from which to start simulation | | `t_save` | Real | Time duration between data output | | `t_stop` | Real | Simulation stop time | | `surface_tension` | Logical | Activate surface tension | | `viscous` | Logical | Activate viscosity | | `hypoelasticity` | Logical | Activate hypoelasticity* | | `igr` | Logical | Enable solution via information geometric regularization (IGR) \cite Cao24 | | `igr_order` | Integer | Order of reconstruction for IGR [3,5] | | `alf_factor` | Real | Alpha factor for IGR entropic pressure (default 10) | | `igr_pres_lim` | Logical | Limit IGR pressure to avoid negative values (default F) | | `igr_iter_solver` | Integer | Solution method for IGR elliptic solve [1] Jacobi [2] Gauss-Seidel | | `num_igr_iters` | Integer | Number of iterations for for the IGR elliptic solve (default 2) | | `num_igr_warm_start_iters` | Integer | Number of iterations for the IGR elliptic solve at the first time step (default 50) | - \* Options that work only with `model_eqns = 2`. - † Options that work only with ``cyl_coord = 'F'``. - ‡ Options that work only with `bc_[x,y,z]%[beg,end] = -15` and/or `bc_[x,y,z]%[beg,end] = -16`. The table lists simulation algorithm parameters. The parameters are used to specify options in algorithms that are used to integrate the governing equations of the multi-component flow based on the initial condition. Models and assumptions that are used to formulate and discretize the governing equations are described in \cite Bryngelson19. Details of the simulation algorithms and implementation of the WENO scheme can be found in \cite Coralic15. - `bc_[x,y,z]%[beg,end]` specifies the boundary conditions at the beginning and the end of domain boundaries in each coordinate direction by a negative integer from -1 through -16. See table [Boundary Conditions](#boundary-conditions) for details. Boundary condition patches can be used with non-characteristic boundary conditions. Their use is detailed in [Boundary Condition Patches](#boundary-condition-patches). - `bc_[x,y,z]%%vb[1,2,3]` specifies the velocity in the (x,1), (y,2), (z,3) direction applied to `bc_[x,y,z]%%beg` when using `bc_[x,y,z]%%beg = -16`. Tangential velocities require viscosity, `weno_avg = T`, and `bc_[x,y,z]%%beg = -16` to work properly. Normal velocities require `bc_[x,y,z]%%end = -15` or `\bc_[x,y,z]%%end = -16` to work properly. - `bc_[x,y,z]%%ve[1,2,3]` specifies the velocity in the (x,1), (y,2), (z,3) direction applied to `bc_[x,y,z]%%beg` when using `bc_[x,y,z]%%end = -16`. Tangential velocities require viscosity, `weno_avg = T`, and `bc_[x,y,z]%%end = 16` to work properly. Normal velocities require `bc_[x,y,z]%%end = -15` or `\bc_[x,y,z]%%end = -16` to work properly. - `model_eqns` specifies the choice of the multi-component model that is used to formulate the dynamics of the flow using integers from 1 through 3. `model_eqns = 1`, `2`, and `3` correspond to $\Gamma$-$\Pi_\infty$ model (\cite Johnsen08), 5-equation model (\cite Allaire02), and 6-equation model (\cite Saurel09), respectively. The difference of the two models is assessed by (\cite Schmidmayer19). Note that some code parameters are only compatible with 5-equation model. - `alt_soundspeed` activates the source term in the advection equations for the volume fractions, $K\nabla\cdot \underline{u}$, that regularizes the speed of sound in the mixture region when the 5-equation model is used. The effect and use of the source term are assessed by \cite Schmidmayer19. - `adv_n` activates the direct computation of number density by the Riemann solver instead of computing number density from the void fraction in the method of classes. - `mpp_lim` activates correction of solutions to avoid a negative void fraction of each component in each grid cell, such that $\alpha_i>\varepsilon$ is satisfied at each time step. - `mixture_err` activates correction of solutions to avoid imaginary speed of sound at each grid cell. - `time_stepper` specifies the order of the Runge-Kutta (RK) time integration scheme that is used for temporal integration in simulation, from the 1st to 5th order by corresponding integer. Note that `time_stepper = 3` specifies the total variation diminishing (TVD), third order RK scheme (\cite Gottlieb98). - `adap_dt` activates the Strang operator splitting scheme which splits flux and source terms in time marching, and an adaptive time stepping strategy is implemented for the source term. It requires ``bubbles_euler = 'T'``, ``polytropic = 'T'``, ``adv_n = 'T'`` and `time_stepper = 3`. Additionally, it can be used with ``bubbles_lagrange = 'T'`` and `time_stepper = 3`. `adap_dt_tol` and `adap_dt_max_iters` are 1e-4 and 100, respectively, by default. - `weno_order` specifies the order of WENO scheme that is used for spatial reconstruction of variables by an integer of 1, 3, 5, and 7, that correspond to the 1st, 3rd, 5th, and 7th order, respectively. - `weno_eps` specifies the lower bound of the WENO nonlinear weights. It is recommended to set `weno_eps` to $10^{-6}$ for WENO-JS, and to $10^{-40}$ for other WENO variants. - `mapped_weno` activates the WENO-M scheme in place of the default WENO-JS scheme (\cite Henrick05). WENO-M a variant of the WENO scheme that remaps the nonlinear WENO-JS weights by assigning larger weights to non-smooth stencils, reducing dissipation compared to the default WENO-JS scheme, at the expense of higher computational cost. Only one of `mapped_weno`, `wenoz`, and `teno` can be activated. - `wenoz` activates the WENO-Z scheme in place of the default WENO-JS scheme (\cite Borges08). WENO-Z is a variant of the WENO scheme that further reduces the dissipation compared to the WENO-M scheme. It has similar computational cost to the WENO-JS scheme. - `wenoz_q` specifies the power parameter `q` used in the WENO-Z scheme. It controls how aggressively the smoothness coefficients scale the weights. A higher value of `wenoz_q` increases the sensitivity to smoothness, improving stability but worsening numerical dissipation. For WENO3 and WENO5, `q=1` is fixed, so `wenoz_q` must not be set. For WENO7, `wenoz_q` can be set to 2, 3, or 4. - `teno` activates the TENO scheme in place of the default WENO-JS scheme (\cite Fu16). TENO is a variant of the ENO scheme that is the least dissipative, but could be less robust for extreme cases. It uses a threshold to identify smooth and non-smooth stencils, and applies optimal weights to the smooth stencils. Only available for `weno_order = 5` and `7`. Requires `teno_CT` to be set. Does not support grid stretching. - `teno_CT` specifies the threshold for the TENO scheme. This dimensionless constant, also known as $C_T$, sets a threshold to identify smooth and non-smooth stencils. Larger values make the scheme more robust but also more dissipative. A recommended value for teno_CT is `1e-6`. When adjusting this parameter, it is recommended to try values like `1e-5` or `1e-7` for TENO5. A smaller value can be used for TENO7. - `null_weights` activates nullification of the nonlinear WENO weights at the buffer regions outside the domain boundaries when the Riemann extrapolation boundary condition is specified (`bc_[x,y,z]%%beg[end]} = -4`). - `mp_weno` activates monotonicity preservation in the WENO reconstruction (MPWENO) such that the values of reconstructed variables do not reside outside the range spanned by WENO stencil (\cite Balsara00; \cite Suresh97). - `muscl_order` specifies the order of the MUSCL scheme that is used for spatial reconstruction of variables by an integer of 1, or 2, that corresponds to the 1st, and 2nd order respectively. When using `muscl_order = 2`, `muscl_lim` must be defined. - `muscl_lim` specifies the slope limiter that is used in 2nd order MUSCL Reconstruction by an integer from 1 through 5. `muscl_lim = 1`, `2`, `3`, `4`, and `5` correspond to minmod, monotonized central, Van Albada, Van Leer, and SUPERBEE, respectively. - `int_comp` activates interface compression using THINC used in MUSCL Reconstruction, with control parameters (`ic_eps`, and `ic_beta`). - `riemann_solver` specifies the choice of the Riemann solver that is used in simulation by an integer from 1 through 4. `riemann_solver = 1`, `2`, and `3` correspond to HLL, HLLC, and Exact Riemann solver, respectively (\cite Toro13). `riemann_solver = 4` is only for MHD simulations. It resolves 5 of the full seven-wave structure of the MHD equations (\cite Miyoshi05). - `low_Mach` specifies the choice of the low Mach number correction scheme for the HLLC Riemann solver. `low_Mach = 0` is default value and does not apply any correction scheme. `low_Mach = 1` and `2` apply the anti-dissipation pressure correction method (\cite Chen22) and the improved velocity reconstruction method (\cite Thornber08). This feature requires `model_eqns = 2` or `3`. `low_Mach = 1` works for `riemann_solver = 1` and `2`, but `low_Mach = 2` only works for `riemann_solver = 2`. - `avg_state` specifies the choice of the method to compute averaged variables at the cell-boundaries from the left and the right states in the Riemann solver by an integer of 1 or 2. `avg_state = 1` and `2` correspond to Roe- and arithmetic averages, respectively. - `wave_speeds` specifies the choice of the method to compute the left, right, and middle wave speeds in the Riemann solver by an integer of 1 and 2. `wave_speeds = 1` and `2` correspond to the direct method (\cite Batten97), and indirect method that approximates the pressures and velocity (\cite Toro13), respectively. Build Risk The new BibTeX integration relies on CITE_BIB_FILES being correctly propagated via CMake substitution. Ensure @DOXYGEN_CITE_BIB_FILES@ expands to a Doxygen-acceptable value (formatting/quoting, list semantics) and that the \ref citelist target is actually produced in the generated docs. If the substitution results in extra quotes or incorrect separators, citations may silently fail to render. # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. CITE_BIB_FILES = @DOXYGEN_CITE_BIB_FILES@

[codeant-ai]

Nitpicks 🔍

🔒 No security issues identified

⚡ Recommended areas for review Unexpanded placeholder The added line uses the CMake/Configure placeholder @DOXYGEN_CITE_BIB_FILES@. Verify that this token is always replaced during configuration; if it remains unexpanded the generated Doxyfile may contain a literal '@DOXYGEN_CITE_BIB_FILES@' which Doxygen won't interpret as intended. BibTeX dependency Populating CITE_BIB_FILES implies use of BibTeX during LaTeX builds (and requires bibtex/perl when LATEX_BIB_STYLE is used). Confirm CI/builds and optional docs generation workflows have the required tools, or make this feature optional/fallback when tools are absent. Path / formatting robustness CITE_BIB_FILES expects one or more .bib files. Ensure the substitution yields properly quoted/escaped paths (or documented format) to avoid issues when paths contain spaces or when multiple files are provided. Missing persistent identifiers Several preprints and tech reports are recorded only in the journal or title fields (e.g. arXiv preprints, NASA techreport). These entries lack standard persistent identifier fields (doi, eprint / archivePrefix, url) which reduces linkability from generated documentation and may break Doxygen's citation linking. Adding DOI / eprint / url fields improves reproducibility and reliability of citations. Preprint / future-year entries A few entries use future years (2024/2025) or are clearly preprints (e.g. Cisneros25, Wilfong25a, Cao24, Bryngelson19). These should be verified and normalized (use eprint/archivePrefix for arXiv, add note = {preprint} or howpublished for in-conference preprints) so readers and automated tools show correct status.

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[cubic-dev-ai]

No issues found across 9 files

Confidence score: 5/5

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

[Copilot]

Pull request overview

Adds a comprehensive “Equations” reference page to the MFC Doxygen documentation and switches documentation citations over to a BibTeX-driven workflow (via Doxygen’s \cite + CITE_BIB_FILES), addressing the need for clearer governing-equation/nondimensionalization guidance (Issue #318).

Changes:

• Introduces a new comprehensive equations reference page (@page equations) covering models, closures, and numerics.
• Adds a central BibTeX database and wires it into the Doxygen build (CITE_BIB_FILES) via CMake configuration.
• Updates existing documentation pages to use \cite ... and simplifies the References page to point to Doxygen’s generated bibliography.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/references.bib	Adds a centralized BibTeX bibliography for Doxygen citations.
docs/documentation/equations.md	New comprehensive equations reference page with inline citations and source cross-references.
docs/documentation/readme.md	Adds navigation entry to the new Equations page.
docs/documentation/references.md	Replaces hardcoded references list with BibTeX/Doxygen bibliography link.
docs/documentation/visualization.md	Converts reference links to \cite usage.
docs/documentation/case.md	Converts multiple reference links to \cite usage throughout.
docs/Doxyfile.in	Enables bibliography input via CITE_BIB_FILES = @DOXYGEN_CITE_BIB_FILES@.
CMakeLists.txt	Defines DOXYGEN_CITE_BIB_FILES for Doxygen config generation.
.typos.toml	Excludes the new docs/references.bib from typos checking.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/documentation/equations.md`:
- Around line 668-676: There are markdownlint emphasis violations: remove stray
spaces inside emphasis markers and use a consistent emphasis style (or code
formatting) in this section; update the "HLLD (`riemann_solver = 3`, MHD only)"
heading and nearby inline text so code/config (riemann_solver = 3) uses
backticks, citations like Miyoshi05 are not wrapped with * or _, and any
emphasized words use a single consistent marker (prefer asterisks) or plain
text; ensure the surrounding math blocks for S_M, S_L^*, S_R^* remain untouched
and only adjust the surrounding markdown emphasis/citation formatting to
eliminate MD037/MD049 warnings.
- Around line 501-502: Update the HLLD Riemann solver index in the
documentation: change the referenced value for riemann_solver from 3 to 4 in the
sentence describing HLLD, so it matches the implementation where riemann_solver
= 4 corresponds to HLLD (and riemann_solver = 3 is the Exact solver); ensure the
text now reads that HLLD uses riemann_solver = 4 and leave the rest of the
GLM/hyper_cleaning description unchanged.

[sbryngelson]

/improve

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 44.03%. Comparing base (0ba6c02) to head (398f9f3).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1136   +/-   ##
=======================================
  Coverage   44.03%   44.03%           
=======================================
  Files          70       70           
  Lines       20649    20649           
  Branches     2053     2054    +1     
=======================================
  Hits         9093     9093           
  Misses      10368    10368           
  Partials     1188     1188           

☔ 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.

[cubic-dev-ai]

2 issues found across 7 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.


<file name="docs/postprocess_citations.py">

<violation number="1" location="docs/postprocess_citations.py:27">
P2: check_bare_citations also looks up citation keys without normalizing case, leading to false ‘missing author prefix’ errors for mixed‑case BibTeX keys.</violation>

<violation number="2" location="docs/postprocess_citations.py:108">
P2: Citation keys are stored lowercase, but process_html looks them up with the original case, so mixed‑case BibTeX keys won’t be found and author prefixes won’t be inserted.</violation>
</file>

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

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@docs/documentation/equations.md`:
- Around line 640-644: Replace the incorrect parameter name
"interface_compression > 0" with the actual THINC toggle "int_comp" (or
"int_comp == true") and mention the real control parameters "ic_beta" (controls
compression steepness) and "ic_eps" (small threshold used by the scheme) in the
surrounding text; leave the formula unchanged but update the sentence to read
something like: "THINC interface compression (int_comp enabled): applies ...
where ... and ic_beta controls compression steepness (with ic_eps used as the
numerical threshold)", and ensure the doc references the logical flag int_comp
and parameters ic_beta and ic_eps instead of interface_compression.
- Around line 818-834: The low_Mach labels are reversed in this section: update
the text so low_Mach = 1 corresponds to Chen's pressure anti-dissipation
correction (APC, p_d, APC_{p\mathbf{u}}, APC_{pE}, pcorr) and low_Mach = 2
corresponds to Thornber's velocity reconstruction (z and u'_L/u'_R formulas).
Concretely, swap the two section headings, their descriptive sentences, and the
adjacent equation blocks so that the Chen/APC block is labeled low_Mach = 1 and
the Thornber/velocity-reconstruction block is labeled low_Mach = 2 to match the
implementation that checks low_Mach == 1 for pressure correction and low_Mach ==
2 for velocity modification.

In `@docs/postprocess_citations.py`:
- Line 23: The type annotation for the local variable `entries` is incorrect: it
is declared as dict[str, tuple[str, int]] but actually stores 3-element tuples
(surname, count, second_surname) matching the function's declared return type;
update the annotation to dict[str, tuple[str, int, str]] (or a named
tuple/TypedDict if preferred) so `entries`'s type matches the actual stored
tuple shape and the function return annotation.

In `@toolchain/mfc/params/definitions.py`:
- Line 784: Remove the spurious empty dependency entry for the "mhd" parameter
in the DEPENDENCIES mapping: delete the `"mhd": {}` key so
DEPENDENCIES.get("mhd") returns None like other parameters; this change targets
the DEPENDENCIES dict (the entry named "mhd") to avoid triggering truthy checks
in validate.py, json_schema_gen.py, and docs_gen.py.

🧹 Nitpick comments (4)

docs/references.bib (1)

653-661: Inconsistent citation key format: Xu2019 uses 4-digit year.

All other entries in this file use 2-digit year suffixes (e.g., Allaire02, Keller80, Cao24). This key uses 4 digits. Consider renaming to Xu19 for consistency. Ensure any \cite Xu2019 references in docs are updated accordingly.

toolchain/mfc/lint_docs.py (1)

87-135: PARAM_RE only matches lowercase-starting identifiers — uppercase MFC params won't be validated.

PARAM_RE requires the first character to be [a-z_], so parameters like Bx0, Re_inv, R0ref, Ca, Web, G, E_wrt referenced in equations.md will never be captured or validated. This is presumably intentional to reduce false positives, but it means a meaningful subset of parameter references won't be checked.

docs/documentation/case.md (1)

819-822: Minor: Inconsistent parenthetical style around \cite.

Some citations use parentheses, e.g., (\cite Preston07) on lines 819 and 866, while others use bare \cite Thornber08. This doesn't affect Doxygen rendering but is a style inconsistency. Consider standardizing to one style across the document.

docs/postprocess_citations.py (1)

155-162: Unused variable count (static analysis).

The unpacked count on line 157 is never used in the has_prefix logic. Prefix with _ to signal intent.

Suggested fix

-            surname, count, second_surname = authors[key]
+            surname, _count, second_surname = authors[key]

[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

[qodo-code-review]

Suggestion: Normalize the citation key to lowercase before looking it up in the authors dictionary to ensure a case-insensitive match. [possible issue, importance: 8]

Suggested change

	def replace_cite(match: re.Match) -> str:
	key = match.group(1)
	full_link = match.group(0)
	info = authors.get(key)
	if not info:
	return full_link
	def replace_cite(match: re.Match) -> str:
	key = match.group(1).lower()
	full_link = match.group(0)
	info = authors.get(key)
	if not info:
	return full_link

[codeant-ai]

Suggestion: Store bibliography entries under their original keys instead of lowercasing them, so lookups using citation keys from the HTML (which preserve case) succeed. [custom_rule]

Severity Level: Minor ⚠️

Suggested change

	entries[key.lower()] = (surname, count, second_surname)
	entries[key] = (surname, count, second_surname)

Why it matters? ⭐

The current implementation lowercases bib keys when building the map but later looks up keys using the exact key captured from the HTML (authors.get(key) / authors[key]). That mismatch can cause lookups to fail and leave citations unprocessed. The proposed change directly fixes this correctness bug (matches storage to lookup) — addressing the repo guideline to prioritize correctness over style. An alternative would be normalizing lookups to key.lower(), but storing the original key is a minimal, correct fix here.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** docs/postprocess_citations.py
**Line:** 52:52
**Comment:**
	*Custom Rule: Store bibliography entries under their original keys instead of lowercasing them, so lookups using citation keys from the HTML (which preserve case) succeed.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

👍 | 👎

[codeant-ai]

Suggestion: The BibTeX keys are stored in lowercase in the authors dictionary, but the HTML citation keys come from Doxygen with their original case, so using authors.get(key) and authors[key] makes the lookup case-sensitive and will fail for any key containing uppercase letters, causing citations to be left unprocessed and incorrectly reported as missing; normalize the Doxygen keys to lowercase before lookup to match how they were stored. [logic error]

Severity Level: Critical 🚨

- ❌ Documentation build fails when citations use mixed-case keys.
- ⚠️ Affected citations lack author prefixes in HTML.
- ⚠️ CI docs job may fail due to citation checks.

Suggested change

	if not info:
	info = authors.get(key.lower())

Steps of Reproduction ✅

1. Ensure `docs/references.bib` contains at least one BibTeX entry whose key has uppercase
letters, e.g. `@article{Allaire1992,...}`, which is parsed by `parse_bib_authors()` in
`docs/postprocess_citations.py:15-55` and stored in the `authors` dict under the
lowercased key `"allaire1992"`.

2. Add a corresponding citation `\cite{Allaire1992}` in a documented file such as
`docs/documentation/equations.md`, then run the normal Doxygen documentation build so the
generated HTML (e.g. `docs/html/equations.html`) contains links of the form `<a class="el"
href="citelist.html#CITEREF_Allaire1992">[1]</a>`, matching `CITE_RE` in
`docs/postprocess_citations.py:93-96`.

3. Run `python3 docs/postprocess_citations.py docs/html`, which executes `main()` at
`docs/postprocess_citations.py:168-212`; this calls `parse_bib_authors()` to build
`authors` and then invokes `process_html()` for each HTML file in `docs/html` at lines
`191-199`.

4. Inside `process_html.replace_cite()` (`docs/postprocess_citations.py:108-132`), `key`
is `"Allaire1992"` while `authors` only contains `"allaire1992"`, so `authors.get(key)`
returns `None`, the citation link is returned unchanged (no author prefix added), and
`check_bare_citations()` later treats this as a bare citation, causing incorrect
formatting and potentially a failing docs build despite a valid BibTeX entry.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** docs/postprocess_citations.py
**Line:** 112:112
**Comment:**
	*Logic Error: The BibTeX keys are stored in lowercase in the `authors` dictionary, but the HTML citation keys come from Doxygen with their original case, so using `authors.get(key)` and `authors[key]` makes the lookup case-sensitive and will fail for any key containing uppercase letters, causing citations to be left unprocessed and incorrectly reported as missing; normalize the Doxygen keys to lowercase before lookup to match how they were stored.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

👍 | 👎

[codeant-ai]

Suggestion: As with process_html, check_bare_citations compares and indexes the authors dictionary using citation keys in their original case even though the dictionary keys were lowercased when parsing the BibTeX file, so entries with uppercase letters are treated as if they have no bib entry and the script will erroneously fail with "no bib entry" or missing author prefix errors; lowercasing the citation key before lookup fixes this. [logic error]

Severity Level: Critical 🚨

- ❌ Script misreports valid citations as missing bibliography entries.
- ⚠️ Causes nonzero exit, breaking automated documentation pipelines.

Suggested change

	bare.append(f" {html_file.name}: [{m.group(2)}] (CITEREF_{key}) — no bib entry")
	continue
	# Check if an author name precedes the link
	before = text[max(0, m.start() - 60):m.start()].rstrip()
	surname, _count, second_surname = authors[key]
	has_prefix = (
	key_lc = key.lower()
	if key_lc not in authors:
	bare.append(f" {html_file.name}: [{m.group(2)}] (CITEREF_{key}) — no bib entry")
	continue
	# Check if an author name precedes the link
	before = text[max(0, m.start() - 60):m.start()].rstrip()
	surname, _count, second_surname = authors[key_lc]

Steps of Reproduction ✅

1. Use the same setup as in the previous suggestion: have `docs/references.bib` contain a
BibTeX entry with a mixed-case key like `@article{Allaire1992,...}`, and ensure
Doxygen-generated HTML under `docs/html` has links such as `<a class="el"
href="citelist.html#CITEREF_Allaire1992">[1]</a>` that match `CITE_RE` in
`docs/postprocess_citations.py:93-96`.

2. Run `python3 docs/postprocess_citations.py docs/html`, executing `main()` at
`docs/postprocess_citations.py:168-212`, which first builds the `authors` dict with
lowercased keys in `parse_bib_authors()` (lines 15-55) and then, after optional HTML
rewriting, calls `check_bare_citations(html_dir, authors)` at lines `199-205`.

3. Inside `check_bare_citations()` (`docs/postprocess_citations.py:141-165`), for each
citation link the loop sets `key = m.group(1)` to `"Allaire1992"` while `authors` only
contains `"allaire1992"`, so the condition `if key not in authors:` is true and the code
appends a `"no bib entry"` warning even though a matching BibTeX entry exists.

4. After scanning all HTML files, `main()` sees the non-empty `bare` list, prints "Bare
citations found (missing author prefix):" and the spurious `"no bib entry"` lines at
`docs/postprocess_citations.py:202-206`, then calls `sys.exit(1)`, causing the
documentation build or CI docs target to fail incorrectly.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** docs/postprocess_citations.py
**Line:** 153:158
**Comment:**
	*Logic Error: As with `process_html`, `check_bare_citations` compares and indexes the `authors` dictionary using citation keys in their original case even though the dictionary keys were lowercased when parsing the BibTeX file, so entries with uppercase letters are treated as if they have no bib entry and the script will erroneously fail with "no bib entry" or missing author prefix errors; lowercasing the citation key before lookup fixes this.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

👍 | 👎

[codeant-ai]

CodeAnt AI Incremental review completed.