tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/operators/remesh.pyi

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._compat import TypeAlias
+
+__all__ = [
+    "apply_network_remesh",
+    "apply_topological_remesh",
+    "apply_remesh_if_globally_stable",
+]
+
+CommunityGraph: TypeAlias = Any
+
+def apply_network_remesh(G: CommunityGraph) -> None: ...
+def apply_topological_remesh(
+    G: CommunityGraph,
+    mode: str | None = None,
+    *,
+    k: int | None = None,
+    p_rewire: float = 0.2,
+    seed: int | None = None,
+) -> None: ...
+def apply_remesh_if_globally_stable(
+    G: CommunityGraph, stable_step_window: int | None = None, **kwargs: Any
+) -> None: ...

tnfr/operators/structural_units.py

@@ -0,0 +1,268 @@
+"""Structural units and types for TNFR canonical measurements.
+
+This module provides type-safe wrappers for TNFR structural units,
+ensuring canonical unit enforcement throughout the engine.
+
+Key structural units:
+- Hz_str: Structural hertz (reorganization rate, νf)
+- rad_str: Structural radians (phase, θ)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+__all__ = [
+    "HzStr",
+    "StructuralFrequency",
+    "ensure_hz_str",
+    "hz_to_hz_str",
+]
+
+# Default tolerance for structural frequency validation
+MIN_STRUCTURAL_FREQUENCY = 0.0
+
+
+class HzStr:
+    """Structural frequency in Hz_str (structural hertz) units.
+
+    Hz_str represents the rate of structural reorganization, not physical
+    frequency. It measures how rapidly a node's Primary Information Structure
+    (EPI) evolves according to the nodal equation:
+
+        ∂EPI/∂t = νf · ΔNFR(t)
+
+    Where νf is the structural frequency in Hz_str units.
+
+    Attributes
+    ----------
+    value : float
+        Magnitude of the structural frequency
+    unit : str
+        Always "Hz_str" to maintain unit clarity
+
+    Notes
+    -----
+    Hz_str is distinct from physical Hz (cycles per second). It represents
+    the rate of structural change in TNFR's reorganization phase space.
+    Conversion from physical Hz depends on the domain context (biological,
+    quantum, social, etc.).
+    """
+
+    __slots__ = ("value", "unit")
+
+    def __init__(self, value: float) -> None:
+        """Initialize structural frequency.
+
+        Parameters
+        ----------
+        value : float
+            Structural frequency magnitude (must be non-negative)
+
+        Raises
+        ------
+        ValueError
+            If value is negative (structural frequencies are non-negative)
+        """
+        if value < MIN_STRUCTURAL_FREQUENCY:
+            raise ValueError(
+                f"Structural frequency must be >= {MIN_STRUCTURAL_FREQUENCY} Hz_str, got {value}"
+            )
+        self.value = float(value)
+        self.unit = "Hz_str"
+
+    def __float__(self) -> float:
+        """Convert to float for numerical operations."""
+        return self.value
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"HzStr({self.value})"
+
+    def __str__(self) -> str:
+        """Human-readable string."""
+        return f"{self.value} Hz_str"
+
+    def __eq__(self, other: Any) -> bool:
+        """Equality comparison."""
+        if isinstance(other, HzStr):
+            return abs(self.value - other.value) < 1e-10
+        if isinstance(other, (int, float)):
+            return abs(self.value - float(other)) < 1e-10
+        return NotImplemented
+
+    def __lt__(self, other: Any) -> bool:
+        """Less than comparison."""
+        if isinstance(other, HzStr):
+            return self.value < other.value
+        if isinstance(other, (int, float)):
+            return self.value < float(other)
+        return NotImplemented
+
+    def __le__(self, other: Any) -> bool:
+        """Less than or equal comparison."""
+        if isinstance(other, HzStr):
+            return self.value <= other.value
+        if isinstance(other, (int, float)):
+            return self.value <= float(other)
+        return NotImplemented
+
+    def __gt__(self, other: Any) -> bool:
+        """Greater than comparison."""
+        if isinstance(other, HzStr):
+            return self.value > other.value
+        if isinstance(other, (int, float)):
+            return self.value > float(other)
+        return NotImplemented
+
+    def __ge__(self, other: Any) -> bool:
+        """Greater than or equal comparison."""
+        if isinstance(other, HzStr):
+            return self.value >= other.value
+        if isinstance(other, (int, float)):
+            return self.value >= float(other)
+        return NotImplemented
+
+    def __add__(self, other: Any) -> HzStr:
+        """Addition."""
+        if isinstance(other, HzStr):
+            return HzStr(self.value + other.value)
+        if isinstance(other, (int, float)):
+            return HzStr(self.value + float(other))
+        return NotImplemented
+
+    def __radd__(self, other: Any) -> HzStr:
+        """Right addition."""
+        return self.__add__(other)
+
+    def __sub__(self, other: Any) -> HzStr:
+        """Subtraction."""
+        if isinstance(other, HzStr):
+            return HzStr(self.value - other.value)
+        if isinstance(other, (int, float)):
+            return HzStr(self.value - float(other))
+        return NotImplemented
+
+    def __rsub__(self, other: Any) -> HzStr:
+        """Right subtraction."""
+        if isinstance(other, (int, float)):
+            return HzStr(float(other) - self.value)
+        return NotImplemented
+
+    def __mul__(self, other: Any) -> Union[HzStr, float]:
+        """Multiplication.
+
+        When multiplied by another HzStr or dimensionless number, returns HzStr.
+        When multiplied by ΔNFR (dimensionless), returns float (∂EPI/∂t rate).
+        """
+        if isinstance(other, HzStr):
+            return HzStr(self.value * other.value)
+        if isinstance(other, (int, float)):
+            # This is typically νf · ΔNFR in nodal equation
+            return self.value * float(other)
+        return NotImplemented
+
+    def __rmul__(self, other: Any) -> Union[HzStr, float]:
+        """Right multiplication."""
+        return self.__mul__(other)
+
+    def __truediv__(self, other: Any) -> HzStr:
+        """Division."""
+        if isinstance(other, HzStr):
+            return HzStr(self.value / other.value)
+        if isinstance(other, (int, float)):
+            if other == 0:
+                raise ZeroDivisionError(
+                    f"Cannot divide structural frequency {self.value} Hz_str by zero"
+                )
+            return HzStr(self.value / float(other))
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        """Hash for use in sets/dicts."""
+        return hash((self.value, self.unit))
+
+
+# Alias for clarity in type hints
+StructuralFrequency = HzStr
+
+
+def ensure_hz_str(value: Union[float, HzStr]) -> HzStr:
+    """Ensure value is in Hz_str units.
+
+    Parameters
+    ----------
+    value : float or HzStr
+        Value to convert to Hz_str
+
+    Returns
+    -------
+    HzStr
+        Value as structural frequency
+
+    Examples
+    --------
+    >>> ensure_hz_str(1.5)
+    HzStr(1.5)
+    >>> ensure_hz_str(HzStr(2.0))
+    HzStr(2.0)
+    """
+    if isinstance(value, HzStr):
+        return value
+    return HzStr(float(value))
+
+
+def hz_to_hz_str(
+    hz_value: float,
+    context: str = "default",
+) -> HzStr:
+    """Convert physical Hz to structural Hz_str with domain-specific scaling.
+
+    Different physical domains have different relationships between physical
+    frequency and structural reorganization rate. This function provides
+    context-aware conversion factors.
+
+    Parameters
+    ----------
+    hz_value : float
+        Physical frequency in Hz (cycles per second)
+    context : str, default "default"
+        Domain context for conversion:
+        - "default": Direct 1:1 mapping
+        - "biological": Biological systems (slower structural reorganization)
+        - "quantum": Quantum systems (faster structural reorganization)
+        - "social": Social systems (much slower structural reorganization)
+        - "neural": Neural systems (moderate structural reorganization)
+
+    Returns
+    -------
+    HzStr
+        Structural frequency in Hz_str units
+
+    Notes
+    -----
+    Conversion factors are based on typical timescales in each domain:
+    - Biological: 0.1 (10 Hz physical → 1 Hz_str)
+    - Quantum: 1e12 (1 Hz physical → 1 THz_str)
+    - Social: 1e-6 (1 MHz physical → 1 Hz_str)
+    - Neural: 1.0 (1 Hz physical → 1 Hz_str, matched to firing rates)
+
+    Examples
+    --------
+    >>> hz_to_hz_str(10.0, "biological")
+    HzStr(1.0)
+    >>> hz_to_hz_str(1.0, "quantum")
+    HzStr(1000000000000.0)
+    """
+    CONVERSION_FACTORS = {
+        "default": 1.0,
+        "biological": 0.1,
+        "quantum": 1e12,
+        "social": 1e-6,
+        "neural": 1.0,
+    }
+
+    factor = CONVERSION_FACTORS.get(context, 1.0)
+    hz_str_value = hz_value * factor
+
+    return HzStr(hz_str_value)

tnfr/operators/unified_grammar.py

@@ -0,0 +1,105 @@
+"""Unified TNFR Grammar - Facade to GrammarValidator.
+
+This module provides a clean facade to the canonical grammar validation
+implemented in grammar.py. It exports the unified grammar constraints (U1-U4)
+and the validator for use in tests and applications.
+
+All grammar rules derive inevitably from TNFR physics:
+- U1: STRUCTURAL INITIATION & CLOSURE
+- U2: CONVERGENCE & BOUNDEDNESS  
+- U3: RESONANT COUPLING
+- U4: BIFURCATION DYNAMICS (U4a: triggers, U4b: transformers)
+
+References
+----------
+- UNIFIED_GRAMMAR_RULES.md: Complete physics derivations
+- AGENTS.md: Canonical invariants and formal contracts
+- TNFR.pdf: Nodal equation and bifurcation theory
+
+Notes
+-----
+This is a facade module that re-exports from grammar.py for clean imports.
+The actual implementation is in grammar.py::GrammarValidator.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from .definitions import Operator
+
+# Import validator class and rename for clarity
+from .grammar import GrammarValidator as UnifiedGrammarValidator
+
+# Import operator sets (canonical definitions from grammar.py)
+from .grammar import (
+    BIFURCATION_HANDLERS,
+    BIFURCATION_TRIGGERS,
+    CLOSURES,
+    COUPLING_RESONANCE,
+    DESTABILIZERS,
+    GENERATORS,
+    STABILIZERS,
+    TRANSFORMERS,
+)
+
+# Import validation functions
+from .grammar import validate_grammar
+
+__all__ = [
+    # Validator class
+    "UnifiedGrammarValidator",
+    # Convenience function
+    "validate_unified",
+    # Operator sets (U1-U4 categories)
+    "GENERATORS",
+    "CLOSURES",
+    "STABILIZERS",
+    "DESTABILIZERS",
+    "COUPLING_RESONANCE",
+    "BIFURCATION_TRIGGERS",
+    "BIFURCATION_HANDLERS",
+    "TRANSFORMERS",
+]
+
+
+def validate_unified(
+    sequence: List["Operator"],
+    epi_initial: float = 0.0,
+) -> bool:
+    """Validate sequence using unified TNFR grammar (U1-U4).
+
+    Convenience function that returns only boolean result.
+    For detailed messages, use UnifiedGrammarValidator.validate().
+
+    Parameters
+    ----------
+    sequence : List[Operator]
+        Sequence of operators to validate
+    epi_initial : float, optional
+        Initial EPI value (default: 0.0)
+
+    Returns
+    -------
+    bool
+        True if sequence satisfies all U1-U4 constraints
+
+    Examples
+    --------
+    >>> from tnfr.operators.definitions import Emission, Coherence, Silence
+    >>> from tnfr.operators.unified_grammar import validate_unified
+    >>> ops = [Emission(), Coherence(), Silence()]
+    >>> validate_unified(ops, epi_initial=0.0)  # doctest: +SKIP
+    True
+
+    Notes
+    -----
+    This validator is 100% physics-based. All constraints emerge from:
+    - Nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+    - TNFR invariants (AGENTS.md)
+    - Formal operator contracts
+
+    See UNIFIED_GRAMMAR_RULES.md for complete derivations.
+    """
+    return validate_grammar(sequence, epi_initial)

