| Name | thevenin JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Equivalent circuit models in Python. |
| upload_time | 2024-11-13 21:16:45 |
| maintainer | Corey R. Randall |
| docs_url | None |
| author | Corey R. Randall |
| requires_python | <3.14,>=3.9 |
| license | BSD 3-Clause License Copyright (c) 2024, Alliance for Sustainable Energy, LLC Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
ecm
equivalent
circuit
model
battery
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!-- <img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;'
src='https://github.com/NREL/thevenin/blob/main/images/dark.png?raw=true#gh-dark-mode-only'/>
<img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;'
src='https://github.com/NREL/thevenin/blob/main/images/light.png?raw=true#gh-light-mode-only'/> -->
# thevenin
[![CI][ci-b]][ci-l]
![tests][test-b]
![coverage][cov-b]
[![pep8][pep-b]][pep-l]
[ci-b]: https://github.com/NREL/thevenin/actions/workflows/ci.yaml/badge.svg
[ci-l]: https://github.com/NREL/thevenin/actions/workflows/ci.yaml
[test-b]: https://github.com/NREL/thevenin/blob/main/images/tests.svg?raw=true
[cov-b]: https://github.com/NREL/thevenin/blob/main/images/coverage.svg?raw=true
[pep-b]: https://img.shields.io/badge/code%20style-pep8-orange.svg
[pep-l]: https://www.python.org/dev/peps/pep-0008
## Summary
This package is a wrapper for the well-known Thevenin equivalent circuit model. The model is comprised of a single series reistor followed by any number of parallel RC pairs. Figure 1 below illustrates a circuit with 2 RC pairs; however, the model can be run with as few as zero, and as many as $N$.
<p align="center">
<img alt="2RC Thevenin circuit." style="width: 75%; min-width: 250px; max-width: 500px;"
src="https://github.com/NREL/thevenin/blob/main/images/example_circuit.png?raw=true"/>
</br>
Figure 1: 2RC Thevenin circuit.
</p>
This system is governed by the evolution of the state of charge (SOC, -), RC overpotentials ($V_j$, V), cell voltage ($V_{\rm cell}$, V), and temperature ($T_{\rm cell}$, K). SOC and $V_j$ evolve in time as
$$\frac{d\rm SOC}{dt} = \frac{-I}{3600 Q_{\rm max}},$$
$$\frac{dV_j}{dt} = -\frac{V_j}{R_jC_j} + \frac{I}{C_j},$$
where $I$ is the load current (A), $Q_{\rm max}$ is the maximum nominal cell capacity (Ah), and $R_j$ and $C_j$ are the resistance (Ohm) and capacitance (F) of each RC pair $j$. Note that the sign convention for $I$ is chosen such that positive $I$ discharges the battery (reduces SOC) and negative $I$ charges the battery (increases SOC). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, $R_j$ and $C_j$ are functions of SOC and $T_{\rm cell}$. The temperature increases while the cell is active according to
$$mC_p\frac{dT_{\rm cell}}{dt} = Q_{\rm gen} + Q_{\rm conv},$$
where $m$ is mass (kg), $C_p$ is specific heat capacity (J/kg/K), $Q_{\rm gen}$ is the heat generation (W), and $Q_{\rm conv}$ is the convective heat loss (W). Heat generation and convection are defined by
$$Q_{\rm gen} = I \times (V_{\rm OCV}({\rm SOC}) - V_{\rm cell}),$$
$$Q_{\rm conv} = hA(T_{\infty} - T_{\rm cell}),$$
where $h$ is the convecitive heat transfer coefficient (W/m<sup>2</sup>/K), $A$ is heat loss area (m<sup>2</sup>), and $T_{\infty}$ is the air/room temperature (K). $V_{\rm OCV}$ is the open circuit voltage (V) and is a function of SOC.
The overall cell voltage is
$$V_{\rm cell} = V_{\rm OCV}({\rm SOC}) - \sum_j V_j - IR_0,$$
where $R_0$ is the lone series resistance (Ohm), as shown in Figure 1. Just like the other resistive elements, $R_0$ is a function of SOC and $T_{\rm cell}$.
## Installation
`thevenin` is installable via either pip or conda. To install from [PyPI](https://pypi.org/project/thevenin) use the following command.
```
pip install thevenin
```
If you prefer using the `conda` package manager, you can install `thevenin` from the `conda-forge` channel using the command below.
```
conda install -c conda-forge thevenin
```
If you run into issues with installation due to the [scikit-sundae](https://github.com/NREL/scikit-sundae) dependency, please submit an issue [here](https://github.com/NREL/scikit-sundae/issues). We also manage this solver package, but distribute it separately since it is not developed in pure Python.
For those interested in setting up a developer and/or editable version of this software please see the directions available in the "Development" section of our [documentation](https://thevenin.readthedocs.io/en/latest/development).
## Get Started
The API is organized around three main classes that allow you to construct the model, define an experiment, and interact with the solution. A basic example for a constant-current discharge is given below. To learn more about the model and see more detailed examples check out the [documentation](https://thevenin.readthedocs.io/) on Read the Docs.
```python
import thevenin as thev
model = thev.Model()
expr = thev.Experiment()
expr.add_step('current_A', 75., (3600., 1.), limits=('voltage_V', 3.))
soln = model.run(expr)
soln.plot('time_h', 'voltage_V')
```
**Notes:**
* If you are new to Python, check out [Spyder IDE](https://www.spyder-ide.org/). Spyder is a powerful interactive development environment (IDE) that can make programming in Python more approachable to new users.
## Citing this Work
This work was authored by researchers at the National Renewable Energy Laboratory (NREL). The project is tracked in NREL's software records under SWR-24-132 and has a DOI available for citing the work. If you use use this package in your work, please include the following citation:
> Placeholder... waiting for DOI.
For convenience, we also provide the following for your BibTex:
```
@misc{Randall2024,
title = {{thevenin: Equivalent circuit models in Python}},
author = {Randall, Corey R.},
year = {2024},
doi = {placeholder... waiting for DOI},
url = {https://github.com/NREL/thevenin},
}
```
## Acknowledgements
The motivation and funding for this project came from the Rapid Operational Validation Initiative (ROVI) sponsored by the Office of Electricity. The focus of ROVI is "to greatly reduce time required for emerging energy storage technologies to go from lab to market by developing new tools that will accelerate the testing and validation process needed to ensure commercial success." If interested, you can read more about ROVI [here](https://www.energy.gov/oe/rapid-operational-validation-initiative-rovi).
## Contributing
If you'd like to contribute to this package, please look through the existing [issues](https://github.com/NREL/thevenin/issues). If the bug you've caught or the feature you'd like to add isn't already being worked on, please submit a new issue before getting started. You should also read through the [developer guidelines](https://thevenin.readthedocs.io/en/latest/development).
## Disclaimer
This work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE). The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.
Raw data
{
"_id": null,
"home_page": null,
"name": "thevenin",
"maintainer": "Corey R. Randall",
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": "corey.randall@nrel.gov",
"keywords": "ECM, equivalent, circuit, model, battery",
"author": "Corey R. Randall",
"author_email": "corey.randall@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/88/cc/b1c2535483ee0e87414227d7793f6fe3193dd95ef8845b51c9013622edfb/thevenin-0.1.1.tar.gz",
"platform": null,
"description": "<!-- <img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;' \n src='https://github.com/NREL/thevenin/blob/main/images/dark.png?raw=true#gh-dark-mode-only'/>\n<img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;' \n src='https://github.com/NREL/thevenin/blob/main/images/light.png?raw=true#gh-light-mode-only'/> -->\n\n # thevenin\n\n[![CI][ci-b]][ci-l] \n![tests][test-b] \n![coverage][cov-b] \n[![pep8][pep-b]][pep-l]\n\n[ci-b]: https://github.com/NREL/thevenin/actions/workflows/ci.yaml/badge.svg\n[ci-l]: https://github.com/NREL/thevenin/actions/workflows/ci.yaml\n\n[test-b]: https://github.com/NREL/thevenin/blob/main/images/tests.svg?raw=true\n[cov-b]: https://github.com/NREL/thevenin/blob/main/images/coverage.svg?raw=true\n\n[pep-b]: https://img.shields.io/badge/code%20style-pep8-orange.svg\n[pep-l]: https://www.python.org/dev/peps/pep-0008\n\n## Summary\nThis package is a wrapper for the well-known Thevenin equivalent circuit model. The model is comprised of a single series reistor followed by any number of parallel RC pairs. Figure 1 below illustrates a circuit with 2 RC pairs; however, the model can be run with as few as zero, and as many as $N$.\n\n<p align=\"center\">\n <img alt=\"2RC Thevenin circuit.\" style=\"width: 75%; min-width: 250px; max-width: 500px;\" \n src=\"https://github.com/NREL/thevenin/blob/main/images/example_circuit.png?raw=true\"/>\n </br>\n Figure 1: 2RC Thevenin circuit.\n</p>\n\nThis system is governed by the evolution of the state of charge (SOC, -), RC overpotentials ($V_j$, V), cell voltage ($V_{\\rm cell}$, V), and temperature ($T_{\\rm cell}$, K). SOC and $V_j$ evolve in time as\n\n$$\\frac{d\\rm SOC}{dt} = \\frac{-I}{3600 Q_{\\rm max}},$$\n$$\\frac{dV_j}{dt} = -\\frac{V_j}{R_jC_j} + \\frac{I}{C_j},$$\n\nwhere $I$ is the load current (A), $Q_{\\rm max}$ is the maximum nominal cell capacity (Ah), and $R_j$ and $C_j$ are the resistance (Ohm) and capacitance (F) of each RC pair $j$. Note that the sign convention for $I$ is chosen such that positive $I$ discharges the battery (reduces SOC) and negative $I$ charges the battery (increases SOC). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, $R_j$ and $C_j$ are functions of SOC and $T_{\\rm cell}$. The temperature increases while the cell is active according to\n\n$$mC_p\\frac{dT_{\\rm cell}}{dt} = Q_{\\rm gen} + Q_{\\rm conv},$$\n\nwhere $m$ is mass (kg), $C_p$ is specific heat capacity (J/kg/K), $Q_{\\rm gen}$ is the heat generation (W), and $Q_{\\rm conv}$ is the convective heat loss (W). Heat generation and convection are defined by\n\n$$Q_{\\rm gen} = I \\times (V_{\\rm OCV}({\\rm SOC}) - V_{\\rm cell}),$$\n$$Q_{\\rm conv} = hA(T_{\\infty} - T_{\\rm cell}),$$\n\nwhere $h$ is the convecitive heat transfer coefficient (W/m<sup>2</sup>/K), $A$ is heat loss area (m<sup>2</sup>), and $T_{\\infty}$ is the air/room temperature (K). $V_{\\rm OCV}$ is the open circuit voltage (V) and is a function of SOC.\n\nThe overall cell voltage is\n\n$$V_{\\rm cell} = V_{\\rm OCV}({\\rm SOC}) - \\sum_j V_j - IR_0,$$\n\nwhere $R_0$ is the lone series resistance (Ohm), as shown in Figure 1. Just like the other resistive elements, $R_0$ is a function of SOC and $T_{\\rm cell}$.\n\n## Installation\n`thevenin` is installable via either pip or conda. To install from [PyPI](https://pypi.org/project/thevenin) use the following command.\n\n```\npip install thevenin\n```\n\nIf you prefer using the `conda` package manager, you can install `thevenin` from the `conda-forge` channel using the command below.\n\n```\nconda install -c conda-forge thevenin\n```\n\nIf you run into issues with installation due to the [scikit-sundae](https://github.com/NREL/scikit-sundae) dependency, please submit an issue [here](https://github.com/NREL/scikit-sundae/issues). We also manage this solver package, but distribute it separately since it is not developed in pure Python.\n\nFor those interested in setting up a developer and/or editable version of this software please see the directions available in the \"Development\" section of our [documentation](https://thevenin.readthedocs.io/en/latest/development).\n\n## Get Started\nThe API is organized around three main classes that allow you to construct the model, define an experiment, and interact with the solution. A basic example for a constant-current discharge is given below. To learn more about the model and see more detailed examples check out the [documentation](https://thevenin.readthedocs.io/) on Read the Docs.\n\n```python\nimport thevenin as thev\n\nmodel = thev.Model()\n\nexpr = thev.Experiment()\nexpr.add_step('current_A', 75., (3600., 1.), limits=('voltage_V', 3.))\n\nsoln = model.run(expr)\nsoln.plot('time_h', 'voltage_V')\n```\n\n**Notes:**\n* If you are new to Python, check out [Spyder IDE](https://www.spyder-ide.org/). Spyder is a powerful interactive development environment (IDE) that can make programming in Python more approachable to new users.\n\n## Citing this Work\nThis work was authored by researchers at the National Renewable Energy Laboratory (NREL). The project is tracked in NREL's software records under SWR-24-132 and has a DOI available for citing the work. If you use use this package in your work, please include the following citation:\n\n> Placeholder... waiting for DOI.\n\nFor convenience, we also provide the following for your BibTex:\n\n```\n@misc{Randall2024,\n title = {{thevenin: Equivalent circuit models in Python}},\n author = {Randall, Corey R.},\n year = {2024},\n doi = {placeholder... waiting for DOI},\n url = {https://github.com/NREL/thevenin},\n}\n```\n\n## Acknowledgements\nThe motivation and funding for this project came from the Rapid Operational Validation Initiative (ROVI) sponsored by the Office of Electricity. The focus of ROVI is \"to greatly reduce time required for emerging energy storage technologies to go from lab to market by developing new tools that will accelerate the testing and validation process needed to ensure commercial success.\" If interested, you can read more about ROVI [here](https://www.energy.gov/oe/rapid-operational-validation-initiative-rovi).\n\n## Contributing\nIf you'd like to contribute to this package, please look through the existing [issues](https://github.com/NREL/thevenin/issues). If the bug you've caught or the feature you'd like to add isn't already being worked on, please submit a new issue before getting started. You should also read through the [developer guidelines](https://thevenin.readthedocs.io/en/latest/development).\n\n## Disclaimer\nThis work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE). The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2024, Alliance for Sustainable Energy, LLC Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Equivalent circuit models in Python.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://thevenin.readthedocs.io",
"Homepage": "https://github.com/NREL/thevenin",
"Issues": "https://github.com/NREL/thevenin/issues",
"Repository": "https://github.com/NREL/thevenin"
},
"split_keywords": [
"ecm",
" equivalent",
" circuit",
" model",
" battery"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2a2f54d086fcc887adc83237bfb7a33ce9819b498a24eb4f9460dcc9be394ea",
"md5": "53f59c6d436b0ee300f4eb1dc3b2fec4",
"sha256": "3005141cb839269c864034b80fadae6f7b4c7e570966361ae0bc20f30a8beb4b"
},
"downloads": -1,
"filename": "thevenin-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53f59c6d436b0ee300f4eb1dc3b2fec4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 25053,
"upload_time": "2024-11-13T21:16:44",
"upload_time_iso_8601": "2024-11-13T21:16:44.326699Z",
"url": "https://files.pythonhosted.org/packages/c2/a2/f54d086fcc887adc83237bfb7a33ce9819b498a24eb4f9460dcc9be394ea/thevenin-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "88ccb1c2535483ee0e87414227d7793f6fe3193dd95ef8845b51c9013622edfb",
"md5": "8644c08d0c90682fa3de7e666bab49c6",
"sha256": "9f1c36ca017736ac485152c2816326d4cc27a745646ee32977df0d8cdcac9032"
},
"downloads": -1,
"filename": "thevenin-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8644c08d0c90682fa3de7e666bab49c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 25133,
"upload_time": "2024-11-13T21:16:45",
"upload_time_iso_8601": "2024-11-13T21:16:45.582281Z",
"url": "https://files.pythonhosted.org/packages/88/cc/b1c2535483ee0e87414227d7793f6fe3193dd95ef8845b51c9013622edfb/thevenin-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 21:16:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NREL",
"github_project": "thevenin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "thevenin"
}
