apsbits 1.0.0__py3-none-any.whl

apsbits/demo_instrument/plans/dm_plans.py

@@ -0,0 +1,111 @@
+"""
+Plans in support of APS Data Management
+=======================================
+
+.. autosummary::
+
+    ~dm_kickoff_workflow
+    ~dm_list_processing_jobs
+    ~dm_submit_workflow_job
+"""
+
+import logging
+
+from apstools.devices import DM_WorkflowConnector
+from apstools.utils import dm_api_proc
+from apstools.utils import share_bluesky_metadata_with_dm
+from bluesky import plan_stubs as bps
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def dm_kickoff_workflow(run, argsDict, timeout=None, wait=False):
+    """
+    Start a DM workflow for this bluesky run and share run's metadata with DM.
+
+    PARAMETERS:
+
+    run (*obj*): Bluesky run object (such as 'run = cat[uid]').
+
+    argsDict (*dict*): Dictionary of parameters needed by 'workflowName'.
+        At minimum, most workflows expect these keys: 'filePath' and
+        'experimentName'.  Consult the workflow for the expected
+        content of 'argsDict'.
+
+    timeout (*number*): When should bluesky stop reporting on this
+        DM workflow job (if it has not ended). Units are seconds.
+        Default is forever.
+
+    wait (*bool*): Should this plan stub wait for the job to end?
+        Default is 'False'.
+    """
+    dm_workflow = DM_WorkflowConnector(name="dm_workflow")
+
+    if timeout is None:
+        # Disable periodic reports, use a long time (s).
+        timeout = 999_999_999_999
+
+    yield from bps.mv(dm_workflow.concise_reporting, True)
+    yield from bps.mv(dm_workflow.reporting_period, timeout)
+
+    workflow_name = argsDict.pop["workflowName"]
+    yield from dm_workflow.run_as_plan(
+        workflow=workflow_name,
+        wait=wait,
+        timeout=timeout,
+        **argsDict,
+    )
+
+    # Upload bluesky run metadata to APS DM.
+    share_bluesky_metadata_with_dm(argsDict["experimentName"], workflow_name, run)
+
+    # Users requested the DM workflow job ID be printed to the console.
+    dm_workflow._update_processing_data()
+    job_id = dm_workflow.job_id.get()
+    job_stage = dm_workflow.stage_id.get()
+    job_status = dm_workflow.status.get()
+    print(f"DM workflow id: {job_id!r}  status: {job_status}  stage: {job_stage}")
+
+
+def dm_list_processing_jobs(exclude=None):
+    """
+    Show all the DM jobs with status not excluded.
+
+    Excluded status (default): 'done', 'failed'
+    """
+    yield from bps.null()  # make this a plan stub
+    api = dm_api_proc()
+    if exclude is None:
+        exclude = ("done", "failed")
+
+    for j in api.listProcessingJobs():
+        if j["status"] not in exclude:
+            print(
+                f"id={j['id']!r}"
+                f"  submitted={j.get('submissionTimestamp')}"
+                f"  status={j['status']!r}"
+            )
+
+
+def dm_submit_workflow_job(workflowName, argsDict):
+    """
+    Low-level plan stub to submit a job to a DM workflow.
+
+    It is recommended to use dm_kickoff_workflow() instead.
+    This plan does not share run metadata with DM.
+
+    PARAMETERS:
+
+    workflowName (*str*): Name of the DM workflow to be run.
+
+    argsDict (*dict*): Dictionary of parameters needed by 'workflowName'.
+        At minimum, most workflows expect these keys: 'filePath' and
+        'experimentName'.  Consult the workflow for the expected
+        content of 'argsDict'.
+    """
+    yield from bps.null()  # make this a plan stub
+    api = dm_api_proc()
+
+    job = api.startProcessingJob(api.username, workflowName, argsDict)
+    print(f"workflow={workflowName!r}  id={job['id']!r}")

apsbits/demo_instrument/plans/sim_plans.py

