pySIMsalabim.aux_funcs package

Submodules

pySIMsalabim.aux_funcs.DRT module

Find System Lifetimes using Distribution of Relaxation Times (DRT) Fitting in the Time Domain

class pySIMsalabim.aux_funcs.DRT.DRT_Fit_Result(time, tau, U, y_inf, y=None, MSE=None, R_2=None)

Bases: object

A class that bundles together all results from fitting a predict_y_model curve to data

U

Fitted coefficients [U_1, U_2, …, U_m]

Type:

numpy.ndarray, shape (m,)

tau

Fitted lifetimes [tau_1, tau_2, …, tau_m]

Type:

numpy.ndarray, shape (m,)

y_inf

y_inf of the steady state of the fitted signal from 0

Type:

float

m

Number of lifetimes/coefficients used in predict_y_model, given by the length of U/tau

Type:

int

y_model

Model given by

y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

Type:

{None, numpy.ndarray}

U_norm

Fitted coefficients normalised by np.sum(self.U)

Type:

{None, numpy.ndarray with shape (m,)}

MSE

Mean square error between the model (self.y) and the fitted signal

Type:

float

R_2

R^2 error between the model (self.y) and the fitted signal

Type:

float

plot_U(normalised=False, tau_analytic=None, U_analytic=None, xaxis_label='$\\tau$ [s]', yaxis_label='Auto', U_model_label='Model', U_label='Analytic', plot_title='DRT', return_ax=False)

Plot the fitted DRT against an optional analytic DRT

Parameters:

• normalised (bool (optional)) – Determines whether self.U (False) or self.U_norm (Ture) is plotted. Default (False)

