apsbits 1.0.0__py3-none-any.whl

apsbits/utils/make_devices.py

@@ -0,0 +1,162 @@
+"""
+Make devices from YAML files
+=============================
+
+Construct ophyd-style devices from simple specifications in YAML files.
+
+.. autosummary::
+    :nosignatures:
+
+    ~make_devices
+    ~Instrument
+"""
+
+import logging
+import pathlib
+import sys
+import time
+
+import guarneri
+from apstools.plans import run_blocking_function
+from apstools.utils import dynamic_import
+from bluesky import plan_stubs as bps
+
+from apsbits.utils.aps_functions import host_on_aps_subnet
+from apsbits.utils.config_loaders import get_config
+from apsbits.utils.config_loaders import load_config_yaml
+from apsbits.utils.controls_setup import oregistry  # noqa: F401
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def make_devices(*, pause: float = 1):
+    """
+    (plan stub) Create the ophyd-style controls for this instrument.
+
+    Feel free to modify this plan to suit the needs of your instrument.
+
+    EXAMPLE::
+
+        RE(make_devices())
+
+    PARAMETERS
+
+    pause : float
+        Wait 'pause' seconds (default: 1) for slow objects to connect.
+
+    """
+
+    logger.debug("(Re)Loading local control objects.")
+
+    iconfig = get_config()
+
+    instrument_path = pathlib.Path(iconfig.get("INSTRUMENT_PATH")).parent
+    configs_path = instrument_path / "configs"
+
+    # Get device files and ensure it's a list
+    device_files = iconfig.get("DEVICES_FILES", [])
+    if isinstance(device_files, str):
+        device_files = [device_files]
+    logger.debug("Loading device files: %r", device_files)
+
+    # Load each device file
+    for device_file in device_files:
+        device_path = configs_path / device_file
+        if not device_path.exists():
+            logger.error(f"Device file not found: {device_path}")
+            continue
+        logger.info(f"Loading device file: {device_path}")
+        try:
+            yield from run_blocking_function(_loader, device_path, main=True)
+        except Exception as e:
+            logger.error(f"Error loading device file {device_path}: {str(e)}")
+            continue
+
+    # Handle APS-specific device files if on APS subnet
+    aps_control_devices_files = iconfig.get("APS_DEVICES_FILES", [])
+    if isinstance(aps_control_devices_files, str):
+        aps_control_devices_files = [aps_control_devices_files]
+
+    if aps_control_devices_files and host_on_aps_subnet():
+        for device_file in aps_control_devices_files:
+            device_path = configs_path / device_file
+            if not device_path.exists():
+                logger.error(f"APS device file not found: {device_path}")
+                continue
+            logger.info(f"Loading APS device file: {device_path}")
+            try:
+                yield from run_blocking_function(_loader, device_path, main=True)
+            except Exception as e:
+                logger.error(f"Error loading APS device file {device_path}: {str(e)}")
+                continue
+
+    if pause > 0:
+        logger.debug(
+            "Waiting %s seconds for slow objects to connect.",
+            pause,
+        )
+        yield from bps.sleep(pause)
+
+    # Configure any of the controls here, or in plan stubs
+
+
+def _loader(yaml_device_file, main=True):
+    """
+    Load our ophyd-style controls as described in a YAML file.
+
+    PARAMETERS
+
+    yaml_device_file : str or pathlib.Path
+        YAML file describing ophyd-style controls to be created.
+    main : bool
+        If ``True`` add these devices to the ``__main__`` namespace.
+
+    """
+    logger.debug("Devices file %r.", str(yaml_device_file))
+    t0 = time.time()
+    _instr.load(yaml_device_file)
+    logger.info("Devices loaded in %.3f s.", time.time() - t0)
+
+    if main:
+        main_namespace = sys.modules["__main__"]
+        for label in oregistry.device_names:
+            logger.info(f"Setting up {label} in main namespace")
+            setattr(main_namespace, label, oregistry[label])
+
+
+class Instrument(guarneri.Instrument):
+    """Custom YAML loader for guarneri."""
+
+    def parse_yaml_file(self, config_file: pathlib.Path | str) -> list[dict]:
+        """Read device configurations from YAML format file."""
+        if isinstance(config_file, str):
+            config_file = pathlib.Path(config_file)
+
+        def parser(creator, specs):
+            if creator not in self.device_classes:
+                self.device_classes[creator] = dynamic_import(creator)
+            entries = [
+                {
+                    "device_class": creator,
+                    "args": (),  # ALL specs are kwargs!
+                    "kwargs": table,
+                }
+                for table in specs
+            ]
+            return entries
+
+        with open(config_file, "r") as f:
+            config_data = load_config_yaml(f)
+
+            devices = [
+                device
+                # parse the file using already loaded config data
+                for k, v in config_data.items()
+                # each support type (class, factory, function, ...)
+                for device in parser(k, v)
+            ]
+        return devices
+
+
+_instr = Instrument({}, registry=oregistry)  # singleton

