pybrid-computing 0.10.0__py3-none-any.whl

pybrid/redac/cluster.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+import typing
+from dataclasses import dataclass
+
+from .entities import Entity, Path, EntityType, EntityClass
+from .blocks import FunctionBlock, MBlock, UBlock, CBlock, IBlock
+
+
+@dataclass(kw_only=True)
+class Cluster(Entity):
+    """
+    A REDAC computation cluster.
+
+    The cluster is the smallest unit capable of an analog computation.
+    It always consists of two optional :class:`.blocks.MBlock` objects
+    and one mandatory :class:`.blocks.UBlock`, :class:`.blocks.CBlock` and :class:`.blocks.IBlock` each.
+    """
+    #: The first :class:`.blocks.MBlock` in this cluster. May be ``None`` if the slot is not filled.
+    m0block: typing.Optional[MBlock]
+    #: The second :class:`.blocks.MBlock` in this cluster. May be ``None`` if the slot is not filled.
+    m1block: typing.Optional[MBlock]
+    #: The :class:`.blocks.UBlock` in this cluster.
+    ublock: UBlock
+    #: The :class:`.blocks.CBlock` in this cluster.
+    cblock: CBlock
+    #: The :class:`.blocks.IBlock` in this cluster.
+    iblock: IBlock
+
+    @property
+    def children(self):
+        """
+        Generator iterating through child entities of type :class:`.blocks.FunctionBlock`.
+        Only returns blocks that are actually present (i.e. not ``None``).
+        """
+        yield from (block for block in self.blocks if block is not None)
+
+    @property
+    def blocks(self) -> tuple[typing.Optional[MBlock], typing.Optional[MBlock], UBlock, CBlock, IBlock]:
+        """
+        List of :class:`.blocks.FunctionBlock` objects in this cluster.
+        Returns ``None`` elements for blocks that are not present.
+        """
+        return self.m0block, self.m1block, self.ublock, self.cblock, self.iblock
+
+    @classmethod
+    def create_from_entity_type_tree(cls, path, tree):
+        # TODO: Refactor out common code
+        # Check information on self
+        this_entity_type = EntityType.pop_from_dict(tree)
+        assert this_entity_type.class_ is EntityClass.CLUSTER
+
+        # Generate child entities
+        blocks = []
+        for sub_path, sub_tree in tree.items():
+            if not sub_path.startswith('/'):
+                raise ValueError('Unexpected entities tree element. Expected only sub-paths to be left.')
+            path_ = path / Path((sub_path.removeprefix('/'),))
+            block = FunctionBlock.create_from_entity_type_tree(path_, sub_tree)
+            blocks.append(block)
+
+        # TODO: Less hard-coding :)
+        return cls(path=path, m0block=blocks[0], m1block=blocks[1], ublock=blocks[2], cblock=blocks[3],
+                   iblock=blocks[4])
+
+    def route(self, m_out: int, u_out: int, c_factor: float, m_in: int):
+        """
+        Convenience function to connect a signal from before the :class:`.blocks.UBlock` through a coefficient
+        on the :class:`.blocks.CBlock` and through the :class:`.blocks.IBlock` to an input on one of the
+        :class:`.blocks.MBlock` slots.
+
+        :param int m_out: Output index from one of the MBlocks, respectively input index of the UBlock.
+        :param int u_out: Output index of the UBlock, respectively index of the coefficient.
+        :param float c_factor: Factor of the coefficient.
+        :param int m_in: Input index of one of the MBlocks, respectively output index of the IBlock.
+        :return: ``None``
+        """
+        # TODO: Sanity checks and error handling
+        self.ublock.connect(m_out, u_out)
+        self.cblock.elements[u_out].factor = c_factor
+        self.iblock.connect(u_out, m_in)

pybrid/redac/computations.py

