diff --git a/doc/architectural_decisions/001-repo-structure.md b/doc/architectural_decisions/001-repo-structure.md index 0f6e1db..9f95122 100644 --- a/doc/architectural_decisions/001-repo-structure.md +++ b/doc/architectural_decisions/001-repo-structure.md @@ -1,6 +1,6 @@ # Repository structure -## Status +### Status Current diff --git a/doc/architectural_decisions/004-use-scipp.md b/doc/architectural_decisions/004-use-scipp.md index efccade..e279590 100644 --- a/doc/architectural_decisions/004-use-scipp.md +++ b/doc/architectural_decisions/004-use-scipp.md @@ -8,11 +8,11 @@ Current A decision needs to be made about whether to use scipp, numpy, uncertainties or develop our own library for the purpose of providing support for generating uncertanties on our counts data. -# Decision +## Decision We will be using scipp. -# Justification & Consequences +## Justification & Consequences - `scipp` is being developed at ESS with past input from STFC, so is well suited for neutron counts data. - `scipp` has a `numpy`-like interface but handles units and uncertainties by default under-the-hood. diff --git a/doc/logging/logger.md b/doc/dev/logging.md similarity index 63% rename from doc/logging/logger.md rename to doc/dev/logging.md index 98d0aac..997dfa1 100644 --- a/doc/logging/logger.md +++ b/doc/dev/logging.md @@ -1,7 +1,10 @@ -# Bluesky logger +# Logging -To invoke the bluesky logger, import as `from ibex_bluesky_core.logger import logger` and use it at the desired level: -`logger.blueskylogger.warning("Message to be logged")` +To invoke the bluesky logger, import and use it at the desired level: +```python +from ibex_bluesky_core.logger import logger +logger.blueskylogger.warning("Message to be logged") +``` The logger utilizes a `TimedRotatingFileHandler` defined in the `logging.conf` file that rolls over the log at midnight. The default logging level is defined at `INFO`. This means that events of lesser severity will not be logged. To change the default level, change level attribute of logger_blueskycore in the `logging.conf` diff --git a/doc/index.rst b/doc/index.rst index 4e8e0c7..d43636b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,7 +3,80 @@ Welcome to ibex_bluesky_core's documentation! ============================================= -This documentation contains information for the bluesky plan stubs & devices for use at ISIS. +``ibex_bluesky_core`` is a library of common ``bluesky`` functionality and ``ophyd-async`` +devices for use on the ISIS neutron & muon source's beamlines. + +`Bluesky `_ is a generic data acquisition +framework, which started at NSLS-ii but is developed as a multi-facility collaboration. Bluesky +provides concepts such as "scanning" in a generic way. + +`ophyd-async `_ is a python device +abstraction library, which allows bluesky to communicate with an underlying control system +(EPICS/IBEX, in our case). + +``ibex_bluesky_core`` provides: + +- Central configuration for core bluesky classes, such as the ``RunEngine``. +- ``RunEngine`` Callbacks customized for use at ISIS: file writing, plotting, fitting, ... +- Central implementations of ISIS device classes using ``ophyd-async``: Blocks, DAE, ... +- Bluesky or scanning-related utilities which are useful across multiple beamlines. + + +Overview +======== + +.. note:: + + bluesky is a very flexible data acquisition framework. The following example illustrates a minimal scan, + not the full extent of bluesky's functionality. + +Using ``ibex_bluesky_core``, one can define some simple instrument-specific devices:: + + from ibex_bluesky_core.devices.block import block_r, block_mot + + mot = block_mot("mot") # An IBEX block pointing at a motor + det = block_r(float, "p5") # A readback block + +And define a simple step-scan which uses those devices:: + + import bluesky.plans as bp + from ophyd_async.plan_stubs import ensure_connected + + def my_plan(start: float, stop: float, num: int): + yield from ensure_connected(det, mot, force_reconnect=True) + yield from bp.scan([det], mot, start, stop, num) + +After which, a simple scan can be run by a user:: + + from ibex_bluesky_core.run_engine import get_run_engine + + # A bluesky RunEngine instance, already available if using IBEX GUI + RE = get_run_engine() + + # Scan "mot" from 0 to 10 in 5 steps, reading "my_detector" at each step. + RE(my_plan(0, 10, 5)) + +That plan may then also use: + +- Other `experimental plans `_ or + `plan stubs `_, to build up more complex + plans. +- `Callbacks `_ provided by either + ``ibex_bluesky_core`` or ``bluesky``, which do something with the results of the scan: live + fitting, live plotting, file-writing, ... +- `Simulation facilities `_ provided by + bluesky, to check for problems before the plan is run +- And a range of other functionality! + +See the `manual system tests `_ for +some full runnable examples of complex plans, using a wider range of bluesky functionality. + +The reference documentation below lists the functionality that has been implemented in ``ibex_bluesky_core``, +however the vast majority of `bluesky `_ functionality remains +available, and the advanced user is also encouraged to read that documentation. + +Reference documentation +======================= .. toctree:: :maxdepth: 2 @@ -44,6 +117,7 @@ This documentation contains information for the bluesky plan stubs & devices for :titlesonly: :caption: Architectural decisions :glob: + :maxdepth: 1 architectural_decisions/*