apsbits/utils/metadata.py

@@ -0,0 +1,96 @@
+"""
+RunEngine Metadata
+==================
+
+.. autosummary::
+    ~MD_PATH
+    ~get_md_path
+    ~re_metadata
+"""
+
+import getpass
+import logging
+import os
+import pathlib
+import socket
+import sys
+
+import apstools
+import bluesky
+import databroker
+import epics
+import h5py
+import intake
+import matplotlib
+import numpy
+import ophyd
+import pyRestTable
+import pysumreg
+import spec2nexus
+
+import apsbits
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+DEFAULT_MD_PATH = pathlib.Path.home() / ".config" / "Bluesky_RunEngine_md"
+HOSTNAME = socket.gethostname() or "localhost"
+USERNAME = getpass.getuser() or "Bluesky user"
+VERSIONS = dict(
+    apstools=apstools.__version__,
+    bluesky=bluesky.__version__,
+    databroker=databroker.__version__,
+    epics=epics.__version__,
+    h5py=h5py.__version__,
+    intake=intake.__version__,
+    matplotlib=matplotlib.__version__,
+    numpy=numpy.__version__,
+    ophyd=ophyd.__version__,
+    pyRestTable=pyRestTable.__version__,
+    python=sys.version.split(" ")[0],
+    pysumreg=pysumreg.__version__,
+    spec2nexus=spec2nexus.__version__,
+    apsbits=apsbits.__version__,
+)
+
+
+def get_md_path(iconfig=None):
+    """
+    Get path for RE metadata.
+
+    ==============  ==============================================
+    support         path
+    ==============  ==============================================
+    PersistentDict  Directory where dictionary keys are stored in separate files.
+    StoredDict      File where dictionary is stored as YAML.
+    ==============  ==============================================
+
+    In either case, the 'path' can be relative or absolute.  Relative
+    paths are with respect to the present working directory when the
+    bluesky session is started.
+    """
+    RE_CONFIG = iconfig.get("RUN_ENGINE", {})
+    md_path_name = RE_CONFIG.get("MD_PATH", DEFAULT_MD_PATH)
+    path = pathlib.Path(md_path_name)
+    logger.info("RunEngine metadata saved in directory: %s", str(path))
+    return str(path)
+
+
+def re_metadata(iconfig=None, cat=None):
+    """Programmatic metadata for the RunEngine."""
+    md = {
+        "login_id": f"{USERNAME}@{HOSTNAME}",
+        "versions": VERSIONS,
+        "pid": os.getpid(),
+        "iconfig": iconfig,
+    }
+    if cat is not None:
+        md["databroker_catalog"] = cat.name
+    RE_CONFIG = iconfig.get("RUN_ENGINE", {})
+    md.update(RE_CONFIG.get("DEFAULT_METADATA", {}))
+
+    conda_prefix = os.environ.get("CONDA_PREFIX")
+    if conda_prefix is not None:
+        md["conda_prefix"] = conda_prefix
+    return md

apsbits/utils/sim_creator.py

