Metadata-Version: 2.4
Name: apsbits
Version: 1.0.0rc4
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>
License: Copyright (c) 2023-2025, UChicago Argonne, LLC
        
        All Rights Reserved
        
        BITS
        
        BCDA, Advanced Photon Source, Argonne National Laboratory
        
        
        OPEN SOURCE LICENSE
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.  Software changes,
           modifications, or derivative works, should be noted with comments and
           the author and organization's name.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the names of UChicago Argonne, LLC or the Department of Energy
           nor the names of its contributors may be used to endorse or promote
           products derived from this software without specific prior written
           permission.
        
        4. The software and the end-user documentation included with the
           redistribution, if any, must include the following acknowledgment:
        
           "This product includes software produced by UChicago Argonne, LLC
           under Contract No. DE-AC02-06CH11357 with the Department of Energy."
        
        ****************************************************************************
        
        DISCLAIMER
        
        THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND.
        
        Neither the United States GOVERNMENT, nor the United States Department
        of Energy, NOR uchicago argonne, LLC, nor any of their employees, makes
        any warranty, express or implied, or assumes any legal liability or
        responsibility for the accuracy, completeness, or usefulness of any
        information, data, apparatus, product, or process disclosed, or
        represents that its use would not infringe privately owned rights.
        
        ****************************************************************************
        
Project-URL: Homepage, https://BCDA-APS.github.io/BITS/
Project-URL: Bug Tracker, https://github.com/BCDA-APS/BITS/issues
Keywords: bluesky,queueserver
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: License :: Freely Distributable
Classifier: License :: Public Domain
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.11
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-widgets
Requires-Dist: bluesky
Requires-Dist: caproto
Requires-Dist: databroker==1.2.5
Requires-Dist: guarneri
Requires-Dist: ipython
Requires-Dist: jupyterlab
Requires-Dist: ophyd-registry
Requires-Dist: ophyd
Requires-Dist: PyQt5>5.15
Requires-Dist: pyRestTable
Requires-Dist: pysumreg
Requires-Dist: qtpy
Requires-Dist: toml
Requires-Dist: tomli
Requires-Dist: tomli-w
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: doc
Requires-Dist: babel; extra == "doc"
Requires-Dist: ipykernel; extra == "doc"
Requires-Dist: jinja2; extra == "doc"
Requires-Dist: markupsafe; extra == "doc"
Requires-Dist: myst_parser; extra == "doc"
Requires-Dist: nbsphinx; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: pygments-ipython-console; extra == "doc"
Requires-Dist: pygments; extra == "doc"
Requires-Dist: sphinx-design; extra == "doc"
Requires-Dist: sphinx-tabs; extra == "doc"
Requires-Dist: sphinx; extra == "doc"
Provides-Extra: all
Requires-Dist: apsbits[dev,doc]; extra == "all"
Dynamic: license-file

# APSBITS: Template Package for Bluesky Instruments

