shepherd-core 2025.8.1__py3-none-any.whl → 2026.2.1__py3-none-any.whl

shepherd_core/vsource/virtual_harvester_model.py

@@ -16,7 +16,7 @@ Compromises:
 
 """
 
-from shepherd_core.data_models.content.virtual_harvester import HarvesterPRUConfig
+from shepherd_core.data_models.content.virtual_harvester_config import HarvesterPRUConfig
 from shepherd_core.logger import log
 
 
@@ -64,33 +64,34 @@ class VirtualHarvesterModel:
         self.voltage_step_x4_uV: int = 4 * self._cfg.voltage_step_uV
         self.age_max: int = 2 * self._cfg.window_size
 
+        self.voc_now: int = self._cfg.voltage_max_uV
+        self.voc_nxt: int = self._cfg.voltage_max_uV
+        self.voc_min: int = max(1000, self._cfg.voltage_min_uV)
+
+        self.lin_extrapolation: bool = bool(self._cfg.hrv_mode & (2**2))
+
         # INIT static vars: CV
         self.voltage_last: int = 0
         self.current_last: int = 0
-        self.compare_last: int = 0
-        self.lin_extrapolation: bool = bool(self._cfg.hrv_mode & (2**2))
-        self.current_delta: int = 0
         self.voltage_delta: int = 0
+        self.current_delta: int = 0
+        self.compare_last: int = 0
 
         # INIT static vars: VOC
         self.age_now: int = 0
-        self.voc_now: int = self._cfg.voltage_max_uV
         self.age_nxt: int = 0
-        self.voc_nxt: int = self._cfg.voltage_max_uV
-        self.voc_min: int = max(1000, self._cfg.voltage_min_uV)
 
         # INIT static vars: PO
-        # already done: interval step
         self.power_last: int = 0
 
         # INIT static vars: OPT
-        # already done: age_now, age_nxt
-        self.power_now: int = 0
+        # already done in VOC: age_now, age_nxt
         self.voltage_now: int = 0
         self.current_now: int = 0
-        self.power_nxt: int = 0
         self.voltage_nxt: int = 0
         self.current_nxt: int = 0
+        self.power_now: int = 0
+        self.power_nxt: int = 0
 
     def ivcurve_sample(self, _voltage_uV: int, _current_nA: int) -> tuple[int, int]:
         if self._cfg.window_size <= 1:
@@ -116,19 +117,25 @@ class VirtualHarvesterModel:
             if distance_now < distance_last and distance_now < self.voltage_step_x4_uV:
                 self.voltage_hold = _voltage_uV
                 self.current_hold = _current_nA
-                self.current_delta = _current_nA - self.current_last
                 self.voltage_delta = _voltage_uV - self.voltage_last
-                # TODO: voltage_delta is static
+                self.current_delta = _current_nA - self.current_last
             elif distance_last < distance_now and distance_last < self.voltage_step_x4_uV:
                 self.voltage_hold = self.voltage_last
                 self.current_hold = self.current_last
-                self.current_delta = _current_nA - self.current_last
                 self.voltage_delta = _voltage_uV - self.voltage_last
+                self.current_delta = _current_nA - self.current_last
         elif self.lin_extrapolation:
             # apply the proper delta if needed
+            # TODO: C-Code differs here slightly, but only to handle unsigned int
             if (self.voltage_hold < self.voltage_set_uV) == (self.voltage_delta > 0):
-                self.voltage_hold += self.voltage_delta
-                self.current_hold += self.current_delta
+                if self.voltage_hold > -self.voltage_delta:
+                    self.voltage_hold += self.voltage_delta
+                else:
+                    self.voltage_hold = 0
+                if self.current_hold > -self.current_delta:
+                    self.current_hold += self.current_delta
+                else:
+                    self.current_hold = 0
             else:
                 if self.voltage_hold > self.voltage_delta:
                     self.voltage_hold -= self.voltage_delta
@@ -145,7 +152,7 @@ class VirtualHarvesterModel:
         return self.voltage_hold, self.current_hold
 
     def ivcurve_2_mppt_voc(self, _voltage_uV: int, _current_nA: int) -> tuple[int, int]:
-        self.interval_step = self.interval_step + 1
+        self.interval_step += 1
         if self.interval_step >= self._cfg.interval_n:
             self.interval_step = 0
         self.age_nxt += 1
@@ -168,14 +175,15 @@ class VirtualHarvesterModel:
 
         _voltage_uV, _current_nA = self.ivcurve_2_cv(_voltage_uV, _current_nA)
         if self.interval_step < self._cfg.duration_n:
-            self.voltage_set_uV = self.voc_now
+            self.voltage_set_uV = self._cfg.voltage_max_uV
+            _current_nA = 0
         elif self.interval_step == self._cfg.duration_n:
             self.voltage_set_uV = int(self.voc_now * self._cfg.setpoint_n8 / 256)
-
+            _current_nA = 0
         return _voltage_uV, _current_nA
 
     def ivcurve_2_mppt_po(self, _voltage_uV: int, _current_nA: int) -> tuple[int, int]:
-        self.interval_step = self.interval_step + 1
+        self.interval_step += 1
         if self.interval_step >= self._cfg.interval_n:
             self.interval_step = 0
 
@@ -211,7 +219,7 @@ class VirtualHarvesterModel:
                 self.voltage_set_uV = self._cfg.voltage_min_uV
                 self.is_rising = True
                 self.volt_step_uV = self._cfg.voltage_step_uV
-            if self.voltage_set_uV <= self._cfg.voltage_step_uV:
+            if self.voltage_set_uV < self._cfg.voltage_step_uV:
                 self.voltage_set_uV = self._cfg.voltage_step_uV
                 self.is_rising = True
                 self.volt_step_uV = self._cfg.voltage_step_uV

shepherd_core/vsource/virtual_harvester_simulation.py

@@ -13,8 +13,8 @@ from pathlib import Path
 from tqdm import tqdm
 
 from shepherd_core.data_models.base.calibration import CalibrationHarvester
-from shepherd_core.data_models.content.virtual_harvester import HarvesterPRUConfig
-from shepherd_core.data_models.content.virtual_harvester import VirtualHarvesterConfig
+from shepherd_core.data_models.content.virtual_harvester_config import HarvesterPRUConfig
+from shepherd_core.data_models.content.virtual_harvester_config import VirtualHarvesterConfig
 from shepherd_core.reader import Reader
 from shepherd_core.writer import Writer
 
@@ -28,45 +28,44 @@ def simulate_harvester(
 
     Fn return the harvested energy.
     """
