Fix biomedical examples and update Silence docstring with clinical documentation links

Copilot · fermga · Copilot · commit 0b255652f622 · 2025-11-08T23:19:45.000Z
Co-authored-by: fermga &lt;203334638+fermga@users.noreply.github.com&gt;
diff --git a/examples/biomedical/recovery_protocols_sha.py b/examples/biomedical/recovery_protocols_sha.py
@@ -3,28 +3,20 @@
 This example demonstrates SHA (Silence) in athletic training as a recovery
 mechanism that enables adaptation consolidation.
 
-Protocol: [Training] VAL → OZ → IL → [Recovery] SHA → [Next Session] NAV → AL
-- Training: Expansion + Dissonance + Coherence (stress and adaptation)
-- Recovery: Silence (νf → 0, adaptation consolidates)
-- Next training: Transition + Emission (return with improved baseline)
+Protocol: AL → VAL → OZ → IL → SHA
+- Emission: Training session begins
+- Expansion + Dissonance + Coherence: Stress and acute adaptation
+- SHA: Recovery pause (νf → 0, adaptation consolidates)
 
 Key insight: SHA models the essential recovery phase where reduced activity
-allows physiological adaptations to consolidate - muscle repair, metabolic
-adjustments, and performance gains require structural pause.
+allows physiological adaptations to consolidate.
 
 References:
 - Kellmann, M., et al. (2018). Recovery and Performance in Sport.
 - See: docs/source/examples/SHA_CLINICAL_APPLICATIONS.md, Section 4
 """
 
-from tnfr.operators.definitions import (
-    Expansion,
-    Dissonance,
-    Coherence,
-    Silence,
-    Transition,
-    Emission,
-)
+from tnfr.operators.definitions import Emission, Expansion, Dissonance, Coherence, Silence
 from tnfr.structural import create_nfr, run_sequence
 
 
@@ -39,79 +31,47 @@ def main():
     # Create muscle tissue node
     G, muscle = create_nfr("muscle_tissue", epi=0.50, vf=1.00)
     
-    # === TRAINING PHASE ===
+    # === TRAINING + RECOVERY ===
     print("=" * 70)
-    print("TRAINING PHASE - Controlled Stress Application")
+    print("TRAINING → RECOVERY CYCLE")
     print("=" * 70)
     print()
     
-    print("Protocol: VAL → OZ → IL (Exercise sequence)")
+    print("Protocol: AL → VAL → OZ → IL → SHA")
     print()
     
-    print("Step 1: EXPANSION (VAL) - Intense muscular activation")
+    print("Step 1: EMISSION (AL) - Training session begins")
+    print("  Athlete initiates workout, system activation")
+    print()
+    
+    print("Step 2: EXPANSION (VAL) - Intense muscular activation")
     print("  Activity: High-intensity intervals, heavy resistance")
     print("  Effect: Increased metabolic demand, fiber recruitment")
     print()
     
-    print("Step 2: DISSONANCE (OZ) - Metabolic stress")
+    print("Step 3: DISSONANCE (OZ) - Metabolic stress")
     print("  Markers: Lactate, ROS, microdamage (adaptive stimulus)")
     print("  Signal: Triggers remodeling response")
     print()
     
-    print("Step 3: COHERENCE (IL) - Acute homeostatic response")
+    print("Step 4: COHERENCE (IL) - Acute homeostatic response")
     print("  Process: Immediate compensation, metabolite clearance")
+    print("  Training complete - adaptive stimulus applied")
     print()
     
-    run_sequence(G, muscle, [Expansion(), Dissonance(), Coherence()])
-    
-    print("✓ Training complete - Adaptive stimulus applied")
-    print("  Markers: Elevated HR, temperature, fatigue, glycogen depletion")
-    print()
-    
-    # === RECOVERY PHASE ===
-    print("=" * 70)
-    print("RECOVERY PHASE - SHA Adaptation Consolidation")
-    print("=" * 70)
-    print()
-    
-    print("Step 4: SILENCE (SHA) - Recovery period")
-    print("  Context: 48-72 hour recovery period")
+    print("Step 5: SILENCE (SHA) - Recovery period [48-72 hours]")
     print("  Activities: Sleep, nutrition, light movement")
     print("  Effect: νf → 0 (minimal activity), adaptation emerges")
     print("  Process:")
     print("    • Day 1: Residual soreness, metabolite clearance")
     print("    • Day 2: Deep adaptation (protein synthesis peaks)")
-    print("    • Result: EPI increases (structural improvement)")
+    print("    • Result: Structural improvement for next training")
     print()
     
-    run_sequence(G, muscle, [Silence()])
+    # Execute the complete sequence
+    run_sequence(G, muscle, [Emission(), Expansion(), Dissonance(), Coherence(), Silence()])
     
-    print("✓ Recovery complete - Adaptation consolidated")
-    print("  Changes: Muscle protein synthesis, glycogen supercompensation,")
-    print("           mitochondrial biogenesis, neural efficiency")
-    print()
-    
-    # === NEXT TRAINING ===
-    print("=" * 70)
-    print("NEXT TRAINING SESSION - Adapted Baseline")
-    print("=" * 70)
-    print()
-    
-    print("Protocol: NAV → AL (Return to training)")
-    print()
-    
-    print("Step 5: TRANSITION (NAV) - Recovery → Active")
-    print("  Process: Return to normal training readiness")
-    print()
-    
-    print("Step 6: EMISSION (AL) - Next training begins")
-    print("  Context: Training resumes with adapted system")
-    print("  Expected: Improved baseline capacity")
-    print()
-    
-    run_sequence(G, muscle, [Transition(), Emission()])
-    
-    print("✓ Ready for training - Performance capacity increased")
+    print("✓ Recovery complete - Adaptation consolidated, ready for next training")
     print()
     
     # Training applications
@@ -125,28 +85,20 @@ def main():
     print("  • Low frequency: SHA 72-96h+ (adaptation/taper)")
     print()
     print("Overtraining Prevention:")
-    print("  ⚠ Warning: ΔNFR fails to normalize during SHA")
-    print("  → Intervention: Extend SHA, reduce training load")
-    print("  ✓ Recovery: νf normalizes, ΔNFR < 0.10")
-    print()
-    print("Performance Optimization:")
-    print("  • SHA timing: Match recovery to adaptation timeline")
-    print("  • SHA quality: Lower EPI variance = better recovery")
-    print("  • Return criteria: Low ΔNFR + normalized νf")
+    print("  ⚠ Warning: Inadequate SHA leads to accumulated stress")
+    print("  ✓ Solution: Extend SHA, reduce training load")
     
     # Physiological correlates
     print()
     print("=" * 70)
     print("PHYSIOLOGICAL CORRELATES")
     print("=" * 70)
     print()
-    print("TNFR Metric → Physiological Marker → Measurement")
+    print("TNFR Metric → Physiological Marker")
     print("-" * 70)
-    print("SHA activation   → Recovery mode        → HRV, resting HR")
-    print("νf reduction     → Metabolic downreg    → VO2, RMR")
-    print("EPI growth       → Structural adaptation → Muscle cross-section")
-    print("ΔNFR normal      → Stress clearance     → Cortisol, CK, IL-6")
-    print("SHA duration     → Recovery time        → Performance tests")
+    print("SHA activation   → Recovery mode (HRV, resting HR)")
+    print("νf reduction     → Metabolic downregulation (VO2, RMR)")
+    print("EPI growth       → Structural adaptation (performance gains)")
     
     print()
     print("=" * 70)
@@ -155,9 +107,8 @@ def main():
     print("\nSHA enables training adaptation through:")
     print("  1. Reduced activity (νf → 0) = metabolic downregulation")
     print("  2. Structure evolution (EPI increases) = adaptation emerges")
-    print("  3. Pressure normalization (ΔNFR decreases) = recovery complete")
     print("\nWithout adequate SHA (recovery), training stress accumulates")
-    print("without adaptation, leading to overtraining and performance decline.")
+    print("without adaptation, leading to overtraining and decline.")
     
     print("\n" + "=" * 70)
     print("PROTOCOL COMPLETE")
diff --git a/examples/biomedical/sleep_consolidation_sha.py b/examples/biomedical/sleep_consolidation_sha.py
@@ -3,10 +3,9 @@
 This example demonstrates SHA (Silence) modeling sleep-dependent memory
 consolidation, showing how structural pause enables learning retention.
 
-Protocol: [Day] AL → IL → SHA → [Night continues SHA] → [Next Day] NAV → AL
-- Day learning: Emission + Coherence (pattern acquisition)
-- Night sleep: Silence (νf → 0, EPI preserved - consolidation)
-- Next day: Transition + Emission (memory recall)
+Protocol: [Day] AL → IL → SHA
+- Day learning: Emission + Coherence (pattern acquisition + SHA consolidation)
+- Models sleep consolidation through structural pause
 
 Key insight: SHA models deep slow-wave sleep where neuronal firing decreases
 dramatically (νf → 0) while learned patterns (EPI) are preserved intact.
@@ -16,7 +15,7 @@
 - See: docs/source/examples/SHA_CLINICAL_APPLICATIONS.md, Section 3
 """
 
