Phase 2 of #149: the correctness fixes

data/README.md

@@ -73,3 +73,24 @@ Manual cross-check:
 - ICRU49 matches the `ICRU_ASTAR.dat` value (`1.016e+03`)
 
 So the small difference is real and source-driven.
+
+## Hand-Added Rows in `src/data/embedded/dedx_metadata.h`
+
+`dedx_embedded_compos_rows[]` is not generated by any script in `tools/` (unlike
+the stopping-power tables) -- it is hand-maintained, and rows added directly to
+it need their own provenance note here rather than only a code comment, per
+issue #149 finding S3.
+
+- **FERROUSOXIDE (material id 159), density row `5.7 g/cm^3`**: this is the
+  standard literature density for ferrous oxide / wüstite (FeO), consistent
+  with the CRC Handbook of Chemistry and Physics. Added to close issue #149
+  finding A5 (the row's absence made `dedx_internal_validate_rho()` fail this
+  material for every program that reads density, tabulated or not). Its
+  mean excitation potential (I-value) is deliberately left at `0.0` in that
+  same row: no raw source in this repository or in `tools/` covers I-values
+  for compounds, so there is nothing to regenerate or verify a fabricated
+  number against, and `dedx_embedded_get_i_value()` treats `0.0` as "not
+  found" rather than a real answer -- see the comment at that row and
+  `tests/test_material_availability.c`'s `test_ferrous_oxide_tabulated_program()`
+  for the tests that depend on this being `0.0` specifically. Only add a real
+  I-value here once one can be cited the same way this density is.

include/dedx.h

@@ -60,7 +60,19 @@ enum {
                              Deliberately grouped with the other tabulated report identifiers
                              (not >= DEDX_DEFAULT) so that a compound target resolves through the
                              same tabulated-first path as DEDX_ICRU instead of always decomposing
-                             into elements. */
+                             into elements.
+
+                             This "best effort" promise has one hole: a compound whose
+                             constituents resolve to *different* tiers -- one tabulated, one
+                             Bethe-fallback -- can end up on mismatched energy grids, since the
+                             two tiers are not sampled at the same points. Rather than silently
+                             mixing or truncating those grids, dedx_load_config() rejects the
+                             mix with DEDX_ERR_INCONSISTENT_ENERGY_GRID (see issue #149 finding
+                             A1). This is a real, if narrow, exception to "falls back rather than
+                             failing outright" above -- it affects compounds like boron carbide,
+                             where boron is Bethe-only but carbon is tabulated. Callers that need
+                             every advertised DEDX_AUTO compound to load must be prepared to
+                             handle this error, not just DEDX_ERR_COMBINATION_NOT_FOUND. */
     DEDX_DEFAULT = 100, /**< Default program (Bethe formula) */
     DEDX_BETHE_EXT00    /**< Bethe formula with extensions */
 };
@@ -369,6 +381,25 @@ int dedx_load_config(dedx_workspace *ws, dedx_config *config, int *err);
  */
 float dedx_get_stp(dedx_workspace *ws, dedx_config *config, float energy, int *err);
 
+/** @brief Report the interpolation mode actually used for a loaded configuration.
+ *
+ *  dedx_config::interpolation_mode is the mode the caller requested.
+ *  DEDX_INTERPOLATION_LOG_LOG silently falls back to DEDX_INTERPOLATION_LINEAR
+ *  when the underlying table contains a non-positive energy or stopping-power
+ *  value (log-log space cannot represent zero or negative values), so the
+ *  effective mode used for interpolation can differ from what was requested.
+ *  Call this after dedx_load_config() to find out which mode was actually
+ *  applied to the loaded dataset.
+ *
+ *  @param[in]  ws      Workspace with a loaded configuration.
+ *  @param[in]  config  Loaded configuration (cfg_id must be valid).
+ *  @param[out] err     Error code; 0 on success.
+ *  @return DEDX_INTERPOLATION_LOG_LOG or DEDX_INTERPOLATION_LINEAR on success, or -1
+ *          if @p config has no valid loaded dataset (check @p err, not the return
+ *          value, to distinguish failure from DEDX_INTERPOLATION_LOG_LOG == 0).
+ */
+int dedx_get_effective_interpolation_mode(dedx_workspace *ws, dedx_config *config, int *err);
+
 /** @brief One-call stopping power evaluation using the default program for the ion.
  *
  *  Convenience wrapper: allocates a workspace internally, loads the appropriate

include/dedx_elements.h

@@ -8,6 +8,15 @@ extern "C" {
 /** Maximum number of tabulated energy points stored per dataset. */
 #define DEDX_MAX_ELEMENTS 150
 