-    stack = ExitStack()
-    file_inp = Reader(path_input, verbose=False)
-    stack.enter_context(file_inp)
-    cal_inp = file_inp.get_calibration_data()
+    with ExitStack() as stack:
+        file_inp = Reader(path_input, verbose=False)
+        stack.enter_context(file_inp)
+        cal_inp = file_inp.get_calibration_data()
 
-    if path_output:
-        cal_hrv = CalibrationHarvester()
-        file_out = Writer(
-            path_output, cal_data=cal_hrv, mode="harvester", verbose=False, force_overwrite=True
-        )
-        stack.enter_context(file_out)
-        cal_out = file_out.get_calibration_data()
-        file_out.store_hostname("hrv_sim_" + config.name)
+        if path_output:
+            cal_hrv = CalibrationHarvester()
+            file_out = Writer(
+                path_output, cal_data=cal_hrv, mode="harvester", verbose=False, force_overwrite=True
+            )
+            stack.enter_context(file_out)
+            cal_out = file_out.get_calibration_data()
+            file_out.store_hostname("hrv_sim_" + config.name)
 
-    hrv_pru = HarvesterPRUConfig.from_vhrv(
-        config,
-        for_emu=True,
-        dtype_in=file_inp.get_datatype(),
-        window_size=file_inp.get_window_samples(),
-        voltage_step_V=file_inp.get_voltage_step(),
-    )
-    hrv = VirtualHarvesterModel(hrv_pru)
-    e_out_Ws = 0.0
+        hrv_pru = HarvesterPRUConfig.from_vhrv(
+            config,
+            for_emu=True,
+            dtype_in=file_inp.get_datatype(),
+            window_size=file_inp.get_window_samples(),
+            voltage_step_V=file_inp.get_voltage_step(),
+        )
+        hrv = VirtualHarvesterModel(hrv_pru)
+        e_out_Ws = 0.0
 