tnfr/parallel/__init__.py

@@ -0,0 +1,54 @@
+"""Parallel and distributed computation engines for TNFR networks.
+
+This module provides parallelization strategies that respect TNFR's structural
+coherence while enabling efficient computation on large networks. All parallel
+implementations preserve the canonical nodal equation and operator closure.
+
+Key components:
+- FractalPartitioner: Partitions networks using coherence-based communities
+- TNFRParallelEngine: Multiprocessing/threading engine for medium networks
+- TNFRDistributedEngine: Optional Ray/Dask backend for massive networks
+- TNFRGPUEngine: Optional GPU acceleration via JAX/CuPy
+- TNFRAutoScaler: Recommends optimal execution strategy
+- ParallelExecutionMonitor: Real-time performance tracking
+
+All engines maintain TNFR invariants:
+- EPI changes only via structural operators
+- νf expressed in Hz_str (structural hertz)
+- ΔNFR semantics preserved (not reinterpreted as ML gradient)
+- Operator closure maintained
+- Phase synchrony verification
+- Operational fractality preserved
+"""
+
+from __future__ import annotations
+
+# Import all core components
+from .partitioner import FractalPartitioner
+from .engine import TNFRParallelEngine
+from .auto_scaler import TNFRAutoScaler
+from .monitoring import ParallelExecutionMonitor, PerformanceMetrics
+
+__all__ = (
+    "FractalPartitioner",
+    "TNFRParallelEngine",
+    "TNFRAutoScaler",
+    "ParallelExecutionMonitor",
+    "PerformanceMetrics",
+)
+
+# Optional distributed backends
+try:
+    from .distributed import TNFRDistributedEngine
+
+    __all__ = __all__ + ("TNFRDistributedEngine",)
+except ImportError:
+    pass
+
+# Optional GPU backend
+try:
+    from .gpu_engine import TNFRGPUEngine
+
+    __all__ = __all__ + ("TNFRGPUEngine",)
+except ImportError:
+    pass

