convergio 0.1.0__tar.gz

convergio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maximilian Jurak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

convergio-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: convergio
+Version: 0.1.0
+Summary: Automatic convergence detection for iterative numerical methods. Stop wasting compute.
+Author: Maximilian Jurak
+License: MIT
+Project-URL: Homepage, https://github.com/maxjurak/convergio
+Keywords: convergence,simulation,solver,early-stopping,FEM,CFD,optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# Convergio
+
+**Automatic convergence detection for iterative numerical methods.**
+
+Stop wasting compute. One function call tells you if your solver has converged, is oscillating, is stuck between two states, or is diverging.
+
+*"Your solver finished 3000 iterations ago."*
+
+## Install
+
+```bash
+pip install convergio
+```
+
+Only dependency: NumPy.
+
+## Usage
+
+### Analyze a completed run
+
+```python
+from convergio import detect
+
+result = detect(my_residual_history)
+
+print(result.state)        # "converged" | "oscillating" | "bistable" | "diverging"
+print(result.quality)      # 0.0 — 1.0
+print(result.converged_at) # step where convergence was detected
+print(result.n_modes)      # number of distinct stable states
+```
+
+### Monitor a running simulation
+
+```python
+from convergio import watch
+
+mon = watch(var_threshold=1e-6)
+
+for step in range(10000):
+    residual = solver.step()
+    stop, info = mon.step(residual)
+    if stop:
+        print(f"Converged at step {step}")
+        break
+```
+
+## What it detects
+
+| State | Meaning | Recommendation |
+|-------|---------|----------------|
+| `converged` | Signal has stabilized | Stop |
+| `oscillating` | Signal oscillates without settling | Continue or adjust parameters |
+| `bistable` | Signal jumps between 2+ distinct states | Investigate — multiple solutions exist |
+| `diverging` | Variance is growing | Restart with different parameters |
+| `warming_up` | Not enough data yet | Continue |
+
+## Works with
+
+- FEM / CFD solvers (residual monitoring)
+- ML training (loss convergence)
+- Monte Carlo simulations (running averages)
+- Optimization loops (objective function)
+- Molecular dynamics (energy equilibration)
+- Any iterative numerical process that produces a scalar time series
+
+## API
+
+### `detect(signal, window=0, var_threshold=1e-6)`
+
+Analyze a complete time series. Returns `ConvergenceResult`.
+
+### `watch(var_threshold=1e-6, check_every=50, min_steps=100)`
+
+Create a live monitor. Returns `Watch` object. Call `.step(value)` each iteration.
+
+### `ConvergenceResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `state` | str | converged, oscillating, bistable, diverging, warming_up |
+| `quality` | float | 0.0 — 1.0 convergence quality |
+| `converged_at` | int or None | Step where convergence detected |
+| `final_variance` | float | Variance of last window |
+| `oscillation_freq` | float | Detected oscillation frequency |
+| `n_modes` | int | Number of distinct stable states |
+| `recommendation` | str | stop, continue, restart |
+
+## License
+
+MIT
+
+## Author
+
+Maximilian Jurak — 3 Kaiserberge Engineering & Research

convergio-0.1.0/README.md

