# kim-convergence utility module
[](https://github.com/openkim/kim-convergence/actions/workflows/python-package.yml)
[](https://anaconda.org/conda-forge/kim-convergence)
[](https://pypi.python.org/pypi/kim-convergence)
[](LICENSE)
## How do you automatically estimate the length of the simulation required?
<table>
<tr>
<td> <img src="./doc/files/vid1_T.gif?raw=true" width="200" height="200"> </td>
<td> <img src="./doc/files/vid1_P.gif?raw=true" width="200" height="200"> </td>
<td> <img src="./doc/files/vid1_V.gif?raw=true" width="200" height="200"> </td>
</tr>
</table>
<table>
<tr>
<td> <img src="./doc/files/vid2_T.gif?raw=true" width="200" height="200"> </td>
<td> <img src="./doc/files/vid2_P.gif?raw=true" width="200" height="200 "> </td>
<td> <img src="./doc/files/vid2_V.gif?raw=true" width="200" height="200 "> </td>
</tr>
</table>
It is desirable to simulate the minimum amount of time necessary to reach an
acceptable amount of uncertainty in the quantity of interest.
## How do you automatically estimate the length of the warm-up period required?
<table>
<tr>
<td> <img src="./doc/files/vid1_T_Eq.gif?raw=true" width="200" height="200"> </td>
</tr>
</table>
Welcome to **kim-convergence** module!
The kim-convergence package is designed to help in automatic equilibration
detection & run length control.
**PLEASE NOTE**:
the kim-convergence code is under active development and is still in beta
versions `0.0.2`. In general changes to the patch version (the third number)
indicate backward compatible beta releases, but please be aware that file
formats and APIs may change.
Bug reports are also welcomed in the GitHub issues!
## Document
<span style="font-size:300%; color:red; font-weight: 900;">!WORK IN PROGRESS!</span>
## Installing kim-convergence
### Requirements
You need Python 3.9 or later to run `kim-convergence`. You can have multiple
Python versions (2.x and 3.x) installed on the same system without problems.
To install Python 3 for different Linux flavors, macOS and Windows, packages
are available at\
[https://www.python.org/getit/](https://www.python.org/getit/)
### Using pip
**pip** is the most popular tool for installing Python packages, and the one
included with modern versions of Python.
`kim-convergence` can be installed with `pip`:
```sh
pip install kim-convergence
```
**NOTE:**
Depending on your Python installation, you may need to use `pip3` instead of
`pip`.
```sh
pip3 install kim-convergence
```
Depending on your configuration, you may have to run `pip` like this:
```sh
python3 -m pip install kim-convergence
```
### Using pip (GIT Support)
`pip` currently supports cloning over `git`
```sh
pip install git+https://github.com/openkim/kim-convergence.git
```
For more information and examples, see the [pip install](https://pip.pypa.io/en/stable/reference/pip_install/#id18) reference.
### Using conda
**conda** is the package management tool for Anaconda Python installations.
Installing `kim-convergence` from the `conda-forge` channel can be achieved by
adding `conda-forge` to your channels with:
```sh
conda config --add channels conda-forge
conda config --set channel_priority strict
```
Once the `conda-forge` channel has been enabled, `kim-convergence` can be
installed with:
```sh
conda install kim-convergence
```
It is possible to list all of the versions of `kim-convergence` available on
your platform with:
```sh
conda search kim-convergence --channel conda-forge
```
## Basic Usage
Basic usage involves importing kim-convergence and use the utility to control
the length of the time series data from a simulation run or a sampling approach,
or a dump file from the previously done simulation.
The main requirement is a `get_trajectory` function. **`get_trajectory`** is a
callback function with a specific signature of
```get_trajectory(nstep: int) -> 1darray```
if we only have one variable or,
```get_trajectory(nstep: int) -> 2darray```
with the shape of return array as,
```(number_of_variables, nstep)```.
For example,
```py
rng = np.random.RandomState(12345)
stop = 0
def get_trajectory(step: int) -> np.ndarray:
global stop
start = stop
if 100000 < start + step:
step = 100000 - start
stop += step
data = np.ones(step) * 10 + (rng.random_sample(step) - 0.5)
return data
```
**NOTE:**
To use extra arguments in calling the ``get_trajectory`` function, one can use
the other specific signature of
```get_trajectory(nstep: int, args: dict) -> 1darray```
or
```get_trajectory(nstep: int, args: dict) -> 2darray```,
where all the extra required parameters and arguments can be provided with the
args.
```py
rng = np.random.RandomState(12345)
args = {'stop': 0, 'maximum_steps': 100000}
def get_trajectory(step: int, args: dict) -> np.ndarray:
start = args['stop']
if args['maximum_steps'] < start + step:
step = args['maximum_steps'] - start
args['stop'] += step
data = np.ones(step) * 10 + (rng.random_sample(step) - 0.5)
return data
```
---
Then call the `run_length_control` function as below,
```py
import kim_convergence as cr
msg = cr.run_length_control(
get_trajectory=get_trajectory,
number_of_variables=1,
initial_run_length=1000,
maximum_run_length=100000,
relative_accuracy=0.01,
fp_format='json'
)
```
or
```py
import kim_convergence as cr
msg = cr.run_length_control(
get_trajectory=get_trajectory,
get_trajectory_args=args,
number_of_variables=1,
initial_run_length=1000,
maximum_run_length=100000,
relative_accuracy=0.01,
fp_format='json'
)
```
An estimate produced by a simulation typically has an accuracy requirement and
is an input to the utility. This requirement means that the experimenter wishes
to run the simulation only until an estimate meets this accuracy requirement.
Running the simulation less than this length would not provide the information
needed while running it longer would be a waste of computing time. In the above
example, the accuracy requirement is specified as the relative accuracy.
In case of having more than one variable,
```py
rng = np.random.RandomState(12345)
stop = 0
def get_trajectory(step: int) -> np.ndarray:
global stop
start = stop
if 100000 < start + step:
step = 100000 - start
stop += step
data = np.ones((3, step)) * 10 + (rng.random_sample(3 * step).reshape(3, step) - 0.5)
return data
```
Then call the `run_length_control` function as below,
```py
import kim_convergence as cr
msg = cr.run_length_control(
get_trajectory=get_trajectory,
number_of_variables=3,
initial_run_length=1000,
maximum_run_length=100000,
relative_accuracy=0.01,
fp_format='json'
)
```
**NOTE:**
All the values returned from this `get_trajectory` function should be finite
values, otherwise the code will stop wih error message explaining the issue.
```py
ERROR(@_get_trajectory): there is/are value/s in the input which is/are non-finite or not number.
```
Thus, one should remove infinit values or Not a Number (NaN) values from the
returning array within the `get_trajectory` function.
---
The run-length control procedure employs `initial_run_length` parameter. It
begins at time 0 and starts calling the `get_trajectory` function with the
provided number of steps (e.g. ```initial_run_length=1000```). At this point,
and with no assumptions about the distribution of the observable of interest,
it tries to estimate an equilibration time. Failing to find the transition
point will request more data and call the `get_trajectory` function until it
finds the equilibration time or hits the maximum run length limit
(e.g. ```maximum_run_length=100000```).
At this point, and after finding an optimal equilibration time, the confidence
interval (CI) generation method is applied to the set of available data points.
If the resulting confidence interval met the provided accuracy value
(e.g. ```relative_accuracy=0.01```), the simulation is terminated. If not, the
simulation is continued by requesting more data and calling the `get_trajectory`
function again and again until it does. This procedure continues until the
criteria is met or it reaches the maximum run length limit.
The `relative_accuracy` as mentioned above, is the relative precision and
defined as a half-width of the estimator's confidence interval or an
approximated upper confidence limit (UCL) divided by the computed sample mean.
The UCL is calculated as a `confidence_coefficient%` confidence interval for
the mean, using the portion of the time series data, which is in the stationary
region. If the ratio is bigger than `relative_accuracy`, the length of the time
series is deemed not long enough to estimate the mean with sufficient accuracy,
which means the run should be extended.
The accuracy parameter `relative_accuracy` specifies the maximum relative error
that will be allowed in the mean value of the data point series. In other words,
the distance from the confidence limit(s) to the mean (which is also known as
the precision, half-width, or margin of error). A value of `0.01` is usually
used to request two digits of accuracy, and so forth.
The parameter ```confidence_coefficient``` is the confidence coefficient and
often, the values ```0.95``` is used. For the confidence coefficient,
`confidence_coefficient`, we can use the following interpretation, If thousands
of samples of n items are drawn from a population using simple random sampling
and a confidence interval is calculated for each sample, the proportion of
those intervals that will include the true population mean is
`confidence_coefficient`.
## Contact us
If something is not working as you think it should or would like it to, please
get in touch with us! Further, if you have an algorithm or any idea that you
would want to try using the kim-convergence, please get in touch with us, we
would be glad to help!
[](https://gitter.im/openkim/kim-convergence?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
## Contributing
Contributions are very welcome.
## Copyright
Copyright (c) 2021-2025, Regents of the University of Minnesota.\
All Rights Reserved
## Contributors
Contributors:\
Yaser Afshar
Raw data
{
"_id": null,
"home_page": null,
"name": "kim-convergence",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Yaser Afshar <ya.afshar@gmail.com>",
"keywords": "convergence, automated equilibration detection, run length control, upper confidence limit, confidence interval",
"author": null,
"author_email": "Yaser Afshar <ya.afshar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cb/8a/9117af752188315079db78ff8214bceb1bc65d13853a6ea6787bdadf6990/kim_convergence-0.0.3.tar.gz",
"platform": null,
"description": "# kim-convergence utility module\n\n[](https://github.com/openkim/kim-convergence/actions/workflows/python-package.yml)\n[](https://anaconda.org/conda-forge/kim-convergence)\n[](https://pypi.python.org/pypi/kim-convergence)\n[](LICENSE)\n\n## How do you automatically estimate the length of the simulation required?\n\n<table>\n <tr>\n <td> <img src=\"./doc/files/vid1_T.gif?raw=true\" width=\"200\" height=\"200\"> </td>\n <td> <img src=\"./doc/files/vid1_P.gif?raw=true\" width=\"200\" height=\"200\"> </td>\n <td> <img src=\"./doc/files/vid1_V.gif?raw=true\" width=\"200\" height=\"200\"> </td>\n </tr>\n</table>\n\n<table>\n <tr>\n <td> <img src=\"./doc/files/vid2_T.gif?raw=true\" width=\"200\" height=\"200\"> </td>\n <td> <img src=\"./doc/files/vid2_P.gif?raw=true\" width=\"200\" height=\"200 \"> </td>\n <td> <img src=\"./doc/files/vid2_V.gif?raw=true\" width=\"200\" height=\"200 \"> </td>\n </tr>\n</table>\n\nIt is desirable to simulate the minimum amount of time necessary to reach an\nacceptable amount of uncertainty in the quantity of interest.\n\n## How do you automatically estimate the length of the warm-up period required?\n\n<table>\n <tr>\n <td> <img src=\"./doc/files/vid1_T_Eq.gif?raw=true\" width=\"200\" height=\"200\"> </td>\n </tr>\n</table>\n\nWelcome to **kim-convergence** module!\n\nThe kim-convergence package is designed to help in automatic equilibration\ndetection & run length control.\n\n**PLEASE NOTE**:\n\nthe kim-convergence code is under active development and is still in beta\nversions `0.0.2`. In general changes to the patch version (the third number)\nindicate backward compatible beta releases, but please be aware that file\nformats and APIs may change.\n\nBug reports are also welcomed in the GitHub issues!\n\n## Document\n\n<span style=\"font-size:300%; color:red; font-weight: 900;\">!WORK IN PROGRESS!</span>\n\n## Installing kim-convergence\n\n### Requirements\n\nYou need Python 3.9 or later to run `kim-convergence`. You can have multiple\nPython versions (2.x and 3.x) installed on the same system without problems.\n\nTo install Python 3 for different Linux flavors, macOS and Windows, packages\nare available at\\\n[https://www.python.org/getit/](https://www.python.org/getit/)\n\n### Using pip\n\n**pip** is the most popular tool for installing Python packages, and the one\nincluded with modern versions of Python.\n\n`kim-convergence` can be installed with `pip`:\n\n```sh\npip install kim-convergence\n```\n\n**NOTE:**\n\nDepending on your Python installation, you may need to use `pip3` instead of\n`pip`.\n\n```sh\npip3 install kim-convergence\n```\n\nDepending on your configuration, you may have to run `pip` like this:\n\n```sh\npython3 -m pip install kim-convergence\n```\n\n### Using pip (GIT Support)\n\n`pip` currently supports cloning over `git`\n\n```sh\npip install git+https://github.com/openkim/kim-convergence.git\n```\n\nFor more information and examples, see the [pip install](https://pip.pypa.io/en/stable/reference/pip_install/#id18) reference.\n\n### Using conda\n\n**conda** is the package management tool for Anaconda Python installations.\n\nInstalling `kim-convergence` from the `conda-forge` channel can be achieved by\nadding `conda-forge` to your channels with:\n\n```sh\nconda config --add channels conda-forge\nconda config --set channel_priority strict\n```\n\nOnce the `conda-forge` channel has been enabled, `kim-convergence` can be\ninstalled with:\n\n```sh\nconda install kim-convergence\n```\n\nIt is possible to list all of the versions of `kim-convergence` available on\nyour platform with:\n\n```sh\nconda search kim-convergence --channel conda-forge\n```\n\n## Basic Usage\n\nBasic usage involves importing kim-convergence and use the utility to control\nthe length of the time series data from a simulation run or a sampling approach,\nor a dump file from the previously done simulation.\n\nThe main requirement is a `get_trajectory` function. **`get_trajectory`** is a\ncallback function with a specific signature of\n\n```get_trajectory(nstep: int) -> 1darray```\n\nif we only have one variable or,\n\n```get_trajectory(nstep: int) -> 2darray```\n\nwith the shape of return array as,\n\n```(number_of_variables, nstep)```.\n\nFor example,\n\n```py\nrng = np.random.RandomState(12345)\nstop = 0\n\ndef get_trajectory(step: int) -> np.ndarray:\n global stop\n start = stop\n if 100000 < start + step:\n step = 100000 - start\n stop += step\n data = np.ones(step) * 10 + (rng.random_sample(step) - 0.5)\n return data\n```\n\n**NOTE:**\n\nTo use extra arguments in calling the ``get_trajectory`` function, one can use\nthe other specific signature of\n\n```get_trajectory(nstep: int, args: dict) -> 1darray```\n\nor\n\n```get_trajectory(nstep: int, args: dict) -> 2darray```,\n\nwhere all the extra required parameters and arguments can be provided with the\nargs.\n\n```py\nrng = np.random.RandomState(12345)\nargs = {'stop': 0, 'maximum_steps': 100000}\n\ndef get_trajectory(step: int, args: dict) -> np.ndarray:\n start = args['stop']\n if args['maximum_steps'] < start + step:\n step = args['maximum_steps'] - start\n args['stop'] += step\n data = np.ones(step) * 10 + (rng.random_sample(step) - 0.5)\n return data\n```\n\n---\n\nThen call the `run_length_control` function as below,\n\n```py\nimport kim_convergence as cr\n\nmsg = cr.run_length_control(\n get_trajectory=get_trajectory,\n number_of_variables=1,\n initial_run_length=1000,\n maximum_run_length=100000,\n relative_accuracy=0.01,\n fp_format='json'\n)\n```\n\nor\n\n```py\nimport kim_convergence as cr\n\nmsg = cr.run_length_control(\n get_trajectory=get_trajectory,\n get_trajectory_args=args,\n number_of_variables=1,\n initial_run_length=1000,\n maximum_run_length=100000,\n relative_accuracy=0.01,\n fp_format='json'\n)\n```\n\nAn estimate produced by a simulation typically has an accuracy requirement and\nis an input to the utility. This requirement means that the experimenter wishes\nto run the simulation only until an estimate meets this accuracy requirement.\nRunning the simulation less than this length would not provide the information\nneeded while running it longer would be a waste of computing time. In the above\nexample, the accuracy requirement is specified as the relative accuracy.\n\nIn case of having more than one variable,\n\n```py\nrng = np.random.RandomState(12345)\nstop = 0\n\ndef get_trajectory(step: int) -> np.ndarray:\n global stop\n start = stop\n if 100000 < start + step:\n step = 100000 - start\n stop += step\n data = np.ones((3, step)) * 10 + (rng.random_sample(3 * step).reshape(3, step) - 0.5)\n return data\n```\n\nThen call the `run_length_control` function as below,\n\n```py\nimport kim_convergence as cr\n\nmsg = cr.run_length_control(\n get_trajectory=get_trajectory,\n number_of_variables=3,\n initial_run_length=1000,\n maximum_run_length=100000,\n relative_accuracy=0.01,\n fp_format='json'\n)\n```\n\n**NOTE:**\n\nAll the values returned from this `get_trajectory` function should be finite\nvalues, otherwise the code will stop wih error message explaining the issue.\n\n```py\nERROR(@_get_trajectory): there is/are value/s in the input which is/are non-finite or not number.\n```\n\nThus, one should remove infinit values or Not a Number (NaN) values from the\nreturning array within the `get_trajectory` function.\n\n---\n\nThe run-length control procedure employs `initial_run_length` parameter. It\nbegins at time 0 and starts calling the `get_trajectory` function with the\nprovided number of steps (e.g. ```initial_run_length=1000```). At this point,\nand with no assumptions about the distribution of the observable of interest,\nit tries to estimate an equilibration time. Failing to find the transition\npoint will request more data and call the `get_trajectory` function until it\nfinds the equilibration time or hits the maximum run length limit\n(e.g. ```maximum_run_length=100000```).\n\nAt this point, and after finding an optimal equilibration time, the confidence\ninterval (CI) generation method is applied to the set of available data points.\nIf the resulting confidence interval met the provided accuracy value\n(e.g. ```relative_accuracy=0.01```), the simulation is terminated. If not, the\nsimulation is continued by requesting more data and calling the `get_trajectory`\nfunction again and again until it does. This procedure continues until the\ncriteria is met or it reaches the maximum run length limit.\n\nThe `relative_accuracy` as mentioned above, is the relative precision and\ndefined as a half-width of the estimator's confidence interval or an\napproximated upper confidence limit (UCL) divided by the computed sample mean.\n\nThe UCL is calculated as a `confidence_coefficient%` confidence interval for\nthe mean, using the portion of the time series data, which is in the stationary\nregion. If the ratio is bigger than `relative_accuracy`, the length of the time\nseries is deemed not long enough to estimate the mean with sufficient accuracy,\nwhich means the run should be extended.\n\nThe accuracy parameter `relative_accuracy` specifies the maximum relative error\nthat will be allowed in the mean value of the data point series. In other words,\nthe distance from the confidence limit(s) to the mean (which is also known as\nthe precision, half-width, or margin of error). A value of `0.01` is usually\nused to request two digits of accuracy, and so forth.\n\nThe parameter ```confidence_coefficient``` is the confidence coefficient and\noften, the values ```0.95``` is used. For the confidence coefficient,\n`confidence_coefficient`, we can use the following interpretation, If thousands\nof samples of n items are drawn from a population using simple random sampling\nand a confidence interval is calculated for each sample, the proportion of\nthose intervals that will include the true population mean is\n`confidence_coefficient`.\n\n## Contact us\n\nIf something is not working as you think it should or would like it to, please\nget in touch with us! Further, if you have an algorithm or any idea that you\nwould want to try using the kim-convergence, please get in touch with us, we\nwould be glad to help!\n\n[](https://gitter.im/openkim/kim-convergence?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)\n\n## Contributing\n\nContributions are very welcome.\n\n## Copyright\n\nCopyright (c) 2021-2025, Regents of the University of Minnesota.\\\nAll Rights Reserved\n\n## Contributors\n\nContributors:\\\n Yaser Afshar\n",
"bugtrack_url": null,
"license": null,
"summary": "kim-convergence designed to help in automatic equilibration detection & run length control.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/openkim/kim-convergence",
"Issues": "https://github.com/openkim/kim-convergence/issues"
},
"split_keywords": [
"convergence",
" automated equilibration detection",
" run length control",
" upper confidence limit",
" confidence interval"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4dca5aba26482d358d9b8ada96c543af91939a6155b1423f947c837bc302f1ea",
"md5": "34a5a0fb6cbbe1e575112742af536aa6",
"sha256": "a1835d74e455c46af4b18ad7dbde90fa66ac733d50ebb0ec8b034964126dfed5"
},
"downloads": -1,
"filename": "kim_convergence-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34a5a0fb6cbbe1e575112742af536aa6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 107877,
"upload_time": "2025-07-28T11:38:48",
"upload_time_iso_8601": "2025-07-28T11:38:48.599686Z",
"url": "https://files.pythonhosted.org/packages/4d/ca/5aba26482d358d9b8ada96c543af91939a6155b1423f947c837bc302f1ea/kim_convergence-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb8a9117af752188315079db78ff8214bceb1bc65d13853a6ea6787bdadf6990",
"md5": "6aa013ca7e38677612abdc317ad5ddfc",
"sha256": "607ba1ccfc5bd95c15c6d8fdbb1ee2c515b57ab61baa6dbfa3e8adb89d968f0c"
},
"downloads": -1,
"filename": "kim_convergence-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6aa013ca7e38677612abdc317ad5ddfc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 465687,
"upload_time": "2025-07-28T11:38:50",
"upload_time_iso_8601": "2025-07-28T11:38:50.044816Z",
"url": "https://files.pythonhosted.org/packages/cb/8a/9117af752188315079db78ff8214bceb1bc65d13853a6ea6787bdadf6990/kim_convergence-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 11:38:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openkim",
"github_project": "kim-convergence",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kim-convergence"
}
JSON
