Skip to content

case.md documents riemann_solver values the validator rejects, and omits one it requires #1782

Description

@sbryngelson

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 truthtoolchain/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

  1. 3 (Exact) is documented in both the table and the prose, but case_validator.py rejects it.
  2. 5 (Lax-Friedrichs) is accepted and has a registered name (lax_friedrichs), but appears nowhere in
    case.md.
  3. "an integer from 1 through 4" is wrong in both directions.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions