apsbits 1.0.0__py3-none-any.whl

apsbits/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: iso-8859-1 -*-
+
+"""Model Bluesky Data Acquisition Instrument."""
+
+from apsbits.utils.logging_setup import configure_logging
+
+configure_logging()
+
+__package__ = "apsbits"
+try:
+    from setuptools_scm import get_version
+
+    __version__ = get_version(root="..", relative_to=__file__)
+    del get_version
+except (LookupError, ModuleNotFoundError):
+    from importlib.metadata import version
+
+    __version__ = version(__package__)

apsbits/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)

apsbits/core/__init__.py

@@ -0,0 +1,11 @@
+"""
+Utility support to start bluesky sessions.
+
+Also contains setup code that MUST run before other code in this directory.
+"""
+
+from apsbits.utils.helper_functions import debug_python
+from apsbits.utils.helper_functions import mpl_setup
+
+debug_python()
+mpl_setup()

apsbits/core/best_effort_init.py

@@ -0,0 +1,51 @@
+"""
+BestEffortCallback: simple real-time visualizations, provides ``bec``.
+======================================================================
+
+.. autosummary::
+    ~init_bec_peaks
+"""
+
+import logging
+
+from bluesky.callbacks.best_effort import BestEffortCallback
+
+from apsbits.utils.helper_functions import running_in_queueserver
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def init_bec_peaks(iconfig):
+    """
+    Create and configure a BestEffortCallback object based on the provided iconfig.
+
+    Parameters:
+        iconfig (dict): Configuration dictionary.
+
+    Returns:
+        tuple: A tuple containing the configured BestEffortCallback object (bec)
+               and its peaks dictionary.
+    """
+
+    bec = BestEffortCallback()
+    """BestEffortCallback object, creates live tables and plots."""
+
+    bec_config = iconfig.get("BEC", {})
+
+    if not bec_config.get("BASELINE", True):
+        bec.disable_baseline()
+
+    if not bec_config.get("HEADING", True):
+        bec.disable_heading()
+
+    if not bec_config.get("PLOTS", True) or running_in_queueserver():
+        bec.disable_plots()
+
+    if not bec_config.get("TABLE", True):
+        bec.disable_table()
+
+    peaks = bec.peaks
+    """Dictionary with statistical analysis of LivePlots."""
+
+    return bec, peaks

apsbits/core/catalog_init.py

@@ -0,0 +1,36 @@
+"""
+Databroker catalog, provides ``cat``
+====================================
+
+.. autosummary::
+    ~cat
+"""
+
+import logging
+
+import databroker
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+TEMPORARY_CATALOG_NAME = "temporalcat"
+
+
+def init_catalog(iconfig):
+    """
+    Initialize the Databroker catalog using the provided iconfig.
+
+    Parameters:
+        iconfig: Configuration object to retrieve catalog name.
+
+    Returns:
+        Databroker catalog object.
+    """
+    catalog_name = iconfig.get("DATABROKER_CATALOG", TEMPORARY_CATALOG_NAME)
+    try:
+        _cat = databroker.catalog[catalog_name].v2
+    except KeyError:
+        _cat = databroker.temp().v2
+
+    logger.info("Databroker catalog name: %s", _cat.name)
+    return _cat

apsbits/core/run_engine_init.py

