cellpycore 0.1.1__py3-none-any.whl

cellpycore/_helpers.py

@@ -0,0 +1,199 @@
+"""Helper functions only intended for development purposes  (e.g. for creating mock data)."""
+
+from typing import TypeVar
+
+DataFrame = TypeVar("DataFrame")
+
+
+def create_raw_data() -> DataFrame:
+    """Create mock raw battery testing data with realistic values.
+
+    TODO: This function was generated using AI and has not been checked for correctness!
+
+    Note that this function is called separately for each test that uses the mock_data_with_raw fixture.
+    If the test-suite is getting slow, consider caching the result of this function or using a different approach.
+    """
+    import polars as pl
+    from cellpycore.config import RawCols
+    from cellpycore.timestamps import NS_PER_SECOND
+
+    # Create a RawCols instance to get column names
+    raw_cols = RawCols()
+
+    # Generate realistic battery testing data
+    n_points = 1000  # Number of data points
+
+    # Create time series data
+    test_time = pl.Series(raw_cols.test_time, range(n_points), dtype=pl.Float64)
+    # epoch_time_utc is int64 nanoseconds since the Unix epoch, UTC (canonical
+    # absolute-timestamp dtype; see cellpycore.timestamps). Start at 2021-01-01 and
+    # advance one second per row.
+    start_epoch_s = 1609459200
+    epoch_time_utc = pl.Series(
+        raw_cols.epoch_time_utc,
+        [(start_epoch_s + i) * NS_PER_SECOND for i in range(n_points)],
+        dtype=pl.Int64,
+    )
+
+    # Generate cycle and step data
+    cycle_num = pl.Series(
+        raw_cols.cycle_num, [i // 100 for i in range(n_points)], dtype=pl.Int64
+    )
+    step_num = pl.Series(
+        raw_cols.step_num, [(i % 100) // 10 for i in range(n_points)], dtype=pl.Int64
+    )
+    datapoint_num = pl.Series(raw_cols.datapoint_num, range(n_points), dtype=pl.Int64)
+    source_datapoint_num = pl.Series(
+        raw_cols.source_datapoint_num, range(n_points), dtype=pl.Int64
+    )
+
+    # Generate step types (charge, discharge, rest)
+    step_types = []
+    for i in range(n_points):
+        step_idx = i % 10
+        if step_idx < 3:
+            step_types.append("charge")
+        elif step_idx < 6:
+            step_types.append("discharge")
+        else:
+            step_types.append("rest")
+
+    step_type = pl.Series(raw_cols.step_type, step_types, dtype=pl.Utf8)
+    step_type_detail = pl.Series(
+        raw_cols.step_type_detail, [f"{t}_cc" for t in step_types], dtype=pl.Utf8
+    )
+
+    # Generate current data (charge: positive, discharge: negative, rest: 0)
+    current = []
+    for i, st in enumerate(step_types):
+        if st == "charge":
+            current.append(1.0 + (i % 5) * 0.1)  # 1.0 to 1.4 A
+        elif st == "discharge":
+            current.append(-1.0 - (i % 5) * 0.1)  # -1.0 to -1.4 A
+        else:
+            current.append(0.0)
+
+    current = pl.Series(raw_cols.current, current, dtype=pl.Float64)
+
+    # Generate potential data (voltage)
+    potential = []
+    base_voltage = 3.7  # Typical Li-ion voltage
+    for i, st in enumerate(step_types):
+        if st == "charge":
+            # Voltage increases during charge
+            potential.append(base_voltage + (i % 100) * 0.01)
+        elif st == "discharge":
+            # Voltage decreases during discharge
+            potential.append(base_voltage - (i % 100) * 0.01)
+        else:
+            # Rest voltage
+            potential.append(base_voltage + (i % 10) * 0.001)
+
+    potential = pl.Series(raw_cols.potential, potential, dtype=pl.Float64)
+
+    # Generate cumulative capacities (cumulative per cycle, per direction).
+    cumulative_charge_capacity = []
+    cumulative_discharge_capacity = []
+    charge_cap = 0.0
+    discharge_cap = 0.0
+
+    for i, (curr, st) in enumerate(zip(current, step_types)):
+        if st == "charge":
+            charge_cap += abs(curr) * 0.1  # Assuming 0.1 hour time step
+        elif st == "discharge":
+            discharge_cap += abs(curr) * 0.1
+        cumulative_charge_capacity.append(charge_cap)
+        cumulative_discharge_capacity.append(discharge_cap)
+
+    cumulative_charge_capacity = pl.Series(
+        raw_cols.cumulative_charge_capacity,
+        cumulative_charge_capacity,
+        dtype=pl.Float64,
+    )
+    cumulative_discharge_capacity = pl.Series(
+        raw_cols.cumulative_discharge_capacity,
+        cumulative_discharge_capacity,
+        dtype=pl.Float64,
+    )
+
+    # Step time (seconds since the start of the current step) and instrument IR.
+    step_time = pl.Series(
+        raw_cols.step_time, [float(i % 10) for i in range(n_points)], dtype=pl.Float64
+    )
+    internal_resistance = pl.Series(
+        raw_cols.internal_resistance, [0.05] * n_points, dtype=pl.Float64
+    )
+
+    # Reference-electrode potential (3-electrode setup): the cell potential
+    # shifted by a small constant offset vs the reference electrode.
+    ref_potential = pl.Series(
+        raw_cols.ref_potential, [v - 0.2 for v in potential], dtype=pl.Float64
+    )
+
+    # Generate auxiliary temperature data
+    temperature_cell = pl.Series(
+        raw_cols.aux_temperature_cell,
+        [25.0 + (i % 20) * 0.5 for i in range(n_points)],
+        dtype=pl.Float64,
+    )
+    temperature_chamber = pl.Series(
+        raw_cols.aux_temperature_chamber,
+        [25.0 + (i % 10) * 0.2 for i in range(n_points)],
+        dtype=pl.Float64,
+    )
+
+    # Generate other metadata
+    source_type = pl.Series(raw_cols.source_type, ["maccor"] * n_points, dtype=pl.Utf8)
+    source_uuid = pl.Series(
+        raw_cols.source_uuid, [f"test_{i:06d}" for i in range(n_points)], dtype=pl.Utf8
+    )
+    step_mode = pl.Series(raw_cols.step_mode, ["CC"] * n_points, dtype=pl.Utf8)
+    pressure = pl.Series(
+        raw_cols.aux_pressure_cell,
+        [101325.0 + (i % 100) * 10 for i in range(n_points)],
+        dtype=pl.Float64,
+    )
+
+    # Create the DataFrame using the column names from RawCols
+    data = {
+        raw_cols.source_type: source_type,
+        raw_cols.source_uuid: source_uuid,
+        raw_cols.source_datapoint_num: source_datapoint_num,
+        raw_cols.datapoint_num: datapoint_num,
+        raw_cols.step_num: step_num,
+        raw_cols.cycle_num: cycle_num,
+        raw_cols.epoch_time_utc: epoch_time_utc,
+        raw_cols.test_time: test_time,
+        raw_cols.step_time: step_time,
+        raw_cols.step_mode: step_mode,
+        raw_cols.step_type: step_type,
+        raw_cols.step_type_detail: step_type_detail,
+        raw_cols.potential: potential,
+        raw_cols.current: current,
+        raw_cols.internal_resistance: internal_resistance,
+        raw_cols.ref_potential: ref_potential,
+        raw_cols.aux_temperature_cell: temperature_cell,
+        raw_cols.aux_temperature_chamber: temperature_chamber,
+        raw_cols.aux_pressure_cell: pressure,
+        raw_cols.cumulative_charge_capacity: cumulative_charge_capacity,
+        raw_cols.cumulative_discharge_capacity: cumulative_discharge_capacity,
+    }
+
+    return pl.DataFrame(data)
+
+
+if __name__ == "__main__":
+    import matplotlib.pyplot as plt
+    df = create_raw_data()
+    df_pandas = df.to_pandas()
+
+    fig, axs = plt.subplots(2, 2, figsize=(10, 10))
+    axs[0, 0].plot(df_pandas["test_time"], df_pandas["potential"])
+    axs[0, 0].set_title("Potential")
+    axs[0, 1].plot(df_pandas["test_time"], df_pandas["current"])
+    axs[0, 1].set_title("Current")
+    axs[1, 0].plot(df_pandas["test_time"], df_pandas["aux_temperature_cell"])
+    axs[1, 0].set_title("Temperature Cell")
+    axs[1, 1].plot(df_pandas["test_time"], df_pandas["aux_temperature_chamber"])
+    axs[1, 1].set_title("Temperature Chamber")
+    plt.show()