distributedKNET

Distributed Kalman filtering and KalmanNet-style graph models for the thesis codebase.

This repository contains the implementation used to train, evaluate, and compare:

<<<<<<< HEAD

• a classical diffusion EKF baseline
• GraphKalmanProcess / Distributed KalmanNet
• a GNN-RNN baseline ======= Constant-velocity DKN/GNN-RNN workflow:
• python -m experiments.run_graphkalmanprocess --localization
• Skip the prompt: python -m experiments.run_graphkalmanprocess --localization --description "baseline run"

Single run:

• python -m experiments.run_graphkalmanprocess --preset baseline
• Override any value with dotted keys: python -m experiments.run_graphkalmanprocess --preset baseline --override model.hidden_dim=128 --override model.lr=1e-4

main

The code supports both nonlinear and linear system variants, with matched and mismatched process models.

Repository Layout

• utils/ - core model, data, and filtering utilities
• experiments/ - experiment runners, presets, and hyperparameter sweeps
• tests/ - unit tests
• models/ - saved model checkpoints and model-related artifacts
• try_models/ - exploratory model variants
• figures/ - generated plots
• notebooks/ - exploratory notebooks and ad hoc analysis

Generated logs, cached outputs, and notebook artifacts are intentionally kept out of the main workflow.

Requirements

The project is built around:

• Python 3.12
• PyTorch
• PyTorch Lightning
• PyTorch Geometric
• NumPy
• Matplotlib
• tqdm

The repository was developed in a local virtual environment. If you are recreating it from scratch, install the dependencies that match your environment and accelerator support.

Installation

Clone the repository and create a virtual environment, then install the project dependencies.

Typical setup:

python -m venv .venv
.venv\Scripts\activate
pip install -U pip
pip install torch pytorch-lightning torch-geometric numpy matplotlib tqdm

Depending on your platform, PyTorch Geometric may require the installation sequence recommended by the official PyG documentation for your Torch and CUDA versions.

Experiments

The main experiment entry point is:

python -m experiments.run_graphkalmanprocess --preset baseline

The runner supports single runs, sweeps, and evaluation on a fresh graph dataset.

Common options:

• override a config value:

python -m experiments.run_graphkalmanprocess --preset baseline --override model.hidden_dim=128 --override model.lr=1e-4

• run a named sweep:

python -m experiments.run_graphkalmanprocess --preset baseline --sweep hidden_dim_x_lr

• run a cartesian grid:

python -m experiments.run_graphkalmanprocess --preset baseline --grid model.hidden_dim=32,64,128 --grid model.lr=1e-4,3e-5

• sweep measurement noise:

python -m experiments.run_graphkalmanprocess --preset baseline --r-scales 0.5,1,2

• sweep process noise and measurement noise:

python -m experiments.run_graphkalmanprocess --preset baseline --q-values 0.1,1 --r-scales 0.5,1,2

• compare matched and mismatched dynamics:

python -m experiments.run_graphkalmanprocess --preset baseline --r-scales 0.5,1,2 --with-without-mismatch --mismatch-angle-deg 20

• evaluate the best checkpoint after training:

python -m experiments.run_graphkalmanprocess --preset baseline --eval --eval-sims 1024

Results are written to experiments/results/*.csv, and Lightning logs are written to lightning_logs/.

Notebook Workflows

The notebooks under notebooks/ are exploratory and are not the primary entry point for the project. They are useful for reproducing plots, running ad hoc comparisons, and checking intermediate results.

Testing

Run the test suite with:

pytest

The existing tests focus on model behavior and helper components. Add regression tests when changing shared training or inference logic.

Outputs

Typical generated artifacts include:

• CSV summaries in experiments/results/
• Lightning logs in lightning_logs/
• plots in figures/
• checkpoints in models/

These files are generated by experiments and should generally not be edited by hand.