| PyPI | Coverage |
| --- | --- |
[![PyPi](https://img.shields.io/pypi/v/apsbits.svg)](https://pypi.python.org/pypi/apsbits) | [![Coverage Status](https://coveralls.io/repos/github/BCDA-APS/BITS/badge.svg?branch=main)](https://coveralls.io/github/BCDA-APS/BITS?branch=main) |

BITS: **B**luesky **I**nstrument **T**emplate **S**tructure

Template of a Bluesky Data Acquisition Instrument in console, notebook, &
queueserver.

## Installing the BITS Package for Development
```
git clone github.com:BCDA-APS/BITS.git
cd BITS
conda create -y -n BITS_env python=3.11 pyepics
conda activate BITS_env
pip install -e ."[all]"
```

## Creating a New Instrument
```bash
export ENV_NAME=BITS_env

conda create -y -n $ENV_NAME python=3.11 pyepics
conda activate $ENV_NAME
pip install apsbits
```


## Creating a New Instrument
```bash
export YOUR_INSTRUMENT_NAME=YOUR_INSTRUMENT_NAME
create-bits $YOUR_INSTRUMENT_NAME "src/"
pip install -e ."[all]"
```


## IPython console Start

To start the bluesky instrument session in a ipython execute the next command in a terminal:

```bash
ipython
```

## Jupyter Notebook Start
Start JupyterLab, a Jupyter notebook server, or a notebook, VSCode.

## Starting the BITS Package

```py
from YOUR_INSTRUMENT_NAME.startup import *
```

## Run Sim Plan Demo

To run some simulated plans that ensure the installation worked as expected
please run the next commands inside an ipython session or a jupyter notebook
after starting the data acquisition:

```py
RE(sim_print_plan())
RE(sim_count_plan())
RE(sim_rel_scan_plan())
```

See this [example](./docs/source/demo.ipynb).

## Configuration files

The files that can be configured to adhere to your preferences are:

- `configs/iconfig.yml` - configuration for data collection
- `configs/logging.yml` - configuration for session logging to console and/or files
- `qserver/qs-config.yml`    - contains all configuration of the QS host process. See the [documentation](https://blueskyproject.io/bluesky-queueserver/manager_config.html) for more details of the configuration.

## queueserver

The queueserver has a host process that manages a RunEngine. Client sessions
will interact with that host process.

### Run a queueserver host process

Use the queueserver host management script to start the QS host process.  The
`restart` option stops the server (if it is running) and then starts it.  This is
the usual way to (re)start the QS host process. Using `restart`, the process
runs in the background.

```bash
./qserver/qs_host.sh restart
```

### Run a queueserver client GUI

To run the gui client for the queueserver you can use the next command inside the terminal:

```bash
queue-monitor &
```

### Shell script explained

A [shell script](./qserver/qs_host.sh) is used to start the QS host process. Below
are all the command options, and what they do.

```bash
(bstest) $ ./qserver/qs_host.sh help
Usage: qs_host.sh {start|stop|restart|status|checkup|console|run} [NAME]

    COMMANDS
        console   attach to process console if process is running in screen
        checkup   check that process is running, restart if not
        restart   restart process
        run       run process in console (not screen)
        start     start process
        status    report if process is running
        stop      stop process

    OPTIONAL TERMS
        NAME      name of process (default: bluesky_queueserver-)
```

Alternatively, run the QS host's startup command directly within the `./qserver/`
subdirectory.

```bash
cd ./qserver
start-re-manager --config=./qs-config.yml
```

## Testing

Use this command to run the test suite locally:

```bash
pytest -vvv --lf ./src
```

## Documentation

<details>
<summary>prerequisite</summary>

To build the documentation locally, install [`pandoc`](https://pandoc.org/) in
your conda environment:

```bash
conda install conda-forge::pandoc
```

</details>

Use this command to build the documentation locally:

```bash
make -C docs clean html
```

Once the documentation builds, view the HTML pages using your web browser:

```bash
BROWSER ./docs/build/html/index.html &
```

### Adding to the documentation source

The documentation source is located in files and directories under
`./docs/source`.  Various examples are provided.

Documentation can be added in these formats:
[`.rst`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
(reStructured text), [`.md`](https://en.wikipedia.org/wiki/Markdown) (markdown),
and [`.ipynb`](https://jupyter.org/) (Jupyter notebook). For more information,
see the [Sphinx](https://www.sphinx-doc.org/) documentation.

## Warnings

### Bluesky Queueserver

The QS host process writes files into the `qserver/` directory. This directory can be
relocated. However, it should not be moved into the instrument package since
that might be installed into a read-only directory.

## How-To Guides
### How to use the template

Consider renaming this `instrument` package to be more clear that is specific to *this*
instrument.  This will be the name by which it is `pip` installed and also used with
`import`.  Let's use an example instrument package name `my_instrument` below to show which parts are edited.

1) Click on use as template button
2) Adjust the following parameters in the following files:
    - `pyproject.toml`
        - `[project]` `name =` *example: `my_instrument`*
        - `[project.urls]`  *change URLs for your repo*
        - `[tool.setuptools]` `package-dir = {"instrument" = "src/instrument"}` *example: `{"my_instrument" = "src/instrument"}`*
    - `src/instrument/init.py`
        - `__package__ = "instrument"` *example: `"my_instrument"`*
    - `src/instrument/configs/iconfig.yml`
        - `DATABROKER_CATALOG:` *change from `temp` to your catalog's name*
        - `beamline_id:` *one word beamline name (such as known by APS scheduling system)*
        - `instrument_name:` *descriptive name of your beamline*
        - `DM_SETUP_FILE:` *Path to DM bash setup file, comment out if you do not have*
        - `BEC:` *adjust for your preferences*
    - `qserver/qs-config.yml`
        - `startup_module: instrument.startup` *example: `my_instrument.startup`*
    - `docs/source/conf.py`
        - `import instrument` *example `import my_instrument`*
        - `project = "instrument"` *example: `"my_instrument"`*
        - `version = instrument.__version__` *example: `my_instrument.__version__`*

- [APS Data Management Plans](./docs/source/guides/dm.md)