@@ -0,0 +1,202 @@
+"""
+Device factories
+================
+
+Device factories are used to:
+
+* *Create* several similar ophyd-style devices (such as ``ophyd.Device``
+  or ``ophyd.Signal``) that fit a pattern.
+
+* *Import* a device which is pre-defined in a module, such as the
+  ophyd simulators in ``ophyd.sim``.
+
+.. autosummary::
+
+    ~factory_base
+    ~motors
+    ~predefined_device
+"""
+
+import logging
+
+from apstools.utils import dynamic_import
+
+from apsbits.utils.controls_setup import oregistry
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def predefined_device(*, name="", creator=""):
+    """
+    Provide a predefined device such as from the 'ophyd.sim' module.
+
+    PARAMETERS
+
+    creator : str
+        Name of the predefined device to be used
+    name : str
+        Simulator will be assigned this name.  (default: use existing name)
+
+    Example entry in `devices.yml` file:
+
+    .. code-block:: yaml
+        :linenos:
+
+        instrument.devices.factories.predefined_device:
+          - {creator: ophyd.sim.motor, name: sim_motor}
+          - {creator: ophyd.sim.noisy_det, name: sim_det}
+    """
+    if creator == "":
+        raise ValueError("Must provide a value for 'creator'.")
+    device = dynamic_import(creator)
+    if name != "":
+        device.name = name
+    logger.debug(device)
+    oregistry.register(device)
+    yield device
+
+
+def factory_base(
+    *,
+    prefix=None,
+    names="object{}",
+    first=0,
+    last=0,
+    creator="ophyd.Signal",
+    **kwargs,
+):
+    """
+    Make one or more objects using  'creator'.
+
+    PARAMETERS
+
+    prefix : str
+        Prefix *pattern* for the EPICS PVs (default: ``None``).
+
+    names : str
+        Name *pattern* for the objects.  The default pattern is ``"object{}"`` which
+        produces devices named ``object1, object2, ..., ```.  If a formatting
+        specification (``{}``) is not provided, it is appended.  Each object
+        will be named using this code: ``names.format(number)``, such as::
+
+            In [23]: "object{}".format(22)
+            Out[23]: 'object22'
+
+    first : int
+        The first object number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    last : int
+        The first object number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    creator : str
+        Name of the *creator* code that will be used to construct each device.
+        (default: ``"ophyd.Signal"``)
+
+    kwargs : dict
+        Dictionary of additional keyword arguments.  This is included
+        when creating each object.
+    """
+    if "{" not in names:
+        names += "{}"
+    if prefix is not None and "{" not in prefix:
+        prefix += "{}"
+
+    klass = dynamic_import(creator)
+
+    first, last = sorted([first, last])
+    for i in range(first, 1 + last):
+        keywords = {"name": names.format(i)}
+        if prefix is not None:
+            keywords["prefix"] = prefix.format(i)
+        keywords.update(kwargs)
+        device = klass(**keywords)
+        logger.debug(device)
+        yield device
+
+
+def motors(
+    *,
+    prefix=None,
+    names="m{}",
+    first=0,
+    last=0,
+    **kwargs,
+):
+    """
+    Make one or more '``ophyd.EpicsMotor``' objects.
+
+    Example entry in `devices.yml` file:
+
+    .. code-block:: yaml
+        :linenos:
+
+        instrument.devices.factories.motors:
+          - {prefix: "ioc:m", first: 1, last: 4, labels: ["motor"]}
+          # skip m5 & m6
+          - {prefix: "ioc:m", first: 7, last: 22, labels: ["motor"]}
+
+    Uses this pattern:
+
+    .. code-block:: py
+        :linenos:
+
+        ophyd.EpicsMotor(
+                prefix=prefix.format(i),
+                name=names.format(i),
+                **kwargs,
+            )
+
+    where ``i`` iterates from 'first' through 'last' (inclusive).
+
+    PARAMETERS
+
+    prefix : str
+        Name *pattern* for the EPICS PVs.  There is no default pattern. If a
+        formatting specification (``{}``) is not  provided, it is appended (as
+        with other ophyd devices).  Each motor will be configured with this
+        prefix: ``prefix.format(number)``, such as::
+
+            In [23]: "ioc:m{}".format(22)
+            Out[23]: 'ioc:m22'
+
+    names : str
+        Name *pattern* for the motors.  The default pattern is ``"m{}"`` which
+        produces motors named ``m1, m2, ..., m22, m23, ...```.  If a formatting
+        specification (``{}``) is not provided, it is appended.  Each motor
+        will be named using this code: ``names.format(number)``, such as::
+
+            In [23]: "m{}".format(22)
+            Out[23]: 'm22'
+
+    first : int
+        The first motor number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    last : int
+        The first motor number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    kwargs : dict
+        Dictionary of additional keyword arguments.  This is included
+        with each EpicsMotor object.
+    """
+    if prefix is None:
+        raise ValueError("Must define a string value for 'prefix'.")
+
+    kwargs["names"] = names or "m{}"
+    kwargs["prefix"] = prefix
+    kwargs.update(
+        {
+            "prefix": prefix,
+            "names": names or "m{}",
+            "first": first,
+            "last": last,
+            "creator": "ophyd.EpicsMotor",
+        }
+    )
+
+    for motor in factory_base(**kwargs):
+        yield motor

apsbits/utils/stored_dict.py

