| Name | BatteryRateCap JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | |
| Summary | A Python package for battery rate capability analysis. |
| upload_time | 2023-06-07 19:13:07 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | MIT License Copyright (c) 2021 c. 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. |
| keywords |
battery
rate analysis
rate capability
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
[comment]: <> (Build Badge)
[](https://app.travis-ci.com/github/BatteryDesign/BatteryRateCap)
# *BatteryRateCap*: A Python Package for Analyzing and Visualizing Battery Rate Capability
This pacakge is intended to faciliate battery
rate capability analysis based on an empirical model approach developed by
[Tian et al.](https://doi.org/10.1038/s41467-019-09792-9).
A common phenomenon in intercalation batteries is decreasing battery capacity (mAh, mAh/g, or
mAh/cm<sup>2</sup>)
to increasing charge and discharge current rate (A, A/cm<sup>2</sup>, or 1/hour).
Rate capability is a battery's ability to maintain its maxnimum
theoretical capacity when charged and discharged at high current rates.
According to Tian et al., a battery's capacity (*Q*) versus current rate (*R*) data, also called the
capacity-rate data,can be analyzed
using the following empirical model:<br/>
Q = Q<sub>max</sub> ( 1 - (R $\tau$ )<sup>n</sup> (1-e<sup>-(R $\tau$
)<sup>-n</sup></sup>)) <br/>
By fitting the capcaity-rate data to the empirical model, we can obtain
three fitting parameters that quantify the performace of a battery:
- The characterictic time ( $\tau$ ) is associated with the time required to fully charge or discharge a
battery. A smaller $\tau$ means higher rate capability.
- The low rate specific capacity (*Q<sub>max</sub>*) measures a battery's maximum theoretical capacity, which
normalizes
$\tau$ and *n* such that batteries made with different materials can be compared on the same scale.
- The exponent *n* gives a physical interpretation of the rate-limiting transport mechanism in
a battery.
For more insight about the fitting parameters, please visit [Tian et
al.(2019)](https://doi.org/10.1038/s41467-019-09792-9) and [Hung et
al.(2022)](https://doi.org/10.1021/acsenergylett.2c02208).
*BatteryRateCap* is composed of four components, each supports a function
to allow or enhance the rate capability analysis approach developed by Tian et al.
The interdependency bewteen components are shown in the diagram above, where a brief desciprtion of each component can be found below:<br/>
- (A) a data conversion component to convert voltage-dicharge data and/or capacity-cycle data to capacity-rate
data
- (B) a curve-fitting component to fit experimental capacity-rate data to Tian et al's empirical model.
- (C) a visulization component to plot the fitting parameters obtained from component (B) against other physical
quantities such as the battery electrode thickness and porosity.
- (D) a hypothesis testing component to compare different battery cases based on their rate capability
charateristics and to detect outliers in a linear relationship. <br/>
## Example Use Cases for Battery Researchers
### Use case 1. Data Conversion
The *data_converter* module converts charge/discharge data (voltage versus capacity) and capacity-cycle data
into rate-capacity data. Complete procedures and example codes on how to use the *data_converter* module are
detailed in Demo/Demo_data_converter.ipynb. Below is an excerpt of the *data_converter* demo notebook, showing
the output of how *data_converter* categorizes capacity data by their C-rate in a capacity-cycle dataset.
The conversion from voltage-capacity to capacity-rate data does not involve any visuals, so no figures are shown here.<br/>
### Use case 2. Data Fitting
The *fitcaprate* module fits capacity-rate data and attains fitting parameters, including charatersitic time,
*n* value, and capacity *Q* as described in the introduction. Complete procedures and example codes on how to
use the *fitcaprate* module can be found in Demo/Demo_fitcaprate.ipynb. Below is an excerpt of the *fitcaprate*
demo notebook, showing the results of fitted curves (red dashed curves) found by *fitcaprate* for a set of
battery capcity-rate data (blue dots).<br/>
### Use case 3: Data visulization
The *visualization* module creates a panel plot that lays out 2D scatter plots of fitting parameters versus
available battery design parameters realated to geometry and materials. Complete procedures and example
codes on how to use the *visualization* module are detailed in Demo/Demo_visualization.ipynb. Below is an
excerpt of the *visualization* demo notebook, showing the output panel plot.<br/>
### Use case 4: Hypothesis testing
The *correlationtest* module determines whether a statistically-signicificant linear relationship exisits
between found battery fitting parameters, which indicate the battery performance, and their desgin parameters
related to geometry and materials. Complete procedures and example codes on how to use the *correlationtest*
module are detailed in Demo/Demo_correlationtest. Below is an excerpt of the *correlationtest* demo notebook,
showing how the module plots the best-fit linear regression line (in blue) between two target parameters
and highlights potential outliers (in red) to the linear relationship.
## How to Install
*BatteryRateCap* can be installed by cloning the entire repoitory or via pip:</br>
```
pip install BatteryRateCap
```
## Software Dependency
- Python >=3.6
- See environment.yml for all Python package dependencies
## Community Guidelines
If you encounter any issue using *BatteryRateCap* or would like to request an additional feature, please report using a [Github
issue](https://github.com/BatteryDesign/BatteryRateCap/issues). If you would like to directly contribute to this project, please email the
reporsitory maintainer Doris Hung at dhung@uw.edu.
Raw data
{
"_id": null,
"home_page": "",
"name": "BatteryRateCap",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "Chih-Hsuan Hung <dhung@uw.edu>",
"keywords": "battery,rate analysis,rate capability",
"author": "",
"author_email": "Chih-Hsuan Hung <dhung@uw.edu>, Praise Anyanwu <anyanc@uw.edu>, \"Kevin G. Lee\" <gskl92@uw.edu>, \"Matthew J. Canin\" <matthewcanin@gmail.com>, Kevin Martinez-Chavez <martikev@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/38/c22dc0330e3817e0f868147dcf22848b7c51373a1ca04a9ef5618ee83a6f/BatteryRateCap-0.1.1.tar.gz",
"platform": null,
"description": "[comment]: <> (Build Badge)\n[](https://app.travis-ci.com/github/BatteryDesign/BatteryRateCap)\n\n\n# *BatteryRateCap*: A Python Package for Analyzing and Visualizing Battery Rate Capability\nThis pacakge is intended to faciliate battery \nrate capability analysis based on an empirical model approach developed by \n[Tian et al.](https://doi.org/10.1038/s41467-019-09792-9). \nA common phenomenon in intercalation batteries is decreasing battery capacity (mAh, mAh/g, or \nmAh/cm<sup>2</sup>)\nto increasing charge and discharge current rate (A, A/cm<sup>2</sup>, or 1/hour). \nRate capability is a battery's ability to maintain its maxnimum \ntheoretical capacity when charged and discharged at high current rates. \nAccording to Tian et al., a battery's capacity (*Q*) versus current rate (*R*) data, also called the \ncapacity-rate data,can be analyzed \nusing the following empirical model:<br/>\n\nQ = Q<sub>max</sub> ( 1 - (R $\\tau$\t)<sup>n</sup> (1-e<sup>-(R $\\tau$\t\n)<sup>-n</sup></sup>)) <br/>\n\nBy fitting the capcaity-rate data to the empirical model, we can obtain\nthree fitting parameters that quantify the performace of a battery:\n- The characterictic time ( $\\tau$ ) is associated with the time required to fully charge or discharge a \nbattery. A smaller $\\tau$ means higher rate capability.\n- The low rate specific capacity (*Q<sub>max</sub>*) measures a battery's maximum theoretical capacity, which \nnormalizes\n$\\tau$ and *n* such that batteries made with different materials can be compared on the same scale.\n- The exponent *n* gives a physical interpretation of the rate-limiting transport mechanism in \na battery.\nFor more insight about the fitting parameters, please visit [Tian et \nal.(2019)](https://doi.org/10.1038/s41467-019-09792-9) and [Hung et \nal.(2022)](https://doi.org/10.1021/acsenergylett.2c02208).\n \n\n\n*BatteryRateCap* is composed of four components, each supports a function \nto allow or enhance the rate capability analysis approach developed by Tian et al.\nThe interdependency bewteen components are shown in the diagram above, where a brief desciprtion of each component can be found below:<br/>\n- (A) a data conversion component to convert voltage-dicharge data and/or capacity-cycle data to capacity-rate \ndata\n- (B) a curve-fitting component to fit experimental capacity-rate data to Tian et al's empirical model.\n- (C) a visulization component to plot the fitting parameters obtained from component (B) against other physical \nquantities such as the battery electrode thickness and porosity. \n- (D) a hypothesis testing component to compare different battery cases based on their rate capability \ncharateristics and to detect outliers in a linear relationship. <br/>\n\n\n\n## Example Use Cases for Battery Researchers\n### Use case 1. Data Conversion\nThe *data_converter* module converts charge/discharge data (voltage versus capacity) and capacity-cycle data \ninto rate-capacity data. Complete procedures and example codes on how to use the *data_converter* module are \ndetailed in Demo/Demo_data_converter.ipynb. Below is an excerpt of the *data_converter* demo notebook, showing \nthe output of how *data_converter* categorizes capacity data by their C-rate in a capacity-cycle dataset. \nThe conversion from voltage-capacity to capacity-rate data does not involve any visuals, so no figures are shown here.<br/>\n \n### Use case 2. Data Fitting\nThe *fitcaprate* module fits capacity-rate data and attains fitting parameters, including charatersitic time, \n*n* value, and capacity *Q* as described in the introduction. Complete procedures and example codes on how to \nuse the *fitcaprate* module can be found in Demo/Demo_fitcaprate.ipynb. Below is an excerpt of the *fitcaprate* \ndemo notebook, showing the results of fitted curves (red dashed curves) found by *fitcaprate* for a set of \nbattery capcity-rate data (blue dots).<br/>\n\n### Use case 3: Data visulization\nThe *visualization* module creates a panel plot that lays out 2D scatter plots of fitting parameters versus \navailable battery design parameters realated to geometry and materials. Complete procedures and example \ncodes on how to use the *visualization* module are detailed in Demo/Demo_visualization.ipynb. Below is an \nexcerpt of the *visualization* demo notebook, showing the output panel plot.<br/>\n\n### Use case 4: Hypothesis testing\nThe *correlationtest* module determines whether a statistically-signicificant linear relationship exisits \nbetween found battery fitting parameters, which indicate the battery performance, and their desgin parameters\nrelated to geometry and materials. Complete procedures and example codes on how to use the *correlationtest* \nmodule are detailed in Demo/Demo_correlationtest. Below is an excerpt of the *correlationtest* demo notebook, \nshowing how the module plots the best-fit linear regression line (in blue) between two target parameters \nand highlights potential outliers (in red) to the linear relationship.\n\n\n \n## How to Install\n*BatteryRateCap* can be installed by cloning the entire repoitory or via pip:</br>\n```\npip install BatteryRateCap\n```\n\n## Software Dependency\n- Python >=3.6\n- See environment.yml for all Python package dependencies\n\n\n## Community Guidelines\nIf you encounter any issue using *BatteryRateCap* or would like to request an additional feature, please report using a [Github \nissue](https://github.com/BatteryDesign/BatteryRateCap/issues). If you would like to directly contribute to this project, please email the \nreporsitory maintainer Doris Hung at dhung@uw.edu.\n\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2021 c. 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. ",
"summary": "A Python package for battery rate capability analysis.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/BatteryDesign/BatteryRateCap"
},
"split_keywords": [
"battery",
"rate analysis",
"rate capability"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15d0654da30c8e02d3ff79ee96e470d5f9908ea7bccc5e2fe9cdbecdfef53e42",
"md5": "8451df747fd6e530adf853c7b6d4c9fa",
"sha256": "f3247c37ab75f24cd72f1e2ee8bdd9867e310c9217be4021fb93206d2b18071c"
},
"downloads": -1,
"filename": "BatteryRateCap-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8451df747fd6e530adf853c7b6d4c9fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5140,
"upload_time": "2023-06-07T19:13:05",
"upload_time_iso_8601": "2023-06-07T19:13:05.907684Z",
"url": "https://files.pythonhosted.org/packages/15/d0/654da30c8e02d3ff79ee96e470d5f9908ea7bccc5e2fe9cdbecdfef53e42/BatteryRateCap-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9438c22dc0330e3817e0f868147dcf22848b7c51373a1ca04a9ef5618ee83a6f",
"md5": "a8fedba7324fc7fb2cf96c69e7ff80a3",
"sha256": "7127a1da3963380fe0d68161bfe093ba498e704e32827d6452048bc104a272f4"
},
"downloads": -1,
"filename": "BatteryRateCap-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "a8fedba7324fc7fb2cf96c69e7ff80a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7364,
"upload_time": "2023-06-07T19:13:07",
"upload_time_iso_8601": "2023-06-07T19:13:07.678393Z",
"url": "https://files.pythonhosted.org/packages/94/38/c22dc0330e3817e0f868147dcf22848b7c51373a1ca04a9ef5618ee83a6f/BatteryRateCap-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-07 19:13:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BatteryDesign",
"github_project": "BatteryRateCap",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "batteryratecap"
}