+/** Highest material identifier that denotes an element (Z = atomic number); every
+ *  id greater than this is a compound or mixture -- DEDX_A150_TISSUE_EQUIVALENT_PLASTIC
+ *  (id 99) is the first compound entry, immediately after DEDX_CALIFORNIUM (id 98),
+ *  the last elemental one. Use this instead of a bare 98/99 literal when testing
+ *  whether a material id is an element: a stray `<= 99` here previously evaluated
+ *  A150 (a compound) as if it were elemental einsteinium (see issue #149, finding A2).
+ */
+#define DEDX_MAX_ELEMENT_ID 98
+
 /**
  * @defgroup ions_and_materials Ion and material identifiers
  * @brief Identifiers for projectile ions and target materials.

include/dedx_error.h

@@ -38,18 +38,21 @@ extern "C" {
 
 /** @defgroup err_data Data and configuration errors (201–210)
  * @{ */
-#define DEDX_ERR_TARGET_NOT_FOUND 201           /**< target not found in embedded metadata */
-#define DEDX_ERR_COMBINATION_NOT_FOUND 202      /**< ion/target combination not in embedded data */
-#define DEDX_ERR_INVALID_DATASET_ID 203         /**< dataset ID does not exist in workspace */
-#define DEDX_ERR_NOT_AN_ELEMENT 204             /**< ID does not correspond to an atomic element */
-#define DEDX_ERR_ESTAR_NOT_IMPL 205             /**< ESTAR program is not implemented */
-#define DEDX_ERR_ION_NOT_SUPPORTED_MSTAR 206    /**< ion not supported for MSTAR (reserved legacy code) */
+#define DEDX_ERR_TARGET_NOT_FOUND 201      /**< target not found in embedded metadata */
+#define DEDX_ERR_COMBINATION_NOT_FOUND 202 /**< ion/target combination not in embedded data */
+#define DEDX_ERR_INVALID_DATASET_ID 203    /**< dataset ID does not exist in workspace */
+#define DEDX_ERR_NOT_AN_ELEMENT 204        /**< ID does not correspond to an atomic element */
+#define DEDX_ERR_ESTAR_NOT_IMPL 205        /**< ESTAR program is not implemented */
+#define DEDX_ERR_ION_NOT_SUPPORTED_MSTAR                                                                               \
+    206 /**< MSTAR mode/ion/effective-charge combination has no implemented coefficient */
 #define DEDX_ERR_ION_NOT_SUPPORTED 207          /**< ion not supported by requested program */
 #define DEDX_ERR_RHO_REQUIRED 208               /**< target density rho must be provided */
 #define DEDX_ERR_ION_A_REQUIRED 209             /**< nucleon number ion_a must be provided */
 #define DEDX_ERR_INVALID_I_VALUE 210            /**< mean excitation potential must be > 0 */
 #define DEDX_ERR_INCONSISTENT_COMPOUND 211      /**< inconsistent compound specification */
 #define DEDX_ERR_INVALID_INTERPOLATION_MODE 212 /**< interpolation mode is not supported */
+#define DEDX_ERR_INVALID_MSTAR_MODE 213         /**< mstar_mode is not one of the DEDX_MSTAR_MODE_* values */
+#define DEDX_ERR_INCONSISTENT_ENERGY_GRID 214   /**< compound constituents resolved onto mismatched energy grids */
 /** @} */
 
 /** @defgroup err_memory Memory errors (301)