@@ -0,0 +1,118 @@
+"""
+Setup the Bluesky RunEngine, provides ``RE`` and ``sd``.
+========================================================
+
+.. autosummary::
+    ~init_RE
+"""
+
+import logging
+
+import bluesky
+from bluesky.utils import ProgressBarManager
+
+from apsbits.utils.controls_setup import connect_scan_id_pv
+from apsbits.utils.controls_setup import set_control_layer
+from apsbits.utils.controls_setup import set_timeouts
+from apsbits.utils.metadata import get_md_path
+from apsbits.utils.metadata import re_metadata
+from apsbits.utils.stored_dict import StoredDict
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def init_RE(iconfig, bec_instance=None, cat_instance=None):
+    """
+    Initialize and configure a bluesky RunEngine (RE) instance.
+
+    This function sets up the RunEngine with metadata storage, subscriptions,
+    preprocessors, and other configurations based on the provided input
+    parameters and configuration dictionary.
+
+    Args:
+        iconfig (dict): Configuration dictionary containing settings for the
+            RunEngine. Expected keys include:
+            - "RUN_ENGINE": A dictionary with RunEngine-specific settings.
+            - "MD_STORAGE_HANDLER": (Optional) The handler for metadata storage
+              (default is "StoredDict").
+            - "DEFAULT_METADATA": (Optional) Default metadata to be added to
+              the RunEngine.
+            - "USE_PROGRESS_BAR": (Optional) Boolean to enable/disable the
+              progress bar (default is True).
+        bec_instance (object, optional): An instance of BestEffortCallback (BEC)
+            for subscribing to the RunEngine. Defaults to `bec`.
+        cat_instance (object, optional): An instance of a databroker catalog
+            for subscribing to the RunEngine. Defaults to `cat`.
+
+    Returns:
+        tuple: A tuple containing the configured RunEngine instance and the
+               SupplementalData instance.
+
+    Raises:
+        Exception: If there is an error creating the metadata storage handler.
+
+    Notes:
+        - The function ensures that the RE.md dictionary is saved/restored
+          using the specified metadata storage handler.
+        - Subscriptions to the catalog and BEC are added if the respective
+          instances are provided.
+        - Additional configurations such as control layer setup, timeouts,
+          and progress bar are applied.
+    """
+    re_config = iconfig.get("RUN_ENGINE", {})
+
+    RE = bluesky.RunEngine()
+    """The bluesky RunEngine object."""
+
+    MD_PATH = get_md_path(iconfig)
+    # Save/restore RE.md dictionary, in this precise order.
+    if MD_PATH is not None:
+        handler_name = re_config.get("MD_STORAGE_HANDLER", "StoredDict")
+        logger.debug(
+            "Select %r to store 'RE.md' dictionary in %s.",
+            handler_name,
+            MD_PATH,
+        )
+        try:
+            if handler_name == "PersistentDict":
+                RE.md = bluesky.utils.PersistentDict(MD_PATH)
+            else:
+                RE.md = StoredDict(MD_PATH)
+        except Exception as error:
+            print(
+                "\n"
+                f"Could not create {handler_name} for RE metadata. Continuing"
+                f" without saving metadata to disk. {error=}\n"
+            )
+            logger.warning("%s('%s') error:%s", handler_name, MD_PATH, error)
+
+    if cat_instance is not None:
+        RE.md.update(re_metadata(iconfig, cat_instance))  # programmatic metadata
+        RE.md.update(re_config.get("DEFAULT_METADATA", {}))
+
+    sd = bluesky.SupplementalData()
+    """Baselines & monitors for ``RE``."""
+
+    if cat_instance is not None:
+        RE.subscribe(cat_instance.v1.insert)
+    if bec_instance is not None:
+        RE.subscribe(bec_instance)
+    RE.preprocessors.append(sd)
+
+    set_control_layer(
+        control_layer=iconfig.get("OPHYD", {}).get("CONTROL_LAYER", "PyEpics")
+    )
+    # MUST happen before ANY EpicsSignalBase (or subclass) is created.
+    set_timeouts(timeouts=iconfig.get("OPHYD", {}).get("TIMEOUTS", {}))
+    connect_scan_id_pv(
+        RE,
+        scan_id_pv=iconfig.get("RUN_ENGINE", {}).get("SCAN_ID_PV"),
+    )  # need to add the variables I removed from iconfig here as args
+
+    if re_config.get("USE_PROGRESS_BAR", True):
+        # Add a progress bar.
+        pbar_manager = ProgressBarManager()
+        RE.waiting_hook = pbar_manager
+
+    return RE, sd

apsbits/demo_instrument/README.md

@@ -0,0 +1 @@
+## Demo Instrument

apsbits/demo_instrument/__init__.py

@@ -0,0 +1,22 @@
+"""
+Demo instrument package.
+
+This package provides a demo instrument implementation for testing and development.
+"""
+
+import logging
+from pathlib import Path
+
+from apsbits.utils.config_loaders import load_config
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+# Get the path to the instrument package
+instrument_path = Path(__file__).parent
+
+# Load configuration
+iconfig_path = instrument_path / "configs" / "iconfig.yml"
+load_config(iconfig_path)
+
+logger.info("Starting Instrument with iconfig: %s", iconfig_path)

