Fixing Numerical Issues: Adjusting VAL_scale In TNFR

by SLV Team 53 views
Fixing Numerical Issues: Adjusting VAL_scale in TNFR

Hey guys! Let's dive into an important adjustment we're making to the TNFR engine to enhance its stability and prevent some pesky issues. This change revolves around a constant called VAL_scale within the GLYPH_FACTORS. We're going to lower it from 1.15 to 1.05. Sounds small, but it has a big impact!

The Problem: EPI Overflow and Numerical Instability

The core issue we're tackling is the potential for EPI (Expansion Potential Indicator) overflow, which can lead to errors in grammar tests. Currently, VAL_scale is set to 1.15. This means that when a value is multiplied by VAL_scale, it can quickly exceed the maximum allowed EPI value of 1.0, particularly when dealing with higher EPI values. This leads to the error message "EPI values going slightly out of range." Let's break down the numerical analysis, and you'll see why this is a problem.

Numerical Analysis

Let's get into the nitty-gritty with some numbers, shall we?

  • Current Situation: With VAL_scale = 1.15, the critical threshold is around 0.869565 (1.0 / 1.15). If the EPI value is at or above this threshold, it's very close to, or already exceeding, the maximum permissible EPI value.
  • Example: If we have an EPI value of 0.95, multiplying it by 1.15 gives us 1.0925, which surpasses the maximum allowed EPI of 1.0.

Proposed Solution and Benefits

  • The Adjustment: We're proposing to set VAL_scale to 1.05. This might seem like a small tweak, but it's a conservative measure to significantly improve numerical stability.
  • New Critical Threshold: With VAL_scale = 1.05, the new critical threshold becomes approximately 0.952381 (1.0 / 1.05). This gives us a much larger safety margin.
  • Significant Safety Margin: The adjustment provides a much larger safety net, reducing the chances of EPI overflow and making the system more reliable.

This simple adjustment is like adding a safety net. It reduces the likelihood of EPI values going out of bounds, which can cause problems during grammar testing.

Justification for the Change within TNFR

Now, let's explore why this is a good change from a structural and operational perspective. We're not just throwing numbers around; we're considering the underlying principles of the TNFR engine.

Principle of Structural Coherence

  • Fractal Expansion: The core idea is that VAL (Value) should be able to expand without compromising its identity. This adjustment helps to maintain this principle.
  • Structural Border: The EPI_MAX (maximum EPI) isn't just an arbitrary limit; it's a boundary that defines the identity of the structure. We don't want to break it.
  • Operational Robustness: By making this conservative adjustment, we're boosting the operational stability without hindering the engine's ability to expand and grow.

Impact on Expansion Capability

  • Scale Reduction: We're reducing the scaling factor by 8.7% (from 1.15 to 1.05).
  • Continued Expansion: The good news is that even with this change, the expansion capability remains substantial. For instance, with ten applications of VAL, starting from 0.5, it would still expand to 0.814 (instead of the previous, problematic 2.078).
  • Predictability: The adjustment improves the predictability of the sequences, especially in longer operations. It ensures that things expand in a more controlled manner, leading to better results.

In essence, we're prioritizing stability and reliability without sacrificing the ability to expand and adapt.

Implementation Details

Here's what you need to know about the practical aspects of this change. It's a simple change, but let's make sure we do it right!

File to be Modified

You'll need to modify the file src/tnfr/constants/core.py.

Specific Change

Inside src/tnfr/constants/core.py, you'll find the GLYPH_FACTORS dictionary. The following code snippet shows exactly what needs to be changed:

# Before
GLYPH_FACTORS: dict[str, float] = field(
    default_factory=lambda: {
        # ...
        "VAL_scale": 1.15,  # ← Problematic
        # ...
    }
)

# After
GLYPH_FACTORS: dict[str, float] = field(
    default_factory=lambda: {
        # ...
        "VAL_scale": 1.05,  # ← Conservative adjustment
        # ...
    }
)