tnfr/parallel/auto_scaler.py

@@ -0,0 +1,234 @@
+"""Auto-scaling and execution strategy recommendation for TNFR computations.
+
+Recommends optimal execution strategies based on network size, available
+resources, and hardware capabilities.
+"""
+
+from __future__ import annotations
+
+from multiprocessing import cpu_count
+from typing import Any, Dict
+
+
+class TNFRAutoScaler:
+    """Auto-scaler for TNFR parallel execution strategies.
+
+    Analyzes network characteristics and system resources to recommend optimal
+    execution strategies (sequential, multiprocessing, GPU, or distributed).
+
+    Examples
+    --------
+    >>> from tnfr.parallel import TNFRAutoScaler
+    >>> scaler = TNFRAutoScaler()
+    >>> strategy = scaler.recommend_execution_strategy(
+    ...     graph_size=500,
+    ...     available_memory_gb=8.0,
+    ...     has_gpu=False
+    ... )
+    >>> strategy['backend'] in ['sequential', 'multiprocessing']
+    True
+    """
+
+    def __init__(self):
+        self.performance_history: Dict[str, Any] = {}
+        self.optimal_configs: Dict[str, Any] = {}
+
+    def recommend_execution_strategy(
+        self,
+        graph_size: int,
+        available_memory_gb: float = 8.0,
+        has_gpu: bool = False,
+    ) -> Dict[str, Any]:
+        """Recommend optimal execution strategy for given configuration.
+
+        Parameters
+        ----------
+        graph_size : int
+            Number of nodes in the network
+        available_memory_gb : float, default=8.0
+            Available system memory in gigabytes
+        has_gpu : bool, default=False
+            Whether GPU acceleration is available
+
+        Returns
+        -------
+        Dict[str, Any]
+            Strategy recommendation with keys:
+            - backend: str (sequential/multiprocessing/gpu/distributed)
+            - workers: int (recommended worker count)
+            - explanation: str (reasoning)
+            - estimated_time_minutes: float (expected duration)
+            - estimated_memory_gb: float (expected memory usage)
+
+        Notes
+        -----
+        Strategy selection follows TNFR-aware heuristics:
+        - Small networks (<100): Sequential is fastest (overhead dominates)
+        - Medium networks (100-1000): Multiprocessing optimal
+        - Large networks (1000-10000) with GPU: Vectorized GPU
+        - Massive networks (>10000): Distributed computation required
+        """
+        strategy: Dict[str, Any] = {}
+
+        # Select backend based on size
+        if graph_size < 100:
+            strategy["backend"] = "sequential"
+            strategy["workers"] = 1
+            strategy["explanation"] = (
+                "Small network - sequential processing fastest due to overhead"
+            )
+
+        elif graph_size < 1000:
+            strategy["backend"] = "multiprocessing"
+            strategy["workers"] = min(cpu_count(), graph_size // 50)
+            strategy["explanation"] = (
+                "Medium network - multiprocessing provides optimal speedup"
+            )
+
+        elif graph_size < 10000 and has_gpu:
+            strategy["backend"] = "gpu"
+            strategy["workers"] = 1
+            strategy["gpu_engine"] = "jax"
+            strategy["explanation"] = (
+                "Large network with GPU - vectorized acceleration available"
+            )
+
+        else:
+            strategy["backend"] = "distributed"
+            strategy["workers"] = cpu_count() * 2
+            strategy["chunk_size"] = min(500, graph_size // 20)
+            strategy["explanation"] = (
+                "Massive network - distributed computation recommended"
+            )
+
+        # Estimate memory requirements
+        estimated_memory = self._estimate_memory_usage(graph_size, strategy["backend"])
+        strategy["estimated_memory_gb"] = estimated_memory
+
+        # Check memory constraints
+        if estimated_memory > available_memory_gb * 0.8:
+            strategy["warning"] = (
+                f"Estimated memory ({estimated_memory:.1f}GB) may exceed "
+                f"available memory ({available_memory_gb:.1f}GB)"
+            )
+            strategy["recommendation"] = (
+                "Consider distributed backend or smaller partition sizes"
+            )
+
+        # Estimate execution time
+        estimated_time = self._estimate_execution_time(graph_size, strategy["backend"])
+        strategy["estimated_time_minutes"] = estimated_time
+
+        return strategy
+
+    def _estimate_memory_usage(self, graph_size: int, backend: str) -> float:
+        """Estimate memory usage in gigabytes.
+
+        Parameters
+        ----------
+        graph_size : int
+            Number of nodes
+        backend : str
+            Execution backend
+
+        Returns
+        -------
+        float
+            Estimated memory in GB
+        """
+        # Base memory: ~1KB per node for attributes
+        base_memory_gb = graph_size * 0.001 / 1024
+
+        # Backend multipliers account for overhead
+        backend_multipliers = {
+            "sequential": 1.0,
+            "multiprocessing": 1.5,  # Serialization overhead
+            "gpu": 2.0,  # GPU + CPU copies
+            "distributed": 1.2,  # Network overhead minimal
+        }
+
+        multiplier = backend_multipliers.get(backend, 1.0)
+        return base_memory_gb * multiplier
+
+    def _estimate_execution_time(self, graph_size: int, backend: str) -> float:
+        """Estimate execution time in minutes.
+
+        Parameters
+        ----------
+        graph_size : int
+            Number of nodes
+        backend : str
+            Execution backend
+
+        Returns
+        -------
+        float
+            Estimated time in minutes
+
+        Notes
+        -----
+        Based on empirical observations. Actual times depend on:
+        - Network density (edges per node)
+        - Operator complexity
+        - Hardware specifications
+        - Cache efficiency
+        """
+        # Base time per 1000 nodes (calibrated with benchmarks)
+        base_time_per_1k = {
+            "sequential": 2.0,  # 2 min per 1000 nodes
+            "multiprocessing": 0.5,  # 4x speedup typical
+            "gpu": 0.1,  # 20x speedup on modern GPUs
+            "distributed": 0.2,  # 10x speedup with cluster
+        }
+
+        time_factor = base_time_per_1k.get(backend, 2.0)
+        return (graph_size / 1000.0) * time_factor
+
+    def get_optimization_suggestions(
+        self, performance_metrics: Dict[str, Any]
+    ) -> List[str]:
+        """Generate optimization suggestions based on observed performance.
+
+        Parameters
+        ----------
+        performance_metrics : Dict[str, Any]
+            Performance data from execution monitoring
+
+        Returns
+        -------
+        list[str]
+            List of actionable optimization suggestions
+        """
+        suggestions = []
+
+        # Check parallelization efficiency
+        if "parallelization_efficiency" in performance_metrics:
+            eff = performance_metrics["parallelization_efficiency"]
+            if eff < 0.5:
+                suggestions.append(
+                    "⚡ Low parallelization efficiency - consider reducing "
+                    "worker count or increasing partition size"
+                )
+
+        # Check memory usage
+        if "memory_efficiency" in performance_metrics:
+            mem_eff = performance_metrics["memory_efficiency"]
+            if mem_eff < 0.1:
+                suggestions.append(
+                    "💾 High memory usage - consider distributed execution "
+                    "or memory optimization"
+                )
+
+        # Check throughput
+        if "operations_per_second" in performance_metrics:
+            ops = performance_metrics["operations_per_second"]
+            if ops < 100:
+                suggestions.append(
+                    "📈 Low throughput - consider GPU backend or algorithm "
+                    "optimization"
+                )
+
+        if not suggestions:
+            suggestions.append("✨ Performance looks optimal!")
+
+        return suggestions