apsbits/demo_instrument/callbacks/__init__.py

@@ -0,0 +1 @@
+"""RunEngine callbacks, mostly."""

apsbits/demo_instrument/callbacks/nexus_data_file_writer.py

@@ -0,0 +1,58 @@
+"""
+Nexus data file writer callback.
+
+This module provides callbacks for writing data to Nexus data files.
+"""
+
+import logging
+
+from apsbits.utils.aps_functions import host_on_aps_subnet
+from apsbits.utils.config_loaders import get_config
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+# Get the configuration
+iconfig = get_config()
+
+
+if host_on_aps_subnet():
+    from apstools.callbacks import NXWriterAPS as NXWriter
+else:
+    from apstools.callbacks import NXWriter
+
+
+class MyNXWriter(NXWriter):
+    """Patch to get sample title from metadata, if available."""
+
+    def get_sample_title(self):
+        """
+        Get the title from the metadata or modify the default.
+
+        default title: S{scan_id}-{plan_name}-{short_uid}
+        """
+        try:
+            title = self.metadata["title"]
+        except KeyError:
+            # title = super().get_sample_title()  # the default title
+            title = f"S{self.scan_id:05d}-{self.plan_name}-{self.uid[:7]}"
+        return title
+
+
+def nxwriter_init(RE):
+    """Initialize the Nexus data file writer callback."""
+    nxwriter = MyNXWriter()  # create the callback instance
+    """The NeXus file writer object."""
+
+    if iconfig.get("NEXUS_DATA_FILES", {}).get("ENABLE", False):
+        RE.subscribe(nxwriter.receiver)  # write data to NeXus files
+
+    nxwriter.file_extension = iconfig.get("NEXUS_DATA_FILES", {}).get(
+        "FILE_EXTENSION", "hdf"
+    )
+
+    print(nxwriter.file_extension)
+    warn_missing = iconfig.get("NEXUS_DATA_FILES", {}).get("WARN_MISSING", False)
+    nxwriter.warn_on_missing_content = warn_missing
+
+    return nxwriter

apsbits/demo_instrument/callbacks/spec_data_file_writer.py

@@ -0,0 +1,97 @@
+"""
+custom callbacks
+================
+
+.. autosummary::
+    :nosignatures:
+
+    ~newSpecFile
+    ~spec_comment
+    ~specwriter
+"""
+
+import datetime
+import logging
+import pathlib
+
+import apstools.callbacks
+import apstools.utils
+
+from apsbits.utils.config_loaders import get_config
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+iconfig = get_config()
+file_extension = iconfig.get("SPEC_DATA_FILES", {}).get("FILE_EXTENSION", "dat")
+
+
+def spec_comment(comment, doc=None):
+    """Make it easy for user to add comments to the data file."""
+    apstools.callbacks.spec_comment(comment, doc, specwriter)
+
+
+def newSpecFile(title, scan_id=None, RE=None):
+    """
+    User choice of the SPEC file name.
+
+    Cleans up title, prepends month and day and appends file extension.
+    If ``RE`` is passed, then resets ``RE.md["scan_id"] = scan_id``.
+
+    If the SPEC file already exists, then ``scan_id`` is ignored and
+    ``RE.md["scan_id"]`` is set to the last scan number in the file.
+    """
+    kwargs = {}
+    if RE is not None:
+        kwargs["RE"] = RE
+
+    mmdd = str(datetime.datetime.now()).split()[0][5:].replace("-", "_")
+    clean = apstools.utils.cleanupText(title)
+    fname = pathlib.Path(f"{mmdd}_{clean}.{file_extension}")
+    if fname.exists():
+        logger.warning(f">>> file already exists: {fname} <<<")
+        handled = "appended"
+    else:
+        kwargs["scan_id"] = scan_id or 1
+        handled = "created"
+
+    specwriter.newfile(fname, **kwargs)
+
+    logger.info(f"SPEC file name : {specwriter.spec_filename}")
+    logger.info(f"File will be {handled} at end of next bluesky scan.")
+
+
+# Add this function to specwriter.py
+def init_specwriter_with_RE(RE):
+    """Initialize specwriter with the run engine."""
+
+    # make the SPEC file in current working directory (assumes is writable)
+    specwriter.newfile(specwriter.spec_filename)
+
+    if iconfig.get("SPEC_DATA_FILES", {}).get("ENABLE", False):
+        RE.subscribe(specwriter.receiver)  # write data to SPEC files
+        logger.info("SPEC data file: %s", specwriter.spec_filename.resolve())
+
+    try:
+        # feature new in apstools 1.6.14
+        from apstools.plans import label_stream_wrapper
+
+        def motor_start_preprocessor(plan):
+            """Record motor positions at start of each run."""
+            return label_stream_wrapper(plan, "motor", when="start")
+
+        RE.preprocessors.append(motor_start_preprocessor)
+    except Exception:
+        logger.warning("Could load support to log motors positions.")
+
+
+# write scans to SPEC data file
+try:
+    # apstools >=1.6.21
+    _specwriter = apstools.callbacks.SpecWriterCallback2()
+except AttributeError:
+    # apstools <1.6.21
+    _specwriter = apstools.callbacks.SpecWriterCallback()
+
+specwriter = _specwriter
+"""The SPEC file writer object."""

