Part of #108 (health-review epic).
Context
For compounds outside a program's native coverage (notably DEDX_PSTAR, DEDX_ASTAR, DEDX_MSTAR), libdedx silently falls back to Bragg additivity / stoichiometric weighting. As the README already notes, this means a value returned under a given program label is not always a native value of that program. The internal dedx_config.bragg_used flag records when this happened, but:
- it is not surfaced through the convenience wrappers (
dedx_wrappers.h), the Python binding, or the WASM API, so downstream consumers (web app, Python users) cannot tell native results from extended ones; and
- there is no test quantifying how accurate the fallback is versus a native/reference source, so we can't bound the error we are exposing.
This is the highest-value correctness/trust item: the numbers are reproducible, but their provenance is currently invisible to users.
Proposed change
- Provide a way to query whether a given (program, ion, target) result used the Bragg fallback (e.g. a wrapper
int dedx_combination_uses_bragg(program, ion, target) or an out-param on the table wrappers), and propagate it to the Python/WASM layers.
- Add reference tests comparing fallback results against native sources where both exist, documenting the observed agreement (tolerance band) in the test and in docs.
- Document the behavior prominently in the API docs (cross-link the README caveat).
Acceptance criteria
References
Part of #108 (health-review epic).
Context
For compounds outside a program's native coverage (notably
DEDX_PSTAR,DEDX_ASTAR,DEDX_MSTAR), libdedx silently falls back to Bragg additivity / stoichiometric weighting. As the README already notes, this means a value returned under a given program label is not always a native value of that program. The internaldedx_config.bragg_usedflag records when this happened, but:dedx_wrappers.h), the Python binding, or the WASM API, so downstream consumers (web app, Python users) cannot tell native results from extended ones; andThis is the highest-value correctness/trust item: the numbers are reproducible, but their provenance is currently invisible to users.
Proposed change
int dedx_combination_uses_bragg(program, ion, target)or an out-param on the table wrappers), and propagate it to the Python/WASM layers.Acceptance criteria
bragg_used(or equivalent) is exposed indedx_wrappers.hand the Python binding.References