bapsf-motion 0.2.0b1__py3-none-any.whl

bapsf_motion/__init__.py

@@ -0,0 +1,59 @@
+"""`bapsf_motion`"""
+__all__ = ["__version__"]
+
+# Enforce Python version check during package import.
+# This is the same check as the one at the top of setup.py
+import sys
+
+if sys.version_info < (3, 7):  # coverage: ignore
+    raise ImportError("bapsf_motion does not support Python < 3.7")
+
+if sys.version_info >= (3, 8):
+    from importlib.metadata import version, PackageNotFoundError
+else:
+    from importlib_metadata import version, PackageNotFoundError
+
+from bapsf_motion import actors, motion_builder, transform, utils
+
+# define version
+try:
+    # this places a runtime dependency on setuptools
+    #
+    # note: if there's any distribution metadata in your source files, then this
+    #       will find a version based on those files.  Keep distribution metadata
+    #       out of your repository unless you've intentionally installed the package
+    #       as editable (e.g. `pip install -e {bapsf_motion_directory_root}`),
+    #       but then __version__ will not be updated with each commit, it is
+    #       frozen to the version at time of install.
+    #
+    #: bapsf_motion version string
+    __version__ = version("bapsf_motion")
+except PackageNotFoundError:
+    # package is not installed
+    fallback_version = "unknown"
+    try:
+        # code most likely being used from source
+        # if setuptools_scm is installed then generate a version
+        from setuptools_scm import get_version
+
+        __version__ = get_version(
+            root="../", relative_to=__file__, fallback_version=fallback_version
+        )
+        del get_version
+        warn_add = "setuptools_scm failed to detect the version"
+    except ModuleNotFoundError:
+        # setuptools_scm is not installed
+        __version__ = fallback_version
+        warn_add = "setuptools_scm is not installed"
+
+    if __version__ == fallback_version:
+        from warnings import warn
+
+        warn(
+            f"bapsf_motion.__version__ not generated (set to 'unknown'), "
+            f"bapsf_motion is not an installed package and {warn_add}.",
+            RuntimeWarning,
+        )
+
+        del warn
+    del fallback_version, warn_add

bapsf_motion/actors/__init__.py

@@ -0,0 +1,18 @@
+__all__ = []
+__actors__ = [
+    "Axis",
+    "BaseActor",
+    "Drive",
+    "EventActor",
+    "RunManager",
+    "MotionGroup",
+    "Motor",
+]
+__all__ += __actors__
+
+from bapsf_motion.actors.axis_ import Axis
+from bapsf_motion.actors.base import BaseActor, EventActor
+from bapsf_motion.actors.drive_ import Drive
+from bapsf_motion.actors.manager_ import RunManager, RunManagerConfig
+from bapsf_motion.actors.motion_group_ import MotionGroup, MotionGroupConfig
+from bapsf_motion.actors.motor_ import Motor

bapsf_motion/actors/axis_.py

