shepherd-core 2023.12.1__py3-none-any.whl → 2024.4.1__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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

shepherd_core/data_models/task/testbed_tasks.py

@@ -1,12 +1,12 @@
 from typing import List
 from typing import Optional
 
-from pydantic import EmailStr
 from pydantic import Field
 from pydantic import validate_call
 from typing_extensions import Annotated
 from typing_extensions import Self
 
+from ..base.content import IdInt
 from ..base.content import NameStr
 from ..base.shepherd import ShpModel
 from ..experiment.experiment import Experiment
@@ -21,7 +21,10 @@ class TestbedTasks(ShpModel):
     observer_tasks: Annotated[List[ObserverTasks], Field(min_length=1, max_length=128)]
 
     # POST PROCESS
-    email: Optional[EmailStr] = None
+    email_results: bool = False
+    owner_id: Optional[IdInt]
+    # TODO: had real email previously, does it really need these at all?
+    #  DB stores experiment and knows when to email
 
     @classmethod
     @validate_call
@@ -34,7 +37,8 @@ class TestbedTasks(ShpModel):
         return cls(
             name=xp.name,
             observer_tasks=obs_tasks,
-            email=xp.email_results,
+            email_results=xp.email_results,
+            owner_id=xp.owner_id,
         )
 
     def get_observer_tasks(self, observer: str) -> Optional[ObserverTasks]:

shepherd_core/data_models/testbed/cape.py

@@ -24,7 +24,7 @@ class TargetPort(str, Enum):
 class Cape(ShpModel, title="Shepherd-Cape"):
     """meta-data representation of a testbed-component (physical object)"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     version: NameStr
     description: SafeStr

shepherd_core/data_models/testbed/gpio.py

@@ -26,7 +26,7 @@ class Direction(str, Enum):
 class GPIO(ShpModel, title="GPIO of Observer Node"):
     """meta-data representation of a testbed-component"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: Optional[SafeStr] = None
     comment: Optional[SafeStr] = None

shepherd_core/data_models/testbed/mcu.py

@@ -26,7 +26,7 @@ class ProgrammerProtocol(str, Enum):
 class MCU(ShpModel, title="Microcontroller of the Target Node"):
     """meta-data representation of a testbed-component (physical object)"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None

shepherd_core/data_models/testbed/observer.py

@@ -26,7 +26,7 @@ MACStr = Annotated[
 class Observer(ShpModel, title="Shepherd-Sheep"):
     """meta-data representation of a testbed-component (physical object)"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None

shepherd_core/data_models/testbed/target.py

@@ -21,7 +21,7 @@ MCUPort = Annotated[int, Field(ge=1, le=2)]
 class Target(ShpModel, title="Target Node (DuT)"):
     """meta-data representation of a testbed-component (physical object)"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     version: NameStr
     description: SafeStr

shepherd_core/data_models/testbed/testbed.py

@@ -20,7 +20,7 @@ from .observer import Observer
 class Testbed(ShpModel):
     """meta-data representation of a testbed-component (physical object)"""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None

shepherd_core/decoder_waveform/uart.py

@@ -17,6 +17,7 @@ https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter
 https://sigrok.org/wiki/Protocol_decoder:Uart
 
 """
+
 from enum import Enum
 from pathlib import Path
 from typing import Optional

shepherd_core/fw_tools/validation.py

@@ -1,6 +1,5 @@
-"""TODO: Work in Progress
+"""TODO: Work in Progress"""
 
-"""
 import tempfile
 from pathlib import Path
 

shepherd_core/inventory/__init__.py