@@ -0,0 +1,69 @@
+"""
+Simulators from ophyd
+=====================
+
+For development and testing only, provides plans.
+
+.. autosummary::
+    ~sim_count_plan
+    ~sim_print_plan
+    ~sim_rel_scan_plan
+"""
+
+import logging
+
+from bluesky import plan_stubs as bps
+from bluesky import plans as bp
+
+from apsbits.utils.controls_setup import oregistry
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+DEFAULT_MD = {"title": "test run with simulator(s)"}
+
+
+def sim_count_plan(num: int = 1, imax: float = 10_000, md: dict = DEFAULT_MD):
+    """Demonstrate the ``count()`` plan."""
+    logger.debug("sim_count_plan()")
+    sim_det = oregistry["sim_det"]
+    yield from bps.mv(sim_det.Imax, imax)
+    yield from bp.count([sim_det], num=num, md=md)
+
+
+def sim_print_plan():
+    """Demonstrate a ``print()`` plan stub (no data streams)."""
+    logger.debug("sim_print_plan()")
+    yield from bps.null()
+    sim_det = oregistry["sim_det"]
+    sim_motor = oregistry["sim_motor"]
+    print("sim_print_plan(): This is a test.")
+    print(f"sim_print_plan():  {sim_motor.position=}  {sim_det.read()=}.")
+
+
+def sim_rel_scan_plan(
+    span: float = 5,
+    num: int = 11,
+    imax: float = 10_000,
+    center: float = 0,
+    sigma: float = 1,
+    noise: str = "uniform",  # none poisson uniform
+    md: dict = DEFAULT_MD,
+):
+    """Demonstrate the ``rel_scan()`` plan."""
+    logger.debug("sim_rel_scan_plan()")
+    sim_det = oregistry["sim_det"]
+    sim_motor = oregistry["sim_motor"]
+    # fmt: off
+    yield from bps.mv(
+        sim_det.Imax, imax,
+        sim_det.center, center,
+        sim_det.sigma, sigma,
+        sim_det.noise, noise,
+    )
+    # fmt: on
+    print(f"sim_rel_scan_plan(): {sim_motor.position=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.read()=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.read_configuration()=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.noise._enum_strs=}.")
+    yield from bp.rel_scan([sim_det], sim_motor, -span / 2, span / 2, num=num, md=md)

apsbits/demo_instrument/startup.py

@@ -0,0 +1,76 @@
+"""
+Start Bluesky Data Acquisition sessions of all kinds.
+
+Includes:
+
+* Python script
+* IPython console
+* Jupyter notebook
+* Bluesky queueserver
+"""
+
+import logging
+
+from apsbits.core.best_effort_init import init_bec_peaks
+from apsbits.core.catalog_init import init_catalog
+from apsbits.core.run_engine_init import init_RE
+from apsbits.utils.aps_functions import aps_dm_setup
+from apsbits.utils.config_loaders import get_config
+from apsbits.utils.helper_functions import register_bluesky_magics
+from apsbits.utils.helper_functions import running_in_queueserver
+from apsbits.utils.make_devices import make_devices
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+# Get the configuration
+iconfig = get_config()
+
+# Configure the session with callbacks, devices, and plans.
+aps_dm_setup(iconfig.get("DM_SETUP_FILE"))
+
+if iconfig.get("USE_BLUESKY_MAGICS", False):
+    register_bluesky_magics()
+
+# Initialize core components
+bec, peaks = init_bec_peaks(iconfig)
+cat = init_catalog(iconfig)
+RE, sd = init_RE(iconfig, bec_instance=bec, cat_instance=cat)
+
+# Import optional components based on configuration
+if iconfig.get("NEXUS_DATA_FILES", {}).get("ENABLE", False):
+    from .callbacks.nexus_data_file_writer import nxwriter_init
+
+    nxwriter = nxwriter_init(RE)
+
+if iconfig.get("SPEC_DATA_FILES", {}).get("ENABLE", False):
+    from .callbacks.spec_data_file_writer import init_specwriter_with_RE
+    from .callbacks.spec_data_file_writer import newSpecFile  # noqa: F401
+    from .callbacks.spec_data_file_writer import spec_comment  # noqa: F401
+    from .callbacks.spec_data_file_writer import specwriter  # noqa: F401
+
+    init_specwriter_with_RE(RE)
+
+# Import all plans
+from .plans import *  # noqa
+
+# These imports must come after the above setup.
+if running_in_queueserver():
+    ### To make all the standard plans available in QS, import by '*', otherwise import
+    ### plan by plan.
+    from apstools.plans import lineup2  # noqa: F401
+    from bluesky.plans import *  # noqa: F403
+
+else:
+    # Import bluesky plans and stubs with prefixes set by common conventions.
+    # The apstools plans and utils are imported by '*'.
+    from apstools.plans import *  # noqa: F403
+    from apstools.utils import *  # noqa: F403
+    from bluesky import plan_stubs as bps  # noqa: F401
+    from bluesky import plans as bp  # noqa: F401
+
+    from apsbits.utils.controls_setup import oregistry
+
+oregistry.clear()
+
+RE(make_devices())