@@ -0,0 +1,30 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+from dataclasses import dataclass, field
+
+from pybrid.base.analog import Integration as BaseIntegration
+from pybrid.base.analog import ScalarMultiplication as BaseScalarMultiplication, \
+    ScalarMultiplicationFactor
+from pybrid.base.analog import Multiplication  # noqa
+
+
+@dataclass(kw_only=True)
+class Integration(BaseIntegration):
+    #: Initial value. Must be in range [-1.0, 1.0].
+    ic: float = 0.0
+    #: Time constant in :math:`\frac{1}{\mathrm{s}}`. Must be one of {100, 10000}.
+    k: int = 10_000
+
+    # Inherit __doc__
+    __doc__ = BaseIntegration.__doc__
+
+
+@dataclass(kw_only=True)
+class ScalarMultiplication(BaseScalarMultiplication):
+    #: Scalar factor α. Must be in range [-20.0, 20.0].
+    factor: float = field(default=ScalarMultiplicationFactor(min=-20.0, max=+20.0, default=1.0))
+
+    # Inherit __doc__
+    __doc__ = BaseScalarMultiplication.__doc__

pybrid/redac/computer.py

@@ -0,0 +1,42 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+from pybrid.base.hybrid import AnalogComputer
+
+from .blocks import FunctionBlock
+from .carrier import Carrier
+from .cluster import Cluster
+from .elements import ComputationElement
+from .entities import Path
+
+
+class REDAC(AnalogComputer):
+    """
+    Representation of the REDAC analog computer and its structure.
+    """
+    hierarchy = (Carrier, Cluster, FunctionBlock, ComputationElement)
+    entities: list[Carrier]
+
+    @property
+    def name(self) -> str:
+        return "REDAC"
+
+    @property
+    def carriers(self) -> list[Carrier]:
+        """The list of :class:`.Carrier` boards in this REDAC."""
+        return self.entities
+
+    @classmethod
+    def create_from_entity_type_tree(cls, type_tree):
+        carriers = []
+        for sub_path, sub_tree in type_tree.items():
+            carrier = Carrier.create_from_entity_type_tree(Path((sub_path,)), sub_tree)
+            carriers.append(carrier)
+        return cls(entities=carriers)
+
+    def __repr__(self):
+        return repr(self.entities)
+
+
+

pybrid/redac/controller.py