@@ -0,0 +1,174 @@
+"""
+Storage-backed Dictionary
+=========================
+A dictionary that writes its contents to YAML file.
+Replaces ``bluesky.utils.PersistentDict``.
+* Contents must be JSON serializable.
+* Contents stored in a single human-readable YAML file.
+* Sync to disk shortly after dictionary is updated.
+.. autosummary::
+    ~StoredDict
+"""
+
+__all__ = ["StoredDict"]
+
+import collections.abc
+import datetime
+import inspect
+import json
+import logging
+import pathlib
+import threading
+import time
+
+import yaml
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+class StoredDict(collections.abc.MutableMapping):
+    """
+    Dictionary that syncs to storage.
+    .. autosummary::
+        ~flush
+        ~popitem
+        ~reload
+    .. rubric:: Static methods
+    All support for the YAML format is implemented in the static methods.
+    .. autosummary::
+        ~dump
+        ~load
+    ----
+    """
+
+    def __init__(self, file, delay=5, title=None, serializable=True):
+        """
+        StoredDict : Dictionary that syncs to storage
+        PARAMETERS
+        file : str or pathlib.Path
+            Name of file to store dictionary contents.
+        delay : number
+            Time delay (s) since last dictionary update to write to storage.
+            Default: 5 seconds.
+        title : str or None
+            Comment to write at top of file.
+            Default: "Written by StoredDict."
+        serializable : bool
+            If True, validate new dictionary entries are JSON serializable.
+        """
+        self._file = pathlib.Path(file)
+        self._delay = max(0, delay)
+        self._title = title or f"Written by {self.__class__.__name__}."
+        self.test_serializable = serializable
+        self.sync_in_progress = False
+        self._sync_deadline = time.time()
+        self._sync_key = f"sync_agent_{id(self):x}"
+        self._sync_loop_period = 0.005
+
+        self._cache = {}
+        self.reload()
+
+    def __delitem__(self, key):
+        """Delete dictionary value by key."""
+        del self._cache[key]
+
+    def __getitem__(self, key):
+        """Get dictionary value by key."""
+        return self._cache[key]
+
+    def __iter__(self):
+        """Iterate over the dictionary keys."""
+        yield from self._cache
+
+    def __len__(self):
+        """Number of keys in the dictionary."""
+        return len(self._cache)
+
+    def __repr__(self):
+        """representation of this object."""
+        return f"<{self.__class__.__name__} {dict(self)!r}>"
+
+    def __setitem__(self, key, value):
+        """Write to the dictionary."""
+        outermost_frame = inspect.getouterframes(inspect.currentframe())[-1]
+        if "sphinx-build" in outermost_frame.filename:
+            # Seems that Sphinx is building the documentation.
+            # Ignore all the objects it tries to add.
+            return
+
+        if self.test_serializable:
+            json.dumps({key: value})
+        self._cache[key] = value  # Store the new (or revised) content.
+
+        # Reset the deadline.
+        self._sync_deadline = time.time() + self._delay
+        logger.debug("new sync deadline in %f s.", self._delay)
+        if not self.sync_in_progress:
+            # Start the sync_agent (thread).
+            self._delayed_sync_to_storage()
+
+    def _delayed_sync_to_storage(self):
+        """
+        Sync the metadata to storage.
+        Start a time-delay thread.  New writes to the metadata dictionary will
+        extend the deadline.  Sync once the deadline is reached.
+        """
+
+        def sync_agent():
+            """Threaded task."""
+            logger.debug("Starting sync_agent...")
+            self.sync_in_progress = True
+            while time.time() < self._sync_deadline:
+                time.sleep(self._sync_loop_period)
+            logger.debug("Sync waiting period ended")
+            self.sync_in_progress = False
+
+            StoredDict.dump(self._file, self._cache, title=self._title)
+
+        thred = threading.Thread(target=sync_agent)
+        thred.start()
+
+    def flush(self):
+        """Force a write of the dictionary to disk"""
+        logger.debug("flush()")
+        if not self.sync_in_progress:
+            StoredDict.dump(self._file, self._cache, title=self._title)
+        self._sync_deadline = time.time()
+        self.sync_in_progress = False
+
+    def popitem(self):
+        """
+        Remove and return a (key, value) pair as a 2-tuple.
+
+        Pairs are returned in LIFO (last-in, first-out) order.
+        Raises KeyError if the dict is empty.
+        """
+        return self._cache.popitem()
+
+    def reload(self):
+        """Read dictionary from storage."""
+        logger.debug("reload()")
+        self._cache = StoredDict.load(self._file)
+
+    @staticmethod
+    def dump(file, contents, title=None):
+        """Write dictionary to YAML file."""
+        logger.debug("_dump(): file='%s', contents=%r, title=%r", file, contents, title)
+        with open(file, "w") as f:
+            if isinstance(title, str) and len(title) > 0:
+                f.write(f"# {title}\n")
+            f.write(f"# Dictionary contents written: {datetime.datetime.now()}\n\n")
+            f.write(yaml.dump(contents, indent=2))
+
+    @staticmethod
+    def load(file):
+        """Read dictionary from YAML file."""
+        from .config_loaders import load_config_yaml
+
+        file = pathlib.Path(file)
+        logger.debug("_load('%s')", file)
+        md = None
+        if file.exists():
+            md = load_config_yaml(file)
+        return md or {}  # In case file is empty.