Merge branch 'main' into copilot/verify-phase-validation-sub-epis

Author: fermga

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,61 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation,
+# and allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # Required for actions/checkout - Copilot needs to access the repository
+      contents: read
+
+    # Configure the environment for TNFR development
+    # Purpose: Enable exploration, study, investigation, and development of TNFR
+    # (Resonant Fractal Nature Theory - modeling coherent patterns through resonance)
+    steps:
+      - name: Checkout TNFR repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          # Using Python 3.11 - the primary version for TNFR development and CI
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install TNFR dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Install TNFR directly from repository source code (NOT from PyPI)
+          # Using editable mode (-e) to work with the latest development version
+          # This provides full environment for exploring and developing TNFR:
+          # - Core operators (13 canonical structural transformations)
+          # - Test infrastructure for validating invariants
+          # - Serialization for state preservation
+          # - NumPy for structural computations
+          python -m pip install -e .[test,numpy,yaml,orjson]
+
+      - name: Verify TNFR installation
+        run: |
+          # Verify the TNFR package is properly installed from repo (not PyPI)
+          python -c "import tnfr; print(f'TNFR version: {tnfr.__version__}')"
+          python -c "import tnfr, os; print(f'TNFR location: {os.path.dirname(tnfr.__file__)}')"
+          # Verify core modules are accessible
+          python -c "from tnfr.operators import Emission, Coherence, Resonance; print('✓ Core operators available')"
+          python -c "from tnfr.metrics.coherence import compute_global_coherence; print('✓ Metrics available')"
+          # Display Python environment info
+          python --version
+          pip list | grep -E "(tnfr|pytest|numpy|networkx)"

docs/THOL_CONFIGURATION_REFERENCE.md

@@ -29,6 +29,7 @@ Parameters controlling when and how bifurcation (sub-EPI creation) occurs.
 | `THOL_MIN_EPI` | 0.2 | [0.05, 0.5] | — | Minimum EPI magnitude required for structural bifurcation |
 | `THOL_MIN_VF` | 0.1 | [0.01, 1.0] | Hz_str | Minimum structural frequency for reorganization capacity |
 | `THOL_ACCEL` | 0.10 | [0.01, 0.5] | — | Acceleration factor in glyph: ΔNFR += `THOL_accel` × d²EPI/dt² |
+| `THOL_MIN_COLLECTIVE_COHERENCE` | 0.3 | [0.0, 1.0] | — | Minimum collective coherence for sub-EPI ensemble. When multiple sub-EPIs exist and coherence < threshold, warning is logged |
 
 **Physical Basis:**
 
@@ -38,6 +39,12 @@ From the nodal equation ∂EPI/∂t = νf · ΔNFR(t), bifurcation occurs when *
 - **EPI_min**: Coherence floor. Nodes below this lack sufficient form to bifurcate coherently.
 - **νf_min**: Reorganization capacity floor. Nodes below this are "frozen" and cannot respond.
 - **THOL_accel**: Controls how strongly d²EPI/dt² influences ΔNFR in glyph sequences.
+- **THOL_MIN_COLLECTIVE_COHERENCE**: Monitors ensemble coherence of sub-EPIs. According to TNFR.pdf §2.2.10, sub-EPIs must form a **coherent ensemble** rather than fragmenting chaotically. Collective coherence is computed as `C = 1/(1 + var(sub_epi_magnitudes))`. Interpretation:
+  - **> 0.7**: High coherence (structurally solid bifurcation)
+  - **0.3-0.7**: Moderate (acceptable, monitor)
+  - **< 0.3**: Low (possible fragmentation, warning logged)
+  
+  When multiple sub-EPIs exist and coherence falls below threshold, a warning is logged and the event is recorded in `G.graph["thol_coherence_warnings"]` for analysis. This validation is **non-blocking** (warnings only) to allow research into low-coherence dynamics.
 
 **Configuration Example:**
 ```python
@@ -48,11 +55,21 @@ G = nx.Graph()
 G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.8  # High threshold
 G.graph["THOL_MIN_EPI"] = 0.3              # Require strong coherence
 G.graph["THOL_MIN_VF"] = 0.2               # Require high capacity
+G.graph["THOL_MIN_COLLECTIVE_COHERENCE"] = 0.5  # Require coherent ensemble
 
 # Sensitive bifurcation (easier to trigger)
 G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.2  # Low threshold
 G.graph["THOL_MIN_EPI"] = 0.1              # Lower coherence floor
 G.graph["THOL_MIN_VF"] = 0.05              # Lower capacity floor
+G.graph["THOL_MIN_COLLECTIVE_COHERENCE"] = 0.2  # More tolerant of fragmentation
+
+# Monitor collective coherence
+from tnfr.operators.health_analyzer import SequenceHealthAnalyzer
+analyzer = SequenceHealthAnalyzer()
+coherence_stats = analyzer.analyze_thol_coherence(G)
+if coherence_stats:
+    print(f"Mean coherence: {coherence_stats['mean_coherence']:.3f}")
+    print(f"Nodes below threshold: {coherence_stats['nodes_below_threshold']}")
 ```
 
 ---
@@ -668,6 +685,7 @@ G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.5         # Higher threshold
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2025-11-09 | Initial release: Centralized all THOL parameters with canonical constraints |
+| 1.1.0 | 2025-11-09 | Added `THOL_MIN_COLLECTIVE_COHERENCE` parameter for sub-EPI ensemble validation |
 
 ---
 

src/tnfr/config/defaults_core.py

@@ -158,6 +158,7 @@ class CoreDefaults:
     THOL_MIN_DEGREE: int = 1  # Minimum network connectivity
     THOL_MIN_HISTORY_LENGTH: int = 3  # Minimum EPI history for acceleration computation
     THOL_ALLOW_ISOLATED: bool = False  # Require network context by default
+    THOL_MIN_COLLECTIVE_COHERENCE: float = 0.3  # Minimum collective coherence for sub-EPI ensemble
 
     # VAL (Expansion) precondition thresholds
     VAL_MAX_VF: float = 10.0  # Maximum structural frequency threshold

src/tnfr/metrics/__init__.py

@@ -32,6 +32,11 @@
     compute_learning_plasticity,
     glyph_history_to_operator_names,
 )
+from .phase_compatibility import (
+    compute_network_phase_alignment,
+    compute_phase_coupling_strength,
+    is_phase_compatible,
+)
 from .reporting import (
     Tg_by_node,
     Tg_global,
@@ -68,4 +73,7 @@
     "compute_bifurcation_rate",
     "compute_metabolic_efficiency",
     "compute_emergence_index",
+    "compute_phase_coupling_strength",
+    "is_phase_compatible",
+    "compute_network_phase_alignment",
 )