shepherd-core 2025.6.4__py3-none-any.whl → 2025.10.1__py3-none-any.whl

shepherd_core/vsource/virtual_source_simulation.py

@@ -14,7 +14,7 @@ import numpy as np
 from tqdm import tqdm
 
 from shepherd_core.data_models.base.calibration import CalibrationEmulator
-from shepherd_core.data_models.content.virtual_source import VirtualSourceConfig
+from shepherd_core.data_models.content.virtual_source_config import VirtualSourceConfig
 from shepherd_core.logger import log
 from shepherd_core.reader import Reader
 from shepherd_core.writer import Writer
@@ -35,81 +35,79 @@ def simulate_source(
 
     FN returns the consumed energy of the target.
     """
-    stack = ExitStack()
-    file_inp = Reader(path_input, verbose=False)
-    stack.enter_context(file_inp)
-    cal_emu = CalibrationEmulator()
-    cal_inp = file_inp.get_calibration_data()
-
-    if path_output:
-        file_out = Writer(
-            path_output, cal_data=cal_emu, mode="emulator", verbose=False, force_overwrite=True
+    with ExitStack() as stack:
+        file_inp = Reader(path_input, verbose=False)
+        stack.enter_context(file_inp)
+        cal_emu = CalibrationEmulator()
+        cal_inp = file_inp.get_calibration_data()
+
+        if path_output:
+            file_out = Writer(
+                path_output, cal_data=cal_emu, mode="emulator", verbose=False, force_overwrite=True
+            )
+            stack.enter_context(file_out)
+            file_out.store_hostname("emu_sim_" + config.name)
+            file_out.store_config(config.model_dump())
+            cal_out = file_out.get_calibration_data()
+
+        src = VirtualSourceModel(
+            config,
+            cal_emu,
+            dtype_in=file_inp.get_datatype(),
+            log_intermediate=False,
+            window_size=file_inp.get_window_samples(),
+            voltage_step_V=file_inp.get_voltage_step(),
         )
-        stack.enter_context(file_out)
-        file_out.store_hostname("emu_sim_" + config.name)
-        file_out.store_config(config.model_dump())
-        cal_out = file_out.get_calibration_data()
-
-    src = VirtualSourceModel(
-        config,
-        cal_emu,
-        dtype_in=file_inp.get_datatype(),
-        log_intermediate=False,
-        window_size=file_inp.get_window_samples(),
-        voltage_step_V=file_inp.get_voltage_step(),
-    )
-    i_out_nA = 0
-    e_out_Ws = 0.0
-    if monitor_internals and path_output:
-        stats_sample = 0
-        stats_internal = np.empty((round(file_inp.runtime_s * file_inp.samplerate_sps), 11))
-        try:
-            # keep dependencies low
-            from matplotlib import pyplot as plt
-        except ImportError:
-            log.warning("Matplotlib not installed, plotting of internals disabled")
+        i_out_nA = 0
+        e_out_Ws = 0.0
+        if monitor_internals and path_output:
+            stats_sample = 0
+            stats_internal = np.empty((round(file_inp.runtime_s * file_inp.samplerate_sps), 11))
+            try:
+                # keep dependencies low
+                from matplotlib import pyplot as plt  # noqa: PLC0415
+            except ImportError:
+                log.warning("Matplotlib not installed, plotting of internals disabled")
+                stats_internal = None
+        else:
             stats_internal = None
-    else:
-        stats_internal = None
-
-    for _t, v_inp, i_inp in tqdm(
-        file_inp.read(is_raw=True), total=file_inp.chunks_n, desc="Chunk", leave=False
-    ):
-        v_uV = 1e6 * cal_inp.voltage.raw_to_si(v_inp)
-        i_nA = 1e9 * cal_inp.current.raw_to_si(i_inp)
-
-        for _n in range(len(_t)):
-            v_uV[_n] = src.iterate_sampling(
-                V_inp_uV=int(v_uV[_n]),
-                I_inp_nA=int(i_nA[_n]),
-                I_out_nA=i_out_nA,
-            )
-            i_out_nA = target.step(int(v_uV[_n]), pwr_good=src.cnv.get_power_good())
-            i_nA[_n] = i_out_nA
-
-            if stats_internal is not None:
-                stats_internal[stats_sample] = [
-                    _t[_n] * 1e-9,  # s
-                    src.hrv.voltage_hold * 1e-6,
-                    src.cnv.V_input_request_uV * 1e-6,  # V
-                    src.hrv.voltage_set_uV * 1e-6,
-                    src.cnv.V_mid_uV * 1e-6,
-                    src.hrv.current_hold * 1e-6,  # mA
-                    src.hrv.current_delta * 1e-6,
-                    i_out_nA * 1e-6,
-                    src.cnv.P_inp_fW * 1e-12,  # mW
-                    src.cnv.P_out_fW * 1e-12,
-                    src.cnv.get_power_good(),
-                ]
-                stats_sample += 1
-
-        e_out_Ws += (v_uV * i_nA).sum() * 1e-15 * file_inp.sample_interval_s
-        if path_output:
-            v_out = cal_out.voltage.si_to_raw(1e-6 * v_uV)
-            i_out = cal_out.current.si_to_raw(1e-9 * i_nA)
-            file_out.append_iv_data_raw(_t, v_out, i_out)
 
-    stack.close()
+        for _t, v_inp, i_inp in tqdm(
+            file_inp.read(is_raw=True), total=file_inp.chunks_n, desc="Chunk", leave=False
+        ):
+            v_uV = 1e6 * cal_inp.voltage.raw_to_si(v_inp)
+            i_nA = 1e9 * cal_inp.current.raw_to_si(i_inp)
+
+            for _n in range(len(_t)):
+                v_uV[_n] = src.iterate_sampling(
+                    V_inp_uV=int(v_uV[_n]),
+                    I_inp_nA=int(i_nA[_n]),
+                    I_out_nA=i_out_nA,
+                )
+                i_out_nA = target.step(int(v_uV[_n]), pwr_good=src.cnv.get_power_good())
+                i_nA[_n] = i_out_nA
+
+                if stats_internal is not None:
+                    stats_internal[stats_sample] = [
+                        _t[_n] * 1e-9,  # s
+                        src.hrv.voltage_hold * 1e-6,
+                        src.cnv.V_input_request_uV * 1e-6,  # V
+                        src.hrv.voltage_set_uV * 1e-6,
+                        src.cnv.V_mid_uV * 1e-6,
+                        src.hrv.current_hold * 1e-6,  # mA
+                        src.hrv.current_delta * 1e-6,
+                        i_out_nA * 1e-6,
+                        src.cnv.P_inp_fW * 1e-12,  # mW
+                        src.cnv.P_out_fW * 1e-12,
+                        src.cnv.get_power_good(),
+                    ]
+                    stats_sample += 1
+
+            e_out_Ws += (v_uV * i_nA).sum() * 1e-15 * file_inp.sample_interval_s
+            if path_output:
+                v_out = cal_out.voltage.si_to_raw(1e-6 * v_uV)
+                i_out = cal_out.current.si_to_raw(1e-9 * i_nA)
+                file_out.append_iv_data_raw(_t, v_out, i_out)
 
     if stats_internal is not None:
         stats_internal = stats_internal[:stats_sample, :]

shepherd_core/vsource/virtual_storage_model.py

@@ -0,0 +1,164 @@
+"""this is ported py-version of the pru-code.
+
+Goals:
+
+- stay close to original code-base (fixed-point integer math)
+- offer a comparison for the tests
+- step 1 to a virtualization of emulation
+
+NOTE1: DO NOT OPTIMIZE -> stay close to original c-code-base
+
+Compromises:
+
+- Py has to map the settings-list to internal vars -> is kernel-task
+
+Expected deviations:
+
+- lead charge ramp maxes out early on cell-voltage (max of V_uV_n8 is 16.78 V)
+
+"""
+
+from pydantic import PositiveFloat
+from pydantic import validate_call
+
+from shepherd_core import log
+from shepherd_core.data_models.content.virtual_storage_config import LuT_SIZE
+from shepherd_core.data_models.content.virtual_storage_config import LuT_SIZE_LOG
+from shepherd_core.data_models.content.virtual_storage_config import StoragePRUConfig
+from shepherd_core.data_models.content.virtual_storage_config import TIMESTEP_s_DEFAULT
+from shepherd_core.data_models.content.virtual_storage_config import VirtualStorageConfig
+from shepherd_core.data_models.content.virtual_storage_config import soc_t
+
+
+class ModelStorage:
+    """Abstract base class for storage models."""
+
+    def step(self, I_charge_A: float) -> tuple[float, float, float, float]: ...
+
+
+def u32s(i: float) -> int:
+    """Guard to supervise calculated model-states."""
+    if i >= 2**32:
+        log.warning("u32-overflow")
+    if i < 0:
+        log.warning("u32-underflow")
+    return int(min(max(i, 0), 2**32 - 1))
+
+
+def u64s(i: float) -> int:
+    """Guard to supervise calculated model-states."""
+    if i >= 2**64:
+        log.warning("u64-overflow")
+    if i < 0:
+        log.warning("u64-underflow")
+    return int(min(max(i, 0), 2**64 - 1))
+
+
+class VirtualStorageModelPRU:
+    """Ported python version of the pru vStorage.
+
+    This model should behave like ModelKiBaMSimple
+    """
+
+    SoC_MAX_1_n62: int = 2**62 - 1
+    SoC_TO_POS_DIV: int = 2 ** (62 - LuT_SIZE_LOG)
+
+    @validate_call
+    def __init__(
+        self,
+        cfg: StoragePRUConfig,
+        SoC_init: soc_t | None = None,
+    ) -> None:
+        self.cfg_pru = cfg
+        # state
+        SoC_1_n30: float = 2**30 * SoC_init if SoC_init is not None else self.cfg_pru.SoC_init_1_n30
+        self.SoC_1_n62 = round(2**32 * SoC_1_n30)
+        self.V_OC_uV_n8 = self.cfg_pru.LuT_VOC_uV_n8[self.pos_LuT(self.SoC_1_n62)]
+
+    def pos_LuT(self, SoC_1_n62: int) -> int:
+        pos = u32s(SoC_1_n62 // self.SoC_TO_POS_DIV)
+        if pos >= LuT_SIZE:
+            pos = LuT_SIZE - 1
+        return pos
+
+    def calc_V_OC_uV(self) -> int:
+        pos_LuT = self.pos_LuT(self.SoC_1_n62)
+        return round(self.cfg_pru.LuT_VOC_uV_n8[pos_LuT] // 2**8)
+
+    def step(self, I_delta_nA_n4: float, *, is_charging: bool) -> float:
+        """Calculate the battery SoC & cell-voltage after drawing a current over a time-step.
+
+        Note: 3x u64 multiplications
+        """
+        dSoC_leak_1_n62 = u64s((self.V_OC_uV_n8 // 2**6) * self.cfg_pru.Constant_1_per_uV_n60)
+        if self.SoC_1_n62 >= dSoC_leak_1_n62:
+            self.SoC_1_n62 = u64s(self.SoC_1_n62 - dSoC_leak_1_n62)
+        else:
+            self.SoC_1_n62 = 0
+
+        dSoC_1_n62 = u64s(I_delta_nA_n4 * self.cfg_pru.Constant_1_per_nA_n60 // (2**2))
+        if is_charging:
+            self.SoC_1_n62 = u64s(self.SoC_1_n62 + dSoC_1_n62)
+            self.SoC_1_n62 = min(self.SoC_MAX_1_n62, self.SoC_1_n62)
+        elif self.SoC_1_n62 > dSoC_1_n62:
+            self.SoC_1_n62 = u64s(self.SoC_1_n62 - dSoC_1_n62)
+        else:
+            self.SoC_1_n62 = 0
+
+        pos_LuT = self.pos_LuT(self.SoC_1_n62)
+        self.V_OC_uV_n8 = self.cfg_pru.LuT_VOC_uV_n8[pos_LuT]
+        # TODO: is interpolation possible?
+        R_series_kOhm_n32 = self.cfg_pru.LuT_RSeries_kOhm_n32[pos_LuT]
+        V_delta_uV_n8 = u32s(u64s(I_delta_nA_n4 * R_series_kOhm_n32) // 2**28)
+
+        if is_charging:
+            V_cell_uV_n8 = u32s(self.V_OC_uV_n8 + V_delta_uV_n8)
+        elif self.V_OC_uV_n8 > V_delta_uV_n8:
+            V_cell_uV_n8 = u32s(self.V_OC_uV_n8 - V_delta_uV_n8)
+        else:
+            V_cell_uV_n8 = 0
+
+        if self.SoC_1_n62 == 0:
+            return 0  # cell voltage breaks down
+        return V_cell_uV_n8 // 2**8  # u32 uV
+
+
+class VirtualStorageModel(VirtualStorageModelPRU, ModelStorage):
+    """Higher level Model that can run on a coarser timebase.
+
+    This model should behave like ModelKiBaMSimple
+    """
+
+    @validate_call
+    def __init__(
+        self,
+        cfg: VirtualStorageConfig,
+        SoC_init: soc_t | None = None,
+        dt_s: PositiveFloat = TIMESTEP_s_DEFAULT,
+        *,
+        optimize_clamp: bool = True,
+    ) -> None:
+        # metadata for simulator
+        self.cfg: VirtualStorageConfig = cfg
+        self.dt_s = dt_s
+        # prepare PRU-Model
+        cfg_pru = StoragePRUConfig.from_vstorage(
+            cfg, TIMESTEP_s_DEFAULT, optimize_clamp=optimize_clamp
+        )
+        super().__init__(cfg_pru, SoC_init=SoC_init)
+
+        # just for simulation
+        self.steps_per_frame = round(dt_s / TIMESTEP_s_DEFAULT)
+
+    def step(self, I_charge_A: float) -> tuple[float, float, float, float]:
+        """Slower outer step with step-size of simulation."""
+        I_delta_nA_n4 = abs(2**4 * (1e9 * I_charge_A))
+        is_charging = I_charge_A >= 0
+        for _ in range(self.steps_per_frame - 1):
+            super().step(I_delta_nA_n4, is_charging=is_charging)
+        V_cell_uV = super().step(I_delta_nA_n4, is_charging=is_charging)
+        # code below just for simulation
+        V_OC = (1e-6 / 2**8) * self.V_OC_uV_n8
+        V_cell = 1e-6 * V_cell_uV
+        SoC = (1.0 / 2**62) * self.SoC_1_n62
+        return V_OC, V_cell, SoC, SoC

shepherd_core/vsource/virtual_storage_model_fixed_point_math.py

@@ -0,0 +1,58 @@
+"""Playground to determine the best integer-math and fit for constants."""
+
+from itertools import product
+
+from shepherd_core import log
+from shepherd_core.data_models.content.virtual_storage_config import LuT_SIZE_LOG
+
+
+def u32l(i: float) -> int:
+    """Guard to supervise calculated model-states."""
+    if i >= 2**32:
+        log.warning("u32-overflow (%d)", i)
+    if i < 0:
+        log.warning("u32-underflow (%d)", i)
+    return round(min(max(i, 0), 2**32 - 1))
+
+
+# #### I_charge-to-dSoC #####
+# Goal: Allow ~1 uF Capacitor to 800 mAh battery
+
+dt_s = 10e-6
+qs_As = [1e-6 * 1 * 2.0, 1e-6 * 5 * 2.5, 1e-6 * 10 * 3.6, 800 * 3.6]
+Constant_1u_per_nA_n40 = [u32l((2**40 / 1e3) * dt_s / q_As) for q_As in qs_As]
+Constant_1_per_nA_n60 = [u32l((2**60 / 1e9) * dt_s / q_As) for q_As in qs_As]
+
+# #### SoC-to-position #####
+# Goal: As-simple-as-possible
+
+SoCs_1u_n32 = [round(x / 10 * 1e6 * 2**32) for x in range(11)]
+LUT_SIZE = 128
+
+# First Approach (1 Division in pos-calc -> impossible for PRU)
+SoC_min_1u = round(1e6 / LUT_SIZE)
+positions1 = [int(SoC_1u_n32 / SoC_min_1u / 2**32) for SoC_1u_n32 in SoCs_1u_n32]
+
+# Second Approach
+SoC_min = 1.0 / LUT_SIZE
+inv_SoC_min_1M_n32 = round(2**32 / 1e6 / SoC_min)  # 1M / SoC_min
+positions2 = [
+    int(int(SoC_1u_n32 / 2**32) * inv_SoC_min_1M_n32 / 2**32) for SoC_1u_n32 in SoCs_1u_n32
+]
+
+# third approach
+SoCs_1_n62 = [round(x / 10 * 2**62) for x in range(11)]
+positions3 = [int(int(SoC_1_n62 / 2**32) * LUT_SIZE / 2**30) for SoC_1_n62 in SoCs_1_n62]
+
+# final approach (upper u32 & rest of shift)
+positions4 = [u32l(SoC_1_n62 // 2 ** (62 - LuT_SIZE_LOG)) for SoC_1_n62 in SoCs_1_n62]
+
+# #### R_Leak-to-dSoC #####
+# Goal: biggest possible dynamic range
+
+Rs_leak_Ohm = [1e3, 10e3, 100e3, 1e6, 10e6]
+Constants_1_per_V = [dt_s / q_As / R_leak_Ohm for q_As, R_leak_Ohm in product(qs_As, Rs_leak_Ohm)]
+Constants_1u_per_uV_n40 = [u32l((2**40) * c_1_per_V) for c_1_per_V in Constants_1_per_V]
+Constants_1_per_uV_n60 = [u32l((2**60 / 1e6) * c_1_per_V) for c_1_per_V in Constants_1_per_V]
+
+print("done")  # noqa: T201