PyDPEET 0.2.0__py3-none-any.whl

pydpeet/process/analyze/configs/ocv_config.py

@@ -0,0 +1,177 @@
+from pydpeet.process.sequence.configs.config import NEWARE_CT_4008Q_5V12A_S1
+from pydpeet.process.sequence.utils.preprocessing.calculate_thresholds import calculate_minimum_definitive_differences
+
+THRESHOLD_DICT_Custom = [  # ARBIN_OLD
+    0.0005,  # ACCURACY_VOLTAGE_SIGNAL
+    0.01,  # ACCURACY_CURRENT_SIGNAL
+    0.0005,  # ACCURACY_VOLTAGE_MEASUREMENT
+    0.01,  # ACCURACY_CURRENT_MEASUREMENT
+    5,  # FS_VOLTAGE
+    3,  # FS_CURRENT
+]
+# use THRESHOLD_DICT = THRESHOLD_DICT_Custom if you don't want to use a predefined dictionary
+THRESHOLD_DICT = NEWARE_CT_4008Q_5V12A_S1  # .threshold_dict_neware
+MIN_DEFINITIVE_VOLTAGE_DIFFERENCE, MIN_DEFINITIVE_CURRENT_DIFFERENCE = calculate_minimum_definitive_differences(
+    *THRESHOLD_DICT
+)
+
+####### depending on the Noise needs to be adjusted even for measurements of the same device #######
+SEGMENTS_TO_DETECT_CONFIG = [
+    # devide threshold by 2 because it's looking above and below the target line
+    ("Voltage[V]", MIN_DEFINITIVE_VOLTAGE_DIFFERENCE / 2),
+    ("Current[A]", MIN_DEFINITIVE_CURRENT_DIFFERENCE / 2),
+    ("Power[W]", (MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE) / 2),
+]
+####### depending on the Noise needs to be adjusted even for measurements of the same device #######
+# ORDER IS IMPORTANT!
+ADJUST_SEGMENTS_CONFIG = [
+    ("Voltage[V]", MIN_DEFINITIVE_VOLTAGE_DIFFERENCE),
+    ("Current[A]", MIN_DEFINITIVE_CURRENT_DIFFERENCE),
+    ("Power[W]", (MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE)),
+]
+
+####### HAS TO USE SAME KEY AS DATA_COLUMNS! only change the values of thresholds! ########
+THRESHOLDS_PRIMITIVE_ANNOTATION = {
+    "V": MIN_DEFINITIVE_VOLTAGE_DIFFERENCE,
+    "I": MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+    "P": MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+}
+
+########################################################################################################################
+SHOW_RUNTIME = True
+SHOW_RUNTIME_ANNOTATION = True
+SHOW_RUNTIME_ANALYZE = True
+SHOW_RUNTIME_VISUALIZATION = True
+THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK = 2
+THRESHOLD_CONSOLE_PRINTS_CV_CHECK = 2
+########################################################################################################################
+# Visualize Data
+VISUALIZE_PHASES_CONFIG = [
+    ("V", "blue"),
+    ("I", "red"),
+    ("P", "green"),
+]
+LINE_VISUALIZATION_CONFIG = [
+    ("Voltage[V]", "blue", (2.4, 4.3)),
+    ("Current[A]", "red", (-10, 10)),
+    # ("Power[W]", "green", (-40, 20)),
+]
+# Bilder Bachelorarbeit Text
+# ("Voltage[V]", "blue", (2.4, 4.3)),
+# ("Current[A]", "red", (-10, 10)),
+START = 0  # 55000.0
+END = 1e10  # 90000
+USE_LINES_FOR_SEGMENTS = True
+SHOW_COLUMN_NAMES = False
+SHOW_TIME = False
+SHOW_ID = False
+SEGMENT_ALPHA = 0.3
+WIDTH_HEIGHT_RATIO = [1.0, 0.3]
+########################################################################################################################
+# Generate Instructions
+END_CONDITION_MAP_GENERATE_INSTRUCTIONS = {
+    "CC": "voltage",
+    "CV": "current",
+    "CP": "voltage",
+    "Pause": "time",
+}
+########################################################################################################################
+SEQUENCES_CONFIG: dict[str, dict] = {
+    # Complex Sequences
+    # Loop rules: "loop": True, "exact_loops": 2, "min_loops": 2, "max_loops": 2, "minimum_IDs": 6
+    "Discharge_iOCV": {"loop": True, "sequence": ["Pause", "CC_Discharge"]},
+    "Charge_iOCV": {"loop": True, "sequence": ["Pause", "CC_Charge"]},
+    # "Discharge_iOCV": {"sequence": ["Discharge_iOCV_correction", "CC_Discharge","CV_Discharge"]},
+}
+
+SEGMENTS_CONFIG_STANDARD: dict[str, dict] = {
+    # Primitive segments
+    # Pause
+    # CC_Charge, CV_Charge, CP_Charge
+    # CC_Discharge, CV_Discharge, CP_Discharge
+    # Ramp_Current_Charge, Ramp_Voltage_Charge, Ramp_Power_Charge
+    # Ramp_Current_Discharge, Ramp_Voltage_Discharge, Ramp_Power_Discharge
+    "Pause": {
+        "rules": {
+            "type": "Rest",
+        }
+    },
+    "CC_Charge": {
+        "rules": {
+            "variable": "I",
+            "type": "Constant",
+            "direction": "Charge",
+        }
+    },
+    "CV_Charge": {
+        "rules": {
+            "variable": "V",
+            "type": "Constant",
+            "direction": "Charge",
+        }
+    },
+    "CC_Discharge": {
+        "rules": {
+            "variable": "I",
+            "type": "Constant",
+            "direction": "Discharge",
+        }
+    },
+    "CV_Discharge": {
+        "rules": {
+            "variable": "V",
+            "type": "Constant",
+            "direction": "Discharge",
+        }
+    },
+    "Ramp": {
+        "rules": {
+            "type": "Ramp",
+        }
+    },
+    "C_Charge": {
+        "rules": {
+            "variable": "I",
+            "direction": "Charge",
+        }
+    },
+    "C_Discharge": {
+        "rules": {
+            "variable": "I",
+            "direction": "Discharge",
+        }
+    },
+    "Discharge": {
+        "rules": {
+            "direction": "Charge",
+        }
+    },
+}
+
+
+SEGMENT_SEQUENCE_CONFIG = {
+    **SEQUENCES_CONFIG,
+    **SEGMENTS_CONFIG_STANDARD,
+}
+
+########################################################################################################################
+#### These shouldn't be changed when using ppb Dataframes ####
+DATA_COLUMNS = {
+    "V": "Voltage[V]",
+    "I": "Current[A]",
+    "P": "Power[W]",
+}
+STANDARD_COLUMNS = ["Test_Time[s]", "Voltage[V]", "Current[A]"]
+#### These shouldn't be changed when using ppb Dataframes ####
+
+STEP_ANALYZER_PRIMITIVES_CONFIG = {
+    "SEGMENTS_TO_DETECT_CONFIG": SEGMENTS_TO_DETECT_CONFIG,
+    "ADJUST_SEGMENTS_CONFIG": ADJUST_SEGMENTS_CONFIG,
+    "THRESHOLDS_PRIMITIVE_ANNOTATION": THRESHOLDS_PRIMITIVE_ANNOTATION,
+    "SHOW_RUNTIME": SHOW_RUNTIME,
+    "SHOW_RUNTIME_ANNOTATION": SHOW_RUNTIME_ANNOTATION,
+    "DATA_COLUMNS": DATA_COLUMNS,
+    "MIN_DEFINITIVE_CURRENT_DIFFERENCE": MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+    "THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK": THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK,
+    "THRESHOLD_CONSOLE_PRINTS_CV_CHECK": THRESHOLD_CONSOLE_PRINTS_CV_CHECK,
+}

