shepherd-core 2025.8.1__tar.gz → 2025.10.1__tar.gz

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shepherd_core
-Version: 2025.8.1
+Version: 2025.10.1
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
 Author-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
 Maintainer-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Natural Language :: English

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/examples/experiment_generic_var1.py

@@ -16,10 +16,11 @@ What the code does:
 from pathlib import Path
 
 import shepherd_core.data_models as sm
-from shepherd_core import WebClient
 from shepherd_core.data_models.task import TestbedTasks
 from shepherd_core.data_models.testbed import MCU
 
+from shepherd_core import WebClient
+
 # For online-queries the lib can be connected to the testbed-server.
 # NOTE: there are 3 states:
 # - unconnected -> demo-fixtures are queried (locally)

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/examples/experiment_generic_var2.py

@@ -15,9 +15,10 @@
 from pathlib import Path
 
 import shepherd_core.data_models as sm
-from shepherd_core import WebClient
 from shepherd_core.data_models.task import TestbedTasks
 
+from shepherd_core import WebClient
+
 # For online-queries the lib can be connected to the testbed-server.
 # NOTE: there are 3 states:
 # - unconnected -> demo-fixtures are queried (locally)

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/examples/experiment_models.py

@@ -19,9 +19,10 @@ How to define an experiment:
 """
 
 import shepherd_core.data_models as sm
-from shepherd_core import WebClient
 from shepherd_core.data_models.task import TestbedTasks
 
+from shepherd_core import WebClient
+
 # generate description for all parameters -> base for web-forms
 sm.Experiment.schema_to_file("experiment_schema.yaml")
 

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/examples/firmware_model.py

@@ -6,11 +6,12 @@ or shepherd-core[elf].
 
 from pathlib import Path
 
-from shepherd_core import WebClient
-from shepherd_core import fw_tools
 from shepherd_core.data_models import Firmware
 from shepherd_core.data_models import FirmwareDType
 
+from shepherd_core import WebClient
+from shepherd_core import fw_tools
+
 path_elf = Path(__file__).parent.parent / "tests/fw_tools/build_msp.elf"
 
 # Option 1 - fully manual

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/examples/firmware_modification.py

@@ -8,10 +8,11 @@ Note: make sure to have installed
 import shutil
 from pathlib import Path
 
-from shepherd_core import fw_tools
 from shepherd_core.data_models import Firmware
 from shepherd_core.data_models import FirmwareDType
 
+from shepherd_core import fw_tools
+
 path_src = Path(__file__).parent.parent / "tests/fw_tools/build_msp.elf"
 path_elf = Path(__file__).with_name("firmware_msp.elf")
 

shepherd_core-2025.8.1/examples/simulate_vharvester.py → shepherd_core-2025.10.1/examples/simulations/vharvester.py

@@ -6,26 +6,31 @@
 
 Output:
 E_out = 0.000 mWs -> cv20
-E_out = 17.165 mWs -> cv10
-E_out = 17.427 mWs -> mppt_voc
-E_out = 17.242 mWs -> mppt_bq_solar
-E_out = 13.998 mWs -> mppt_bq_thermoelectric
-E_out = 15.202 mWs -> mppt_po
+E_out = 17.143 mWs -> cv10
+E_out = 17.384 mWs -> mppt_voc
+E_out = 17.249 mWs -> mppt_bq_solar
+E_out = 13.954 mWs -> mppt_bq_thermoelectric
+E_out = 15.001 mWs -> mppt_po
 E_out = 17.811 mWs -> mppt_opt
+
 """
 
 from pathlib import Path
 
-from shepherd_core import Reader
 from shepherd_core.data_models import VirtualHarvesterConfig
 from shepherd_core.vsource import simulate_harvester
+
+from shepherd_core import Reader
 from shepherd_data import ivonne
 
 # config simulation
 sim_duration = 32
-file_ivonne = Path(__file__).parent.parent.parent / "shepherd_data/examples/jogging_10m.iv"
+file_ivonne = Path(__file__).parents[3] / "shepherd_data/examples/jogging_10m.iv"
 file_ivcurve = Path(__file__).parent / "jogging_ivcurve.h5"
 