@@ -0,0 +1,141 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+import asyncio
+import logging
+import typing
+from asyncio import Future
+from uuid import UUID
+
+from pybrid.base.hybrid import BaseController
+
+from .computer import REDAC
+from .entities import Entity, Path
+from .protocol.messages import RunStateChangeMessage, RunDataMessage
+from .protocol.protocol import Protocol
+from .run import Run, RunState
+
+logger = logging.getLogger(__name__)
+
+
+class Controller(BaseController):
+    """
+    Abstraction of the REDAC hybrid controller.
+
+    The hybrid controller is an interface to all relevant functions to configure and control the REDAC.
+    It also collects all :class:`Run` instances started with it.
+
+    The controller object also holds references to the underlying protocol and transport objects and manages them.
+    """
+    computer: REDAC
+    protocol: Protocol
+    #: List of all runs started by this controller.
+    runs: dict[UUID, Run] = dict()
+    _ongoing_runs: dict[UUID, Future] = dict()
+
+    @classmethod
+    def get_run_implementation(cls) -> typing.Type[Run]:
+        """Returns the specific :class:`.Run` implementation used by the REDAC."""
+        return Run
+
+    async def start(self) -> None:
+        await super().start()
+        self.protocol.register_callback(RunStateChangeMessage, self.handle_run_state_change)
+        self.protocol.register_callback(RunDataMessage, self.handle_run_data)
+
+    def handle_run_state_change(self, msg: RunStateChangeMessage):
+        """A handler for incoming :class:`.RunStateChangeMessage` messages."""
+        logger.debug("Received run state change: %s.", msg)
+        if run := self.runs.get(msg.id, None):
+            run.state = RunState(msg.new)
+            if run.state.is_done():
+                self._ongoing_runs.pop(run.id_).set_result(run)
+        else:
+            logger.warning("Received run state change with unknown id %s.", msg.id)
+
+    def handle_run_data(self, msg: RunDataMessage):
+        """A handler for incoming :class:`.RunDataMessage` messages."""
+        if run := self.runs.get(msg.id, None):
+            adc_paths = [Path(msg.entity).join(f"ADC{idx}") for idx in range(run.daq.num_channels)]
+            for data_pkg in msg.data:
+                for channel, data_point in zip(adc_paths, data_pkg):
+                    run.data[channel].append(data_point)
+            last_t = len(run.data["t"])
+            run.data["t"].extend(range(last_t, last_t + len(msg.data)))
+
+    #  ██████  ██████  ███    ███ ███    ███  █████  ███    ██ ██████  ███████
+    # ██      ██    ██ ████  ████ ████  ████ ██   ██ ████   ██ ██   ██ ██
+    # ██      ██    ██ ██ ████ ██ ██ ████ ██ ███████ ██ ██  ██ ██   ██ ███████
+    # ██      ██    ██ ██  ██  ██ ██  ██  ██ ██   ██ ██  ██ ██ ██   ██      ██
+    #  ██████  ██████  ██      ██ ██      ██ ██   ██ ██   ████ ██████  ███████
+
+    async def hack(self, cmd: str, data: typing.Any) -> typing.Any:
+        """
+        Send the passed data as a 'hack' request, only used during development.
+        It allows to pass and receive arbitrary data to and from the hybrid controller.
+        """
+        return await self.protocol.hack_request(cmd, data)
+
+    async def get_computer(self) -> REDAC:
+        """
+        Retrieve the current hardware configuration of the REDAC.
+        """
+        entities = await self.protocol.get_entities()
+        computer = REDAC.create_from_entity_type_tree(entities)
+        return computer
+
+    async def set_computer(self, computer: REDAC):
+        """
+        Change the configuration of all carrier boards and sub-entities on the REDAC.
+
+        :param computer: The :class:`.REDAC` object containing the configuration to be set.
+        :return: None
+        """
+        for carrier in computer.carriers:
+            await self.set_config(carrier)
+
+    async def start_run(self, run: typing.Optional[Run] = None) -> Future:
+        """
+        Start a run (computation) on the REDAC.
+
+        :param run: The :class:`.Run` to be started, including its configuration. If None, a new run is created.
+        :return: An :class:`asyncio.Future` which can be awaited and will return the run object once it is done.
+        """
+        if run is None:
+            run = await self.create_run()
+        self.runs[run.id_] = run
+        self._ongoing_runs[run.id_] = run_future = asyncio.get_event_loop().create_future()
+        await self.protocol.start_run_request(run.id_, run.config, run.daq)
+        return run_future
+
+    async def start_and_await_run(self, run: typing.Optional[Run] = None, timeout=5) -> Run:
+        """
+        A convenience function which starts a run, blocks until it is completed and returns it.
+
+        :param run: The :class:`.Run` to be started, including its configuration. If None, a new run is created.
+        :param timeout: Timeout
+        :return: The completed :class:`.Run`.
+        """
+        run_future = await self.start_run(run)
+        await asyncio.wait_for(run_future, timeout=timeout)
+        return run_future.result()
+
+    async def set_config(self, entity: Entity):
+        """
+        Change the configuration of a singe entity.
+
+        :param entity: The entity to change.
+        :return: None
+        """
+        await self.protocol.set_config(entity)
+
+    async def reset(self, keep_calibration: bool = True, sync: bool = True):
+        """
+        Reset the hybrid controller and the analog computer to its initial configuration.
+
+        :param keep_calibration: Whether to keep the calibration.
+        :param sync: Whether to write the reset values to the hardware.
+        :return: None
+        """
+        await self.protocol.reset(keep_calibration=keep_calibration, sync=sync)