@@ -3,6 +3,9 @@
 - system-parameters
 - hardware-config
 """
+
+from datetime import datetime
+from datetime import timedelta
 from pathlib import Path
 from typing import List
 
@@ -26,14 +29,20 @@ __all__ = [
 
 class Inventory(PythonInventory, SystemInventory, TargetInventory):
     # has all child-parameters
+    hostname: str
+    created: datetime
 
     @classmethod
     def collect(cls) -> Self:
         # one by one for more precise error messages
-        pid = PythonInventory.collect().model_dump(exclude_unset=True, exclude_defaults=True)
+        # NOTE: system is first, as it must take a precise timestamp
         sid = SystemInventory.collect().model_dump(exclude_unset=True, exclude_defaults=True)
+        pid = PythonInventory.collect().model_dump(exclude_unset=True, exclude_defaults=True)
         tid = TargetInventory.collect().model_dump(exclude_unset=True, exclude_defaults=True)
         model = {**pid, **sid, **tid}
+        # make important metadata available at root level
+        model["created"] = sid["timestamp"]
+        model["hostname"] = sid["hostname"]
         return cls(**model)
 
 
@@ -53,3 +62,44 @@ class InventoryList(ShpModel):
                 content = list(item.model_dump().values())
                 content = ["" if value is None else str(value) for value in content]
                 fd.write(", ".join(content) + "\r\n")
+
+    def warn(self) -> dict:
+        warnings = {}
+        ts_earl = min([_e.created.timestamp() for _e in self.elements])
+        for _e in self.elements:
+            if _e.uptime > timedelta(hours=30).total_seconds():
+                warnings["uptime"] = f"[{self.hostname}] restart is recommended"
+            if (_e.created.timestamp() - ts_earl) > 10:
+                warnings["time_delta"] = f"[{self.hostname}] time-sync has failed"
+
+        # turn  dict[hostname][type] = val
+        # to    dict[type][val] = list[hostnames]
+        _inp = {
+            _e.hostname: _e.model_dump(exclude_unset=True, exclude_defaults=True)
+            for _e in self.elements
+        }
+        result = {}
+        for _host, _types in _inp.items():
+            for _type, _val in _types.items():
+                if _type not in result:
+                    result[_type] = {}
+                if _val not in result[_type]:
+                    result[_type][_val] = []
+                result[_type][_val].append(_host)
+        rescnt = {_key: len(_val) for _key, _val in result.items()}
+        t_unique = [
+            "h5py",
+            "numpy",
+            "pydantic",
+            "python",
+            "shepherd_core",
+            "shepherd_sheep",
+            "yaml",
+            "zstandard",
+        ]
+        for _key in t_unique:
+            if rescnt[_key] > 1:
+                warnings[_key] = f"[{_key}] VersionMismatch - {result[_key]}"
+
+        # TODO: finish with more potential warnings
+        return warnings

shepherd_core/inventory/system.py

@@ -2,10 +2,12 @@ import platform
 import subprocess
 import time
 from contextlib import suppress
+from datetime import datetime
 from typing import Optional
 
 from typing_extensions import Self
 
+from .. import local_now
 from .. import logger
 
 try:
@@ -22,6 +24,9 @@ from ..data_models import ShpModel
 class SystemInventory(ShpModel):
     uptime: PositiveInt
     # ⤷ seconds
+    timestamp: datetime
+    # time_delta: timedelta = timedelta(0)  # noqa: ERA001
+    # ⤷ lag behind earliest observer, TODO: wrong place
 
     system: str
     release: str
@@ -43,6 +48,8 @@ class SystemInventory(ShpModel):
 
     @classmethod
     def collect(cls) -> Self:
+        ts = local_now()
+
         if psutil is None:
             ifs2 = {}
             uptime = 0
@@ -58,6 +65,7 @@ class SystemInventory(ShpModel):
 
         model_dict = {
             "uptime": round(uptime),
+            "timestamp": ts,
             "system": platform.system(),
             "release": platform.release(),
             "version": platform.version(),

shepherd_core/reader.py

@@ -1,6 +1,5 @@
-"""
-Reader-Baseclass
-"""
+"""Reader-Baseclass"""
+
 import contextlib
 import errno
 import logging
@@ -36,8 +35,10 @@ class Reader:
     """Sequentially Reads shepherd-data from HDF5 file.
 
     Args:
+    ----
         file_path: Path of hdf5 file containing shepherd data with iv-samples, iv-curves or isc&voc
         verbose: more debug-info during usage, 'None' skips the setter
+
     """
 
     samples_per_buffer: int = 10_000
@@ -158,7 +159,7 @@ class Reader:
         )
 
     def _refresh_file_stats(self) -> None:
-        """update internal states, helpful after resampling or other changes in data-group"""
+        """Update internal states, helpful after resampling or other changes in data-group"""
         self.h5file.flush()
         if (self.ds_time.shape[0] > 1) and (self.ds_time[1] != self.ds_time[0]):
             # this assumes isochronal sampling
@@ -182,15 +183,17 @@ class Reader:
     ) -> Generator[tuple, None, None]:
         """Generator that reads the specified range of buffers from the hdf5 file.
         can be configured on first call
-        TODO: reconstruct - start/end mark samples and
-            each call can request a certain number of samples
+        TODO: reconstruct - start/end mark samples &
+         each call can request a certain number of samples
 
         Args:
+        ----
             :param start_n: (int) Index of first buffer to be read
             :param end_n: (int) Index of last buffer to be read
             :param is_raw: (bool) output original data, not transformed to SI-Units
             :param omit_ts: (bool) optimize reading if timestamp is never used
         Yields: Buffers between start and end (tuple with time, voltage, current)
+
         """
         if end_n is None:
             end_n = int(self.ds_voltage.shape[0] // self.samples_per_buffer)
@@ -250,7 +253,7 @@ class Reader:
             return None
 
     def get_hrv_config(self) -> dict:
-        """essential info for harvester
+        """Essential info for harvester
         :return: config-dict directly for vHarvester to be used during emulation
         """
         return {
@@ -259,7 +262,7 @@ class Reader:
         }
 
     def is_valid(self) -> bool:
-        """checks file for plausibility
+        """Checks file for plausibility
 
         :return: state of validity
         """
@@ -387,7 +390,7 @@ class Reader:
         return True
 
     def __getitem__(self, key: str) -> Any:
-        """returns attribute or (if none found) a handle for a group or dataset (if found)
+        """Returns attribute or (if none found) a handle for a group or dataset (if found)
 
         :param key: attribute, group, dataset
         :return: value of that key, or handle of object
@@ -399,7 +402,7 @@ class Reader:
         raise KeyError
 
     def energy(self) -> float:
-        """determine the recorded energy of the trace
+        """Determine the recorded energy of the trace
         # multiprocessing: https://stackoverflow.com/a/71898911
         # -> failed with multiprocessing.pool and pathos.multiprocessing.ProcessPool
 
@@ -427,7 +430,7 @@ class Reader:
     def _dset_statistics(
         self, dset: h5py.Dataset, cal: Optional[CalibrationPair] = None
     ) -> Dict[str, float]:
-        """some basic stats for a provided dataset
+        """Some basic stats for a provided dataset
         :param dset: dataset to evaluate
         :param cal: calibration (if wanted)
         :return: dict with entries for mean, min, max, std
@@ -469,7 +472,7 @@ class Reader:
         return stats
 
     def _data_timediffs(self) -> List[float]:
-        """calculate list of (unique) time-deltas between buffers [s]
+        """Calculate list of (unique) time-deltas between buffers [s]
             -> optimized version that only looks at the start of each buffer
 
         :return: list of (unique) time-deltas between buffers [s]
@@ -500,7 +503,7 @@ class Reader:
         return list(diffs)
 
     def check_timediffs(self) -> bool:
-        """validate equal time-deltas
+        """Validate equal time-deltas
         -> unexpected time-jumps hint at a corrupted file or faulty measurement
 
         :return: True if OK
@@ -529,7 +532,7 @@ class Reader:
         *,
         minimal: bool = False,
     ) -> Dict[str, dict]:
-        """recursive FN to capture the structure of the file
+        """Recursive FN to capture the structure of the file
         :param node: starting node, leave free to go through whole file
         :param minimal: just provide a bare tree (much faster)
         :return: structure of that node with everything inside it
@@ -580,7 +583,7 @@ class Reader:
         return metadata
 
     def save_metadata(self, node: Union[h5py.Dataset, h5py.Group, None] = None) -> dict:
-        """get structure of file and dump content to yaml-file with same name as original
+        """Get structure of file and dump content to yaml-file with same name as original
 
         :param node: starting node, leave free to go through whole file
         :return: structure of that node with everything inside it
@@ -609,7 +612,7 @@ class Reader:
 
     @staticmethod
     def get_filter_for_redundant_states(data: np.ndarray) -> np.ndarray:
-        """input is 1D state-vector, kep only first from identical & sequential states
+        """Input is 1D state-vector, kep only first from identical & sequential states
         algo: create an offset-by-one vector and compare against original
         """
         if len(data.shape) > 1:

shepherd_core/testbed_client/cache_path.py

@@ -0,0 +1,15 @@
+import os
+from pathlib import Path
+
+
+def _get_xdg_path(variable_name: str, default_path: Path) -> Path:
+    _value = os.environ.get(variable_name)
+    if _value is None or _value == "":
+        return default_path
+    return Path(_value)
+
+
+user_path = Path("~").expanduser()
+
+cache_xdg_path = _get_xdg_path("XDG_CACHE_HOME", user_path / ".cache")
+cache_user_path = cache_xdg_path / "shepherd_datalib"