kkf 0.11__tar.gz

kkf-0.11/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/PKG-INFO

@@ -0,0 +1,200 @@
+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
+
+# 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/README.md

@@ -0,0 +1,186 @@
+# 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/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)