@@ -0,0 +1,328 @@
+"""
+Module for functionality focused around the
+`~bapsf_motion.actors.axis_.Axis` actor class.
+"""
+__all__ = ["Axis"]
+__actors__ = ["Axis"]
+
+import asyncio
+import logging
+
+from typing import Any, Dict, Union
+
+from bapsf_motion.actors.base import EventActor
+from bapsf_motion.actors.motor_ import Motor
+from bapsf_motion.utils import units as u
+
+
+class Axis(EventActor):
+    """
+    The `Axis` actor is the next level actor above the |Motor| actor.
+    This actor is ignorant of how it is situated in a probe drive, but
+    is fully aware of the entire physical axis that defines it and the
+    motor that moves the axis.  This actor operates in physical units
+    and will handle all the necessary unit converstion to communicate
+    with the |Motor| actor.
+
+    Parameters
+    ----------
+    ip: str
+        IPv4 address for the motor driving the axis
+
+    units: str
+        Physical units the axis operates in (e.g. ``'cm'``)
+
+    units_per_rev: float
+        The number of ``units`` traversed per motor revolution.
+
+    name: str
+        Name the axis.  (DEFAULT: ``'Axis'``)
+
+    logger: `~logging.Logger`, optional
+        An instance of `~logging.Logger` that the Actor will record
+        events and status updates to.  If `None`, then a logger will
+        automatically be generated. (DEFUALT: `None`)
+
+    loop: `asyncio.AbstractEventLoop`, optional
+        Instance of an `asyncio` `event loop`_. Communication with the
+        motor will happen primaritly through the evenet loop.  If
+        `None`, then an `event loop`_ will be auto-generated.
+        (DEFAULT: `None`)
+
+    auto_run: bool, optional
+        If `True`, then the `event loop`_ will be placed in a separate
+        thread and started.  This is all done via the :meth:`run`
+        method. (DEFAULT: `False`)
+
+    Examples
+    --------
+
+    >>> from bapsf_motion.actors import Axis
+    >>> import logging
+    >>> import sys
+    >>> logging.basicConfig(stream=sys.stdout, level=logging.NOTSET)
+    >>> ax = Axis(
+    ...     ip="192.168.6.104",
+    ...     units="cm",
+    ...     units_per_rev=0.1*2.54,  # acme rod with .1 in pitch
+    ...     name="WALL-E",
+    ...     auto_run=True,
+    ... )
+
+    """
+    # TODO: better handle naming of the Axis and child Motor
+
+    def __init__(
+        self,
+        *,
+        ip: str,
+        units: str,
+        units_per_rev: float,
+        name: str = "Axis",
+        logger: logging.Logger = None,
+        loop: asyncio.AbstractEventLoop = None,
+        auto_run: bool = False,
+    ):
+        # TODO: update units so inches can be used
+        self._motor = None
+        self._units = u.Unit(units)
+        self._units_per_rev = units_per_rev * self._units / u.rev
+
+        super().__init__(
+            name=name,
+            logger=logger,
+            loop=loop,
+            auto_run=False,
+        )
+
+        self._motor = Motor(
+            ip=ip,
+            name="motor",
+            logger=self.logger,
+            loop=self.loop,
+            auto_run=False,
+        )
+
+        self.run(auto_run=auto_run)
+
+    def _configure_before_run(self):
+        return
+
+    def _initialize_tasks(self):
+        return
+
+    def run(self, auto_run=True):
+        super().run(auto_run=auto_run)
+
+        if self.motor is None:
+            return
+
+        self.motor.run(auto_run=auto_run)
+
+    def terminate(self, delay_loop_stop=False):
+        self.motor.terminate(delay_loop_stop=True)
+        super().terminate(delay_loop_stop=delay_loop_stop)
+
+    @property
+    def config(self) -> Dict[str, Any]:
+        """Dictionary of the axis configuration parameters."""
+        return {
+            "name": self.name,
+            "ip": self.motor.ip,
+            "units": str(self.units),
+            "units_per_rev": self.units_per_rev.value.item()
+        }
+    config.__doc__ = EventActor.config.__doc__
+
+    @property
+    def motor(self) -> Motor:
+        """Instance of the |Motor| object that belongs to |Axis|."""
+        return self._motor
+
+    @property
+    def ip(self):
+        """IPv4 address for the Axis' motor"""
+        return self.motor.ip
+
+    @property
+    def is_moving(self) -> bool:
+        """
+        `True` or `False` indicating if the axis is currently moving.
+        """
+        return self.motor.is_moving
+
+    @property
+    def position(self):
+        """
+        Current axis position in units defined by the :attr:`units`
+        attribute.
+        """
+        pos = self.motor.position
+        return pos.to(self.units, equivalencies=self.equivalencies)
+
+    @property
+    def steps_per_rev(self):
+        """Number of motor steps for a full revolution."""
+        return self.motor.steps_per_rev
+
+    @property
+    def units(self) -> u.Unit:
+        """
+        The unit of measure for the `Axis` physical parameters like
+        position, speed, etc.
+        """
+        return self._units
+
+    @units.setter
+    def units(self, new_units: u.Unit):
+        """Set the units of measure."""
+        if self.units.physical_type != new_units.physical_type:
+            raise ValueError
+
+        self._units_per_rev = self.units_per_rev.to(new_units / u.rev)
+        self._units = new_units
+
+    @property
+    def units_per_rev(self) -> u.Quantity:
+        """
+        The number of units (:attr:`units`) translated per full
+        revolution of the motor (:attr:`motor`).
+        """
+        return self._units_per_rev
+
+    @units_per_rev.setter
+    def units_per_rev(self, value: Union[float, u.Quantity]):
+        """
+        Update the number of units translated per full revolution of the
+        motor.
+        """
+        if isinstance(value, float) and value > 0.0:
+            self._units_per_rev = value * self.units / u.rev
+        elif (
+            isinstance(value, u.Quantity)
+            and value.unit == self.units / u.rev
+            and value > 0.0
+        ):
+            self._units_per_rev = value
+
+    @property
+    def equivalencies(self):
+        """
+        List of unit equivalencies to convert back-and-forth between
+        the axis physical units and the motor units.
+        """
+        steps_per_rev = self.steps_per_rev.value
+        units_per_rev = self.units_per_rev.value
+
+        equivs = [
+            (
+                u.rev,
+                u.steps,
+                lambda x: int(x * steps_per_rev),
+                lambda x: x / steps_per_rev,
+            ),
+            (
+                u.rev,
+                self.units,
+                lambda x: x * units_per_rev,
+                lambda x: x / units_per_rev,
+            ),
+            (
+                u.steps,
+                self.units,
+                lambda x: x * units_per_rev / steps_per_rev,
+                lambda x: int(x * steps_per_rev / units_per_rev),
+            ),
+        ]
+        for equiv in equivs.copy():
+            equivs.extend(
+                [
+                    (equiv[0] / u.s, equiv[1] / u.s, equiv[2], equiv[3]),
+                    (equiv[0] / u.s / u.s, equiv[1] / u.s / u.s, equiv[2], equiv[3]),
+                ]
+            )
+
+        return equivs
+
+    @property
+    def conversion_pairs(self):
+        """
+        List of conversion pairs between motor units and physical
+        units.  For example, ``[(u.steps, self.units), ...]``.
+        """
+        return [
+            (u.steps, self.units),
+            (u.steps / u.s, self.units / u.s),
+            (u.steps / u.s / u.s, self.units / u.s / u.s),
+            (u.rev / u.s, self.units / u.s),
+            (u.rev / u.s / u.s, self.units / u.s / u.s),
+        ]
+
+    def send_command(self, command, *args):
+        """
+        Send ``command`` to the motor, and receive its response.  If the
+        `event loop`_ is running, then the command will be sent as
+        a threadsafe coroutine_ in the loop.  Otherwise, the command
+        will be sent directly to the motor.
+
+        Parameters
+        ----------
+        command: str
+            The desired command to be sent to the motor.
+        *args:
+            Any arguments to the ``command`` that will be sent with the
+            motor command.
+        """
+        cmd_entry = self.motor._commands[command]
+        motor_unit = cmd_entry["units"]  # type: u.Unit
+
+        # TODO: put this into a separate convert() method that can handle both
+        #       the send and recv unit conversion
+        if motor_unit is not None and len(args):
+            axis_unit = None
+            for motor_u, axis_u in self.conversion_pairs:
+                if motor_unit == motor_u:
+                    axis_unit = axis_u
+                    break
+
+            if axis_unit is not None:
+                args = list(args)
+                args[0] = args[0] * axis_unit.to(
+                    motor_unit, equivalencies=self.equivalencies
+                )
+
+                # TODO: There should be a cleaner way of enforcing this
+                #       int conversion...maybe add it to the Motor class,
+                #       but I [Erik] currently feel the conversion should
+                #       happen outside the Motor class
+                if motor_unit is u.steps:
+                    args[0] = int(args[0])
+
+        rtn = self.motor.send_command(command, *args)
+
+        # TODO: see detailing todo above
+        if hasattr(rtn, "unit"):
+            axis_unit = None
+            for motor_u, axis_u in self.conversion_pairs:
+                if rtn.unit == motor_u:
+                    axis_unit = axis_u
+                    break
+
+            if axis_unit is not None:
+                rtn = rtn.to(axis_unit, equivalencies=self.equivalencies)
+
+        return rtn
+
+    def move_to(self, *args):
+        """
+        Quick access command for ``send_command("move_to", *args)``.
+        """
+        return self.send_command("move_to", *args)
+
+    def stop(self):
+        """
+        Quick access command for ``send_command("stop")``.
+        """
+        # not sending STOP command through send_command() since using
+        # motor.stop() should result in faster execution
+        return self.motor.stop()