+if not file_ivonne.exists():
+    raise FileNotFoundError("Input-File not found - check path")
+
 hrv_list = [
     "cv20",
     # ⤷ fails due to lower solar voltage
@@ -39,7 +44,7 @@ hrv_list = [
     "mppt_opt",
 ]
 
-save_files: bool = False
+save_files: bool = True
 
 # convert IVonne to IVCurve
 if not file_ivcurve.exists():

shepherd_core-2025.8.1/examples/simulate_vsource.py → shepherd_core-2025.10.1/examples/simulations/vsource.py

@@ -10,20 +10,22 @@ The output file can be analyzed and plotted with shepherds tool suite.
 
 Output:
 E_out = 220.001 mWs -> direct (no current-limit)
-E_out = 13.142 mWs -> diode+capacitor
-E_out = 13.066 mWs -> diode+resistor+capacitor
-E_out = 15.045 mWs -> BQ25504
-E_out = 14.962 mWs -> BQ25504s
-E_out = 14.397 mWs -> BQ25570
-E_out = 14.232 mWs -> BQ25570s
+E_out = 14.670 mWs -> diode+capacitor
+E_out = 14.563 mWs -> diode+resistor+capacitor
+E_out = 16.718 mWs -> BQ25504
+E_out = 16.805 mWs -> BQ25504s
+E_out = 16.369 mWs -> BQ25570
+E_out = 16.387 mWs -> BQ25570s
 
 """
 
 from pathlib import Path
 
 from shepherd_core.data_models import VirtualSourceConfig
+from shepherd_core.data_models import VirtualStorageConfig
 from shepherd_core.vsource import ResistiveTarget
 from shepherd_core.vsource import simulate_source
+
 from shepherd_data import Reader
 
 # config simulation
@@ -41,6 +43,11 @@ src_list = [
 tgt = ResistiveTarget(R_Ohm=1_000, controlled=True)
 save_files = True
 
+if not file_input.exists():
+    raise FileNotFoundError(
+        "Input-File not found - please run harvester-simulation first to create it."
+    )
+
 for src_name in src_list:
     file_output = file_input.with_stem(file_input.stem + "_emu_" + src_name) if save_files else None
 
@@ -48,10 +55,12 @@ for src_name in src_list:
         config=VirtualSourceConfig(
             name=src_name,
             C_output_uF=0,
-            V_intermediate_enable_threshold_mV=1,
-            V_intermediate_disable_threshold_mV=0,
-            # jogging-dataset has max VOC of ~1.6 V -> lower set-point for non-boost
-            C_intermediate_uF=100 if "direct" not in src_name else 0,
+            V_intermediate_enable_output_threshold_mV=1,
+            V_intermediate_disable_output_threshold_mV=0,
+            # jogging-dataset has maximum VOC of ~1.6 V -> lower set-point for non-boost
+            storage=VirtualStorageConfig.capacitor(C_uF=100, V_rated=10.0)
+            if "direct" not in src_name
+            else None,
             V_pwr_good_enable_threshold_mV=1300 if "dio" in src_name else 2800,
             V_pwr_good_disable_threshold_mV=1000 if "dio" in src_name else 2400,
             V_input_drop_mV=150 if "dio" in src_name else 0,

shepherd_core-2025.10.1/examples/simulations/vstorage.py

@@ -0,0 +1,239 @@
+"""A set of experiments to validate and qualify the virtual storage algorithms.
+
+Some general Notes:
+
+- ShpCap is also displayed when emulating Lipo and lead-acid, but it can't and won't behave similar
+- during charging the model KiBaM-Plus will deviate from normal KiBaM and KiBaM-Simple,
+  as it supports the rate capacity effect and transients (during charging)
+
+"""
+
+import multiprocessing
+import os
+import sys
+from datetime import timedelta
+from pathlib import Path
+
+from pydantic import PositiveFloat
+from pydantic import validate_call
+from shepherd_core.data_models.content.virtual_storage_config import VirtualStorageConfig
+from shepherd_core.data_models.content.virtual_storage_config import soc_t
+from shepherd_core.vsource.virtual_storage_model import ModelStorage
+from shepherd_core.vsource.virtual_storage_model import VirtualStorageModel
+from shepherd_core.vsource.virtual_storage_models_kibam import ModelKiBaM
+from shepherd_core.vsource.virtual_storage_models_kibam import ModelKiBaMPlus
+from shepherd_core.vsource.virtual_storage_models_kibam import ModelKiBaMSimple
+from shepherd_core.vsource.virtual_storage_models_kibam import ModelShpCap
+from shepherd_core.vsource.virtual_storage_simulator import StorageSimulator
+
+from shepherd_core import log
+
+path_here = Path(__file__).parent
+
+duration_max = 20 if "PYTEST_CURRENT_TEST" in os.environ else sys.float_info.max
+# ⤷ limits runtime for pytest
+
+
+@validate_call
+def get_models(
+    SoC_init: soc_t, config: VirtualStorageConfig, dt_s: PositiveFloat
+) -> list[ModelStorage]:
+    """Models to include in experiments."""
+    return [
+        ModelKiBaM(SoC_init=SoC_init, cfg=config, dt_s=dt_s),
+        ModelKiBaMPlus(SoC_init=SoC_init, cfg=config, dt_s=dt_s),
+        ModelKiBaMSimple(SoC_init=SoC_init, cfg=config, dt_s=dt_s, optimize_clamp=True),
+        ModelKiBaMSimple(SoC_init=SoC_init, cfg=config, dt_s=dt_s, interpolate=True),
+        VirtualStorageModel(SoC_init=SoC_init, cfg=config, dt_s=dt_s),
+        ModelShpCap(SoC_init=SoC_init, cfg=config, dt_s=dt_s),
+    ][1:5]
+
+
+class CurrentPulsed:
+    """A simple constant current source that is pulsed until a target SoC is reached."""
+
+    @validate_call
+    def __init__(
+        self,
+        I_pulse: float,
+        period_pulse: PositiveFloat,
+        duration_pulse: PositiveFloat,
+        SoC_target: soc_t,
+    ) -> None:
+        self.I_pulse = I_pulse
+        self.period_pulse = period_pulse
+        self.duration_pulse = duration_pulse
+        self.SoC_target = SoC_target
+
+    def step(self, t_s: float, SoC: float, _v: float) -> float:
+        if (self.I_pulse < 0 and SoC <= self.SoC_target) or (
+            self.I_pulse > 0 and SoC >= self.SoC_target
+        ):
+            return 0
+        return self.I_pulse if t_s % self.period_pulse < self.duration_pulse else 0
+
+
+class ResistiveChargePulsed:
+    """A pulsed charger that is 'current limited' by a resistor."""
+
+    @validate_call
+    def __init__(
+        self,
+        V_target: PositiveFloat,
+        R_Ohm: PositiveFloat,
+        period_pulse: PositiveFloat,
+        duration_pulse: PositiveFloat,
+    ) -> None:
+        self.R_Ohm = R_Ohm
+        self.V_target = V_target
+        self.period_pulse = period_pulse
+        self.duration_pulse = duration_pulse
+
+    def step(self, t_s: float, _s: float, V: float) -> float:
+        I_A = (self.V_target - V) / self.R_Ohm
+        return I_A if t_s % self.period_pulse < self.duration_pulse else 0
+
+
+def experiment_current_ramp_pos(config: VirtualStorageConfig) -> None:
+    """Charge virtual storage with a positive current ramp (increasing power)."""
+    dt_s = 0.1
+    SoC_start = 0.5
+    duration_s = min(200, duration_max)
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+
+    def current_trace(t_s: float, _s: float, _v: float) -> float:
+        return 0.1 + 0.15 * t_s / duration_s  # pru-model can handle +- 268 mA
+
+    sim.run(fn=current_trace, duration_s=duration_s)
+    sim.plot(path_here, f"XP {config.name}, current charge ramp (positive)")
+
+
+def experiment_current_ramp_neg(config: VirtualStorageConfig) -> None:
+    """Discharge virtual storage with a negative current ramp (increasing power)."""
+    dt_s = 0.1
+    SoC_start = 0.5
+    duration_s = min(200, duration_max)
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+
+    def current_trace(t_s: float, _s: float, _v: float) -> float:
+        return -(0.1 + 0.14 * t_s / duration_s)  # pru-model can handle +- 268 mA
+
+    sim.run(fn=current_trace, duration_s=duration_s)
+    sim.plot(path_here, f"XP {config.name}, current discharge ramp (negative)")
+
+
+def experiment_pulsed_discharge(config: VirtualStorageConfig) -> None:
+    """Discharge virtual storage with a pulsed constant current."""
+    dt_s = 0.2
+    SoC_start = 1.0
+    SoC_target = 0.0
+    i_pulse = CurrentPulsed(
+        I_pulse=-0.1, period_pulse=200, duration_pulse=100, SoC_target=SoC_target
+    )  # pru-model can handle +- 268 mA
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+    sim.run(fn=i_pulse.step, duration_s=min(1_000, duration_max))
+    sim.plot(path_here, f"XP {config.name}, pulsed discharge .1A, 1000 s (figure_9a)")
+
+
+def experiment_pulsed_charge(config: VirtualStorageConfig) -> None:
+    """Charge virtual storage with a pulsed constant current."""
+    dt_s = 0.2
+    SoC_start = 0.0
+    SoC_target = 1.0
+    i_pulse = CurrentPulsed(
+        I_pulse=0.1, period_pulse=200, duration_pulse=100, SoC_target=SoC_target
+    )  # pru-model can handle +- 268 mA
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+    sim.run(fn=i_pulse.step, duration_s=min(1_000, duration_max))
+    sim.plot(path_here, f"XP {config.name}, pulsed charge .1A, 1000 s (figure_9b)")
+
+
+def experiment_pulsed_resistive_charge(config: VirtualStorageConfig) -> None:
+    """Charge virtual storage with a resistive constant voltage."""
+    dt_s = 0.5
+    SoC_start = 0.0
+    i_pulse = ResistiveChargePulsed(R_Ohm=20, V_target=4.2, period_pulse=200, duration_pulse=100)
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+    sim.run(fn=i_pulse.step, duration_s=min(3_000, duration_max))
+    sim.plot(path_here, f"XP {config.name}, pulsed resistive charge 20 Ohm to 4.2 V, 3000 s")
+
+
+def experiment_resistive_load(config: VirtualStorageConfig) -> None:
+    """Charge virtual storage with a resistive constant voltage."""
+    dt_s = 0.5
+    SoC_start = 1.0
+
+    def i_charge(_t_s: float, _s: float, V: float) -> float:
+        return -V / 20
+
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+    sim.run(fn=i_charge, duration_s=min(1_000, duration_max))
+    sim.plot(path_here, f"XP {config.name}, resistive load 20 Ohm from 4.2 V, 1000 s")
+
+
+def experiment_self_discharge() -> None:
+    """Observe self-discharge behavior of virtual storage models."""
+    dt_s = 0.2
+    SoC_start = 1.0
+    SoC_target = 0.9
+    duration = timedelta(minutes=25)
+    store = VirtualStorageConfig.capacitor(C_uF=100, V_rated=6.3)
+    R_leak = store.calc_R_leak_capacitor(duration=duration, SoC_final=SoC_target, SoC_0=SoC_start)
+    log.info("R_leak = %.2f Ohm", R_leak)
+    config = VirtualStorageConfig.capacitor(C_uF=100, V_rated=6.3, R_leak_Ohm=R_leak)
+    sim = StorageSimulator(
+        models=get_models(SoC_start, config, dt_s),
+        dt_s=dt_s,
+    )
+
+    def step(_t: float, _s: float, _v: float) -> float:
+        return 0
+
+    sim.run(fn=step, duration_s=min(duration.total_seconds(), duration_max))
+    sim.plot(
+        path_here,
+        f"XP {config.name}, self-discharge, "
+        f"SoC {SoC_start} to {SoC_target} in {duration.total_seconds()} s",
+    )
+
+
+if __name__ == "__main__":
+    with multiprocessing.Pool() as pool:
+        pool.apply_async(experiment_self_discharge)
+
+        configs = [
+            VirtualStorageConfig.capacitor(C_uF=10e6, V_rated=4.2),  # match charge with batteries
+            VirtualStorageConfig.lipo(q_mAh=10),
+            VirtualStorageConfig.lead_acid(q_mAh=10),
+        ]
+
+        for cfg in configs:
+            pool.apply_async(experiment_pulsed_charge, args=(cfg,))
+            pool.apply_async(experiment_pulsed_discharge, args=(cfg,))
+            pool.apply_async(experiment_current_ramp_pos, args=(cfg,))
+            pool.apply_async(experiment_current_ramp_neg, args=(cfg,))
+
+        for cfg in configs[0:2]:
+            pool.apply_async(experiment_pulsed_resistive_charge, args=(cfg,))
+            pool.apply_async(experiment_resistive_load, args=(cfg,))
+
+        pool.close()
+        pool.join()

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/pyproject.toml

@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Natural Language :: English",

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/shepherd_core/data_models/__init__.py

@@ -22,8 +22,9 @@ from .content.energy_environment import EnergyDType
 from .content.energy_environment import EnergyEnvironment
 from .content.firmware import Firmware
 from .content.firmware import FirmwareDType
-from .content.virtual_harvester import VirtualHarvesterConfig
-from .content.virtual_source import VirtualSourceConfig
+from .content.virtual_harvester_config import VirtualHarvesterConfig
+from .content.virtual_source_config import VirtualSourceConfig
+from .content.virtual_storage_config import VirtualStorageConfig
 from .experiment.experiment import Experiment
 from .experiment.observer_features import GpioActuation
 from .experiment.observer_features import GpioEvent
@@ -58,5 +59,6 @@ __all__ = [
     "UartLogging",
     "VirtualHarvesterConfig",
     "VirtualSourceConfig",
+    "VirtualStorageConfig",
     "Wrapper",
 ]

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/shepherd_core/data_models/base/content.py

@@ -36,10 +36,12 @@ class ContentModel(ShpModel):
         default_factory=id_default,
     )
     name: NameStr
+    """ ⤷ name of virtual content, models can be queried by this slug."""
     description: Annotated[SafeStr | None, Field(description="Required when public")] = None
     comment: SafeStr | None = None
     created: datetime = Field(default_factory=datetime.now)
     updated_last: datetime = Field(default_factory=datetime.now)
+    # TODO: add dedicated 'inherit_from' field?
 
     # Ownership & Access
     # TODO: remove owner & group, only needed for DB

{shepherd_core-2025.8.1 → shepherd_core-2025.10.1}/shepherd_core/data_models/content/__init__.py

@@ -7,8 +7,9 @@ from .energy_environment import EnergyDType
 from .energy_environment import EnergyEnvironment
 from .firmware import Firmware
 from .firmware_datatype import FirmwareDType
-from .virtual_harvester import VirtualHarvesterConfig
-from .virtual_source import VirtualSourceConfig
+from .virtual_harvester_config import VirtualHarvesterConfig
+from .virtual_source_config import VirtualSourceConfig
+from .virtual_storage_config import VirtualStorageConfig
 
 __all__ = [
     "EnergyDType",
@@ -17,4 +18,5 @@ __all__ = [
     "FirmwareDType",
     "VirtualHarvesterConfig",
     "VirtualSourceConfig",
+    "VirtualStorageConfig",
 ]

shepherd_core-2025.8.1/shepherd_core/data_models/content/virtual_harvester.py → shepherd_core-2025.10.1/shepherd_core/data_models/content/virtual_harvester_config.py

@@ -332,11 +332,11 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
     @model_validator(mode="after")
     def post_validation(self) -> Self:
         if self.voltage_min_mV > self.voltage_max_mV:
-            raise ValueError("Voltage min > max")
+            raise ValueError("Voltage minimum > max")
         if self.voltage_mV < self.voltage_min_mV:
-            raise ValueError("Voltage below min")
+            raise ValueError("Voltage below minimum")
         if self.voltage_mV > self.voltage_max_mV:
-            raise ValueError("Voltage above max")
+            raise ValueError("Voltage above maximum")
 
         return self