# `hpfracc.validation` — architecture, dependencies, and maintenance

This note complements [CONTRIBUTING.md](https://github.com/dave2k77/hpfracc/blob/main/CONTRIBUTING.md), [UTILS_ARCHITECTURE.md](UTILS_ARCHITECTURE.md), [BENCHMARKS_ARCHITECTURE.md](BENCHMARKS_ARCHITECTURE.md), and [SOLVERS_ARCHITECTURE.md](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

```text
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](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`**.

```bash
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.

---

## 7. Related documentation

- [UTILS_ARCHITECTURE.md](UTILS_ARCHITECTURE.md)
- [BENCHMARKS_ARCHITECTURE.md](BENCHMARKS_ARCHITECTURE.md)
- [SOLVERS_ARCHITECTURE.md](SOLVERS_ARCHITECTURE.md)
- [ALGORITHMS_ARCHITECTURE.md](ALGORITHMS_ARCHITECTURE.md)
- [SPECIAL_ARCHITECTURE.md](SPECIAL_ARCHITECTURE.md)