Extractors (moirae.extractors)

Model-specific algorithms for quickly extracting parameters and state from informative parts of time series data

Base Classes (m.extractors.base)

Interface for extractors

class moirae.extractors.base.BaseExtractor

Bases: object

Base class for tools which determine parameters from special cycles

check_data(data: BatteryDataset)

Verify whether data contains features needed for algorithm

Parameters:

data – Data to be evaluated

Raises:

(ValueError) If the dataset is missing critical information –

extract(data: BatteryDataset) → HealthVariable

Determine parameters of a physics model from battery dataset

Parameters:

data – Data to use for parameter assessment

Returns:

Part of the parameter set for a model.

ECM (m.extractors.ecm)

Extraction algorithms which gather parameters of an ECM

class moirae.extractors.ecm.MaxCapacityExtractor

Bases: BaseExtractor

Estimate the maximum discharge capacity of a battery

Suggested Data: Low current cycles which sample fully charge or discharge a battery

Algorithm:

1. Compute the observed capacity each cycle if not available using CapacityPerCycle.

2. Find the maximum capacity over all provided cycles

extract(data: CellDataset) → MaxTheoreticalCapacity

Determine parameters of a physics model from battery dataset

Parameters:

data – Data to use for parameter assessment

Returns:

Part of the parameter set for a model.

class moirae.extractors.ecm.OCVExtractor(capacity: float | MaxTheoreticalCapacity, soc_points: ndarray | int = 11, soc_requirement: float = 0.95, interpolation_style: str = 'linear')

Bases: BaseExtractor

Estimate the Open Circuit Voltage (OCV) of a battery as a function of state of charge (SOC)

Suggested data: OCV extraction works best when provided with data for a cycle that samples the entire SOC range (at least a range larger than soc_requirement) with a slow charge and discharge rate. Periodic rests are helpful but not required.

Algorithm:

1. Locate cycle with the lowest average voltage during charge and discharge

2. Assign an SOC to each measurement based on capacity

3. Assign a weights to each point based on \(1 / max(\left| current \right|, 1e-6)\). Normalize weights such that they sum to 1.

4. Fit an isotonic regressor to the weighted data.

5. Evaluate the regression at SOC points requested by the user, return as a OpenCircuitVoltage object using the interpolation_style type of spline.

Parameters:

soc_points – SOC points at which to extract OCV or (int) number of grid points.

capacity: float

A-hr

Type:

Assumed capacity of the cell. Units

check_data(data: CellDataset)

Verify whether data contains features needed for algorithm

Parameters:

data – Data to be evaluated

Raises:

(ValueError) If the dataset is missing critical information –

extract(dataset: CellDataset) → OpenCircuitVoltage

Extract an estimate for the OCV of a cell

Parameters:

dataset – Dataset containing an estimate for the nominal capacity and time series measurements.

Returns:

An OCV instance with the requested SOC interpolation points,

interpolate_ocv(cycle: DataFrame) → ndarray

Fit then evaluate a smoothing spline which explains voltage as a function of SOC and current

Parameters:

cycle – Cycle to use for fitting the spline

Returns:

An estimate for the OCV at soc_points

interpolation_style: str

Type of spline used for the output

soc_points: ndarray

State of charge points at which to estimate the resistance

soc_requirement: float

Require that dataset samples at least this fraction of the capacity

class moirae.extractors.ecm.R0Extractor(capacity: float | MaxTheoreticalCapacity, soc_points: ndarray | int = 11, soc_requirement: float = 0.95, dt_max: float = 0.02, dInorm_min: float = 0.1)

Bases: BaseExtractor

Estimate the Instantaneous Resistance (R0) of a battery as a function of state of charge (SOC)

Suggested data: R0 extraction works best when provided with data for a cycle that samples instantaneous changes in current across the entire SOC range (at least a range larger than soc_requirement)

Algorithm:

1. Locate cycle with jumps in current across SOC range

2. Assign an SOC to each measurement based on capacity

3. Calculate instantanous resistance as dI/dt

4. Filter for R0 values with dt below the threshold specified by dt_max and dI above the threshold specified by dInorm_min

5. Fit a 1-D smoothing cubic spline for voltage as a function of SOC, placing knots at soc_points.

6. Evaluate the spline at SOC points requested by the user, return as a Resistance object using the interpolation_style type of spline.

Parameters:

• soc_points – SOC points at which to extract R0 or (int) number of

• points. (grid)

check_data(data: CellDataset)

Verify whether data contains features needed for algorithm

Parameters:

data – Data to be evaluated

Raises:

(ValueError) If the dataset is missing critical information –

dInorm_min: float

Min normalized current change for valid R0

dt_max: float

Max timestep for valid R0 instance

extract(dataset: CellDataset) → Resistance

Extract an estimate for the R0 of a cell

Parameters:

dataset – Dataset containing time series measurements.

Returns:

An R0 instance with the requested SOC interpolation points,

interpolate_r0(cycle: DataFrame) → ndarray

Fit then evaluate a smoothing spline which explains R0 as a function of SOC

Parameters:

cycle – Cycle to use for fitting the spline

Returns:

An estimate for the R0 at soc_points

soc_points: ndarray

State of charge points at which to estimate the resistance

soc_requirement: float

Require that dataset samples at least this fraction of the capacity

class moirae.extractors.ecm.RCExtractor(capacity: float | MaxTheoreticalCapacity, soc_points: ndarray | int = 11, soc_requirement: float = 0.95, n_rc: int = 1, min_rest: float = 600, max_rest_I: float | None = None)

Bases: BaseExtractor

Estimate the values of a parallel resistor-capacitor couples (RC) for an ECM of a battery as a function of state of charge (SOC)

Required data: RC extraction requires rest periods of at least min_rest seconds across a reasonable SOC range.

Algorithm:

1. Locate rest periods of at least min_rest seconds

2. Assign an SOC to each measurement based on capacity

3. Fit n_rc exponential models to the IV(t) data

4. The scale and power parameters are converted to the RC parameters

5. Fit a 1-D smoothing cubic spline for voltage as a function of SOC, placing knots at soc_points.

6. Evaluate the spline at SOC points requested by the user, return as a Resistance object using the interpolation_style type of spline.

Parameters:

• capacity (of the) – Best estimate for capacity of the cell (Amp-hours)

• soc_points – SOC points at which to extract R0 or (int) number of

• points. (grid)

• soc_requirement – Require that dataset samples at least this fraction

• capacity

• n_rc – Number of RC couples in the ECM

• min_rest – Minimum required rest duration in seconds

• max_rest_I – Maximum current expected during a rest period (Amps)

capacity: float

Best estimate for capacity of the cell

check_data(data: CellDataset)

Verify whether data contains features needed for algorithm

Parameters:

data – Data to be evaluated

Raises:

(ValueError) If the dataset is missing critical information –

extract(dataset: CellDataset) → Tuple[RCComponent, ...]

Extract an estimate for the RC elements of a cell

Parameters:

dataset – Dataset containing time series measurements.

Returns:

An tuple of RC instances with the requested SOC interpolation points

interpolate_rc(data: CellDataset) → ndarray

Fit then evaluate a smoothing spline which explains RC values as a function of SOC

Parameters:

cycle – Cycle to use for fitting the spline

Returns:

An estimate for all RC parameters at soc_points

max_rest_I: float

Maximum current expected during a rest period (Amps)

min_rest: float

Minimum required rest duration in seconds

n_rc: int

Number of RC couples in the ECM

soc_points: ndarray

State of charge points at which to estimate the resistance

soc_requirement: float

Require that dataset samples at least this fraction of the capacity