apsbits/demo_instrument/configs/__init__.py

@@ -0,0 +1 @@
+"""Configs required to set up user package"""

apsbits/demo_instrument/configs/devices.yml

@@ -0,0 +1,52 @@
+# Guarneri-style device YAML configuration
+
+apsbits.utils.sim_creator.predefined_device:
+- {creator: ophyd.sim.motor, name: sim_motor}
+- {creator: ophyd.sim.noisy_det, name: sim_det}
+
+apstools.devices.SimulatedApsPssShutterWithStatus:
+- name: shutter
+  labels: ["shutters"]
+
+# ophyd.Signal:
+# - name: test
+#   value: 50.7
+# - name: t2
+#   value: 2
+
+# apstools.synApps.Optics2Slit2D_HV:
+# - name: slit1
+#   prefix: ioc:Slit1
+#   labels: ["slits"]
+
+# hkl.SimulatedE4CV:
+# - name: sim4c
+#   prefix: ""
+#   labels: ["diffractometer"]
+
+# ophyd.scaler.ScalerCH:
+# - name: scaler1
+#   prefix: vme:scaler1
+#   labels: ["scalers", "detectors"]
+
+# ophyd.EpicsMotor:
+# - {name: m1, prefix: gp:m1, labels: ["motor"]}
+# - {name: m2, prefix: gp:m2, labels: ["motor"]}
+# - {name: m3, prefix: gp:m3, labels: ["motor"]}
+# - {name: m4, prefix: gp:m4, labels: ["motor"]}
+
+# apstools.devices.ad_creator:
+#   - name: adsimdet
+#     prefix: "ad:"
+#     labels: ["area_detector", "detectors"]
+#     plugins:
+#       - cam:
+#           class: apstools.devices.SimDetectorCam_V34
+#       - image
+#       - pva
+#       - hdf1:
+#           class: apstools.devices.AD_EpicsFileNameHDF5Plugin
+#           read_path_template: "/path/to/bluesky/tmp/"
+#           write_path_template: "/path/to/ioc/tmp/"
+#       - roi1
+#       - stats1

apsbits/demo_instrument/configs/devices_aps_only.yml

@@ -0,0 +1,6 @@
+# Guarneri-style device YAML configuration
+
+# Objects only available at APS
+
+apstools.devices.ApsMachineParametersDevice:
+  - name: aps

apsbits/demo_instrument/configs/iconfig.yml

