### Test SIMD Kalman installation from TestPyPI

Source: https://github.com/oseiskar/simdkalman/blob/master/README.md

This command demonstrates how to test an installation of the SIMD Kalman library from the TestPyPI repository, including installing matplotlib and running an example script.

```bash
source venvs/test-pythonNNN/bin/activate
pip install \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple \
    simdkalman --upgrade
pip install matplotlib
python examples/example.py
deactivate
```

--------------------------------

### Install SIMD Kalman using pip

Source: https://github.com/oseiskar/simdkalman/blob/master/README.md

This command shows the basic installation of the SIMD Kalman library using pip, the standard Python package installer.

```bash
pip install simdkalman
```

--------------------------------

### Set up development environment for SIMD Kalman

Source: https://github.com/oseiskar/simdkalman/blob/master/README.md

These commands outline the steps for setting up a local development environment for SIMD Kalman, including creating and activating virtual environments, installing development dependencies, and running tests.

```bash
1. Create virtualenv
   * Python 2: virtualenv venvs/python2
   * Python 3: python3 -m venv venvs/python3
2. Activate virtualenv: source venvs/pythonNNN/bin/activate
3. Install locally pip install -e .[dev,test,docs]
4. ./run-tests.sh
5. deactivate virtualenv
```

--------------------------------

### Implement Extended Kalman Filter (EKF) for Object Tracking

Source: https://context7.com/oseiskar/simdkalman/llms.txt

This example shows how to implement an EKF using simdkalman primitives. It performs linearization by dynamically computing the Jacobian matrix H based on distance measurements to sensors.

```python
import numpy as np
import simdkalman

class SimpleEKF:
    def __init__(self, n_objects, sensor_positions):
        self.sensors = sensor_positions
        STATE_DIM = 2
        OBS_DIM = len(sensor_positions)
        self.m = np.zeros((n_objects, STATE_DIM, 1))
        self.P = np.eye(STATE_DIM)[np.newaxis, ...] * 10.0
        self.P = np.tile(self.P, (n_objects, 1, 1))
        self.A = np.eye(STATE_DIM)[np.newaxis, ...]
        self.A = np.tile(self.A, (n_objects, 1, 1))
        self.Q = np.eye(STATE_DIM)[np.newaxis, ...] * 0.05**2
        self.Q = np.tile(self.Q, (n_objects, 1, 1))
        self.R = np.eye(OBS_DIM)[np.newaxis, ...] * 0.1**2
        self.R = np.tile(self.R, (n_objects, 1, 1))

    def predict(self):
        self.m, self.P = simdkalman.primitives.predict(self.m, self.P, self.A, self.Q)

    def update(self, distance_observations):
        est_deltas = self.m[:, np.newaxis, :, 0] - self.sensors[np.newaxis, :, :]
        est_distances = np.sqrt(np.sum(est_deltas**2, axis=2))[..., np.newaxis]
        H = est_deltas / est_distances
        y_lin = distance_observations - est_distances + simdkalman.primitives.ddot(H, self.m)
        self.m, self.P = simdkalman.primitives.update(self.m, self.P, H, self.R, y_lin)
```

--------------------------------

### Initialize KalmanFilter for Vectorized Operations

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Demonstrates how to initialize the KalmanFilter class for vectorized Kalman filtering. This includes defining state transition, process noise, observation model, and observation noise. The example shows creating sample data with missing values for batch processing.

```python
import simdkalman
import numpy as np

# Define a Kalman filter with state transition, process noise, observation model, and observation noise
# State: [position, velocity], Observation: position only
kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),    # A: state transition matrix
    process_noise = np.diag([0.1, 0.01]),             # Q: process noise covariance
    observation_model = np.array([[1, 0]]),           # H: observation model matrix
    observation_noise = 1.0                            # R: observation noise variance
)

# Create sample data: 100 independent time series, each with 200 observations
np.random.seed(42)
data = np.cumsum(np.random.normal(size=(100, 200)), axis=1) + np.random.normal(size=(100, 200)) * 2

# Introduce 10% missing values (handled automatically)
data[np.random.uniform(size=data.shape) < 0.1] = np.nan

print(f"Data shape: {data.shape}")
# Output: Data shape: (100, 200)
```

--------------------------------

### Perform Kalman Prediction for Future Steps

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Illustrates the use of the `predict()` method for forecasting future states and observations using a Kalman filter. The example demonstrates predicting future values for a single time series and accessing the shape of the predicted observations.

```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0
)

# Single time series prediction
np.random.seed(0)
single_series = np.random.normal(size=200)

# Predict 15 future steps
predicted = kf.predict(single_series, n_test=15)

# Access predicted observations (1D case returns 1D arrays)
print(f"Predicted observations shape: {predicted.observations.mean.shape}")
# Output: Predicted observations shape: (15,)
```

