Skip to content

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

Open

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

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions