Skip to content

Commit

Permalink
Added usage info to the README file.
Browse files Browse the repository at this point in the history
  • Loading branch information
canismarko committed Sep 20, 2024
1 parent 1aad529 commit 22ea318
Showing 1 changed file with 119 additions and 4 deletions.
123 changes: 119 additions & 4 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,13 +1,128 @@
===============================
guarneri
===============================
==========================
Guarneri Instrument Maker
==========================


.. image:: https://img.shields.io/pypi/v/guarneri.svg
:target: https://pypi.python.org/pypi/guarneri


guarneri
A package for creating Ophyd and Ophyd-async devices from configuration
files.

Instead of instantiating devices directly in python, Guarneri reads a
configuration file and creates/connects the devices for you. This
provides the following benefits:

1) Beamline configuration is in a human-readable configuration file (e.g. TOML).
2) Other tools can modify the configuration file if needed.
3) Devices can be connected in parallel.
4) Missing devices are handled gracefully.
5) Devices can be simulated/mocked by changing single value in the config file.


Usage
-----

Let's say **you have some ophyd and ophyd-async devices** defined
(with type hints) in a file called ``devices.py``. This is not
specific to guarneri, just regular Ophyd.

.. code-block:: python
:caption: devices.py
from ophyd_async.epics import epics_signal_rw
from ophyd_async.core import AsyncDevice
from ophyd import Device, Component
from guarneri import Instrument
class MyDevice(Device):
description = Component(".DESC")
class MyAsyncDevice(AsyncDevice):
def __init__(self, prefix: str, name: str = ""):
self.description = epics_signal_rw(str, f"{prefix}.DESC")
super().__init__(name=name)
def area_detector_factory(hdf: bool=True):
# Create devices here using the arguments
area_detector = ...
return area_detector
Instead of instantiating these in a python startup script, Guarneri
will let you **create devices from a TOML configuration file**. First
we create a TOML file (e.g. ``instrument.toml``) with the necessary parameters, these map
directly onto the arguments of the device's ``__init__()``, or the
arguments of a factory that returns a device.


.. code-block:: toml
:caption: instrument.toml
[my_device.device1]
prefix = '255id:'
[async_device.device3]
prefix = '255id:'
[area_detector.sim_det]
hdf = true
Then in your beamline startup code, create a Guarneri instrument and
load the config files.

.. code-block:: python
:caption: instrument.py
from io import StringIO
from devices import MyDevice, MyAsyncDevice, area_detector_factory
# Prepare the instrument device
instrument = Instrument({
"my_device": MyDevice,
"async_device": MyAsyncDevice,
"area_detector": area_detector_factory,
})
# Create the devices from the TOML configuration file
instrument.load_config_files("instrument.toml")
# Optionally connect all the devices
await instrument.connect_devices()
# Now use the devices for science!
instrument.devices['device_1'].description.get()
The first argument to ``guarneri.Instrument.__init__()`` is a
mapping of TOML section names to device classes. Guarneri then
introspects the device or factory to decide which TOML keys and types
are valid. In the above example, the heading ``[my_device.device1]``
will create an instance of ``MyDevice()`` with the name ``"device1"``.


What About Happi?
-----------------

Happi has a similar goal to Guarneri, but with a different
scope. While Happi is meant for facility-level configuration (e.g.
LCLS), Guarneri is aimed at individual beamlines at a synchrotron.
Happi uses ``HappiItem`` classes with ``ItemInfo``
objects to describe the devices definitions, while Guarneri uses the
device classes themselves. Happi provides a python client for adding
and modifying the devices, while Guarneri uses human-readable
configuration files.

**Which one is better?** Depends on what you're trying to do. If you
want a **flexible and scalable** system the **shares devices across a
facility**, try Happi. If you want a way to **get devices running
quickly** on your beamline before users show up, try Guarneri.


Documentation
-------------
Expand Down

0 comments on commit 22ea318

Please sign in to comment.