hpfracc.algorithms — architecture, dependencies, and maintenance

This note complements CONTRIBUTING.md (numerical integrity, canonical engines), the Development Guide, SPECIAL_ARCHITECTURE.md, VALIDATION_ARCHITECTURE.md, and 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).

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]"):

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:

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 — canonical engines, numerical integrity, CI vs full pytest.

• README.md — “Failure over Falsity” policy.

• ANALYTICS_ARCHITECTURE.md — usage/performance/error/workflow telemetry package (hpfracc.analytics).

• BENCHMARKS_ARCHITECTURE.md — numerical vs ML vs validation benchmark entry points.

• SPECIAL_ARCHITECTURE.md — Γ, Β, binomial, Mittag–Leffler package (hpfracc.special).

• UTILS_ARCHITECTURE.md — error analysis, memory/cache, plotting (hpfracc.utils).

• VALIDATION_ARCHITECTURE.md — analytical solutions, convergence testing, validation benchmarks (hpfracc.validation).

• SOLVERS_ARCHITECTURE.md — fractional ODE/PDE/SDE time-stepping (hpfracc.solvers).

• Sphinx development toctree: index.rst (this file is picked up via *.md glob).