KIM-Convergence

0.0.3 · active · verified Fri Apr 17

kim-convergence is a Python library designed to assist in the automatic detection of equilibration and control of run lengths in simulations or data streams. It provides tools to determine when a time series of data has reached a steady state or converged. The current version is 0.0.3, with releases happening infrequently as major improvements or compatibility updates are needed.

Common errors

```
ModuleNotFoundError: No module named 'kim_convergence'
```
cause The 'kim-convergence' package is not installed in your current Python environment.

fix Install the package using pip: `pip install kim-convergence`.
```
AttributeError: module 'numpy' has no attribute 'NINF'
```
cause You are likely using an older version of 'kim-convergence' (before 0.0.3) with a newer version of NumPy (2.0 or higher). NumPy 2.0 removed `np.NINF`.

fix Upgrade 'kim-convergence' to version 0.0.3 or newer: `pip install --upgrade kim-convergence`. If you must use an older 'kim-convergence', downgrade NumPy to < 2.0 (`pip install 'numpy<2.0'`).
```
ValueError: time_series must be a 2D array.
```
cause The `detect_convergence` method received a 1D array instead of the expected 2D array.

fix Reshape your input array to be 2-dimensional. For example, if you have a 1D array `data_1d`, convert it to `data_1d.reshape(-1, 1)` before passing it to `detect_convergence`.

Warnings

breaking Older versions of kim-convergence (< 0.0.3) are not compatible with NumPy versions 2.0 and later due to changes in NumPy's internal API (e.g., `np.NINF` removal).
Fix: Upgrade kim-convergence to version 0.0.3 or higher: `pip install --upgrade kim-convergence`.
gotcha The `detect_convergence` method expects a 2D NumPy array for the `time_series` input. Passing a 1D array or a list of lists will result in a `ValueError` or unexpected behavior.
Fix: Ensure your input data is a 2D NumPy array. For a single variable time series, use `np.array(your_1d_list).reshape(-1, 1)` to convert it to a 2D array with a single column.

Install

pip install kim-convergence Install stable version

Imports

ConvergenceDetector
wrong:
```
from kim_convergence.detector import ConvergenceDetector
```
correct:
```
from kim_convergence import ConvergenceDetector
```
The ConvergenceDetector class is directly exposed at the top-level package for convenience.

Quickstart

This quickstart demonstrates how to use `ConvergenceDetector` to identify the point at which a time series of data converges. It initializes a detector with 'rmse' criteria, a window size, and a threshold, then applies it to a sample 2D NumPy array.

import numpy as np
from kim_convergence import ConvergenceDetector

# Generate some example converging data (e.g., from a simulation)
np.random.seed(42)
time_series_data = np.concatenate([
    np.random.rand(50, 2) + np.array([10.0, 20.0]), # Initial transient
    np.random.rand(50, 2) * 0.1 + np.array([10.5, 20.5]) # Converged state
])

# Initialize the detector with desired criteria
# 'rmse' (Root Mean Square Error) is a common choice
detector = ConvergenceDetector(
    criteria='rmse',
    window_size=10, # Number of data points in the comparison windows
    threshold=0.1   # Maximum allowed difference for convergence
)

# Detect convergence
convergence_step = detector.detect_convergence(time_series_data)

if convergence_step is not None:
    print(f"Convergence detected at step: {convergence_step}")
    print(f"Data considered converged from index: {convergence_step}")
else:
    print("Convergence not detected within the given time series.")

view raw JSON →