nbs-bl 0.2.0__tar.gz

nbs_bl-0.2.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      url: https://pypi.org/p/nbs-bl
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

nbs_bl-0.2.0/.gitignore

@@ -0,0 +1,82 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+venv/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/build/
+docs/source/generated/
+
+# pytest
+.pytest_cache/
+
+# PyBuilder
+target/
+
+# Editor files
+#mac
+.DS_Store
+*~
+
+#vim
+*.swp
+*.swo
+
+#pycharm
+.idea/
+
+#VSCode
+.vscode/
+
+#Ipython Notebook
+.ipynb_checkpoints

nbs_bl-0.2.0/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

nbs_bl-0.2.0/LICENSE

@@ -0,0 +1,13 @@
+NIST Software Licensing Statement 
+
+  
+
+NIST-developed software is provided by NIST as a public service. You may use, copy, and distribute copies of the software in any medium, provided that you keep intact this entire notice. You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the software. 
+
+  
+
+NIST-developed software is expressly provided "AS IS." NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE SOFTWARE. 
+
+  
+
+You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. The software developed by NIST employees is not subject to copyright protection within the United States. 

nbs_bl-0.2.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: nbs-bl
+Version: 0.2.0
+Summary: NBS Beamline Framework
+Project-URL: homepage, https://github.com/xraygui/nbs-bl
+Author-email: Charles Titus <ctitus@bnl.gov>
+License-File: LICENSE
+Keywords: beamline,bluesky,nsls-ii
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Public Domain
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: bluesky
+Requires-Dist: bluesky-queueserver
+Requires-Dist: databroker>=2.0.0b67
+Requires-Dist: ipython
+Requires-Dist: nbs-core>=0.1
+Requires-Dist: numpy
+Requires-Dist: numpydoc
+Requires-Dist: ophyd
+Requires-Dist: redis-json-dict
+Requires-Dist: tomli; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# NSLS-II Beamline Support Library
+
+A Python library for beamline operation and control at NSLS-II, providing configuration management, device control, and scan plans.
+
+## Features
+
+- TOML-based beamline configuration system
+- Device control and monitoring
+- Scan plans and utilities
+- Simulation capabilities for offline testing
+- Integration with Bluesky/Ophyd ecosystem
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/xraygui/nbs-bl.git
+cd nbs-bl
+
+# Install in development mode
+pip install -e .
+```
+
+## Dependencies
+
+- Python 3.8+
+- Bluesky
+- Ophyd
+- NumPy
+- nbs-core
+
+## Documentation
+
+Documentation is available at [https://nbs-bl.readthedocs.io](https://nbs-bl.readthedocs.io)
+
+## Configuration
+
+The library uses TOML configuration files to define beamline devices and settings:
+- `beamline.toml`: General beamline configuration
+- `devices.toml`: Device-specific configuration
+
+See the [configuration reference](https://nbs-bl.readthedocs.io/configuration_reference.html) for detailed documentation.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details. 

nbs_bl-0.2.0/README.md

@@ -0,0 +1,46 @@
+# NSLS-II Beamline Support Library
+
+A Python library for beamline operation and control at NSLS-II, providing configuration management, device control, and scan plans.
+
+## Features
+
+- TOML-based beamline configuration system
+- Device control and monitoring
+- Scan plans and utilities
+- Simulation capabilities for offline testing
+- Integration with Bluesky/Ophyd ecosystem
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/xraygui/nbs-bl.git
+cd nbs-bl
+
+# Install in development mode
+pip install -e .
+```
+
+## Dependencies
+
+- Python 3.8+
+- Bluesky
+- Ophyd
+- NumPy
+- nbs-core
+
+## Documentation
+
+Documentation is available at [https://nbs-bl.readthedocs.io](https://nbs-bl.readthedocs.io)
+
+## Configuration
+
+The library uses TOML configuration files to define beamline devices and settings:
+- `beamline.toml`: General beamline configuration
+- `devices.toml`: Device-specific configuration
+
+See the [configuration reference](https://nbs-bl.readthedocs.io/configuration_reference.html) for detailed documentation.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details. 

nbs_bl-0.2.0/docs/conf.py

@@ -0,0 +1,41 @@
+"""Sphinx configuration for nbs-bl documentation."""
+
+project = "NBS-BL"
+copyright = "2024, NSLS-II"
+author = "NSLS-II"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_rtd_theme",
+    "myst_parser",  # For markdown support
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# HTML output options
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# Intersphinx mapping
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "ophyd": ("https://blueskyproject.io/ophyd/", None),
+    "bluesky": ("https://blueskyproject.io/bluesky/", None),
+}
+
+# Napoleon settings
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = True
+
+# MyST settings
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]

nbs_bl-0.2.0/docs/configuration_reference.md