@@ -0,0 +1,94 @@
+# Convergio
+
+**Automatic convergence detection for iterative numerical methods.**
+
+Stop wasting compute. One function call tells you if your solver has converged, is oscillating, is stuck between two states, or is diverging.
+
+*"Your solver finished 3000 iterations ago."*
+
+## Install
+
+```bash
+pip install convergio
+```
+
+Only dependency: NumPy.
+
+## Usage
+
+### Analyze a completed run
+
+```python
+from convergio import detect
+
+result = detect(my_residual_history)
+
+print(result.state)        # "converged" | "oscillating" | "bistable" | "diverging"
+print(result.quality)      # 0.0 — 1.0
+print(result.converged_at) # step where convergence was detected
+print(result.n_modes)      # number of distinct stable states
+```
+
+### Monitor a running simulation
+
+```python
+from convergio import watch
+
+mon = watch(var_threshold=1e-6)
+
+for step in range(10000):
+    residual = solver.step()
+    stop, info = mon.step(residual)
+    if stop:
+        print(f"Converged at step {step}")
+        break
+```
+
+## What it detects
+
+| State | Meaning | Recommendation |
+|-------|---------|----------------|
+| `converged` | Signal has stabilized | Stop |
+| `oscillating` | Signal oscillates without settling | Continue or adjust parameters |
+| `bistable` | Signal jumps between 2+ distinct states | Investigate — multiple solutions exist |
+| `diverging` | Variance is growing | Restart with different parameters |
+| `warming_up` | Not enough data yet | Continue |
+
+## Works with
+
+- FEM / CFD solvers (residual monitoring)
+- ML training (loss convergence)
+- Monte Carlo simulations (running averages)
+- Optimization loops (objective function)
+- Molecular dynamics (energy equilibration)
+- Any iterative numerical process that produces a scalar time series
+
+## API
+
+### `detect(signal, window=0, var_threshold=1e-6)`
+
+Analyze a complete time series. Returns `ConvergenceResult`.
+
+### `watch(var_threshold=1e-6, check_every=50, min_steps=100)`
+
+Create a live monitor. Returns `Watch` object. Call `.step(value)` each iteration.
+
+### `ConvergenceResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `state` | str | converged, oscillating, bistable, diverging, warming_up |
+| `quality` | float | 0.0 — 1.0 convergence quality |
+| `converged_at` | int or None | Step where convergence detected |
+| `final_variance` | float | Variance of last window |
+| `oscillation_freq` | float | Detected oscillation frequency |
+| `n_modes` | int | Number of distinct stable states |
+| `recommendation` | str | stop, continue, restart |
+
+## License
+
+MIT
+
+## Author
+
+Maximilian Jurak — 3 Kaiserberge Engineering & Research

convergio-0.1.0/convergio/__init__.py