-from tnfr.operators.definitions import Emission, Coherence, Silence, Transition
+from tnfr.operators.definitions import Emission, Coherence, Silence
 from tnfr.structural import create_nfr, run_sequence
 
 
@@ -31,69 +30,37 @@ def main():
     # Create learning neuron node
     G, neuron = create_nfr("learning_neuron", epi=0.20, vf=1.20)
     
-    # === DAY: ACTIVE LEARNING ===
+    # === DAY: LEARNING + SLEEP CONSOLIDATION ===
     print("=" * 70)
-    print("DAY - ACTIVE LEARNING PHASE")
+    print("LEARNING → SLEEP CONSOLIDATION CYCLE")
     print("=" * 70)
     print()
     
-    print("Protocol: AL → IL (Learning sequence)")
+    print("Protocol: AL → IL → SHA")
     print()
     
-    print("Step 1: EMISSION (AL) - New information presented")
+    print("Step 1: EMISSION (AL) - New information presented [DAY]")
     print("  Student encounters new concept, neural activation begins")
-    print()
-    
-    print("Step 2: COHERENCE (IL) - Pattern stabilizes")
     print("  Synaptic integration, early LTP formation")
-    print("  Pattern begins to cohere, initial memory trace formed")
-    print()
-    
-    run_sequence(G, neuron, [Emission(), Coherence()])
-    
-    print("✓ Learning complete - Pattern acquired")
     print()
     
