kkf 0.11__py3-none-any.whl

kkf/DynamicalSystems.py

@@ -0,0 +1,185 @@
+from typing import Callable, Any, Optional, Union
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import rv_continuous
+
+class DynamicalSystem:
+    """
+    A class representing a general dynamical system with state and measurement equations.
+    
+    This class encapsulates the dynamics, measurements, and associated probability
+    distributions for both state and measurement noise. Can be considered as:
+
+    Discrete time: 
+        Dynamics: x_{k+1} = f(x_{k}) + w_{k}
+        Measurements: y_{k} = g(x_{k}) + v_{k}
+
+    Continous time:
+        Dynamics: x'(t) = f(x(t)) + w(t)
+        Measurements: y(t) = g(x(t)) + v(t)
+    
+    Attributes
+    ----------
+    nx : int
+        Dimension of the state space.
+    ny : int
+        Dimension of the measurement/output space.
+    f : Callable
+        State transition function (dynamics).
+    g : Callable
+        Measurement/output function.
+    dist_X : rv_continuous
+        Probability distribution for initial states.
+    dist_dyn : rv_continuous
+        Probability distribution for dynamics noise.
+    dist_obs : rv_continuous
+        Probability distribution for measurement noise.
+    discrete_time : bool
+        Indicates if the system is in discrete time, if False the system is in continous time.
+        
+    Notes
+    -----
+    The functions f and g should have the following signatures:
+    - f(x: ndarray, w: ndarray) -> ndarray
+    - g(x: ndarray, v: ndarray) -> ndarray
+    where:
+    - x is the state vector
+    - w is the process noise
+    - v is the measurement noise
+    """
+    
+    def __init__(
+        self,
+        nx: int,
+        ny: int,
+        f: Callable[[NDArray[np.float64]], NDArray[np.float64]],
+        g: Callable[[NDArray[np.float64]], NDArray[np.float64]],
+        dist_X: rv_continuous,
+        dist_dyn: rv_continuous,
+        dist_obs: rv_continuous,
+        discrete_time: bool
+    ):
+        self.nx = nx
+        self.ny = ny
+        self.f = f
+        self.g = g
+        self.dist_X = dist_X
+        self.dist_dyn = dist_dyn
+        self.dist_obs = dist_obs
+        self.discrete_time = discrete_time
+        
+    def dynamics(self, x: NDArray[np.float64], w: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Apply the state transition function.
+        
+        Parameters
+        ----------
+        x : np.ndarray
+            Current state vector.
+        w : np.ndarray
+            Process noise vector.
+            
+        Returns
+        -------
+        np.ndarray
+            Next state vector.
+        """
+        return self.f(x) + w
+    
+    def measurements(self, x: NDArray[np.float64], v: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Apply the measurement function.
+        
+        Parameters
+        ----------
+        x : np.ndarray
+            Current state vector.
+        v : np.ndarray
+            Measurement noise vector.
+            
+        Returns
+        -------
+        np.ndarray
+            Measurement/output vector.
+        """
+        return self.g(x) + v
+    
+    def sample_state(self, size: int = 1) -> NDArray[np.float64]:
+        """
+        Sample from the state distribution.
+        
+        Parameters
+        ----------
+        size : int, optional
+            Number of samples to draw. Default is 1.
+            
+        Returns
+        -------
+        np.ndarray
+            Sampled state(s).
+        """
+        return self.dist_X.rvs(size=size).reshape((size, self.nx))
+
+def create_additive_system(
+    nx: int,
+    ny: int,
+    f: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    g: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    dist_X: rv_continuous,
+    dist_dyn: rv_continuous,
+    dist_obs: rv_continuous,
+    N_samples: int,
+    discrete_time: bool = True
+) -> DynamicalSystem:
+    """
+    Create an additive dynamical system where noise is added to the state and observation functions.
+    
+    Parameters
+    ----------
+    nx : int
+        Dimension of the state space.
+    ny : int
+        Dimension of the measurement space.
+    f : Callable
+        State transition function (with noise).
+    g : Callable
+        Measurement function (with noise).
+    dist_X : rv_continuous
+        Initial state distribution.
+    dist_dyn : rv_continuous
+        Dynamics noise distribution.
+    dist_obs : rv_continuous
+        Measurement noise distribution.
+    N_samples: int
+        Number of samples to generate empirical mean of dynamics and observation.
+    discrete_time : bool, optional
+        Indicates if the system is in discrete time. Default is True.
+        
+    Returns
+    -------
+    DynamicalSystem
+        New dynamical system instance with additive noise.
+        
+    Notes
+    -----
+    The resulting system has the form:
+    x[k+1] = f(x[k]) + w[k]
+    y[k] = g(x[k]) + v[k]
+    where w and v are noise terms.
+    """
+    new_f = lambda x: np.mean([f(x.reshape((len(x),1)), dist_dyn.rvs(N_samples))], axis=1)
+    new_g = lambda x: np.mean([g(x.reshape((len(x),1)), dist_obs.rvs(N_samples))], axis=1)
+    class DynDist:
+        def __init__(self):
+            pass
+
+        def rvs(self, x, size=1):
+            return f(x, dist_dyn.rvs(size=size)) - new_f(x)
+        
+    class ObsDist:
+        def __init__(self):
+            pass
+
+        def rvs(self, x, size=1):
+            return g(x, dist_obs.rvs(size=size)) - new_g(x)
+    return DynamicalSystem(nx, ny, new_f, new_g, dist_X, DynDist, ObsDist, discrete_time=discrete_time)

kkf/KKFsol.py

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+import numpy as np
+from numpy.typing import NDArray
+from typing import Optional
+
+import numpy as np
+from numpy.linalg import pinv, cholesky
+from typing import Any, Tuple, Optional, Callable
+from numpy.typing import NDArray
+
+from .covariances import compute_initial_covariance, compute_dynamics_covariance, compute_observation_covariance
+
+@dataclass
+class KoopmanKalmanFilterSolution:
+    """
+    A class to store the solution of a Koopman-Kalman Filter iteration.
+    
+    This class maintains the state estimates, covariance matrices, and filter gains
+    for both the prior (minus) and posterior (plus) estimates in both state and 
+    feature spaces.
+    
+    Attributes
+    ----------
+    x_plus : np.ndarray
+        Posterior state estimate after measurement update.
+    x_minus : np.ndarray
+        Prior state estimate from prediction step.
+    Pz_plus : np.ndarray
+        Posterior covariance matrix in feature space after measurement update.
+    Pz_minus : np.ndarray
+        Prior covariance matrix in feature space from prediction step.
+    Px_plus : np.ndarray
+        Posterior covariance matrix in state space after measurement update.
+    Px_minus : np.ndarray
+        Prior covariance matrix in state space from prediction step.
+    S : np.ndarray
+        Innovation (residual) covariance matrix.
+    K : np.ndarray
+        Kalman gain matrix.
+        
+    Notes
+    -----
+    The class uses the common Kalman filter notation where:
+    - (-) denotes prior estimates before measurement update
+    - (+) denotes posterior estimates after measurement update
+    - Pz refers to covariances in the feature/transformed space
+    - Px refers to covariances in the original state space
+    
+    Examples
+    --------
+    >>> solution = KoopmanKalmanFilterSolution(
+    ...     x_plus=np.array([1.0, 2.0]),
+    ...     x_minus=np.array([0.9, 1.9]),
+    ...     Pz_plus=np.eye(2),
+    ...     Pz_minus=np.eye(2) * 1.1,
+    ...     Px_plus=np.eye(2) * 0.9,
+    ...     Px_minus=np.eye(2),
+    ...     S=np.eye(2) * 0.5,
+    ...     K=np.array([[0.1, 0], [0, 0.1]])
+    ... )
+    """
+    
+    x_plus: NDArray[np.float64]
+    x_minus: NDArray[np.float64]
+    Pz_plus: NDArray[np.float64]
+    Pz_minus: NDArray[np.float64]
+    Px_plus: NDArray[np.float64]
+    Px_minus: NDArray[np.float64]
+    S: NDArray[np.float64]
+    K: NDArray[np.float64]
+    
+    def __post_init__(self):
+        """Validate the dimensions of the input arrays."""
+        # Ensure all inputs are numpy arrays
+        for attr in ['x_plus', 'x_minus', 'Pz_plus', 'Pz_minus', 
+                    'Px_plus', 'Px_minus', 'S', 'K']:
+            value = getattr(self, attr)
+            if not isinstance(value, np.ndarray):
+                setattr(self, attr, np.array(value))
+    
+    def get_state_dimension(self) -> int:
+        """
+        Get the dimension of the state vector.
+        
+        Returns
+        -------
+        int
+            The dimension of the state vector.
+        """
+        return len(self.x_plus)
+    
+    def get_feature_dimension(self) -> int:
+        """
+        Get the dimension of the feature space.
+        
+        Returns
+        -------
+        int
+            The dimension of the feature space.
+        """
+        return self.Pz_plus.shape[0]
+    
+    def get_estimation_error(self) -> NDArray[np.float64]:
+        """
+        Calculate the difference between prior and posterior estimates.
+        
+        Returns
+        -------
+        np.ndarray
+            The difference between posterior and prior state estimates.
+        """
+        return self.x_plus - self.x_minus
+    
+    def get_trace_reduction(self) -> float:
+        """
+        Calculate the reduction in uncertainty as measured by trace of covariance.
+        
+        Returns
+        -------
+        float
+            The relative reduction in trace of the state covariance matrix.
+        """
+        trace_minus = np.trace(self.Px_minus)
+        trace_plus = np.trace(self.Px_plus)
+        return (trace_minus - trace_plus) / trace_minus if trace_minus != 0 else 0.0
+    
+    def to_dict(self) -> dict:
+        """
+        Convert the solution to a dictionary format.
+        
+        Returns
+        -------
+        dict
+            Dictionary containing all solution components.
+        """
+        return {
+            'x_plus': self.x_plus,
+            'x_minus': self.x_minus,
+            'Pz_plus': self.Pz_plus,
+            'Pz_minus': self.Pz_minus,
+            'Px_plus': self.Px_plus,
+            'Px_minus': self.Px_minus,
+            'S': self.S,
+            'K': self.K
+        }

kkf/__init__.py

@@ -0,0 +1,5 @@
+# __init__.py
+from .covariances import compute_initial_covariance, compute_dynamics_covariance, compute_observation_covariance
+from .DynamicalSystems import DynamicalSystem, create_additive_system
+from .kEDMD import KoopmanOperator
+from .KKFsol import KoopmanKalmanFilterSolution

kkf/applyKKF.py

@@ -0,0 +1,228 @@
+from dataclasses import dataclass
+import numpy as np
+from numpy.linalg import pinv, cholesky
+from numpy.typing import NDArray
+
+from typing import Any, Tuple, Optional, Callable
+
+from .covariances import compute_initial_covariance, compute_dynamics_covariance, compute_observation_covariance
+from .KKFsol import KoopmanKalmanFilterSolution
+
+def apply_koopman_kalman_filter(
+    koopman_operator: Any,
+    observations: NDArray[np.float64],
+    initial_distribution: Any,
+    n_features: int,
+    optimize: bool = True,
+    n_restarts_optimizer: int = 10,
+    noise_samples: int = 100
+) -> 'KoopmanKalmanFilterSolution':
+    """
+    Implementation of the Koopman-Kalman Filter algorithm.
+    
+    This function combines Koopman operator theory with Kalman filtering to perform
+    state estimation for nonlinear dynamical systems. It operates by lifting the
+    state space to a higher-dimensional feature space where the dynamics are
+    approximately linear.
+    
+    Parameters
+    ----------
+    koopman_operator : object
+        Object containing Koopman operator methods and attributes:
+        - kEDMD(n_features): Extended Dynamic Mode Decomposition method
+        - dyn_sys: Dynamical system object
+        - U, B, C: Matrices for Koopman approximation
+        - phi: Feature map function
+    observations : np.ndarray
+        Array of shape (n_timesteps, n_outputs) containing system measurements.
+    initial_distribution : object
+        Distribution object for initial state with methods:
+        - mean: Returns mean of initial state
+        - rvs: Random sampling method
+    n_features : int
+        Number of features in the lifted space.
+    optimize : bool, optional
+        Whether to optimize the kernel parameters. Default is True.
+    n_restarts_optimizer : int, optional
+        Number of restarts for kernel optimization. Default is 10.
+    noise_samples : int, optional
+        Number of samples for noise covariance estimation. Default is 100.
+        
+    Returns
+    -------
+    KoopmanKalmanFilterSolution
+        Object containing all filter estimates and covariances.
+        
+    Notes
+    -----
+    The algorithm consists of three main phases:
+    1. Initialization:
+       - Sets up initial states and covariances
+       - Computes Koopman approximation
+    
+    2. Prediction Step:
+       - Projects state forward using system dynamics
+       - Updates covariances using Koopman operator
+    
+    3. Update Step:
+       - Incorporates new measurements
+       - Updates state and covariance estimates
+    
+    The filter operates in both the original state space (x) and the lifted
+    feature space (z), maintaining estimates and covariances in both spaces.
+    """
+    # Compute Koopman approximation
+    koopman_operator.compute_edmd(n_features, optimize, n_restarts_optimizer)
+    dynamical_system = koopman_operator.dynamical_system
+
+    # Extract system and Koopman components
+    state_dynamics = dynamical_system.f
+    measurement_model = dynamical_system.g
+    U, B, C = koopman_operator.U, koopman_operator.B, koopman_operator.C
+    phi = koopman_operator.phi
+
+    ### Initialization ###
+    x0 = initial_distribution.mean  # Initial state estimate
+    z0 = phi(x0)  # Initial state in feature space
+
+    # Get problem dimensions
+    n_timesteps, n_states = observations.shape[0], len(x0)
+    n_outputs = observations.shape[1]
+
+    # Initialize state arrays
+    x_minus, x_plus = _initialize_state_arrays(n_timesteps, n_states)
+    z_minus, z_plus = _initialize_state_arrays(n_timesteps, n_features)
+    
+    # Initialize covariance arrays
+    Px_minus, Px_plus = _initialize_covariance_arrays(n_timesteps, n_states)
+    Pz_minus, Pz_plus = _initialize_covariance_arrays(n_timesteps, n_features)
+    
+    # Initialize filter matrices
+    S = np.zeros((n_timesteps, n_outputs, n_outputs))  # Innovation covariance
+    K = np.zeros((n_timesteps, n_features, n_outputs))  # Kalman gain
+
+    # Set initial conditions
+    x_minus[0, :], x_plus[0, :] = x0, x0
+    z_minus[0, :], z_plus[0, :] = z0, z0
+
+    # Initialize covariances
+    initial_covariance = compute_initial_covariance(
+        x_minus[0, :], n_features, initial_distribution, 
+        koopman_operator, noise_samples
+    )
+    Pz_minus[0, :, :], Pz_plus[0, :, :] = initial_covariance, initial_covariance
+
+    ### Main Filter Loop ###
+    for t in range(1, n_timesteps):
+        # Prediction Step
+        x_minus[t], z_minus[t], Pz_minus[t] = _prediction_step(
+            x_plus[t-1], z_plus[t-1], Pz_plus[t-1],
+            state_dynamics, phi, U, dynamical_system,
+            koopman_operator, n_features, noise_samples
+        )
+
+        # Update Step
+        x_plus[t], z_plus[t], Pz_plus[t], S[t], K[t] = _update_step(
+            x_minus[t], z_minus[t], Pz_minus[t],
+            observations[t], measurement_model,
+            C, B, dynamical_system, noise_samples
+        )
+
+        # Update state-space covariances
+        Px_minus[t], Px_plus[t] = _update_state_covariances(
+            Pz_minus[t], Pz_plus[t], B
+        )
+
+    return KoopmanKalmanFilterSolution(
+        x_plus, x_minus, Pz_plus, Pz_minus, Px_plus, Px_minus, S, K
+    )
+
+def _initialize_state_arrays(
+    n_timesteps: int, 
+    n_dim: int
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Initialize arrays for state estimates."""
+    return (np.zeros((n_timesteps, n_dim)), 
+            np.zeros((n_timesteps, n_dim)))
+
+def _initialize_covariance_arrays(
+    n_timesteps: int, 
+    n_dim: int
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Initialize arrays for covariance matrices."""
+    return (np.zeros((n_timesteps, n_dim, n_dim)), 
+            np.zeros((n_timesteps, n_dim, n_dim)))
+
+def _prediction_step(
+    x_prev: NDArray[np.float64],
+    z_prev: NDArray[np.float64],
+    Pz_prev: NDArray[np.float64],
+    state_dynamics: Callable,
+    phi: Callable,
+    U: NDArray[np.float64],
+    dynamical_system: Any,
+    koopman_operator: Any,
+    n_features: int,
+    noise_samples: int
+) -> Tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Perform the prediction step of the filter."""
+    # Compute dynamics covariance
+    Qz = compute_dynamics_covariance(
+        x_prev, n_features, dynamical_system, 
+        koopman_operator, noise_samples
+    )
+    
+    # Predict states
+    x_pred = state_dynamics(x_prev, )
+    z_pred = phi(x_pred)
+    
+    # Predict covariance
+    Pz_pred = U @ Pz_prev @ U.T + Qz
+    
+    return x_pred, z_pred, Pz_pred
+
+def _update_step(
+    x_minus: NDArray[np.float64],
+    z_minus: NDArray[np.float64],
+    Pz_minus: NDArray[np.float64],
+    observation: NDArray[np.float64],
+    measurement_model: Callable,
+    C: NDArray[np.float64],
+    B: NDArray[np.float64],
+    dynamical_system: Any,
+    noise_samples: int
+) -> Tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], 
+           NDArray[np.float64], NDArray[np.float64]]:
+    """Perform the update step of the filter."""
+    # Compute measurement covariance
+    Rz = compute_observation_covariance(
+        x_minus, len(observation), dynamical_system, noise_samples
+    )
+    
+    # Compute innovation
+    innovation = observation - measurement_model(x_minus)
+    
+    # Compute innovation covariance
+    S = C @ Pz_minus @ C.T + Rz
+    
+    # Compute Kalman gain
+    K = Pz_minus @ C.T @ pinv(cholesky(S))
+    
+    # Update states
+    z_plus = z_minus + K @ innovation
+    x_plus = B @ z_plus
+    
+    # Update covariance
+    Pz_plus = (np.eye(len(z_minus)) - K @ C) @ Pz_minus
+    
+    return x_plus, z_plus, Pz_plus, S, K
+
+def _update_state_covariances(
+    Pz_minus: NDArray[np.float64],
+    Pz_plus: NDArray[np.float64],
+    B: NDArray[np.float64]
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Update covariances in the state space."""
+    Px_minus = B @ Pz_minus @ B.T
+    Px_plus = B @ Pz_plus @ B.T
+    return Px_minus, Px_plus

kkf/covariances.py

@@ -0,0 +1,162 @@
+import numpy as np
+from typing import Callable, Any, Union
+from scipy.stats import rv_continuous
+from numpy.typing import NDArray
+
+def compute_initial_covariance(
+    x: NDArray[np.float64],
+    n_features: int,
+    initial_distribution: rv_continuous,
+    koopman_operator: Any,
+    n_samples: int
+) -> NDArray[np.float64]:
+    """
+    Compute the covariance matrix for the initial distribution in feature space.
+    
+    This function samples from an initial distribution and computes the covariance
+    matrix of the transformed samples using a Koopman operator's feature map.
+    
+    Parameters
+    ----------
+    x : np.ndarray
+        Current state vector or reference point.
+    n_features : int
+        Number of features in the transformed space.
+    initial_distribution : scipy.stats.rv_continuous
+        Initial probability distribution to sample from.
+    koopman_operator : object
+        Object containing the feature map phi method for state transformation.
+        Must have a method phi(x) that maps states to feature space.
+    n_samples : int
+        Number of samples to use for covariance estimation.
+        
+    Returns
+    -------
+    np.ndarray
+        Covariance matrix of size (n_features, n_features) in the transformed space.
+        
+    Notes
+    -----
+    The function performs the following steps:
+    1. Samples from the initial distribution
+    2. Applies the Koopman operator's feature map to each sample
+    3. Computes the covariance matrix of the transformed samples
+    """
+    # Sample from initial distribution
+    samples = initial_distribution.rvs(size=n_samples).reshape((n_samples, len(x)))
+    
+    # Initialize array for transformed samples
+    transformed_samples = np.zeros((n_samples, n_features))
+    
+    # Transform each sample using the feature map
+    for i in range(n_samples):
+        transformed_samples[i, :] = koopman_operator.phi(samples[i,:])
+    
+    # Compute and return covariance matrix
+    return np.cov(transformed_samples, rowvar=False)
+
+def compute_dynamics_covariance(
+    x: NDArray[np.float64],
+    n_features: int,
+    dynamics: Any,
+    koopman_operator: Any,
+    n_samples: int
+) -> NDArray[np.float64]:
+    """
+    Compute the covariance matrix for the system dynamics in feature space.
+    
+    This function samples from the dynamics distribution, applies the system
+    dynamics, and computes the covariance matrix of the transformed results.
+    
+    Parameters
+    ----------
+    x : np.ndarray
+        Current state vector or reference point.
+    n_features : int
+        Number of features in the transformed space.
+    dynamics : object
+        Dynamical system object containing:
+        - dist_dyn: scipy.stats.rv_continuous distribution for dynamics noise
+        - dynamics(x, w): method implementing the system dynamics
+    koopman_operator : object
+        Object containing the feature map phi method for state transformation.
+        Must have a method phi(x) that maps states to feature space.
+    n_samples : int
+        Number of samples to use for covariance estimation.
+        
+    Returns
+    -------
+    np.ndarray
+        Covariance matrix of size (n_features, n_features) in the transformed space.
+        
+    Notes
+    -----
+    The function performs the following steps:
+    1. Samples from the dynamics noise distribution
+    2. Applies the system dynamics to each sample
+    3. Transforms the results using the Koopman operator's feature map
+    4. Computes the covariance matrix of the transformed samples
+    """
+    # Sample from dynamics distribution
+    noise_samples = dynamics.dist_dyn.rvs(size=n_samples).reshape((n_samples, len(x)))
+    
+    # Initialize array for transformed samples
+    transformed_samples = np.zeros((n_samples, n_features))
+    
+    # Apply dynamics and transform each sample
+    for i in range(n_samples):
+        state_evolution = dynamics.dynamics(x, noise_samples[i,:])
+        transformed_samples[i, :] = koopman_operator.phi(state_evolution)
+    
+    # Compute and return covariance matrix
+    return np.cov(transformed_samples, rowvar=False)
+
+def compute_observation_covariance(
+    x: NDArray[np.float64],
+    n_outputs: int,
+    dynamics: Any,
+    n_samples: int
+) -> NDArray[np.float64]:
+    """
+    Compute the covariance matrix for the observation/measurement process.
+    
+    This function samples from the measurement noise distribution and computes
+    the covariance matrix of the measurement process.
+    
+    Parameters
+    ----------
+    x : np.ndarray
+        Current state vector or reference point.
+    n_outputs : int
+        Number of measurement outputs.
+    dynamics : object
+        Dynamical system object containing:
+        - dist_obs: scipy.stats.rv_continuous distribution for measurement noise
+        - measurements(x, w): method implementing the measurement process
+    n_samples : int
+        Number of samples to use for covariance estimation.
+        
+    Returns
+    -------
+    np.ndarray
+        Covariance matrix of size (n_outputs, n_outputs) for the measurement process.
+        
+    Notes
+    -----
+    The function performs the following steps:
+    1. Samples from the measurement noise distribution
+    2. Applies the measurement function to each sample
+    3. Computes the covariance matrix of the measurements
+    """
+    # Sample from measurement distribution
+    noise_samples = dynamics.dist_obs.rvs(size=n_samples).reshape((n_samples, n_outputs))
+    
+    # Initialize array for measurements
+    measurement_samples = np.zeros((n_samples, n_outputs))
+    
+    # Apply measurement function to each sample
+    for i in range(n_samples):
+        measurement_samples[i, :] = dynamics.measurements(x, noise_samples[i,:])
+    
+    # Compute and return covariance matrix
+    return np.cov(measurement_samples, rowvar=False)

kkf/kEDMD.py

@@ -0,0 +1,147 @@
+from typing import Callable, Any, Optional, Union
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import rv_continuous
+from sklearn.gaussian_process.kernels import Kernel
+from sklearn.gaussian_process import GaussianProcessRegressor
+from .DynamicalSystems import DynamicalSystem, create_additive_system
+
+class KoopmanOperator:
+    """
+    Implementation of Koopman operator approximation using kernel-based Extended 
+    Dynamic Mode Decomposition (kEDMD).
+    
+    This class provides methods to compute finite-dimensional approximations of the
+    Koopman operator for nonlinear dynamical systems.
+    
+    Attributes
+    ----------
+    kernel_function : Callable
+        Kernel function for computing feature space mappings.
+    dynamical_system : DynamicalSystem
+        The underlying dynamical system.
+    X : Optional[np.ndarray]
+        Dictionary of states used for kernel computations.
+    phi : Optional[Callable]
+        Feature map function.
+    U : Optional[np.ndarray]
+        Koopman operator matrix.
+    G : Optional[np.ndarray]
+        Gram matrix.
+    C : Optional[np.ndarray]
+        Output matrix.
+    B : Optional[np.ndarray]
+        State-to-feature space transformation matrix.
+        
+    Notes
+    -----
+    The Koopman operator framework lifts nonlinear dynamics to a linear setting
+    in a higher-dimensional feature space. This implementation uses kernel methods
+    to compute the necessary feature spaces and operators.
+    """
+    
+    def __init__(
+        self,
+        kernel_function: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+        dynamical_system: DynamicalSystem
+    ):
+        self.kernel_function = kernel_function
+        self.dynamical_system = dynamical_system
+        self.X: Optional[NDArray[np.float64]] = None
+        self.phi: Optional[Callable] = None
+        self.U: Optional[NDArray[np.float64]] = None
+        self.G: Optional[NDArray[np.float64]] = None
+        self.C: Optional[NDArray[np.float64]] = None
+        self.B: Optional[NDArray[np.float64]] = None
+        
+    def compute_edmd(self, n_features: int, optimize: bool = True, n_restarts_optimizer: int = 10) -> None:
+        """
+        Compute the kernel-based Extended Dynamic Mode Decomposition (kEDMD).
+        
+        This method constructs finite-dimensional approximations of the Koopman
+        operator and associated matrices using kernel methods.
+        
+        Parameters
+        ----------
+        n_features : int
+            Number of features to use in the approximation.
+
+        optimize : bool
+            Whether to optimize the kernel function. If True, the method will
+            optimize the kernel function using Gaussian Process Regression. If False, 
+            the provided kernel function will be used without optimization. Default is True.
+
+        n_restarts_optimizer : int
+            Number of restarts for the optimizer. If optimize is False, will be ignored. Default is 10.
+            
+        Notes
+        -----
+        The method performs the following steps:
+        1. Generates dictionary points using the state distribution
+        2. Constructs the feature map using the kernel function
+        3. Computes the Gram matrix and its inverse
+        4. Constructs the Koopman operator approximation
+        5. Computes output and state transformation matrices
+        """
+        # Extract system components
+        f, g = self.dynamical_system.f, self.dynamical_system.g
+        
+        # Generate dictionary points
+        self.X = self.dynamical_system.sample_state(n_features)
+
+        # Optimize kernel function
+        if optimize:
+            self.opt_kernel(X=self.X, n_restarts_optimizer=n_restarts_optimizer)
+        
+        # Define feature map
+        self.phi = lambda x: self.kernel_function(x, self.X)[0]
+        
+        # Compute Gram matrix
+        self.G = self.kernel_function(self.X, self.X)
+        G_inv = np.linalg.inv(self.G)
+        
+        # Compute Koopman operator approximation
+        next_states = f(self.X.T).T
+        self.U = self.kernel_function(self.X, next_states) @ G_inv
+        
+        # Compute output and state transformation matrices
+        self.C = g(self.X.T) @ G_inv
+        self.B = self.X.T @ G_inv
+        
+    def get_feature_dimension(self) -> Optional[int]:
+        """
+        Get the dimension of the feature space.
+        
+        Returns
+        -------
+        Optional[int]
+            Dimension of the feature space, or None if EDMD hasn't been computed.
+        """
+        return self.X.shape[0] if self.X is not None else None
+
+    def opt_kernel(self, X: NDArray[np.float64], n_restarts_optimizer: int = 10) -> None:
+        """
+        Optimal kernel function for the Koopman operator.
+        
+        Parameters
+        ----------
+        X : np.ndarray
+            Set of points.
+
+        n_restarts_optimizer : int
+            Number of restarts for the optimizer. Default is 10.
+            
+        Notes
+        -----
+        This method uses Gaussian Process Regression to optimize the kernel function.
+        """
+        # Compute the output of the dynamical system
+        y = self.dynamical_system.f(X.T).T
+
+        # Fit the Gaussian process
+        gp = GaussianProcessRegressor(kernel=self.kernel_function, n_restarts_optimizer=n_restarts_optimizer)
+        gp.fit(X.T, y.T)
+
+        # Return the optimal kernel
+        self.kernel_function = gp.kernel_
+        

kkf-0.11.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 diegoolguinw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kkf-0.11.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.1
+Name: kkf
+Version: 0.11
+Summary: kkf: a library for Python implementation of Kernel-Koopman-Kalman Filter.
+Home-page: https://github.com/diegoolguinw/kkf
+Author: Diego Olguin-Wende
+Author-email: dolguin@dim.uchile.cl
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+
+# Kernel Koopman Kalman Filter
+
+KKKF is a Python library that implements kernel Extended Dynamic Mode Decomposition (EDMD) of Koopman operators and provides a non-linear variant of the Kalman Filter. This library is particularly useful for state estimation in dynamical systems with non-linear behavior.
+
+## Installation
+
+You can install KKKF using pip:
+
+```bash
+pip install KKKF
+```
+
+## Features
+
+- Kernel-based Extended Dynamic Mode Decomposition (EDMD)
+- Non-linear Kalman Filter implementation
+- Support for general dynamical systems
+- Integration with various kernel functions (e.g., Matérn kernel)
+- Robust state estimation with noise handling
+
+## Dependencies
+
+- NumPy
+- SciPy
+- scikit-learn (for kernel functions)
+- Matplotlib (for visualization)
+
+## Quick Start
+
+Here's a complete example of using KKKF to estimate and visualize states in a SIR (Susceptible-Infected-Recovered) model:
+
+```python
+# Dependencies
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy import stats
+from sklearn.gaussian_process.kernels import Matern
+from KKKF.DynamicalSystems import DynamicalSystem
+from KKKF.kEDMD import KoopmanOperator
+from KKKF.applyKKKF import apply_koopman_kalman_filter
+
+# Define system parameters
+beta, gamma = 0.12, 0.04
+
+# Define system dynamics
+def f(x):
+    return x + np.array([-beta*x[0]*x[1], beta*x[0]*x[1] - gamma*x[1], gamma*x[1]])
+
+# Define system observations
+def g(x):
+    return np.array([x[1]])
+
+# Setup system dimensions and kernel
+N = 300
+nx, ny = 3, 1
+k = Matern(length_scale=N**(-1/nx), nu=0.5)
+
+# Setup distributions
+X_dist = stats.dirichlet(alpha=np.ones(nx))
+dyn_dist = stats.multivariate_normal(mean=np.zeros(nx), cov=1e-5*np.eye(3))
+obs_dist = stats.multivariate_normal(mean=np.zeros(ny), cov=1e-3*np.eye(1))
+
+# Create dynamical system
+dyn = DynamicalSystem(nx, ny, f, g, X_dist, dyn_dist, obs_dist)
+
+# Generate synthetic data
+iters = 100
+x0 = np.array([0.9, 0.1, 0.0])
+x = np.zeros((iters, nx))
+y = np.zeros((iters, ny))
+
+x[0] = x0
+y[0] = g(x[0]) + obs_dist.rvs()
+
+for i in range(1, iters):
+    x[i] = f(x[i-1]) + dyn.dist_dyn.rvs()
+    y[i] = g(x[i]) + obs_dist.rvs()
+
+# Initialize and apply Koopman Kalman Filter
+
+# Prior for the initial condition
+x0_prior = np.array([0.8, 0.15, 0.05])
+d0 = stats.multivariate_normal(mean=x0_prior, cov=0.1*np.eye(3))
+
+# Koopman operator
+Koop = KoopmanOperator(k, dyn)
+
+# Solution
+sol = apply_koopman_kalman_filter(Koop, y, d0, N, noise_samples=100)
+
+# Visualization with confidence intervals
+conf = np.zeros((iters, nx))
+for i in range(iters):
+    conf[i, :] = np.sqrt(np.diag(sol.Px_plus[i,:,:]))
+
+# 95% confidence interval
+err1 = sol.x_plus - 1.96*conf
+err2 = sol.x_plus + 1.96*conf
+
+# Plot elements
+labels = ["S (True)", "I (True)", "R (True)"]
+colors = ["blue", "red", "green"]
+
+plt.plot(sol.x_plus, label=["S (KKF)", "I (KKF)", "R (KKF)"])
+
+for i in range(nx):
+    plt.fill_between(np.arange(iters), err1[:,i], err2[:,i], alpha=0.6)
+    plt.scatter(np.arange(iters), x[:,i], label=labels[i], color=colors[i], s=1.4)
+
+plt.xlabel("Days")
+plt.ylabel("Propotion of population")
+plt.title("KKKF Estimation")
+plt.legend()
+plt.show()
+```
+
+## API Reference
+
+### DynamicalSystem
+
+```python
+DynamicalSystem(nx, ny, f, g, X_dist, dyn_dist, obs_dist)
+```
+Creates a dynamical system with:
+- `nx`: State dimension
+- `ny`: Observation dimension
+- `f`: State transition function
+- `g`: Observation function
+- `X_dist`: State distribution
+- `dyn_dist`: Dynamic noise distribution
+- `obs_dist`: Observation noise distribution
+
+### KoopmanOperator
+
+```python
+KoopmanOperator(kernel, dynamical_system)
+```
+Initializes a Koopman operator with:
+- `kernel`: Kernel function (e.g., Matérn kernel)
+- `dynamical_system`: Instance of DynamicalSystem
+
+### apply_koopman_kalman_filter
+
+```python
+apply_koopman_kalman_filter(koopman, observations, initial_distribution, N, noise_samples=100)
+```
+Applies the Koopman-based Kalman filter with:
+- `koopman`: KoopmanOperator instance
+- `observations`: Observation data
+- `initial_distribution`: Initial state distribution
+- `N`: Number of samples
+- `noise_samples`: Number of noise samples for uncertainty estimation
+
+Returns a solution object containing:
+- `x_plus`: State estimates
+- `Px_plus`: Covariance matrices
+- Additional filter statistics
+
+## Visualization
+
+The library supports visualization of results with confidence intervals. The example above demonstrates how to:
+- Plot state estimates
+- Add confidence intervals (shaded regions)
+- Compare with real data (if available)
+- Customize plot appearance
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{kkkf,
+  title = {KKKF: Kernel Koopman Kalman Filter},
+  year = {2024},
+  author = {Diego Olguín-Wende},
+  url = {https://github.com/diegoolguinw/KKKF}
+}
+```

kkf-0.11.dist-info/RECORD

@@ -0,0 +1,12 @@
+kkf/DynamicalSystems.py,sha256=rVtnyaHkAVvbc_cVF4cuLp2jH78lqlLpav2DijspsV0,5519
+kkf/KKFsol.py,sha256=1OJf3ILunJavRnvHMQQF-gR4eG6F6Z-qb_6ZdrIJlyY,4613
+kkf/__init__.py,sha256=NV_a6HLBOlB-0Db21t2g2ZXMQ0vcb3s-LYylO8vxebA,279
+kkf/applyKKF.py,sha256=_65n-PUp3AqccrjYModDgdNY48Qgc59Lp-v75NJHzGE,7887
+kkf/covariances.py,sha256=m7J10FSQj6hVSyJBUVjl4Rf_Gn87NWRqyBQvqLmHSV4,5812
+kkf/kEDMD.py,sha256=ihxD8If5XxCNrZBJsEeFpeMJZHZjpPxnCZYDCHxS628,5467
+kkf/utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kkf-0.11.dist-info/LICENSE,sha256=6WnhMjAMnLiDcClR0tHyWuaX8lEs0MSn5R51JqXL7Ts,1069
+kkf-0.11.dist-info/METADATA,sha256=h_-BrDZrdELzzACjoI4C42qNONhw5JiF5ifMeUEBYDc,5494
+kkf-0.11.dist-info/WHEEL,sha256=2wepM1nk4DS4eFpYrW1TTqPcoGNfHhhO_i5m4cOimbo,92
+kkf-0.11.dist-info/top_level.txt,sha256=_KexmN1Hv2HyrRJoTbhwHIS1S9dmHS1wsXA0gIW1Bls,4
+kkf-0.11.dist-info/RECORD,,

kkf-0.11.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.38.4)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kkf-0.11.dist-info/top_level.txt

@@ -0,0 +1 @@
+kkf