--------------------------------

### Kalman Filter Smoothing Example

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Example of using the `smooth` method to process multiple time series data with missing values (NaNs).

```APIDOC
## Smoothing Multiple Time Series

### Description
This example demonstrates how to use the `smooth` method of the `KalmanFilter` class to process multiple independent time series, including handling missing observations represented by NaNs.

### Method
```python
KalmanFilter.smooth(data, initial_value, initial_covariance)
```

### Parameters
#### Path Parameters
- **data** (numpy.ndarray) - Input data array, where rows represent time series and columns represent time steps. NaNs indicate missing observations.
- **initial_value** (list or numpy.ndarray) - Initial state vector for the Kalman filter.
- **initial_covariance** (numpy.ndarray) - Initial state covariance matrix.

### Request Example
```python
import simdkalman
import numpy as np

# Assume kf is an initialized KalmanFilter object
# kf = simdkalman.KalmanFilter(...)

# Generate fake data with NaNs
data = np.random.normal(size=(100, 200))
data[np.random.uniform(size=data.shape) < 0.1] = np.nan

# Smooth the data
smoothed_results = kf.smooth(data,
                     initial_value = [1,0],
                     initial_covariance = np.eye(2) * 0.5)

# Accessing smoothed states
print('mean')
print(smoothed_results.states.mean[1,2,:])

print('covariance')
print(smoothed_results.states.cov[1,2,:,:])
```

### Response
#### Success Response (200)
- **states.mean** (numpy.ndarray) - The mean of the estimated state at each time step for each series.
- **states.cov** (numpy.ndarray) - The covariance of the estimated state at each time step for each series.

#### Response Example
```json
{
  "states": {
    "mean": [
      [0.29311384, -0.06948961],
      ...
    ],
    "cov": [
      [[0.19959416, -0.00777587],
       [-0.00777587, 0.02528967]],
      ...
    ]
  }
}
```
```

--------------------------------

### KalmanFilter.smooth() Method

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Applies the Kalman smoother to estimate hidden states using all available observations, providing more accurate state estimates by incorporating future information. This example demonstrates smoothing with custom initial conditions and accessing the results.

```APIDOC
## KalmanFilter.smooth()

### Description
Applies the Kalman smoother (forward-backward algorithm) to estimate hidden states using all available observations. Returns smoothed estimates with lower uncertainty than filtering alone by incorporating both past and future observations. Supports 1D, 2D, and 3D input arrays.

### Method
`kf.smooth(data, initial_value=None, initial_covariance=None)`

### Parameters
- **data** (numpy.ndarray) - The input time series data, potentially with missing values (NaN).
- **initial_value** (list or numpy.ndarray, optional) - The initial state estimate.
- **initial_covariance** (numpy.ndarray, optional) - The initial uncertainty (covariance matrix) of the state estimate.

### Request Example
```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = [[1, 1], [0, 1]],
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0
)

# Generate test data with missing values
np.random.seed(0)
data = np.random.normal(size=(100, 200))
data[np.random.uniform(size=data.shape) < 0.1] = np.nan

# Smooth all time series with custom initial conditions
smoothed = kf.smooth(
    data,
    initial_value=[1, 0],                    # Initial state estimate [position, velocity]
    initial_covariance=np.eye(2) * 0.5       # Initial uncertainty
)

# Access smoothed states: shape (n_series, n_timesteps, n_states)
print(f"Smoothed states shape: {smoothed.states.mean.shape}")

# Access specific result: series 1, timestep 2
print(f"State mean at series 1, step 2: {smoothed.states.mean[1, 2, :]}")
print(f"State covariance:\n{smoothed.states.cov[1, 2, :, :]}")

# Access smoothed observations: shape (n_series, n_timesteps)
print(f"Smoothed observations shape: {smoothed.observations.mean.shape}")
```

### Response Example
```
Smoothed states shape: (100, 200, 2)
State mean at series 1, step 2: [ 0.29311384 -0.06948961]
State covariance:
[[ 0.19959416 -0.00777587]
 [-0.00777587  0.02528967]]
Smoothed observations shape: (100, 200)
```
```

--------------------------------

### Kalman Filter Prediction Example

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Example of using the `predict` method to forecast future observations for a single time series.

```APIDOC
## Predicting Future Observations

### Description
This example demonstrates how to use the `predict` method of the `KalmanFilter` class to forecast future observations for a single time series, given historical data.

### Method
```python
KalmanFilter.predict(data, n_steps)
```

### Parameters
#### Path Parameters
- **data** (numpy.ndarray) - Historical observation data for a single time series.
- **n_steps** (int) - The number of future time steps to predict.

### Request Example
```python
import simdkalman
import numpy as np

# Assume kf is an initialized KalmanFilter object
# kf = simdkalman.KalmanFilter(...)