pydpeet/process/analyze/configs/step_analyzer_config.py

@@ -0,0 +1,178 @@
+from pydpeet.process.sequence.configs import config
+from pydpeet.process.sequence.utils.preprocessing.calculate_thresholds import calculate_minimum_definitive_differences
+
+THRESHOLD_DICT_Custom = [  # ARBIN_OLD
+    0.0005,  # ACCURACY_VOLTAGE_SIGNAL
+    0.01,  # ACCURACY_CURRENT_SIGNAL
+    0.0005,  # ACCURACY_VOLTAGE_MEASUREMENT
+    0.01,  # ACCURACY_CURRENT_MEASUREMENT
+    5,  # FS_VOLTAGE
+    3,  # FS_CURRENT
+]
+# use THRESHOLD_DICT = THRESHOLD_DICT_Custom if you don't want to use a predefined dictionary
+THRESHOLD_DICT = config.NEWARE_CT_4008Q_5V12A_S1
+MIN_DEFINITIVE_VOLTAGE_DIFFERENCE, MIN_DEFINITIVE_CURRENT_DIFFERENCE = calculate_minimum_definitive_differences(
+    *THRESHOLD_DICT
+)
+
+####### depending on the Noise needs to be adjusted even for measurements of the same device #######
+SEGMENTS_TO_DETECT_CONFIG = [
+    # devide threshold by 2 because it's looking above and below the target line
+    ("Voltage[V]", MIN_DEFINITIVE_VOLTAGE_DIFFERENCE / 2),
+    ("Current[A]", MIN_DEFINITIVE_CURRENT_DIFFERENCE / 2),
+    ("Power[W]", (MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE) / 2),
+]
+####### depending on the Noise needs to be adjusted even for measurements of the same device #######
+# ORDER IS IMPORTANT!
+ADJUST_SEGMENTS_CONFIG = [
+    ("Voltage[V]", MIN_DEFINITIVE_VOLTAGE_DIFFERENCE),
+    ("Current[A]", MIN_DEFINITIVE_CURRENT_DIFFERENCE),
+    ("Power[W]", (MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE)),
+]
+
+####### HAS TO USE SAME KEY AS DATA_COLUMNS! only change the values of thresholds! ########
+THRESHOLDS_PRIMITIVE_ANNOTATION = {
+    "V": MIN_DEFINITIVE_VOLTAGE_DIFFERENCE,
+    "I": MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+    "P": MIN_DEFINITIVE_VOLTAGE_DIFFERENCE + MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+}
+
+########################################################################################################################
+SHOW_RUNTIME = True
+SHOW_RUNTIME_ANNOTATION = True
+SHOW_RUNTIME_ANALYZE = True
+SHOW_RUNTIME_VISUALIZATION = True
+THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK = 2
+THRESHOLD_CONSOLE_PRINTS_CV_CHECK = 2
+THRESHOLD_CONSOLE_PRINTS_FINETUNING_WIDTH = 2
+THRESHOLD_CONSOLE_PRINTS_POWER_ZERO_WATT_CHECK = 10
+########################################################################################################################
+# Visualize Data
+VISUALIZE_PHASES_CONFIG = [
+    ("V", "blue"),
+    ("I", "red"),
+    ("P", "green"),
+]
+LINE_VISUALIZATION_CONFIG = [
+    ("Voltage[V]", "blue", (2.4, 4.3)),
+    ("Current[A]", "red", (-10, 10)),
+    # ("Power[W]", "green", (-40, 20)),
+]
+# Bilder Bachelorarbeit Text
+# ("Voltage[V]", "blue", (2.4, 4.3)),
+# ("Current[A]", "red", (-10, 10)),
+START = 0  # 55000.0
+END = 1e100  # 90000
+USE_LINES_FOR_SEGMENTS = True
+SHOW_COLUMN_NAMES = False
+SHOW_TIME = False
+SHOW_ID = False
+SEGMENT_ALPHA = 0.3
+WIDTH_HEIGHT_RATIO = [0.6666, 0.3]
+########################################################################################################################
+# Generate Instructions
+END_CONDITION_MAP_GENERATE_INSTRUCTIONS = {
+    "CC": "voltage",
+    "CV": "current",
+    "CP": "voltage",
+    "Pause": "time",
+}
+########################################################################################################################
+SEQUENCES_CONFIG: dict[str, dict] = {
+    # Complex Sequences
+    # Loop rules: "loop": True, "exact_loops": 2, "min_loops": 2, "max_loops": 2, "minimum_IDs": 6
+    # "Discharge_iOCV": {"loop": True, "minimum_IDs": 4, "sequence": ["CC_Discharge","Pause"]},
+    # "Charge_iOCV": {"loop": True, "min_loops": 2, "sequence": ["Pause", "CC_Charge"]},
+    "CCCV_Charge": {"loop": False, "sequence": ["CC_Charge", "CV_Charge"]},
+    "CCCV_Discharge": {"loop": False, "sequence": ["CC_Discharge", "CV_Discharge"]},
+    "CC_Discharge_after_CC_Charge": {"loop": False, "sequence": ["CC_Charge", "CC_Discharge"]},
+    "CC_Discharge_after_CCCV_Charge": {"loop": False, "sequence": ["CCCV_Charge", "CC_Discharge"]},
+    "CC_Discharge_after_CV_Charge": {"loop": False, "sequence": ["CV_Charge", "CC_Discharge"]},
+    "CC_Discharge_after_CCCV_Charge_with_Pause": {"loop": False, "sequence": ["CCCV_Charge", "Pause", "CV_Discharge"]},
+    "CC_Discharge_after_CC_Charge_with_Pause": {"loop": False, "sequence": ["CC_Charge", "Pause", "CC_Discharge"]},
+    "CC_Discharge_after_CV_Charge_with_Pause": {"loop": False, "sequence": ["CV_Charge", "Pause", "CC_Discharge"]},
+}
+SEGMENTS_CONFIG_STANDARD: dict[str, dict] = {
+    # Primitive segments
+    # Pause
+    # CC_Charge, CV_Charge, CP_Charge
+    # CC_Discharge, CV_Discharge, CP_Discharge
+    # Ramp_Current_Charge, Ramp_Voltage_Charge, Ramp_Power_Charge
+    # Ramp_Current_Discharge, Ramp_Voltage_Discharge, Ramp_Power_Discharge
+    "Pause": {
+        "rules": {
+            "type": "Rest",
+        }
+    },
+    "CC_Charge": {
+        "rules": {
+            "variable": "I",
+            "type": "Constant",
+            "direction": "Charge",
+        }
+    },
+    "CV_Charge": {
+        "rules": {
+            "variable": "V",
+            "type": "Constant",
+            "direction": "Charge",
+        }
+    },
+    "CP_Charge": {
+        "rules": {
+            "variable": "P",
+            "type": "Constant",
+            "direction": "Charge",
+        }
+    },
+    "CC_Discharge": {
+        "rules": {
+            "variable": "I",
+            "type": "Constant",
+            "direction": "Discharge",
+        }
+    },
+    "CV_Discharge": {
+        "rules": {
+            "variable": "V",
+            "type": "Constant",
+            "direction": "Discharge",
+        }
+    },
+    "CP_Discharge": {
+        "rules": {
+            "variable": "P",
+            "type": "Constant",
+            "direction": "Discharge",
+        }
+    },
+}
+
+
+SEGMENT_SEQUENCE_CONFIG = {
+    **SEQUENCES_CONFIG,
+    **SEGMENTS_CONFIG_STANDARD,
+}
+########################################################################################################################
+#### These shouldn't be changed when using ppb Dataframes ####
+DATA_COLUMNS = {
+    "V": "Voltage[V]",
+    "I": "Current[A]",
+    "P": "Power[W]",
+}
+STANDARD_COLUMNS = ["Test_Time[s]", "Voltage[V]", "Current[A]"]
+#### These shouldn't be changed when using ppb Dataframes ####
+
+STEP_ANALYZER_PRIMITIVES_CONFIG = {
+    "SEGMENTS_TO_DETECT_CONFIG": SEGMENTS_TO_DETECT_CONFIG,
+    "ADJUST_SEGMENTS_CONFIG": ADJUST_SEGMENTS_CONFIG,
+    "THRESHOLDS_PRIMITIVE_ANNOTATION": THRESHOLDS_PRIMITIVE_ANNOTATION,
+    "SHOW_RUNTIME": SHOW_RUNTIME,
+    "SHOW_RUNTIME_ANNOTATION": SHOW_RUNTIME_ANNOTATION,
+    "DATA_COLUMNS": DATA_COLUMNS,
+    "MIN_DEFINITIVE_CURRENT_DIFFERENCE": MIN_DEFINITIVE_CURRENT_DIFFERENCE,
+    "THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK": THRESHOLD_CONSOLE_PRINTS_ZERO_LENGTH_CHECK,
+    "THRESHOLD_CONSOLE_PRINTS_CV_CHECK": THRESHOLD_CONSOLE_PRINTS_CV_CHECK,
+    "THRESHOLD_CONSOLE_PRINTS_FINETUNING_WIDTH": THRESHOLD_CONSOLE_PRINTS_FINETUNING_WIDTH,
+    "THRESHOLD_CONSOLE_PRINTS_POWER_ZERO_WATT_CHECK": THRESHOLD_CONSOLE_PRINTS_POWER_ZERO_WATT_CHECK,
+}