-    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 = cal_inp.voltage.raw_to_si(v_inp) * 1e6
-        i_nA = cal_inp.current.raw_to_si(i_inp) * 1e9
-        length = min(v_uV.size, i_nA.size)
-        for _n in range(length):
-            v_uV[_n], i_nA[_n] = hrv.ivcurve_sample(
-                _voltage_uV=int(v_uV[_n]), _current_nA=int(i_nA[_n])
-            )
-        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(v_uV / 1e6)
-            i_out = cal_out.current.si_to_raw(i_nA / 1e9)
-            file_out.append_iv_data_raw(_t, v_out, i_out)
+        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 = cal_inp.voltage.raw_to_si(v_inp) * 1e6
+            i_nA = cal_inp.current.raw_to_si(i_inp) * 1e9
+            length = min(v_uV.size, i_nA.size)
+            for n_ in range(length):
+                v_uV[n_], i_nA[n_] = hrv.ivcurve_sample(
+                    _voltage_uV=int(v_uV[n_]), _current_nA=int(i_nA[n_])
+                )
+            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(v_uV / 1e6)
+                i_out = cal_out.current.si_to_raw(i_nA / 1e9)
+                file_out.append_iv_data_raw(t_, v_out, i_out)
 
-    stack.close()
     return e_out_Ws

shepherd_core/vsource/virtual_source_model.py

@@ -11,10 +11,11 @@ NOTE: DO NOT OPTIMIZE -> stay close to original code-base
 """
 
 from shepherd_core.data_models.base.calibration import CalibrationEmulator
-from shepherd_core.data_models.content.energy_environment import EnergyDType
-from shepherd_core.data_models.content.virtual_harvester import HarvesterPRUConfig
-from shepherd_core.data_models.content.virtual_source import ConverterPRUConfig
-from shepherd_core.data_models.content.virtual_source import VirtualSourceConfig
+from shepherd_core.data_models.content.enum_datatypes import EnergyDType
+from shepherd_core.data_models.content.virtual_harvester_config import HarvesterPRUConfig
+from shepherd_core.data_models.content.virtual_source_config import ConverterPRUConfig
+from shepherd_core.data_models.content.virtual_source_config import VirtualSourceConfig
+from shepherd_core.data_models.content.virtual_storage_config import StoragePRUConfig
 
 from .virtual_converter_model import PruCalibration
 from .virtual_converter_model import VirtualConverterModel
@@ -36,25 +37,28 @@ class VirtualSourceModel:
     ) -> None:
         self._cal_emu: CalibrationEmulator = cal_emu
         self._cal_pru: PruCalibration = PruCalibration(cal_emu)
-
         self.cfg_src = VirtualSourceConfig() if vsrc is None else vsrc
-        cnv_config = ConverterPRUConfig.from_vsrc(
-            self.cfg_src,
-            dtype_in=dtype_in,
-            log_intermediate_node=log_intermediate,
-        )
-        self.cnv: VirtualConverterModel = VirtualConverterModel(cnv_config, self._cal_pru)
 
-        hrv_config = HarvesterPRUConfig.from_vhrv(
+        # init Harvester
+        cfg_hrv = HarvesterPRUConfig.from_vhrv(
             self.cfg_src.harvester,
             for_emu=True,
             dtype_in=dtype_in,
             window_size=window_size,
             voltage_step_V=voltage_step_V,
         )
+        self.hrv: VirtualHarvesterModel = VirtualHarvesterModel(cfg_hrv)
 
-        self.hrv: VirtualHarvesterModel = VirtualHarvesterModel(hrv_config)
+        # init Converters
+        cfg_cnv = ConverterPRUConfig.from_vsrc(
+            self.cfg_src,
+            dtype_in=dtype_in,
+            log_intermediate_node=log_intermediate,
+        )
+        cfg_storage = StoragePRUConfig.from_vstorage(self.cfg_src.storage, optimize_clamp=True)
+        self.cnv: VirtualConverterModel = VirtualConverterModel(cfg_cnv, self._cal_pru, cfg_storage)
 
+        # state for simulation
         self.W_inp_fWs: float = 0.0
         self.W_out_fWs: float = 0.0
 
@@ -74,8 +78,8 @@ class VirtualSourceModel:
 
         # fake ADC read
         A_out_raw = self._cal_emu.adc_C_A.si_to_raw(I_out_nA * 10**-9)
-
         P_out_fW = self.cnv.calc_out_power(A_out_raw)
+
         V_mid_uV = self.cnv.update_cap_storage()
         V_out_raw = self.cnv.update_states_and_output()
         V_out_uV = int(self._cal_emu.dac_V_A.raw_to_si(V_out_raw) * 10**6)

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  # noqa: PLC0415
-        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