# Assume data[1,:] is a historical observation sequence for one series
# predicted_results = kf.predict(data[1,:], 123)

# predicted observation y, third new time step
# pred_mean = predicted_results.observations.mean[2]
# pred_stdev = np.sqrt(predicted_results.observations.cov[2])

# print('%g +- %g' % (pred_mean, pred_stdev))
```

### Response
#### Success Response (200)
- **observations.mean** (numpy.ndarray) - The mean of the predicted observations for each future time step.
- **observations.cov** (numpy.ndarray) - The covariance of the predicted observations for each future time step.

#### Response Example
```json
{
  "observations": {
    "mean": [
      1.71543,
      ...
    ],
    "cov": [
      1.65322,
      ...
    ]
  }
}
```
```

--------------------------------

### KalmanFilter.predict() Method

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Filters past data and predicts future values for a specified number of steps. This example shows how to perform predictions on a single time series.

```APIDOC
## KalmanFilter.predict()

### Description
Filters past data and predicts future values for a specified number of steps. Returns predicted states and observations with their associated uncertainties. Supports single time series (1D), multiple series (2D), and multi-dimensional observations (3D).

### Method
`kf.predict(data, n_test)`

### Parameters
- **data** (numpy.ndarray) - The input time series data.
- **n_test** (int) - The number of future steps to predict.

### Request Example
```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0
)

# Single time series prediction
np.random.seed(0)
single_series = np.random.normal(size=200)

# Predict 15 future steps
predicted = kf.predict(single_series, n_test=15)

# Access predicted observations (1D case returns 1D arrays)
print(f"Predicted observations shape: {predicted.observations.mean.shape}")
```

### Response Example
```
Predicted observations shape: (15,)
```
```

--------------------------------

### KalmanFilter Class Initialization

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Demonstrates how to initialize the KalmanFilter class with state transition, process noise, observation model, and observation noise parameters.

```APIDOC
## simdkalman.KalmanFilter Class

### Description
The `KalmanFilter` class provides convenient interfaces to vectorized smoothing and filtering operations on multiple independent time series.

### Method
```python
KalmanFilter(state_transition, process_noise, observation_model, observation_noise)
```

### Parameters
#### Parameters
- **state_transition** (matrix) - State transition matrix $A$
- **process_noise** (matrix) - Process noise (state transition covariance) matrix $Q$
- **observation_model** (matrix) - Observation model (measurement model) matrix $H$
- **observation_noise** (matrix) - Observation noise (measurement noise covariance) matrix $R$

### Request Example
```python
import simdkalman
import numpy as np

kalman_filter = simdkalman.KalmanFilter(
    state_transition = [[1,1],[0,1]],        # matrix A
    process_noise = np.diag([0.1, 0.01]),    # Q
    observation_model = np.array([[1,0]]),   # H
    observation_noise = 1.0)                 # R
```
```

--------------------------------

### KalmanFilter Class Initialization

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Demonstrates how to initialize the KalmanFilter class with state transition, process noise, observation model, and observation noise parameters. It also shows how to prepare sample data with missing values for batch processing.

```APIDOC
## KalmanFilter Class Initialization

### Description
Initializes the `KalmanFilter` class for vectorized Kalman filtering, smoothing, and prediction. This example sets up a filter for a system with position and velocity states and position observations, then generates sample data with missing values.

### Method
`simdkalman.KalmanFilter()`

### Parameters
- **state_transition** (numpy.ndarray or list) - The state transition matrix (A).
- **process_noise** (numpy.ndarray or float) - The process noise covariance matrix (Q) or its diagonal.
- **observation_model** (numpy.ndarray or list) - The observation model matrix (H).
- **observation_noise** (numpy.ndarray or float) - The observation noise covariance matrix (R) or its diagonal.

### Request Example
```python
import simdkalman
import numpy as np

# Define a Kalman filter with state transition, process noise, observation model, and observation noise
# State: [position, velocity], Observation: position only
kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),    # A: state transition matrix
    process_noise = np.diag([0.1, 0.01]),             # Q: process noise covariance
    observation_model = np.array([[1, 0]]),           # H: observation model matrix
    observation_noise = 1.0                            # R: observation noise variance
)

# Create sample data: 100 independent time series, each with 200 observations
np.random.seed(42)
data = np.cumsum(np.random.normal(size=(100, 200)), axis=1) + np.random.normal(size=(100, 200)) * 2

# Introduce 10% missing values (handled automatically)
data[np.random.uniform(size=data.shape) < 0.1] = np.nan

print(f"Data shape: {data.shape}")
```

### Response Example
```
Data shape: (100, 200)
```
```

--------------------------------

### Apply Kalman Smoothing with Custom Initial Conditions

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Shows how to use the `smooth()` method of the KalmanFilter class to apply the forward-backward algorithm for Kalman smoothing. It demonstrates handling missing data and specifying custom initial state estimates and covariances for multiple time series.

