hpfracc.validation โ€” architecture, dependencies, and maintenance๏ƒ

This note complements CONTRIBUTING.md, UTILS_ARCHITECTURE.md, BENCHMARKS_ARCHITECTURE.md, and SOLVERS_ARCHITECTURE.md. It maps validation modules, naming collisions with other packages, and tests / scripts.

1. Design goals๏ƒ

  1. Reference checks for numerical methods: known analytical expressions, convergence studies over grid refinement, and benchmark suites (accuracy / performance).

  2. No import cycles into core engines: validation may use hpfracc.utils (ErrorAnalyzer); it does not need to be imported by algorithms or core at startup.

  3. Explicit disambiguation from similarly named types elsewhere in the repo (see ยง4).

2. Module layout๏ƒ

File

Responsibility

analytical_solutions.py

AnalyticalSolutions and subclasses (PowerFunctionSolutions, ExponentialSolutions, TrigonometricSolutions), helpers get_analytical_solution, validate_against_analytical. Uses SciPy gamma where closed forms need it.

convergence_tests.py

OrderOfAccuracy, ConvergenceTester (per-norm convergence runs), ValidationConvergenceAnalyzer (multi-case studies, optimal grid estimate, order checks; deprecated alias ConvergenceAnalyzer), run_convergence_study, run_method_convergence_test, module-level estimate_convergence_rate. Imports ErrorAnalyzer from hpfracc.utils.error_analysis.

method_benchmarks.py

BenchmarkSuite, PerformanceBenchmark, AccuracyBenchmark, BenchmarkResult, run_benchmarks, compare_methods, generate_benchmark_report. Uses NumPy, psutil, time โ€” separate from hpfracc.benchmarks (see ยง4).

__init__.py

Re-exports the public surface listed in __all__.

3. Dependency edges๏ƒ

flowchart LR
  VAL["hpfracc.validation"]
  UTILS["hpfracc.utils.error_analysis"]
  VAL --> UTILS

  • convergence_tests โ†’ ..utils.error_analysis (ErrorAnalyzer for norms / errors).

  • analytical_solutions / method_benchmarks โ†’ standard scientific stack (NumPy, SciPy where used, psutil in benchmarks).

Intended: no validation โ†’ algorithms / core imports at module level (keeps optional validation off the critical import path for derivative engines).

4. Naming collisions (read carefully)๏ƒ

Name here

Also exists in

Relation

ValidationConvergenceAnalyzer (validation)

ConvergenceRateAnalyzer / deprecated ConvergenceAnalyzer (utils)

Different roles. Validation class orchestrates ConvergenceTester and method-vs-analytical studies. Utils ConvergenceRateAnalyzer fits generic error arrays and dict-style analyze_convergence. Prefer these names over the deprecated ConvergenceAnalyzer aliases.

validation.method_benchmarks (BenchmarkSuite, PerformanceBenchmark, โ€ฆ)

hpfracc.benchmarks (BenchmarkRunner, ML benchmarks, โ€ฆ)

Different modules. BENCHMARKS_ARCHITECTURE.md describes the split; validation code is for method comparison in validation workflows, not the numerical BenchmarkRunner nor ML torch benchmarks.

estimate_convergence_rate

Module function in convergence_tests vs helpers in utils.error_analysis

Signatures differ by design; do not assume interchangeability.

5. Entry points (scripts / tests)๏ƒ

  • scripts/run_validation_suite.py, scripts/run_comprehensive_validation.py โ€” orchestrate imports from hpfracc.validation.

  • Tests: tests/test_validation/, plus tests/test_validation.py and references in tests/test_additional_coverage.py.

python -m pytest tests/test_validation/ tests/test_validation.py -q

6. Risks and mitigations๏ƒ

Risk

Mitigation

Legacy ConvergenceAnalyzer name

Use ValidationConvergenceAnalyzer (validation) or ConvergenceRateAnalyzer (utils). Deprecated subclasses still emit DeprecationWarning.

Confusing โ€œbenchmarksโ€

Prefer from hpfracc.validation import BenchmarkSuite vs from hpfracc.benchmarks import BenchmarkRunner naming in docs and examples.

Heavy or flaky CI

Full validation suites may be slow; gate behind scripts or markers if you split CI later.

ConvergenceTester calling convention: test_convergence passes the grid as the first positional argument x to method_func / analytical_func. Entries named x are removed from test_params before **test_params is applied, so a pre-filled x in the dict does not collide with the positional grid. Other parameter names (e.g. a second positional requirement in a mock) are the callerโ€™s responsibility.