Implement λ(W) causal-indefiniteness metric

docs/modules/qmlhc/metrics/index.rst

@@ -20,14 +20,18 @@ Architecture Overview
    |    qmlhc.metrics     |
    +-----------+----------+
                |
-       +-------v--------+     +--------------------+     +----------------------+
-       |   anomalies    |     |      control       |     |     forecasting      |
-       | (early alarms) |     | (stability/robust) |     | (error & Δ-lag)      |
-       +----------------+     +--------------------+     +----------------------+
+       +-------v--------+     +--------------------+     +----------------------+    +-----------------------+
+       |   anomalies    |     |      control       |     |    forecasting       |    |causal_indefiniteness  |
+       | (early alarms) |     | (stability/robust) |     | (error & Δ-lag)      |    |(causal structure λ(W))|
+       +----------------+     +--------------------+     +----------------------+    +-----------------------+
+
 
 - ``anomalies`` - metrics for **early detection** and **recall-at-lag** within sequential data.
 - ``control`` - indicators of **overshoot**, **settling time**, and **robustness** for response stability.
 - ``forecasting`` - statistical errors and temporal alignment metrics (MAPE, MASE, ΔLag, RMSE).
+- ``causal_indefiniteness`` – metrics for **quantifying causal non-separability**
+     via trace-distance–based measures.
+
 
 Core Contracts
 --------------
@@ -52,6 +56,10 @@ Core Contracts
      - Stability index in ``(0, 1]`` inversely proportional to MSE.
    * - ``mape``, ``mase``, ``delta_lag``, ``rmse`` (forecasting)
      - Standard predictive accuracy and alignment metrics.
+   * - ``lambda_w_trace(W, W_AB, W_BA)`` (causal_indefiniteness)
+     - Computes the **causal-indefiniteness measure** :math:`\lambda(W)` as the
+       trace-distance to the convex hull of definite causal orders.
+
 
 Integrated Evaluation Example
 -----------------------------
@@ -208,3 +216,4 @@ Module References
    Anomaly Metrics <qmlhc.metrics.anomalies>
    Control Metrics <qmlhc.metrics.control>
    Forecasting Metrics <qmlhc.metrics.forecasting>
+   Causal-Indefiniteness Metrics <qmlhc.metrics.causal_indefiniteness>

docs/modules/qmlhc/metrics/qmlhc.metrics.causal_indefiniteness.rst

@@ -0,0 +1,7 @@
+Causal-Indefiniteness Metric
+============================
+
+.. automodule:: qmlhc.metrics.causal_indefiniteness
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/theory.rst

@@ -1,4 +1,6 @@
-Theory / Concepts
+.. _theory:
+
+Theory & Concepts
 =================
 
 This section explains the theoretical foundations of QML-HCS, covering
@@ -87,4 +89,95 @@ Associated Paper
       </div>
 
      </div>
-   </div>
+   </div>
+
+
+
+.. raw:: html
+
+   <div style="
+     border: 2px solid #1c1758ff;
+     background: #ffffffff;
+     padding: 18px 20px;
+     border-radius: 10px;
+     box-shadow: 0 8px 20px rgba(0,0,0,0.35);
+     margin-top: 1rem;
+     margin-bottom: 1.5rem;
+   ">
+
+     <h3 style="margin-top:0; color:#4f46e5;">
+       Pre-Temporal Model of Quantum Causal Order
+     </h3>
+
+     <p style="margin: 0.4rem 0 0.8rem 0; color: #757575ff;">
+       <strong>Hector E. Mozo</strong>
+     </p>
+
+     <p style="margin-bottom: 1rem; color: #686868ff; line-height:1.6;">
+      This paper establishes the theoretical foundation for treating causal order
+      as a continuous, quantifiable resource within computational and learning
+      frameworks. It introduces the causal-indefiniteness measure <em>λ(W)</em>,
+      defined via the trace distance between a quantum process and the convex set
+      of causally separable processes, providing a principled scalar that
+      interpolates between indefinite and definite causal structure.
+      <br><br>
+      Within the context of QML-HCS, this pre-temporal formulation supplies a
+      rigorous conceptual layer for modeling systems whose causal structure
+      evolves over time. The measure <em>λ(W)</em> functions as an operational
+      signal that can be tracked, optimized, or regularized within hypercausal
+      learning loops, enabling QML-HCS to reason about causal consolidation,
+      stability, and regime transitions in non-stationary environments.
+      <br><br>
+      In this way, the framework leverages pre-temporal causal dynamics not as an
+      abstract phenomenon, but as a computable control variable that informs
+      prediction, adaptation, and system-level coherence.
+     </p>
+
+     <div style="display:flex; gap:12px; flex-wrap:wrap;">
+
+       <a href="https://ssrn.com/abstract=5993818"
+          target="_blank"
+          style="
+            padding: 10px 14px;
+            background: #1b176eff;
+            color: #ffffff;
+            border-radius: 6px;
+            text-decoration: none;
+            font-weight: 600;
+          ">
+          SSRN: 5993818
+       </a>
+
+       <div style="
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        padding: 8px 12px;
+        background: #0f172a;
+        border: 1.5px solid #201d64ff;
+        border-radius: 6px;
+        font-family: monospace;
+        font-size: 0.95em;
+        color: #e5e7eb;
+      ">
+        <span>DOI: 10.2139/ssrn.5993818</span>
+
+        <button onclick="
+          navigator.clipboard.writeText('10.2139/ssrn.5993818');
+          this.innerText='✓';
+          setTimeout(() => this.innerText='⧉', 1200);
+        "
+        style="
+          background: transparent;
+          border: none;
+          color: #a5b4fc;
+          cursor: pointer;
+          font-size: 1.1em;
+        "
+        title="Copy DOI">
+          ⧉
+        </button>
+      </div>
+
+     </div>
+   </div>

src/qmlhc/metrics/__init__.py

@@ -5,6 +5,8 @@
 from .control import overshoot, settling_time, robustness
 from .anomalies import early_roc_auc, recall_at_lag
 
+# NEW: causal-indefiniteness metric
+from .causal_indefiniteness import lambda_w_trace, trace_distance
 __all__ = [
     "mape",
     "mase",
@@ -15,4 +17,6 @@
     "early_roc_auc",
     "recall_at_lag",
     "rmse"
+    "lambda_w_trace",
+    "trace_distance",
 ]