apsbits/demo_qserver/qs-config.yml

@@ -0,0 +1,51 @@
+# Bluesky-Queueserver start-re-manager configuration
+# use:
+#   queue-monitor &
+#   ./qserver/qs_host.sh start
+#
+#   or
+#   cd ./qserver
+#   start-re-manager --config=./qs-config.yml
+#
+# https://blueskyproject.io/bluesky-queueserver/manager_config.html
+
+network:
+    redis_addr: localhost:6379
+    redis_name_prefix: qs_default
+    zmq_control_addr: tcp://*:60615
+    zmq_info_addr: tcp://*:60625
+    zmq_publish_console: true
+
+operation:
+    # choices: SILENT QUIET NORMAL VERBOSE
+    console_logging_level: NORMAL
+
+    # emergency_lock_key: custom_lock_key
+
+    print_console_output: true
+
+    # choices: NEVER ENVIRONMENT_OPEN ALWAYS
+    update_existing_plans_and_devices: ENVIRONMENT_OPEN
+
+    # 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
+    existing_plans_and_devices_path: ./
+    user_group_permissions_path: ./
+
+worker:
+    use_ipython_kernel: true
+    # ipython_kernel_ip: auto
+    ipython_matplotlib: qt5

apsbits/demo_qserver/qs_host.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+# file: qs_host.sh
+# Manage the bluesky queueserver host process.
+# Could be in a screen session or run as a direct process.
+
+SHELL_SCRIPT_NAME=${BASH_SOURCE:-${0}}
+SCRIPT_DIR="$(dirname $(readlink -f  "${SHELL_SCRIPT_NAME}"))"
+CONFIGS_DIR=$(readlink -f "${SCRIPT_DIR}/../demo_instrument/configs")
+
+###-----------------------------
+### Change program defaults here
+
+# Instrument configuration YAML file with databroker catalog name.
+ICONFIG_YML="${CONFIGS_DIR}"/iconfig.yml
+
+# Bluesky queueserver configuration YAML file.
+# This file contains the definition of 'redis_addr'.  (default: localhost:6379)
+QS_CONFIG_YML="${SCRIPT_DIR}/qs-config.yml"
+
+# Host name (from $hostname) where the queueserver host process runs.
+# QS_HOSTNAME=amber.xray.aps.anl.gov  # if a specific host is required
+QS_HOSTNAME="$(hostname)"
+
+PROCESS=start-re-manager  # from the conda environment
+STARTUP_COMMAND="${PROCESS} --config=${QS_CONFIG_YML}"
+
+#--------------------
+# internal configuration below
+
+# echo "PROCESS=${PROCESS}"
+if [ ! -f $(which "${PROCESS}") ]; then
+    echo "PROCESS '${PROCESS}': file not found. CONDA_PREFIX='${CONDA_PREFIX}'"
+    exit 1
+fi
+
+if [ -z "$STARTUP_DIR" ] ; then
+    # If no startup dir is specified, use the directory with this script
+    STARTUP_DIR="${SCRIPT_DIR}"
+fi
+
+if [ "${DATABROKER_CATALOG}" == "" ]; then
+    if [ -f "${ICONFIG_YML}" ]; then
+        DATABROKER_CATALOG=$(grep DATABROKER_CATALOG "${ICONFIG_YML}" | awk '{print $NF}')
+        # echo "Using catalog ${DATABROKER_CATALOG}"
+    fi
+fi
+DEFAULT_SESSION_NAME="bluesky_queueserver-${DATABROKER_CATALOG}"
+
+#--------------------
+
+SELECTION=${1:-usage}
+SESSION_NAME=${2:-"${DEFAULT_SESSION_NAME}"}
+
+# But other management commands will fail if mismatch
+if [ "$(hostname)" != "${QS_HOSTNAME}" ]; then
+    echo "Must manage queueserver process on ${QS_HOSTNAME}.  This is $(hostname)."
+    exit 1
+fi
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+# echo "SESSION_NAME = ${SESSION_NAME}"
+# echo "SHELL_SCRIPT_NAME = ${SHELL_SCRIPT_NAME}"
+# echo "STARTUP_COMMAND = ${STARTUP_COMMAND}"
+# echo "STARTUP_DIR = ${STARTUP_DIR}"
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+function checkpid() {
+    # Assume the process is down until proven otherwise
+    PROCESS_DOWN=1
+
+    MY_UID=$(id -u)
+    # The '\$' is needed in the pgrep pattern to select vm7, but not vm7.sh
+    MY_PID=$(ps -u | grep "${PROCESS}")
+    #!echo "MY_PID=${MY_PID}"
+    SCREEN_SESSION="${MY_PID}.${SESSION_NAME}"
+
+    if [ "${MY_PID}" != "" ] ; then
+        SCREEN_PID="${MY_PID}"
+
+        # At least one instance of the process is running;
+        # Find the binary that is associated with this process
+        for pid in ${MY_PID}; do
+            # compare directories
+            BIN_CWD=$(readlink "/proc/${pid}/cwd")
+            START_CWD=$(readlink -f "${STARTUP_DIR}")
+
+            if [ "$BIN_CWD" = "$START_CWD" ] ; then
+                # The process is running with PID=$pid from $STARTUP_DIR
+                P_PID=$(ps -p "${pid}" -o ppid=)
+                # strip leading (and trailing) whitespace
+                arr=($P_PID)
+                P_PID=${arr[0]}
+                SCREEN_SESSION="${P_PID}.${SESSION_NAME}"
+                SCREEN_MATCH=$(screen -ls "${SCREEN_SESSION}" | grep "${SESSION_NAME}")
+                if [ "${SCREEN_MATCH}" != "" ] ; then
+                    # process is running in screen
+                    PROCESS_DOWN=0
+                    MY_PID=${pid}
+                    SCREEN_PID=${P_PID}
+                    break
+                fi
+            fi
+        done
+    else
+        # process is not running
+        PROCESS_DOWN=1
+    fi
+
+    return ${PROCESS_DOWN}
+}
+
+function checkup () {
+    if ! checkpid; then
+        restart
+    fi
+}
+
+function console () {
+    if checkpid; then
+        echo "Connecting to ${SCREEN_SESSION}'s screen session"
+        # The -r flag will only connect if no one is attached to the session
+        #!screen -r "${SESSION_NAME}"
+        # The -x flag will connect even if someone is attached to the session
+        screen -x "${SCREEN_SESSION}"
+    else
+        echo "${SCREEN_NAME} is not running"
+    fi
+}
+
+function exit_if_running() {
+    # ensure that multiple, simultaneous processes are not started by this user ID
+    MY_UID=$(id -u)
+    MY_PID=$(pgrep "${SESSION_NAME}"\$ -u "${MY_UID}")
+
+    if [ "" != "${MY_PID}" ] ; then
+        echo "${SESSION_NAME} is already running (PID=${MY_PID}), won't start a new one"
+        exit 1
+    fi
+}
+
+function restart() {
+    stop
+    start
+}
+
+function run_process() {
+    # only use this for diagnostic purposes
+    exit_if_running
+    cd "${STARTUP_DIR}"
+    ${STARTUP_COMMAND}
+}
+
+function screenpid() {
+    if [ -z "${SCREEN_PID}" ] ; then
+        echo
+    else
+        echo " in a screen session (pid=${SCREEN_PID})"
+    fi
+}
+
+function start() {
+    if checkpid; then
+        echo -n "${SCREEN_SESSION} is already running (pid=${MY_PID})"
+        screenpid
+    else
+        if [ ! -f "${CONDA_EXE}" ]; then
+            echo "No 'conda' command available."
+            exit 1
+        fi
+        echo "Starting ${SESSION_NAME}"
+        cd "${STARTUP_DIR}"
+        # Run SESSION_NAME inside a screen session
+        CMD="screen -DmS ${SESSION_NAME} -h 5000 ${STARTUP_COMMAND}"
+        ${CMD} &
+    fi
+}
+
+function status() {
+    if checkpid; then
+        echo -n "${SCREEN_SESSION} is running (pid=${MY_PID})"
+        screenpid
+    else
+        echo "${SESSION_NAME} is not running"
+    fi
+}
+
+function stop() {
+    if checkpid; then
+        echo "Stopping ${SCREEN_SESSION} (pid=${MY_PID})"
+        kill "${MY_PID}"
+    else
+        echo "${SESSION_NAME} is not running"
+    fi
+}
+
+function usage() {
+    echo "Usage: $(basename "${SHELL_SCRIPT_NAME}") {start|stop|restart|status|checkup|console|run} [NAME]"
+    echo ""
+    echo "    COMMANDS"
+    echo "        console   attach to process console if process is running in screen"
+    echo "        checkup   check that process is running, restart if not"
+    echo "        restart   restart process"
+    echo "        run       run process in console (not screen)"
+    echo "        start     start process"
+    echo "        status    report if process is running"
+    echo "        stop      stop process"
+    echo ""
+    echo "    OPTIONAL TERMS"
+    echo "        NAME      name of process (default: ${DEFAULT_SESSION_NAME})"
+}
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+case ${SELECTION} in
+    start) start ;;
+    stop | kill) stop ;;
+    restart) restart ;;
+    status) status ;;
+    checkup) checkup ;;
+    console) console ;;
+    run) run_process ;;
+    *) usage ;;
+esac
+
+# -----------------------------------------------------------------------------
+# :author:    BCDA
+# :copyright: (c) 2017-2025, UChicago Argonne, LLC
+# The full license is in the file LICENSE, distributed with this software.
+# -----------------------------------------------------------------------------

