apsbits 1.0.4__tar.gz → 1.0.5__tar.gz

{apsbits-1.0.4 → apsbits-1.0.5}/HISTORY.rst

@@ -30,11 +30,27 @@ describe future plans.
 .. Coming release content can be gathered here.
     Some people object to publishing unreleased changes.
 
-    1.0.4
+    1.1.0
     #####
 
     release expected ?
 
+    New Features
+    ---------------
+
+    * Hoist support to setup baseline stream using labels kwarg from USAXS.
+
+    Maintenance
+    ---------------
+
+    * Bump iconfig version to 2.0.1 for the baseline addition.
+    * Remove run_engine section from QS config.yml file and pin QS to 0.0.22+.
+
+1.0.4
+#####
+
+released 2025-05-14
+
 1.0.3
 #####
 

{apsbits-1.0.4/apsbits.egg-info → apsbits-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apsbits
-Version: 1.0.4
+Version: 1.0.5
 Summary: Model of a Bluesky Data Acquisition Instrument in console, notebook, & queueserver.
 Author-email: Eric Codrea <ecodrea@anl.gov>, Pete Jemian <prjemian+instrument@gmail.com>, Rafael Vescovi <rvescovi@anl.gov>
 Maintainer-email: Eric Codrea <ecodrea@anl.gov>, Pete Jemian <prjemian+instrument@gmail.com>, Rafael Vescovi <rvescovi@anl.gov>
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: apstools>=1.7.2
 Requires-Dist: bluesky-queueserver-api
-Requires-Dist: bluesky-queueserver
+Requires-Dist: bluesky-queueserver>=0.0.22
 Requires-Dist: bluesky-widgets
 Requires-Dist: bluesky
 Requires-Dist: caproto

{apsbits-1.0.4 → apsbits-1.0.5/apsbits.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apsbits
-Version: 1.0.4
+Version: 1.0.5
 Summary: Model of a Bluesky Data Acquisition Instrument in console, notebook, & queueserver.
 Author-email: Eric Codrea <ecodrea@anl.gov>, Pete Jemian <prjemian+instrument@gmail.com>, Rafael Vescovi <rvescovi@anl.gov>
 Maintainer-email: Eric Codrea <ecodrea@anl.gov>, Pete Jemian <prjemian+instrument@gmail.com>, Rafael Vescovi <rvescovi@anl.gov>
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: apstools>=1.7.2
 Requires-Dist: bluesky-queueserver-api
-Requires-Dist: bluesky-queueserver
+Requires-Dist: bluesky-queueserver>=0.0.22
 Requires-Dist: bluesky-widgets
 Requires-Dist: bluesky
 Requires-Dist: caproto

{apsbits-1.0.4 → apsbits-1.0.5}/apsbits.egg-info/SOURCES.txt

@@ -120,6 +120,7 @@ src/apsbits/tests/test_run_instrument.py
 src/apsbits/tests/test_stored_dict.py
 src/apsbits/utils/__init__.py
 src/apsbits/utils/aps_functions.py
+src/apsbits/utils/baseline_setup.py
 src/apsbits/utils/config_loaders.py
 src/apsbits/utils/controls_setup.py
 src/apsbits/utils/helper_functions.py

{apsbits-1.0.4 → apsbits-1.0.5}/apsbits.egg-info/requires.txt

@@ -1,6 +1,6 @@
 apstools>=1.7.2
 bluesky-queueserver-api
-bluesky-queueserver
+bluesky-queueserver>=0.0.22
 bluesky-widgets
 bluesky
 caproto

{apsbits-1.0.4 → apsbits-1.0.5}/docs/source/guides/creating_devices.rst

@@ -46,32 +46,24 @@ You can also add a device from an external package to the ``devices.yml`` file.
        prefix: ioc:Slit1
        labels: ["slits"]
 
-2. Make sure all your device files are loaded on the ``iconfig.yml`` file.
-
-.. code-block:: yaml
-
-      DEVICES_FILES:
-        - devices.yml
-      APS_DEVICES_FILES:
-        - devices_aps_only.yml
-
-Note that the ``devices.yml`` file is loaded by default and the ``devices_aps_only.yml`` file is only loaded if the device is on the APS network.
 
 .. tip::
-    All kwargs of your device can be specified in the yaml file making it easy to resuse classes.
+    `APSTOOLS <https://github.com/BCDA-APS/apstools/tree/main/apstools>`_ has a lot of devices commonly used at the APS. Consider first checking the package and overwriting the device class to fit your needs before creating a new device.
 
 .. tip::
-   You can add any number of device files inside the iconfig file used by your instrument ``startup.py`` file. Just add another entry to the list.
+    You can add the `label: baseline` to any device in your configuration to automatically track its state during scans. This is particularly useful for monitoring environmental conditions or instrument parameters. For example:
 
-   .. code-block:: yaml
+    .. code-block:: yaml
 
-      ### Local OPHYD Device Control Yaml
-      DEVICES_FILES:
-        - devices.yml ## standard device file
-        - devices_2.yml ## another device file
-      APS_DEVICES_FILES:
-        - devices_aps_only.yml ## APS only device file
-        - devices_aps_only_2.yml ## another APS only device file
+        apstools.devices.ApsMachineParametersDevice:
+        - name: aps
+          labels:
+          - baseline
 
-.. tip::
-    `APSTOOLS <https://github.com/BCDA-APS/apstools/tree/main/apstools>`_ has a lot of devices commonly used at the APS. Consider first checking the package and overwriting the device class to fit your needs before creating a new device.
+        ophyd.EpicsSignalRO:
+        - name: temperature_monitor
+          prefix: "IOC:TEMP"
+          labels:
+          - baseline
+
+    Baseline devices will be automatically included in the metadata of each scan, making it easy to track changes in environmental conditions or instrument parameters over time.

{apsbits-1.0.4 → apsbits-1.0.5}/docs/source/guides/sessions.rst

@@ -35,4 +35,26 @@ When ready to load the bluesky data acquisition for use, type this command. For
 
 .. code-block:: bash
 
+    from demo_instrument.startup import *
+
+.. note::
+Change the demo_instrument to your instrument installed package name.
+
+Adding BITS to ipython profile
+----------------------------------
+
+To add BITS to your ipython profile, first create a new profile:
+
+.. code-block:: bash
+
+    ipython profile create bits-xx
+
+Then, add the following to your startup file:
+
+.. code-block:: bash
+
+    cat > ~/.ipython/profile_bits-xx/startup/00-start-bits.py  << EOF
     from new_instrument.startup import *
+    EOF
+
+For more detailed guidance on creating and configuring an ipython profile, see the `bluesky training documentation <https://github.com/BCDA-APS/bluesky_training/blob/304b8d02503044932afa5657cb43afd1f6be2f40/docs/source/instrument/_create_bluesky_ipython_profile.rst#L2>`_.

{apsbits-1.0.4 → apsbits-1.0.5}/docs/source/guides/startup.rst

@@ -52,7 +52,6 @@ Tips:
 * Create an extra_logging.yml file if you need custom logging configuration
 * The default logging setup from apsbits will be used if no extra configuration is provided
 
-
 Data Management Setup
 ~~~~~~~~~~~~~~~~~~~
 
@@ -129,10 +128,51 @@ Device Loading
     if host_on_aps_subnet():
         RE(make_devices(clear=False, file="device_aps_only.yml"))
 
+This block:
+* Loads the main device configuration from devices.yml
+* Optionally loads APS-specific devices from devices_aps_only.yml if running on APS subnet
+* Uses clear=False to preserve existing devices
+
 Tips:
 * Create a devices.yml file with your instrument's device configurations
 * Optionally create device_aps_only.yml for APS-specific devices
-* Set clear=False to preserve existing devices
+* The make_devices function will automatically register devices with the ophyd registry
+
+Baseline Device Setup
+~~~~~~~~~~~~~~~~~~~
+
+The baseline device setup allows you to track and record the state of specific devices during each scan. This is particularly useful for monitoring environmental conditions or instrument parameters that might affect your measurements.
+
+To configure baseline devices:
+
+1. In your devices.yml file, add a `label: baseline` to any device you want to track:
+
+   .. code-block:: yaml
+
+       apstools.devices.ApsMachineParametersDevice:
+       - name: aps
+         labels:
+         - baseline
+
+       ophyd.EpicsSignalRO:
+       - name: temperature_monitor
+         prefix: "IOC:TEMP"
+         labels:
+         - baseline
+
+2. The baseline devices will be automatically included in the metadata of each scan through the setup_baseline_stream function:
+
+   .. code-block:: python
+
+       setup_baseline_stream(sd, oregistry, connect=False)
+
+3. You can access baseline device values in your analysis using the scan metadata.
+
+Tips:
+* Use baseline devices for monitoring critical environmental parameters
+* Consider including timestamps, temperature, pressure, or other relevant measurements
+* Baseline devices should be read-only to avoid accidental modifications
+* Keep the number of baseline devices reasonable to avoid excessive data collection
 
 Configuration Tips
 ----------------

{apsbits-1.0.4 → apsbits-1.0.5}/pyproject.toml

@@ -35,7 +35,7 @@ classifiers = [
 dependencies = [
     "apstools >= 1.7.2",
     "bluesky-queueserver-api",
-    "bluesky-queueserver",
+    "bluesky-queueserver >=0.0.22",
     "bluesky-widgets",
     "bluesky",
     "caproto",

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.0.4'
-__version_tuple__ = version_tuple = (1, 0, 4)
+__version__ = version = '1.0.5'
+__version_tuple__ = version_tuple = (1, 0, 5)

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/core/instrument_init.py

@@ -62,6 +62,22 @@ def make_devices(
 
     logger.debug("(Re)Loading local control objects.")
 
+    if file is None:
+        logger.error("No custom device file provided.")
+        return
+
+    if path is None:
+        iconfig = get_config()
+        instrument_path = pathlib.Path(iconfig.get("INSTRUMENT_PATH")).parent
+        configs_path = instrument_path / "configs"
+        logger.info(
+            f"No custom path provided.\n\nUsing default configs path: {configs_path}"
+        )
+
+    else:
+        logger.info(f"Using custom path for device files: {path}")
+        configs_path = pathlib.Path(path)
+
     if clear:
         main_namespace = sys.modules[MAIN_NAMESPACE]
 
@@ -75,27 +91,10 @@ def make_devices(
 
         oregistry.clear()
 
-    if path is not None and file is None:
-        raise ValueError(
-            "When a custom path is provided, a specific device file must"
-            " also be provided"
-        )
-
-    if path is not None:
-        configs_path = pathlib.Path(path)
-        print(f"\n\nConfigs path: {configs_path}\n\n")
-
-    else:
-        iconfig = get_config()
-        instrument_path = pathlib.Path(iconfig.get("INSTRUMENT_PATH")).parent
-        configs_path = instrument_path / "configs"
-
-    device_file = file
-
-    logger.debug("Loading device files: %r", device_file)
+    logger.debug("Loading device files: %r", file)
 
     # Load each device file
-    device_path = configs_path / device_file
+    device_path = configs_path / file
     if not device_path.exists():
         logger.error("Device file not found: %s", device_path)
 
@@ -129,14 +128,17 @@ def namespace_loader(yaml_device_file, main=True):
     logger.debug("Devices file %r.", str(yaml_device_file))
     t0 = time.time()
 
+    current_devices = oregistry.device_names
+
     instrument.load(yaml_device_file)
 
     logger.info("Devices loaded in %.3f s.", time.time() - t0)
     if main:
         main_namespace = sys.modules[MAIN_NAMESPACE]
-        for label in oregistry.device_names:
+        for label in sorted(oregistry.device_names):
+            if label in current_devices:
+                continue
             logger.info("Adding ophyd device %r to main namespace", label)
-
             setattr(main_namespace, label, oregistry[label])
 
 

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/core/run_engine_init.py

@@ -7,7 +7,7 @@ Bluesky RunEngine with metadata storage, subscriptions, and various
 settings based on a configuration dictionary.
 
 .. autosummary::
-    init_RE
+    ~init_RE
 """
 
 import logging
@@ -113,7 +113,6 @@ def init_RE(
         RE.subscribe(cat_instance.v1.insert)
     if bec_instance is not None:
         RE.subscribe(bec_instance)
-    RE.preprocessors.append(sd)
 
     scan_id_pv = iconfig.get("RUN_ENGINE", {}).get("SCAN_ID_PV")
     connect_scan_id_pv(RE, pv=scan_id_pv)

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/demo_instrument/configs/devices.yml

@@ -1,13 +1,12 @@
 # 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}
+- { creator: ophyd.sim.motor, name: sim_motor }
+- { creator: ophyd.sim.noisy_det, name: sim_det }
 
 apstools.devices.SimulatedApsPssShutterWithStatus:
 - name: shutter
-  labels: ["shutters"]
-
+  labels: [ "shutters", "baseline" ]
 
 ## THIS ARE EXAMPLES OF OTHER DEVICES THAT YOU CAN USE
 # ophyd.Signal:
@@ -19,7 +18,7 @@ apstools.devices.SimulatedApsPssShutterWithStatus:
 # apstools.synApps.Optics2Slit2D_HV:
 # - name: slit1
 #   prefix: ioc:Slit1
-#   labels: ["slits"]
+#   labels: ["slits", "baseline"]
 
 # hkl.SimulatedE4CV:
 # - name: sim4c

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/demo_instrument/configs/devices_aps_only.yml

@@ -3,4 +3,6 @@
 # Objects only available at APS
 
 apstools.devices.ApsMachineParametersDevice:
-  - name: aps
+- name: aps
+  labels:
+  - baseline

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/demo_instrument/configs/iconfig.yml

@@ -1,7 +1,7 @@
 # Configuration for the Bluesky instrument package.
 
 # identify the version of this iconfig.yml file
-ICONFIG_VERSION: 2.0.0
+ICONFIG_VERSION: 2.0.1
 
 # Add additional configuration for use with your instrument.
 
@@ -29,6 +29,12 @@ RUN_ENGINE:
     ### Default: False
     USE_PROGRESS_BAR: false
 
+### Baseline stream
+### When ENABLE=true, all ophyd objects with a "baseline" label
+### will be added to the baseline stream.
+BASELINE_LABEL:
+    ENABLE: true
+
 ### Best Effort Callback Configurations
 ### Defaults: all true
 ### except no plots in queueserver
@@ -50,7 +56,7 @@ SPEC_DATA_FILES:
     FILE_EXTENSION: dat
 
 ### APS Data Management
-### Use bash shell, deactivate all conda environments, source this file:
+### Learn environment variables for Data Management from this file:
 DM_SETUP_FILE: "/home/dm/etc/dm.setup.sh"
 
 # ----------------------------------

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/demo_instrument/startup.py

@@ -24,6 +24,7 @@ from apsbits.core.run_engine_init import init_RE
 # Utility functions
 from apsbits.utils.aps_functions import aps_dm_setup
 from apsbits.utils.aps_functions import host_on_aps_subnet
+from apsbits.utils.baseline_setup import setup_baseline_stream
 
 # Configuration functions
 from apsbits.utils.config_loaders import load_config
@@ -104,3 +105,7 @@ RE(make_devices(clear=False, file="devices.yml"))  # Create the devices.
 
 if host_on_aps_subnet():
     RE(make_devices(clear=False, file="devices_aps_only.yml"))
+
+# Setup baseline stream with connect=False is default
+# Devices with the label 'baseline' will be added to the baseline stream.
+setup_baseline_stream(sd, oregistry, connect=False)

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/demo_qserver/qs-config.yml

@@ -30,15 +30,6 @@ operation:
     # choices: NEVER ON_REQUEST ON_STARTUP
     user_group_permissions_reload: ON_STARTUP
 
-run_engine:
-    # databroker_config: name_of_databroker_config_file
-
-    # kafka_server: 127.0.0.1:9092
-    # kafka_topic: custom_topic_name
-
-    use_persistent_metadata: true
-    zmq_data_proxy_addr: localhost:5567
-
 startup:
     keep_re: true
     startup_module: demo_instrument.startup

{apsbits-1.0.4 → apsbits-1.0.5}/src/apsbits/tests/test_config.py

@@ -15,12 +15,14 @@ from apsbits.utils.config_loaders import load_config
 if TYPE_CHECKING:
     pass
 
+ICONFIG_VERSION_NOW: str = "2.0.1"
+
 
 @pytest.fixture
 def yml_config_file():
     """Create a temporary YAML configuration file."""
     config = {
-        "ICONFIG_VERSION": "2.0.0",
+        "ICONFIG_VERSION": ICONFIG_VERSION_NOW,
         "DATABROKER_CATALOG": "temp",
         "test_key": "test_value",
     }
@@ -37,7 +39,7 @@ def yml_config_file():
 def toml_config_file():
     """Create a temporary TOML configuration file."""
     config = {
-        "ICONFIG_VERSION": "2.0.0",
+        "ICONFIG_VERSION": ICONFIG_VERSION_NOW,
         "DATABROKER_CATALOG": "temp",
         "test_key": "test_value",
     }
@@ -58,7 +60,7 @@ def test_load_yaml_config(yml_config_file: pathlib.Path) -> None:
         yml_config_file: Path to the temporary YAML configuration file.
     """
     config = load_config(yml_config_file)
-    assert config["ICONFIG_VERSION"] == "2.0.0"
+    assert config["ICONFIG_VERSION"] == ICONFIG_VERSION_NOW
     assert config["DATABROKER_CATALOG"] == "temp"
     assert config["test_key"] == "test_value"
 
@@ -71,7 +73,7 @@ def test_load_toml_config(toml_config_file: pathlib.Path) -> None:
         toml_config_file: Path to the temporary TOML configuration file.
     """
     config = load_config(toml_config_file)
-    assert config["ICONFIG_VERSION"] == "2.0.0"
+    assert config["ICONFIG_VERSION"] == ICONFIG_VERSION_NOW
     assert config["DATABROKER_CATALOG"] == "temp"
     assert config["test_key"] == "test_value"
 

apsbits-1.0.5/src/apsbits/utils/baseline_setup.py

@@ -0,0 +1,104 @@
+"""
+Setup all configured ophyd items for the baseline stream.
+
+.. autosummary::
+    ~setup_baseline_stream
+"""
+
+import logging
+
+import bluesky
+import guarneri
+
+from apsbits.utils.config_loaders import get_config
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def setup_baseline_stream(
+    sd: bluesky.SupplementalData,
+    oregistry: guarneri.Instrument,
+    connect: bool = False,
+) -> None:
+    """
+    Add ophyd objects with 'baseline' label to baseline stream.
+
+    Call :func:`~apsbits.core.run_engine_init.setup_baseline_stream(sd, iconfig,
+    oregistry)` in the startup code after all ophyd objects have been created.
+    It is safe to call this function even when no objects are labeled; there are
+    checks that return early if not configured.  This function should part of
+    every startup.
+
+    To include any ophyd object created after startup has completed, append it
+    to the 'sd.baseline' list, such as: ``sd.baseline.append(new_ophyd_object)``
+
+    Parameters:
+
+    sd bluesky.SupplementalData :
+        Object which contains the list of baseline objects to be published.
+    oregistry guarneri.Instrument :
+        Registry of ophyd objects.
+    connect bool :
+        When True (default: False), will wait for connection for all marked
+        devices.  A warning will be logged for any devices which do not
+        connect.
+
+    .. rubric:: Background
+
+    The baseline stream records the values of ophyd objects:
+
+    * at the start and end of a run
+    * that are not intended as detectors (or other readables) for the primary stream
+    * that may not be suitable to record in the run's metadata
+    * for use by post-acquisition processing
+
+    To enable the assignment of an ophyd object to the baseline stream, add
+    "baseline" to its labels kwarg list. On startup, after all the objects have
+    been created, use the oregistry to find all the objects with the "baseline"
+    label and append each to the sd.baseline list.
+
+    To learn more about baseline readings and the baseline stream in bluesky, see:
+
+    * https://blueskyproject.io/bluesky/main/plans.html#supplemental-data
+    * https://blueskyproject.io/bluesky/main/metadata.html#recording-metadata
+    * https://nsls-ii.github.io/bluesky/tutorial.html#baseline-readings-and-other-supplemental-data
+    """
+
+    iconfig = get_config()
+    baseline_config = iconfig.get("BASELINE_LABEL")
+    if baseline_config is None:
+        logger.info("No baseline configuration found in iconfig.yml file.")
+        return
+
+    if not baseline_config.get("ENABLE", False):
+        logger.info("Baseline stream is disabled in iconfig.yml file.")
+        return
+
+    candidates = oregistry.findall("baseline", allow_none=True)
+    if candidates is None:
+        logger.info("No baseline objects found in oregistry.")
+        return
+
+    if connect:
+        # Wait for all objects in parallel.
+        for item in candidates:
+            try:
+                item.wait_for_connection()
+            except TimeoutError:
+                pass  # Check for connection below.
+
+        troubled = [item for item in candidates if not item.connected]
+        for item in troubled:
+            logger.warning("Could not connect baseline object: %s", item)
+            candidates.remove(item)
+            oregistry.pop(item)
+
+    try:
+        logger.info("Adding marked objects to 'baseline' stream.")
+        sd.baseline.extend(candidates)
+    except Exception as excuse:
+        logger.warning(
+            "Problem extending 'baseline' stream: %s",
+            excuse,
+        )