pydpeet/process/analyze/cycle.py

@@ -0,0 +1,63 @@
+import inspect
+import logging
+
+import numpy as np
+import pandas as pd
+
+from pydpeet.process.analyze.capacity import add_charge_throughput
+from pydpeet.process.analyze.configs.battery_config import BatteryConfig
+from pydpeet.process.analyze.utils import StepTimer
+
+
+def add_equivalent_full_cycles(
+    df: pd.DataFrame,
+    config: BatteryConfig = None,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Calculate equivalent full cycles from absolute charge throughput and capacity reference.
+
+    Equivalent full cycles are calculated as the absolute charge throughput divided by two times the capacity reference,
+    so that every full cycle is counted as one cycle.
+
+    Parameters:
+        df (pandas.DataFrame): Input DataFrame containing battery test data
+        config (BatteryConfig, optional): Configuration for the battery. Defaults to BATTERY_DEFAULT
+
+    Returns:
+        pandas.DataFrame: DataFrame with added 'EquivalentFullCycles' column
+    """
+    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}")
+
+    df_mod = df.copy()
+    logging.info(f"Starting Equivalent Full Cycles computation on dataframe of size {len(df_mod)}...")
+
+    c_ref = config.c_ref
+    if c_ref is None:
+        logging.info("c_ref is None, attempting to use first valid capacity value as reference")
+
+        first_valid_idx = df_mod["Capacity[Ah]"].first_valid_index()
+
+        if first_valid_idx is None:
+            logging.warning("No valid capacity values found — returning DataFrame with empty SOH column")
+            df_mod["SOH"] = np.nan  # or whatever column you intend to fill
+            return df_mod
+        else:
+            c_ref = df_mod.at[first_valid_idx, "Capacity[Ah]"]
+            logging.info(f"Using first valid capacity value ({c_ref:.4f} Ah) as reference")
+
+    if "AbsoluteChargeThroughput[Ah]" not in df_mod.columns:
+        logging.info(
+            "AbsoluteChargeThroughput[Ah] not found, adding AbsoluteChargeThroughput[Ah] column with add_charge_throughput function..."
+        )
+        with StepTimer(verbose) as st:
+            df_mod = add_charge_throughput(df_mod)
+            st.log("added charge throughput column to df")
+
+    with StepTimer(verbose) as st:
+        df_mod["EquivalentFullCycles"] = df_mod["AbsoluteChargeThroughput[Ah]"] / (c_ref * 2)
+        st.log("computed Equivalent Full Cycles")
+
+    return df_mod

pydpeet/process/analyze/efficiency.py

@@ -0,0 +1,182 @@
+import inspect
+import logging
+
+import numpy as np
+import pandas as pd
+
+from pydpeet.process.analyze.average import (
+    calculate_total_charge,
+    calculate_total_discharge,
+)
+from pydpeet.process.analyze.configs.battery_config import BatteryConfig
+from pydpeet.process.analyze.utils import StepTimer
+
+
+def add_efficiency_coulomb(
+    df: pd.DataFrame,
+    df_blocks_charge: pd.DataFrame,
+    df_blocks_discharge: pd.DataFrame,
+    config: BatteryConfig = None,
+    max_time_diff_in_secs: int = 300,
+    ignore_threshold_values: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Calculate the Coulomb Efficiency of a battery based on the given data.
+
+    The Coulomb efficiency is calculated as the total discharge divided by the total charge.
+    The time difference between a charge block and the subsequent discharge block is taken into account.
+    If a charge block does not have a corresponding discharge block within the given time difference,
+    it is ignored. Similarly, if a discharge block does not have a corresponding charge block within
+    the given time difference, it is ignored.
+
+    Parameters:
+        df (pandas.DataFrame): Input DataFrame containing battery test data
+        df_blocks_charge (list[pandas.DataFrame] or pandas.DataFrame): List of DataFrames containing charge blocks
+        df_blocks_discharge (list[pandas.DataFrame] or pandas.DataFrame): List of DataFrames containing discharge blocks
+        config (BatteryConfig, optional): Configuration object containing battery test parameters
+        max_time_diff_in_secs (int, optional): Maximum time difference in seconds between charge and discharge blocks
+        ignore_threshold_values (bool, optional): Whether to ignore voltage thresholds when computing Coulomb efficiency
+        verbose (bool, optional): If True, print debug messages
+
+    Returns:
+        pandas.DataFrame: DataFrame with added 'CoulombEfficiency' column
+    """
+    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}")
+
+    logging.info(f"Starting Coulomb Efficiency computation on dataframe of size {len(df)}...")
+
+    # Ensure blocks are lists
+    if isinstance(df_blocks_charge, pd.DataFrame):
+        df_blocks_charge = [df_blocks_charge]
+    if isinstance(df_blocks_discharge, pd.DataFrame):
+        df_blocks_discharge = [df_blocks_discharge]
+
+    # Determine which time column to use
+    if "Test_Time[s]" in df.columns:
+        time_col = "Test_Time[s]"
+        parse_time = False
+        tolerance_val = max_time_diff_in_secs  # already seconds
+    elif "Date_Time" in df.columns:
+        # TODO: Assumed stack level for now
+        logging.warning("Date_Time is used as time column, because there is no 'Test_Time[s]' given.", stacklevel=2)
+        time_col = "Date_Time"
+        parse_time = True
+        tolerance_val = pd.Timedelta(seconds=max_time_diff_in_secs)
+    else:
+        raise ValueError("No suitable time column found. Provide 'Date_Time' or 'Test_Time[s]'.")
+
+    max_voltage = config.max_voltage
+    min_voltage = config.min_voltage
+
+    # Voltage thresholds
+    max_v_adj_down = max_voltage * (1 - config.voltage_intervall)
+    max_v_adj_up = max_voltage * (1 + config.voltage_intervall)
+    min_v_adj_up = min_voltage * (1 + config.voltage_intervall)
+    min_v_adj_down = min_voltage * (1 - config.voltage_intervall)
+
+    df_mod = df.copy()
+    df_mod["CoulombEfficiency"] = np.nan  # numeric NaN
+
+    # Helper to summarize blocks safely
+    def summarize_blocks(blocks, total_col_name):
+        summary = []
+        for block in blocks:
+            if block.empty:
+                continue
+            block_max = block["Voltage[V]"].max()
+            block_min = block["Voltage[V]"].min()
+            if ignore_threshold_values or (
+                max_v_adj_down <= block_max <= max_v_adj_up and min_v_adj_down <= block_min <= min_v_adj_up
+            ):
+                start_time = pd.to_datetime(block[time_col].iloc[0]) if parse_time else block[time_col].iloc[0]
+                end_time = pd.to_datetime(block[time_col].iloc[-1]) if parse_time else block[time_col].iloc[-1]
+                with StepTimer(verbose) as timer:
+                    total = (
+                        calculate_total_charge(block)
+                        if total_col_name == "total_charge"
+                        else calculate_total_discharge(block)
+                    )
+                    timer.log(f"calculated {total_col_name} for one block")
+                summary.append(
+                    {
+                        "start_time": start_time,
+                        "end_time": end_time,
+                        total_col_name: total,
+                        "last_index": block.index[-1],
+                    }
+                )
+        if not summary:
+            return pd.DataFrame(columns=["start_time", "end_time", total_col_name, "last_index"])
+        return pd.DataFrame(summary).sort_values("start_time")
+
+    # Helper to find matching blocks
+    with StepTimer(verbose) as st:
+        charge_df = summarize_blocks(df_blocks_charge, "total_charge")
+        discharge_df = summarize_blocks(df_blocks_discharge, "total_discharge")
+        st.log("summarized all charge/discharge blocks")
+
+    if charge_df.empty or discharge_df.empty:
+        logging.info("No valid charge/discharge blocks found. Skipping Coulomb Efficiency computation.")
+        return df_mod
+
+    if parse_time:
+        # Ensure datetime dtype
+        charge_df["start_time"] = pd.to_datetime(charge_df["start_time"])
+        charge_df["end_time"] = pd.to_datetime(charge_df["end_time"])
+        discharge_df["start_time"] = pd.to_datetime(discharge_df["start_time"])
+        discharge_df["end_time"] = pd.to_datetime(discharge_df["end_time"])
+
+    # Sort before merge_asof
+    charge_df = charge_df.sort_values("start_time").reset_index(drop=True)
+    discharge_df = discharge_df.sort_values("start_time").reset_index(drop=True)
+
+    # Forward merge: discharge after charge
+    with StepTimer(verbose) as st:
+        paired_forward = pd.merge_asof(
+            charge_df,
+            discharge_df,
+            left_on="end_time",
+            right_on="start_time",
+            direction="forward",
+            tolerance=tolerance_val,
+        )
+        st.log("performed forward merge of charge/discharge blocks")
+
+    # Backward merge: discharge before charge
+    with StepTimer(verbose) as st:
+        paired_backward = pd.merge_asof(
+            charge_df,
+            discharge_df,
+            left_on="start_time",
+            right_on="end_time",
+            direction="backward",
+            tolerance=tolerance_val,
+        )
+        st.log("performed backward merge of charge/discharge blocks")
+
+    # Combine forward/backward and pick closest in absolute time
+    with StepTimer(verbose) as st:
+        combined = pd.concat([paired_forward, paired_backward], ignore_index=True, sort=False)
+        combined["time_diff"] = (
+            pd.to_datetime(combined["start_time_y"]) - pd.to_datetime(combined["end_time_x"])
+        ).abs()
+        combined = combined.dropna(subset=["total_discharge"])
+        combined = combined.sort_values("time_diff").drop_duplicates(subset=["start_time_x", "end_time_x"])
+
+        # Assign Coulomb Efficiency to last index of the later block
+        for _, row in combined.iterrows():
+            total_charge = row.get("total_charge", np.nan)
+            total_discharge = row.get("total_discharge", np.nan)
+            if pd.isna(total_charge) or total_charge == 0:
+                ce = np.nan
+            else:
+                ce = total_discharge / total_charge
+            # Use nan-safe max and cast to int to avoid type checker complaints about comparing Series
+            last_index = int(np.nanmax([row.get("last_index_x", np.nan), row.get("last_index_y", np.nan)]))
+            df_mod.loc[last_index, "CoulombEfficiency"] = ce
+        st.log("assigned Coulomb Efficiency to dataframe")
+
+    return df_mod

