galpynostatic.model module

Module with the galvanostatic regression model.

class galpynostatic.model.GalvanostaticRegressor(dataset='spherical', d=0.0001, z=3, dcoeff_lle=-15, dcoeff_ule=-6, dcoeff_num=100, k0_lle=-14, k0_ule=-5, k0_num=100)

Bases: BaseEstimator, RegressorMixin

A heuristic regressor for State-of-Charge (SOC) versus C-rates data.

This physics-based heuristic model [4] uses the maps in the galpynostatic.datasets submodule to perform a grid search, using different combinations of the diffusion coefficient, \(D\), and the kinetic rate constant, \(k^0\), to fit experimental data of the State-of-Charge (SOC) of the electrode material as a function of the galvanostatic charging rate (C-rate). This is done while keeping invariant all the other experimental descriptors involved in the parameters \(\Xi\) and \(\ell\) of the continuum model [4], such as the characteristic diffusion length, \(d\), and the geometric factor, \(z\) (see galpynostatic.utils module).

Each time a set of parameters \(D\) and \(k^0\) are taken, the SOC values are predicted and the mean square error (MSE) is calculated. The set of parameters that minimises the MSE is then obtained, providing a fundamental description of the system.

Parameters:

• dataset (str or pandas.DataFrame, default="spherical") – A str specifying the particle geometry (“planar”, “cylindrical” or “spherical”) to use the datasets distributed in this package, which can also be loaded using the functions of the galpynostatic.datasets submodule to get it as a pandas.DataFrame with the mapping of maximum SOC values as a function of the internal parameters \(\log(\ell)\) and \(\log(\Xi)\).

• d (float, default=1e-4) – Characteristic diffusion length (particle size) in cm.

• z (int, default=3) – Geometric factor (1 for planar, 2 for cylinder and 3 for sphere).

• dcoeff_lle (int, default=-15) – The lower limit exponent of the diffusion coefficient line used to generate the grid.

• dcoeff_ule (int, default=-6) – The upper limit exponent of the diffusion coefficient line used to generate the grid.

• dcoeff_num (int, default=100) – Number of samples of diffusion coefficients to generate between the lower and the upper limit exponents.

• k0_lle (int, default=-14) – The lower limit exponent of the kinetic rate constant line used to generate the grid.

• k0_ule (int, default=-5) – The upper limit exponent of the kinetic rate constant line used to generate the grid.

• k0_num (int, default=100) – Number of samples of kinetic rate constants to generate between the lower and the upper limit exponents.

Notes

You can also give your own dataset to another potential cut-off in the same format as the distributed ones and as pandas.DataFrame, i.e. in the column of \(\ell\) the different values have to be grouped in ascending order and for each of these groups the \(\Xi\) have to be in descending order and respecting that for each group of \(\ell\) the same values are simulated (this is a restriction to perform the scipy.interpolate.RectBivariateSpline, since x and y must be strictly in a special order, which is handled internally by the galpynostatic.base (dev module)).

References

[4] (1,2)

F. Fernandez, E. M. Gavilán-Arriazu, D. E. Barraco, A. Visintin, Y. Ein-Eli and E. P. M. Leiva. “Towards a fast-charging of LIBs electrode materials: a heuristic model based on galvanostatic simulations.” Electrochimica Acta 464 (2023): 142951.

dcoeff_

Predicted diffusion coefficient in \(cm^2/s\).

Type:

float

dcoeff_err_

Uncertainty of the predicted diffusion coefficient.

Type:

float

k0_

Predicted kinetic rate constant in \(cm/s\).

Type:

float

k0_err_

Uncertainty of the predicted kinetic rate constant.

Type:

float

mse_

Mean squared error of the best fitted model.

Type:

float

fit(X, y, sample_weight=None)

Fit the heuristic galvanostatic regressor model.

Parameters:

• X (array-like of shape (n_measurements, 1)) – C-rates data of the experiments.

• y (array-like of shape (n_measurements,)) – Target maximum SOC values, between 0 and 1.

• sample_weight (array-like of shape(n_measurements,), default=None) – Individual weights of each data point.

Returns:

self – Fitted model.

Return type:

object

Raises:

ValueError – If the instantiated dataset is an str but is not a valid geometry (“planar”, “cylindrical” or “spherical”).

predict(X)

Predict using the heuristic model within the map constraints.

Parameters:

X (array-like of shape (n_measurements, 1)) – C-rates input points.

Returns:

y – The predicted maximum SOC values for the C-rate inputs.

Return type:

array-like of shape (n_measurements,)

score(X, y, sample_weight=None)

Return the coefficient of determination of the prediction.

The coefficient of determination \(R^2\) is defined as \((1 - \frac{u}{v})\), where \(u\) is the residual sum of squares ((y_experimental - y_pred)** 2).sum() and \(v\) is the total sum of squares ((y_experimental - y_experimental.mean()) ** 2).sum(). The best possible score is 1.0 and it can be negative (because the model can be arbitrarily worse).

Parameters:

• X (array-like of shape (n_measurements, 1)) – C-rates data of the experiments.

• y (array-like of shape (n_measurements,)) – Maximum SOC values of the experiments.

• sample_weight (array-like of shape(n_measurements,), default=None) – Individual weights of each data point.

Returns:

score – \(R^2\) of self.predict(X) wrt. y.

Return type:

float

to_dataframe(X, y=None)

Convert the train, the evaluation or both sets into a dataframe.

Get a dataframe with two or three columns (C_rates, SOC_exp and SOC_pred), depending on whether you have passed the y-values or not.

Parameters:

• X (array-like of shape (n_measurements, 1)) – C-rate points.

• y (array-like of shape (n_measurements,), default=None) – Maximum SOC values.

Returns:

df – A pandas.DataFrame containing the train, the evaluation or both sets.

Return type:

pandas.DataFrame

property plot

Plot accessor for the galpynostatic.plot module.