pntos-api 2.1.0.post0.dev0__py3-none-any.whl

pntos/api/plugins/controller.py

@@ -0,0 +1,99 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from pntos.api import CommonPlugin
+
+
+class ControllerPlugin(CommonPlugin, ABC):
+    """
+    Controller plugin.
+
+    An implementation of a primary controller in charge of defining the usage of all other pntOS
+    plugins.
+
+    In ordinary operation, an app will import plugins, initialize a controller plugin, and then
+    call :meth:`pntos.api.ControllerPlugin.take_control` on the controller plugin, passing in a list of
+    ``plugins`` that it imported.
+
+    From that point forward, the controller is responsible for all activity. It may
+    use any or none of the plugins in the ``plugins`` list as desired. In general, it may do
+    anything it wants, within the following guidelines:
+
+    - The controller should not load new plugins - it should work with the ``plugins`` passed to it
+      in the :meth:`take_control` parameters.
+
+    - The controller must call :meth:`pntos.api.CommonPlugin.init_plugin` on any plugin it wishes to use prior
+      to using any other functionality on that plugin. The controller must pass a :class:`pntos.api.Mediator`
+      that the plugin may use to communicate back to the controller. This callback design allows the
+      controller to abstract away the concurrency model - in particular, a callback function may be
+      anything from a direct invocation of a Python function to a shim that utilizes IPC channels to
+      communicate to process-separated or machine-separated plugins.
+
+    Outside of these requirements, the controller defines any and all I/O it supports, which pntOS
+    plugins are loaded / used, and the type of fusion being done. The controller can be hard-coded
+    to support only a specific sensor configuration or written generically to support arbitrary
+    run-time environment sensing. Outside of some initialization in the app, the controller is the
+    conceptual "main" function.
+
+    When the controller is provided a :class:`pntos.api.PlatformIntegrationPlugin` as one of the plugins in
+    the ``plugins`` list passed to :meth:`take_control`, that indicates to the controller that
+    platform-specific control logic exists and must be used. In this case, the controller's primary
+    objective's are to:
+
+    - Pick the concurrency model being used (multiprocessed, multithreaded, coroutines,
+      single-threaded, etc.).
+    - Spin up the concurrency primitives to implement the chosen concurrency type.
+    - Provide a :class:`pntos.api.Mediator` to all plugins in their :meth:`pntos.api.CommonPlugin.init_plugin` call that
+      enables inter-plugin communication.
+
+    After that task is accomplished, the controller should call the
+    :meth:`pntos.api.PlatformIntegrationPlugin.take_control` function and allow the
+    :class:`pntos.api.PlatformIntegrationPlugin` (PIP) to actively call functions on the ``plugins`` list.
+    Once the :meth:`pntos.api.PlatformIntegrationPlugin.take_control` has been called, the controller must
+    lock/synchronize the controller's and the PIP's access to function calls in the ``plugins``
+    list, such that any action the PIP might take will not interfere with the controller's actions
+    (or, equivalently, actions that the mediator provided by the controller is taking). One simple
+    approach to synchronizing access to the plugins list across the controller and PIP is for the
+    plugins list provided to the PIP to be a facade that actually routes messages through to the
+    mediator, such that the mediator handles all requests and can synchronously dispatch them. More
+    efficient approaches exist, however, it is the responsibility of the controller to make sure
+    that all accesses the PIP makes to resources passed to it are synchronized with respect to the
+    controller's chosen concurrency primitive.
+    """
+
+    @abstractmethod
+    def take_control(
+        self,
+        plugins: list[CommonPlugin],
+        plugin_resources_locations: list[str | None] | None = None,
+        initial_config: str | None = None,
+    ) -> None:
+        """
+        Takes over primary control of the program from the app.
+
+        Takes over primary control of the program from the app, using the ``plugins`` to process
+        data, generate fused estimates, and ultimately produce and output PNT solutions.
+        :meth:`take_control` must use the plugins passed to it and construct a full pntOS system.
+        Please see the description of the :class:`pntos.api.PlatformIntegrationPlugin` (PIP) for a description
+        of duties of this function compared to the duties of the
+        :meth:`pntos.api.PlatformIntegrationPlugin.take_control` method (if a PIP is in the ``plugins`` list).
+
+        Args:
+            plugins (list[CommonPlugin]): An array of plugins available to the controller.
+            plugin_resources_locations (list[str  |  None] | None, optional): A list of strings
+                which represent a list of locations, one for each plugin in ``plugins``, where those
+                plugins may find auxiliary data if needed. The array can be ``None``,
+                otherwise the array is of the same length as ``plugins``. Each string may be
+                ``None``, filesystem paths, or adhere to some scheme, such as the URI scheme, for
+                defining the resource's location.
+            initial_config (str | None, optional): Represents a source of values to initialize the
+                primary pntOS configuration. This could be ``None`` or a ``str``. Examples of
+                possible values for the latter are:
+
+                1. The entire config.
+                2. A local file path on systems which support them.
+                3. A string adhering to the URI scheme.
+        """
+
+    pass

