shepherd-core 2023.12.1__tar.gz → 2024.4.1__tar.gz

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/PKG-INFO

@@ -1,14 +1,12 @@
 Metadata-Version: 2.1
 Name: shepherd_core
-Version: 2023.12.1
+Version: 2024.4.1
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
-Home-page: https://pypi.org/project/shepherd-core/
-Author: Ingmar Splitt, Kai Geissdoerfer
-Author-email: ingmar.splitt@tu-dresden.de
-Maintainer-email: ingmar.splitt@tu-dresden.de
-License: MIT
-Project-URL: Tracker, https://github.com/orgua/shepherd-datalib/issues
-Project-URL: Source, https://github.com/orgua/shepherd-datalib
+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: Source, https://pypi.org/project/shepherd-core/
 Keywords: testbed,beaglebone,pru,batteryless,energyharvesting,solar
 Platform: unix
 Platform: linux
@@ -35,8 +33,8 @@ Requires-Dist: numpy
 Requires-Dist: pyYAML
 Requires-Dist: chromalog
 Requires-Dist: pydantic[email]>2.0.0
-Requires-Dist: tqdm
 Requires-Dist: scipy
+Requires-Dist: tqdm
 Requires-Dist: intelhex
 Requires-Dist: requests
 Requires-Dist: pyelftools
