Skip to content

Make Bragg/stoichiometric fallback transparent (surface bragg_used) and add accuracy tests #111

@grzanka

Description

@grzanka

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:

  1. 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
  2. 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

  • Consumers can determine, without loading internals, whether a result is native or Bragg-extended.
  • bragg_used (or equivalent) is exposed in dedx_wrappers.h and the Python binding.
  • At least one test documents fallback-vs-native agreement with an explicit tolerance.
  • API docs explain native vs. extended coverage and link the README note.

References

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions