kiwi-scan 0.2.0__py3-none-any.whl

kiwi_scan/__init__.py

@@ -0,0 +1,192 @@
+# SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
+# SPDX-License-Identifier: MIT
+
+"""
+This module provides the startup helpers for the import of scans and plugins.
+
+Loading order:
+1. Built-in
+2. Optional
+
+__all__:
+- Plugin classes register themselves via decorators at import time.
+- If a module is not imported, its class is not registered.
+- Debug logging here helps diagnose missing registrations 
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import importlib.util
+import logging
+import os
+import pkgutil
+import sys
+from pathlib import Path
+from typing import Set
+from kiwi_scan.scan.registry import load_all_scan_types
+from importlib.metadata import version, PackageNotFoundError
+
+__all__ = ["__version__", "load_all_plugins", "load_all_scan_types"]
+try:
+    __version__ = version("kiwi-scan")
+except PackageNotFoundError:
+    # fallback for editable installs / no metadata
+    __version__ = "0+unknown"
+
+logger = logging.getLogger(__name__)
+
+PLUGIN_ENVVAR = "KIWI_SCAN_PLUGIN_PATH"
+
+
+def _module_suffix_for_path(pyfile: Path) -> str:
+    """
+    Avoids module-name collisions when two different plugin directories
+    contain files with the same basename.
+    """
+    resolved = str(pyfile.resolve())
+    digest = hashlib.sha1(resolved.encode("utf-8")).hexdigest()[:12]
+    return f"{pyfile.stem}_{digest}"
+
+
+def _import_plugin_file(pyfile: Path, raise_on_error: bool = False) -> None:
+    """
+    Import plugin module.
+    """
+    pyfile = pyfile.resolve()
+    module_name = f"kiwi_scan_ext_{_module_suffix_for_path(pyfile)}"
+
+    try:
+        logger.debug("Importing plugin file: %s as %s", pyfile, module_name)
+
+        spec = importlib.util.spec_from_file_location(module_name, pyfile)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not create import spec for {pyfile}")
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+
+        logger.debug("Imported plugin file successfully: %s", pyfile)
+
+    except Exception:
+        logger.exception("Failed to import plugin file %s", pyfile)
+        if raise_on_error:
+            raise
+
+
+def _import_package_modules(package_name: str, raise_on_error: bool = False) -> None:
+    """
+    Import all modules provided by kiwi scan
+    """
+    try:
+        package = importlib.import_module(package_name)
+    except Exception:
+        logger.exception("Failed to import package %s", package_name)
+        if raise_on_error:
+            raise
+        return
+
+    package_path = getattr(package, "__path__", None)
+    if not package_path:
+        logger.debug("Package %s has no __path__; nothing to scan", package_name)
+        return
+
+    modules = sorted(pkgutil.iter_modules(package_path), key=lambda m: m.name)
+    logger.debug("Scanning built-in plugin package %s (%d modules)", package_name, len(modules))
+
+    for module_info in modules:
+        if module_info.name.startswith("_"):
+            logger.debug("Skipping private module %s.%s", package_name, module_info.name)
+            continue
+
+        fullname = f"{package_name}.{module_info.name}"
+        try:
+            logger.debug("Importing built-in plugin module %s", fullname)
+            importlib.import_module(fullname)
+            logger.debug("Imported built-in plugin module %s", fullname)
+        except Exception:
+            logger.exception("Failed to import built-in plugin module %s", fullname)
+            if raise_on_error:
+                raise
+
+
+def load_all_plugins(raise_on_error: bool = False) -> None:
+    """
+    Import all plugin modules.
+    """
+    package_root = __package__ or __name__
+    builtin_package = f"{package_root}.plugin_concrete"
+
+    raw = os.environ.get(PLUGIN_ENVVAR, "")
+
+    logger.debug("Starting plugin loading")
+    logger.debug("Builtin plugin package: %s", builtin_package)
+    logger.debug("%s=%r", PLUGIN_ENVVAR, raw)
+
+    # Always load the plugins that ship with kiwi_scan.
+    _import_package_modules(builtin_package, raise_on_error=raise_on_error)
+
+    # Then load any external plugins configured by the user.
+    if not raw.strip():
+        logger.debug("%s not set; built-in plugins loaded only", PLUGIN_ENVVAR)
+    else:
+        seen: Set[Path] = set()
+
+        for entry in raw.split(os.pathsep):
+            entry = entry.strip()
+            if not entry:
+                continue
+
+            p = Path(entry).expanduser().resolve()
+            logger.debug("Considering plugin path entry: %s", p)
+
+            if not p.exists():
+                logger.warning("Plugin path does not exist: %s", p)
+                continue
+
+            if p.is_file():
+                if p.suffix != ".py":
+                    logger.debug("Skipping non-Python file: %s", p)
+                    continue
+
+                if p in seen:
+                    logger.debug("Skipping duplicate plugin file: %s", p)
+                    continue
+
+                _import_plugin_file(p, raise_on_error=raise_on_error)
+                seen.add(p)
+                continue
+
+            if p.is_dir():
+                pyfiles = sorted(
+                    candidate
+                    for candidate in p.glob("*.py")
+                    if not candidate.name.startswith("_")
+                )
+                logger.debug("Scanning plugin directory %s (%d files)", p, pyfiles.__len__())
+
+                for pyfile in pyfiles:
+                    pyfile = pyfile.resolve()
+                    if pyfile in seen:
+                        logger.debug("Skipping already imported plugin file: %s", pyfile)
+                        continue
+
+                    _import_plugin_file(pyfile, raise_on_error=raise_on_error)
+                    seen.add(pyfile)
+
+                continue
+
+            logger.warning("Plugin path is neither a file nor directory: %s", p)
+
+    try:
+        from kiwi_scan.plugin.registry import PLUGIN_REGISTRY
+
+        logger.debug(
+            "Plugin registry now contains %d entries: %s",
+            len(PLUGIN_REGISTRY),
+            sorted(PLUGIN_REGISTRY.keys()),
+        )
+    except Exception:
+        logger.exception("Could not inspect plugin registry after loading")

kiwi_scan/actuator/factory.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
+# SPDX-License-Identifier: MIT
+
+from typing import Type, Dict, Optional
+
+from kiwi_scan.datamodels import ActuatorConfig
+from kiwi_scan.actuator_concrete.single_epics import EpicsActuator
+from kiwi_scan.actuator_concrete.single_simulation import SimulatedActuator
+from kiwi_scan.actuator.single import AbstractActuator
+
+
+class ActuatorFactory:
+    """
+    Factory for creating actuator instances based on configuration.
+
+    Usage:
+        # simple flag-based simulation
+        actuator = ActuatorFactory.create(config, use_simulation=True)
+
+        # config-based (EPICS)
+        actuator = ActuatorFactory.create(config)
+    """
+    # Registry mapping type keys to actuator classes
+    _registry: Dict[str, Type[AbstractActuator]] = {
+        'epics': EpicsActuator,
+        'sim': SimulatedActuator,
+    }
+
+    @classmethod
+    def create(
+        cls,
+        config: ActuatorConfig,
+        use_simulation: Optional[bool] = None,
+        actuator_type: Optional[str] = None,
+    ) -> AbstractActuator:
+        """
+        Create an actuator based on:
+          - explicit `use_simulation` flag (overrides everything)
+          - `actuator_type` argument ('epics' or 'sim')
+          - `config.actuator_type` attribute, if defined in your datamodel
+
+        Falls back to EpicsActuator.
+        """
+        # Determine type key
+        if use_simulation is True:
+            key = 'sim'
+        elif use_simulation is False:
+            key = 'epics'
+        else:
+            # try explicit override
+            key = actuator_type or getattr(config, 'actuator_type', None)
+            # default if missing
+            key = key or 'epics'
+
+        try:
+            actuator_cls = cls._registry[key]
+        except KeyError:
+            raise ValueError(f"Unknown actuator type '{key}'. "
+                             f"Supported types: {list(cls._registry)}")
+
+        return actuator_cls(config)
+
+
+def create_actuator(config: ActuatorConfig) -> AbstractActuator:
+    key = config.type  # “epics” or “sim”
+    cls = ActuatorFactory._registry.get(key)
+    if cls is None:
+        raise ValueError(f"Unknown type {key}")
+    return cls(config)

kiwi_scan/actuator/multi.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
+# SPDX-License-Identifier: MIT
+
+from typing import Sequence, Optional, Any
+import time
+from kiwi_scan.actuator.single import AbstractActuator
+from kiwi_scan.datamodels import ActuatorConfig
+
+import logging
+import time
+from typing import Sequence, Optional, Any
+
+import numpy as np
+from kiwi_scan.actuator.single import AbstractActuator
+from kiwi_scan.datamodels import ActuatorConfig
+from kiwi_scan.epics_wrapper import EpicsPV
+
+class MultiActuator(AbstractActuator):
+    """
+    A composite actuator that lets you jog N child actuators in one call.
+    """
+    def __init__(self, actuators: Sequence[AbstractActuator], config: ActuatorConfig):
+        super().__init__(config)
+        self._axes = list(actuators)
+
+    @property
+    def pvname(self) -> Sequence[str]:
+        return [ax.pvname for ax in self._axes]
+
+    @property
+    def rbv(self) -> Sequence[Any]:
+        return [ax.rbv for ax in self._axes]
+
+    @rbv.setter
+    def rbv(self, values: Sequence[Any]) -> None:
+        if len(values) != len(self._axes):
+            raise ValueError(f"Expected {len(self._axes)} values, got {len(values)}")
+        for ax, v in zip(self._axes, values):
+            ax.rbv = v
+
+    @property
+    def cmdv(self) -> Sequence[Any]:
+        return [ax.cmdv for ax in self._axes]
+
+    @cmdv.setter
+    def cmdv(self, values: Sequence[Any]) -> None:
+        if len(values) != len(self._axes):
+            raise ValueError(f"Expected {len(self._axes)} values, got {len(values)}")
+        for ax, v in zip(self._axes, values):
+            ax.cmdv = v
+
+    # Implemented abstract methods:
+    def set_velocity(self, velocities: Sequence[float]) -> None:
+        if len(velocities) != len(self._axes):
+            raise ValueError(f"Need {len(self._axes)} velocities, got {len(velocities)}")
+        for ax, v in zip(self._axes, velocities):
+            ax.set_velocity(v)
+
+    def get_velocity(self) -> Sequence[Optional[float]]:
+        return [ax.get_velocity() for ax in self._axes]
+
+    def move(self, positions: Sequence[float]) -> None:
+        # non-blocking multi-axis move
+        self.run_move(positions, sync=False)
+
+    def rel_move(self, deltas: Sequence[float]) -> None:
+        """Non-blocking multi-axis relative move."""
+        self.run_rel_move(deltas, sync=False)
+
+    def run_move(self, positions: Sequence[float], sync: bool = True) -> None:
+        if len(positions) != len(self._axes):
+            raise ValueError(f"Expected {len(self._axes)} positions, got {len(positions)}")
+        # issue each child move without blocking
+        for ax, pos in zip(self._axes, positions):
+            ax.run_move(pos, sync=False)
+        if sync:
+            # wait until all axes are ready
+            while not self.is_ready():
+                time.sleep(0.01)
+
+    def run_rel_move(self, deltas: Sequence[float], sync: bool = True) -> None:
+        if len(deltas) != len(self._axes):
+            raise ValueError(f"Expected {len(self._axes)} deltas, got {len(deltas)}")
+        # issue each child relative move without blocking
+        for ax, d in zip(self._axes, deltas):
+            ax.run_rel_move(float(d), sync=False)
+        if sync:
+            while not self.is_ready():
+                time.sleep(0.01)
+
+    def jog(self, velocities: Sequence[float], sync: bool = True) -> None:
+        if len(velocities) != len(self._axes):
+            raise ValueError(f"Need {len(self._axes)} velocities, got {len(velocities)}")
+        for ax, v in zip(self._axes, velocities):
+            ax.jog(v, sync=False)
+        if sync:
+            while not self.is_ready():
+                time.sleep(0.01)
+
+    def stop(self) -> None:
+        for ax in self._axes:
+            ax.stop()
+
+    def is_ready(self) -> bool:
+        # wait for all single actuator conditions
+        return all(ax.is_ready() for ax in self._axes)
+
+    def is_in_position(self, targets: Sequence[float], in_position_band: Optional[float] = None) -> bool:
+        band = in_position_band if in_position_band is not None else self.in_position_band
+        return all(ax.is_in_position(t, band) for ax, t in zip(self._axes, targets))
+
+    def wait_until_done(self, positions: Optional[Sequence[float]] = None) -> None:
+        # wait until all axes have stopped, single actuators provide in position band etc.
+        while not self.is_ready():
+            time.sleep(0.01)
+

kiwi_scan/actuator/single.py

@@ -0,0 +1,216 @@
+# SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional, Any, Callable, Dict, Mapping
+import threading
+import time
+import logging
+
+from kiwi_scan.datamodels import ActuatorConfig
+
+
+@dataclass(frozen=True)
+class PvEvent:
+    """
+    Representation of one PV update.
+    This decouples from the raw pyepics callback kwargs.
+    """
+    pvname: str
+    value: Any
+    source: Optional[str] = None
+
+    # Time
+    timestamp: Optional[float] = None   # seconds since epoch (float)
+    posixseconds: Optional[int] = None
+    nanoseconds: Optional[int] = None
+
+    # Alarm / status
+    severity: Optional[int] = None
+    status: Optional[int] = None
+    
+    # Anything else provided by the backend
+    raw: Mapping[str, Any] = None
+
+
+MonitorCallback = Callable[[PvEvent], None]
+
+
+class AbstractActuator(ABC):
+    """
+    Defines the interface for an actuator.
+    """
+
+    def __init__(self, config: ActuatorConfig):
+        self.config = config
+        # Expose common config parameters
+        self.backlash: float = config.backlash
+        self.in_position_band: float = config.in_position_band
+        self.dwell_time: float = config.dwell_time
+        self.ready_value: Any = config.ready_value
+        self.startup_timeout: float = config.startup_timeout
+        self.q_delay: float = config.queueing_delay
+
+        # --- Monitoring  -----------------------
+        self._monitors: Dict[str, Any] = {}                 # pvname -> backend monitor object (e.g. EpicsPV)
+        self._monitor_callbacks: Dict[str, list[MonitorCallback]] = {}
+        self._last_events: Dict[str, PvEvent] = {}
+        self._monitor_lock = threading.RLock()
+
+    # --------------------- monitor/event helpers ----------------------------
+
+    def supports_monitors(self) -> bool:
+        """Override in backends that can subscribe to PV updates (e.g. EPICS)."""
+        return False
+
+    def add_monitor(self, pvname: str, user_callback: Optional[MonitorCallback] = None, **kwargs) -> Any:
+        """
+        Subscribe to PV updates. Concrete backends (EpicsActuator) should override.
+        Returns a backend-specific monitor handle/object (e.g. EpicsPV).
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support PV monitors")
+
+    def remove_monitor(self, pvname: str) -> None:
+        """
+        Remove/close a monitor subscription for pvname if supported by backend.
+        Concrete backends should override if they can actually clear CA subscriptions.
+        """
+        with self._monitor_lock:
+            self._monitors.pop(pvname, None)
+            self._monitor_callbacks.pop(pvname, None)
+            self._last_events.pop(pvname, None)
+
+    def clear_monitors(self) -> None:
+        """Remove all monitors."""
+        with self._monitor_lock:
+            pvs = list(self._monitors.keys())
+        for pv in pvs:
+            self.remove_monitor(pv)
+
+    def on_pv_event(self, pvname: str, cb: MonitorCallback) -> None:
+        """Register an additional listener for pvname (even if monitor already exists)."""
+        with self._monitor_lock:
+            self._monitor_callbacks.setdefault(pvname, []).append(cb)
+
+    def get_last_event(self, pvname: str) -> Optional[PvEvent]:
+        with self._monitor_lock:
+            return self._last_events.get(pvname)
+
+    def _dispatch_pv_update(self, pvname: str, value: Any, **kw: Any) -> PvEvent:
+        """
+        Backend-facing entry point: call this from EPICS callbacks.
+        Stores last event and notifies listeners.
+        """
+        ev = PvEvent(
+            pvname=pvname,
+            value=value,
+            timestamp=kw.get("timestamp", None),
+            posixseconds=kw.get("posixseconds", None),
+            nanoseconds=kw.get("nanoseconds", None),
+            severity=kw.get("severity", None),
+            status=kw.get("status", None),
+            source=kw.get("source", None),
+            raw=dict(kw) if kw else {},
+        )
+
+        with self._monitor_lock:
+            self._last_events[pvname] = ev
+            listeners = list(self._monitor_callbacks.get(pvname, []))
+
+        # Call listeners outside the lock
+        for cb in listeners:
+            try:
+                cb(ev)
+            except Exception:
+                # Keep it non-fatal: monitor callbacks must never kill control logic
+                logging.exception(f"Monitor callback failed for {pvname}")
+
+        return ev
+    @property
+    @abstractmethod
+    def pvname(self) -> str:
+        """The primary PV name for the actuator."""
+        pass
+
+    @property
+    @abstractmethod
+    def rbv(self) -> Optional[Any]:
+        """Read-back value shortcut property."""
+        pass
+
+    @rbv.setter
+    @abstractmethod
+    def rbv(self, value: Any) -> None:
+        """Read-back value shortcut property setter."""
+        pass
+
+    @property
+    @abstractmethod
+    def cmdv(self) -> Optional[Any]:
+        """Commanded value shortcut property."""
+        pass
+
+    @cmdv.setter
+    @abstractmethod
+    def cmdv(self, value: Any) -> None:
+        """Commanded value shortcut property setter."""
+        pass
+
+    @abstractmethod
+    def set_velocity(self, velocity: float) -> None:
+        """Set the actuator velocity (for move and jog)."""
+        pass
+
+    @abstractmethod
+    def get_velocity(self) -> Optional[float]:
+        """Get the current actuator velocity."""
+        pass
+
+    @abstractmethod
+    def move(self, position: float) -> None:
+        """Issue a move command without waiting."""
+        pass
+
+    @abstractmethod
+    def rel_move(self, delta: float) -> None:
+        """Issue a *relative* move command without waiting (incremental move)."""
+        pass
+
+    @abstractmethod
+    def run_move(self, position: float, sync: bool = True) -> None:
+        """Move the actuator, optionally waiting until completion."""
+        pass
+
+    @abstractmethod
+    def run_rel_move(self, delta: float, sync: bool = True) -> None:
+        """Relative move, optionally waiting until completion."""
+        pass
+
+    @abstractmethod
+    def jog(self, velocity: float, sync: bool = True) -> None:
+        """Continuous jog at given velocity."""
+        pass
+
+    @abstractmethod
+    def is_ready(self) -> bool:
+        """Return True if actuator is ready (not is_movingy())."""
+        pass
+    
+    def is_moving(self) -> bool:
+        return not self.is_ready()
+
+    @abstractmethod
+    def is_in_position(self, target: float, in_position_band: float) -> bool:
+        """Check if readback is within band of target."""
+        pass
+
+    @abstractmethod
+    def wait_until_done(self, position: float) -> None:
+        """Block until actuator has reached target."""
+        pass
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop motion immediately."""
+        pass