```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = [[1, 1], [0, 1]],
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0
)

# Generate test data with missing values
np.random.seed(0)
data = np.random.normal(size=(100, 200))
data[np.random.uniform(size=data.shape) < 0.1] = np.nan

# Smooth all time series with custom initial conditions
smoothed = kf.smooth(
    data,
    initial_value=[1, 0],                    # Initial state estimate [position, velocity]
    initial_covariance=np.eye(2) * 0.5       # Initial uncertainty
)

# Access smoothed states: shape (n_series, n_timesteps, n_states)
print(f"Smoothed states shape: {smoothed.states.mean.shape}")
# Output: Smoothed states shape: (100, 200, 2)

# Access specific result: series 1, timestep 2
print(f"State mean at series 1, step 2: {smoothed.states.mean[1, 2, :]}")
print(f"State covariance:\n{smoothed.states.cov[1, 2, :, :]}")
# Output: State mean at series 1, step 2: [ 0.29311384 -0.06948961]
# Output: State covariance:
# [[ 0.19959416 -0.00777587]
#  [-0.00777587  0.02528967]]

# Access smoothed observations: shape (n_series, n_timesteps)
print(f"Smoothed observations shape: {smoothed.observations.mean.shape}")
# Output: Smoothed observations shape: (100, 200)
```

--------------------------------

### Initialize Kalman Filter in Python

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Demonstrates how to initialize a KalmanFilter object in Python using simdkalman. This involves defining the state transition matrix, process noise covariance, observation model matrix, and observation noise covariance.

```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = [[1,1],[0,1]],        # matrix A
    process_noise = np.diag([0.1, 0.01]),    # Q
    observation_model = np.array([[1,0]]),   # H
    observation_noise = 1.0)                 # R
```

--------------------------------

### Initialize and Use Kalman Filter in Python

Source: https://github.com/oseiskar/simdkalman/blob/master/README.md

This snippet demonstrates how to initialize a KalmanFilter object with specified state transition, process noise, observation model, and observation noise. It then shows how to use the filter to smooth existing data and predict new data points.

```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1,1],[0,1]]),
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1,0]]),
    observation_noise = 1.0)

data = np.random.normal(size=(200, 1000))

# smooth and explain existing data
smoothed = kf.smooth(data)
# predict new data
pred = kf.predict(data, 15)
```

--------------------------------

### Distribute SIMD Kalman package using Twine

Source: https://github.com/oseiskar/simdkalman/blob/master/README.md

This section details the process of distributing the SIMD Kalman package to PyPI and TestPyPI using Twine. It includes steps for account creation, configuration, and uploading the package.

```bash
# test PyPI site
twine upload --repository testpypi dist/simdkalman-VERSION*
# the real thing
twine upload dist/simdkalman-VERSION*
# update git tags
git tag VERSION -m "released VERSION"
git push --tags
```

--------------------------------

### Primitives Module

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Documentation for the low-level Kalman filter computation steps with multi-dimensional input arrays.

```APIDOC
## Primitives

### Description
The `simdkalman.primitives` module contains low-level Kalman filter computation steps with multi-dimensional input arrays. See [this page](primitives.html) for full documentation.
```

--------------------------------

### Change Log

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Link to the change log for the simdkalman library.

```APIDOC
## Change log

### Description
See [https://github.com/oseiskar/simdkalman/releases](https://github.com/oseiskar/simdkalman/releases)
```

--------------------------------

### Define and Execute Multi-Dimensional Kalman Filter

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Demonstrates how to initialize a KalmanFilter with multi-dimensional observations, generate synthetic data, and perform smoothing and prediction tasks. This approach is suitable for scenarios where multiple sensors measure the same underlying signal.

```python
import numpy as np
import simdkalman

kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.2, 0.01])**2,
    observation_model = [[1, 0], [1, 0]],
    observation_noise = np.eye(2) * 3**2
)

np.random.seed(42)
n_series, n_steps = 100, 200
signal = np.cumsum(np.cumsum(np.random.normal(size=(n_series, n_steps)) * 0.02, axis=1) + np.random.normal(size=(n_series, n_steps)), axis=1)
data = np.dstack([signal + np.random.normal(size=(n_series, n_steps)) * 3, signal + np.random.normal(size=(n_series, n_steps)) * 3])

smoothed = kf.smooth(data)
pred = kf.predict(data, n_test=15)
```

--------------------------------

### Perform Kalman Filter Predictions

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Demonstrates how to extract mean and standard deviation for specific prediction steps and how to perform batch predictions across multiple time series.

```python
pred_mean = predicted.observations.mean[2]
pred_stdev = np.sqrt(predicted.observations.cov[2])
print(f"Prediction at step 3: {pred_mean:.4f} +/- {pred_stdev:.4f}")

data = np.random.normal(size=(100, 200))
batch_predicted = kf.predict(data, n_test=20)
print(f"Batch predicted states shape: {batch_predicted.states.mean.shape}")
```

