Add explicit failure status reporting to uniform billiard walk

[adilraza99]

Fixes #433

Summary

This PR adds explicit failure status reporting to the uniform billiard walk implementation to address the silent failure scenarios discussed in #433.

Previously, the walk could fail internally without informing the caller. This made it difficult for users to detect issues or implement proper error handling in higher-level code.

Problem

The billiard walk could silently fail in several situations, including:

• Hitting the maximum reflection limit
• Numerical stagnation where the sampled point does not move
• Invalid or degenerate geometric intersections

In all of these cases, the caller had no way to distinguish a successful walk from a failed one.

Solution

This change introduces a small WalkStatus enum and updates the core walk function to return an explicit status value.

The enum covers the main failure modes:

• SUCCESS – walk completed normally
• ITERATION_LIMIT – maximum reflections exceeded
• NUMERICAL_STAGNATION – insufficient movement detected
• INVALID_STATE – degenerate intersection or numerical issue

This allows callers to detect and handle failures explicitly:

WalkStatus status = walk.apply(P, p, walk_length, rng);
if (status != WalkStatus::SUCCESS) {
    // handle failure
}

Scope and Compatibility

The change is intentionally minimal and localized to
uniform_billiard_walk.hpp.

Successful walks preserve their previous behavior, and the sampling
trajectory is unchanged. The update simply exposes failure information
that was previously hidden.

Verification

• Project builds successfully
• Existing tests pass
• Manual checks confirm that previously silent failures are now detectable

This PR focuses only on exposing failure status and does not introduce
architectural changes.

[Akash504-ai]

Thank you for working on this. Adding WalkStatus is the right idea but the current changes modify too much of the file and introduce duplicated code and structural issues. Please keep the original structure and make only the minimal changes to add status reporting.

[adilraza99]

@Akash504-ai

Thanks for the review and for suggesting a minimal approach.

I’ve revised the implementation to follow the existing walker pattern while keeping the changes strictly surgical:

• apply() now returns bool, consistent with the exact walk implementation
• returns false when the iteration limit (50*n) is reached
• returns true on successful completion
• original structure, formatting, and includes remain unchanged

Verification:
• clean rebuild from scratch — no compilation issues
• tests pass (5/6); the single failure is pre-existing on develop and unrelated
• diff remains minimal: 1 file changed, 4 insertions, 1 deletion

Please let me know if you’d like any further adjustments.

[Akash504-ai]

Thank you for the change, this change is clean and correctly handles the iteration limit case. But the issue also mentions numerical stagnation and degenerate intersections which are not handled yet. Should we extend this to cover those cases as well or clarify the exact scope of this fix? Since this is an architectural level issue in my opinion it may be better to wait for mentor's suggestion and have a proper discussion before finalizing the approach.