pybrid/redac/data.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+# TODO: Refactor out common code with Model-1 data exporters and make abstraction for command line
+
+import dataclasses
+import typing
+
+from pybrid.redac.run import Run
+
+
+# TODO: Implement a lookup for different data types
+# _REGISTRY = {}
+# def get_exporter(format):
+#     return _REGISTRY[format]
+
+
+class BaseExporter:
+    FORMAT = None
+
+    def export(self, run, **kwargs):
+        ...
+
+
+class DatExporter(BaseExporter):
+    FORMAT = "dat"
+
+    def __init__(self, file: typing.IO):
+        self._file = file
+
+    def _write_line(self, line=""):
+        self._file.write(line)
+        self._file.write("\n")
+
+    def _write_header_line(self, key, value):
+        self._write_line(f"# {key} = {value}")
+
+    def _write_header(self, run):
+        self._write_line("# Run result")
+        for key in ("id_", "created"):
+            self._write_header_line(key, getattr(run, key))
+        for flag in dataclasses.fields(run.flags):
+            flag_set = "Yes" if getattr(run.flags, flag.name) else "No"
+            self._write_header_line("flag " + flag.name, flag_set)
+
+    def _write_data_line(self, idx, data_pkg):
+        self._write_line(str(idx) + "\t" + "\t".join(map(str, data_pkg)))
+
+    def _write_data(self, run: Run):
+        if not run.data:
+            self._write_line("# No data.")
+            return
+
+        data_header = "# idx\t" + "\t".join(map(str, run.data.keys()))
+        self._write_line(data_header)
+
+        for idx, data_pkg in enumerate(zip(*run.data.values())):
+            self._write_data_line(idx, data_pkg)
+
+    def export(self, run):
+        self._write_header(run)
+        self._write_line("#")
+        self._write_data(run)

pybrid/redac/display.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+from .computer import REDAC
+
+
+class TreeDisplay:
+
+    @staticmethod
+    def render(redac: REDAC):
+        buffer = ""
+        buffer += "REDAC Analag Computer\n"
+
+        # TODO: Do it better :)
+        for carrier in redac.carriers:
+            buffer += "├── " + carrier.__class__.__name__ + " @ " + str(carrier.path) + "\n"
+            for cluster in carrier.children:
+                buffer += "│   ├── " + cluster.__class__.__name__ + " @ " + str(cluster.path) + "\n"
+                for block in cluster.children:
+                    buffer += "│   │   ├── " + block.__class__.__name__ + " @ " + str(block.path) + "\n"
+                    for element in block.children:
+                        buffer += "│   │   │   ├── " + element.__class__.__name__ + " @ " + str(element.path) + "\n"
+
+        return buffer

pybrid/redac/elements.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+from pybrid.base.hybrid import ComputationElement as BaseComputationElement
+
+from .entities import Entity
+
+
+class ComputationElement(BaseComputationElement, Entity):
+    """
+    A REDAC computation element (a function).
+
+    Each computation element implements one of the available
+    analog computations in :doc:`configurations`.
+    """
+
+    def generate_partial_configuration(self, attribute):
+        if self.computation_class.__dataclass_fields__.get(attribute, None):
+            return {attribute: getattr(self.computation, attribute)}
+        else:
+            raise ValueError("Unknown attribute %s for %s." % (attribute, self.__class__))
+
+    def apply_partial_configuration(self, attribute, value):
+        if field := self.computation_class.__dataclass_fields__.get(attribute, None):
+            setattr(self.computation, attribute, field.type(value))
+        else:
+            raise ValueError("Unknown attribute %s for %s." % (attribute, self.__class__))

pybrid/redac/entities.py