--------------------------------

### Multi-Dimensional Observations

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Demonstrates how to handle multi-dimensional observations with SIMD Kalman, where each time step can have multiple measurement components.

```APIDOC
## Multi-Dimensional Observations

### Description
SIMD Kalman supports multi-dimensional observations where each time step has multiple measurement components. The data should be provided as a 3D array with shape (n_series, n_timesteps, n_obs_dims).

### Method
N/A (Concept explanation)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import simdkalman
import numpy as np

# Example data shape for multi-dimensional observations
# (n_series, n_timesteps, n_obs_dims)
multi_dim_data = np.random.normal(size=(10, 50, 3))

# Initialize Kalman Filter (example parameters)
kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0], [0, 1], [1, 1]]),
    observation_noise = np.diag([1.0, 1.0, 1.0])
)

# Compute results with multi-dimensional data
result = kf.compute(multi_dim_data)

print(f"Shape of multi-dimensional data: {multi_dim_data.shape}")
print(f"Shape of smoothed states: {result.smoothed.states.mean.shape}")
# Output: Shape of multi-dimensional data: (10, 50, 3)
# Output: Shape of smoothed states: (10, 50, 2)
```

### Response
#### Success Response (200)
- **result** (object) - An object containing computed results, where states and observations can be multi-dimensional.

#### Response Example
```json
{
  "smoothed": {
    "states": {
      "mean": "(10, 50, 2)",
      "cov": "(10, 50, 2, 2)"
    },
    "observations": {
      "mean": "(10, 50, 3)",
      "cov": "(10, 50, 3, 3)"
    }
  }
}
```
```

--------------------------------

### Generate and Smooth Fake Data with simdkalman

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Shows how to generate synthetic time series data with missing values (NaNs) and then apply the smoothing operation using a pre-initialized simdkalman KalmanFilter. It also demonstrates how to access the smoothed states' mean and covariance.

```python
import numpy.random as random

# 100 independent time series
data = random.normal(size=(100, 200))

# with 10% of NaNs denoting missing values
data[random.uniform(size=data.shape) < 0.1] = np.nan

smoothed = kf.smooth(
    data,
    initial_value = [1,0],
    initial_covariance = np.eye(2) * 0.5)

# second timeseries, third time step, hidden state x
print('mean')
print(smoothed.states.mean[1,2,:])

print('covariance')
print(smoothed.states.cov[1,2,:,:])
```

--------------------------------

### Learn Noise Parameters with EM Algorithm

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Uses the em() method to estimate optimal process and observation noise parameters from observed data. This is useful when the underlying noise characteristics of the system are unknown.

```python
kf_fitted = kf_initial.em(observations, n_iter=10, verbose=True)
print(f"Learned process noise:\n{kf_fitted.process_noise[0]}")
print(f"Learned observation noise: {kf_fitted.observation_noise[0, 0, 0]:.4f}")
```

--------------------------------

### KalmanFilter.em()

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Learns optimal noise parameters (process noise Q and observation noise R) from data using the Expectation-Maximization algorithm.

```APIDOC
## KalmanFilter.em()

### Description
Learns optimal noise parameters (process noise Q and observation noise R) from data using the Expectation-Maximization algorithm. Returns a new KalmanFilter instance with fitted parameters. Particularly useful when noise characteristics are unknown.

### Method
`em`

### Endpoint
N/A (Method within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import simdkalman
import numpy as np

# Start with initial guesses for noise parameters
kf_initial = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.1, 0.01]),       # Initial guess
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0                      # Initial guess
)

# Generate realistic data with known noise characteristics
np.random.seed(42)
true_process_noise = np.diag([0.2, 0.02])
true_obs_noise = 2.0

# Simulate random walk with trend
n_series, n_steps = 100, 200
states = np.zeros((n_series, n_steps, 2))
observations = np.zeros((n_series, n_steps))

for i in range(n_series):
    state = np.array([0.0, 0.1])
    for t in range(n_steps):
        state = np.array([[1, 1], [0, 1]]) @ state + np.random.multivariate_normal([0, 0], true_process_noise)
        states[i, t] = state
        observations[i, t] = state[0] + np.random.normal(0, np.sqrt(true_obs_noise))

# Fit noise parameters using EM algorithm
kf_fitted = kf_initial.em(observations, n_iter=10, verbose=True)
```

### Response
#### Success Response (200)
- **kf_fitted** (KalmanFilter) - A new KalmanFilter instance with learned process and observation noise parameters.

#### Response Example
```json
{
  "kf_fitted": {
    "process_noise": [
      [
        [0.0398, 0.0020],
        [0.0020, 0.0004]
      ]
    ],
    "observation_noise": [
      [
        [1.9876]
      ]
    ]
  }
}
```
```

