{"id":9867,"library":"kim-convergence","title":"KIM-Convergence","description":"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.","status":"active","version":"0.0.3","language":"en","source_language":"en","source_url":"https://github.com/openkim/kim-convergence","tags":["scientific computing","data analysis","equilibration","convergence detection","simulation","numpy","statistics"],"install":[{"cmd":"pip install kim-convergence","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Used for statistical tests like Levene's test if specified as a convergence criterion.","package":"scipy","optional":false}],"imports":[{"note":"The ConvergenceDetector class is directly exposed at the top-level package for convenience.","wrong":"from kim_convergence.detector import ConvergenceDetector","symbol":"ConvergenceDetector","correct":"from kim_convergence import ConvergenceDetector"}],"quickstart":{"code":"import numpy as np\nfrom kim_convergence import ConvergenceDetector\n\n# Generate some example converging data (e.g., from a simulation)\nnp.random.seed(42)\ntime_series_data = np.concatenate([\n    np.random.rand(50, 2) + np.array([10.0, 20.0]), # Initial transient\n    np.random.rand(50, 2) * 0.1 + np.array([10.5, 20.5]) # Converged state\n])\n\n# Initialize the detector with desired criteria\n# 'rmse' (Root Mean Square Error) is a common choice\ndetector = ConvergenceDetector(\n    criteria='rmse',\n    window_size=10, # Number of data points in the comparison windows\n    threshold=0.1   # Maximum allowed difference for convergence\n)\n\n# Detect convergence\nconvergence_step = detector.detect_convergence(time_series_data)\n\nif convergence_step is not None:\n    print(f\"Convergence detected at step: {convergence_step}\")\n    print(f\"Data considered converged from index: {convergence_step}\")\nelse:\n    print(\"Convergence not detected within the given time series.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade kim-convergence to version 0.0.3 or higher: `pip install --upgrade kim-convergence`.","message":"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).","severity":"breaking","affected_versions":"< 0.0.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install kim-convergence`.","cause":"The 'kim-convergence' package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'kim_convergence'"},{"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'`).","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`.","error":"AttributeError: module 'numpy' has no attribute 'NINF'"},{"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`.","cause":"The `detect_convergence` method received a 1D array instead of the expected 2D array.","error":"ValueError: time_series must be a 2D array."}]}