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

This note complements [CONTRIBUTING.md](https://github.com/dave2k77/hpfracc/blob/main/CONTRIBUTING.md) (numerical integrity, canonical engines), the [Development Guide](DEVELOPMENT_GUIDE.md), [SPECIAL_ARCHITECTURE.md](SPECIAL_ARCHITECTURE.md), [VALIDATION_ARCHITECTURE.md](VALIDATION_ARCHITECTURE.md), and [SOLVERS_ARCHITECTURE.md](SOLVERS_ARCHITECTURE.md). It describes how the **algorithms** package is layered, how it talks to **core** / **special**, known risks, and how to refresh **coverage** numbers.

---

## 1. Design goals

1. **Single numerical path** for classical fractional **derivatives** (Riemann–Liouville, Caputo, Grünwald–Letnikov): `algorithms/derivatives.py` + `algorithms/impls/*`.
2. **Explicit** behaviour under numerical stress: warnings, NaN where appropriate, optional strict mode (see README “Failure over Falsity”).
3. **Legacy grid integrals** (`integral_methods.py`) remain a supported **alternate API**, clearly documented vs `hpfracc.core.integrals`.
4. **Research extensions** (advanced / novel / special operators) live in larger modules without diluting the canonical three-operator path.

---

## 2. Layered layout (mental model)

| Layer | Modules | Responsibility |
|-------|---------|------------------|
| **A — Canonical engines** | `derivatives.py`, `dispatch.py`, `impls/numpy_backend.py`, `impls/jax_backend.py`, `impls/cuda_backend.py` | Backend dispatch, finite checks, RL/Caputo/GL kernels. |
| **B — Compatibility shims** | `optimized_methods.py` | `Optimized*` = RL/Caputo/GL engine aliases; deprecated `GPU*` shims and `gpu_optimized_*` helpers live here. Re-export `FractionalOperator` for legacy imports. |
| **C — Legacy grid integrals** | `integral_methods.py` | FFT / direct / adaptive RL & Caputo integrals on uniform samples; delegates to `core.integrals` where documented. |
| **D — Extended operators** | `advanced_methods.py`, `novel_derivatives.py`, `fractional_operator_methods.py` | Weyl, Marchaud, Hadamard, Reiz–Feller, Adomian; CF/AB; Laplacian, FrFT, Z/Mellin, etc. (legacy import path ``algorithms.special_methods`` shim). |
| **E — Legacy base** | `base.py` | `FractionalOperator.compute` (JAX try / generic warn); subclassed by `UnifiedFractionalOperator`, which **replaces** `compute` for the three engines. |

---

## 3. Dependency diagram (read-only edges)

Intended import direction: **core.definitions** and **special** are foundations; **fractional_implementations** consumes algorithms; algorithms **must not** import `core.derivatives` at module top level (avoid cycles).

```text
flowchart TB
  subgraph foundations["Foundations"]
    DEF["core.definitions"]
    SPEC["special (gamma, binomial, …)"]
  end

  subgraph algorithms_pkg["hpfracc.algorithms"]
    BASE["base.FractionalOperator"]
    DISP["dispatch.BackendDispatcher"]
    IMPL["impls: numpy / jax / cuda"]
    DER["derivatives.UnifiedFractionalOperator\nRiemannLiouville, Caputo, GrunwaldLetnikov"]
    OPT["optimized_methods\n(engines + GPU-named shims)"]
    INT["integral_methods"]
    ADV["advanced_methods"]
    NOV["novel_derivatives"]
    SPM["fractional_operator_methods"]
  end

  subgraph core_pkg["hpfracc.core (consumers)"]
    FI["fractional_implementations"]
    CI["core.integrals"]
  end

  DEF --> DER
  DEF --> INT
  DEF --> ADV
  DEF --> NOV
  DEF --> SPM
  SPEC --> IMPL
  SPEC --> INT
  SPEC --> ADV
  SPEC --> SPM
  BASE --> DER
  DISP --> DER
  IMPL --> DER
  DER --> OPT
  INT --> CI
  FI --> DER
  FI --> INT
  FI --> ADV
  FI --> NOV
  FI --> SPM
```

---

## 4. Naming: engines vs parallel advanced operators

- In **`optimized_methods.py`**: `OptimizedRiemannLiouville` (etc.) are **aliases** of the unified RL/Caputo/GL classes in `derivatives.py` (same numerical engines, convenience names).
- In **`advanced_methods.py`**: canonical parallel subclasses are **`ParallelWeylDerivative`**, **`ParallelMarchaudDerivative`**, and siblings. Deprecated aliases `OptimizedWeylDerivative = ParallelWeylDerivative` (etc.) remain for old code; they are **not** the RL/Caputo `Optimized*` family. The `optimized_*_derivative` callables emit **`DeprecationWarning`** and delegate to **`parallel_*_derivative`**.

When refactoring or searching, qualify: **“Optimized* engines (`optimized_methods`)”** vs **“Parallel* / legacy Optimized* advanced (`advanced_methods`)”**.

---

## 5. Risk register and mitigations

| Risk | Mitigation (status) |
|------|---------------------|
| Legacy **`FractionalOperator.compute`** weaker than unified policy | Documented in `base.py`; engines use `derivatives.compute`. Re-export `FractionalOperator` from `optimized_methods` for old imports. |
| **Deprecated `GPU*` import surface** | Centralized in `optimized_methods.py` with `DeprecationWarning`; migrate to `derivatives.*` with `backend=`. |
| **`integral_methods` FFT** used circular convolution historically | **Fixed**: linear `scipy.signal.fftconvolve`; adaptive tiered `UserWarning` / `RuntimeWarning`. |
| **`fractional_operator_methods`** (legacy ``special_methods``) | Canonical module for Laplacian / FrFT / Z–Mellin-style **algorithm** tooling, distinct from **`hpfracc.special`** (Γ, binomial, Mittag–Leffler). Prefer **targeted tests** when changing it. |
| **Coverage uneven** on D-layer | Use commands below before large edits; add tests with the same PR when behaviour changes. |

---

## 6. Refreshing coverage (algorithms-focused)

From the repo root, with dev extras installed (`pip install -e ".[dev]"`):

```bash
python -m pytest tests/test_algorithms/ \
  --cov=hpfracc \
  --cov-report=term-missing:skip-covered \
  -q
```

Use **`--cov=hpfracc`**, not only `hpfracc.algorithms`: on some Windows/JAX/pytest-cov combinations, restricting coverage to the subpackage can trigger a **partially initialized `jax`** error during collection (import tracing order). Measuring the whole package and **reading the `hpfracc\algorithms\...` rows** avoids that while still exercising the algorithms test tree.

Optional HTML report:

```bash
python -m pytest tests/test_algorithms/ --cov=hpfracc --cov-report=html:htmlcov_algorithms -q
```

**Note:** CI’s main workflow often runs a **slice** of tests, not all of `tests/test_algorithms/`; a green PR job does not replace a local `--cov` pass before risky algorithm changes.

### Representative snapshot (2026-04-14, `tests/test_algorithms/`, `--cov=hpfracc`)

| Module | Stmts | Miss | Cover |
|--------|------:|-----:|------:|
| `algorithms/__init__.py` | 5 | 0 | 100% |
| `algorithms/advanced_methods.py` | 361 | 127 | 65% |
| `algorithms/base.py` | 70 | 28 | 60% |
| `algorithms/derivatives.py` | 115 | 43 | 63% |
| `algorithms/dispatch.py` | 25 | 10 | 60% |
| `algorithms/impls/cuda_backend.py` | 58 | 48 | 17% |
| `algorithms/impls/jax_backend.py` | 79 | 8 | 90% |
| `algorithms/impls/numpy_backend.py` | 66 | 58 | 12% |
| `algorithms/integral_methods.py` | 187 | 23 | 88% |
| `algorithms/novel_derivatives.py` | 189 | 54 | 71% |
| `algorithms/optimized_methods.py` | — | — | includes deprecated `GPU*` shims† |
| `algorithms/special_methods.py` | 658 | 386 | 41% |

**Reading:** `integral_methods` and `optimized_methods` (including deprecated GPU-named shims) are well hit by this folder. **`numpy_backend`** stays low when JAX wins `backend="auto"` on typical sizes; **`cuda_backend`** stays low without GPU. **`fractional_operator_methods`** has moderate line coverage here; add tests when you change behaviour, without assuming a future file split.

† **`optimized_methods.py` row:** refresh stmt/miss/% with `pytest tests/test_algorithms/ --cov=hpfracc` (whole package). Restricting `--cov` to `hpfracc.algorithms` only can trigger a **partially initialized `jax`** error on some Windows/pytest-cov import orders.

---

## 7. Related documentation

- [CONTRIBUTING.md](https://github.com/dave2k77/hpfracc/blob/main/CONTRIBUTING.md) — canonical engines, numerical integrity, CI vs full pytest.
- [README.md](https://github.com/dave2k77/hpfracc/blob/main/README.md) — “Failure over Falsity” policy.
- [ANALYTICS_ARCHITECTURE.md](ANALYTICS_ARCHITECTURE.md) — usage/performance/error/workflow telemetry package (`hpfracc.analytics`).
- [BENCHMARKS_ARCHITECTURE.md](BENCHMARKS_ARCHITECTURE.md) — numerical vs ML vs validation benchmark entry points.
- [SPECIAL_ARCHITECTURE.md](SPECIAL_ARCHITECTURE.md) — Γ, Β, binomial, Mittag–Leffler package (`hpfracc.special`).
- [UTILS_ARCHITECTURE.md](UTILS_ARCHITECTURE.md) — error analysis, memory/cache, plotting (`hpfracc.utils`).
- [VALIDATION_ARCHITECTURE.md](VALIDATION_ARCHITECTURE.md) — analytical solutions, convergence testing, validation benchmarks (`hpfracc.validation`).
- [SOLVERS_ARCHITECTURE.md](SOLVERS_ARCHITECTURE.md) — fractional ODE/PDE/SDE time-stepping (`hpfracc.solvers`).
- Sphinx development toctree: [index.rst](index.rst) (this file is picked up via `*.md` glob).