--------------------------------

### simdkalman.primitives.smooth

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Performs the Kalman smoother backwards step.

```APIDOC
## smooth(posterior_mean, posterior_covariance, state_transition, process_noise, next_smooth_mean, next_smooth_covariance)

### Description
Calculates the smoothed mean and covariance for the current step given future smoothed estimates.

### Parameters
- **posterior_mean** (numpy.ndarray) - Required - Filtered mean of x_j.
- **posterior_covariance** (numpy.ndarray) - Required - Filtered covariance of x_j.
- **state_transition** (numpy.ndarray) - Required - Matrix A.
- **process_noise** (numpy.ndarray) - Required - Matrix Q.
- **next_smooth_mean** (numpy.ndarray) - Required - Smoothed mean of x_{j+1}.
- **next_smooth_covariance** (numpy.ndarray) - Required - Smoothed covariance of x_{j+1}.

### Response
- **smooth_mean** (numpy.ndarray) - Smoothed mean E[x_j|y_1...y_T].
- **smooth_covariance** (numpy.ndarray) - Smoothed covariance Cov[x_j|y_1...y_T].
- **smoothing_gain** (numpy.ndarray) - The calculated smoothing gain.
```

--------------------------------

### Predict New Data with simdkalman

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Illustrates how to use the predict method of a simdkalman KalmanFilter to forecast future observations for a single time series. It shows how to calculate the mean and standard deviation of the predicted observations.

```python
predicted = kf.predict(data[1,:], 123)

# predicted observation y, third new time step
pred_mean = predicted.observations.mean[2]
pred_stdev = np.sqrt(predicted.observations.cov[2])

print('%g +- %g' % (pred_mean, pred_stdev))
```

--------------------------------

### Execute Single Prediction Step

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

The predict_next method calculates the prior mean and covariance for the next time step given the current state distribution.

```python
prior_mean, prior_cov = kf.predict_next(m, P)
```

--------------------------------

### Kalman Smoother Backwards Step (Python)

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Executes the backward step of the Kalman smoother. It uses the filtered state estimates and the estimates from the next time step to compute a smoothed estimate for the current time step, improving accuracy by utilizing all available data.

```python
from simdkalman.primitives import smooth

# Assuming posterior_mean, posterior_covariance, state_transition, process_noise, next_smooth_mean, and next_smooth_covariance are defined numpy arrays
# smooth_mean, smooth_covariance, smoothing_gain = smooth(posterior_mean, posterior_covariance, state_transition, process_noise, next_smooth_mean, next_smooth_covariance)
```

--------------------------------

### Perform Backward Smoothing with simdkalman.primitives

Source: https://context7.com/oseiskar/simdkalman/llms.txt

This snippet demonstrates a backward smoothing pass following a forward Kalman filter. It uses the smooth() primitive to update state means and covariances by incorporating information from future observations.

```python
import numpy as np
from simdkalman.primitives import predict, update, smooth

# Model setup
A = np.array([[1, 1], [0, 1]])
Q = np.eye(2) * 0.01
H = np.array([[1, 0]])
R = np.array([[1.0]])

# Simulate a simple forward pass (filtering)
observations = [2.0, 3.5, 5.2, 6.8, 8.1]
filtered_means = []
filtered_covs = []

m = np.array([[0], [1]])
P = np.eye(2)

for y_val in observations:
    m, P = predict(m, P, A, Q)
    m, P = update(m, P, H, R, np.array([[y_val]]))
    filtered_means.append(m.copy())
    filtered_covs.append(P.copy())

# Backward smoothing pass
n = len(observations)
smoothed_means = [None] * n
smoothed_covs = [None] * n

# Initialize with last filtered state
smoothed_means[-1] = filtered_means[-1]
smoothed_covs[-1] = filtered_covs[-1]

# Smooth backwards
for j in range(n - 2, -1, -1):
    m_smooth, P_smooth = smooth(
        filtered_means[j],
        filtered_covs[j],
        A,
        Q,
        smoothed_means[j + 1],
        smoothed_covs[j + 1]
    )
    smoothed_means[j] = m_smooth
    smoothed_covs[j] = P_smooth
```

--------------------------------

### simdkalman.primitives.update

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Performs the Kalman filter update step using a measurement.

```APIDOC
## update(prior_mean, prior_covariance, observation_model, observation_noise, measurement)

### Description
Updates the prior mean and covariance based on a new observation.

### Parameters
- **prior_mean** (numpy.ndarray) - Required - The prior mean of x_j.
- **prior_covariance** (numpy.ndarray) - Required - The prior covariance of x_j.
- **observation_model** (numpy.ndarray) - Required - The observation model matrix H.
- **observation_noise** (numpy.ndarray) - Required - The observation noise matrix R.
- **measurement** (numpy.ndarray) - Required - The observation y_j.

### Response
- **posterior_mean** (numpy.ndarray) - Updated mean E[x_j|y_j].
- **posterior_covariance** (numpy.ndarray) - Updated covariance Cov[x_j|y_j].
```

