bmlite.SPM

A packaged single particle model (SPM). Build a model using the Simulation class, and run an experiment using either the run() or run_step() methods. These methods return Solution class instances with post processing, plotting, and saving methods.

Submodules

• bmlite.SPM.dae
• bmlite.SPM.domains
• bmlite.SPM.postutils

Classes

CycleSolution	All-step solution.
Simulation	Make a SPM simulation capable of running various experiments.
StepSolution	Single-step solution.

Package Contents

class bmlite.SPM.CycleSolution(*soln, t_shift=0.001)

All-step solution.

A solution instance with all experiment steps stitch together into a single cycle.

Parameters:

• *soln (StepSolution) – All unpacked StepSolution instances to stitch together. The given steps should be given in the same sequential order that they were run.

• t_shift (float) – Time (in seconds) to shift step solutions by when stitching them together. If zero the end time of each step overlaps the starting time of its following step. The default is 1e-3.

get_steps(idx)

Return a subset of the solution.

Parameters:

idx (int | tuple) – The step index (int) or first/last indices (tuple) to return.

Returns:

StepSolution | CycleSolution – The returned solution subset. A StepSolution is returned if ‘idx’ is an int, and a CycleSolution will be returned for the range of requested steps when ‘idx’ is a tuple.

property solvetime: str

Print a statement specifying how long IDASolver spent integrating.

Returns:

solvetime (str) – An f-string with the total solver integration time in seconds.

class bmlite.SPM.Simulation(yamlfile='graphite_nmc532')

Make a SPM simulation capable of running various experiments.

The initialization will add all of the battery attributes from the .yaml file under its bat, el, an, and ca attributes. The pre() method runs at the end of the initialization to add dependent parameters, including the mesh, algebraic indices, etc. to the simulation instance. This only happens in __init__, which has some implications if the user modifies parameters after initialization (see the warning below).

Parameters:

yamlfile (str, optional) – An absolute or relative path to the .yaml file that defines the battery properties. The .yaml extension will be added to the end of the string if it is not already there. The default is 'default_SPM', which loads an internal file from the bmlite library.

Warning

The user may choose to modify parameters after loading in a .yaml file, however, they will need to manually re-run the pre() method if they do so. Otherwise, the dependent parameters may not be consistent with the user-defined inputs.

See also

bmlite.templates

Get help making your own .yaml file by starting with the default template.

copy()

Create a copy of the Simulation instance.

Returns:

sim (SPM Simulation object) – A unique copy (stored separately in memory) of the Simulation instance.

j_pattern(plot=True, return_bands=False)

Determine the Jacobian pattern.

Parameters:

• plot (bool, optional) – Whether or not to plot the Jacobian pattern. The default is True.

• return_bands (bool, optional) – Whether or not to return the half bandwidths (lower, upper). The default is False.

Returns:

• lband (int) – The lower half bandwidth. Only returned if return_bands=True.

• uband (int) – The upper half bandwidth. Only returned if return_bands=True.

pre()

Pre-process the dependent parameters.

The dependent parameters include A_s, eps_s, eps_AM, sigma_s, and setting the material classes for each domain. In addition, this method determines the mesh, pointers, algebraic indices, bandwidth, and initial solution. pre() is automatically executed in the __init__() method which has some implications if the user modifies parameters after initialization (see the warning below).

Warning

The user may choose to modify parameters after loading in a .yaml file, however, they will need to manually re-run the pre() method if they do so. Otherwise, the dependent parameters may not be consistent with the user-defined inputs.

run(expr, reset_state=True, t_shift=0.001, bar=False)

Run a full experiment.

Parameters:

• expr (Experiment) – An experiment instance.

• reset_state (bool, optional) – If True (default), the internal state of the model will be reset back to a rested condition at ‘soc0’ at the end of all steps. When False, the state does not reset. Instead it will update to match the final state of the last experimental step.

• t_shift (float, optional) – Time (in seconds) to shift step solutions by when stitching them together. If zero the end time of each step overlaps the starting time of its following step. The default is 1e-3.

• bar (bool, optional) – Displays a progress bar showing percentage of completed steps when True. The default is False.

Returns:

soln (Solution) – A SPM solution instance. If the experiment was only one step then a StepSolution will be returned. Otherwise, a CycleSolution is returned with all steps stitched together.

Warning

The default behavior resets the model’s internal state back to a rested condition at ‘soc0’ by calling the pre() method at the end of all steps. This means that if you run a second experiment afterward, it will not start where the previous one left off. Instead, it will start from the original rested condition that the model initialized with. You can bypass this by using reset_state=False, which keeps the state at the end of the final experimental step.

See also

Experiment

Build an experiment.

StepSolution

Wrapper for a single-step solution.

CycleSolution

Wrapper for an all-steps solution.

run_step(expr, stepidx)

Run a single experimental step.

Parameters:

• expr (Experiment) – An experiment instance.

• stepidx (int) – Step index to run. The first step has index 0.

Returns:

StepSolution – Solution to the experimental step.

Warning

The model’s internal state is changed at the end of each experimental step. Consequently, you should not run steps out of order. You should always start with stepidx = 0 and then progress to the subsequent steps afterward. Run pre() after your last step to reset the state back to a rested condition at ‘soc0’, if needed. Alternatively, you can continue running experiments back-to-back without a pre-processing in between if you want the following experiment to pick up from the same state that the last experiment ended.

See also

Experiment

Build an experiment.

StepSolution

Wrapper for a single-step solution.

Notes

Using the run() loops through all steps in an experiment and then stitches their solutions together. Most of the time, this is more convenient. However, advantages for running step-by-step is that it makes it easier to fine tune solver options, and allows for analyses or control decisions in the middle of an experiment.

class bmlite.SPM.StepSolution(sim, idasoln, timer)

Single-step solution.

A solution instance for a single experimental step.

Parameters:

• sim (Simulation) – The simulation instance that was run to produce the solution.

• idasoln (IDAResult) – The unformatted solution returned by IDASolver.

• timer (float) – Amount of time it took for IDASolver to perform the integration.

property solvetime: str

Print a statement specifying how long IDASolver spent integrating.

Returns:

solvetime (str) – An f-string with the solver integration time in seconds.