docs/documentation/case.md documents a set of riemann_solver values that does not match what the
toolchain accepts. A user following the docs can pick a value that is rejected, and cannot discover a
value that is required by several of the repo's own benchmark cases.
Source of truth — toolchain/mfc/params/definitions.py:
"riemann_solver": {
"choices": [1, 2, 4, 5],
"value_labels": {1: "HLL", 2: "HLLC", 4: "HLLD", 5: "Lax-Friedrichs"},
"names": {"hll": 1, "hllc": 2, "hlld": 4, "lax_friedrichs": 5},
},
and toolchain/mfc/case_validator.py:
riemann_solver must be 1 (HLL), 2 (HLLC), 4 (HLLD), or 5 (Lax-Friedrichs)
What the docs say (docs/documentation/case.md, on master):
- Table row:
Riemann solver algorithm: [1] HLL*; [2] HLLC; [3] Exact*; [4] HLLD (only for MHD)
- Prose: "specifies the choice of the Riemann solver ... by an integer from 1 through 4"
- Prose: "
riemann_solver = 1, 2, and 3 correspond to HLL, HLLC, and Exact Riemann solver"
Concrete mismatches
3 (Exact) is documented in both the table and the prose, but case_validator.py rejects it.
5 (Lax-Friedrichs) is accepted and has a registered name (lax_friedrichs), but appears nowhere in
case.md.
- "an integer from 1 through 4" is wrong in both directions.
case.md advertises named enum values ("Enumerated parameters accept named values as well as integer
codes"), so lax_friedrichs is a usable name that is not documented anywhere.
Why it matters beyond tidiness: riemann_solver = 5 is what the AMR performance benchmarks in this
repo's tooling actually run, so the setting used for published comparisons is currently undocumented,
while a documented setting fails validation.
Suggested fix: regenerate that table row and the prose from definitions.py's value_labels so the
two cannot drift, or at minimum correct the row to [1] HLL; [2] HLLC; [4] HLLD; [5] Lax-Friedrichs and
drop the "1 through 4" phrasing. Whether 3 (Exact) should be restored in code or removed from the docs
is a maintainer call — the two options are not equivalent and I did not assume one.
docs/documentation/case.mddocuments a set ofriemann_solvervalues that does not match what thetoolchain accepts. A user following the docs can pick a value that is rejected, and cannot discover a
value that is required by several of the repo's own benchmark cases.
Source of truth —
toolchain/mfc/params/definitions.py:and
toolchain/mfc/case_validator.py:What the docs say (
docs/documentation/case.md, on master):Riemann solver algorithm: [1] HLL*; [2] HLLC; [3] Exact*; [4] HLLD (only for MHD)riemann_solver = 1,2, and3correspond to HLL, HLLC, and Exact Riemann solver"Concrete mismatches
3(Exact) is documented in both the table and the prose, butcase_validator.pyrejects it.5(Lax-Friedrichs) is accepted and has a registered name (lax_friedrichs), but appears nowhere incase.md.case.mdadvertises named enum values ("Enumerated parameters accept named values as well as integercodes"), so
lax_friedrichsis a usable name that is not documented anywhere.Why it matters beyond tidiness:
riemann_solver = 5is what the AMR performance benchmarks in thisrepo's tooling actually run, so the setting used for published comparisons is currently undocumented,
while a documented setting fails validation.
Suggested fix: regenerate that table row and the prose from
definitions.py'svalue_labelsso thetwo cannot drift, or at minimum correct the row to
[1] HLL; [2] HLLC; [4] HLLD; [5] Lax-Friedrichsanddrop the "1 through 4" phrasing. Whether
3(Exact) should be restored in code or removed from the docsis a maintainer call — the two options are not equivalent and I did not assume one.