--------------------------------

### Single Kalman Smoother Backwards Step

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Performs a single backwards step for the Kalman smoother.

```APIDOC
## smooth_current(m, P, ms, Ps)

### Description
Performs a single Kalman smoother backwards step.

### Parameters
- **m** - ${\mathbb E}[x_j|y_1,…,y_j]$, the filtered mean of $x_j$.
- **P** - ${\rm Cov}[x_j|y_1,…,y_j]$, the filtered covariance of $x_j$.
- **ms** - ${\mathbb E}[x_{j+1}|y_1,…,y_T]$, the smoothed mean of the next state.
- **Ps** - ${\rm Cov}[x_{j+1}|y_1,…,y_T]$, the smoothed covariance of the next state.

### Return type
`(smooth_mean, smooth_covariance, smoothing_gain)`
- **smooth_mean** - Smoothed mean ${\mathbb E}[x_j|y_1,…,y_T]$.
- **smooth_covariance** - Smoothed covariance ${\rm Cov}[x_j|y_1,…,y_T]$.
- **smoothing_gain** - Smoothing gain $C$.
```

--------------------------------

### Kalman Filter Update Step (Python)

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Performs the update step of the Kalman filter. It incorporates a new measurement to refine the prior mean and covariance, producing a posterior mean and covariance. This step is crucial for correcting state estimates based on new observations.

```python
from simdkalman.primitives import update

# Assuming prior_mean, prior_covariance, observation_model, observation_noise, and measurement are defined numpy arrays
# posterior_mean, posterior_covariance = update(prior_mean, prior_covariance, observation_model, observation_noise, measurement)
```

--------------------------------

### Predict Observation Distribution (Python)

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Computes the probability distribution of an observation given the state distribution. This function is useful for tasks like calculating the likelihood of an observation under a given model or for model checking.

```python
from simdkalman.primitives import predict_observation

# Assuming mean, covariance, observation_model, and observation_noise are defined numpy arrays
# observation_mean, observation_covariance = predict_observation(mean, covariance, observation_model, observation_noise)
```

--------------------------------

### Kalman Filter Prediction Step (Python)

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/primitives.md

Performs the prediction step of the Kalman filter. It takes the previous filtered mean and covariance, along with the state transition matrix and process noise, to compute the prior mean and covariance for the current step. This function is essential for time series forecasting and state estimation.

```python
from simdkalman.primitives import predict
import numpy

# different states
m1, m2, m3 = [numpy.array([[0],[i]]) for i in range(3)]
# with the same covariance (initially)
P = numpy.eye(2)

# different transition matrices
A1, A2, A3 = [numpy.eye(2)*i for i in range(3)]
# same process noise
Q = numpy.eye(2)*0.01

# stack correctly
m = numpy.vstack([
    m1[numpy.newaxis, ...],
    m2[numpy.newaxis, ...],
    m3[numpy.newaxis, ...]
])
A = numpy.vstack([
    A1[numpy.newaxis, ...],
    A2[numpy.newaxis, ...],
    A3[numpy.newaxis, ...]
])

# predict
m, P = predict(m, P, A, Q)

print(m.shape)
print(P.shape)
```

--------------------------------

### Single Kalman Update Step

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Performs a single update step in the Kalman filter, including NaN checks.

```APIDOC
## update(m, P, y, log_likelihood=False)

### Description
Performs a single update step with NaN check.

### Parameters
- **m** - ${\mathbb E}[x_j|y_1,…,y_{j-1}]$, the prior mean of $x_j$.
- **P** - ${\rm Cov}[x_j|y_1,…,y_{j-1}]$, the prior covariance of $x_j$.
- **y** - Observation $y_j$.
- **log_likelihood** (boolean) - Whether to compute log-likelihood. Defaults to False.

### Return type
`(posterior_mean, posterior_covariance, log_likelihood)`
- **posterior_mean** - Posterior mean ${\mathbb E}[x_j|y_1,…,y_j]$.
- **posterior_covariance** - Posterior covariance ${\rm Cov}[x_j|y_1,…,y_j]$.
- **log_likelihood** - Log-likelihood, if requested. If $y_j$ is NaN, returns the prior mean and covariance instead.
```

--------------------------------

### KalmanFilter.compute()

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Performs smoothing, filtering, and prediction in a single pass, providing access to various estimated states, covariances, likelihoods, and Kalman gains.