pydpeet/process/analyze/energy.py

@@ -0,0 +1,51 @@
+import inspect
+import logging
+
+import pandas as pd
+from scipy import integrate
+
+from pydpeet.process.analyze.configs.battery_config import BatteryConfig
+from pydpeet.process.analyze.power import add_power
+from pydpeet.process.analyze.utils import (
+    StepTimer,
+    _check_columns,
+)
+
+
+def add_cumulative_energy(
+    df: pd.DataFrame,
+    config: BatteryConfig = None,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """
+    Calculates cumulative energy [Wh] from 'Test_Time[s]' and 'Power[W]' columns and adds it as a new column.
+
+    Parameters:
+    - df (pandas.DataFrame): DataFrame containing 'Test_Time[s]' and 'Power[W]' columns
+    - cumu_energy_method (CumulativeEnergyMethod): Method to use for cumulative energy calculation
+    - config (BatteryConfig): Config object containing max and min voltage values
+
+    Returns:
+    - pandas.DataFrame: DataFrame with added 'CumulativeEnergy[Wh]' column
+    """
+    logging.info("Calculating CumulativeEnergy[Wh]...")
+
+    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}")
+
+    df_mod = df.copy()
+    if "Power[W]" not in df_mod.columns:
+        logging.info("Power[W] column missing → adding via add_power.")
+        with StepTimer(verbose) as st:
+            df_mod = add_power(df_mod)
+            st.log("added Power[W] column")
+
+    with StepTimer(verbose) as st:
+        _check_columns(df_mod, ["Test_Time[s]", "Power[W]"])
+        df_mod["CumulativeEnergy[Wh]"] = (
+            integrate.cumulative_trapezoid(df_mod["Power[W]"], x=df_mod["Test_Time[s]"], initial=0) / 3600
+        )
+        st.log("calculated CumulativeEnergy[Wh]")
+
+    return df_mod

pydpeet/process/analyze/extract/__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__ = []