@@ -0,0 +1,412 @@
+"""
+Convergio — Automatic Convergence Detection for Iterative Methods
+================================================================
+Detects convergence, oscillation, bistability, and divergence
+in any numerical time series. One function call. No configuration needed.
+
+Usage:
+    from convergio import detect, watch
+
+    # Analyze a completed run
+    result = detect(my_time_series)
+    print(result.state)        # "converged" | "oscillating" | "bistable" | "diverging"
+    print(result.converged_at) # step where convergence was detected
+    print(result.quality)      # 0.0 - 1.0
+
+    # Monitor a running simulation
+    mon = watch(var_threshold=1e-6)
+    for step in range(10000):
+        value = my_solver_step()
+        should_stop, info = mon.step(value)
+        if should_stop:
+            print(f"Converged at step {step}, saved {10000-step} steps")
+            break
+
+(c) 2026 Maximilian Jurak — 3 Kaiserberge Engineering & Research
+"""
+
+__version__ = "0.1.0"
+__author__ = "Maximilian Jurak"
+
+import numpy as np
+from typing import Optional, Tuple, List, Union
+from dataclasses import dataclass, field
+
+
+# =============================================================
+# Result Object
+# =============================================================
+
+@dataclass
+class ConvergenceResult:
+    """Result of convergence analysis."""
+
+    state: str
+    """One of: 'converged', 'oscillating', 'bistable', 'diverging', 'warming_up'"""
+
+    quality: float
+    """Convergence quality score from 0.0 (no convergence) to 1.0 (perfect)."""
+
+    converged_at: Optional[int]
+    """Step index where convergence was first detected. None if not converged."""
+
+    final_variance: float
+    """Variance of the signal in the last analysis window."""
+
+    oscillation_freq: float
+    """Detected oscillation frequency (0.0 if not oscillating)."""
+
+    n_modes: int
+    """Number of distinct stable modes detected (1 = unimodal, 2+ = multimodal)."""
+
+    recommendation: str
+    """One of: 'stop', 'continue', 'restart'."""
+
+    saved_steps: int = 0
+    """Steps saved by early stopping (0 if not applicable)."""
+
+    total_steps: int = 0
+    """Total steps in the analyzed series."""
+
+    def __repr__(self):
+        return (f"ConvergenceResult(state='{self.state}', quality={self.quality:.2f}, "
+                f"converged_at={self.converged_at}, recommendation='{self.recommendation}')")
+
+
+# =============================================================
+# Core Analysis
+# =============================================================
+
+def rolling_variance(signal: np.ndarray, window: int = 50) -> np.ndarray:
+    """
+    Compute rolling variance of a signal.
+
+    Args:
+        signal: 1D array of values
+        window: window size for variance computation
+
+    Returns:
+        Array of rolling variance values
+    """
+    signal = np.asarray(signal, dtype=float)
+    n = len(signal)
+
+    if n < window:
+        return np.array([np.var(signal)])
+
+    # Efficient rolling variance using cumulative sums
+    result = np.zeros(n - window + 1)
+    for i in range(len(result)):
+        result[i] = np.var(signal[i:i + window])
+
+    return result
+
+
+def count_modes(signal: np.ndarray, n_bins: int = 30) -> int:
+    """
+    Count distinct modes (peaks in distribution) of signal values.
+
+    Args:
+        signal: 1D array of values
+        n_bins: number of histogram bins
+
+    Returns:
+        Number of detected modes (>= 1)
+    """
+    signal = np.asarray(signal, dtype=float)
+
+    if len(signal) < 10:
+        return 1
+
+    hist, _ = np.histogram(signal, bins=n_bins)
+    hist_smooth = np.convolve(hist, [0.25, 0.5, 0.25], mode='same')
+
+    peaks = 0
+    threshold = np.max(hist_smooth) * 0.15
+
+    for i in range(1, len(hist_smooth) - 1):
+        if (hist_smooth[i] > hist_smooth[i - 1] and
+            hist_smooth[i] > hist_smooth[i + 1] and
+            hist_smooth[i] > threshold):
+            peaks += 1
+
+    return max(1, peaks)
+
+
+def detect(
+    signal: Union[list, np.ndarray],
+    window: int = 0,
+    var_threshold: float = 1e-6,
+    osc_threshold: float = 0.3,
+) -> ConvergenceResult:
+    """
+    Analyze a time series for convergence.
+
+    This is the main entry point. Pass any 1D numerical time series
+    and get back a complete convergence analysis.
+
+    Args:
+        signal: 1D array of scalar values (residuals, energies, loss, etc.)
+        window: analysis window size (0 = auto, typically 5-10% of signal length)
+        var_threshold: variance below this = converged
+        osc_threshold: zero-crossing frequency above this = oscillating
+
+    Returns:
+        ConvergenceResult with state, quality, recommendation, etc.
+
+    Examples:
+        >>> import numpy as np
+        >>> from convergio import detect
+        >>>
+        >>> # Converging signal
+        >>> signal = np.exp(-np.linspace(0, 5, 1000)) + np.random.randn(1000) * 0.001
+        >>> result = detect(signal)
+        >>> result.state
+        'converged'
+        >>>
+        >>> # Oscillating signal
+        >>> signal = np.sin(np.linspace(0, 50, 1000))
+        >>> result = detect(signal)
+        >>> result.state
+        'oscillating'
+    """
+    signal = np.asarray(signal, dtype=float)
+    n = len(signal)
+
+    # Auto window size
+    if window <= 0:
+        window = max(10, min(200, n // 10))
+
+    # Not enough data
+    if n < window * 2:
+        return ConvergenceResult(
+            state="warming_up",
+            quality=0.0,
+            converged_at=None,
+            final_variance=float(np.var(signal)) if n > 1 else 0.0,
+            oscillation_freq=0.0,
+            n_modes=1,
+            recommendation="continue",
+            total_steps=n,
+        )
+
+    # --- Rolling variance ---
+    rv = rolling_variance(signal, window)
+    final_var = float(rv[-1]) if len(rv) > 0 else float(np.var(signal))
+
+    # --- Check divergence (variance growing or signal unbounded) ---
+    if len(rv) > 10:
+        tail = rv[-min(20, len(rv)):]
+        trend = np.polyfit(np.arange(len(tail)), tail, 1)[0]
+
+        # Compare first and last quarter variance
+        q1 = np.mean(rv[:max(1, len(rv) // 4)])
+        q4 = np.mean(rv[-max(1, len(rv) // 4):])
+
+        # Also check if signal magnitude itself is growing (random walk)
+        first_quarter_range = np.ptp(signal[:n // 4]) if n > 4 else 0
+        last_quarter_range = np.ptp(signal[-n // 4:]) if n > 4 else 0
+
+        is_growing = (
+            (trend > 0 and q4 > q1 * 2) or
+            (last_quarter_range > first_quarter_range * 2 and final_var > var_threshold * 10) or
+            (final_var > var_threshold * 1000 and trend > 0)
+        )
+
+        if is_growing and final_var > var_threshold * 10:
+            return ConvergenceResult(
+                state="diverging",
+                quality=0.0,
+                converged_at=None,
+                final_variance=final_var,
+                oscillation_freq=0.0,
+                n_modes=1,
+                recommendation="restart",
+                total_steps=n,
+            )
+
+    # --- Find convergence point ---
+    converged_at = None
+    for i, v in enumerate(rv):
+        if v < var_threshold:
+            converged_at = i + window
+            break
+
+    # --- Oscillation detection ---
+    detrended = signal - np.mean(signal)
+    zero_crossings = int(np.sum(np.diff(np.sign(detrended)) != 0))
+    osc_freq = zero_crossings / (2.0 * n)
+
+    # Check if variance is stable (not decreasing) — sign of sustained oscillation
+    variance_stable = False
+    if len(rv) > 4:
+        first_half_var = np.mean(rv[:len(rv) // 2])
+        second_half_var = np.mean(rv[len(rv) // 2:])
+        if first_half_var > 0 and second_half_var / (first_half_var + 1e-30) > 0.5:
+            variance_stable = True
+
+    # Oscillating = enough zero crossings + variance not decreasing + not converged
+    is_oscillating = (zero_crossings > n * 0.01 and
+                      variance_stable and
+                      final_var > var_threshold)
+
+    # --- Mode count (bistability) ---
+    tail_len = min(n, window * 4)
+    n_modes = count_modes(signal[-tail_len:])
+
+    # --- Classify ---
+    if final_var < var_threshold:
+        state = "converged"
+        quality = min(1.0, 1.0 - final_var / var_threshold)
+        recommendation = "stop"
+    elif n_modes >= 2 and not is_oscillating:
+        state = "bistable"
+        quality = 0.3
+        recommendation = "continue"
+    elif is_oscillating:
+        state = "oscillating"
+        quality = max(0.1, 0.5 * (1.0 - min(1.0, final_var / (var_threshold * 100))))
+        recommendation = "continue"
+    else:
+        # Slow convergence or unclear
+        if converged_at is not None:
+            state = "converged"
+            quality = min(1.0, 1.0 - final_var / var_threshold)
+            recommendation = "stop"
+        else:
+            state = "unconverged"
+            quality = max(0.0, 1.0 - min(1.0, final_var / (var_threshold * 1000)))
+            recommendation = "continue"
+
+    return ConvergenceResult(
+        state=state,
+        quality=quality,
+        converged_at=converged_at,
+        final_variance=final_var,
+        oscillation_freq=osc_freq,
+        n_modes=n_modes,
+        recommendation=recommendation,
+        total_steps=n,
+    )
+
+
+# =============================================================
+# Live Monitor (for running simulations)
+# =============================================================
+
+class Watch:
+    """
+    Live convergence monitor for running simulations.
+
+    Call .step(value) every iteration. Returns (should_stop, result).
+
+    Example:
+        mon = Watch(var_threshold=1e-6, check_every=100, min_steps=200)
+        for i in range(10000):
+            residual = solver.step()
+            stop, info = mon.step(residual)
+            if stop:
+                print(f"Converged at step {i}")
+                break
+    """
+
+    def __init__(
+        self,
+        var_threshold: float = 1e-6,
+        check_every: int = 50,
+        min_steps: int = 100,
+        window: int = 0,
+    ):
+        self.var_threshold = var_threshold
+        self.check_every = check_every
+        self.min_steps = min_steps
+        self.window = window
+
+        self._history: List[float] = []
+        self._step_count = 0
+        self._converged = False
+        self._last_result: Optional[ConvergenceResult] = None
+
+    def step(self, value: float) -> Tuple[bool, Optional[ConvergenceResult]]:
+        """
+        Feed one value. Returns (should_stop, result_or_None).
+
+        Args:
+            value: current scalar value (residual, energy, loss, etc.)
+
+        Returns:
+            (True, ConvergenceResult) if should stop
+            (False, None) if should continue
+            (False, ConvergenceResult) at check points
+        """
+        self._history.append(float(value))
+        self._step_count += 1
+
+        if self._converged:
+            return True, self._last_result
+
+        if self._step_count < self.min_steps:
+            return False, None
+
+        if self._step_count % self.check_every != 0:
+            return False, None
+
+        # Analyze
+        result = detect(
+            np.array(self._history),
+            window=self.window,
+            var_threshold=self.var_threshold,
+        )
+        result.total_steps = self._step_count
+
+        self._last_result = result
+
+        if result.recommendation == "stop":
+            self._converged = True
+            result.converged_at = self._step_count
+            return True, result
+
+        return False, result
+
+    @property
+    def history(self) -> np.ndarray:
+        """Return the full recorded history."""
+        return np.array(self._history)
+
+    @property
+    def n_steps(self) -> int:
+        """Number of steps recorded."""
+        return self._step_count
+
+    def reset(self):
+        """Reset the monitor for a new run."""
+        self._history = []
+        self._step_count = 0
+        self._converged = False
+        self._last_result = None
+
+
+def watch(
+    var_threshold: float = 1e-6,
+    check_every: int = 50,
+    min_steps: int = 100,
+    window: int = 0,
+) -> Watch:
+    """
+    Create a live convergence monitor.
+
+    Args:
+        var_threshold: variance below this = converged
+        check_every: check convergence every N steps
+        min_steps: minimum steps before first check
+        window: analysis window (0 = auto)
+
+    Returns:
+        Watch instance. Call .step(value) in your loop.
+    """
+    return Watch(
+        var_threshold=var_threshold,
+        check_every=check_every,
+        min_steps=min_steps,
+        window=window,
+    )

convergio-0.1.0/convergio.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: convergio
+Version: 0.1.0
+Summary: Automatic convergence detection for iterative numerical methods. Stop wasting compute.
+Author: Maximilian Jurak
+License: MIT
+Project-URL: Homepage, https://github.com/maxjurak/convergio
+Keywords: convergence,simulation,solver,early-stopping,FEM,CFD,optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# Convergio
+
+**Automatic convergence detection for iterative numerical methods.**
+
+Stop wasting compute. One function call tells you if your solver has converged, is oscillating, is stuck between two states, or is diverging.
+
+*"Your solver finished 3000 iterations ago."*
+
+## Install
+
+```bash
+pip install convergio
+```
+
+Only dependency: NumPy.
+
+## Usage
+
+### Analyze a completed run
+
+```python
+from convergio import detect
+
+result = detect(my_residual_history)
+
+print(result.state)        # "converged" | "oscillating" | "bistable" | "diverging"
+print(result.quality)      # 0.0 — 1.0
+print(result.converged_at) # step where convergence was detected
+print(result.n_modes)      # number of distinct stable states
+```
+
+### Monitor a running simulation
+
+```python
+from convergio import watch
+
+mon = watch(var_threshold=1e-6)
+
+for step in range(10000):
+    residual = solver.step()
+    stop, info = mon.step(residual)
+    if stop:
+        print(f"Converged at step {step}")
+        break
+```
+
+## What it detects
+
+| State | Meaning | Recommendation |
+|-------|---------|----------------|
+| `converged` | Signal has stabilized | Stop |
+| `oscillating` | Signal oscillates without settling | Continue or adjust parameters |
+| `bistable` | Signal jumps between 2+ distinct states | Investigate — multiple solutions exist |
+| `diverging` | Variance is growing | Restart with different parameters |
+| `warming_up` | Not enough data yet | Continue |
+
+## Works with
+
+- FEM / CFD solvers (residual monitoring)
+- ML training (loss convergence)
+- Monte Carlo simulations (running averages)
+- Optimization loops (objective function)
+- Molecular dynamics (energy equilibration)
+- Any iterative numerical process that produces a scalar time series
+
+## API
+
+### `detect(signal, window=0, var_threshold=1e-6)`
+
+Analyze a complete time series. Returns `ConvergenceResult`.
+
+### `watch(var_threshold=1e-6, check_every=50, min_steps=100)`
+
+Create a live monitor. Returns `Watch` object. Call `.step(value)` each iteration.
+
+### `ConvergenceResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `state` | str | converged, oscillating, bistable, diverging, warming_up |
+| `quality` | float | 0.0 — 1.0 convergence quality |
+| `converged_at` | int or None | Step where convergence detected |
+| `final_variance` | float | Variance of last window |
+| `oscillation_freq` | float | Detected oscillation frequency |
+| `n_modes` | int | Number of distinct stable states |
+| `recommendation` | str | stop, continue, restart |
+
+## License
+
+MIT
+
+## Author
+
+Maximilian Jurak — 3 Kaiserberge Engineering & Research

convergio-0.1.0/convergio.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+convergio/__init__.py
+convergio.egg-info/PKG-INFO
+convergio.egg-info/SOURCES.txt
+convergio.egg-info/dependency_links.txt
+convergio.egg-info/requires.txt
+convergio.egg-info/top_level.txt
+tests/test_convergio.py

convergio-0.1.0/convergio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

convergio-0.1.0/convergio.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.20

convergio-0.1.0/convergio.egg-info/top_level.txt

@@ -0,0 +1 @@
+convergio

convergio-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "convergio"
+version = "0.1.0"
+description = "Automatic convergence detection for iterative numerical methods. Stop wasting compute."
+authors = [{name = "Maximilian Jurak"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["numpy>=1.20"]
+keywords = ["convergence", "simulation", "solver", "early-stopping", "FEM", "CFD", "optimization"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.urls]
+Homepage = "https://github.com/maxjurak/convergio"

convergio-0.1.0/setup.cfg

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

convergio-0.1.0/tests/test_convergio.py

@@ -0,0 +1,145 @@
+"""Tests for OptionE convergence detection."""
+
+import numpy as np
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from convergio import detect, watch, rolling_variance, count_modes
+
+
+def test_converging_signal():
+    signal = np.exp(-np.linspace(0, 10, 1000))
+    result = detect(signal, var_threshold=1e-6)
+    assert result.state == "converged", f"Expected converged, got {result.state}"
+    assert result.converged_at is not None
+    assert result.quality > 0.5
+    assert result.recommendation == "stop"
+    print("PASS: converging signal")
+
+
+def test_oscillating_signal():
+    signal = np.sin(np.linspace(0, 100, 2000))
+    result = detect(signal, var_threshold=1e-6)
+    assert result.state == "oscillating", f"Expected oscillating, got {result.state}"
+    assert result.oscillation_freq > 0.001, f"Expected osc_freq > 0.001, got {result.oscillation_freq}"
+    assert result.recommendation == "continue"
+    print("PASS: oscillating signal")
+
+
+def test_diverging_signal():
+    np.random.seed(42)
+    signal = np.cumsum(np.random.randn(1000) * 0.5)
+    result = detect(signal, var_threshold=1e-4)
+    assert result.state == "diverging", f"Expected diverging, got {result.state}"
+    assert result.recommendation == "restart"
+    print("PASS: diverging signal")
+
+
+def test_constant_signal():
+    signal = np.ones(500) * 3.14 + np.random.randn(500) * 1e-8
+    result = detect(signal, var_threshold=1e-6)
+    assert result.state == "converged", f"Expected converged, got {result.state}"
+    assert result.quality > 0.9
+    print("PASS: constant signal")
+
+
+def test_bistable_signal():
+    np.random.seed(42)
+    signal = np.zeros(2000)
+    state = 1.0
+    for i in range(2000):
+        if np.random.random() < 0.02:
+            state = -state
+        signal[i] = state + np.random.randn() * 0.05
+    result = detect(signal, var_threshold=0.001)
+    assert result.n_modes >= 2, f"Expected >=2 modes, got {result.n_modes}"
+    print("PASS: bistable signal")
+
+
+def test_short_signal():
+    signal = [1.0, 2.0, 3.0]
+    result = detect(signal)
+    assert result.state == "warming_up"
+    assert result.recommendation == "continue"
+    print("PASS: short signal")
+
+
+def test_rolling_variance():
+    signal = np.ones(100)
+    rv = rolling_variance(signal, window=10)
+    assert len(rv) == 91
+    assert np.all(rv < 1e-10)
+    print("PASS: rolling variance")
+
+
+def test_count_modes_unimodal():
+    signal = np.random.randn(1000) + 5.0
+    n = count_modes(signal)
+    assert n == 1, f"Expected 1 mode, got {n}"
+    print("PASS: count modes unimodal")
+
+
+def test_count_modes_bimodal():
+    signal = np.concatenate([
+        np.random.randn(500) - 3.0,
+        np.random.randn(500) + 3.0
+    ])
+    n = count_modes(signal)
+    assert n >= 2, f"Expected >=2 modes, got {n}"
+    print("PASS: count modes bimodal")
+
+
+def test_watch_early_stopping():
+    mon = watch(var_threshold=1e-6, check_every=50, min_steps=100)
+    stopped = False
+    for i in range(5000):
+        value = 10.0 * np.exp(-i / 100.0) + np.random.randn() * 1e-8
+        stop, result = mon.step(value)
+        if stop:
+            stopped = True
+            assert i < 2000, f"Should have stopped much earlier, stopped at {i}"
+            break
+    assert stopped, "Watch should have triggered early stopping"
+    print(f"PASS: watch early stopping (stopped at step {i})")
+
+
+def test_watch_reset():
+    mon = watch(var_threshold=1e-4)
+    for i in range(200):
+        mon.step(float(i))
+    assert mon.n_steps == 200
+    mon.reset()
+    assert mon.n_steps == 0
+    print("PASS: watch reset")
+
+
+if __name__ == "__main__":
+    tests = [
+        test_converging_signal,
+        test_oscillating_signal,
+        test_diverging_signal,
+        test_constant_signal,
+        test_bistable_signal,
+        test_short_signal,
+        test_rolling_variance,
+        test_count_modes_unimodal,
+        test_count_modes_bimodal,
+        test_watch_early_stopping,
+        test_watch_reset,
+    ]
+
+    passed = 0
+    failed = 0
+
+    for t in tests:
+        try:
+            t()
+            passed += 1
+        except Exception as e:
+            print(f"FAIL: {t.__name__}: {e}")
+            failed += 1
+
+    print(f"\n{'='*40}")
+    print(f"Results: {passed} passed, {failed} failed")
+    print(f"{'='*40}")