@@ -0,0 +1,82 @@
+# Configuration for the Bluesky instrument package.
+
+# identify the version of this iconfig.yml file
+ICONFIG_VERSION: 2.0.0
+
+# Add additional configuration for use with your instrument.
+
+### The short name for the databroker catalog.
+DATABROKER_CATALOG: &databroker_catalog temp
+
+### RunEngine configuration
+RUN_ENGINE:
+    DEFAULT_METADATA:
+        beamline_id: demo_instrument
+        instrument_name: Most Glorious Scientific Instrument
+        proposal_id: commissioning
+        databroker_catalog: *databroker_catalog
+
+    ### EPICS PV to use for the `scan_id`.
+    ### Default: `RE.md["scan_id"]` (not using an EPICS PV)
+    # SCAN_ID_PV: "IOC:bluesky_scan_id"
+
+    ### Where to "autosave" the RE.md dictionary.
+    ### Defaults:
+    MD_STORAGE_HANDLER: StoredDict
+    MD_PATH: .re_md_dict.yml
+
+    ### The progress bar is nice to see,
+    ### except when it clutters the output in Jupyter notebooks.
+    ### Default: False
+    USE_PROGRESS_BAR: false
+
+# Command-line tools, such as %wa, %ct, ...
+USE_BLUESKY_MAGICS: true
+
+### Best Effort Callback Configurations
+### Defaults: all true
+### except no plots in queueserver
+BEC:
+    BASELINE: true
+    HEADING: true
+    PLOTS: false
+    TABLE: true
+
+### Support for known output file formats.
+### Uncomment to use.  If undefined, will not write that type of file.
+### Each callback should apply its configuration from here.
+NEXUS_DATA_FILES:
+    ENABLE: false
+    FILE_EXTENSION: hdf
+
+SPEC_DATA_FILES:
+    ENABLE: true
+    FILE_EXTENSION: dat
+
+### APS Data Management
+### Use bash shell, deactivate all conda environments, source this file:
+DM_SETUP_FILE: "/home/dm/etc/dm.setup.sh"
+
+### Local OPHYD Device Control Yaml
+DEVICES_FILES:
+- devices.yml
+APS_DEVICES_FILES:
+- devices_aps_only.yml
+
+# ----------------------------------
+
+OPHYD:
+    ### Control layer for ophyd to communicate with EPICS.
+    ### Default: PyEpics
+    ### Choices: "PyEpics" or "caproto" # caproto is not yet supported
+    CONTROL_LAYER: PyEpics
+
+    ### default timeouts (seconds)
+    TIMEOUTS:
+        PV_READ: &TIMEOUT 5
+        PV_WRITE: *TIMEOUT
+        PV_CONNECTION: *TIMEOUT
+
+# Control detail of exception traces in IPython (console and notebook).
+# Options are: Minimal, Plain, Verbose
+XMODE_DEBUG_LEVEL: Plain

apsbits/demo_instrument/configs/logging.yml

@@ -0,0 +1,41 @@
+# Bluesky Session Logging Configuration
+
+console_logs:
+  date_format: "%a-%H:%M:%S"
+  log_format: "%(levelname)-.1s %(asctime)s.%(msecs)03d: %(message)s"
+  level: info
+  root_level: bsdev
+
+file_logs:
+  date_format: "%Y-%m-%d %H:%M:%S"
+  log_directory: .logs
+  log_filename_base: logging.log
+  log_format: "|\
+    %(asctime)s.%(msecs)03d|\
+    %(levelname)s|\
+    %(process)d|\
+    %(name)s|\
+    %(module)s|\
+    %(lineno)d|\
+    %(threadName)s| - \
+    %(message)s"
+  maxBytes: 1_000_000
+  backupCount: 9
+  level: info
+  rotate_on_startup: true
+
+ipython_logs:
+  log_directory: .logs
+  log_filename_base: ipython_log.py
+  log_mode: rotate
+  options: -o -t
+
+modules:
+  apstools: warning
+  bluesky-queueserver: warning
+  bluesky: warning
+  bluesky.RE: warning
+  caproto: warning
+  databroker: warning
+  instrument: bsdev
+  ophyd: warning

apsbits/demo_instrument/devices/__init__.py

@@ -0,0 +1 @@
+"""Ophyd-style devices."""

apsbits/demo_instrument/plans/__init__.py

@@ -0,0 +1,8 @@
+"""Bluesky plans."""
+
+from .dm_plans import dm_kickoff_workflow  # noqa: F401
+from .dm_plans import dm_list_processing_jobs  # noqa: F401
+from .dm_plans import dm_submit_workflow_job  # noqa: F401
+from .sim_plans import sim_count_plan  # noqa: F401
+from .sim_plans import sim_print_plan  # noqa: F401
+from .sim_plans import sim_rel_scan_plan  # noqa: F401