@@ -0,0 +1,200 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+"""
+The REDAC analog computer consists of a hierarchical structure of hardware modules.
+
+This structure is represented by a tree-like structure of :class:`Entity` objects and their sub-classes.
+Each entity has a unique :class:`Path` defining its position in this hierarchy.
+You can iterate over the children of an entity via its :attr:`Entity.children` property.
+As described in :class:`Path`, the hierarchy represented is as follows.
+
+#. Carrier boards implemented by :class:`pybrid.redac.carrier.Carrier`
+#. Clusters implemented by :class:`pybrid.redac.cluster.Cluster`
+#. Function blocks implemented by :class:`pybrid.redac.blocks.FunctionBlock`, see :doc:`configurations`
+#. Functions (Elements) implemented by :class:`pybrid.redac.elements.ComputationElement`
+"""
+
+from dataclasses import dataclass, fields, replace
+from enum import Enum
+import typing
+
+from pybrid.base.hybrid import Path as BasePath
+from pybrid.base.hybrid import Entity as BaseEntity
+
+
+class UnknownEntityTypeError(ValueError):
+    """Exception thrown when trying to get an unknown :class:`EntityType` instance."""
+    pass
+
+
+class EntityTypeRegistryError(ValueError):
+    """Exception for errors inside the :class:`EntityType` registry."""
+    pass
+
+
+class EntityClass(Enum):
+    """Entity class differentiates between carrier boards, different function blocks and so on. Max 5bit = 31."""
+    CARRIER = 0
+    CLUSTER = 1  # mostly unused
+    MBLOCK = 2
+    UBLOCK = 3
+    CBLOCK = 4
+    IBLOCK = 5
+    OTHER = 31
+
+
+_ENTITY_TYPE_REGISTRY: dict["EntityType", object] = dict()
+
+
+@dataclass(kw_only=True, eq=True, frozen=True)
+class EntityType:
+    """
+    A unique identifier for an entity type.
+
+    Each hardware module in a REDAC analog computer contains hardware version information
+    in their EEPROM. When the client library connects to an analog computer,
+    it generally requests the tree of hardware modules present.
+    This is given as a tree-like list of :class:`EntityType` objects.
+    Since it is also automatically converted to the respective python objects,
+    you typically do not need to handle :class:`EntityType` objects directly.
+
+    One notable exception is registering a python class for the auto-conversion
+    from an :class:`EntityType` to its respective :class:`Entity` class as follows.
+
+    .. code-block::
+
+        @EntityType.register(EntityClass.MBLOCK, 17, 3, 1)
+        class ACustomMBlock(ElementBlock):
+            ...
+    """
+    #: The class of the entity, see :class:`EntityClass`.
+    #: Different classes of entities can only be placed at their expected slots and can not be interchanged.
+    class_: EntityClass
+    #: The type of the entity, mostly relevant for :class:`pybrid.redac.blocks.MBlock`.
+    #: Different types of an entity have significantly different functionality, but may be placed in the same slots.
+    type_: typing.Optional[int] = None
+    #: The variant of an entity.
+    #: Different variants of an entity have similar functionality, but may differ in certain implementation details.
+    variant: typing.Optional[int] = None
+    #: The version on an entity.
+    #: Different versions of an entity are basically identical, but may contain different hardware elements or bugfixes.
+    version: typing.Optional[int] = None
+
+    @classmethod
+    def pop_from_dict(cls, d):
+        return cls(class_=EntityClass(d.pop("class")), type_=d.pop("type"), variant=d.pop("variant"),
+                   version=d.pop("version"))
+
+    def fallback_type(self):
+        """Return a copy of this :class:`EntityType` with one more field set to None."""
+        for field in reversed(fields(self)[1:]):
+            if getattr(self, field.name) is not None:
+                return replace(self, **{field.name: None})
+        raise ValueError("Can not further decay.")
+
+    @classmethod
+    def register(cls, class_: EntityClass, type_, variant, version):
+        """Register a class as an implementation of an :class:`EntityType`."""
+        entity_type = cls(class_=class_, type_=type_, variant=variant, version=version)
+
+        def register_(obj):
+            if entity_type in _ENTITY_TYPE_REGISTRY:
+                raise EntityTypeRegistryError("Entity type is already registered.")
+            _ENTITY_TYPE_REGISTRY[entity_type] = obj
+            return obj
+
+        return register_
+
+    @classmethod
+    def lookup(cls, type_, decay=False):
+        """
+        Lookup the implementation of an :class:`EntityType`.
+        Use the ``decay`` parameter if you want to allow finding a more generic implementation.
+        """
+        try:
+            return _ENTITY_TYPE_REGISTRY[type_]
+        except KeyError:
+            if not decay:
+                raise UnknownEntityTypeError("Entity type %s not registered." % type_)
+            else:
+                try:
+                    return cls.lookup(type_.fallback_type(), True)
+                except ValueError:
+                    raise UnknownEntityTypeError("Neither entity type %s nor any fallbacks are registered." % type_)
+
+
+class Path(BasePath):
+    """
+    A tuple uniquely identifying an entity in the REDAC.
+
+    The path to an entity is a hierarchical combination of paths to its parent entities.
+    Its structure in the REDAC is :code:`(<carrier board>, <cluster>, <block>, <function>)`.
+    Carrier boards are defined by their MAC address, e.g. "04-E9-E5-14-74-BF".
+    Clusters are defined by their index sent as a string, e.g. "0".
+    Function blocks on them are identified by their abbreviation, one of "M0", "M1", "U", "C", "I".
+    Functions on blocks are defined by their index as integer, e.g. 7.
+    The blocks' functions are usually not directly accessed, but instead configured via their block.
+
+    :Usage: Combine the identifiers to the required depth
+
+        .. code-block::
+
+            path_to_a_carrier_board = Path("00:00:5e:00:53:af")
+            path_to_second_cluster_on_it = Path("00:00:5e:00:53:af", "1")
+            path_to_m0_block_in_cluster0 = Path("00:00:5e:00:53:af", "0", "M0")
+            path_to_first_func_on_block = Path("00:00:5e:00:53:af", "0", "M0", 0)
+    """
+    #: The schema defining the data types for the path's subcomponents.
+    SCHEMA = (str, str, str, int)
+
+    def to_carrier(self):
+        """Returns the path until the carrier board level."""
+        return Path(self[:1])
+
+    def to_cluster(self):
+        """
+        Returns the path until the cluster level.
+
+        Raises IndexError if path is not of sufficient depth.
+        """
+        return Path(self[:2])
+
+    def to_block(self):
+        """
+        Returns the path until the block level.
+
+        Raises IndexError if path is not of sufficient depth.
+        """
+        return Path(self[:3])
+
+    def to_function(self):
+        """
+        Returns the path until the function level.
+
+        Raises IndexError if path is not of sufficient depth.
+        """
+        return Path(self[:4])
+
+
+@dataclass
+class Entity(BaseEntity):
+    """
+    Base class for all entities inside a REDAC.
+    """
+    #: Unique path to this entity.
+    path: Path
+
+    @classmethod
+    def create_from_entity_type_tree(cls, sub_path, sub_tree):
+        raise NotImplementedError
+
+    def generate_partial_configuration(self, attribute):
+        if self.__dataclass_fields__.get(attribute, None):
+            return {attribute: getattr(self, attribute)}
+        else:
+            raise ValueError("Unknown attribute %s for %s." % (attribute, self.__class__))
+
+    def apply_partial_configuration(self, attribute, value):
+        raise NotImplementedError

