Implement λ(W) causal-indefiniteness metric

[HectorMozo3110]

Summary

• Introduces a new causal-indefiniteness metric λ(W) based on trace distance.
• Implements the computable formulation described in the paper “Pre-Temporal Model of Quantum Causal Order”, restricted to a one-parameter convex mixture of two definite causal orders.
• Exposes the metric through the public qmlhc.metrics API.
• Adds unit tests covering numerical correctness, input validation, and internal computation branches.
• Adds initial API documentation and registers the module in the metrics documentation index.

Paper (context & reference):
Pre-Temporal Model of Quantum Causal Order
https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5993818

---

Checklist

Completed

• Implement causal-indefiniteness metric λ(W) using trace distance.
• Add reference-process construction for definite causal orders.
• Expose λ(W) via the public qmlhc.metrics API.
• Add unit tests for correctness, validation, and branch coverage.
• Add API documentation for the new metric.
• Register the metric module in the metrics documentation index.

Planned follow-ups (next commits before merge)

• Add an expanded example demonstrating how to compute λ(W) from real
  framework outputs (e.g., HCGraph branches or process representations).
• Expand documentation with a conceptual explanation of causal
  indefiniteness and interpretation guidelines for λ(W).
• Add a reference entry to the paper in the Theories & Concepts
  section of the documentation.
• Show how λ(W) can be combined with existing control and stability
  metrics (e.g., as a diagnostic or monitoring signal).
• Run a full documentation build (make html) and perform final review
  before merge.

---

Motivation

Quantifying causal structure is a central requirement in pre-temporal and
hypercausal models. The causal-indefiniteness metric λ(W), introduced in
“Pre-Temporal Model of Quantum Causal Order”, provides a continuous and
interpretable measure of how far a process or operator departs from definite
causal order. This enables systematic analysis of causal transitions, noise
effects, and intermediate regimes, and supports tighter integration between
causal diagnostics, control, and learning workflows within the framework.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!