Skip to content

Type the two error conventions crossing the hybrid-pipeline boundary#403

Merged
LegrandNico merged 2 commits into
masterfrom
feat/error-conventions
Jul 9, 2026
Merged

Type the two error conventions crossing the hybrid-pipeline boundary#403
LegrandNico merged 2 commits into
masterfrom
feat/error-conventions

Conversation

@LegrandNico

@LegrandNico LegrandNico commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

In pyhgf's "hybrid" / mixed pipelines, you can chain together two kinds of building blocks:

  • Standard deep-learning parts (like a GELU activation or layer-norm) that pass errors around the way PyTorch/TensorFlow/JAX do, the "gradient" convention, where a positive error means "the output was too high."
  • PyHGF learning parts that use the framework's native belief-updating math, the "prediction error" convention, where a positive error means "the observation was higher than the prediction."
    These two conventions are exact negatives of each other. If you accidentally mix them up the code runs fine, but training silently diverges. That's a nasty class of bug: invisible, and only detectable by noticing the model won't learn.

This PR makes this sign convention explicit and self-documenting so those bugs are caught or avoided, without changing any runtime behavior:

DescentError (gradient-like: positive = output too high) and ObservedMinusPredicted (PyHGF's prediction error: positive = observation exceeded prediction) are now distinct annotated types, with validate_error_convention as a runtime sanity check. The hybrid-pipeline docstrings spell out where the single descent ↔ observed-minus-predicted conversion happens (the executor's backward pass for DeepNetworkAdapter), and EquinoxAdapter.backward_fn's signature declares the convention it must respect. A missing negation at this boundary trains silently in the wrong direction; the types make that mistake visible.

@LegrandNico LegrandNico force-pushed the feat/deep-network-declarative-api branch from d6713da to 291396b Compare July 8, 2026 21:51
@LegrandNico LegrandNico force-pushed the feat/error-conventions branch from aa62ab2 to 2fa62cc Compare July 8, 2026 21:51
@LegrandNico LegrandNico force-pushed the feat/deep-network-declarative-api branch 2 times, most recently from 96f6501 to 91237d2 Compare July 8, 2026 23:01
Base automatically changed from feat/deep-network-declarative-api to master July 8, 2026 23:06
@LegrandNico LegrandNico force-pushed the feat/error-conventions branch from 2fa62cc to 99da34b Compare July 9, 2026 19:19
@codecov

codecov Bot commented Jul 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
pyhgf/model/__init__.py 87.50% <100.00%> (+0.83%) ⬆️
pyhgf/model/error_types.py 100.00% <100.00%> (ø)
pyhgf/model/hybrid.py 86.90% <100.00%> (+0.15%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@LegrandNico LegrandNico force-pushed the feat/error-conventions branch from 99da34b to 913253b Compare July 9, 2026 19:47
@LegrandNico LegrandNico merged commit bb701bf into master Jul 9, 2026
22 checks passed
@LegrandNico LegrandNico deleted the feat/error-conventions branch July 9, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant