From 00b429b468f18bfc5b0683707608e2f3b11ec6aa Mon Sep 17 00:00:00 2001 From: architeuthidae Date: Tue, 13 Aug 2024 11:40:22 +0800 Subject: [PATCH] doc: Refactor management system reference --- doc/manual/core_drivers_reference.rst | 2 +- doc/manual/core_language_reference.rst | 4 +- doc/manual/index.rst | 1 + doc/manual/management_system.rst | 91 +---------------------- doc/manual/mgmt_system_reference.rst | 99 ++++++++++++++++++++++++++ 5 files changed, 104 insertions(+), 93 deletions(-) create mode 100644 doc/manual/mgmt_system_reference.rst diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst index ffad04bc5..c7f8de3d6 100644 --- a/doc/manual/core_drivers_reference.rst +++ b/doc/manual/core_drivers_reference.rst @@ -1,4 +1,4 @@ -Core drivers reference +Core real-time drivers ====================== These drivers are for the core device and the peripherals closely integrated into it, which do not use the controller mechanism. diff --git a/doc/manual/core_language_reference.rst b/doc/manual/core_language_reference.rst index 3f991f6b0..9b17e9432 100644 --- a/doc/manual/core_language_reference.rst +++ b/doc/manual/core_language_reference.rst @@ -1,5 +1,5 @@ -Core language reference -======================= +Core language and environment +============================= The most commonly used features from the ARTIQ language modules and from the core device modules are bundled together in ``artiq.experiment`` and can be imported with ``from artiq.experiment import *``. diff --git a/doc/manual/index.rst b/doc/manual/index.rst index 3e5ca1622..d862942b3 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -51,6 +51,7 @@ ARTIQ manual main_frontend_tools core_language_reference core_drivers_reference + mgmt_system_reference utilities .. toctree:: diff --git a/doc/manual/management_system.rst b/doc/manual/management_system.rst index cb40ffc18..dc807b9dd 100644 --- a/doc/manual/management_system.rst +++ b/doc/manual/management_system.rst @@ -102,93 +102,4 @@ The experiment must place the hardware in a safe state and disconnect from the c Accessing the :meth:`pause` and :meth:`~artiq.master.scheduler.Scheduler.check_pause` methods is done through a virtual device called ``scheduler`` that is accessible to all experiments. The scheduler virtual device is requested like regular devices using :meth:`~artiq.language.environment.HasEnvironment.get_device` (``self.get_device()``) or :meth:`~artiq.language.environment.HasEnvironment.setattr_device` (``self.setattr_device()``). -:meth:`~artiq.master.scheduler.Scheduler.check_pause` can be called (via RPC) from a kernel, but :meth:`pause` must not be. - -Scheduler API reference ------------------------ - -The scheduler is exposed to the experiments via a virtual device called ``scheduler``. It can be requested like any regular device, and the methods below, as well as :meth:`pause`, can be called on the returned object. - -The scheduler virtual device also contains the attributes ``rid``, ``pipeline_name``, ``priority`` and ``expid``, which contain the corresponding information about the current run. - -.. autoclass:: artiq.master.scheduler.Scheduler - :members: - -Client control broadcasts (CCBs) --------------------------------- - -Client control broadcasts are requests made by experiments for clients to perform some action. Experiments do so by requesting the ``ccb`` virtual device and calling its ``issue`` method. The first argument of the issue method is the name of the broadcast, and any further positional and keyword arguments are passed to the broadcast. - -CCBs are used by experiments to configure applets in the dashboard, for example for plotting purposes. - -.. autoclass:: artiq.dashboard.applets_ccb.AppletsCCBDock - :members: - -.. _applet-references: - -Applet request interfaces -------------------------- - -Applet request interfaces allow applets to perform actions on the master database and set arguments in the dashboard. Applets may inherit from ``artiq.applets.simple.SimpleApplet`` and call the methods defined below through the ``req`` attribute. - -Embedded applets should use ``AppletRequestIPC`` while standalone applets use ``AppletRequestRPC``. ``SimpleApplet`` automatically chooses the correct interface on initialization. - -.. autoclass:: artiq.applets.simple._AppletRequestInterface - :members: - -Applet entry area ------------------ - -Argument widgets can be used in applets through the :class:`~artiq.gui.applets.EntryArea` class. Below is a simple example code snippet: :: - - entry_area = EntryArea() - - # Create a new widget - entry_area.setattr_argument("bl", BooleanValue(True)) - - # Get the value of the widget (output: True) - print(entry_area.bl) - - # Set the value - entry_area.set_value("bl", False) - - # False - print(entry_area.bl) - -The :class:`~artiq.gui.applets.EntryArea` object can then be added to a layout and integrated with the applet GUI. Multiple :class:`~artiq.gui.applets.EntryArea` objects can be used in a single applet. - -.. class:: artiq.gui.applets.EntryArea - - .. method:: setattr_argument(name, proc, group=None, tooltip=None) - - Sets an argument as attribute. The names of the argument and of the - attribute are the same. - - :param name: Argument name - :param proc: Argument processor, for example :class:`~artiq.language.environment.NumberValue` - :param group: Used to group together arguments in the GUI under a common category - :param tooltip: Tooltip displayed when hovering over the entry widget - - .. method:: get_value(name) - - Get the value of an entry widget. - - :param name: Argument name - - .. method:: get_values() - - Get all values in the :class:`~artiq.gui.applets.EntryArea` as a dictionary. Names are stored as keys, and argument values as values. - - .. method:: set_value(name, value) - - Set the value of an entry widget. The change is temporary and will reset to default when the reset button is clicked. - - :param name: Argument name - :param value: Object representing the new value of the argument. For :class:`~artiq.language.scan.Scannable` arguments, this parameter - should be a :class:`~artiq.language.scan.ScanObject`. The type of the :class:`~artiq.language.scan.ScanObject` will be set as the selected type when this function is called. - - .. method:: set_values(values) - - Set multiple values from a dictionary input. Calls :meth:`set_value` for each key-value pair. - - :param values: Dictionary with names as keys and new argument values as values. +:meth:`~artiq.master.scheduler.Scheduler.check_pause` can be called (via RPC) from a kernel, but :meth:`pause` must not be. \ No newline at end of file diff --git a/doc/manual/mgmt_system_reference.rst b/doc/manual/mgmt_system_reference.rst new file mode 100644 index 000000000..76b5a0bb3 --- /dev/null +++ b/doc/manual/mgmt_system_reference.rst @@ -0,0 +1,99 @@ +Management system interface +=========================== + +ARTIQ makes certain provisions to allow interactions between different components when using the :doc:`management system `. An experiment may make requests of the master or clients using virtual devices to represent the necessary line of communication; applets may interact with databases, the dashboard, and directly with the user (through argument widgets). This page collects the references for these features. + +In experiments +-------------- + +``scheduler`` virtual device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scheduler is exposed to the experiments via a virtual device called ``scheduler``. It can be requested like any other device, and the methods below, as well as :meth:`pause`, can be called on the returned object. + +The scheduler virtual device also contains the attributes ``rid``, ``pipeline_name``, ``priority`` and ``expid``, which contain the corresponding information about the current run. + +.. autoclass:: artiq.master.scheduler.Scheduler + :members: + +``ccb`` virtual device +^^^^^^^^^^^^^^^^^^^^^^ + +Client control broadcasts (CCBs) are requests made by experiments for clients to perform some action. Experiments do so by requesting the ``ccb`` virtual device and calling its ``issue`` method. The first argument of the issue method is the name of the broadcast, and any further positional and keyword arguments are passed to the broadcast. + +CCBs are especially used by experiments to configure applets in the dashboard, for example for plotting purposes. + +.. autoclass:: artiq.dashboard.applets_ccb.AppletsCCBDock + :members: + +In applets +---------- + +.. _applet-references: + +Applet request interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Applet request interfaces allow applets to perform actions on the master database and set arguments in the dashboard. Applets may inherit from ``artiq.applets.simple.SimpleApplet`` and call the methods defined below through the ``req`` attribute. + +Embedded applets should use ``AppletRequestIPC``, while standalone applets use ``AppletRequestRPC``. ``SimpleApplet`` automatically chooses the correct interface on initialization. + +.. autoclass:: artiq.applets.simple._AppletRequestInterface + :members: + +Applet entry area +^^^^^^^^^^^^^^^^^ + +Argument widgets can be used in applets through the :class:`~artiq.gui.applets.EntryArea` class. Below is a simple example code snippet: :: + + entry_area = EntryArea() + + # Create a new widget + entry_area.setattr_argument("bl", BooleanValue(True)) + + # Get the value of the widget (output: True) + print(entry_area.bl) + + # Set the value + entry_area.set_value("bl", False) + + # False + print(entry_area.bl) + +The :class:`~artiq.gui.applets.EntryArea` object can then be added to a layout and integrated with the applet GUI. Multiple :class:`~artiq.gui.applets.EntryArea` objects can be used in a single applet. + +.. class:: artiq.gui.applets.EntryArea + + .. method:: setattr_argument(name, proc, group=None, tooltip=None) + + Sets an argument as attribute. The names of the argument and of the + attribute are the same. + + :param name: Argument name + :param proc: Argument processor, for example :class:`~artiq.language.environment.NumberValue` + :param group: Used to group together arguments in the GUI under a common category + :param tooltip: Tooltip displayed when hovering over the entry widget + + .. method:: get_value(name) + + Get the value of an entry widget. + + :param name: Argument name + + .. method:: get_values() + + Get all values in the :class:`~artiq.gui.applets.EntryArea` as a dictionary. Names are stored as keys, and argument values as values. + + .. method:: set_value(name, value) + + Set the value of an entry widget. The change is temporary and will reset to default when the reset button is clicked. + + :param name: Argument name + :param value: Object representing the new value of the argument. For :class:`~artiq.language.scan.Scannable` arguments, this parameter + should be a :class:`~artiq.language.scan.ScanObject`. The type of the :class:`~artiq.language.scan.ScanObject` will be set as the selected type when this function is called. + + .. method:: set_values(values) + + Set multiple values from a dictionary input. Calls :meth:`set_value` for each key-value pair. + + :param values: Dictionary with names as keys and new argument values as values. \ No newline at end of file