```APIDOC
## KalmanFilter.compute()

### Description
Comprehensive method that performs smoothing, filtering, and prediction in a single pass. Provides access to filtered results, smoothed results, predictions, log-likelihoods, and Kalman gains. Useful when multiple outputs are needed or for implementing custom algorithms.

### Method
`compute`

### Endpoint
N/A (Method within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import simdkalman
import numpy as np

kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1, 1], [0, 1]]),
    process_noise = np.diag([0.1, 0.01]),
    observation_model = np.array([[1, 0]]),
    observation_noise = 1.0
)

np.random.seed(42)
data = np.cumsum(np.random.normal(size=(50, 100)), axis=1)

# Compute everything at once
result = kf.compute(
    data,
    n_test=10,                    # Predict 10 future steps
    smoothed=True,                # Compute smoothed estimates
    filtered=True,                # Also return filtered estimates
    states=True,                  # Return state estimates
    observations=True,            # Return observation estimates
    covariances=True,             # Include covariance matrices
    likelihoods=True,             # Return per-step likelihoods
    log_likelihood=True,          # Return total log-likelihood
    gains=True                    # Return Kalman gains
)
```

### Response
#### Success Response (200)
- **result** (object) - An object containing various computed results such as smoothed states, filtered states, predicted states, log-likelihoods, and Kalman gains.

#### Response Example
```json
{
  "smoothed": {
    "states": {
      "mean": "(50, 100, 2)",
      "cov": "(50, 100, 2, 2)"
    }
  },
  "filtered": {
    "states": {
      "mean": "(50, 100, 2)",
      "cov": "(50, 100, 2, 2)"
    },
    "gains": "(50, 100, 2, 1)"
  },
  "predicted": {
    "states": {
      "mean": "(10, 2)",
      "cov": "(10, 2, 2)"
    }
  },
  "log_likelihood": "(50,)",
  "total_log_likelihood": -7543.21
}
```
```

--------------------------------

### Perform Low-Level Kalman Prediction

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Utilizes the simdkalman.primitives.predict function for manual control over the filtering process. It supports both single-state prediction and vectorized prediction for multiple states simultaneously.

```python
import numpy as np
from simdkalman.primitives import predict

state_transition = np.array([[1, 1], [0, 1]])
process_noise = np.eye(2) * 0.01
m = np.array([[0], [1]])
P = np.eye(2)

m_pred, P_pred = predict(m, P, state_transition, process_noise)

m_stacked = np.vstack([np.array([[0], [0]])[np.newaxis, ...], np.array([[0], [1]])[np.newaxis, ...], np.array([[0], [2]])[np.newaxis, ...]])
A_stacked = np.vstack([np.eye(2)[np.newaxis, ...], (np.eye(2) * 1.5)[np.newaxis, ...], (np.eye(2) * 2.0)[np.newaxis, ...]])
m_all, P_all = predict(m_stacked, np.eye(2), A_stacked, process_noise)
```

--------------------------------

### Calculate Observation Distribution

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

The predict_observation method computes the probability distribution of an observation y based on the current state distribution of x.

```python
y_mean, y_cov = kf.predict_observation(m, P)
```

--------------------------------

### Perform Low-Level Kalman Update

Source: https://context7.com/oseiskar/simdkalman/llms.txt

Uses the update and update_with_nan_check functions to apply observations to the filter state. The nan-check variant is specifically designed to handle missing data by returning the prior when an observation is NaN.

```python
import numpy as np
from simdkalman.primitives import predict, update, update_with_nan_check

state_transition = np.array([[1, 1], [0, 1]])
process_noise = np.eye(2) * 0.01
observation_model = np.array([[1, 0]])
observation_noise = np.array([[1.0]])

m = np.array([[0], [1]])
P = np.eye(2)

m, P = predict(m, P, state_transition, process_noise)
y = np.array([[4.0]])
m_post, P_post = update(m, P, observation_model, observation_noise, y)

y_missing = np.array([[np.nan]])
m_nan, P_nan = update_with_nan_check(m, P, observation_model, observation_noise, y_missing)
```

--------------------------------

### Perform Kalman Filtering and Prediction

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

The compute method performs smoothing, filtering, and prediction simultaneously. It accepts various boolean flags to toggle the return of specific Kalman components like gains, likelihoods, and smoothed states.

```python
result = kf.compute(data, n_test=10, smoothed=True, filtered=True, log_likelihood=True)
```

--------------------------------

### predict_next()

Source: https://github.com/oseiskar/simdkalman/blob/master/doc/index.md

Performs a single prediction step for mean and covariance.

```APIDOC
## predict_next(m, P)

### Description
Calculates a single prediction step given the previous mean and covariance.

### Parameters
- **m** (array) - Required - Previous mean E[x_{j-1}].
- **P** (matrix) - Required - Previous covariance Cov[x_{j-1}].

### Response
- **tuple** (prior_mean, prior_cov) - The predicted mean and covariance E[x_j], Cov[x_j].
```