-    # === NIGHT: SLEEP CONSOLIDATION ===
-    print("=" * 70)
-    print("NIGHT - SLEEP CONSOLIDATION (SHA)")
-    print("=" * 70)
+    print("Step 2: COHERENCE (IL) - Pattern stabilizes [DAY]")
+    print("  Pattern coheres, initial memory trace formed")
+    print("  Learning complete - ready for sleep consolidation")
     print()
     
-    print("Step 3: SILENCE (SHA) - Deep sleep structural pause")
+    print("Step 3: SILENCE (SHA) - Sleep consolidation [NIGHT]")
     print("  Context: Deep slow-wave sleep (stages 3-4)")
-    print("  Duration: 6-8 hours (typical sleep period)")
+    print("  Duration: 6-8 hours")
     print("  Neural correlate: δ waves (0.5-4 Hz)")
-    print("  Effect: νf → 0 (minimal firing), EPI preserved (pattern intact)")
+    print("  Effect: νf → 0 (minimal firing), EPI preserved")
     print("  Process: Synaptic consolidation without interference")
     print()
     
-    run_sequence(G, neuron, [Silence()])
-    
-    print("✓ Sleep consolidation complete - Memory preserved")
-    print()
-    
-    # === NEXT DAY: MEMORY RECALL ===
-    print("=" * 70)
-    print("NEXT DAY - MEMORY REACTIVATION")
-    print("=" * 70)
-    print()
-    
-    print("Protocol: NAV → AL (Wake and recall)")
-    print()
-    
-    print("Step 4: TRANSITION (NAV) - Sleep → wake transition")
-    print("  Process: Awakening, neuronal activity increases")
-    print()
-    
-    print("Step 5: EMISSION (AL) - Memory recall initiated")
-    print("  Context: Student attempts to recall learned material")
-    print("  Effect: Pattern retrieved with high fidelity")
-    print()
-    
-    run_sequence(G, neuron, [Transition(), Emission()])
+    # Execute the complete sequence
+    run_sequence(G, neuron, [Emission(), Coherence(), Silence()])
     
-    print("✓ Recall complete - Memory successfully retrieved")
+    print("✓ Consolidation complete - Memory preserved through sleep")
     print()
     
     # Neuroscientific correlates
@@ -106,7 +73,6 @@ def main():
     print("SHA activation   → SWS onset           → δ waves (0.5-4 Hz)")
     print("νf → 0           → Reduced firing      → Single-unit recordings")
     print("EPI preservation → Synaptic maintain   → LTP stability")
-    print("ΔNFR inactive    → Reduced interference → Memory stability tests")
     print("SHA duration     → Sleep stage duration → Polysomnography")
     
     # Research applications
@@ -132,7 +98,7 @@ def main():
     print("\nSHA models sleep's role in memory through:")
     print("  1. Minimal reorganization (νf → 0) = reduced neural activity")
     print("  2. Pattern preservation (EPI intact) = memory maintained")
-    print("  3. Interference prevention (ΔNFR inactive) = no disruption")
+    print("  3. Interference prevention = no disruption during consolidation")
     print("\nThis explains why sleep is essential for learning: structural")
     print("pause allows patterns to consolidate without interference.")
     
diff --git a/src/tnfr/operators/definitions.py b/src/tnfr/operators/definitions.py
@@ -2194,6 +2194,27 @@ class Silence(Operator):
     Coherence : Often precedes SHA for stable preservation
     Transition : Breaks silence with controlled change
     Emission : Reactivates silenced structures
+    
+    Extended Clinical Documentation
+    --------------------------------
+    For detailed clinical protocols, expected telemetry, physiological correlates,
+    and scientific references, see:
+    
+    **docs/source/examples/SHA_CLINICAL_APPLICATIONS.md**
+    
+    Comprehensive documentation includes:
+    - Cardiac Coherence Training (HRV consolidation)
+    - Trauma Therapy (protective containment)
+    - Sleep & Memory Consolidation (neuroscience applications)
+    - Post-Exercise Recovery (athletic training)
+    - Meditation & Mindfulness (contemplative practices)
+    - Organizational Strategy (strategic pause protocols)
+    
+    **Executable Examples**: examples/biomedical/
+    - cardiac_coherence_sha.py
+    - trauma_containment_sha.py
+    - sleep_consolidation_sha.py
+    - recovery_protocols_sha.py
     """
 
     __slots__ = ()