apsbits/demo_qserver/user_group_permissions.yaml

@@ -0,0 +1,46 @@
+user_groups:
+  root:  # The group includes all available plan and devices
+    allowed_plans:
+      - null  # Allow all
+    forbidden_plans:
+      - ":^_"  # All plans with names starting with '_'
+    allowed_devices:
+      - null  # Allow all
+    forbidden_devices:
+      - ":^_:?.*"  # All devices with names starting with '_'
+    allowed_functions:
+      - null  # Allow all
+    forbidden_functions:
+      - ":^_"  # All functions with names starting with '_'
+  primary:  # The group includes beamline staff, includes all or most of the plans and devices
+    allowed_plans:
+      - ":.*"  # Different way to allow all plans.
+    forbidden_plans:
+      - null  # Nothing is forbidden
+    allowed_devices:
+      - ":?.*:depth=5"  # Allow all device and subdevices. Maximum deepth for subdevices is 5.
+    forbidden_devices:
+      - null  # Nothing is forbidden
+    allowed_functions:
+      - "function_sleep"  # Explicitly listed name
+  test_user:  # Users with limited access capabilities
+    allowed_plans:
+      - ":^count"  # Use regular expression patterns
+      - ":scan$"
+    forbidden_plans:
+      - ":^adaptive_scan$" # Use regular expression patterns
+      - ":^inner_product"
+    allowed_devices:
+      - ":^det:?.*"  # Use regular expression patterns
+      - ":^motor:?.*"
+      - ":^sim_bundle_A:?.*"
+    forbidden_devices:
+      - ":^det[3-5]$:?.*" # Use regular expression patterns
+      - ":^motor\\d+$:?.*"
+    allowed_functions:
+      - ":element$"
+      - ":elements$"
+      - "function_sleep"
+      - "clear_buffer"
+    forbidden_functions:
+      - ":^_"  # All functions with names starting with '_'

apsbits/tests/__init__.py

@@ -0,0 +1 @@
+"""Test code for minimal instrument package."""

apsbits/tests/conftest.py

@@ -0,0 +1,39 @@
+"""
+Pytest fixtures for instrument tests.
+
+This module provides fixtures for initializing the RunEngine with devices,
+allowing tests to operate with device-dependent configurations without relying
+on the production startup logic.
+
+Fixtures:
+    runengine_with_devices: A RunEngine object in a session with devices configured.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from apsbits.demo_instrument.startup import RE
+from apsbits.demo_instrument.startup import make_devices
+from apsbits.utils.config_loaders import load_config
+
+
+@pytest.fixture(scope="session")
+def runengine_with_devices() -> Any:
+    """
+    Initialize the RunEngine with devices for testing.
+
+    This fixture calls RE with the `make_devices()` plan stub to mimic
+    the behavior previously performed in the startup module.
+
+    Returns:
+        Any: An instance of the RunEngine with devices configured.
+    """
+    # Load the configuration before testing
+    instrument_path = Path(__file__).parent.parent / "demo_instrument"
+    iconfig_path = instrument_path / "configs" / "iconfig.yml"
+    load_config(iconfig_path)
+
+    RE(make_devices())
+    return RE