bapsf_motion/actors/base.py

@@ -0,0 +1,281 @@
+"""
+Module for functionality focused around the [Abstract] base actors.
+"""
+
+__all__ = ["BaseActor", "EventActor"]
+__actors__ = ["BaseActor", "EventActor"]
+
+import asyncio
+import logging
+import threading
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Union
+
+
+# TODO: create an EventActor for an actor that utilizes asyncio event loops
+#       - EventActor should inherit from BaseActor and ABC
+
+
+class BaseActor(ABC):
+    """
+    Low-level base class for any Actor class.
+
+    Parameters
+    ----------
+    name : str, optional
+        A unique :attr:`name` for the Actor instance.
+    logger : `~logging.Logger`, optional
+        The instance of `~logging.Logger` that the Actor should record
+        events and status updates.
+    """
+
+    def __init__(
+        self, *, name: str = None, logger: logging.Logger = None,
+    ):
+        # setup logger to track events
+        log_name = "Actor" if logger is None else logger.name
+        if name is not None:
+            log_name += f".{name}"
+
+        self.name = name if name is not None else ""
+        self.logger = logging.getLogger(log_name)
+
+    @property
+    def name(self) -> str:
+        """
+        (`str`) A unique name given for the instance of the actor.  This
+        name is used as an identifier in the actor logger (see
+        :attr:`logger`).
+
+        If the user does not specify a name, then the Actor should
+        auto-generate a name.
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value):
+        self._name = value
+
+    @property
+    def logger(self) -> logging.Logger:
+        """The `~logger.Logger` instance being used for the actor."""
+        return self._logger
+
+    @logger.setter
+    def logger(self, value):
+        self._logger = value
+
+    @property
+    @abstractmethod
+    def config(self) -> Dict[str, Any]:
+        """
+        Configuration dictionary of the actor.
+
+        .. warning::
+
+           This dictionary should never be written to from outside the
+           owning actor.
+        """
+        ...
+
+
+# TODO: Create an EventActor
+#       - must setup the asyncio event loop
+#       - must handle running th loop in a separate thread
+#       - How should I incorporate the heartbeat?
+#       - Must have the option to auto_run the event loop
+#       - must inherit from BaseActor
+#       - will likely need abstract methods _actor_setup_pre_loop() and
+#         _actor_setup_post_loop() for setup actions before and after
+#         the loop creation, respectively.
+
+
+class EventActor(BaseActor, ABC):
+    r"""
+    A base class for any Actor that will be interacting with an `asncio`
+    event loop.
+
+    Parameters
+    ----------
+    name : str, optional
+        A unique :attr:`name` for the Actor instance.
+
+    logger : `~logging.Logger`, optional
+        The instance of `~logging.Logger` that the Actor should record
+        events and status updates.
+
+    loop: `asyncio.AbstractEventLoop`, optional
+        Instance of an `asyncio` `event loop`_\ .  If `None`, then an
+        `event loop`_ will be auto-generated.  (DEFAULT: `None`)
+
+    auto_run: bool, optional
+        If `True`, then the `event loop`_ will be placed in a separate
+        thread and started.  This is all done via the :meth:`run`
+        method. (DEFAULT: `False`)
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str = None,
+        logger: logging.Logger = None,
+        loop: asyncio.AbstractEventLoop = None,
+        auto_run: bool = False,
+    ):
+
+        super().__init__(name=name, logger=logger)
+
+        self._thread = None
+        self._loop = self.setup_event_loop(loop)
+        self._tasks = None
+
+        self._configure_before_run()
+        self._initialize_tasks()
+
+        self.run(auto_run)
+
+    @property
+    def tasks(self) -> List[asyncio.Task]:
+        r"""
+        List of `asyncio.Task`\ s this actor has in its `event loop`_.
+        """
+        if self._tasks is None:
+            self._tasks = []
+
+        return self._tasks
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop:
+        """The `asyncio` :term:`event loop` for the actor."""
+        return self._loop
+
+    @property
+    def thread(self) -> threading.Thread:
+        """
+        The `~threading.Thread` the `event loop`_ is running in.
+
+        If :attr:`loop` was given during instantiation, then there is
+        no way of obtaining the thread object the event loop is
+        running in.  In this case :attr:`thread` will be `None`.
+
+        The thread id can always be retrieved using :attr:`_thread_id`.
+        """
+        return self._thread
+
+    @property
+    def _thread_id(self) -> Union[int, None]:
+        """
+        Unique ID for the thread the loop is running in.
+
+        `None` if the :attr:`loop` does not exit or is not running.
+        """
+        if self.loop is None or not self.loop.is_running():
+            # no loop has been created or loop is not running
+            return None
+        elif self._thread is not None:
+            return self._thread.ident
+
+        # get thread id from inside the event loop
+        future = asyncio.run_coroutine_threadsafe(
+            self._thread_id_async(),
+            self.loop
+        )
+        return future.result(5)
+
+    async def _thread_id_async(self):
+        """
+        Asyncio coroutine for retrieving the id of the thread the event
+        loop is running in.
+        """
+        return threading.current_thread().ident
+
+    @abstractmethod
+    def _configure_before_run(self):
+        # A set of functionality for the subclass to run before the
+        # asyncio tasks are created and the event loop is started.
+        #
+        # This method is executed by __init__ before the event loop is
+        # started.
+        ...
+
+    @abstractmethod
+    def _initialize_tasks(self):
+        # Used by the subclass to initialize a list of tasks to be
+        # executed in the event loop after the loop is started.
+        #
+        # This method is executed by __init__ after
+        # _configure_before_run() but before the event loop is started.
+        ...
+
+    def setup_event_loop(
+        self, loop: Optional[asyncio.AbstractEventLoop] = None
+    ):
+        """
+        Set up the `asyncio` `event loop`_.  If the given loop is not an
+        instance of `~asyncio.AbstractEventLoop`, then a new loop will
+        be created.
+
+        Parameters
+        ----------
+        loop: `asyncio.AbstractEventLoop`
+            `asyncio` `event loop`_ for the actor's tasks
+
+        """
+        # get a valid event loop
+        if loop is None:
+            loop = asyncio.new_event_loop()
+        elif not isinstance(loop, asyncio.AbstractEventLoop):
+            self.logger.warning(
+                "Given asyncio event is not valid.  Creating a new event loop to use."
+            )
+            loop = asyncio.new_event_loop()
+        return loop
+
+    def run(self, auto_run=True):
+        r"""
+        Activate the `asyncio` `event loop`_\ .   If the event loop is
+        running, then nothing happens.  Otherwise, the event loop is
+        placed in a separate thread and set to
+        `~asyncio.loop.run_forever`.
+
+        Parameters
+        ----------
+        auto_run: `bool`, optional
+            If `False`, then do NOT start the event loop.  This keyword
+            is only made available to help with subclassing.
+            (DEFAULT: `True`)
+        """
+        if self.loop is None or self.loop.is_running() or not auto_run:
+            return
+
+        self._thread = threading.Thread(target=self._loop.run_forever)
+        self._thread.start()
+
+    def terminate(self, delay_loop_stop=False):
+        r"""
+        Stop the actor's `event loop`_\ .  All actor tasks will be
+        cancelled, the connection to the motor will be shutdown, and
+        the event loop will be stopped.
+
+        Parameters
+        ----------
+        delay_loop_stop: bool
+            If `True`, then do NOT stop the `event loop`_\ .  In this
+            case it is assumed the calling functionality is managing
+            additional tasks in the event loop, and it is up to that
+            functionality to stop the loop.  (DEFAULT: `False`)
+        """
+        for task in list(self.tasks):
+            self.loop.call_soon_threadsafe(task.cancel)
+            self.tasks.remove(task)
+
+        if delay_loop_stop:
+            return
+
+        # if we're stopping the loop, then all tasks need to be cancelled
+        for task in asyncio.all_tasks(self.loop):
+            if not task.done() or not task.cancelled():
+                self.loop.call_soon_threadsafe(task.cancel)
+
+        self.loop.call_soon_threadsafe(self.loop.stop)