Source code for Karana.Models.DataPlotter

# Copyright (c) 2024-2025 Karana Dynamics Pty Ltd. All rights reserved.
#
# NOTICE TO USER:
#
# This source code and/or documentation (the "Licensed Materials") is
# the confidential and proprietary information of Karana Dynamics Inc.
# Use of these Licensed Materials is governed by the terms and conditions
# of a separate software license agreement between Karana Dynamics and the
# Licensee ("License Agreement"). Unless expressly permitted under that
# agreement, any reproduction, modification, distribution, or disclosure
# of the Licensed Materials, in whole or in part, to any third party
# without the prior written consent of Karana Dynamics is strictly prohibited.
#
# THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
# KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
# BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
# FITNESS FOR A PARTICULAR PURPOSE.
#
# IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
# INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
# OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
#
# U.S. Government End Users: The Licensed Materials are a "commercial item"
# as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
# only as a commercial end item under the terms of this license.
#
# Any use of the Licensed Materials in individual or commercial software must
# include, in the user documentation and internal source code comments,
# this Notice, Disclaimer, and U.S. Government Use Provision.

"""This file contains the DataPlotter model.

A model that can be used to update DashApp plots.
"""

from typing import Annotated, TYPE_CHECKING
import numpy as np
from numpy.typing import ArrayLike
from Karana.Core import warn
from Karana.Models import KModel, KModelParams
from Karana.KUtils.DataPlotter import DashApp

if TYPE_CHECKING:
    from Karana.Dynamics import StatePropagator




class DataPlotterParams(KModelParams):
    """Parameter class for DataPlotter model.

    Parameters
    ----------
    plot_first_step: bool
        If True, then update the plot on the first step. Otherwise, the first update
        will happen at the postModelStep.
    dash_app: DashApp
        The DashApp to update.
    """

    plot_first_step: bool = True
    dash_app: DashApp = None  # pyright: ignore



    def isFinalized(self) -> bool:
        """Ensure  the DataPlotterParams are finalized.

        Returns
        -------
        bool
            True if finalized, False otherwise.
        """
        flag = True
        if self.dash_app is None:
            warn("DashApp is not initialized.")
            flag = False
        return flag






class DataPlotter(KModel):
    """DataPlotter model.

    This model updates a DashApp at the specified interval.
    """

    params: DataPlotterParams

    def __init__(self, name: str, sp: "StatePropagator"):
        """Create an instance of DataPlotter."""
        super().__init__(name, sp)
        self.params = DataPlotterParams()  # pyright: ignore
        sp.registerModel(self)



    def postModelStep(
        self, t: float | np.timedelta64, x: Annotated[ArrayLike, np.float64, "[m, 1]"]
    ):  # pyright: ignore
        """Update the DashApp.

        Parameters
        ----------
        t : float | np.timedelta64
            Current time. Unused.
        x : Annotated[ArrayLike, np.float64, '[m, 1]']
            Current state vector. Unused.
        """
        self.params.dash_app.update()


    def _registerModel(self):
        """Register DataPlotter with the StatePropagator."""
        super()._registerModel()

        if self.params.plot_first_step:
            from Karana.Dynamics import TimedEvent

            # If plot_first_step is set, then update the event for the current time.
            te = TimedEvent(
                f"{self.name()}_first_step",
                self.state_propagator.getTime(),
                lambda _: self.params.dash_app.update(),
                True,
            )
            self.state_propagator.registerTimedEvent(te)

    def _unregisterModel(self):
        """Register DataPlotter with the StatePropagator."""
        super()._unregisterModel()

        self.state_propagator.unregisterTimedEvent(f"{self.name()}_first_step", True, True)