shepherd-core 2025.5.3__tar.gz → 2025.6.1__tar.gz

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: shepherd_core
-Version: 2025.5.3
+Version: 2025.6.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>
-Project-URL: Documentation, https://github.com/orgua/shepherd-datalib/blob/main/README.md
-Project-URL: Issues, https://github.com/orgua/shepherd-datalib/issues
+Project-URL: Documentation, https://github.com/nes-lab/shepherd-tools/blob/main/README.md
+Project-URL: Issues, https://github.com/nes-lab/shepherd-tools/issues
 Project-URL: Source, https://pypi.org/project/shepherd-core/
 Keywords: testbed,beaglebone,pru,batteryless,energyharvesting,solar
 Platform: unix
@@ -56,16 +56,16 @@ Requires-Dist: coverage; extra == "test"
 
 # Core Library
 
-[![PyPiVersion](https://img.shields.io/pypi/v/shepherd_core.svg)](https://pypi.org/project/shepherd_core)
+[![PyPIVersion](https://img.shields.io/pypi/v/shepherd_core.svg)](https://pypi.org/project/shepherd_core)
 [![image](https://img.shields.io/pypi/pyversions/shepherd_core.svg)](https://pypi.python.org/pypi/shepherd-core)
-[![Pytest](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml/badge.svg)](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml)
+[![QA-Tests](https://github.com/nes-lab/shepherd-tools/actions/workflows/quality_assurance.yaml/badge.svg)](https://github.com/nes-lab/shepherd-tools/actions/workflows/quality_assurance.yaml)
 [![CodeStyle](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-**Main Documentation**: <https://orgua.github.io/shepherd>
+**Main Documentation**: <https://nes-lab.github.io/shepherd>
 
-**Source Code**: <https://github.com/orgua/shepherd-datalib>
+**Source Code**: <https://github.com/nes-lab/shepherd-tools>
 
-**Main Project**: <https://github.com/orgua/shepherd>
+**Main Project**: <https://github.com/nes-lab/shepherd>
 
 ---
 
@@ -87,7 +87,7 @@ For postprocessing shepherds .h5-files usage of [shepherd_data](https://pypi.org
 - decode waveforms (gpio-state & timestamp) to UART
 - create an inventory (for deployed versions of software, hardware)
 
-See [official documentation](https://orgua.github.io/shepherd) or [example scripts](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased in both. The [extra](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a [trafficbench](https://github.com/orgua/TrafficBench)-experiment that's used to derive the link-matrix of the testbed-nodes.
+See [official documentation](https://nes-lab.github.io/shepherd) or [example scripts](https://github.com/nes-lab/shepherd-tools/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased in both. The [extra](https://github.com/nes-lab/shepherd-tools/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a [trafficbench](https://github.com/nes-lab/TrafficBench)-experiment that's used to derive the link-matrix of the testbed-nodes.
 
 ## Config-Models in Detail
 
@@ -145,9 +145,9 @@ pip install shepherd-data -U
 For bleeding-edge-features or dev-work it is possible to install directly from GitHub-Sources (here `dev`-branch):
 
 ```Shell
-pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U
+pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U
 # and on sheep with newer debian
-sudo pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
+sudo pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U --break-system-packages
 ```
 
 If you are working with ``.elf``-files (embedding into experiments) you make "objcopy" accessible to python. In Ubuntu, you can either install ``build-essential`` or ``binutils-$ARCH`` with arch being ``msp430`` or ``arm-none-eabi`` for the nRF52.
@@ -179,7 +179,7 @@ To run the testbench, follow these steps:
 3. run the testbench (~ 320 tests):
 
 ```Shell
-cd shepherd-datalib/shepherd_core
+cd shepherd-tools/shepherd_core
 pip3 install ./[tests]
 pytest
 ```

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/README.md

@@ -1,15 +1,15 @@
 # Core Library
 
-[![PyPiVersion](https://img.shields.io/pypi/v/shepherd_core.svg)](https://pypi.org/project/shepherd_core)
+[![PyPIVersion](https://img.shields.io/pypi/v/shepherd_core.svg)](https://pypi.org/project/shepherd_core)
 [![image](https://img.shields.io/pypi/pyversions/shepherd_core.svg)](https://pypi.python.org/pypi/shepherd-core)
-[![Pytest](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml/badge.svg)](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml)
+[![QA-Tests](https://github.com/nes-lab/shepherd-tools/actions/workflows/quality_assurance.yaml/badge.svg)](https://github.com/nes-lab/shepherd-tools/actions/workflows/quality_assurance.yaml)
 [![CodeStyle](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-**Main Documentation**: <https://orgua.github.io/shepherd>
+**Main Documentation**: <https://nes-lab.github.io/shepherd>
 
-**Source Code**: <https://github.com/orgua/shepherd-datalib>
+**Source Code**: <https://github.com/nes-lab/shepherd-tools>
 
-**Main Project**: <https://github.com/orgua/shepherd>
+**Main Project**: <https://github.com/nes-lab/shepherd>
 
 ---
 
@@ -31,7 +31,7 @@ For postprocessing shepherds .h5-files usage of [shepherd_data](https://pypi.org
 - decode waveforms (gpio-state & timestamp) to UART
 - create an inventory (for deployed versions of software, hardware)
 
-See [official documentation](https://orgua.github.io/shepherd) or [example scripts](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased in both. The [extra](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a [trafficbench](https://github.com/orgua/TrafficBench)-experiment that's used to derive the link-matrix of the testbed-nodes.
+See [official documentation](https://nes-lab.github.io/shepherd) or [example scripts](https://github.com/nes-lab/shepherd-tools/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased in both. The [extra](https://github.com/nes-lab/shepherd-tools/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a [trafficbench](https://github.com/nes-lab/TrafficBench)-experiment that's used to derive the link-matrix of the testbed-nodes.
 
 ## Config-Models in Detail
 
@@ -89,9 +89,9 @@ pip install shepherd-data -U
 For bleeding-edge-features or dev-work it is possible to install directly from GitHub-Sources (here `dev`-branch):
 
 ```Shell
-pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U
+pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U
 # and on sheep with newer debian
-sudo pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
+sudo pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U --break-system-packages
 ```
 
 If you are working with ``.elf``-files (embedding into experiments) you make "objcopy" accessible to python. In Ubuntu, you can either install ``build-essential`` or ``binutils-$ARCH`` with arch being ``msp430`` or ``arm-none-eabi`` for the nRF52.
@@ -123,7 +123,7 @@ To run the testbench, follow these steps:
 3. run the testbench (~ 320 tests):
 
 ```Shell
-cd shepherd-datalib/shepherd_core
+cd shepherd-tools/shepherd_core
 pip3 install ./[tests]
 pytest
 ```

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/pyproject.toml

@@ -71,8 +71,8 @@ file = "README.md"
 content-type = "text/markdown"
 
 [project.urls]
-Documentation = "https://github.com/orgua/shepherd-datalib/blob/main/README.md"
-Issues = "https://github.com/orgua/shepherd-datalib/issues"
+Documentation = "https://github.com/nes-lab/shepherd-tools/blob/main/README.md"
+Issues = "https://github.com/nes-lab/shepherd-tools/issues"
 Source = "https://pypi.org/project/shepherd-core/"
 
 [build-system]

shepherd_core-2025.6.1/shepherd_core/commons.py

@@ -0,0 +1,6 @@
+"""Container for commonly shared constants."""
+
+from .config import config
+
+# TODO: deprecated - replace with config in subprojects and then remove here
+SAMPLERATE_SPS_DEFAULT: int = config.SAMPLERATE_SPS

shepherd_core-2025.6.1/shepherd_core/config.py

@@ -0,0 +1,34 @@
+"""Container for a common configuration.
+
+This can be adapted by the user by importing 'config' and changing its variables.
+"""
+
+from pydantic import BaseModel
+from pydantic import HttpUrl
+
+
+class ConfigDefault(BaseModel):
+    """Container for a common configuration."""
+
+    __slots__ = ()
+
+    TESTBED: str = "shepherd_tud_nes"
+    """name of the testbed to validate against - if enabled - see switch below"""
+    VALIDATE_INFRA: bool = True
+    """switch to turn on / off deep validation of data models also considering the current
+    layout & infrastructure of the testbed.
+    """
+
+    SAMPLERATE_SPS: int = 100_000
+    """Rate of IV-Recording of the testbed."""
+
+    UID_NAME: str = "SHEPHERD_NODE_ID"
+    """Variable name to patch in ELF-file"""
+    UID_SIZE: int = 2
+    """Variable size in Byte"""
+
+    TESTBED_SERVER: HttpUrl = "https://shepherd.cfaed.tu-dresden.de:8000/"
+    """Server that holds up to date testbed fixtures"""
+
+
+config = ConfigDefault()

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/base/calibration.py

@@ -95,14 +95,19 @@ cal_hrv_legacy = {  # legacy translator
     "adc_voltage": "adc_V_Sense",  # datalog voltage
 }
 
+# defaults (pre-init complex types)
+cal_pair_dac_V = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
+cal_pair_adc_V = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
+cal_pair_adc_C = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+
 
 class CalibrationHarvester(ShpModel):
     """Container for all calibration-pairs for that device."""
 
-    dac_V_Hrv: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    dac_V_Sim: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    adc_V_Sense: CalibrationPair = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
-    adc_C_Hrv: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+    dac_V_Hrv: CalibrationPair = cal_pair_dac_V
+    dac_V_Sim: CalibrationPair = cal_pair_dac_V
+    adc_V_Sense: CalibrationPair = cal_pair_adc_V
+    adc_C_Hrv: CalibrationPair = cal_pair_adc_C
 
     def export_for_sysfs(self) -> dict:
         """Convert and write the essential data.
@@ -143,10 +148,10 @@ class CalibrationEmulator(ShpModel):
     Differentiates between both target-ports A/B.
     """
 
-    dac_V_A: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    dac_V_B: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    adc_C_A: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
-    adc_C_B: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+    dac_V_A: CalibrationPair = cal_pair_dac_V
+    dac_V_B: CalibrationPair = cal_pair_dac_V
+    adc_C_A: CalibrationPair = cal_pair_adc_C
+    adc_C_B: CalibrationPair = cal_pair_adc_C
 
     def export_for_sysfs(self) -> dict:
         """Convert and write the essential data.

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/base/wrapper.py

@@ -17,11 +17,11 @@ class Wrapper(BaseModel):
     """Generalized web- & file-interface for all models with dynamic typecasting."""
 
     datatype: str
-    # ⤷ model-name
+    """ ⤷ model-name"""
     comment: Optional[SafeStrClone] = None
     created: Optional[datetime] = None
-    # ⤷ Optional metadata
+    """ ⤷ Optional metadata"""
     lib_ver: Optional[str] = version
-    # ⤷ for debug-purposes and later comp-checks
+    """ ⤷ for debug-purposes and later compatibility-checks"""
     parameters: dict
-    # ⤷ ShpModel
+    """ ⤷ ShpModel"""

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/content/energy_environment.py

@@ -28,7 +28,7 @@ class EnergyEnvironment(ContentModel):
     data_path: Path
     data_type: EnergyDType
     data_local: bool = True
-    # ⤷ signals that file has to be copied to testbed
+    """ ⤷ signals that file has to be copied to testbed"""
 
     duration: PositiveFloat
     energy_Ws: PositiveFloat

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/content/firmware.py

@@ -62,7 +62,7 @@ class Firmware(ContentModel, title="Firmware of Target"):
     data_type: FirmwareDType
     data_hash: Optional[str] = None
     data_local: bool = True
-    # ⤷ signals that file has to be copied to testbed
+    """ ⤷ signals that file has to be copied to testbed"""
 
     @model_validator(mode="before")
     @classmethod
@@ -125,12 +125,17 @@ class Firmware(ContentModel, title="Firmware of Target"):
             if "mcu" not in kwargs:
                 kwargs["mcu"] = arch_to_mcu[arch]
 
+        # verification of ELF - warn if something is off
+        # -> adds ARCH if it is able to derive
         if kwargs["data_type"] == FirmwareDType.base64_elf:
             arch = fw_tools.read_arch(file)
-            if "msp430" in arch and not fw_tools.is_elf_msp430(file):
-                raise ValueError("File is not a ELF for msp430")
-            if ("nrf52" in arch or "arm" in arch) and not fw_tools.is_elf_nrf52(file):
-                raise ValueError("File is not a ELF for nRF52")
+            try:
+                if "msp430" in arch and not fw_tools.is_elf_msp430(file):
+                    raise ValueError("File is not a ELF for msp430")
+                if ("nrf52" in arch or "arm" in arch) and not fw_tools.is_elf_nrf52(file):
+                    raise ValueError("File is not a ELF for nRF52")
+            except RuntimeError:
+                logger.warning("ObjCopy not found -> Arch of Firmware can't be verified")
             logger.debug("ELF-File '%s' has arch: %s", file.name, arch)
             if "mcu" not in kwargs:
                 kwargs["mcu"] = arch_to_mcu[arch]

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/content/virtual_harvester.py

@@ -10,7 +10,7 @@ from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Self
 
-from shepherd_core.commons import SAMPLERATE_SPS_DEFAULT
+from shepherd_core.config import config
 from shepherd_core.data_models.base.calibration import CalibrationHarvester
 from shepherd_core.data_models.base.content import ContentModel
 from shepherd_core.data_models.base.shepherd import ShpModel
@@ -363,9 +363,9 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
     def calc_timings_ms(self, *, for_emu: bool) -> tuple[float, float]:
         """factor-in model-internal timing-constraints."""
         window_length = self.samples_n * (1 + self.wait_cycles)
-        time_min_ms = (1 + self.wait_cycles) * 1_000 / SAMPLERATE_SPS_DEFAULT
+        time_min_ms = (1 + self.wait_cycles) * 1_000 / config.SAMPLERATE_SPS
         if for_emu:
-            window_ms = window_length * 1_000 / SAMPLERATE_SPS_DEFAULT
+            window_ms = window_length * 1_000 / config.SAMPLERATE_SPS
             time_min_ms = max(time_min_ms, window_ms)
 
         interval_ms = min(max(self.interval_ms, time_min_ms), 1_000_000)
@@ -453,16 +453,16 @@ class HarvesterPRUConfig(ShpModel):
     voltage_min_uV: u32
     voltage_max_uV: u32
     voltage_step_uV: u32
-    # ⤷ for window-based algo like ivcurve
+    """ ⤷ for window-based algo like ivcurve"""
     current_limit_nA: u32
-    # ⤷ lower bound to detect zero current
+    """ ⤷ lower bound to detect zero current"""
     setpoint_n8: u32
     interval_n: u32
-    # ⤷ between measurements
+    """ ⤷ between measurements"""
     duration_n: u32
-    # ⤷ of measurement
+    """ ⤷ of measurement"""
     wait_cycles_n: u32
-    # ⤷ for DAC to settle
+    """ ⤷ for DAC to settle"""
 
     @classmethod
     def from_vhrv(
@@ -517,7 +517,7 @@ class HarvesterPRUConfig(ShpModel):
             voltage_step_uV=round(voltage_step_mV * 10**3),
             current_limit_nA=round(data.current_limit_uA * 10**3),
             setpoint_n8=round(min(255, data.setpoint_n * 2**8)),
-            interval_n=round(interval_ms * SAMPLERATE_SPS_DEFAULT * 1e-3),
-            duration_n=round(duration_ms * SAMPLERATE_SPS_DEFAULT * 1e-3),
+            interval_n=round(interval_ms * config.SAMPLERATE_SPS * 1e-3),
+            duration_n=round(duration_ms * config.SAMPLERATE_SPS * 1e-3),
             wait_cycles_n=data.wait_cycles,
         )

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/content/virtual_source.py

@@ -7,7 +7,7 @@ from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Self
 
-from shepherd_core.commons import SAMPLERATE_SPS_DEFAULT
+from shepherd_core.config import config
 from shepherd_core.data_models.base.content import ContentModel
 from shepherd_core.data_models.base.shepherd import ShpModel
 from shepherd_core.logger import logger
@@ -23,6 +23,9 @@ NormedNum = Annotated[float, Field(ge=0.0, le=1.0)]
 LUT1D = Annotated[list[NormedNum], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 LUT2D = Annotated[list[LUT1D], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 
+# defaults (pre-init complex types for improved perf) TODO: is documentation still fine?
+vhrv_mppt_opt = VirtualHarvesterConfig(name="mppt_opt")
+
 
 class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     """The vSrc uses the energy environment (file) for supplying the Target Node.
@@ -41,46 +44,48 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     # General Metadata & Ownership -> ContentModel
 
     enable_boost: bool = False
-    # ⤷ if false -> v_intermediate = v_input, output-switch-hysteresis is still usable
+    """ ⤷ if false -> v_intermediate = v_input, output-switch-hysteresis is still usable"""
     enable_buck: bool = False
-    # ⤷ if false -> v_output = v_intermediate
+    """ ⤷ if false -> v_output = v_intermediate"""
     enable_feedback_to_hrv: bool = False
-    # src can control a cv-harvester for ivcurve
+    """ src can control a cv-harvester for ivcurve"""
 
     interval_startup_delay_drain_ms: Annotated[float, Field(ge=0, le=10_000)] = 0
 
-    harvester: VirtualHarvesterConfig = VirtualHarvesterConfig(name="mppt_opt")
+    harvester: VirtualHarvesterConfig = vhrv_mppt_opt
 
     V_input_max_mV: Annotated[float, Field(ge=0, le=10_000)] = 10_000
     I_input_max_mA: Annotated[float, Field(ge=0, le=4.29e3)] = 4_200
     V_input_drop_mV: Annotated[float, Field(ge=0, le=4.29e6)] = 0
-    # ⤷ simulate input-diode
+    """ ⤷ simulate input-diode"""
     R_input_mOhm: Annotated[float, Field(ge=0, le=4.29e6)] = 0
-    # ⤷ resistance only active with disabled boost, range [1 mOhm; 1MOhm]
+    """ ⤷ resistance only active with disabled boost, range [1 mOhm; 1MOhm]"""
 
     # primary storage-Cap
     C_intermediate_uF: Annotated[float, Field(ge=0, le=100_000)] = 0
     V_intermediate_init_mV: Annotated[float, Field(ge=0, le=10_000)] = 3_000
-    # ⤷ allow a proper / fast startup
+    """ ⤷ allow a proper / fast startup"""
     I_intermediate_leak_nA: Annotated[float, Field(ge=0, le=4.29e9)] = 0
 
     V_intermediate_enable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 1
-    # ⤷ target gets connected (hysteresis-combo with next value)
+    """ ⤷ target gets connected (hysteresis-combo with next value)"""
     V_intermediate_disable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 0
-    # ⤷ target gets disconnected
+    """ ⤷ target gets disconnected"""
     interval_check_thresholds_ms: Annotated[float, Field(ge=0, le=4.29e3)] = 0
-    # ⤷ some ICs (BQ) check every 64 ms if output should be disconnected
+    """ ⤷ some ICs (BQ) check every 64 ms if output should be disconnected"""
     # TODO: add intervals for input-disable, output-disable & power-good-signal
 
     # pwr-good: target is informed on output-pin (hysteresis) -> for intermediate voltage
     V_pwr_good_enable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 2_800
     V_pwr_good_disable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 2200
     immediate_pwr_good_signal: bool = True
-    # ⤷ 1: activate instant schmitt-trigger, 0: stay in interval for checking thresholds
+    """ ⤷ 1: activate instant schmitt-trigger, 0: stay in interval for checking thresholds"""
 
-    # final (always last) stage to compensate undetectable current spikes
-    # when enabling power for target
     C_output_uF: Annotated[float, Field(ge=0, le=4.29e6)] = 1.0
+    """
+    final (always last) stage to compensate undetectable current spikes when
+    enabling power for target
+    """
     # TODO: C_output is handled internally as delta-V, but should be a I_transient
     #       that makes it visible in simulation as additional i_out_drain
     # TODO: potential weakness, ACD lowpass is capturing transient,
@@ -88,32 +93,35 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
 
     # Extra
     V_output_log_gpio_threshold_mV: Annotated[float, Field(ge=0, le=4.29e6)] = 1_400
-    # ⤷ min voltage needed to enable recording changes in gpio-bank
+    """ ⤷ min voltage needed to enable recording changes in gpio-bank"""
 
     # Boost Converter
     V_input_boost_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 0
-    # ⤷ min input-voltage for the boost converter to work
+    """ ⤷ min input-voltage for the boost converter to work"""
     V_intermediate_max_mV: Annotated[float, Field(ge=0, le=10_000)] = 10_000
-    # ⤷ boost converter shuts off
+    """ ⤷ boost converter shuts off"""
 
     LUT_input_efficiency: LUT2D = 12 * [12 * [1.00]]
-    # ⤷ rows are current -> first row a[V=0][:]
-    # input-LUT[12][12] depending on array[inp_voltage][log(inp_current)],
-    # influence of cap-voltage is not implemented
+    """ ⤷ rows are current -> first row a[V=0][:]
+
+    input-LUT[12][12] depending on array[inp_voltage][log(inp_current)],
+    influence of cap-voltage is not implemented
+    """
+
     LUT_input_V_min_log2_uV: Annotated[int, Field(ge=0, le=20)] = 0
-    # ⤷ 2^7 = 128 uV -> LUT[0][:] is for inputs < 128 uV
+    """ ⤷ i.e. 2^7 = 128 uV -> LUT[0][:] is for inputs < 128 uV"""
     LUT_input_I_min_log2_nA: Annotated[int, Field(ge=1, le=20)] = 1
-    # ⤷ 2^8 = 256 nA -> LUT[:][0] is for inputs < 256 nA
+    """ ⤷ i.e. 2^8 = 256 nA -> LUT[:][0] is for inputs < 256 nA"""
 
     # Buck Converter
     V_output_mV: Annotated[float, Field(ge=0, le=5_000)] = 2_400
     V_buck_drop_mV: Annotated[float, Field(ge=0, le=5_000)] = 0
-    # ⤷ simulate LDO / diode min voltage differential or output-diode
+    """ ⤷ simulate LDO / diode min voltage differential or output-diode"""
 
     LUT_output_efficiency: LUT1D = 12 * [1.00]
-    # ⤷ array[12] depending on output_current
+    """ ⤷ array[12] depending on output_current"""
     LUT_output_I_min_log2_nA: Annotated[int, Field(ge=1, le=20)] = 1
-    # ⤷ 2^8 = 256 nA -> LUT[0] is for inputs < 256 nA, see notes on LUT_input for explanation
+    """ ⤷ 2^8 = 256 nA -> LUT[0] is for inputs < 256 nA, see notes on LUT_input for explanation"""
 
     @model_validator(mode="before")
     @classmethod
@@ -242,7 +250,7 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         dV[uV] = constant[us/nF] * current[nA] = constant[us*V/nAs] * current[nA]
         """
         C_cap_uF = max(self.C_intermediate_uF, 0.001)
-        return int((10**3 * (2**28)) // (C_cap_uF * SAMPLERATE_SPS_DEFAULT))
+        return int((10**3 * (2**28)) // (C_cap_uF * config.SAMPLERATE_SPS))
 
 
 u32 = Annotated[int, Field(ge=0, lt=2**32)]
@@ -317,7 +325,7 @@ class ConverterPRUConfig(ShpModel):
                 dtype_in, log_intermediate_node=log_intermediate_node
             ),
             interval_startup_delay_drain_n=round(
-                data.interval_startup_delay_drain_ms * SAMPLERATE_SPS_DEFAULT * 1e-3
+                data.interval_startup_delay_drain_ms * config.SAMPLERATE_SPS * 1e-3
             ),
             V_input_max_uV=round(data.V_input_max_mV * 1e3),
             I_input_max_nA=round(data.I_input_max_mA * 1e6),
@@ -330,7 +338,7 @@ class ConverterPRUConfig(ShpModel):
             V_disable_output_threshold_uV=round(states["V_disable_output_threshold_mV"] * 1e3),
             dV_enable_output_uV=round(states["dV_enable_output_mV"] * 1e3),
             interval_check_thresholds_n=round(
-                data.interval_check_thresholds_ms * SAMPLERATE_SPS_DEFAULT * 1e-3
+                data.interval_check_thresholds_ms * config.SAMPLERATE_SPS * 1e-3
             ),
             V_pwr_good_enable_threshold_uV=round(data.V_pwr_good_enable_threshold_mV * 1e3),
             V_pwr_good_disable_threshold_uV=round(data.V_pwr_good_disable_threshold_mV * 1e3),

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/content/virtual_source_fixture.yaml

@@ -1,6 +1,6 @@
 # info:
 # - compendium of all parameters & description
-# - base for neutral fallback values if provided yml is sparse
+# - base for neutral fallback values if provided yaml is sparse
 # - -> it is encouraged to omit redundant parameters
 ---
 - datatype: VirtualSourceConfig

{shepherd_core-2025.5.3 → shepherd_core-2025.6.1}/shepherd_core/data_models/experiment/experiment.py

@@ -11,11 +11,12 @@ from pydantic import model_validator
 from typing_extensions import Self
 from typing_extensions import deprecated
 
+from shepherd_core.config import config
 from shepherd_core.data_models.base.content import IdInt
 from shepherd_core.data_models.base.content import NameStr
 from shepherd_core.data_models.base.content import SafeStr
-from shepherd_core.data_models.base.content import id_default
 from shepherd_core.data_models.base.shepherd import ShpModel
+from shepherd_core.data_models.base.timezone import local_now
 from shepherd_core.data_models.testbed.target import Target
 from shepherd_core.data_models.testbed.testbed import Testbed
 from shepherd_core.version import version
@@ -23,33 +24,28 @@ from shepherd_core.version import version
 from .observer_features import SystemLogging
 from .target_config import TargetConfig
 
+# defaults (pre-init complex types)
+sys_log_all = SystemLogging()  # = all active
+
 
 class Experiment(ShpModel, title="Config of an Experiment"):
     """Config for experiments on the testbed emulating energy environments for target nodes."""
 
     # General Properties
-    id: int = Field(description="Unique ID", default_factory=id_default)
-    # ⤷ TODO: automatic ID is problematic for identification by hash
-
     name: NameStr
     description: Annotated[
         Optional[SafeStr], Field(description="Required for public instances")
     ] = None
     comment: Optional[SafeStr] = None
-    created: datetime = Field(default_factory=datetime.now)
-
-    # Ownership & Access
-    owner_id: Optional[IdInt] = None
 
     # feedback
-    email_results: bool = False
+    email_results: bool = True
 
-    sys_logging: SystemLogging = SystemLogging()  # = all active
+    sys_logging: SystemLogging = sys_log_all
 
     # schedule
     time_start: Optional[datetime] = None  # = ASAP
     duration: Optional[timedelta] = None  # = till EOF
-    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
 
     # targets
     target_configs: Annotated[list[TargetConfig], Field(min_length=1, max_length=128)]
@@ -57,13 +53,16 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     # debug
     lib_ver: Optional[str] = version
 
+    # deprecated fields, TODO: remove before public release
+    id: Annotated[Optional[int], deprecated("not needed")] = None
+    created: Annotated[Optional[datetime], deprecated("not needed")] = None
+    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
+    owner_id: Annotated[Optional[IdInt], deprecated("not needed")] = None
+
     @model_validator(mode="after")
     def post_validation(self) -> Self:
-        # TODO: only do deep validation with active connection to TB-client
-        #       or with cached fixtures
-        testbed = Testbed()  # this will query the first (and only) entry of client
+        self._validate_observers(self.target_configs)
         self._validate_targets(self.target_configs)
-        self._validate_observers(self.target_configs, testbed)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Duration of experiment can't be negative.")
         return self
@@ -75,8 +74,9 @@ class Experiment(ShpModel, title="Config of an Experiment"):
         for _config in configs:
             for _id in _config.target_IDs:
                 target_ids.append(_id)
-                Target(id=_id)
-                # ⤷ this can raise exception for non-existing targets
+                if config.VALIDATE_INFRA:
+                    Target(id=_id)
+                    # ⤷ this can raise exception for non-existing targets
             if _config.custom_IDs is not None:
                 custom_ids = custom_ids + _config.custom_IDs[: len(_config.target_IDs)]
             else:
@@ -87,7 +87,10 @@ class Experiment(ShpModel, title="Config of an Experiment"):
             raise ValueError("Custom Target-ID are faulty (some form of id-collisions)!")
 
     @staticmethod
-    def _validate_observers(configs: Iterable[TargetConfig], testbed: Testbed) -> None:
+    def _validate_observers(configs: Iterable[TargetConfig]) -> None:
+        if not config.VALIDATE_INFRA:
+            return
+        testbed = Testbed()
         target_ids = [_id for _config in configs for _id in _config.target_IDs]
         obs_ids = [testbed.get_observer(_id).id for _id in target_ids]
         if len(target_ids) > len(set(obs_ids)):
@@ -105,3 +108,10 @@ class Experiment(ShpModel, title="Config of an Experiment"):
         # gets already caught in target_config - but keep:
         msg = f"Target-ID {target_id} was not found in Experiment '{self.name}'"
         raise ValueError(msg)
+
+    def folder_name(self, custom_date: Optional[datetime] = None) -> str:
+        date = custom_date if custom_date is not None else self.time_start
+        timestamp = local_now() if date is None else date
+        timestrng = timestamp.strftime("%Y-%m-%d_%H-%M-%S")
+        # ⤷ closest to ISO 8601, avoids ":"
+        return f"{timestrng}_{self.name.replace(' ', '_')}"