SoftwareX 11 (2020) 100506

Contents lists available at ScienceDirect

SoftwareX
journal homepage: www.elsevier.com/locate/softx

Original software publication

BEEP: A Python library for Battery Evaluation and Early Prediction

∗
Patrick Herring a , Chirranjeevi Balaji Gopal a , Muratahan Aykol a , , Joseph H. Montoya a ,
Abraham Anapolsky a , Peter M. Attia b , William Gent b , Jens S. Hummelshøj a ,
Linda Hung a , Ha-Kyung Kwon a , Patrick Moore a , Daniel Schweigert a ,
Kristen A. Severson c , Santosh Suram a , Zi Yang b , Richard D. Braatz c , Brian D. Storey a
a
Toyota Research Institute, Los Altos, CA 94022, USA
b
Department of Materials Science and Engineering, Stanford University, Stanford, CA 94305, USA
c
Department of Chemical Engineering, Massachusetts Institute of Technology, Cambridge, MA 02139, USA

article info a b s t r a c t

Article history: Battery evaluation and early prediction software package (BEEP) provides an open-source Python-based
Received 21 February 2020 framework for the management and processing of high-throughput battery cycling data-streams. BEEPs
Received in revised form 2 April 2020 features include file-system based organization of raw cycling data and metadata received from cell
Accepted 9 April 2020
testing equipment, validation protocols that ensure the integrity of such data, parsing and structuring
Keywords: of data into Python-objects ready for analytics, featurization of structured cycling data to serve as
Battery input for machine-learning, and end-to-end examples that use processed data for anomaly detection
Cycling experiments and featurized data to train early-prediction models for cycle life. BEEP is developed in response to the
Python software and expertise gap between cell-level battery testing and data-driven battery development.
Data management © 2020 The Authors. Published by Elsevier B.V. This is an open access article under the CC BY license
Machine-learning (http://creativecommons.org/licenses/by/4.0/).

Code metadata

Current Code version 1.0

Permanent link to code/repository used of this code version https://github.com/ElsevierSoftwareX/SOFTX_2020_49
Legal Code License Apache 2.0
Code Versioning system used git
Software Code Language used Python
Compilation requirements, Operating environments & dependencies Python 3 on Linux, OSX or Windows. Dependencies listed in setup.py in code repository.
If available Link to developer documentation/manual –
Support email for questions [email protected] or [email protected]

1. Motivation and significance of electrodes, electrolytes, additives [2–5] or formation [6], and
designing state-of-health (SoH) [7–10], state-of-charge (SoC) [10–
Energy storage in Li-ion batteries revolutionized the portable 12], early prediction models [9,10,13] or advanced battery man-
electronics industry and is now defining the future of vehicle agement systems (BMSs) [14–16]. An increase in the volume of
electrification. The growing consumer adoption of electric vehi- standardized cycling data can open the door to improvement of
cles (EVs) and the potential for positive environmental benefits
existing approaches to data-driven prognostics, [9,13,15,17] or to
have spurred academic and industrial interest in improving the
design of more complex algorithms capable of delivering accurate
capacity, energy and power density, durability and safety of Li-ion
cells, as well as lowering the manufacturing costs [1]. Transition- health predictions.
ing to a data-driven research paradigm shows great potential to For the broader adoption of data-driven battery development,
accelerate battery development –a traditionally slow and tedious reusable high-throughput battery testing data [13,18] and soft-
process- in areas including the optimization of the chemistry ware tools for processing and analysis of such data are essential.
While the hardware for automated battery cycling is accessible,
∗ Correspondence to: 4440 El Camino Real, Los Altos, CA 94022, USA. the field still lacks open software for both acquisition and man-
E-mail address: [email protected] (M. Aykol). agement of cycling data and preparing the data for analytics.

https://doi.org/10.1016/j.softx.2020.100506
2352-7110/© 2020 The Authors. Published by Elsevier B.V. This is an open access article under the CC BY license (http://creativecommons.org/licenses/by/4.0/).
2 P. Herring, C. Balaji Gopal, M. Aykol et al. / SoftwareX 11 (2020) 100506

Community-driven software development can be effective in fill- all paths are defined in reference to the BEEP_EP_ROOT en-
ing this gap [19] and can yield reliable and reusable tools (as vironment variable. If collate is called from the command
experienced in computational materials science [20,21]). Such line, the module locates the raw data files, parses the meta-
software libraries can form the basis for advanced development data, and collates files according to a combination of proto-
capabilities for the expert and lower the barrier for the novice to col, channel number, and date, organizing them in ‘/data-
set foot in data-centric battery research. share/collated_cycler_files’. This functionality is han-
The repetitive nature of battery experiments defines the re- dled mainly by the function process_files_json which can
quirements for such a tool to be useful to battery researchers. also be called directly. The output is a JSON string that contains
Experiments consist of repeated application of ‘‘cycling protocols’’ ids, paths and names for raw cycler files, paths for the collated
(which prescribe how the battery should be charged and dis-
cycler files, cycling protocols corresponding to each file, channel
charged) to a user-supplied battery cell by the hardware. Such cy-
number and the date the original file was generated.
cling experiments can take from a few hours to several months to
complete. During these experiments, many types of information,
such as time, capacity, voltage, cycle number and temperature 2.2. Validate
are recorded with high sampling frequency, and the size of raw
data can grow rapidly. Besides, the naming conventions for dif-
As in any experimental process, erroneous or corrupted data
ferent projects, data, metadata and protocol files can vary among
can be produced as a consequence of instrument failures (e.g.
vendors or members of a research group. Hence, a scalable data
power outage), changes in environmental conditions (e.g. temper-
management and processing system is required. In addition, the
ature), software glitches or human errors (e.g. misconfigured pro-
data structures can be complicated due to the cyclic nature of the
experiments. For example, raw data may need to be grouped over tocols) in any stage of battery cycling experiments. If unnoticed,
one axis and interpolated over another. Data formats and stor- such data may contaminate the analytical process or misguide
age technologies (e.g. databases, file systems) also vary among the research. To address this issue, BEEP provides a validate
different cycler hardware. Researchers could benefit from stan- module, where the ValidatorBeep class validates collated cy-
dardized data formats, alongside programmatic interfaces to such cling data against researcher-defined schemas prescribed in yaml
databases as needed. Data streams should be validated against files (examples can be found in VALIDATION_SCHEMA_DIR) or as
human errors, equipment errors or failures, and environmental dictionary-based rule definitions of the external Python library
circumstances to ensure their integrity. Organized, processed, and cerberus [24]. The validation schemas can include data-types,
validated data are the key ingredient for a data-driven research min/max values, ranges, non-allowed values or complex rules via
pipeline, and can be used in unsupervised modeling (e.g. for cerberus, which adopts a convenient, dictionary based schema
anomaly detection) or followed by a ‘‘featurization’’ step that definition. A fast, lightweight version is provided as Simpl-
computes engineered features from the data [13,22]. Featurized eValidatorBeep which does dataframe-based validation (re-
cycling data can be used in training predictive models (e.g. for stricted to type, min/max and non-allowed) and supports the
failure prediction). cerberus syntax for interchangeable use. Validation stores the
To the best of our knowledge, there is no open software list of files being validated and the results in JSON format, at
that satisfies the requirements or features summarized above, DEFAULT_VALIDATION_RECORDS.
which are expected to be useful for enabling wider adoption of
data-driven approaches in battery research. The battery experi-
mentation and early prediction Python library, BEEP, aims to fill 2.3. Structure
this gap. Since it is built on common Python libraries such as
NumPy, SciPy, scikit-learn and pandas, and adopts common data Battery cycling tests accumulate information in a tabular form,
interchange formats like JSON, we expect BEEP to make this tran- containing thousands to millions of rows, and produce large data
sition to data-driven research easier for individual researchers
files that need to be structured for analytics. The structure
and provide useful building blocks for battery research platforms
module contains two classes that serve this purpose: RawCy-
developed by research groups [23].
clerRun and ProcessedCyclerRun. The first class supports
parsing and indexing of raw data into appropriate integer (e.g.
2. Software description
step, cycle index) and float (e.g. time, current, voltage, charge ca-
pacity, temperature) columns in a dataframe, and provides meth-
BEEP consists of six main modules: collate, validate,
ods to identify diagnostic cycles, and deliver summary statistics
structure, featurize, generate_protocol and run_
and metadata. This class can interpolate target variables over
model. While the modules can be used independently, this order
other variables and return interpolated data-containers of the
of execution is typical for the data management and processing
steps delivered by the BEEP framework, and therefore the output same structure (e.g. interpolating variables on a consistent volt-
of the main methods in each module is the input for the next. The age scale), which is useful for machine-learning models. Pro-
default functionality of each module can also be directly accessed cessedCyclerRun provides project-specific structuring of raw
from the command-line, where input arguments are provided as data from RawCyclerRun, for which example schemas are pro-
JSON-strings. Almost all BEEP classes are serializable and can be vided in the conversion_schemas folder for various types of
stored as such objects. Here we explain the main functionalities hardware. Input data needed for structuring exist in datafiles
delivered with each module in BEEP. of almost any cycling hardware, often recorded with different
naming conventions. This library of conversion schemas can be
2.1. Collate expanded to other formats and provide a centralized resource
for the community to be used with other battery cyclers and
The collate module is used for standardization of raw cycler instruments. The ProcessedCyclerRun class produces a rich,
files and metadata as well as organization of the standardized serializable object, which flexibly allows addition of fields and
files. BEEP follows a name-based convention for file storage and data as needed.
 P. Herring, C. Balaji Gopal, M. Aykol et al. / SoftwareX 11 (2020) 100506 3

Fig. 1. Code snippets demonstrating the raw data file handling, processing and featurization.

2.4. Featurize train method. Single or multi-point fitting can be performed,

and train automatically makes that determination from the
Data input for machine learning algorithms generally needs to dataset. Model attributes, coefficients (for linear models), per-
be uniformly formatted. For many cases, this formatting can be formance metrics, dataset-id and other metadata required to
done through the construction of features, which are quantities reproduce the training are serialized as a JSON file. The pre-
computed from raw or interpolated data, and are based on known dictions are reported as cycle-life, or the number of cycles to
physical phenomena in the system. We handle this process in reach a certain discharge capacity relative to the nominal value,
the Featurize module. In the DegradationPredictor class, along with a 95% confidence interval. Current implementation
features are computed on a per-cell basis from ProcessedCy- includes regularized multi-linear regression, but as the model
clerRun and are used to predict the performance of the battery objects build on scikit-learn (and hence use its estimator API),
at a certain number of cycles in the future. Many of these quan- they are easily extensible to other machine learning models, like
tities could be computed per cycle or at specific times in order ensemble methods or neural networks in scikit-learn or similar
to fit a model that predicts the performance of the battery at a libraries. Integration with other machine-learning libraries can
point in the future (relative or absolute). Currently default fea- be achieved by adopting their APIs in new model classes derived
tures include time integrated temperature at cycle 100, capacity from existing ones above.
decrease over the first 100 cycles, minimum temperature in the
first 100 cycles, and others [13]. Additional features can be easily 2.6. Protocol
added, but care must be taken to also update the downstream
models. Community improvement of this feature set is a desirable Most battery cycling systems have a ‘‘protocol’’ file that is
development direction. used to run the cycling experiment. This file contains parameters
that control the cell, limit conditions for each of the steps in
2.5. Model the cycling experiment, and other variables. Different hardware
vendors refer to these files differently, e.g. as schedule, procedure,
The model module comprises methods to aggregate featur- or sequence files and adopt different formats in terms of language
ized battery cycling data, and train and store machine-learning and layout. We use the term protocol to refer to these files and
models, currently for early prediction of cycle life. As input, it provide an abstraction for their components to unify such differ-
takes feature files encoding DegradationPredictor objects. ent formats. In a manner similar to the data files, we structure
The core of the module is DegradationModel and its associ- different protocol formats into JSON objects that can be accessed
ated attributes/methods for model initialization, hyperparameter and modified. This allows programmatic generation of protocols
tuning, training and cross-validation, and predictions. Users have in the generate_protocol module. We provide functions that
the option to load existing serialized models, or train new mod- convert protocol objects to the file format in use. Care should
els on the set of DegradationPredictor objects using the be taken when using this functionality since there are numerous
4 P. Herring, C. Balaji Gopal, M. Aykol et al. / SoftwareX 11 (2020) 100506

Fig. 2. Code snippets demonstrating model prediction using existing (stored) model and training of a new model using featurized data.

Fig. 3. Predicted vs. actual cycle life at different capacity fade thresholds. The capacity fade threshold is shown as a percentage of initial nominal capacity in each
panel.

safety values included in the file; setting these values incorrectly and display rendering can become a roadblock in large battery
can result in damage to the cycling system or the cell under test, cycling experiments. Hence, components of BEEP are modularized
either of which might be catastrophic. However, the benefits of for easy deployment to cloud-based services that can scale up
this capability are far reaching, such as the elimination of manual or down. Additional cloud infrastructure can provide messaging
test creation, which is time-consuming and error-prone, and the and coordination of various scripts to deal with large data loads
ability to create and run protocols in cyclers with minimal human and processing-heavy tasks. For such application environments,
input. These features enable automated control and selection we designed most of the scripts to be containerized and run via
of experiments by active learning systems, as demonstrated in command-line arguments, and messaging between components
Ref. [25]. Future developments include the ability to convert from to be achieved with event streaming.
one system’s protocol file to another’s (within the appropriate Currently, BEEP assumes that data are arriving in a flat-file
hardware constraints) and supporting more systems. format, with one file per test. There are, however, database-
centered cycler systems that do not store or export data in this
2.7. Other features form, which improves performance but makes data less accessi-
ble. Scripts that enable integration with such systems and output
BEEP scripts can be run locally on a machine with appropriate of flat files ingestible by BEEP are available at https://github.
access to data and adequate compute/memory. But dealing with com/TRI-AMDD/beep-integration-scripts. There are two caveats
the computational workload of data processing, model fitting to such scripts. First, there are assumptions about the way that
 P. Herring, C. Balaji Gopal, M. Aykol et al. / SoftwareX 11 (2020) 100506 5

the tests are run, such as the user will not duplicate a test name
on a channel, each test runs to completion on a single channel,
etc. These assumptions stem from common practices, but the
scripts have not been tested against a large number of conditions.
Second, while for most cases the data files are less than a few
hundred megabytes, sufficient memory must be available to fit
large tests into memory. Further development might reduce the
memory requirement and provide more robust extraction of the
data, e.g. with improved SQL queries.

3. Illustrative example

BEEP is intended to streamline the process of transforming raw

data from a battery cycler into actionable insights through data
management, transformation and modeling. As a simplified end-
to-end pipeline, here we will parse the raw dataset published by
Severson et al. [13], and featurize it to train a multi-task linear
model for early-prediction of cycle life. Relevant code snippets for
reproducing this exercise are provided in Figs. 1 and 2. First, the Fig. 4. Capacity fade curves (discharge capacity vs. cycle index). Experimental
paths to desired raw cycling data are compiled into a JSON object, measurements reported in Severson et al. [13] are shown as solid lines, and
and validated, the output of which is a JSON object containing predictions made using the model illustrated in the text are shown as points,
the validity information. Next, the validated raw data are struc- along with the associated standard deviations as horizontal bars.
tured in two steps. First, a RawCyclerRun object is initialized to
store time-series of measured quantities as a dataframe in data
and metadata, and electrochemical impedance spectra in eis, 4. Impact
if measured. The raw data are then processed to yield a Pro-
cessedCyclerRun object, with optional arguments specifying As the use of Li-ion batteries grows, especially in the EV
the range and resolution of voltage interpolation. The resulting market, the importance of understanding their potential and lim-
object contains dataframes that store summary statistics, and itations will increase rapidly. We view BEEP as a platform that
interpolated discharge curves. The object also contains meta-data, can accelerate battery research by removing the burden of data
such as the barcode of the cell, protocol and channel_id. organization from the researcher and automating as many pro-
Each row in summary dataframe stores point-measures of var- cesses as possible. BEEP enables researchers to efficiently deal
ious metrics for a cycle. The resulting dataframe is useful for with larger sample sizes, improving the repeatability and re-
developing features that rely on aggregated properties over a liability of their results. Automated organization, cleaning and
cycle. The cycles_interpolated dataframe contains similar structuring of data make sharing and collaboration seamless, and
quantities as summary, but instead of aggregation over cycles, the machine-learning approaches more accessible for researchers.
values are interpolated on an evenly spaced voltage grid within Our hope is that as the battery community builds larger public
each cycle. This dataframe is useful for differential analysis at datasets, better and more complex models can be trained and
specific voltages, or for featurization based on material-specific these models can guide battery development and reduce the
properties not captured in summary. The processed cycle run number of physical battery experiments, accelerating the pace of
can be used to prepare features via DegradationPredictor, battery development. Such models can potentially provide more
with optional arguments specifying the quantity to be predicted accurate predictions, e.g. for diagnostics, health management or
(e.g. cycle as a function of capacity) and type (single vs. future performance. Our goal with BEEP is to create a community
multi task). The feature object contains the name of the feature- composed of both academic and industrial entities, dedicated to
set, actual values of the features in a dataframe X, feature names building methods for data-driven battery development.
in feature_labels, nominal_capacity of the cell in the first
few cycles and the outcomes y for training data.
5. Conclusion
In Fig. 2, we show how a previously trained and stored model
(DegradationModel) can be loaded to make predictions on
We present a set of methods for automated ingestion and
incoming featurized-data or how a new model can be trained
analysis of battery cycling data. These methods are embodied in
from scratch on a set of DegradationPredictor objects, us-
Python scripts that leverage open source formats and packages to
ing the train method and a dictionary of hyperparameters for
allow a larger community of battery researchers to use them.
optimization. The train method assembles all the predictors
into a dataframe, performs train-test-split, hyperparameter op-
timization and cross-validation as specified by hyperparame- Declaration of competing interest
ters. Following that, predictions can be generated and/or the
DegradationModel object can be serialized and stored with all The authors declare the following financial interests/personal
requisite details to reproduce the training process at a later time. relationships which may be considered as potential competing
In the current implementation model key corresponds to a linear interests: P.K., M.A., A.A., C.G., P.A. R.B., and K.S. have U.S. patent
model and confidence_bounds is the 95% confidence interval applications in the area of battery data management and prog-
(for each task) calculated on the test data. A sample plot of actual nostics. The remaining authors have no competing interests to
vs. predicted capacity fade using a multi-task model trained on 4 declare.
different batches of cells is shown in Fig. 3. Specifically, the cycles
(time) taken to reach 95%, 92%, 89%, 86%, 83% and 80% of nominal Acknowledgments
capacity using the first 100 cycles are predicted. Predictions of the
model are further compared with the experimental capacity fade Authors acknowledge Prof. William Chueh and Prof. Martin
curves in Fig. 4. Bazant for the discussions throughout the development of BEEP.
6 P. Herring, C. Balaji Gopal, M. Aykol et al. / SoftwareX 11 (2020) 100506

References [14] Lu L, Han X, Li J, Hua J, Ouyang M. J Power Sources 2013;226:272–88.

[15] Pecht M, Jaai R. Microelectron Reliab 2010;50:317–23.
[1] Thackeray MM, Wolverton C, Isaacs ED. Energy Environ Sci 2012;5:7854. [16] Rezvanizaniani SM, Liu Z, Chen Y, Lee J. J Power Sources 2014;256:110–24.
[2] Kauwe S, Rhone T, Sparks T. Crystals 2019;9:54. [17] Nuhic A, Terzimehic T, Soczka-Guth T, Buchholz M, Dietmayer K. J Power
[3] Halls MD, Tasaki K. J Power Sources 2010;195:1472–8. Sources 2013;239:680–8.
[4] Qu X, Jain A, Rajput NN, Cheng L, Zhang Y, Ong SP, et al. Comput Mater [18] Wilkinson MD, Dumontier M, Aalbersberg IjJ, Appleton G, Axton M, Baak A,
Sci 2015;103:56–67. et al. Sci Data 2016;3:1–9.
[5] Hautier G, Jain A, Chen H, Moore C, Ong SP, Ceder G. J Mater Chem [19] Ward L, Aykol M, Blaiszik B, Foster I, Meredig B, Saal J, et al. MRS Bull
2011;21:17147. 2018;43:683–9.
[6] Ermon S, Chueh WC, Grover A, Markov TM, Perkins N, Attia PM. Au- [20] Ong SP, Richards WD, Jain A, Hautier G, Kocher M, Cholia S, et al. Comput
tonomous screening and optimization of battery formation and cycling Mater Sci 2013;68:314–9.
procedures. USPTO No. US 2019/0115778 A1, 2019. [21] Kirklin S, Saal JE, Meredig B, Thompson A, Doak JW, Aykol M, et al. Npj
[7] Shen S, Sadoughi M, Chen X, Hong M, Hu C. J Energy Storage 2019;25. Comput Mater 2015;1:15010.
100817. [22] Ward L, Dunn A, Faghaninia A, Zimmermann NER, Bajaj S, Wang Q, et al.
[8] Richardson RR, Osborne MA, Howey DA. J Energy Storage 2019;23:320–8. Comput Mater Sci 2018;152:60–9.
[9] Li Y, Liu K, Foley AM, Zülke A, Berecibar M, Nanini-Maury E, et al. Renew [23] Aykol M, Hummelshøj JS, Anapolsky A, et al. Matter 2019;1:1433–8.
Sustain Energy Rev 2019;113. [24] Cerberus Python package. 2020, http://python-cerberus.org (accessed April
[10] Plett GL. J Power Sources 2004;134:277–92. 1, 2020).
[11] Ng KS, Moo CS, Chen YP, Hsieh YC. Appl Energy 2009;86:1506–11. [25] Attia P, Grover A, Severson K, et al. Nature 2020;578:397–402.
[12] Xing Y, He W, Pecht M, Tsui KL. Appl Energy 2014;113:106–15.
[13] Severson KA, Attia PM, Jin N, Perkins N, Jiang B, Yang Z, et al. Nat Energy
2019;4:383–91.