API Documentation

Blocks module

This module contains all of the classes that represent distinct blocks within a battery simulation.

class battery_sizing_model.blocks.Battery(cell_chemistry: str, pack_capacity: float, pack_voltage: float = 0, cell_discharge_energy_eff: float = 1, cell_charge_energy_eff: float = 1)

Represents a full battery pack of a single chemistry.

Attributes

cell_chemistry : str

Chemistry of the battery. Currently only supports NCA.

pack_capacity : float

Capacity of the pack in Watt-hours.

pack_voltage : float, optional

Rated voltage of the pack, doesn’t have any bearing on the performance of the simulation. Default = 0.

cell_dishcarge_energy_eff : float, optional

Energy efficiency of the battery during discharge. Default = 1.

cell_charge_energy_eff : float, optional

Energy efficiency of the battery during charge. Default = 1.

cell_capacity_ah : float

Cell capacity in Amp-hours.

cell_capacity_wh : float

Cell capacity in Watt-hours.

cell_nom_voltage : float

Nominal voltage of the cell.

cell_min_voltage : float

Minimum voltage of the cell.

price_per_kwh : float

Estimated price_per_kwh of the cell chemistry.

capital_cost : float

Capital cost of the battery pack cells.

num_series : int

Calculated number of cells in series in the pack. Only valid if pack_voltage > 0.

num_parallel : int

Calculated number of cells in parallel in the pack.

get_current(power: float) → float

Calculates current in Amps from nominal voltage and input/output power.

Parameters

power : float

Input power signal for the battery at each step in the simulation.

Returns

float

Calculated cell current using the cell nominal voltage.

class battery_sizing_model.blocks.BatterySimulator(ecm: ECM, ocv: OCVTable, integrator: SOCIntegrator, deg_model: DegradationModel, battery: Battery, soc: float = 1, soh: float = 1)

Represents a simulation for a battery.

Attributes

ecm : ECM

Equivalent circuit model object.

ocv : OCVTable

Open circuit voltgate lookup table object.

integrator : SOCIntegrator

State of charge integrator.

deg_model : DegradationModel

State of health estimation model.

battery : Battery

Battery object.

soc : float

State of charge at this step.

soh : float

State of health at this step.

voltage : float

Voltage at this step.

soh_i : float

Beginning of life state of health.

nom_cap : float

Cell nominal capacity.

voltage_result : list[float]

Estimated voltage for every step in the simulation.

current_result : list[float]

Calculated current for every step in the simulation.

soc_result : list[float]

State of charge calculated at every step in the simulation.

soh_result : list[float]

State of health calculated every 340 hours of simulation.

run(power: list[float], timestep: float, validate: bool = False) → None

Simulation loop that estimates battery state of health, state of charge, and voltage.

Parameters

power : array[float]

Entire power signal for the battery with magnitudes on the pack level scale. Points are spaced out in time with a distance of timestep between them.

timestep : float

Timestep of the simulation.

validate : bool

Flag for turning off error checking to account for varying charge/discharge efficiencies in real life data.

exception battery_sizing_model.blocks.CapacityError(*args: object, message='State of charge is greater than the current state of health or less than 0.')

class battery_sizing_model.blocks.DegradationModel(ref_soc: float = 0.5)

Represents a model that predicts the battery SOH.

Attributes

model_params : numpy.array

Fitted coefficients for the model using molicel P42A cell data.

dod : list

Depth of discharge of every step in the simulation.

delta_soc : float

Change in state of charge between steps.

soc_sign : int

1 for positive change in state of charge. -1 for negative change in state of charge.

ref_soc : float

Reference state of charge for the depth of discharge calculation.

soc_chg : float

Amount of charge added to the battery for each step.

cycle_chg : int

Number of equivalent full cycles * 2.

get_dod()

Getter for depth of discharge.

get_efc()

Getter for equivalent full cycles.

increment_dod(prev_soc: float, curr_soc: float) → None

Increments the depth of discharge based on the previoius and current soc.

DOD is only calculated if the sign of the current changes.

Parameters

prev_soc : float

Previous steps state of charge.

curr_soc : float

Current steps state of charge.

increment_efc(prev_soc: float, curr_soc: float) → None

Increments the equivalent full cycle value given the previous and current state of charge.

An equivalent full cycle is counted when the battery has experienced enough cumulative charge to fully charge or discharge the battery.

Parameters

prev_soc : float

Previous steps state of charge.

curr_soc : float

Current steps state of charge.

model(efc: float, c_rate: list[float], dod: list[float], t: float, soh_i: float) → float

State of health estimation model that estimates the state of health of the battery for a given time-period.

Parameters

efc : float

Equivalent full cycles, defined as the amount of charge needed to fully charge or discharge the battery. See increment_efc().

c_rate : list[float]

C-rate for every soh estimation step.

dod : list[float]

Depth of discharge for every soh estimation step. See increment_dod().

t : float

Total time in hours that the battery has existed.

soh_i : float

Beginning of life state of health of the battery.

Returns

float

Estimeated state of health for the given input parameters.

class battery_sizing_model.blocks.ECM(num_rc_pairs: int, R0: float, R: list[float], C: list[float], timestep: int)

Represents an equivalent circuit model.

This class is used for simulating a circuit given circuit parameters.

Currently only supports multi-RC Randles circuits.

Attributes

r0 : float

Series resistance of the Randles circuit.

R : numpy.array

Array of resistances in the RC pairs.

C : numpy.array

Array of capacitances in the RC pairs.

A_rc : numpy.array

State matrix for the circuit.

B_rc : numpy.array

Control matrix for the circuit.

I_rk : numpy.array

Previous current estimate through the RC pairs.

step(I_k: float, ocv: float) → float

Steps the circuit model forward one timestep.

Parameters

I_k : float

Current input for the this step.

ocv : float

Open circuit voltage from the ocv table.

Returns

float

Predicted battery voltage.

class battery_sizing_model.blocks.OCVTable

Represents an open circuit voltage lookup table.

Currently only supports the molicel P42A cell (NCA).

Attributes

charge_ocv : dict

Charge open circuit voltage indexed by state of health.

discharge_ocv : dict

Discharge open circuit voltage indexed by state of health.

x : array

Interpolation points for the lookup table.

get_charge_ocv(soh: float, soc: float) → float

Gets the charge open circuit voltage from a lookup table.

Parameters

soh : float

Current state of health of the battery.

soc : float

Current state of charge of the battery.

Returns

float

Open circuit voltage from a lookup table.

get_discharge_ocv(soh: float, soc: float) → float

Gets the discharge open circuit voltage from a lookup table.

Parameters

soh : float

Current state of health of the battery.

soc : float

Current state of charge of the battery.

Returns

float

Open circuit voltage from a lookup table.

class battery_sizing_model.blocks.SOCIntegrator(charge_eff: float = 1, discharge_eff: float = 1, validate: bool = False)

Represents an integrator for counting couloumbs and calculating state of charge.

Attributes

charge_eff : float, optional

Charge efficiency of the battery [0,1]. Default = 1.

discharge_eff : float, optional

Discharge efficiency of the battery [0,1]. Default = 1.

validate : bool, optional

Flag for indicating whether the sim should compensate for the varying charge/discharge efficiency in real data when validating. Default = False.

step(soc_k: float, timestep: float, I_k: float, nom_cap: float) → float

Integrate the current for this timestep.

Assumes that current is constant over the sampling interval.

Parameters

soc_k : float

State of charge of the previous step.

timestep : float

Duration in time for this step.

I_k : float

Current for this step.

nom_cap : float

Nominal capacity of the battery.

Returns

float

State of charge from this step.