pmtvs-physics 0.5.0__tar.gz

pmtvs_physics-0.5.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: pmtvs-physics
+Version: 0.5.0
+Summary: Physics analogs for signal manifold analysis
+Author: pmtvs contributors
+License: PolyForm-Strict-1.0.0
+Project-URL: Homepage, https://github.com/pmtvs/pmtvs
+Project-URL: Repository, https://github.com/pmtvs/pmtvs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pmtvs-fractal>=0.5.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

pmtvs_physics-0.5.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pmtvs-physics"
+version = "0.5.0"
+description = "Physics analogs for signal manifold analysis"
+readme = "README.md"
+license = {text = "PolyForm-Strict-1.0.0"}
+authors = [{name = "pmtvs contributors"}]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pmtvs-fractal>=0.5.0",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pmtvs/pmtvs"
+Repository = "https://github.com/pmtvs/pmtvs"
+
+[tool.setuptools.packages.find]
+where = ["python"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pmtvs_physics-0.5.0/python/pmtvs_physics/__init__.py

@@ -0,0 +1,35 @@
+"""
+pmtvs-physics: Physics analogs for signal manifold analysis.
+
+Pure math functions. Arrays in, scalars/arrays out.
+No file IO. No orchestration. No pipeline awareness.
+
+Novel physics analogs applied to manifold departure:
+    Reynolds number → laminar vs turbulent departure
+    Phase transitions → thermodynamic melting of geometric order
+    Dissipation rate → irreversible geometric structure loss
+"""
+
+from .viscosity import hurst_viscosity
+from .momentum import (
+    compute_momentum,
+    compute_reynolds_analog,
+    classify_flow_regime,
+    compute_dissipation_rate,
+)
+from .thermodynamics import (
+    detect_phase_transition,
+    free_energy_slope,
+)
+
+__all__ = [
+    "hurst_viscosity",
+    "compute_momentum",
+    "compute_reynolds_analog",
+    "classify_flow_regime",
+    "compute_dissipation_rate",
+    "detect_phase_transition",
+    "free_energy_slope",
+]
+
+BACKEND = "python"

pmtvs_physics-0.5.0/python/pmtvs_physics/momentum.py

@@ -0,0 +1,133 @@
+"""
+Momentum, Reynolds analog, and dissipation rate
+for manifold departure flow.
+"""
+
+import numpy as np
+
+
+def compute_momentum(
+    velocity_magnitude: float,
+    effective_dim:      float,
+) -> float:
+    """
+    Momentum analog for manifold departure.
+
+    momentum = velocity_magnitude × effective_dim
+
+    effective_dim acts as the "mass" of the system:
+    a system moving in higher-dimensional feature space
+    has more inertia — harder to stop or redirect.
+
+    Args:
+        velocity_magnitude: speed of departure (L2 norm of
+                             feature vector velocity)
+        effective_dim:      participation ratio from eigendecomp
+                             measures dimensionality of motion
+
+    Returns:
+        float >= 0 — momentum analog
+        NaN if inputs are invalid
+    """
+    v = float(velocity_magnitude)
+    m = float(effective_dim)
+    if np.isnan(v) or np.isnan(m) or v < 0 or m < 0:
+        return float('nan')
+    return v * m
+
+
+def compute_reynolds_analog(
+    momentum:  float,
+    viscosity: float,
+    epsilon:   float = 1e-10,
+) -> float:
+    """
+    Reynolds number analog for manifold departure flow.
+
+    Re = momentum / viscosity
+       = (velocity × effective_dim) / Hurst_departure
+
+    Interpretation:
+        Re >> 1: turbulent departure — likely irreversible
+        Re << 1: laminar departure — system may recover
+        Re ≈ 1:  transitional — critical region
+
+    Novel: no existing literature applies Reynolds number
+    to manifold-geometric system monitoring.
+
+    Args:
+        momentum:   momentum analog (from compute_momentum)
+        viscosity:  viscosity analog (from hurst_viscosity)
+        epsilon:    floor for viscosity to avoid division by zero
+
+    Returns:
+        float >= 0 — Reynolds analog
+        NaN if momentum is NaN or invalid
+    """
+    m = float(momentum)
+    v = float(viscosity)
+    if np.isnan(m) or m < 0:
+        return float('nan')
+    if np.isnan(v) or v < 0:
+        v = epsilon
+    return m / max(v, epsilon)
+
+
+def classify_flow_regime(
+    reynolds_analog:     float,
+    laminar_threshold:   float = 1.0,
+    turbulent_threshold: float = 10.0,
+) -> str:
+    """
+    Classify departure flow regime from Reynolds analog.
+
+    Args:
+        reynolds_analog:     from compute_reynolds_analog
+        laminar_threshold:   Re below this → laminar
+        turbulent_threshold: Re above this → turbulent
+
+    Returns:
+        'laminar' | 'transitional' | 'turbulent' | 'unknown'
+
+    Note: thresholds are initial estimates.
+    Calibrate against known outcomes on FD001-004.
+    Document calibrated values in CANONICAL_CONFIGS.md.
+    """
+    re = float(reynolds_analog)
+    if np.isnan(re):
+        return 'unknown'
+    if re <= laminar_threshold:
+        return 'laminar'
+    if re > turbulent_threshold:
+        return 'turbulent'
+    return 'transitional'
+
+
+def compute_dissipation_rate(
+    viscosity:          float,
+    velocity_gradient:  float,
+) -> float:
+    """
+    Dissipation rate analog.
+
+    ε = viscosity × velocity_gradient²
+
+    Classical: ε = ν × (∂u/∂x)²  (Navier-Stokes dissipation)
+    In Ørthon: ε = Hurst_departure × (ΔV/Δwindow)²
+
+    Measures how fast the system is losing geometric structure.
+    High dissipation = rapid irreversible departure.
+
+    Args:
+        viscosity:          Hurst-based viscosity analog [0, 1]
+        velocity_gradient:  rate of change of velocity magnitude
+
+    Returns:
+        float >= 0 — dissipation rate analog
+        NaN if viscosity is invalid
+    """
+    v  = float(viscosity)
+    g  = float(velocity_gradient)
+    if np.isnan(v) or v < 0:
+        return float('nan')
+    return v * g * g

pmtvs_physics-0.5.0/python/pmtvs_physics/thermodynamics.py

@@ -0,0 +1,97 @@
+"""
+Thermodynamic phase transition detection for manifold departure.
+"""
+
+import numpy as np
+from typing import Optional
+
+
+def detect_phase_transition(
+    free_energy_series:   np.ndarray,
+    heat_capacity_series: np.ndarray,
+) -> dict:
+    """
+    Detect thermodynamic phase transitions from F = E - TS.
+
+    Two indicators:
+    1. Free energy sign change:
+       F < 0 means entropy dominates energy — geometric
+       structure has "melted." In physical systems this
+       marks a phase transition.
+
+    2. Heat capacity divergence:
+       dE/dT → ∞ near critical point (critical slowing down).
+       Pre-transition warning: Cv peaks BEFORE F goes negative.
+
+    Args:
+        free_energy_series:   time series of F = E - TS values
+        heat_capacity_series: time series of dE/dT values
+
+    Returns:
+        dict with keys:
+            transition_detected:       bool
+            transition_window:         int or None
+            heat_capacity_peak:        float
+            heat_capacity_peak_window: int or None
+            pre_transition_warning:    bool
+                True if Cv peaks before F sign change —
+                early warning of approaching transition
+    """
+    F  = np.asarray(free_energy_series,   dtype=np.float64)
+    Cv = np.asarray(heat_capacity_series, dtype=np.float64)
+
+    # Sign change detection — first window where F < 0
+    transition_window: Optional[int] = None
+    for i in range(len(F)):
+        if np.isfinite(F[i]) and F[i] < 0:
+            transition_window = i
+            break
+
+    # Heat capacity peak
+    finite_cv = [
+        (i, float(v)) for i, v in enumerate(Cv)
+        if np.isfinite(v)
+    ]
+    if finite_cv:
+        peak_idx, peak_val = max(finite_cv, key=lambda x: x[1])
+    else:
+        peak_idx, peak_val = None, float('nan')
+
+    # Pre-transition warning
+    pre_warning = (
+        peak_idx is not None and
+        transition_window is not None and
+        peak_idx < transition_window
+    )
+
+    return {
+        'transition_detected':       transition_window is not None,
+        'transition_window':         transition_window,
+        'heat_capacity_peak':        peak_val,
+        'heat_capacity_peak_window': peak_idx,
+        'pre_transition_warning':    pre_warning,
+    }
+
+
+def free_energy_slope(free_energy_series: np.ndarray) -> float:
+    """
+    Trend slope of free energy series.
+
+    Negative slope → system moving toward phase transition.
+    Positive slope → system moving away from transition.
+
+    Args:
+        free_energy_series: 1D array of F = E - TS values
+
+    Returns:
+        float — slope of linear fit
+        NaN if fewer than 3 finite values
+    """
+    F     = np.asarray(free_energy_series, dtype=np.float64)
+    valid = np.isfinite(F)
+    if valid.sum() < 3:
+        return float('nan')
+    t       = np.arange(len(F))[valid].astype(np.float64)
+    F_valid = F[valid]
+    slope   = np.polyfit(t, F_valid, 1)[0]
+    return float(slope)

pmtvs_physics-0.5.0/python/pmtvs_physics/viscosity.py

@@ -0,0 +1,35 @@
+"""Hurst-based viscosity analog for manifold departure."""
+
+import numpy as np
+from pmtvs_fractal import hurst_exponent
+
+
+def hurst_viscosity(departure_series: np.ndarray) -> float:
+    """
+    Viscosity analog from Hurst exponent of departure series.
+
+    Maps the Hurst exponent to a viscosity-like quantity:
+        H > 0.5: persistent departure (high viscosity)
+                 system resists change — hard to reverse
+        H < 0.5: antipersistent departure (low viscosity)
+                 system oscillates — may recover
+        H = 0.5: random walk (neutral viscosity)
+
+    Returns the Hurst exponent directly as the viscosity analog.
+    Range: [0, 1].
+
+    Args:
+        departure_series: 1D array of departure distances over time
+
+    Returns:
+        float in [0, 1] — viscosity analog
+        NaN if series too short (< 50 observations)
+    """
+    series = np.asarray(departure_series, dtype=np.float64)
+    series = series[np.isfinite(series)]
+    if len(series) < 50:
+        return float('nan')
+    try:
+        return float(hurst_exponent(series))
+    except Exception:
+        return float('nan')

pmtvs_physics-0.5.0/python/pmtvs_physics.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: pmtvs-physics
+Version: 0.5.0
+Summary: Physics analogs for signal manifold analysis
+Author: pmtvs contributors
+License: PolyForm-Strict-1.0.0
+Project-URL: Homepage, https://github.com/pmtvs/pmtvs
+Project-URL: Repository, https://github.com/pmtvs/pmtvs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pmtvs-fractal>=0.5.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

pmtvs_physics-0.5.0/python/pmtvs_physics.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+pyproject.toml
+python/pmtvs_physics/__init__.py
+python/pmtvs_physics/momentum.py
+python/pmtvs_physics/thermodynamics.py
+python/pmtvs_physics/viscosity.py
+python/pmtvs_physics.egg-info/PKG-INFO
+python/pmtvs_physics.egg-info/SOURCES.txt
+python/pmtvs_physics.egg-info/dependency_links.txt
+python/pmtvs_physics.egg-info/requires.txt
+python/pmtvs_physics.egg-info/top_level.txt
+tests/test_momentum.py
+tests/test_thermodynamics.py
+tests/test_viscosity.py

pmtvs_physics-0.5.0/python/pmtvs_physics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pmtvs_physics-0.5.0/python/pmtvs_physics.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pmtvs-fractal>=0.5.0
+numpy>=1.24
+
+[dev]
+pytest>=7.0

pmtvs_physics-0.5.0/python/pmtvs_physics.egg-info/top_level.txt

@@ -0,0 +1 @@
+pmtvs_physics

pmtvs_physics-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pmtvs_physics-0.5.0/tests/test_momentum.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pytest
+from pmtvs_physics import (
+    compute_momentum,
+    compute_reynolds_analog,
+    classify_flow_regime,
+    compute_dissipation_rate,
+)
+
+
+def test_momentum_multiplication():
+    assert compute_momentum(5.0, 3.0) == pytest.approx(15.0)
+    assert compute_momentum(0.0, 3.0) == pytest.approx(0.0)
+    assert compute_momentum(2.5, 4.0) == pytest.approx(10.0)
+
+
+def test_momentum_nan_on_invalid():
+    assert np.isnan(compute_momentum(-1.0, 3.0))
+    assert np.isnan(compute_momentum(float('nan'), 3.0))
+    assert np.isnan(compute_momentum(5.0, float('nan')))
+
+
+def test_reynolds_high_momentum_high_re():
+    re = compute_reynolds_analog(100.0, 0.5)
+    assert re > 10.0, f"High momentum should give Re > 10, got {re:.2f}"
+
+
+def test_reynolds_high_viscosity_low_re():
+    re = compute_reynolds_analog(1.0, 0.9)
+    assert re < 2.0, f"High viscosity should give Re < 2, got {re:.2f}"
+
+
+def test_reynolds_nan_viscosity_uses_epsilon():
+    """NaN viscosity falls back to epsilon — should not raise."""
+    re = compute_reynolds_analog(5.0, float('nan'))
+    assert np.isfinite(re), "NaN viscosity should use epsilon fallback"
+    assert re > 0
+
+
+def test_reynolds_nan_momentum_returns_nan():
+    assert np.isnan(compute_reynolds_analog(float('nan'), 0.5))
+
+
+def test_flow_regime_classification():
+    assert classify_flow_regime(0.5)         == 'laminar'
+    assert classify_flow_regime(5.0)         == 'transitional'
+    assert classify_flow_regime(50.0)        == 'turbulent'
+    assert classify_flow_regime(float('nan')) == 'unknown'
+
+
+def test_flow_regime_boundaries():
+    assert classify_flow_regime(1.0)  == 'laminar'       # at threshold
+    assert classify_flow_regime(10.0) == 'transitional'  # at threshold
+    assert classify_flow_regime(10.1) == 'turbulent'
+
+
+def test_dissipation_formula():
+    d = compute_dissipation_rate(0.7, 2.0)
+    assert d == pytest.approx(0.7 * 4.0)  # 0.7 × 2² = 2.8
+
+
+def test_dissipation_zero_gradient():
+    assert compute_dissipation_rate(0.7, 0.0) == pytest.approx(0.0)
+
+
+def test_dissipation_nan_viscosity():
+    assert np.isnan(compute_dissipation_rate(float('nan'), 2.0))

pmtvs_physics-0.5.0/tests/test_thermodynamics.py

@@ -0,0 +1,66 @@
+import numpy as np
+import pytest
+from pmtvs_physics import detect_phase_transition, free_energy_slope
+
+
+def test_sign_change_detected():
+    F  = np.array([5.0, 3.0, 1.0, -0.5, -2.0])
+    Cv = np.array([0.1, 0.2, 0.5,  0.3,  0.1])
+    r  = detect_phase_transition(F, Cv)
+    assert r['transition_detected']
+    assert r['transition_window'] == 3
+
+
+def test_pre_transition_warning():
+    """Cv peaks at window 1, F goes negative at window 3."""
+    F  = np.array([5.0, 3.0, 1.0, -0.5, -2.0])
+    Cv = np.array([0.1, 2.5, 0.3,  0.1,  0.1])
+    r  = detect_phase_transition(F, Cv)
+    assert r['pre_transition_warning']
+    assert r['heat_capacity_peak_window'] == 1
+    assert r['transition_window'] == 3
+
+
+def test_no_transition_when_f_positive():
+    F  = np.array([5.0, 4.0, 3.0, 2.0, 1.0])
+    Cv = np.array([0.1, 0.1, 0.1, 0.1, 0.1])
+    r  = detect_phase_transition(F, Cv)
+    assert not r['transition_detected']
+    assert r['transition_window'] is None
+    assert not r['pre_transition_warning']
+
+
+def test_immediate_transition():
+    """F is negative from the first window."""
+    F  = np.array([-1.0, -2.0, -3.0])
+    Cv = np.array([ 0.1,  0.1,  0.1])
+    r  = detect_phase_transition(F, Cv)
+    assert r['transition_detected']
+    assert r['transition_window'] == 0
+
+
+def test_free_energy_slope_negative():
+    """Declining F should have negative slope."""
+    F = np.array([5.0, 3.0, 1.0, -1.0, -3.0])
+    s = free_energy_slope(F)
+    assert s < 0, f"Declining F should have negative slope, got {s}"
+
+
+def test_free_energy_slope_positive():
+    """Rising F should have positive slope."""
+    F = np.array([-3.0, -1.0, 1.0, 3.0, 5.0])
+    s = free_energy_slope(F)
+    assert s > 0, f"Rising F should have positive slope, got {s}"
+
+
+def test_free_energy_slope_short_series():
+    """Fewer than 3 finite values → NaN."""
+    assert np.isnan(free_energy_slope(np.array([1.0, 2.0])))
+    assert np.isnan(free_energy_slope(np.array([float('nan')] * 5)))
+
+
+def test_nan_in_free_energy_handled():
+    """NaN values in F are skipped for slope computation."""
+    F = np.array([5.0, float('nan'), 1.0, float('nan'), -3.0])
+    s = free_energy_slope(F)
+    assert np.isfinite(s), "Should compute slope on finite values"

pmtvs_physics-0.5.0/tests/test_viscosity.py

@@ -0,0 +1,40 @@
+import numpy as np
+import pytest
+from pmtvs_physics import hurst_viscosity
+
+
+def test_persistent_series_high_viscosity():
+    """Trending series has H close to 1 — high viscosity."""
+    series = np.cumsum(np.ones(200))
+    v = hurst_viscosity(series)
+    assert not np.isnan(v), "Should not be NaN for 200-pt series"
+    assert v > 0.7, f"Trend should have H > 0.7, got {v:.3f}"
+
+
+def test_short_series_returns_nan():
+    """Series shorter than 50 observations → NaN."""
+    assert np.isnan(hurst_viscosity(np.ones(10)))
+    assert np.isnan(hurst_viscosity(np.array([])))
+    assert np.isnan(hurst_viscosity(np.ones(49)))
+
+
+def test_output_in_unit_interval():
+    """All valid outputs must be in [0, 1]."""
+    rng = np.random.default_rng(42)
+    for _ in range(10):
+        n      = rng.integers(50, 300)
+        series = rng.normal(0, 1, n)
+        v      = hurst_viscosity(series)
+        if not np.isnan(v):
+            assert 0.0 <= v <= 1.0, f"H={v:.4f} outside [0,1]"
+
+
+def test_nan_in_series_handled():
+    """NaN values in input are stripped before computation."""
+    rng    = np.random.default_rng(42)
+    series = rng.normal(0, 1, 200).tolist()
+    series[10] = float('nan')
+    series[50] = float('nan')
+    v = hurst_viscosity(np.array(series))
+    # Should still compute on the 198 finite values
+    assert not np.isnan(v)