pybrid/redac/modules.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2022-2024 anabrid GmbH
+# Contact: https://www.anabrid.com/licensing/
+# SPDX-License-Identifier: MIT OR GPL-2.0-or-later
+
+from dataclasses import dataclass
+
+
+class ModuleType(str):
+    """Should probably be roughly equal to what we save in metadata storage"""
+    pass
+
+
+@dataclass
+class Module:
+    pass

pybrid/redac/protocol/__init__.py

@@ -0,0 +1,20 @@
+"""
+The REDAC network protocol is a request-response message based protocol.
+Messages are encoded as JSON strings and delimited by newline characters.
+The message definition can be found in the :mod:`.messages` namespace.
+Please refer to their documentations and the therein contained sequence diagrams
+for details about the messaging process.
+
+A usual sequence of messages for running one or multiple analog computations is:
+
+#. Get the current hardware configuration via a :class:`~.messages.GetEntitiesRequest`.
+#. Start a new user session (if required) via a :class:`~.messages.StartSessionRequest`.
+#. Configure the analog computation via a series of :class:`~.messages.SetConfigRequest`.
+#. Start the analog computation via a :class:`~.messages.StartRunRequest`.
+#. Monitor the analog computation by listening to incoming :class:`~.messages.RunStateChangeMessage`
+   and :class:`~.messages.RunDataMessage` notifications.
+#. The analog computation is done once you receive a :class:`~.messages.RunStateChangeMessage`
+   with :attr:`~.messages.RunStateChangeMessage.new` set to :attr:`~..run.RunState.DONE`.
+#. Evaluate the data received and repeat from step 3 if necessary.
+#. End your session with a :class:`~.messages.EndSessionRequest`.
+"""