Validation

Validation infrastructure: running the official GOTM test cases, comparing output against Fortran reference NetCDF files, and rendering HTML reports.

Per-case execution and validation logic for pyGOTM validation.

pygotm.validation.runner.run_case(case_name, runs_dir, *, cases_root=None)

Run a compiled parity case, write NetCDF, return (path, elapsed_s).

Return type:

tuple[Path, float]

Parameters:

• case_name (str)

• runs_dir (Path)

• cases_root (Path | None)

pygotm.validation.runner.summary_case(result)

Return a lightweight case summary without per-variable result rows.

Return type:

CaseResult

Parameters:

result (CaseResult)

pygotm.validation.runner.strip_case_plots(result)

Return per-variable results without embedded Plotly HTML payloads.

Return type:

CaseResult

Parameters:

result (CaseResult)

pygotm.validation.runner.validate_case(case_name, runs_dir, *, skip_run=False, debug_turbulence=False, cases_root=None)

Run (optionally) and validate a single GOTM case.

Return type:

CaseResult

Parameters:

• case_name (str)

• runs_dir (Path)

• skip_run (bool)

• debug_turbulence (bool)

• cases_root (Path | None)

pygotm.validation.runner.validate_case_to_html(case_name, runs_dir, output_dir, *, generated_at, hardware, skip_run=False, debug_turbulence=False, cases_root=None)

Run or compare one case, write its HTML page, and return JSON-safe data.

Return type:

CaseResult

Parameters:

• case_name (str)

• runs_dir (Path)

• output_dir (Path)

• generated_at (str)

• hardware (dict[str, str])

• skip_run (bool)

• debug_turbulence (bool)

• cases_root (Path | None)

NetCDF comparison utilities for pyGOTM validation using Frechet distance.

class pygotm.validation.compare.VarResult(name, section, status, color, reference_at_worst, calculated_at_worst, d_raw, d_norm, plot_html, metric_mode='d_norm', score=None, peak_d_norm=None)

Bases: object

Per-variable result for Frechet validation.

Parameters:

• name (str)

• section (Literal['pygotm', 'pyfabm'])

• status (Literal['PASS', 'MARGINAL', 'DISCREPANT', 'BROKEN'])

• color (Literal['green', 'yellow', 'orange', 'red'])

• reference_at_worst (float)

• calculated_at_worst (float)

• d_raw (float)

• d_norm (float)

• plot_html (str | None)

• metric_mode (Literal['d_norm', 'd_rel'])

• score (float | None)

• peak_d_norm (float | None)

name: str

section: Literal['pygotm', 'pyfabm']

status: Literal['PASS', 'MARGINAL', 'DISCREPANT', 'BROKEN']

color: Literal['green', 'yellow', 'orange', 'red']

reference_at_worst: float

calculated_at_worst: float

d_raw: float

d_norm: float

plot_html: str | None

metric_mode: Literal['d_norm', 'd_rel'] = 'd_norm'

score: float | None = None

peak_d_norm: float | None = None

exception pygotm.validation.compare.ValidationError

Bases: Exception

Raised for unrecoverable comparison failures.

pygotm.validation.compare.compare_nc(py_path, ref_path, case_name, config=FrechetConfig(pass_tol=0.01, marginal_tol=0.05, discrepant_tol=0.2, frechet_abs_tol=1e-12, frechet_rel_tol=1e-06, frechet_k=200, robust=False, q_low=0.1, q_high=99.9, pyfabm_robust=True, pyfabm_q_low=0.1, pyfabm_q_high=99.9, peak_frechet_k=400, switch_oom=2.0, eps_floor=1e-12, default_magnitude_floor=1e-06))

Compare py_path against ref_path using Frechet distance.

Return type:

list[VarResult]

Parameters:

• py_path (Path)

• ref_path (Path)

• case_name (str)

• config (FrechetConfig)

Reference-case discovery and NetCDF opening helpers for validation.

class pygotm.validation.reference.ValidationCase(name, directory, yaml_path, reference_path)

Bases: object

Resolved metadata for one GOTM reference case and YAML input file.

Parameters:

• name (str)

• directory (Path)

• yaml_path (Path)

• reference_path (Path)

name: str

directory: Path

yaml_path: Path

reference_path: Path

property yaml_base: str

Base name of the selected GOTM YAML input file.

property task_name: str

Dask task name for this case/input pair.

property run_name: str

Validation output name for this case/input pair.

pygotm.validation.reference.discover_reference_cases(*, cases_root=None)

Resolve all declared reference cases in canonical order.

Return type:

tuple[ValidationCase, ...]

Parameters:

cases_root (Path | None)

pygotm.validation.reference.numeric_variable_names(dataset)

Return numeric data variables in dataset order.

Return type:

tuple[str, ...]

Parameters:

dataset (Dataset)

pygotm.validation.reference.open_reference_dataset(case)

Open the Fortran reference NetCDF for case.

Return type:

Dataset

Parameters:

case (ValidationCase)

pygotm.validation.reference.open_validation_dataset(path)

Open a validation NetCDF with the same backend fallback as references.

Return type:

Dataset

Parameters:

path (Path)

pygotm.validation.reference.resolve_reference_case(case_name, *, yaml_file=None, cases_root=None)

Resolve a named reference case to its YAML and Fortran NetCDF paths.

Return type:

ValidationCase

Parameters:

• case_name (str)

• yaml_file (str | Path | None)

• cases_root (Path | None)

Render validation HTML reports directly from existing NetCDF outputs.

Usage

python -m pygotm.validation.render_report python -m pygotm.validation.render_report –cases couette,channel python -m pygotm.validation.render_report –all –workers 4 python -m pygotm.validation.render_report –report-dir validation/report