It's a straightforward replacement. Just change 1.15 to 1.05.

Evaluating NUL_scale

  • For now, we will maintain NUL_scale = 0.85.
  • It doesn't immediately cause lower overflow.
  • Minimum secure EPI: -1.0 / 0.85 ≈ -1.176 (a problem only for really negative values).
  • It will be protected by structural_clip and edge-aware scaling (#2661, #2662).

Documentation Requirements

To ensure everyone is in the loop and understands why these changes were made, we need to update the documentation.

File Updates

You'll need to update the following files:

  • ARCHITECTURE.md: Document the rationale behind this adjustment.
  • IMPLEMENTATION_SUMMARY_DYNAMIC_LIMITS.md: Explain the concept of the "structural border" and the conservative nature of VAL_scale.
  • Code Comments: Add comments in the code to justify the value 1.05.

Changelog Entry

Here's what the changelog entry should look like:

### Changed
- Reduced VAL_scale from 1.15 to 1.05 to prevent EPI overflow in expansion operations
- Improved numerical stability for grammar tests with high EPI values

Make sure the changelog accurately reflects the changes and the reasons behind them. This helps keep a clear history of what was done and why.

Tests to Update

After making the code change, it's crucial to ensure that all existing tests still pass and that the changes haven't introduced any regressions. Some tests might require adjustments to accommodate the new VAL_scale value.

Tests That Might Need Adjustments

Here's how to identify tests that might need to be adjusted:

  • Identify: Any test that specifically assumes VAL_scale = 1.15 will need to be reviewed.
  • Search Locations: Look for these tests in the following locations:
    • tests/unit/operators/test_*
    • tests/integration/
    • examples/ that explicitly use VAL.

Carefully review each test to make sure it functions correctly with the adjusted VAL_scale. It may require minor changes to ensure they pass, but the overall functionality should remain intact.

Additional Verifications

We also need to add some specific tests to verify that the new VAL_scale value works as intended and doesn't break any existing functionality.

Here are the types of tests we need to implement:


def test_val_scale_conservative():
    """Verify that VAL_scale=1.05 is sufficiently conservative"""
    assert GLYPH_FACTORS["VAL_scale"] == 1.05
    assert 1.0 / 1.05 > 0.95  # Safe threshold

def test_val_expansion_capability_maintained():
    """Ensure that the expansion capability is still useful"""
    # Verify that multiple applications still allow for significant growth

The test_val_scale_conservative function checks that the new value is correct and that the threshold remains safe. The test_val_expansion_capability_maintained ensures that expansion operations still work effectively.

Acceptance Criteria

To ensure that this change is fully implemented and working correctly, we have set some clear acceptance criteria.

  • ✅ VAL_scale is changed from 1.15 to 1.05 in GLYPH_FACTORS.
  • ✅ All existing tests pass (or are adjusted to pass) without regressions.
  • ✅ Documentation is updated to explain the changes made.
  • ✅ Verification tests for the new value have been added.
  • ✅ Performance has not regressed.
  • ✅ The changelog is updated to reflect these changes.

By following this checklist, we ensure that the changes are correctly applied, thoroughly tested, and well-documented.

Relation to Other Issues

This adjustment is part of a larger effort to enhance the stability and robustness of the TNFR engine. It works together with other improvements to create a more resilient system.

This change acts as a secondary safety net and is complementary to:

  • #2661: structural_clip (primary protection)
  • #2662: Edge-aware scaling (dynamic adaptation)

Together, these three components form a robust defense system to prevent EPI overflow.

Priority

This change has a Medium-High priority. It can be implemented independently but ideally after #2661 and #2662 to ensure the effectiveness of the improvement.

That's it, guys! By adjusting VAL_scale, we're taking a significant step towards a more reliable and stable TNFR engine. It's all about making sure that the core functionalities are working as expected and that we are preventing problems before they arise. Thanks for your attention, and let's keep improving the code together!