PyDPEET 0.2.0__py3-none-any.whl

pydpeet/process/analyze/average.py

@@ -0,0 +1,297 @@
+import logging
+
+import numpy as np
+import pandas as pd
+
+from pydpeet.process.analyze.capacity import add_charge_throughput
+from pydpeet.process.analyze.utils import (
+    StepTimer,
+    _check_columns,
+)
+
+
+def calculate_average_temperature(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    if "Temperature[°C]" not in df.columns:
+        raise ValueError("Temperature[°C] column not found in DataFrame.")
+
+    average_temperature = df["Temperature[°C]"].mean()
+
+    return average_temperature
+
+
+def calculate_average_voltage(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    if "Voltage[V]" not in df.columns:
+        raise ValueError("Voltage[V] column not found in DataFrame.")
+
+    average_voltage = df["Voltage[V]"].mean()
+
+    return average_voltage
+
+
+def calculate_average_loading_voltage(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    if "Voltage[V]" not in df.columns:
+        raise ValueError("Voltage[V] column not found in DataFrame.")
+
+    positive_charges = df[df["Voltage[V]"].diff() > 0]["Voltage[V]"]
+    average_charge = positive_charges.mean()
+
+    return average_charge
+
+
+def calculate_average_charge(df: pd.DataFrame) -> float:
+    """
+    Calculate the average charge current [A] over all charging phases (Current > 0) efficiently.
+    """
+    if "Current[A]" not in df.columns:
+        return np.nan
+
+    currents = df["Current[A]"].to_numpy()
+    positive = currents[currents > 0]
+
+    if positive.size == 0:
+        return np.nan
+
+    return positive.mean()
+
+
+def calculate_average_discharge(df: pd.DataFrame) -> float:
+    """
+    Calculate the average discharge current [A] over all discharging phases (Current < 0) efficiently.
+    """
+    if "Current[A]" not in df.columns:
+        return np.nan
+
+    currents = df["Current[A]"].to_numpy()
+    negative = currents[currents < 0]
+
+    if negative.size == 0:
+        return np.nan
+
+    return negative.mean()
+
+
+def calculate_soh_loss(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the total SOH loss for a dataset.
+    Returns a single scalar value:
+        soh_loss = 1 - min(valid SOH)
+    """
+    _check_columns(df, ["SOH"])
+
+    soh = df["SOH"].astype(float).dropna()
+
+    if soh.empty:
+        if verbose:
+            logging.warning("No valid SOH values found.")
+
+        return np.nan
+
+    with StepTimer(verbose) as st:
+        soh_loss = 1 - soh.min()
+        st.log("computed SOH loss")
+
+    return soh_loss
+
+
+def calculate_soh_loss_per_cycle(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the SOH loss per equivalent full cycle.
+    Returns a single scalar value:
+        soh_loss_per_cycle = (1 - min(SOH)) / max(EquivalentFullCycles)
+    """
+    _check_columns(df, ["SOH", "EquivalentFullCycles"])
+
+    soh_loss = calculate_soh_loss(df, verbose=False)
+    cycles = df["EquivalentFullCycles"].astype(float).dropna()
+
+    if cycles.empty:
+        if verbose:
+            logging.warning("No valid EquivalentFullCycles values found. returning np.nan")
+
+        return np.nan
+
+    max_cycles = cycles.max()
+    if max_cycles <= 0:
+        if verbose:
+            logging.warning("Max EquivalentFullCycles <= 0, cannot compute loss per cycle. returning np.nan")
+
+        return np.nan
+
+    with StepTimer(verbose) as st:
+        soh_loss_per_cycle = soh_loss / max_cycles
+        st.log("computed SOH loss per cycle")
+
+    return soh_loss_per_cycle
+
+
+def add_soh_loss_over_charging(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Calculate SOH loss per unit of charging current.
+
+    Parameters:
+        df (pd.DataFrame): Must contain 'SOH' and 'ChargingCurrent' columns.
+        verbose (bool): If True, prints intermediate steps.
+
+    Returns:
+        pd.DataFrame: Original df with a new column 'SohLossPerAh'.
+    """
+    df = df.sort_index().copy()
+    soh_indices = df.index[~df["SOH"].isna()]
+    df["SohLossPerAh"] = np.nan
+
+    for i in range(1, len(soh_indices)):
+        start_idx = soh_indices[i - 1]
+        end_idx = soh_indices[i]
+
+        soh_diff = df.at[end_idx, "SOH"] - df.at[start_idx, "SOH"]
+
+        # Slice the dataframe between two SOH measurements
+        df_slice = df.loc[start_idx:end_idx]
+
+        # Calculate average charging current (make sure function exists)
+        avg_current = calculate_average_positive_chargeThroughput(df_slice)
+
+        # Compute SOH loss per Ah
+        loss_per_current = soh_diff / avg_current if avg_current != 0 else np.nan
+        df.at[end_idx, "SohLossPerAh"] = loss_per_current
+
+        if verbose:
+            logging.info(
+                f"From index {start_idx} to {end_idx}: SOH diff = {soh_diff}, "
+                f"Avg current = {avg_current}, Loss/current = {loss_per_current}"
+            )
+
+    return df
+
+
+def calculate_total_charge(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the total charge (in Ah) from the ChargeThroughput column.
+
+    Parameters:
+    -----------
+    df : pandas.DataFrame
+        Input DataFrame containing 'ChargeThroughput[Ah]' column
+
+    Returns:
+    -------
+    float
+        Total charge (in Ah)
+    """
+    if "ChargeThroughput[Ah]" not in df.columns:
+        if verbose:
+            logging.info("ChargeThroughput column missing, computing via add_charge_throughput...")
+
+        df = add_charge_throughput(df, verbose=verbose)
+
+    delta_load = df["ChargeThroughput[Ah]"].diff().fillna(0)
+    total_charge = delta_load[delta_load > 0].sum()
+
+    if verbose:
+        logging.info(f"Total charge computed: {total_charge:.4f} Ah")
+
+    return total_charge
+
+
+def calculate_total_discharge(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the total discharge (in Ah) from the ChargeThroughput column.
+
+    Parameters:
+    df (pandas.DataFrame): Input DataFrame containing 'ChargeThroughput[Ah]' column
+
+    Returns:
+    float: Total discharge (in Ah)
+
+    Notes:
+    The total discharge is calculated as the sum of negative differences in the ChargeThroughput column.
+    """
+    if "ChargeThroughput[Ah]" not in df.columns:
+        logging.info("ChargeThroughput column missing, computing via add_charge_throughput...")
+        df = add_charge_throughput(df, verbose=verbose)
+
+    delta_load = df["ChargeThroughput[Ah]"].diff().fillna(0)
+    total_discharge = -delta_load[delta_load < 0].sum()
+
+    if verbose:
+        logging.info(f"Total discharge computed: {total_discharge:.4f} Ah")
+
+    return total_discharge
+
+
+def calculate_average_positive_chargeThroughput(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the average charge (in Ah) from the ChargeThroughput column.
+
+    Parameters:
+    df (pandas.DataFrame): Input DataFrame containing 'ChargeThroughput[Ah]' column
+    verbose (bool, optional): If True, print debug messages
+
+    Returns:
+    float: Average charge (in Ah)
+
+    Notes:
+    The average charge is calculated as the mean of only positive values in the ChargeThroughput column.
+    """
+    if "ChargeThroughput[Ah]" not in df.columns:
+        logging.info("ChargeThroughput column missing, computing via add_charge_throughput...")
+        df = add_charge_throughput(df, verbose=verbose)
+
+    positive_charges = df[df["ChargeThroughput[Ah]"] > 0]["ChargeThroughput[Ah]"]
+    average_charge = positive_charges.mean()
+
+    return average_charge
+
+
+def calculate_average_negative_charge_throughput(
+    df: pd.DataFrame,
+    verbose: bool = True,
+) -> float:
+    """
+    Calculate the average discharge (in Ah) from the ChargeThroughput column.
+
+    Parameters:
+    df (pandas.DataFrame): Input DataFrame containing 'ChargeThroughput[Ah]' column
+    verbose (bool, optional): If True, print debug messages
+
+    Returns:
+    float: Average discharge (in Ah)
+
+    Notes:
+    The average discharge is calculated as the mean of only negative values in the ChargeThroughput column.
+    """
+    if "ChargeThroughput[Ah]" not in df.columns:
+        logging.info("ChargeThroughput column missing, computing via add_charge_throughput...")
+        df = add_charge_throughput(df, verbose=verbose)
+
+    negative_charges = df[df["ChargeThroughput[Ah]"] < 0]["ChargeThroughput[Ah]"]
+    average_discharge = negative_charges.mean()
+
+    return average_discharge

pydpeet/process/analyze/capacity.py

@@ -0,0 +1,208 @@
+import inspect
+import logging
+
+import numpy as np
+import pandas as pd
+from scipy import integrate
+
+from pydpeet.process.analyze.configs.battery_config import BatteryConfig
+from pydpeet.process.analyze.configs.step_analyzer_config import SEGMENT_SEQUENCE_CONFIG
+from pydpeet.process.analyze.utils import (
+    StepTimer,
+    _check_columns,
+)
+from pydpeet.process.sequence.step_analyzer import extract_sequence_overview
+from pydpeet.process.sequence.utils.postprocessing.filter_df import filter_and_split_df_by_blocks
+
+
+def add_capacity(
+    df: pd.DataFrame,
+    df_primitives: pd.DataFrame,
+    neware_bool: bool = True,
+    config: BatteryConfig = None,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Compute the capacity of a battery cell from its discharge data.
+
+    The capacity computation is a multistep process. First, the discharge blocks
+    are filtered from the data. Then, the blocks with a full discharge (from max to min)
+    are searched. For each of these blocks, the cumulative capacity is computed by
+    integrating the absolute current over time.
+
+    The resulting DataFrame has an additional 'Capacity[Ah]' column.
+
+    Parameters:
+        df (pandas.DataFrame): Input DataFrame containing battery test data
+        config (BatteryConfig, optional): Configuration object containing battery test parameters
+        verbose (bool, optional): If True, print debug messages. Defaults to False.
+
+    Returns:
+        pandas.DataFrame: DataFrame with added 'Capacity[Ah]' column
+        :param THRESHOLD_DICT: threshold dictionary for neware params
+    """
+    # Check if the required columns are present
+    required_cols = ["Test_Time[s]", "Current[A]", "Voltage[V]"]
+    _check_columns(df, required_cols)
+
+    if config is None:
+        func_name = inspect.currentframe().f_code.co_name
+        raise ValueError(f"config is None, please provide a valid config for {func_name}!")
+
+    minimal_current = config.minimal_current_for_capacity
+    maximal_current = config.maximal_current_for_capacity
+
+    df_mod = df.copy()
+    max_voltage = config.max_voltage
+    min_voltage = config.min_voltage
+    voltage_intervall = config.voltage_intervall
+
+    logging.info(f"Starting capacity computation on dataframe of size {len(df_mod)}...")
+
+    # Step 2: Segments and sequences
+    with StepTimer(verbose) as st:
+        df_segments_and_sequences = extract_sequence_overview(
+            df_primitives, SEGMENT_SEQUENCE_CONFIG=SEGMENT_SEQUENCE_CONFIG
+        )
+        st.log("computed segments and sequences")
+
+    if neware_bool:
+        # Step 3: Filter discharge blocks
+        rules = [
+            "CC_Discharge_after_CC_Charge",
+            "CC_Discharge_after_CCCV_Charge",
+            "CC_Discharge_after_CV_Charge",
+            "CC_Discharge_after_CCCV_Charge_with_Pause",
+            "CC_Discharge_after_CC_Charge_with_Pause",
+            "CC_Discharge_after_CV_Charge_with_Pause",
+        ]
+        with StepTimer(verbose) as st:
+            dfs_per_block, df_filtered = filter_and_split_df_by_blocks(
+                df_segments_and_sequences=df_segments_and_sequences,
+                df_primitives=df_primitives,
+                rules=rules,
+                combine_op="or",
+                also_return_filtered_df=True,
+            )
+            st.log("filtered initial discharge blocks")
+
+    rules = ["CC_Discharge"]
+    with StepTimer(verbose) as st:
+        dfs_per_block, df_filtered = filter_and_split_df_by_blocks(
+            df_segments_and_sequences=df_segments_and_sequences,
+            df_primitives=df_primitives,
+            rules=rules,
+            combine_op="or",
+            also_return_filtered_df=True,
+        )
+        st.log("filtered CC_Discharge blocks")
+
+    discharge_dfs = []
+    # search for the blocks with a full discharge (from max to min)
+    for i, block in enumerate(dfs_per_block):
+        avg_current = block["Current[A]"].mean()
+        voltage_range = (block["Voltage[V]"].max(), block["Voltage[V]"].min())
+
+        if not (minimal_current < avg_current < maximal_current) or not (
+            voltage_range[0] >= max_voltage * (1 - voltage_intervall)
+            and voltage_range[1] <= min_voltage * (1 + voltage_intervall)
+        ):
+            continue
+
+        block = block.copy()
+        time_diff = block["Test_Time[s]"].diff() / 3600
+        block["Capacity[Ah]"] = (block["Current[A]"] * time_diff).cumsum()
+
+        if len(block) > 0:
+            time_seconds = block["Test_Time[s]"].values
+            current = block["Current[A]"].values
+            with StepTimer(verbose) as st:
+                capacity_ah = integrate.cumulative_trapezoid(abs(current), time_seconds, initial=0) / 3600
+                st.log(f"computed cumulative capacity for block {i}")
+            block["Capacity[Ah]"] = float("NaN")
+            block.loc[block.index[-1], "Capacity[Ah]"] = capacity_ah[-1]
+
+        discharge_dfs.append(block)
+
+    if len(discharge_dfs) > 0:
+        for block in discharge_dfs:
+            df_mod.loc[block.index[0] : block.index[-1], "Capacity[Ah]"] = block["Capacity[Ah]"]
+    else:
+        logging.info("No valid discharge blocks found, returning DataFrame with Capacity as nans")
+        df_mod["Capacity[Ah]"] = np.full(len(df_mod), np.nan, dtype=np.float64)
+
+    return df_mod
+
+
+def add_charge_throughput(
+    df: pd.DataFrame,
+    calculate_tests_individually: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Calculate charge throughput and absolute charge throughput from a given DataFrame.
+
+    Parameters:
+    df (pandas.DataFrame): Input DataFrame containing 'Test_Time[s]' and 'Current[A]' columns
+
+    Returns:
+    pandas.DataFrame: DataFrame with added 'ChargeThroughput[Ah]' and 'AbsoluteChargeThroughput[Ah]' columns
+
+    Notes:
+    The 'ChargeThroughput[Ah]' column represents the cumulative charge (in Ah) with sign (i.e., loaded + / unloaded -)
+    The 'AbsoluteChargeThroughput[Ah]' column represents the cumulative absolute charge (in Ah)
+    """
+    time_col = "Test_Time[s]"
+    current_col = "Current[A]"
+    testindex_col = "TestIndex"
+
+    # quick checks
+    if time_col not in df.columns or current_col not in df.columns:
+        raise KeyError(f"Missing required columns: {time_col}, {current_col}")
+
+    n = len(df)
+    if n == 0:
+        if verbose:
+            logging.info("Empty DataFrame, returning.")
+        return df.copy()
+
+    time = df[time_col].to_numpy(dtype=float)
+    current = df[current_col].to_numpy(dtype=float)
+
+    charge_throughput = np.full(n, np.nan, dtype=float)
+    abs_charge_throughput = np.full(n, np.nan, dtype=float)
+
+    def _process_slice(start_slice: int, end_slice: int):
+        slice_time = time[start_slice:end_slice]
+        slice_current = current[start_slice:end_slice]
+
+        mask = ~np.isnan(slice_time) & ~np.isnan(slice_current)
+        if np.sum(mask) <= 1:
+            return
+
+        charge = integrate.cumulative_trapezoid(slice_current[mask], slice_time[mask], initial=0) / 3600.0
+        abs_charge = integrate.cumulative_trapezoid(np.abs(slice_current[mask]), slice_time[mask], initial=0) / 3600.0
+
+        valid_indices = np.nonzero(mask)[0] + start_slice
+        charge_throughput[valid_indices] = charge
+        abs_charge_throughput[valid_indices] = abs_charge
+
+    with StepTimer(verbose) as st:
+        if calculate_tests_individually and (testindex_col in df.columns):
+            testvalues = df[testindex_col].to_numpy()
+            starts = np.nonzero(np.concatenate(([True], testvalues[1:] != testvalues[:-1])))[0]
+            starts = np.append(starts, n)
+            for i in range(len(starts) - 1):
+                start = int(starts[i])
+                end = int(starts[i + 1])
+                _process_slice(start, end)
+            st.log("Processed charge throughput per individual test blocks")
+        else:
+            _process_slice(0, n)
+            st.log("Processed charge throughput for whole DataFrame")
+
+    df_mod = df.copy()
+    df_mod["ChargeThroughput[Ah]"] = charge_throughput
+    df_mod["AbsoluteChargeThroughput[Ah]"] = abs_charge_throughput
+
+    return df_mod

pydpeet/process/analyze/configs/__init__.py

@@ -0,0 +1,7 @@
+"""
+Auto-generated __init__ file.
+Created: 2026-03-06 15:11:49
+"""
+
+# Restrictive package init: start with no public API
+__all__ = []

pydpeet/process/analyze/configs/battery_config.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class BatteryConfig:
+    cell_name: str = "Default"
+    c_ref: float = None
+    soc_start: float = 0
+    max_voltage: float = 4.2
+    min_voltage: float = 2.5
+    threshold_current: float = 0.075
+    voltage_intervall: float = 0.01
+    # ----- values for capacity calculation -----
+    minimal_current_for_capacity: float = -1.2
+    maximal_current_for_capacity: float = -0.8
+    # ----- values for internal resistance calculation -----
+    min_current_diff: float = 1
+    max_time_diff: float = 0.5
+    min_voltage_diff: float = 0
+    # ignores negative values in internal resistance calculation,
+    # should only appear in Neware Cells because of a bug
+    ignore_negative_resistance_values: bool = False
+
+
+battery_config_default = BatteryConfig()
+
+# Configs for different Cells
+lgm50lt_nmc_4800 = BatteryConfig(
+    c_ref=4.8,
+    max_voltage=4.2,
+    min_voltage=2.5,
+    min_current_diff=1,
+    max_time_diff=0.5,
+    min_voltage_diff=0,
+    ignore_negative_resistance_values=True,
+)
+
+hakadi_nmc_1500 = BatteryConfig(c_ref=1.5, max_voltage=3.6, min_voltage=2.0)