pntos/api/plugins/fusion.py

@@ -0,0 +1,572 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from aspn23 import TypeTimestamp
+from numpy import float64
+from numpy.typing import NDArray
+
+from .common import CommonPlugin, EstimateWithCovariance, Message
+from .fusion_strategy import (
+    StandardFusionStrategy,
+)
+from .state_modeling import (
+    StandardMeasurementProcessor,
+    StandardStateBlock,
+    VirtualStateBlock,
+)
+
+
+@dataclass
+class CrossCovariances:
+    """
+    A container for a set of covariances relating a StateBlock to one or more other StateBlocks.
+
+    For example, suppose that some StateBlock named ``A`` existed containing ``a`` states. Then this
+    structure could define the cross covariance of ``A`` with respect to other StateBlocks named
+    ``B`` (with ``b`` states) and ``C`` (with ``c`` states). In that case, :attr:`block_labels`
+    would be an array of 2 strings ``B`` and ``C``, and :attr:`cross_covariances` would be an array
+    of two matrices: the cross-covariance matrix of ``B`` and ``A``, with shape ``[b, a]`` and the
+    cross-covariance matrix of ``C`` and ``A`` with shape ``[c, a]``.
+
+    Attributes:
+        block_labels (list[str]): A list of labels of the :class:`pntos.api.StandardStateBlock` this
+            structure contains the cross-covariances for.
+        cross_covariances (list[NDArray[float64]]): A list of cross-covariance matrices between a single
+            StateBlock and the set of StateBlocks listed in :attr:`block_labels`.
+    """
+
+    block_labels: list[str]
+    """The labels of the state blocks that the entries in ``cross_covariances`` relate to.
+    """
+
+    cross_covariances: list[NDArray[float64]]
+    """The covariances between the state blocks.
+    """
+
+
+class StandardFusionEngine(ABC):
+    """
+    An implementation of a fusion engine that supports the standard fusion model.
+
+    Assumes the system is described by discrete-time matrices and noise inputs are zero-mean white
+    Gaussian. In addition, all covariance matrices / mean vectors are descriptions of
+    jointly-Gaussian multivariate distributions. All noise sources are jointly-Gaussian distributed.
+
+    This object requires a :class:`pntos.api.StandardFusionStrategy` to work. Some implementations may be able
+    to provide their own. Others will require a strategy to be provided by setting the
+    :attr:`StandardFusionEngine.strategy` field. It is possible to check whether a fusion
+    engine needs to be provided a fusion strategy by checking the
+    :attr:`StandardFusionEngine.strategy` field (if it is ``None`` then this fusion engine
+    needs to be provided a strategy). While :attr:`StandardFusionEngine.strategy` is ``None``,
+    all other methods are unsafe to be called.
+
+    Note:
+        This class must have an operational ``__deepcopy__`` method. For most classes, the default
+        ``__deepcopy__`` method provided by Python will be sufficient. However, if the class has a
+        field which does not properly implement its own ``__deepcopy__`` (such as a C object wrapped
+        to Python), then the class will need to implement a custom ``__deepcopy__`` which properly
+        copies all fields.
+
+    Caution:
+        **Unstable**: This feature is unstable and is not yet considered part of the stable pntOS
+        API. Usage of this feature is highly discouraged in non-experimental code, and its
+        definition may change at any time.
+    """
+
+    @property
+    @abstractmethod
+    def time(self) -> TypeTimestamp:
+        """
+        Get the current time of the filter.
+
+        Returns:
+            TypeTimestamp
+        """
+        pass
+
+    @time.setter
+    @abstractmethod
+    def time(self, time: TypeTimestamp) -> None:
+        """Setter for the :meth:`pntos.api.StandardFusionEngine.time` property."""
+        pass
+
+    @property
+    @abstractmethod
+    def strategy(self) -> StandardFusionStrategy | None:
+        """
+        The underlying algorithm used for Bayesian inference.
+
+        Returns:
+            StandardFusionStrategy | None: The fusion strategy is the type of filter (EKF, UKF,
+            etc.).
+        """
+        pass
+
+    @strategy.setter
+    @abstractmethod
+    def strategy(self, strategy: StandardFusionStrategy) -> None:
+        """The setter for the :meth:`strategy` property on :class:`pntos.api.StandardFusionEngine`."""
+        pass
+
+    @property
+    @abstractmethod
+    def num_states(self) -> int:
+        """
+        Get the total number of states currently in the fusion engine.
+
+        Virtual state blocks do not affect this result.
+
+        Returns:
+            int: The total number of states currently in the fusion engine.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def state_block_labels(self) -> list[str] | None:
+        """
+        Get a list of :class:`pntos.api.StandardStateBlock` labels that have been added to this fusion engine.
+
+        Returns:
+            list[str] | None: A list of the :class:`pntos.api.StandardStateBlock` labels that have been added
+            to this fusion engine. Returns ``None`` if no state blocks have been added. Guaranteed
+            to not return ``None`` if :attr:`num_states` is a value other than 0.
+        """
+        pass
+
+    @abstractmethod
+    def add_state_block(
+        self,
+        block: StandardStateBlock,
+        initial_estimate_covariance: EstimateWithCovariance,
+        cross_covariances: CrossCovariances | None = None,
+    ) -> None:
+        """
+        Add the given :class:`pntos.api.StandardStateBlock` to the fusion engine.
+
+        This will expand the state vector being estimated by the value of :attr:`num_states`.
+
+        Args:
+            block (StandardStateBlock): The :class:`pntos.api.StandardStateBlock` to be added to the fusion
+                engine.
+            initial_estimate_covariance (EstimateWithCovariance): Contains the initial conditions of
+                the states, with ``initial_estimate_covariance.estimate`` being an Nx1 matrix and
+                ``initial_estimate_covariance.covariance`` being an NxN matrix, where N is
+                ``block.num_states``.
+            cross_covariances (CrossCovariances | None, optional): An optional parameter which, if
+                non-``None``, contains a description of the newly added StateBlock's cross
+                covariances with respect to a set of StateBlocks which already exist inside the
+                filter (specified by ``cross_covariances.block_labels``). If the
+                ``cross_covariance`` parameter is ``None``, cross covariance between the existing
+                states and the added states will be set to zeroes.
+        """
+        pass
+
+    @abstractmethod
+    def get_state_block_estimate(self, block_label: str) -> NDArray[float64] | None:
+        """
+        Get the estimate associated with a state block.
+
+        Find a :class:`pntos.api.StandardStateBlock` or :class:`pntos.api.VirtualStateBlock` within the fusion engine
+        matching ``block_label``, and return a copy of its current estimate vector.
+
+        Args:
+            block_label (str)
+
+        Returns:
+            NDArray[float64] | None: A copy of its current estimate vector. If ``block_label`` references a
+            virtual state block (VSB) this will return a converted estimate, converted into the VSBs
+            coordinate frame. Returns ``None`` if ``block_label`` does not correspond to a block
+            that has been added to the fusion engine. Guaranteed to not return ``None`` when
+            ``block_label`` is in the list returned by :attr:`state_block_labels` and
+            :attr:`strategy` is not ``None``.
+        """
+        pass
+
+    @abstractmethod
+    def get_state_block_covariance(self, block_label: str) -> NDArray[float64] | None:
+        """
+        Get the covariance associated with a state block.
+
+        Find a :class:`pntos.api.StandardStateBlock` or :class:`pntos.api.VirtualStateBlock` within the fusion engine
+        matching ``block_label``, and return a copy of its current covariance matrix.
+
+        Args:
+            block_label (str)
+
+        Returns:
+            NDArray[float64] | None: A copy of its current covariance matrix. If ``block_label`` references a
+            virtual state block (VSB) this will return a converted covariance, converted into the
+            VSBs coordinate frame. Returns ``None`` if ``block_label`` does not correspond to a
+            block that has been added to the fusion engine. Guaranteed to not return ``None`` when
+            ``block_label`` is in the list returned by :attr:`state_block_labels` and
+            :attr:`strategy` is not ``None``.
+        """
+        pass
+
+    @abstractmethod
+    def get_state_block_cross_covariance(
+        self, block_label1: str, block_label2: str
+    ) -> NDArray[float64] | None:
+        """
+        Get the cross covariance between the states associated with two state blocks.
+
+        Find the :class:`pntos.api.StandardStateBlock` s within the fusion engine matching ``block_label1``
+        and ``block_label2``, and return the cross-covariance matrix between them.
+
+        Args:
+            block_label1 (str)
+            block_label2 (str)
+
+        Returns:
+            NDArray[float64] | None: The cross-covariance matrix between ``block_label1`` and
+            ``block_label2``. Returns ``None`` if ``block_label1`` or ``block_label2`` do not
+            correspond to blocks that have been added to the fusion engine. Guaranteed to not return
+            ``None`` when both ``block_label1`` and ``block_label2`` are in the list returned by
+            :attr:`state_block_labels` and :attr:`strategy` is not ``None``.
+        """
+        pass
+
+    @abstractmethod
+    def set_state_block_estimate(
+        self, block_label: str, estimate: NDArray[float64]
+    ) -> None:
+        """
+        Update the estimate associated with a given state block.
+
+        Find a :class:`pntos.api.StandardStateBlock` within the fusion engine matching ``block_label``, and
+        change its current estimate vector.
+
+        Note:
+            This function may lead to performance degradation with some implementations and thus its
+            use is discouraged if other options are available.
+
+        Args:
+            block_label (str)
+            estimate (NDArray[float64])
+        """
+        pass
+
+    @abstractmethod
+    def set_state_block_covariance(
+        self, block_label: str, covariance: NDArray[float64]
+    ) -> None:
+        """
+        Update the covariance associated with a given state block.
+
+        Find a :class:`pntos.api.StandardStateBlock` within the fusion engine matching ``block_label``, and
+        change its current covariance matrix.
+
+        Note:
+            This function may lead to performance degradation with some implementations and thus its
+            use is discouraged if other options are available.
+
+        Args:
+            block_label (str)
+            covariance (NDArray[float64])
+        """
+        pass
+
+    @abstractmethod
+    def set_state_block_cross_covariance(
+        self, block_label1: str, block_label2: str, covariance: NDArray[float64]
+    ) -> None:
+        """
+        Update the covariance between two state blocks.
+
+        Find the :class:`pntos.api.StandardStateBlock` s within the fusion engine matching ``block_label1``
+        and ``block_label2``, and change the current covariance matrix between them.
+
+        Note:
+            This function may lead to performance degradation with some implementations and thus its
+            use is discouraged if other options are available.
+
+        Args:
+            block_label1 (str)
+            block_label2 (str)
+            covariance (NDArray[float64])
+        """
+        pass
+
+    @abstractmethod
+    def remove_state_block(self, block_label: str) -> None:
+        """
+        Remove the :class:`pntos.api.StandardStateBlock` matching ``block_label``.
+
+        This will reduce the state vector being estimated by the number of states that the block
+        represents.
+
+        Args:
+            block_label (str)
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def virtual_state_block_target_labels(self) -> list[str] | None:
+        """
+        Gets a list of the target labels of virtual state blocks that have been added.
+
+        A label being returned by this list is not a guarantee that the virtual state block has a
+        valid source. For that, call :meth:`has_virtual_state_block`.
+
+        Returns:
+            list[str] | None: A list of the target labels of virtual state blocks that have been
+            added. Returns ``None`` if no virtual state blocks have been added to this fusion
+            engine.
+        """
+        pass
+
+    @abstractmethod
+    def has_virtual_state_block(self, vsb_target_label: str) -> bool:
+        """
+        Checks if the fusion engine has a :class:`pntos.api.VirtualStateBlock` with a matching target label.
+
+        Args:
+            vsb_target_label (str)
+
+        Returns:
+            bool: ``True`` if the fusion engine has a :class:`pntos.api.VirtualStateBlock` with a matching
+            target label, ``False`` if no virtual state block with matching target label exists or
+            if one exists but is not capable of generating an estimate. That is, the VSB's source
+            must exist and be in a continuous chain to a concrete state block which also exists in
+            the fusion engine in order to return ``True``.
+        """
+        pass
+
+    @abstractmethod
+    def add_virtual_state_block(self, virtual_state_block: VirtualStateBlock) -> None:
+        """
+        Add the given :class:`pntos.api.VirtualStateBlock` to the fusion engine.
+
+        A virtual state block (VSB) convert from an underlying block coordinate frame into the VSB
+        coordinate frame.
+
+        Args:
+            virtual_state_block (VirtualStateBlock)
+        """
+        pass
+
+    @abstractmethod
+    def remove_virtual_state_block(self, vsb_target_label: str) -> None:
+        """
+        Remove the :class:`pntos.api.VirtualStateBlock` matching ``vsb_target_label``.
+
+        Args:
+            vsb_target_label (str)
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def measurement_processor_labels(self) -> list[str] | None:
+        """
+        Get a list of the labels of measurement processors that have been added.
+
+        Returns:
+            list[str] | None: list of labels of measurement processors that have been added. Returns
+            ``None`` if no measurement processors have been added to this fusion engine.
+        """
+        pass
+
+    @abstractmethod
+    def add_measurement_processor(
+        self, processor: StandardMeasurementProcessor
+    ) -> None:
+        """
+        Add a :class:`pntos.api.StandardMeasurementProcessor`.
+
+        This can be used to process future measurements that correspond to ``processor.label``.
+
+        Args:
+            processor (StandardMeasurementProcessor)
+        """
+        pass
+
+    @abstractmethod
+    def remove_measurement_processor(self, processor_label: str) -> None:
+        """
+        Remove a :class:`pntos.api.StandardMeasurementProcessor` previously added to the fusion engine.
+
+        Assumes a measurement processor was previously added via :meth:`add_measurement_processor`
+        with the label ``processor_label``.
+
+        Args:
+            processor_label (str)
+        """
+        pass
+
+    @abstractmethod
+    def propagate(self, time: TypeTimestamp) -> None:
+        """
+        Propagate the filter estimate forward in time.
+
+        May be evaluated lazily (when results are requested).
+
+        Args:
+            time (TypeTimestamp)
+        """
+        pass
+
+    @abstractmethod
+    def update(self, processor_label: str, message: Message) -> None:
+        """
+        Update the filter with the given measurement.
+
+        Will propagate first if needed to reach the time encoded inside the measurement.
+
+        Args:
+            processor_label (str)
+            message (Message)
+        """
+        pass
+
+    @abstractmethod
+    def peek_ahead(
+        self, time: TypeTimestamp, block_labels: list[str]
+    ) -> EstimateWithCovariance | None:
+        """
+        Calculates the estimate and covariance at a requested time.
+
+        Uses the state blocks listed in ``block_labels``, without changing the state of the fusion
+        engine or its underlying filter. Blocks are assembled in the order that the labels are
+        passed in.
+
+        If all of the following are true:
+
+        - ``time`` is equal to or after the filter time (which can be checked with :attr:`time`).
+        - All labels in ``block_labels`` correspond to a block that has been added to the fusion
+          engine (which can be checked with :attr:`state_block_labels`).
+        - ``block_labels`` has at least one element.
+
+        Then the result returned is guaranteed to not be ``None``. Otherwise, if any of the above
+        are false then the result will be ``None``.
+
+        Args:
+            time (TypeTimestamp)
+            block_labels (list[str]): An array of strings.
+
+        Returns:
+            EstimateWithCovariance | None
+        """
+        pass
+
+    @abstractmethod
+    def generate_x_and_p(
+        self, block_labels: list[str]
+    ) -> EstimateWithCovariance | None:
+        """
+        Generates the current estimate and covariance.
+
+        Estimate and covariance are built corresponding to a list of StateBlock labels. Blocks are
+        assembled in the order that the labels are passed in.
+
+        If all of the following are true:
+
+            - All labels in ``block_labels`` correspond to a block that has been added to the fusion
+              engine (which can be checked with :attr:`state_block_labels`).
+            - ``block_labels`` has at least one element.
+
+        Then the result returned is guaranteed to not be ``None``. Otherwise, if any of the above
+        are false then the result will be ``None``.
+
+        Args:
+            block_labels (list[str]): An array of strings.
+
+        Returns:
+            EstimateWithCovariance | None
+        """
+        pass
+
+    @abstractmethod
+    def give_state_block_aux_data(
+        self, block_label: str, aux: list[Message | None]
+    ) -> None:
+        """
+        Route a list of messages of aux data to a :class:`pntos.api.StandardStateBlock`.
+
+        Args:
+            block_label (str)
+            aux (list[Message | None])
+        """
+        pass
+
+    @abstractmethod
+    def give_measurement_processor_aux_data(
+        self, processor_label: str, aux: list[Message | None]
+    ) -> None:
+        """
+        Route a list of messages of aux data to a :class:`pntos.api.StandardMeasurementProcessor`.
+
+        Args:
+            processor_label (str)
+            aux (list[Message | None])
+        """
+        pass
+
+    @abstractmethod
+    def give_virtual_state_block_aux_data(
+        self, target_label: str, aux: list[Message | None]
+    ) -> None:
+        """
+        Route a list of messages of aux data to a :class:`pntos.api.VirtualStateBlock`.
+
+        Args:
+            target_label (str)
+            aux (list[Message | None])
+        """
+        pass
+
+
+FusionEngineType = TypeVar('FusionEngineType', StandardFusionEngine, Any)
+"""Enumerates the types of fusion engines.
+
+Currently only StandardFusionEngine is defined, but this TypeVar also includes "Any" in the type
+list for future compatibility.
+"""
+
+
+class FusionPlugin(CommonPlugin, ABC):
+    """
+    Plugin that provides a fusion engine.
+
+    A fusion engine allows data from multiple sensors to be integrated into a unified state
+    estimate.
+    """
+
+    @abstractmethod
+    def is_fusion_type_supported(self, fusion_type: type[FusionEngineType]) -> bool:
+        """
+        Check if the plugin supports a given type of fusion.
+
+        Args:
+            fusion_type (type[FusionEngineType])
+
+        Returns:
+            bool
+        """
+        pass
+
+    @abstractmethod
+    def new_fusion_engine(
+        self, fusion_type: type[FusionEngineType]
+    ) -> FusionEngineType | None:
+        """
+        Create a fusion engine.
+
+        Args:
+            fusion_type (type[FusionEngineType]): This parameter specifies the type of fusion engine that
+                will be returned.
+
+        Returns:
+            FusionEngineType | None: The ``fusion_type`` parameter specifies the type of fusion engine
+            that will be returned. For example, if the user passes in :class:`pntos.api.StandardFusionEngine`,
+            then an implementation of :class:`pntos.api.StandardFusionEngine` will be returned. Returns
+            ``None`` if ``fusion_type`` is not supported by this fusion plugin
+            (:meth:`is_fusion_type_supported` can be used to check the type before calling this
+            method). Otherwise the return is guaranteed to not be ``None``.
+        """
+        pass