• tau_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of tau values use to generate the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• U_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of U values used in the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘$tau$ [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘U’ by default.

• U_model_label (str (optional)) – Label for the curve U_model in the output plot legend. ‘Model’ by default.

• U_label (str (optional)) – Label for the U_analytic curve in the output plot legend. ‘Analytic’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘DRT’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

plot_cumulative_U(normalised=False, tau_analytic=None, U_analytic=None, xaxis_label='$\\tau$ [s]', yaxis_label='Auto', U_model_label='Model', U_label='Analytic', plot_title='Cumulative DRT', return_ax=False)

Plot the cumulative sum of self.U or self.U_norm, optionally against a known analytical form.

Parameters:

• normalised (bool (optional)) – Determines whether self.U (False) or self.U_norm (Ture) is plotted. Default (False)

• tau_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of tau values use to generate the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• U_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of U values used in the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘$tau$ [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘Cumulative U’ by default.

• U_model_label (str (optional)) – Label for the curve U_model in the output plot legend. ‘Model’ by default.

• U_label (str (optional)) – Label for the U_analytic curve in the output plot legend. ‘Analytic’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘Cumulative DRT’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

plot_y_model(time, y_data=None, xaxis_label='Time [s]', yaxis_label='y(t)', y_data_plot_label='Data', y_model_plot_label='Model', plot_title='DRT Fit', return_ax=False)

Plot the fitted model agains the data

Parameters:

• time (numpy.ndarray, shape (n,)) – The time values over which the simulated experiment took place

• y_data ({None, numpy.ndarray shape (n,)} (optional)) – The data the model was fitted to. Either y_model or y must not be None. y is None by default.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘Time [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘y(t)’ by default.

• y_data_plot_label (str (optional)) – Label for the curve y in the output plot legend. ‘Data’ by default.

• y_model_plot_label (str (optional)) – Label for the y_model curve in the output plot legend. ‘Model’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘DRT Fit’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

set_U_norm()

Set self.U_norm equal to self.U/np.sum(self.U)

set_y_model(t)

Sets self.predict_y_model = predict_y_model(t) using the objects attributes

Parameters:

• t (float or list/numpy.ndarray, shape (n,)) – Time values to calculate the predict_y_model curve

• backend ({'numpy', 'torch'} (optional)) – Determines whether matrix operations are done with numpy or pytorch. Default numpy.

• device (torch.device (optional)) – Determines what device is used for matrix ops if backend=’torch’.

Return type:

None

exception pySIMsalabim.aux_funcs.DRT.FitError

Bases: Exception

Custom fit error

pySIMsalabim.aux_funcs.DRT.calculate_tau(time)

Generate a range of tau values for DRT fitting based off an observation window over time values ‘time’

Parameters:

time (arraylike, shape (n,)) – Time values data is observed over

Returns:

tau_values

Return type:

arraylike, shape (m,)

pySIMsalabim.aux_funcs.DRT.checkerboard_fit(time, y_data, tau='Auto', y_inf='Auto', checkerboard_iters=50, fit_scaling=True)

Performs a ‘checkerboard’ DRT fit by iteratively fitting capacitive and inductive effects in supplied data (y)

Parameters:

• time (arraylike, shape (n,)) – Time values over which the simulated experiment took place

• y_data (arraylike, shape (n,)) – Data for model fitting

• tau ({'Auto', tuple(tau_min, tau_max, m), array_like of shape (m,)} (optional)) –

  The tau values used in the model

  y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

  ’Auto’ will use the ‘calculate_tau’ method to determine lifetimes for fitting. Passing a tuple in the form (tau_min, tau_max, m) will generate a logarithmic array of m values between tau_min and tau_max. Any passed array_like that isn’t a tuple of length 3 will be used for all tau values. Default ‘Auto’.

• y_inf ({'Auto', float} (optional)) – Amplitude of steady state signal, assumed to be at y(infinity) when set to ‘Auto’. (Default ‘Auto’)

• checkerboard_iters (int, optional) – The number of iterations to perform using the checkerboard fitting method. (Default 50)

• fit_scaling (bool, optional) – Determines whether minmax scaling is used during each call of the ‘linear_fit’ method. Can impact the smoothness of the MSE and R^2 over many iterations. Default True.

Returns:

fits – An array of fit objects corresponding to each iteration of the checkerboard procedure.

Return type:

arraylike(DRT_Fit_Results), shape (checkerboard_iters,)

Raises:

• FitError – Invalid input: input time and input data (y_data) have mismatch lengths

• FitError – Invalid input: ‘tau’ must be either ‘Auto’, a tuple of length 3, or an array-like of length n

• FitError – Invalid input: ‘y_inf’ must be either ‘Auto’ or a float

pySIMsalabim.aux_funcs.DRT.linear_fit(time, y_data, tau='Auto', y_inf='Auto', bounds=None, scaling=True)

Performs a linear fit of

y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

to the data (y_data)

Converts the linear fit problem to a convex quadratic program and minimises using the Operator Splitting Quadratic Program (OSQP) package solver [2]. Using a QP solver was inspired by the pyDRTtools package [3].

Parameters:

• time (numpy.ndarray, shape (n,)) – Time values over which the simulated experiment took place

• y_data (numpy.ndarray, shape (n,)) – Data for model fitting

• tau ({'Auto', (tau_min, tau_max, m), array_like of shape (m,)} (optional)) –

  The tau values used in the model

  y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

  ’Auto’ will use the ‘calculate_tau’ method to determine lifetimes for fitting. Passing a tuple in the form (tau_min, tau_max, m) will generate a logarithmic array of m values between tau_min and tau_max. Any passed array_like that isn’t a tuple of length 3 will be used for all tau values. Default ‘Auto’.

• bounds ({None, (lower, upper)} (optional)) – Sets the bounds for the fitted coeffs. U. Use np.inf for unbounded limit. Default None.

• scaling (bool (optional)) – Determines whether minmax scaling is applied to the data before fitting (the data is scaled back post fit). Would recomend leaving at default value. Default True.

• Results

• -------

• fit (DRT_Fit_Result) – Fit object containing fit data.

pySIMsalabim.aux_funcs.DRT.main(argv=None)

Script entry point for running a checkerboard fit.

Parameters:

argv ([str] (optional)) – List of strings containing command line args and flags. Default None

Returns:

EXIT_CODE – 0 on a success 1 on a failure 2 on a failure due to a usage error

Return type:

int

pySIMsalabim.aux_funcs.DRT.parse_arguments(argv=None)

Parses command line arguments into an ArgumentParser object

Parameters:

argv ({[str] or Dict[str, str]} (optional)) – List or dictrionary of strings containing command line args and flags. If list, must be in the format [dataFile_path, ‘-flag1’, argument1, ‘-flag2’, argument2, …]. If dict, must be in the format {‘dataFile’ : dataFile_path, ‘flag1’ : argument1, …} If none, parses sys.argv[1:] instead.

Returns:

args

Return type:

argparse.ArgumentParser

Example

# Parses sys.argv[1:] args1 = parse_arguments()

# Parses a list args2 = parse_arguments([‘dataFile.txt’, ‘-timeCol’, ‘time’, ‘-iters’, ‘20’])

# Parses a dictionary args3 = parse_arguments([‘dataFile’ : ‘dataFile.txt’, ‘timeCol’ : ‘time’, ‘iters’ : ‘20’])

pySIMsalabim.aux_funcs.DRT.plot_MSE(error_array, xaxis_label='Iteration', yaxis_label='MSE', plot_title='MSE per Fit Iteration', return_ax=False)

Plots the mean square error. Useful for checking how the MSE varies with iteration during checkerboard fit.

Parameters:

• error_array ({array_like(DRT_Fit_Result) of shape (i,), arraylike(float)}) – An iterable conatining EITHER DRT_Fit_Result objects from which the MSE values are taken OR float values which are considered to be the MSE values

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘Iteration’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the ouput plot. ‘MSE’ by default.

• plot_title (str (optional)) – Title for the output plot. ‘MSE per Fit Iteration’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

pySIMsalabim.aux_funcs.DRT.plot_R_2(error_array, ylim=(0, 1.1), xaxis_label='Iteration', yaxis_label='$R^2$', plot_title='$R^2$ per fit Iteration', return_ax=False)

Plots the R^2 error. Useful for checking how R^2 varies with iteration during checkerboard fit.

Parameters:

• fit_array (array_like(DRT_Fit_Result), shape (i,)) – An iterable conatining DRT_Fit_Result objects from which the R^2 values are taken

• ylim (tuple, (2,) (optional)) – Set the ylimits of the plot. ylim[0] gives the lower bound, y[1] the upper. Default (0, 1.1)

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘Iteration’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the ouput plot. ‘$R^2$’ by default.

• plot_title (str (optional)) – Title for the output plot. ‘$R^2$ per fit Iteration’.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

pySIMsalabim.aux_funcs.DRT.plot_U(tau_model, U_model, tau_analytic=None, U_analytic=None, xaxis_label='$\\tau$ [s]', yaxis_label='U', U_model_label='Model', U_label='Analytic', plot_title='DRT', return_ax=False)

Plot the fitted DRT against an optional analytic DRT

Parameters:

• tau_model (numpy.ndarray, shape (m,)) – The tau values used in the model

• U_model (numpy.ndarray shape (m,)) –

  The coeffs from the DRT fit, given by U in

  y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

• tau_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of tau values use to generate the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• U_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of U values used in the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘$tau$ [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘U’ by default.

• U_model_label (str (optional)) – Label for the curve U_model in the output plot legend. ‘Model’ by default.

• U_label (str (optional)) – Label for the U_analytic curve in the output plot legend. ‘Analytic’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘DRT’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

pySIMsalabim.aux_funcs.DRT.plot_cumulative_U(tau_model, U_model, tau_analytic=None, U_analytic=None, xaxis_label='$\\tau$ [s]', yaxis_label='Cumulative U', U_model_label='Model', U_label='Analytic', plot_title='Cumulative DRT', return_ax=False)

Plot the fitted DRT against an optional analytic DRT

Parameters:

• tau_model (numpy.ndarray, shape (m,)) – The tau values used in the model

• U_model (numpy.ndarray shape (m,)) –

  The coeffs from the DRT fit, given by U in

  y_model = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2)… + U_m*exp(-t/tau_m) + y_inf

• tau_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of tau values use to generate the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• U_analytic ({None, numpy.ndarray shape (l,)} (optional)) – Array of U values used in the analytic curve, if known. This is mostly for comparision if fitting to a known DRT for testing purposes. Default None.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘$tau$ [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘Cumulative U’ by default.

• U_model_label (str (optional)) – Label for the curve U_model in the output plot legend. ‘Model’ by default.

• U_label (str (optional)) – Label for the U_analytic curve in the output plot legend. ‘Analytic’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘Cumulative DRT’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

pySIMsalabim.aux_funcs.DRT.plot_y(time, y_model=None, y_data=None, xaxis_label='Time [s]', yaxis_label='y(t)', y_data_plot_label='Data', y_model_plot_label='Model', plot_title='DRT Fit', return_ax=False)

Plot the fitted model agains the data

Parameters:

• time (numpy.ndarray, shape (n,)) – The time values over which the simulated experiment took place

• y_model ({None, numpy.ndarray shape (n,)} (optional)) – The model predicted curve. Either y_model or y must not be None. y_model is None by default.

• y_data ({None, numpy.ndarray shape (n,)} (optional)) – The data the model was fitted to. Either y_model or y must not be None. y is None by default.

• xaxis_label (str (optional)) – Label for the x axis of the output plot. ‘Time [s]’ by default.

• yaxis_label (str (optional)) – Label for the y axis of the output plot. ‘y(t)’ by default.

• y_plot_label (str (optional)) – Label for the curve y in the output plot legend. ‘Data’ by default.

• y_model_plot_label (str (optional)) – Label for the y_model curve in the output plot legend. ‘Model’ by default.

• plot_title (str (optional)) – Title of the output plot. ‘DRT Fit’ by default.

• return_ax (bool (optional)) – Determines whether the matplotlib.axes.Axes object is returned (True) or plotted (False). Default False.

Returns:

ax – Returned axes object if return_ax is True.

Return type:

matplotlib.axes.Axes (optional)

pySIMsalabim.aux_funcs.DRT.predict_y_model(time, U, tau, y_inf=0)

Calculate the function

predict_y_model(t) = U_1*exp(-t/tau_1) + U_2*exp(-t/tau_2) + … + U_m*exp(-t/tau_m) + y_inf

Parameters:

• time (numpy.ndarray, shape (n,)) – The time values over which the simulated impedance-adjacent experiment takes place

• U (numpy.ndarray with shape (m,)) – Coefficients for the exponential decay functions such that U[i] is the coefficient of exp(-t/tau[i])

• tau (numpy.ndarray with shape (m,)) – The relaxation times used in the model as above.

• y_inf (float (optional)) – The amplitude of the steady state signal in y_data i.e. y(infinity)

Returns:

y_model – predict y_model at all time values in t

Return type:

numpy.ndarray with shape (n,)

pySIMsalabim.aux_funcs.DRT.save_model_errors_to_txt(path, fits, float_format='%.5e')

Save the MSE and R_2 values from a collection of DRT_Fit_Result objects to a txt file.

Parameters:

• path (str) – File path of save file

• fits (arraylike(DRT_Fit_Result)) – Array like object of fit results

• float_format (str (optional)) – Controls how float values are save to file

Return type:

None

pySIMsalabim.aux_funcs.DRT.save_model_predictions_to_txt(path, fits, float_format='%.5e')

Save the y_model values from a collection of DRT_Fit_Result objects to a txt file.

Parameters:

• path (str) – File path of save file

• fits (arraylike(DRT_Fit_Result)) – Array like object of fit results

• time (numpy.ndarray) – Time values over which each fit was made

• float_format (str (optional)) – Controls how float values are save to file

Return type:

None

pySIMsalabim.aux_funcs.DRT.save_models_to_txt(path, fits, float_format='%.5e')

Save the tau and U values from a collection of DRT_Fit_Result objects to a txt file. Stores y_inf as a # comment in the first line of the file.

Parameters:

• path (str) – File path of save file

• fits (arraylike(DRT_Fit_Result)) – Array like object of fit results

• float_format (str (optional)) – Controls how float values are save to file

Return type:

None

pySIMsalabim.aux_funcs.DRT.save_to_json(directory_path, fits)

Saves array of models to .json file in the passed directory

Parameters:

• directory_path (String) – Directory path for save data

• fits (array-like[DRT_Fit_Result])

Return type:

None

pySIMsalabim.aux_funcs.DRT.save_to_txt(directory_path, fits, float_format='%.5e')

Save tau, U, y, MSE, and R_2 values from a collection of fit objects to text files.

Parameters:

• directory_path (str) – All save files are saved to this directory

• fits (arraylike(DRT_Fit_Result)) – Array like object of fit results

• time (numpy.ndarray) – Time values over which each fit was made

• float_format (str (optional)) – Controls how float values are save to file

Return type:

None

pySIMsalabim.aux_funcs.JV_funcs module

Useful helper functions for pySIMsalabim

pySIMsalabim.aux_funcs.JV_funcs.Find_Solar_Cell_Parameters(Volt, Curr, max_interpolation_order=3, threshold_err=0.05)

Finds Jsc, Voc, MPP (and thus FF) by interpolating the V-J data points

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

• max_interpolation_order (int, optional) – Maximum order of the interpolation polynomial, by default 3

• threshold_err (float, optional) – Maximum allowable error for interpolation, by default 0.05

Returns:

Dictionary containing the extracted solar cell parameters.

Return type:

dict

pySIMsalabim.aux_funcs.JV_funcs.Fit_Parabola(x1, x2, x3, y1, y2, y3)

Fits a parabola through [(x1, y1), (x2, y2), (x3,y3)], y = ax^2 + bx + c

Parameters:

• x1 (float) – X-coordinates of the three points.

• x2 (float) – X-coordinates of the three points.

• x3 (float) – X-coordinates of the three points.

• y1 (float) – Y-coordinates of the three points.

• y2 (float) – Y-coordinates of the three points.

• y3 (float) – Y-coordinates of the three points.

Returns:

• a (float) – Quadratic coefficient.

• b (float) – Linear coefficient.

• c (float) – Constant term.

pySIMsalabim.aux_funcs.JV_funcs.InterExtraPolation(x, y, x0, order, extra_index=0)

Interpolation / extrapolation routine. This is a wrapper for Neville’s algorithm.

Parameters:

• x (1D numpy array) – Array of x values (ascending or descending).

• y (1D numpy array) – Array of y values corresponding to x.

• x0 (float) – Target value to interpolate or extrapolate.

• order (int) – Order of the interpolation polynomial.

• extra_index (int, optional) –

  Extrapolation control:

  0 -> no extrapolation allowed 1 -> limited extrapolation 2 -> full extrapolation

  ,by default 0

Returns:

success (bool), y_estimate (float), err_estimate (float)

Return type:

tuple

Raises:

ValueError – If the interpolation order is invalid.

pySIMsalabim.aux_funcs.JV_funcs.Locate(x, x0, imin, imax)

Simple, slow, (hopefully) robust routine to an index within

row x (from imin to imax). x0 is some target we’re looking for. The resulting index is such that x0 sits between x[i] and x[i+1] if x0 is outside the interval determined by x[imin], x[imax] then it returns imin-1 or imax+1.

Parameters:

• x (1D numpy array) – Array of x values (ascending or descending).

• x0 (float) – Target value to locate within x.

• imin (int) – Minimum index to consider.

• imax (int) – Maximum index to consider.

Returns:

Index i such that x0 sits between x[i] and x[i+1], or imin-1 or imax+1 if x0 is outside the interval.

Return type:

int

pySIMsalabim.aux_funcs.JV_funcs.Neville(x0, x, y, n=None)

Neville interpolation.

Parameters:

• x0 (float) – x0: x of desired point

• x (1D numpy array) – Array of x values (ascending or descending).

• y (1D numpy array) – Array of y values corresponding to x.

• n (int, optional) – Number of points to use (Defaults to len(x)).

Returns:

• float – Interpolated y value at x0.

• float – Estimated error of the interpolation.

pySIMsalabim.aux_funcs.JV_funcs.get_FF(Volt, Curr)

Get the fill factor (FF) from solar cell JV-curve by calculating the maximum power point

Parameters:

• Volt (1-D sequence of floats) – Array containing the voltages.

• Curr (1-D sequence of floats) – Array containing the current-densities.

Returns:

FF – Fill factor value

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_FF_SIMsalabim(Volt, Curr, max_interpolation_order=3, threshold_err=0.05)

SIMsalabim-style FF extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

• max_interpolation_order (int, optional) – Maximum order of the interpolation polynomial, by default 3

• threshold_err (float, optional) – Maximum allowable error for interpolation, by default 0.05

Returns:

Extracted fill factor (FF) value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_Jsc(Volt, Curr)

Get the short-circuit current (Jsc) from solar cell JV-curve by interpolating the current at 0 V

Parameters:

• Volt (1-D sequence of floats) – Array containing the voltages.

• Curr (1-D sequence of floats) – Array containing the current-densities.

Returns:

Jsc – Short-circuit current value

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_Jsc_SIMsalabim(Volt, Curr, max_interpolation_order=3, threshold_err=0.05)

SIMsalabim-style Jsc extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

• max_interpolation_order (int, optional) – Maximum order of the interpolation polynomial, by default 3

• threshold_err (float, optional) – Maximum allowable error for interpolation, by default 0.05

Returns:

Extracted short-circuit current (Jsc) value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_PCE(Volt, Curr, suns=1)

Get the power conversion efficiency (PCE) from solar cell JV-curve

Parameters:

• Volt (1-D sequence of floats) – Array containing the voltages.

• Curr (1-D sequence of floats) – Array containing the current-densities.

Returns:

PCE – Power conversion efficiency value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_PCE_SIMsalabim(Volt, Curr, suns=1, max_interpolation_order=3, threshold_err=0.05)

SIMsalabim-style PCE extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

• suns (int, optional) – Number of suns for illumination, by default 1

• max_interpolation_order (int, optional) – Maximum order of the interpolation polynomial, by default 3

• threshold_err (float, optional) – Maximum allowable error for interpolation, by default 0.05

Returns:

Extracted power conversion efficiency (PCE) value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_Vmpp_SIMsalabim(Volt, Curr)

SIMsalabim-style Vmpp extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

Returns:

Extracted voltage at maximum power point (Vmpp) value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_Voc(Volt, Curr)

Get the Open-circuit voltage (Voc) from solar cell JV-curve by interpolating the Voltage when the current is 0

Parameters:

• Volt (1-D sequence of floats) – Array containing the voltages.

• Curr (1-D sequence of floats) – Array containing the current-densities.

Returns:

Voc – Open-circuit voltage value

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_Voc_SIMsalabim(Volt, Curr, max_interpolation_order=3, threshold_err=0.05)

SIMsalabim-style Voc extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

• max_interpolation_order (int, optional) – Maximum order of the interpolation polynomial, by default 3

• threshold_err (float, optional) – Maximum allowable error for interpolation, by default 0.05

Returns:

Extracted open-circuit voltage (Voc) value.

Return type:

float

pySIMsalabim.aux_funcs.JV_funcs.get_ideality_factor(suns, Vocs, T=295)

Returns ideality factor from suns-Voc data linear fit of Voc = (nIF/Vt)*log(suns) + intercept

Parameters:

• suns (1-D sequence of floats) – Array containing the intensity in sun.

• Vocs (1-D sequence of floats) – Array containing the open-circuit voltages.

• T (float optional) – Temperature in Kelvin (Default = 295 K).

Returns:

• nIF (float) – Ideality factor value.

• intercept (float) – Intercept of the regression line.

• rvalue (float) – Correlation coefficient.

• pvalue (float) – Two-sided p-value for a hypothesis test whose null hypothesis is that the slope is zero, using Wald Test with t-distribution of the test statistic.

• stderr (float) – Standard error of the estimated gradient.

pySIMsalabim.aux_funcs.JV_funcs.get_mpp_SIMsalabim(Volt, Curr)

SIMsalabim-style MPP extraction (standalone).

Parameters:

• Volt (1D numpy array) – Array of voltage values.

• Curr (1D numpy array) – Array of current values corresponding to Volt.

Returns:

Extracted maximum power point (MPP) value.

Return type:

float

pySIMsalabim.aux_funcs.PathChecksWin module

Check and convert Windows paths to long path format if necessary.

pySIMsalabim.aux_funcs.PathChecksWin.convert_to_long_path(tempPath)

Convert a path to a Windows long path by adding the \?prefix

Parameters:

tempPath (string) – Path to be converted

Returns:

Converted Path object with long path prefix

Return type:

Path

pySIMsalabim.aux_funcs.SCLC_funcs module

pySIMsalabim.aux_funcs.SCLC_funcs.Make_SCLC_plot(ax, data_JV, x='Vext', y=['Jext'], show_tangent=[1, 2, 3], xlimits=[], ylimits=[], plot_type=0, labels='', colors='b', line_type=['-'], mark='', legend=True, plot_jvexp=False, data_JVexp=Empty DataFrame Columns: [] Index: [], save_yes=False, pic_save_name='JV.jpg')

Make typical plot for SCLC measurement analysis for SIMsalabim

Parameters:

• num_fig (int) – number of the fig to plot JV

• data_JV (DataFrame) – Panda DataFrame containing JV_file

• x (str, optional) – xaxis data (default = ‘Vext’), by default ‘Vext’

• y (list of str, optional) – yaxis data can be multiple like [‘Jext’,’Jbimo’] (default = [‘Jext’]), by default [‘Jext’]

• show_tangent (list of int, optional) – show tangent line at V1,Vinf,V2 (default = [1,2,3]), by default [1,2,3]

• xlimits (list, optional) – x axis limits if = [] it lets python chose limits, by default []

• ylimits (list, optional) – y axis limits if = [] it lets python chose limits, by default []

• plot_type (int, optional) – type of plot 1 = logx, 2 = logy, 3 = loglog else linlin (default = linlin), by default 0

• labels (str, optional) – label of the JV, by default ‘’

• colors (str, optional) – color for the JV line, by default ‘b’

• line_type (list, optional) – type of line for simulated data plot size line_type need to be = size(y), by default [‘-‘]

• mark (str, optional) – type of Marker for the JV, by default ‘’

• legend (bool, optional) – Display legend or not, by default True

• plot_jvexp (bool, optional) – plot an experimental JV or not, by default False

• data_JVexp ([type], optional) – Panda DataFrame containing experimental JV_file with ‘V’ the voltage and ‘J’ the current, by default pd.DataFrame()

• save_yes (bool, optional) – If True, save JV as an image with the file name defined by “pic_save_name”, by default False

• pic_save_name (str, optional) – name of the file where the figure is saved, by default ‘JV.jpg’

Returns:

• Vslopef (list) – list of of the Voltage values after filtering

• Jslopef (list) – list of of the current values after filtering

• slopesf (list) – list of logarithmic slopes of the JV after filtering

• get_tangentf (bool) – True if tangents are calculated i.e. if max(slopef) > 2, False if not

• idx_maxf (int) – index of the max slope of the JV after filtering

• max_slopesf (float) – max slope of the JV after filtering

• tang_val_V1f (list) – list of the tangent values of the JV after filtering for the first tangent point. Typically crossing between the ohmic and Trap filled limited regime.

• tang_val_V2f (list) – list of the tangent values of the JV after filtering for the second tangent point (here the inflexion point)

• tang_val_V3f (list) – list of the tangent values of the JV after filtering for the third tangent point. Typically crossing between the Trap filled limited regime and the Mott-Gurney regime.

• V1f (float) – Voltage value of the first crossing point

• J1f (float) – current value of the first crossing point

• V2f (float) – Voltage value of the second crossing point

• J2f (float) – current value of the second crossing point

• Vinf (float) – Voltage value of the inflexion point

• Jinf (float) – current value of the inflexion point

pySIMsalabim.aux_funcs.SCLC_funcs.MottGurney(V, mu, eps_r, Vbi, L)

Mott-Gurney equation typically used to fit single carrier devices JVs to get the mobility.

J = (9/8)*eps_0*eps_r*mu*((V-Vbi)**2)/(L**3)

Refs: Mott N F and Gurney R W 1940 Electronic Processes in Ionic Crystals (Oxford: Oxford University Press) Nice paper to read on MG ==> J. Phys.: Condens. Matter 30 (2018) 105901

Parameters:

• V (1-D sequence of floats) – Array containing the voltages (V)

• mu (float) – Mobility (m^2/(Vs))

• eps_r (float) – Relative dielectric constant

• Vbi (float) – Built-in voltage (V)

• L (float) – Thickness (m)

Returns:

Array containing the current-density (A m^-2)

Return type:

1-D sequence of floats

pySIMsalabim.aux_funcs.SCLC_funcs.SCLC_get_data_plot(volt, curr)

Get the data for the SCLC plot

Parameters:

• volt (1-D sequence of floats) – Voltage data

• curr (1-D sequence of floats) – Current data

Returns:

• V_slopef (1-D sequence of floats) – Voltage data after filtering

• J_slopef (1-D sequence of floats) – Current data after filtering

• slopesf (1-D sequence of floats) – logarithmic slopes of the JV after filtering

• get_tangentf (bool) – True if tangents are calculated i.e. if max(slopef) > 2, False if not

• idx_maxf (int) – index of the max slope of the JV after filtering

• max_slopesf (float) – max slope of the JV after filtering

• tang_val_V1f (1-D sequence of floats) – tangent values of the JV after filtering for the first tangent point. Typically crossing between the ohmic and Trap filled limited regime.

• tang_val_V2f (1-D sequence of floats) – tangent values of the JV after filtering for the second tangent point (here the inflexion point)

• tang_val_V3f (1-D sequence of floats) – tangent values of the JV after filtering for the third tangent point. Typically crossing between the Trap filled limited regime and the Mott-Gurney regime.

• V1f (float) – Voltage value of the first crossing point

• J1f (float) – current value of the first crossing point

• V2f (float) – Voltage value of the second crossing point

• J2f (float) – current value of the second crossing point

• Vinf (float) – Voltage value of the inflexion point

• Jinf (float) – current value of the inflexion point

pySIMsalabim.aux_funcs.SCLC_funcs.calc_Vnet_with_ions(ions, traps, L, eps_r)

Calculate Vnet for SCLC measurement in the presence of Ions as defined in equation (4) in ACS Energy Lett. 2021, 6, 3, 1087–1094 https://doi.org/10.1021/acsenergylett.0c02599

Vnet = q * n_net * L**2 /( 2 * eps_0 * eps_r) = q * (traps-ions) * L**2 /( 2 * eps_0 * eps_r)

Parameters:

• ions (float) – Ion density (m^-3)

• traps (float) – Trap density (m^-3)

• L (float) – Thickness (m)

• eps_r (float) – Relative dielectric constant

Returns:

returns vnet as defined in

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.calc_Vsat(L, Nc, phi, eps_r, T)

Calculate Vsat for SCLC measurement as defined in equation (15) in https://doi.org/10.1021/acsenergylett.0c02599

Vsat = (8/9) * ((q*Nc*L**2)/(eps_0*eps_r))*exp(-q*phi/k*T)

Parameters:

• L (float) – Thickness (m)

• Nc (float) – Effective density of states (m^-3)

• phi (float) – Injection barrier (V)

• eps_r (float) – Relative dielectric constant

• T (float) – Temperature (K)

Returns:

returns Vsat as defined in

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.calc_Vtfl(traps, L, eps_r)

Calculate VTFL for SCLC measurement as defined in equation (2) in ACS Energy Lett. 2021, 6, 3, 1087–1094 https://doi.org/10.1021/acsenergylett.0c02599

Vnet = q * n_traps * L**2 /( 2 * eps_0 * eps_r)

Parameters:

• traps (float) – Trap density (m^-3)

• L (float) – Thickness (m)

• eps_r (float) – Relative dielectric constant

Returns:

returns vnet as defined in

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.calc_net_charge(Vnet, L, eps_r)

Calculate the net charge for SCLC measurement as defined in equation (4) in ACS Energy Lett. 2021, 6, 3, 1087–1094 https://doi.org/10.1021/acsenergylett.0c02599

Vnet = q * n_net * L**2 /( 2 * eps_0 * eps_r)

Note that if there are not ions or dopant n_net = traps

Parameters:

• Vnet (float) – Vnet see ref

• L (float) – Thickness (m)

• eps_r (float) – Relative dielectric constant

Returns:

net-charge in the bulk

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.calc_nt_min(L, eps_r, T)

Calculate the minimum appearant trap density for SCLC measurement as defined in equation (3) in ACS Energy Lett. 2021, 6, 3, 1087–1094 https://doi.org/10.1021/acsenergylett.0c02599

Ntmin = 4*np.Pi()**2*((k*T)/(q**2))*((eps_0*eps_r)/(L**2))

Parameters:

• L (float) – Thickness (m)

• eps_r (float) – Relative dielectric constant

• T (float) – Temperature (K)

Returns:

minimum appearant trap density

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.calc_trap_charge(Vnet, L, eps_r)

Calculate the trap charges for SCLC measurement as defined in equation (2) in ACS Energy Lett. 2021, 6, 3, 1087–1094 https://doi.org/10.1021/acsenergylett.0c02599

Vnet = q * n_trap * L**2 /( 2 * eps_0 * eps_r)

Note that if there are not ions or dopant n_net = traps

Parameters:

• Vtfl (float) – Vtfl see ref

• L (float) – Thickness (m)

• eps_r (float) – Relative dielectric constant

Returns:

trapped charges in the bulk

Return type:

float

pySIMsalabim.aux_funcs.SCLC_funcs.deriv(x, y)

Get the derivative of input data dy/dx

Parameters:

• x (1-D sequence of floats) – x-axis data

• y (1-D sequence of floats) – y-axis data

Returns:

dy/dx

Return type:

1-D sequence of floats

pySIMsalabim.aux_funcs.SCLC_funcs.fit_MottGurney(V, J, mu, eps_r, Vbi, L, var2fit=['mu'])

Fit the Mott-Gurney equation to the data

Parameters:

• V (1-D sequence of floats) – Array containing the voltages (V)

• J (1-D sequence of floats) – Array containing the current-density (A m^-2)

• mu (float) – Mobility (m^2/(Vs))

• eps_r (float) – Relative dielectric constant

• Vbi (float) – Built-in voltage (V)

• L (float) – Thickness (m)

• var2fit (list, optional) – Chose variable to fit (can be multiple), by default [‘mu’]

Returns:

list of the fitted values in the same order than var2fit

Return type:

list

pySIMsalabim.aux_funcs.SCLC_funcs.log_slope(x, y)

Get the slope of the logarithmic data

Parameters:

• x (1-D sequence of floats) – x-axis data

• y (1-D sequence of floats) – y-axis data

Returns:

slope of the logarithmic data

Return type:

1-D sequence of floats

pySIMsalabim.aux_funcs.addons module

Useful helper functions for pySIMsalabim

pySIMsalabim.aux_funcs.addons.sci_notation(number, sig_fig=2)

Make proper scientific notation for graphs

Parameters:

• number (float) – Number to put in scientific notation.

• sig_fig (int, optional) – Number of significant digits (Defaults = 2).

Returns:

output – String containing the number in scientific notation

Return type:

str

pySIMsalabim.aux_funcs.light_pulse module

Functions to run a ZimT simulation using a (Gaussian) light pulse

pySIMsalabim.aux_funcs.light_pulse.create_spectrum(I_pulse, wavelength, FWHM, session_path, spectrum_name, spectrum_path='', lambda_min=2.8e-07, lambda_max=4e-06, lambda_step=1e-09)

Create a spectrum file with monochrqamtic wavelength, which contains the wavelength (lambda) and the irradiance (I) for each wavelength. The spectrum is defined as a Gaussian pulse with the specified parameters.

Parameters:

• I_pulse (float) – The intensity of the pulse in photons/m^2/pulse

• wavelength (float) – The wavelength of the pulse in meters

• FWHM (float) – The full width at half maximum (FWHM) of the pulse

• session_path (string) – The path to the session folder, which is the working directory for the simulation

• spectrum_name (string) – The name of the spectrum file to create, which will be saved in the session path/spectrum_path

• spectrum_path (string, optional) – The path to the folder where the spectrum file will be saved, relative to the session path, by default ‘’

• lambda_min (float, optional) – The minimum wavelength to include in the spectrum, by default 280E-9

• lambda_max (float, optional) – The maximum wavelength to include in the spectrum, by default 4000E-9

• lambda_step (float, optional) – The wavelength step to use in the spectrum, by default 1E-9

Returns:

The path to the created spectrum file, relative to the session path

Return type:

string

pySIMsalabim.aux_funcs.light_pulse.create_tVG_light_pulse(tmax, tVG_name, session_path, t_scale='lin', t_step=1e-09, t_pulse=4e-08, FWHM=2e-09)

Create a tVG file for a light pulse simulation, which contains the time (t), the external voltage (Vext), and the generation profile (G_frac) for each time step. The generation profile is defined as a Gaussian pulse with the specified parameters.

Parameters:

• tmax (float) – The maximum time for the experiment

• tVG_name (string) – The name of the tVG file to create, which will be saved in the session path

• session_path (string) – The path to the session folder, which is the working directory for the simulation

• t_scale (string, optional) – The time scale to use for the time array, which can be ‘lin’ for linear or ‘log’ for logarithmic, by default ‘lin’

• t_step (float, optional) – The time step when using a linear scale and the shortest timestep using a logarithmic scale, by default 1E-9. Note: Make sure the time step is small enough to accurately describe the laser pulse, as defined by the FWHM.

• t_pulse (float, optional) – The center of the pulse in time. Make sure it is far enough from t=0 otherwise first part of pulse will be cut, resulting in lower number of photons, by default 40

• FWHM (float, optional) – The full width at half maximum (FWHM) of the pulse, by default 2E-9

Returns:

• int – 0 if the tVG file is created successfully, -1 if there is an error

• string – A message indicating the success or failure of the tVG file creation

pySIMsalabim.aux_funcs.light_pulse.run_light_pulse_simu(zimt_simulation_setup, session_path, t_max, t_scale, t_step, t_pulse, FWHM, genProfile, spectrum_type='laser', I=6000000000000000.0, wavelength=6.4e-07, run_mode=False, tVG_name='tVG.txt', tj_name='tj.dat', log_name='log.txt', varFile='none', cmd_pars=None, turnoff_autoTidy=True, verbose=False, threadsafe=False)

Run a ZimT simulation for a (gaussian) light pulse. The function will create the necessary tVG file, as well as take into account the type of generation profile specified by the user, and create the necessary spectrum file if needed. The function will also handle the use of blocking layers, by updating the simulation setup file and creating the necessary blocking layer parameter files.

Parameters:

• zimt_simulation_setup (string) – The name of the ZimT device parameters file, which should be located in the session path

• session_path (string) – The path to the session folder, which is the working directory for the simulation

• t_max (float) – The maximum time for the experiment

• t_scale (string) – The time scale to use for the time array, which can be ‘lin’ for linear or ‘log’ for logarithmic

• t_step (float) – The time step for the tVG file

• t_pulse (float) – The center of the pulse in time. Make sure it is far enough from t=0 otherwise first part of pulse will be cut, resulting in lower number of photons

• FWHM (float) – The full width at half maximum (FWHM) of the pulse

• genProfile (string) – The type of generation profile to use, which can be ‘calc’ for a calculated generation profile based on a spectrum, ‘none’ for no generation profile (in which case the generation rate should be specified in the simulation setup file or through cmd_pars), or a filename for a user supplied generation profile (in which case the file should be located in the session path)

• spectrum_type (string, optional) – The type of spectrum to use for the calculated generation profile, which can be ‘laser’ for a Gaussian spectrum based on the specified intensity, wavelength, and FWHM, or ‘setup’ to use the spectrum as specified in the simulation setup file, by default ‘laser’

• I (float, optional) – The intensity of the pulse in photons/m^2/pulse, only used when genProfile is ‘calc’ and spectrum_type is ‘laser’, by default 6E15

• wavelength (float, optional) – The wavelength of the pulse in meters, only used when genProfile is ‘calc’ and spectrum_type is ‘laser’, by default 640E-9

• run_mode (bool, optional) – If False, show verbose output in console, by default False

• tVG_name (string, optional) – The name of the tVG file, by default ‘tVG.txt’

• tj_name (string, optional) – The name of the tJ file, by default ‘tj.dat’

• log_name (string, optional) – The name of the log file, by default ‘log.txt’

• varFile (string, optional) – The name of the var file to create, by default ‘none’. If ‘none’, no var file will be created and the varFile parameter will not be passed to ZimT.

• cmd_pars (list of dict, optional) – A list of dictionaries with the parameters to update in the simulation setup file, where each dictionary should have the format {‘par’: ‘parameter_name’, ‘val’: ‘parameter_value’}, by default None

• turnoff_autoTidy (bool, optional) – Whether to turn off the autoTidy option in ZimT, by default True

• verbose (bool, optional) – Use verbose output, by default False

• threadsafe (bool, optional) – Whether to force run the simulation in a thread-safe way, by default False

Returns:

• int – 0 if the simulation ran successfully, -1 if there was an error

• string – A message indicating the success or failure of the simulation

Module contents