From bf1c332a306084aadc61c1705f3d1a6bad52c875 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Tue, 30 Dec 2025 19:46:00 +0100 Subject: [PATCH] docs(tests): synchronize README line numbers with current code - Update Coverage Mapping table line references for invariants 102-106, 110-113, 115-116, 118-121 - Update Non-Owning Smoke table line references for integration, components, pbrs, statistics - Add missing constant groups to documentation (EFFICIENCY, PBRS, SCENARIOS, STAT_TOL) --- .../reward_space_analysis/tests/README.md | 54 ++++++++++--------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/ReforceXY/reward_space_analysis/tests/README.md b/ReforceXY/reward_space_analysis/tests/README.md index 71645e7..4998239 100644 --- a/ReforceXY/reward_space_analysis/tests/README.md +++ b/ReforceXY/reward_space_analysis/tests/README.md @@ -84,6 +84,10 @@ seed_all(SEEDS.FIXED_UNIT) - `EXIT_FACTOR.*` - Exit factor scenarios - `CONTINUITY.*` - Continuity check parameters - `STATISTICAL.*` - Statistical test thresholds +- `EFFICIENCY.*` - Efficiency coefficient testing configuration +- `PBRS.*` - Potential-Based Reward Shaping thresholds +- `SCENARIOS.*` - Test scenario parameters and sample sizes +- `STAT_TOL.*` - Tolerances for statistical metrics **Never use magic numbers** - add new constants to `constants.py` instead. @@ -180,26 +184,26 @@ Columns: | report-abs-shaping-line-091 | integration | Abs Σ Shaping Reward line present & formatted | integration/test_report_formatting.py:4 | Module docstring; primary test at line 95. PBRS report may render line; formatting owned here | | report-additives-deterministic-092 | components | Additives deterministic report section | components/test_additives.py:4 | Integration/PBRS may reference outcome non-owning | | robustness-decomposition-integrity-101 | robustness | Single active core component equals total reward under mutually exclusive scenarios | robustness/test_robustness.py:43 | Scenarios: idle, hold, exit, invalid; non-owning refs integration/test_reward_calculation.py | -| robustness-exit-mode-fallback-102 | robustness | Unknown exit_attenuation_mode falls back to linear w/ warning | robustness/test_robustness.py:660 | Comment line (function at :661) | -| robustness-negative-grace-clamp-103 | robustness | Negative exit_plateau_grace clamps to 0.0 w/ warning | robustness/test_robustness.py:702 | | -| robustness-invalid-power-tau-104 | robustness | Invalid power tau falls back alpha=1.0 w/ warning | robustness/test_robustness.py:753 | | -| robustness-near-zero-half-life-105 | robustness | Near-zero half life yields no attenuation (factor≈base) | robustness/test_robustness.py:798 | | -| pbrs-canonical-exit-semantic-106 | pbrs | Canonical exit uses shaping=-prev_potential and next_potential=0.0 | pbrs/test_pbrs.py:372 | Uses stored potential across steps; no drift correction applied | -| pbrs-canonical-near-zero-report-116 | pbrs | Canonical near-zero cumulative shaping classification | pbrs/test_pbrs.py:1214 | Full report classification | +| robustness-exit-mode-fallback-102 | robustness | Unknown exit_attenuation_mode falls back to linear w/ warning | robustness/test_robustness.py:654 | Comment line (function at :655) | +| robustness-negative-grace-clamp-103 | robustness | Negative exit_plateau_grace clamps to 0.0 w/ warning | robustness/test_robustness.py:696 | | +| robustness-invalid-power-tau-104 | robustness | Invalid power tau falls back alpha=1.0 w/ warning | robustness/test_robustness.py:747 | | +| robustness-near-zero-half-life-105 | robustness | Near-zero half life yields no attenuation (factor≈base) | robustness/test_robustness.py:792 | | +| pbrs-canonical-exit-semantic-106 | pbrs | Canonical exit uses shaping=-prev_potential and next_potential=0.0 | pbrs/test_pbrs.py:374 | Uses stored potential across steps; no drift correction applied | +| pbrs-canonical-near-zero-report-116 | pbrs | Canonical near-zero cumulative shaping classification | pbrs/test_pbrs.py:1223 | Full report classification | | statistics-partial-deps-skip-107 | statistics | skip_partial_dependence => empty PD structures | statistics/test_statistics.py:42 | Docstring line | | helpers-duplicate-rows-drop-108 | helpers | Duplicate rows dropped w/ warning counting removals | helpers/test_utilities.py:27 | Docstring line | | helpers-missing-cols-fill-109 | helpers | Missing required columns filled with NaN + single warning | helpers/test_utilities.py:51 | Docstring line | -| statistics-binned-stats-min-edges-110 | statistics | <2 bin edges raises ValueError | statistics/test_statistics.py:57 | Docstring line | -| statistics-constant-cols-exclusion-111 | statistics | Constant columns excluded & listed | statistics/test_statistics.py:68 | Docstring line | -| statistics-degenerate-distribution-shift-112 | statistics | Degenerate dist: zero shift metrics & KS p=1.0 | statistics/test_statistics.py:84 | Docstring line | -| statistics-constant-dist-widened-ci-113a | statistics | Non-strict: widened CI with warning | statistics/test_statistics.py:543 | Test docstring labels "Invariant 113 (non-strict)" | -| statistics-constant-dist-strict-omit-113b | statistics | Strict: omit metrics (no widened CI) | statistics/test_statistics.py:575 | Test docstring labels "Invariant 113 (strict)" | -| statistics-fallback-diagnostics-115 | statistics | Fallback diagnostics constant distribution (qq_r2=1.0 etc.) | statistics/test_statistics.py:190 | Docstring line | +| statistics-binned-stats-min-edges-110 | statistics | <2 bin edges raises ValueError | statistics/test_statistics.py:60 | Docstring line | +| statistics-constant-cols-exclusion-111 | statistics | Constant columns excluded & listed | statistics/test_statistics.py:71 | Docstring line | +| statistics-degenerate-distribution-shift-112 | statistics | Degenerate dist: zero shift metrics & KS p=1.0 | statistics/test_statistics.py:87 | Docstring line | +| statistics-constant-dist-widened-ci-113a | statistics | Non-strict: widened CI with warning | statistics/test_statistics.py:551 | Test docstring labels "Invariant 113 (non-strict)" | +| statistics-constant-dist-strict-omit-113b | statistics | Strict: omit metrics (no widened CI) | statistics/test_statistics.py:583 | Test docstring labels "Invariant 113 (strict)" | +| statistics-fallback-diagnostics-115 | statistics | Fallback diagnostics constant distribution (qq_r2=1.0 etc.) | statistics/test_statistics.py:191 | Docstring line | | robustness-exit-pnl-only-117 | robustness | Only exit actions have non-zero PnL | robustness/test_robustness.py:127 | Comment line | -| pbrs-absence-shift-placeholder-118 | pbrs | Placeholder shift line present (absence displayed) | pbrs/test_pbrs.py:1514 | Ensures placeholder appears when shaping shift absent | -| components-pbrs-breakdown-fields-119 | components | PBRS breakdown fields finite and mathematically aligned | components/test_reward_components.py:696 | Tests base_reward, pbrs_delta, invariance_correction fields and their alignment | -| integration-pbrs-metrics-section-120 | integration | PBRS Metrics section present in report with tracing metrics | integration/test_report_formatting.py:160 | Verifies PBRS Metrics (Tracing) subsection rendering in statistical_analysis.md | -| cli-pbrs-csv-columns-121 | cli | PBRS columns in reward_samples.csv when shaping enabled | cli/test_cli_params_and_csv.py:238 | Ensures reward_base, reward_pbrs_delta, reward_invariance_correction columns exist and contain finite values | +| pbrs-absence-shift-placeholder-118 | pbrs | Placeholder shift line present (absence displayed) | pbrs/test_pbrs.py:1523 | Ensures placeholder appears when shaping shift absent | +| components-pbrs-breakdown-fields-119 | components | PBRS breakdown fields finite and mathematically aligned | components/test_reward_components.py:783 | Tests base_reward, pbrs_delta, invariance_correction fields and their alignment | +| integration-pbrs-metrics-section-120 | integration | PBRS Metrics section present in report with tracing metrics | integration/test_report_formatting.py:155 | Verifies PBRS Metrics (Tracing) subsection rendering in statistical_analysis.md | +| cli-pbrs-csv-columns-121 | cli | PBRS columns in reward_samples.csv when shaping enabled | cli/test_cli_params_and_csv.py:221 | Ensures reward_base, reward_pbrs_delta, reward_invariance_correction columns exist and contain finite values | ### Non-Owning Smoke / Reference Checks @@ -214,15 +218,15 @@ Table tracks approximate line ranges and source ownership: | File | Lines (approx) | References | Ownership Source | | -------------------------------------- | -------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | -| integration/test_reward_calculation.py | 35 | Decomposition identity (sum components) | robustness/test_robustness.py:43 | -| components/test_reward_components.py | 472 | Exit factor finiteness & plateau behavior | robustness/test_robustness.py:43+ | -| pbrs/test_pbrs.py | 1048 | Canonical vs non-canonical classification formatting | robustness/test_robustness.py:43, robustness/test_robustness.py:127 | -| pbrs/test_pbrs.py | 1213,1283,1406 | Abs Σ Shaping Reward line formatting | integration/test_report_formatting.py:95 | -| pbrs/test_pbrs.py | 1213 | Canonical near-zero cumulative shaping classification | robustness/test_robustness.py:43 | -| pbrs/test_pbrs.py | 1283 | Canonical warning classification (Σ shaping > tolerance) | robustness/test_robustness.py:43 | -| pbrs/test_pbrs.py | 1406 | Non-canonical full report reason aggregation | robustness/test_robustness.py:43 | -| pbrs/test_pbrs.py | 1460 | Non-canonical mode-only reason (additives disabled) | robustness/test_robustness.py:43 | -| statistics/test_statistics.py | 296 | Mean decomposition consistency | robustness/test_robustness.py:43 | +| integration/test_reward_calculation.py | 44 | Decomposition identity (sum components) | robustness/test_robustness.py:43 | +| components/test_reward_components.py | 551 | Exit factor finiteness & plateau behavior | robustness/test_robustness.py:43+ | +| pbrs/test_pbrs.py | 1053 | Canonical vs non-canonical classification formatting | robustness/test_robustness.py:43, robustness/test_robustness.py:127 | +| pbrs/test_pbrs.py | 1222,1292,1415 | Abs Σ Shaping Reward line formatting | integration/test_report_formatting.py:95 | +| pbrs/test_pbrs.py | 1222 | Canonical near-zero cumulative shaping classification | robustness/test_robustness.py:43 | +| pbrs/test_pbrs.py | 1292 | Canonical warning classification (Σ shaping > tolerance) | robustness/test_robustness.py:43 | +| pbrs/test_pbrs.py | 1415 | Non-canonical full report reason aggregation | robustness/test_robustness.py:43 | +| pbrs/test_pbrs.py | 1469 | Non-canonical mode-only reason (additives disabled) | robustness/test_robustness.py:43 | +| statistics/test_statistics.py | 292 | Mean decomposition consistency | robustness/test_robustness.py:43 | ### Deprecated / Reserved IDs -- 2.53.0