@@ -63,7 +61,7 @@ Requires-Dist: coverage; extra == "test"
 [![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)
 [![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)
 
-**Documentation**: <https://orgua.github.io/shepherd/external/shepherd_core.html>
+**Main Documentation**: <https://orgua.github.io/shepherd>
 
 **Source Code**: <https://github.com/orgua/shepherd-datalib>
 
@@ -71,53 +69,42 @@ Requires-Dist: coverage; extra == "test"
 
 ---
 
-This Python Module is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
+`shepherd-core` is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
 
-For postprocessing shepherds .h5-files users want to use [shepherd_data](https://pypi.org/project/shepherd_data).
+For postprocessing shepherds .h5-files usage of [shepherd_data](https://pypi.org/project/shepherd_data) is recommended.
 
 ## Features
 
 - read and write shepherds hdf5-files
-- create, read, write and convert experiments for the testbed (all data-models included)
+- create, read, write and convert experiments for the testbed
+  - all required data-models are included
 - simulate the virtual source, including virtual harvesters (and virtual converter as a whole)
-- connect and query the testbed via a webclient (TestbedClient)
+- connect and query the testbed via a webclient (TestbedClient in alpha-stage)
   - offline usage defaults to static demo-fixtures loaded from yaml-files in the model-directories
 - work with target-firmwares
   - embed, modify, verify, convert
   - **Note**: working with ELF-files requires external dependencies, see ``Installation``-Chapter
 - decode waveforms (gpio-state & timestamp) to UART
-- create an inventory (used versions of software, hardware)
+- create an inventory (for deployed versions of software, hardware)
 
-See [examples](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased there. 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-experiment that's used to derive the link-matrix.
+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.
 
-### Compatibility
+## Config-Models in Detail
 
-| OS      |   PyVersion  | Comment                                    |
-|---------|--------------|--------------------------------------------|
-| Ubuntu  | 3.8 - 3.12   |                                            |
-| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
-| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+These pydantic data-models are used throughout all shepherd interfaces. Users can create an experiment, include their own content and feed it to the testbed.
 
-Notes:
-- hex-conversion needs a working and accessible objcopy
-- elf-supports needs
-  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
-  - most elf-features also still utilize hex-conversion
-
-### Data-Models in Detail
-
-- new orchestration ``/data-models`` with focus on remote shepherd-testbed
+- orchestration ``/data-models`` with focus on remote shepherd-testbed
 - classes of sub-models
   - ``/base``: base-classes, configuration and -functionality for all models
   - ``/testbed``: meta-data representation of all testbed-components
-  - ``/content``: reusable meta-data for fw, h5 and vsrc-definitions
+  - ``/content``: reusable user-defined meta-data for fw, h5 and vsrc-definitions
   - ``/experiment``: configuration-models including sub-systems
   - ``/task``: digestible configs for shepherd-herd or -sheep
   - behavior controlled by ``ShpModel`` and ``content``-model
 - a basic database is available as fixtures through a ``tb_client``
   - fixtures selectable by name & ID
   - fixtures support inheritance
-- models support
+- the models support
   - auto-completion with neutral / sensible values
   - complex and custom datatypes (i.e. PositiveInt, lists-checks on length)
   - checking of inputs and type-casting
@@ -130,6 +117,20 @@ Notes:
   - exposes no internal paths
 - experiments can be transformed to task-sets (``TestbedTasks.from_xp()``)
 
+## Compatibility
+
+| OS      |   PyVersion  | Comment                                    |
+|---------|--------------|--------------------------------------------|
+| Ubuntu  | 3.8 - 3.12   |                                            |
+| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
+| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+
+Notes:
+- hex-conversion needs a working and accessible objcopy
+- elf-supports needs
+  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
+  - most elf-features also still utilize hex-conversion
+
 ## Installation
 
 The Library is available via PyPI and can be installed with
@@ -166,3 +167,17 @@ For creating an inventory of the host-system you should install
 ```shell
   pip install shepherd-core[inventory]
 ```
+
+## Unittests
+
+To run the testbench, follow these steps:
+
+1. Navigate your host-shell into the package-folder and
+2. install dependencies
+3. run the testbench (~ 320 tests):
+
+```Shell
+cd shepherd-datalib/shepherd_core
+pip3 install ./[tests]
+pytest
+```

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/README.md

@@ -5,7 +5,7 @@
 [![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)
 [![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)
 
-**Documentation**: <https://orgua.github.io/shepherd/external/shepherd_core.html>
+**Main Documentation**: <https://orgua.github.io/shepherd>
 
 **Source Code**: <https://github.com/orgua/shepherd-datalib>
 
@@ -13,53 +13,42 @@
 
 ---
 
-This Python Module is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
+`shepherd-core` is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
 
-For postprocessing shepherds .h5-files users want to use [shepherd_data](https://pypi.org/project/shepherd_data).
+For postprocessing shepherds .h5-files usage of [shepherd_data](https://pypi.org/project/shepherd_data) is recommended.
 
 ## Features
 
 - read and write shepherds hdf5-files
-- create, read, write and convert experiments for the testbed (all data-models included)
+- create, read, write and convert experiments for the testbed
+  - all required data-models are included
 - simulate the virtual source, including virtual harvesters (and virtual converter as a whole)
-- connect and query the testbed via a webclient (TestbedClient)
+- connect and query the testbed via a webclient (TestbedClient in alpha-stage)
   - offline usage defaults to static demo-fixtures loaded from yaml-files in the model-directories
 - work with target-firmwares
   - embed, modify, verify, convert
   - **Note**: working with ELF-files requires external dependencies, see ``Installation``-Chapter
 - decode waveforms (gpio-state & timestamp) to UART
-- create an inventory (used versions of software, hardware)
+- create an inventory (for deployed versions of software, hardware)
 
-See [examples](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased there. 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-experiment that's used to derive the link-matrix.
+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.
 
-### Compatibility
+## Config-Models in Detail
 
-| OS      |   PyVersion  | Comment                                    |
-|---------|--------------|--------------------------------------------|
-| Ubuntu  | 3.8 - 3.12   |                                            |
-| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
-| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
-
-Notes:
-- hex-conversion needs a working and accessible objcopy
-- elf-supports needs
-  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
-  - most elf-features also still utilize hex-conversion
-
-### Data-Models in Detail
+These pydantic data-models are used throughout all shepherd interfaces. Users can create an experiment, include their own content and feed it to the testbed.
 
-- new orchestration ``/data-models`` with focus on remote shepherd-testbed
+- orchestration ``/data-models`` with focus on remote shepherd-testbed
 - classes of sub-models
   - ``/base``: base-classes, configuration and -functionality for all models
   - ``/testbed``: meta-data representation of all testbed-components
-  - ``/content``: reusable meta-data for fw, h5 and vsrc-definitions
+  - ``/content``: reusable user-defined meta-data for fw, h5 and vsrc-definitions
   - ``/experiment``: configuration-models including sub-systems
   - ``/task``: digestible configs for shepherd-herd or -sheep
   - behavior controlled by ``ShpModel`` and ``content``-model
 - a basic database is available as fixtures through a ``tb_client``
   - fixtures selectable by name & ID
   - fixtures support inheritance
-- models support
+- the models support
   - auto-completion with neutral / sensible values
   - complex and custom datatypes (i.e. PositiveInt, lists-checks on length)
   - checking of inputs and type-casting
@@ -72,6 +61,20 @@ Notes:
   - exposes no internal paths
 - experiments can be transformed to task-sets (``TestbedTasks.from_xp()``)
 
+## Compatibility
+
+| OS      |   PyVersion  | Comment                                    |
+|---------|--------------|--------------------------------------------|
+| Ubuntu  | 3.8 - 3.12   |                                            |
+| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
+| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+
+Notes:
+- hex-conversion needs a working and accessible objcopy
+- elf-supports needs
+  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
+  - most elf-features also still utilize hex-conversion
+
 ## Installation
 
 The Library is available via PyPI and can be installed with
@@ -108,3 +111,17 @@ For creating an inventory of the host-system you should install
 ```shell
   pip install shepherd-core[inventory]
 ```
+
+## Unittests
+
+To run the testbench, follow these steps:
+
+1. Navigate your host-shell into the package-folder and
+2. install dependencies
+3. run the testbench (~ 320 tests):
+
+```Shell
+cd shepherd-datalib/shepherd_core
+pip3 install ./[tests]
+pytest
+```

shepherd_core-2024.4.1/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "shepherd_core"
+description = "Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed"
+keywords = ["testbed", "beaglebone", "pru", "batteryless", "energyharvesting", "solar"]
+
+authors = [{name = "Ingmar Splitt", email = "ingmar.splitt@tu-dresden.de"},]
+maintainers = [{name = "Ingmar Splitt", email = "ingmar.splitt@tu-dresden.de"},]
+
+readme = {file = "README.md", content-type = "text/markdown"}
+license = {file = "LICENSE"}
+dynamic = ["version"]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Natural Language :: English",
+]
+
+requires-python = ">=3.8"
+dependencies = [
+    "h5py",
+    "numpy",
+    "pyYAML",
+    "chromalog",
+    "pydantic[email]>2.0.0",
+    "scipy",
+    "tqdm",
+    "intelhex",
+    "requests",
+    "pyelftools",
+    "zstandard",
+]
+
+[project.optional-dependencies]
+elf = [
+    "pwntools-elf-only",
+    # TODO: still separate because of missing windows-compat
+    # modified package for reading ELF-files with fw_tools
+    # original can be problematic to install on windows & beaglebone
+    # probably also needed: https://docs.pwntools.com/en/stable/install.html  + binutils-$ARCH
+]
+
+inventory = [
+    "psutil",
+]
+
+
+dev = [
+    "twine",
+    "pre-commit",
+    "pyright",
+    "ruff",
+    "mypy",
+    "types-PyYAML",
+]
+
+test = [
+    "pytest",
+    "coverage",
+]
+
+[project.urls]
+Documentation = "https://github.com/orgua/shepherd-datalib/blob/main/README.md"
+Issues = "https://github.com/orgua/shepherd-datalib/issues"
+Source = "https://pypi.org/project/shepherd-core/"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+platforms = ["unix", "linux", "osx", "cygwin", "win32", "win64"]
+zip-safe = true
+include-package-data = true
+
+[tool.setuptools.package-dir]
+shepherd_core = "shepherd_core"
+
+[tool.setuptools.package-data]
+shepherd_core = [
+    "README.md",
+    "*.yaml",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "shepherd_core.__version__"}
+
+[tool.pytest.ini_options]
+markers = [
+    "converter: automatically added when no objcopy is found (on ubuntu install build-essential)",
+    "elf: automatically added when no elf-support is found (on windows or missing shepherd-core[elf])"
+]
+
+addopts = "-vvv --stepwise" # opts: verbose result for each tests
+# TODO: add something like "--cov --cov-report html --cov-report term-missing --cov-fail-under 95"
+
+[tool.coverage.run]
+source = ["shepherd_core"]
+omit = ["*/shepherd_data/*"]
+
+[tool.mypy]
+python_version = 3.8
+ignore_missing_imports = true

shepherd_core-2024.4.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/__init__.py

@@ -4,6 +4,7 @@ Provides classes for storing and retrieving sampled IV data to/from
 HDF5 files.
 
 """
+
 from .data_models.base.calibration import Calc_t
 from .data_models.base.calibration import CalibrationCape
 from .data_models.base.calibration import CalibrationEmulator
@@ -12,7 +13,7 @@ from .data_models.base.calibration import CalibrationPair
 from .data_models.base.calibration import CalibrationSeries
 from .data_models.base.timezone import local_now
 from .data_models.base.timezone import local_tz
-from .data_models.task import Compression
+from .data_models.task.emulation import Compression
 from .inventory import Inventory
 from .logger import get_verbose_level
 from .logger import increase_verbose_level
@@ -22,7 +23,7 @@ from .testbed_client.client import TestbedClient
 from .testbed_client.client import tb_client
 from .writer import Writer
 
-__version__ = "2023.12.1"
+__version__ = "2024.04.1"
 
 __all__ = [
     "Reader",

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/base/calibration.py

@@ -165,7 +165,7 @@ class CapeData(ShpModel):
     `See<https://github.com/beagleboard/beaglebone-black/wiki/System-Reference-Manual#824_EEPROM_Data_Format>`_
     """
 
-    header: conbytes(max_length=4) = b"\xAA\x55\x33\xEE"
+    header: conbytes(max_length=4) = b"\xaa\x55\x33\xee"
     eeprom_revision: constr(max_length=2) = "A2"
     board_name: constr(max_length=32) = "BeagleBone SHEPHERD2 Cape"
     version: constr(max_length=4) = "24B0"
@@ -207,6 +207,7 @@ class CalibrationCape(ShpModel):
             cape: data can be supplied
         Returns:
             CalibrationCape object with extracted calibration data.
+
         """
         dv = cls().model_dump(include={"harvester", "emulator"})
         lw = list(dict_generator(dv))
@@ -225,6 +226,7 @@ class CalibrationCape(ShpModel):
         Returns
         -------
             Byte string representation of calibration values.
+
         """
         lw = list(dict_generator(self.model_dump(include={"harvester", "emulator"})))
         values = [walk[-1] for walk in lw]

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/base/content.py

@@ -1,7 +1,10 @@
 import hashlib
 from datetime import datetime
 from typing import Optional
+from typing import Union
+from uuid import uuid4
 
+from pydantic import UUID4
 from pydantic import Field
 from pydantic import StringConstraints
 from pydantic import model_validator
@@ -14,30 +17,34 @@ from .timezone import local_now
 # constr -> to_lower=True, max_length=16, regex=r"^[\w]+$"
 # ⤷ Regex = AlphaNum
 IdInt = Annotated[int, Field(ge=0, lt=2**128)]
-NameStr = Annotated[str, StringConstraints(max_length=32, pattern=r'^[^<>:;,?"*|\/\\]+$')]
+NameStr = Annotated[str, StringConstraints(max_length=32, pattern=r"^[^<>:;,?\"\*|\/\\]+$")]
 # ⤷ Regex = FileSystem-Compatible ASCII
 SafeStr = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ Regex = All Printable ASCII-Characters with Space
 
 
 def id_default() -> int:
+    # note: IdInt has space for 128 bit, so 128/4 = 32 hex-chars
     time_stamp = str(local_now()).encode("utf-8")
-    time_hash = hashlib.sha3_224(time_stamp).hexdigest()[-16:]
+    time_hash = hashlib.sha3_224(time_stamp).hexdigest()[-32:]
     return int(time_hash, 16)
 
 
 class ContentModel(ShpModel):
     # General Properties
-    id: IdInt = Field(  # noqa: A003
+    # id: UUID4 = Field(  # TODO: db-migration - temp fix for documentation
+    id: Union[UUID4, int] = Field(
         description="Unique ID",
-        default_factory=id_default,
+        default_factory=uuid4,
     )
     name: NameStr
     description: Annotated[Optional[SafeStr], Field(description="Required when public")] = None
     comment: Optional[SafeStr] = None
     created: datetime = Field(default_factory=datetime.now)
+    updated_last: datetime = Field(default_factory=datetime.now)
 
     # Ownership & Access
+    # TODO: remove owner & group, only needed for DB
     owner: NameStr
     group: Annotated[NameStr, Field(description="University or Subgroup")]
     visible2group: bool = False

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/base/shepherd.py

@@ -7,6 +7,7 @@ from typing import Any
 from typing import Generator
 from typing import Optional
 from typing import Union
+from uuid import UUID
 
 import yaml
 from pydantic import BaseModel
@@ -39,6 +40,7 @@ yaml.add_representer(pathlib.WindowsPath, path2str, SafeDumper)
 yaml.add_representer(pathlib.Path, path2str, SafeDumper)
 yaml.add_representer(timedelta, time2int, SafeDumper)
 yaml.add_representer(IPv4Address, generic2str, SafeDumper)
+yaml.add_representer(UUID, generic2str, SafeDumper)
 
 
 class ShpModel(BaseModel):

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/content/energy_environment.py

@@ -13,7 +13,7 @@ class EnergyDType(str, Enum):
     ivsample = "ivsample"
     ivsamples = "ivsample"
     ivcurve = "ivcurve"
-    ivcurves = "ivcurve"
+    ivcurves = "ivcurve"  # a stream could also be called iv-surface
     isc_voc = "isc_voc"
 
 

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/content/virtual_harvester.py

@@ -76,7 +76,7 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
         logger.debug("VHrv-Inheritances: %s", chain)
 
         # post corrections -> should be in separate validator
-        cal = CalibrationHarvester()  # todo: as argument?
+        cal = CalibrationHarvester()  # TODO: as argument?
         c_limit = values.get("current_limit_uA", 50_000)  # cls.current_limit_uA)
         values["current_limit_uA"] = max(10**6 * cal.adc_C_Hrv.raw_to_si(4), c_limit)
 

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/content/virtual_source.py

@@ -25,12 +25,13 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     for supplying the Target Node during the experiment.
     If not already done, the energy will be harvested and then converted.
     The converter-stage is software defined and offers:
-      buck-boost-combinations,
-      a simple diode + resistor and
-      an intermediate buffer capacitor.
-      TODO: I,V,R should be in regular unit (V, A, Ohm)
+    - buck-boost-combinations,
+    - a simple diode + resistor and
+    - an intermediate buffer capacitor.
     """
 
+    # TODO: I,V,R should be in regular unit (V, A, Ohm)
+
     # General Metadata & Ownership -> ContentModel
 
     enable_boost: bool = False
@@ -123,14 +124,17 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         only has simpler formula, second enabling when V_Cap >= V_out
 
         Math behind this calculation:
-        Energy-Change Storage Cap   ->  E_new = E_old - E_output
-        with Energy of a Cap 	    -> 	E_x = C_x * V_x^2 / 2
-        combine formulas 		    ->
-                    C_store * V_store_new^2 / 2 = C_store * V_store_old^2 / 2 - C_out * V_out^2 / 2
-        convert formula to V_new 	->	V_store_new^2 = V_store_old^2 - (C_out / C_store) * V_out^2
-        convert into dV	 	        ->	dV = V_store_new - V_store_old
-        in case of V_cap = V_out 	-> 	dV = V_store_old * (sqrt(1 - C_out / C_store) - 1)
-        -> dV values will be reversed (negated), because dV is always negative (Voltage drop)
+
+        - Energy-Change Storage Cap ->  E_new = E_old - E_output
+        - with Energy of a Cap 	    -> 	E_x = C_x * V_x^2 / 2
+        - combine formulas 		    ->  C_store * V_store_new^2 / 2 =
+          C_store * V_store_old^2 / 2 - C_out * V_out^2 / 2
+        - convert formula to V_new 	->	V_store_new^2 =
+          V_store_old^2 - (C_out / C_store) * V_out^2
+        - convert into dV	 	        ->	dV = V_store_new - V_store_old
+        - in case of V_cap = V_out 	-> 	dV = V_store_old * (sqrt(1 - C_out / C_store) - 1)
+
+        Note: dV values will be reversed (negated), because dV is always negative (Voltage drop)
         """
         values = {}
         if self.C_intermediate_uF > 0 and self.C_output_uF > 0:
@@ -186,8 +190,9 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
 
     def calc_converter_mode(self, *, log_intermediate_node: bool) -> int:
         """Assembles bitmask from discrete values
+
         log_intermediate_node: record / log virtual intermediate (cap-)voltage and
-                            -current (out) instead of output-voltage and -current
+        -current (out) instead of output-voltage and -current
         """
         enable_storage = self.C_intermediate_uF > 0
         enable_boost = self.enable_boost and enable_storage

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/experiment/experiment.py

@@ -2,8 +2,10 @@ from datetime import datetime
 from datetime import timedelta
 from typing import List
 from typing import Optional
+from typing import Union
+from uuid import uuid4
 
-from pydantic import EmailStr
+from pydantic import UUID4
 from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Annotated
@@ -12,7 +14,6 @@ from typing_extensions import Self
 from ..base.content import IdInt
 from ..base.content import NameStr
 from ..base.content import SafeStr
-from ..base.content import id_default
 from ..base.shepherd import ShpModel
 from ..testbed.target import Target
 from ..testbed.testbed import Testbed
@@ -26,11 +27,10 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     """
 
     # General Properties
-    id: IdInt = Field(  # noqa: A003
-        description="Unique ID",
-        default_factory=id_default,
-    )
+    # id: UUID4 ... # TODO db-migration - temp fix for documentation
+    id: Union[UUID4, int] = Field(default_factory=uuid4)
     # ⤷ TODO: automatic ID is problematic for identification by hash
+
     name: NameStr
     description: Annotated[
         Optional[SafeStr], Field(description="Required for public instances")
@@ -38,12 +38,12 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     comment: Optional[SafeStr] = None
     created: datetime = Field(default_factory=datetime.now)
 
-    # Ownership & Access, TODO
-    owner_id: Optional[IdInt] = 5472  # UUID?
+    # Ownership & Access
+    owner_id: Optional[IdInt] = None
 
     # feedback
-    email_results: Optional[EmailStr] = None
-    # ⤷ TODO: can be bool, as its linked to account
+    email_results: bool = False
+
     sys_logging: SystemLogging = SystemLogging(dmesg=True, ptp=True, shepherd=True)
 
     # schedule

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/experiment/observer_features.py

@@ -66,7 +66,7 @@ class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
 
     # post-processing,
     uart_decode: bool = False
-    # todo: quickfix - uart-log currently done online in userspace
+    # TODO: quickfix - uart-log currently done online in userspace
     # NOTE: gpio-tracing currently shows rather big - but rare - "blind" windows (~1-4us)
     uart_pin: GPIO = GPIO(name="GPIO8")
     uart_baudrate: Annotated[int, Field(ge=2_400, le=921_600)] = 115_200
@@ -113,11 +113,10 @@ class GpioEvent(ShpModel, title="Config for a GPIO-Event"):
 
 
 class GpioActuation(ShpModel, title="Config for GPIO-Actuation"):
-    """Configuration for a GPIO-Actuation-Sequence
-    TODO: not implemented ATM:
-        - decide if pru control sys-gpio or
-        - reverses pru-gpio (preferred if possible)
-    """
+    """Configuration for a GPIO-Actuation-Sequence"""
+
+    # TODO: not implemented ATM - decide if pru control sys-gpio or
+    # TODO: not implemented ATM - reverses pru-gpio (preferred if possible)
 
     events: Annotated[List[GpioEvent], Field(min_length=1, max_length=1024)]
 

{shepherd_core-2023.12.1 → shepherd_core-2024.4.1}/shepherd_core/data_models/task/observer_tasks.py

@@ -21,7 +21,7 @@ class ObserverTasks(ShpModel):
     """Collection of tasks for selected observer included in experiment"""
 
     observer: NameStr
-    owner_id: IdInt
+    owner_id: Optional[IdInt]  # TODO: set to optional for now, shouldn't be
 
     # PRE PROCESS
     time_prep: datetime  # TODO: should be optional