@@ -0,0 +1,210 @@
+# Beamline Configuration Reference
+
+## Overview
+The beamline configuration system uses TOML files to define the hardware, settings, and behavior of a beamline. The configuration is split into two main files:
+- `beamline.toml`: Core beamline settings and capabilities
+- `devices.toml`: Hardware device definitions and properties
+
+## beamline.toml Reference
+
+### Configuration Section
+```toml
+[configuration]
+# List of groups that should be automatically added to baseline readings
+baseline = ["motors", "vacuum", "shutters"]
+
+# Core beamline capabilities
+has_slits = true          # Whether beamline has slit devices
+has_motorized_samples = true    # Whether beamline has motorized sample stages
+has_motorized_eref = false     # Whether beamline has motorized energy reference
+has_polarization = false       # Whether beamline has polarization control
+```
+
+### Detector Sets
+Define groups of detectors that are commonly used together.
+```toml
+[detector_sets.default]
+primary = "main_detector"        # Primary detector for measurements
+normalization = "i0"            # Detector used for normalization
+reference = "ir"                # Reference detector
+
+[detector_sets.transmission]
+primary = "it"
+normalization = "i0"
+reference = "ir"
+```
+
+### Settings
+General beamline settings and module configuration.
+```toml
+[settings]
+# Python modules to load at startup
+# nbs_bl provides a default, but you should
+# define your own in your beamline's code package
+modules = ["nbs_bl.startup"]
+
+# Plan load files, located in the ipython startup directory
+# Keys should correspond to entrypoints in the beamline's code package
+[settings.plans]
+xas = ["xas.toml"]
+xps = ["xps.toml"]
+
+# Redis configuration for RE.md
+[settings.redis.md]
+host = "redis"
+prefix = "beamline_name"
+
+# Redis configuration for other metadata to share with QueueServer
+[settings.redis.info]
+host = "redisInfo"
+prefix = ""
+port = 60737
+db = 1
+```
+
+## devices.toml Reference
+
+### Device Configuration Format
+Each device entry follows this general structure:
+```toml
+[device_name]
+# Required fields
+_target = "package.module.DeviceClass"  # Python class to instantiate
+name = "human_readable_name"            # Display name
+prefix = "PV:PREFIX:"                   # EPICS PV prefix
+
+# Optional fields
+_defer_loading = false                  # Whether to defer device loading
+_add_to_ns = true                       # Add to IPython namespace
+_load_order = 1                         # Load order, if device must be loaded after others
+_baseline = true                        # Override for group baseline setting
+description = "Device description"      # Human-readable description
+
+# Group membership
+_group = "group_name"                   # Device groups
+_role = "role_name"                     # Device roles
+
+# Device-specific parameters
+param1 = value1
+param2 = value2
+```
+
+### Common Device Types
+
+#### Motors
+```toml
+[sample_x]
+_target = "nbs_bl.devices.motors.DeadbandEpicsMotor"
+_group = "motors"
+name = "Sample X"
+prefix = "MOTOR:X:"
+tolerance = 0.1
+```
+
+#### Detectors
+```toml
+[main_detector]
+_target = "nbs_bl.devices.detectors.ophScalar"
+_group = "detectors"
+name = "Main Detector"
+prefix = "DET:MAIN:"
+description = "Main measurement detector"
+rescale = 1.0
+```
+
+#### Sample Holders
+```toml
+[sample_holder]
+_target = "nbs_bl.devices.sampleholders.Manipulator4AxBase"
+name = "Sample Manipulator"
+prefix = "MANIP:"
+_group = "manipulators"
+_role = "primary_sampleholder"
+```
+
+#### Shutters
+```toml
+[photon_shutter]
+_target = "nbs_bl.devices.shutters.EPS_Shutter"
+name = "Photon Shutter"
+prefix = "PS:"
+_group = "shutters"
+openval = 1
+closeval = 0
+```
+
+## Best Practices
+
+### Device Organization
+1. Group related devices together in the configuration
+2. Use consistent naming conventions:
+   - Lowercase with underscores for device keys
+   - Descriptive human-readable names
+   - Clear, consistent PV prefixes
+3. Document special requirements or dependencies
+
+### Deferred Loading
+Use `_defer_loading = true` for devices that:
+- Are not always available
+- Have long initialization times
+- Are only needed for specific operations
+- May conflict with other devices
+
+Use `_load_order` to control devices which:
+- have dependencies on other devices
+
+### Device Groups
+Standard group names include:
+- `motors`: All motor devices
+- `detectors`: All detector devices
+- `shutters`: Beam and safety shutters
+- `gauges`: Vacuum gauges
+- `manipulators`: Sample manipulation devices
+- `mirrors`: Beamline optics
+- `slits`: Beam-defining slits
+
+### Device Roles
+Common roles include:
+- `beam_current`: Storage ring current measurement
+- `beam_status`: Beam availability status
+- `default_shutter`: Primary photon shutter
+- `energy`: Monochromator or energy setting device
+- `intensity_detector`: Primary intensity measurement
+- `primary_sampleholder`: Main sample manipulation stage
+- `reference_sampleholder`: Reference sample stage
+- `slits`: Primary beam-defining slits
+
+### Redis Configuration
+1. Use separate configurations for metadata and info
+2. Choose meaningful prefixes to avoid conflicts
+3. Document required Redis setup and connectivity
+
+## Configuration Validation
+Before deploying a new configuration:
+1. Verify all required fields are present
+2. Check PV connectivity
+3. Test device initialization
+4. Validate group and role assignments
+5. Ensure Redis connectivity
+6. Test deferred loading behavior
+
+## Common Issues and Solutions
+
+### Device Loading Failures
+- Verify PV prefix is correct
+- Check EPICS IOC is running
+- Ensure network connectivity
+- Verify required dependencies are installed
+
+### Redis Connectivity
+- Check Redis server is running
+- Verify port and host settings
+- Ensure network allows Redis connections
+- Check database permissions
+
+### Group and Role Conflicts
+- Verify no duplicate role assignments
+- Check group membership logic
+- Validate device compatibility
+- Test interaction between grouped devices
+```