From 03e0891bbbb32046ca78bc366e4f4e5183d56ed0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Wed, 24 Dec 2025 23:53:18 +0100 Subject: [PATCH] docs(ReforceXY): update tests documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- .../reward_space_analysis/tests/README.md | 68 +++++++++---------- .../components/test_reward_components.py | 2 +- .../integration/test_reward_calculation.py | 2 +- .../tests/pbrs/test_pbrs.py | 10 +-- .../tests/statistics/test_statistics.py | 2 +- 5 files changed, 42 insertions(+), 42 deletions(-) diff --git a/ReforceXY/reward_space_analysis/tests/README.md b/ReforceXY/reward_space_analysis/tests/README.md index 486fb15..71645e7 100644 --- a/ReforceXY/reward_space_analysis/tests/README.md +++ b/ReforceXY/reward_space_analysis/tests/README.md @@ -175,31 +175,31 @@ Columns: - Notes: Clarifications (sub-modes, extensions, non-owning references elsewhere, line clusters for multi-path coverage). -| ID | Category | Description | Owning File | Notes | -| -------------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| report-abs-shaping-line-091 | integration | Abs Σ Shaping Reward line present & formatted | integration/test_report_formatting.py:4 | Module docstring; primary test at line 84. PBRS report may render line; formatting owned here (core assertion lines 84–103) | -| 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:36 | 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:525 | Comment line (function at :526) | -| robustness-negative-grace-clamp-103 | robustness | Negative exit_plateau_grace clamps to 0.0 w/ warning | robustness/test_robustness.py:555 | | -| robustness-invalid-power-tau-104 | robustness | Invalid power tau falls back alpha=1.0 w/ warning | robustness/test_robustness.py:592 | | -| robustness-near-zero-half-life-105 | robustness | Near-zero half life yields no attenuation (factor≈base) | robustness/test_robustness.py:621 | | -| pbrs-canonical-exit-semantic-106 | pbrs | Canonical exit uses shaping=-prev_potential and next_potential=0.0 | pbrs/test_pbrs.py:449 | 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:748 | Full report classification | -| statistics-partial-deps-skip-107 | statistics | skip_partial_dependence => empty PD structures | statistics/test_statistics.py:28 | Docstring line | -| helpers-duplicate-rows-drop-108 | helpers | Duplicate rows dropped w/ warning counting removals | helpers/test_utilities.py:26 | Docstring line | -| helpers-missing-cols-fill-109 | helpers | Missing required columns filled with NaN + single warning | helpers/test_utilities.py:50 | Docstring line | -| statistics-binned-stats-min-edges-110 | statistics | <2 bin edges raises ValueError | statistics/test_statistics.py:45 | Docstring line | -| statistics-constant-cols-exclusion-111 | statistics | Constant columns excluded & listed | statistics/test_statistics.py:57 | Docstring line | -| statistics-degenerate-distribution-shift-112 | statistics | Degenerate dist: zero shift metrics & KS p=1.0 | statistics/test_statistics.py:74 | Docstring line | -| statistics-constant-dist-widened-ci-113a | statistics | Non-strict: widened CI with warning | statistics/test_statistics.py:533 | Test docstring labels "Invariant 113 (non-strict)" | -| statistics-constant-dist-strict-omit-113b | statistics | Strict: omit metrics (no widened CI) | statistics/test_statistics.py:565 | 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 | -| robustness-exit-pnl-only-117 | robustness | Only exit actions have non-zero PnL | robustness/test_robustness.py:126 | Newly assigned ID | -| pbrs-absence-shift-placeholder-118 | pbrs | Placeholder shift line present (absence displayed) | pbrs/test_pbrs.py:979 | 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:454 | 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:156 | 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:240 | Ensures reward_base, reward_pbrs_delta, reward_invariance_correction columns exist and contain finite values | +| ID | Category | Description | Owning File | Notes | +| -------------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| 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 | +| 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 | +| 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 | ### Non-Owning Smoke / Reference Checks @@ -214,15 +214,15 @@ Table tracks approximate line ranges and source ownership: | File | Lines (approx) | References | Ownership Source | | -------------------------------------- | -------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | -| integration/test_reward_calculation.py | 15-22 | Decomposition identity (sum components) | robustness/test_robustness.py:36 | -| components/test_reward_components.py | 212-242 | Exit factor finiteness & plateau behavior | robustness/test_robustness.py:156+ | -| pbrs/test_pbrs.py | 591-630 | Canonical vs non-canonical classification formatting | robustness/test_robustness.py:36, robustness/test_robustness.py:126 | -| pbrs/test_pbrs.py | 616,624,799 | Abs Σ Shaping Reward line formatting | integration/test_report_formatting.py:84-103 | -| pbrs/test_pbrs.py | 742-806 | Canonical near-zero cumulative shaping classification | robustness/test_robustness.py:36 | -| pbrs/test_pbrs.py | 807-860 | Canonical warning classification (Σ shaping > tolerance) | robustness/test_robustness.py:36 | -| pbrs/test_pbrs.py | 861-915 | Non-canonical full report reason aggregation | robustness/test_robustness.py:36 | -| pbrs/test_pbrs.py | 916-969 | Non-canonical mode-only reason (additives disabled) | robustness/test_robustness.py:36 | -| statistics/test_statistics.py | 292 | Mean decomposition consistency | robustness/test_robustness.py:36 | +| 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 | ### Deprecated / Reserved IDs diff --git a/ReforceXY/reward_space_analysis/tests/components/test_reward_components.py b/ReforceXY/reward_space_analysis/tests/components/test_reward_components.py index 9275625..416a391 100644 --- a/ReforceXY/reward_space_analysis/tests/components/test_reward_components.py +++ b/ReforceXY/reward_space_analysis/tests/components/test_reward_components.py @@ -469,7 +469,7 @@ class TestRewardComponents(RewardSpaceTestBase): def test_exit_factor_calculation(self): """Exit factor calculation smoke test across attenuation modes. - Non-owning smoke test; ownership: robustness/test_robustness.py:35 + Non-owning smoke test; ownership: robustness/test_robustness.py:43 Verifies: - Exit factors are finite and positive (linear, power modes) diff --git a/ReforceXY/reward_space_analysis/tests/integration/test_reward_calculation.py b/ReforceXY/reward_space_analysis/tests/integration/test_reward_calculation.py index cf53611..01e80d7 100644 --- a/ReforceXY/reward_space_analysis/tests/integration/test_reward_calculation.py +++ b/ReforceXY/reward_space_analysis/tests/integration/test_reward_calculation.py @@ -32,7 +32,7 @@ class TestRewardCalculation(RewardSpaceTestBase): ): """Smoke: each primary component activates in a representative scenario. - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) Detailed progressive / boundary / proportional invariants are NOT asserted here. We only check sign / non-zero activation plus total decomposition identity. """ diff --git a/ReforceXY/reward_space_analysis/tests/pbrs/test_pbrs.py b/ReforceXY/reward_space_analysis/tests/pbrs/test_pbrs.py index c861270..caede00 100644 --- a/ReforceXY/reward_space_analysis/tests/pbrs/test_pbrs.py +++ b/ReforceXY/reward_space_analysis/tests/pbrs/test_pbrs.py @@ -1045,7 +1045,7 @@ class TestPBRS(RewardSpaceTestBase): # ---------------- Report classification / formatting ---------------- # - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101), robustness/test_robustness.py:125 (robustness-exit-pnl-only-117) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101), robustness/test_robustness.py:127 (robustness-exit-pnl-only-117) @pytest.mark.smoke def test_pbrs_non_canonical_report_generation(self): """Synthetic invariance section: Non-canonical classification formatting.""" @@ -1210,7 +1210,7 @@ class TestPBRS(RewardSpaceTestBase): f"Expected non-zero shaping (got {shaping_sum})", ) - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) # Owns invariant: pbrs-canonical-near-zero-report-116 @pytest.mark.smoke def test_pbrs_canonical_near_zero_report(self): @@ -1280,7 +1280,7 @@ class TestPBRS(RewardSpaceTestBase): ) self.assertIn("max|correction|≈0", content) - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) @pytest.mark.smoke def test_pbrs_canonical_suppresses_additives_in_report(self): """Canonical exit mode suppresses additives for classification. @@ -1403,7 +1403,7 @@ class TestPBRS(RewardSpaceTestBase): expected_corr_fragment = f"{max_abs_corr:.6e}" self.assertIn(expected_corr_fragment, content) - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) @pytest.mark.smoke def test_pbrs_non_canonical_full_report_reason_aggregation(self): """Full report: Non-canonical classification aggregates mode + additives reasons.""" @@ -1457,7 +1457,7 @@ class TestPBRS(RewardSpaceTestBase): ) self.assertIn("exit_potential_mode='progressive_release'", content) - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) @pytest.mark.smoke def test_pbrs_non_canonical_mode_only_reason(self): """Non-canonical exit mode with additives disabled -> reason excludes additive list.""" diff --git a/ReforceXY/reward_space_analysis/tests/statistics/test_statistics.py b/ReforceXY/reward_space_analysis/tests/statistics/test_statistics.py index 2e1d830..41e9899 100644 --- a/ReforceXY/reward_space_analysis/tests/statistics/test_statistics.py +++ b/ReforceXY/reward_space_analysis/tests/statistics/test_statistics.py @@ -293,7 +293,7 @@ class TestStatistics(RewardSpaceTestBase): f"Expected near-zero divergence after equal scaling (k={k}, v={v})", ) - # Non-owning smoke; ownership: robustness/test_robustness.py:35 (robustness-decomposition-integrity-101) + # Non-owning smoke; ownership: robustness/test_robustness.py:43 (robustness-decomposition-integrity-101) @pytest.mark.smoke def test_stats_mean_decomposition_consistency(self): """Batch mean additivity.""" -- 2.43.0