# kalmannet/kalmannet_tsp architecture

> Architecture diagram of the GitHub repository kalmannet/kalmannet_tsp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kalmannet/kalmannet_tsp
- Repository: https://github.com/kalmannet/kalmannet_tsp

## Overview

##### Project Type and Purpose
- KalmanNet is a research‐oriented Python toolkit that implements and compares classical Kalman filters (e.g., Linear KF, EKF) against a neural‐network–based filter (KalmanNet).
- It provides simulation modules for linear and non‐linear dynamical systems (e.g., constant‐acceleration, canonical linear, Lorenz attractor), data‐generation, training pipelines, and plotting utilities.

##### High‐Level File Structure Analysis
- Top-level “main_*.py” scripts: orchestrate end-to-end runs for each scenario (linear canonical, CA, Lorenz variants).
- Filters/: implementations of Linear KF, Extended KF, and their test suites.
- KNet/: the PyTorch neural‐network definition (KalmanNet_nn.py).
- Pipelines/: training/evaluation control flow (Pipeline_EKF.py).
- Simulations/: system models, parameter definitions, synthetic data storage, and helper utilities (config.py, utils.py).
- Plot.py: result visualization.
- requirements.txt: external dependencies (NumPy, PyTorch, etc.).

##### README Insights
- Shows which “main_*.py” to run for each experiment.
- Explains where to tweak system parameters (Simulations/*/parameters.py) and training settings (Simulations/config.py).
- Indicates batched processing support.

##### Components & Their Relationships
a. Main Orchestration Layer
- main_*.py scripts
- Responsibilities: read flags/paths, load config, invoke simulation, pipeline, and plotting modules.
b. Data Generation Layer
- Simulations/…
- Responsibilities: define f/F, h/H, Q, R; generate and save .pt datasets.
c. Filtering Layer
- Filters/: classical filters (Linear_KF.py, EKF.py)
- KNet/: KalmanNet_nn.py (NN model)
d. Pipeline Layer
- Pipelines/Pipeline_EKF.py
- Responsibilities: load data, instantiate filter (classical or NN), run training loops, compute metrics.
e. Visualization Layer
- Plot.py
- Responsibilities: read results, produce figures.

Relationships and Data Flow:
1. main_*.py → load Simulations/config.py → choose scenario
2. Simulations/… → generate or load existing dataset (.pt)
3. main_*.py → call Pipelines/Pipeline_EKF.py, passing dataset & config
4. Pipeline_EKF → instantiate filter from Filters/ and model from KNet/ → train/evaluate
5. Pipeline_EKF → save outputs (e.g., loss curves, state estimates)
6. main_*.py → call Plot.py on saved outputs → final figures

##### Architectural Patterns & Design Principles
- Modular layering: clear separation of data generation, filtering algorithms, training logic, and plotting.
- Pipeline pattern: data flows sequentially from simulation → training → evaluation → visualization.
- Extensibility: new system models in Simulations/, new filters in Filters/ or KNet/.

##### Technologies & Frameworks
- Python 3.x
- PyTorch (neural network modeling and batched tensor operations)
- NumPy (numerical ops)
- Torch .pt files for dataset serialization

##### Summary of Elements
- main_*.py (Orchestrator)
- Simulations (model & data gen)
- Filters (Linear_KF, EKF)
- KNet (NN model)
- Pipelines (training/eval)
- Plot.py (visualization)
- main → Simulations (init)
- main → Pipeline (invoke)
- Pipeline → Filters/KNet (compute)
- Pipeline → Data store (read/write)
- main → Plot (invoke)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Modules
    subgraph "Control Modules"
        direction TB
        ML1["main_linear_CA.py"]:::control
        ML2["main_linear_canonical.py"]:::control
        ML3["main_lor_DT.py"]:::control
        ML4["main_lor_DT_NLobs.py"]:::control
        ML5["main_lor_decimation.py"]:::control
    end

    %% Data Modules
    subgraph "Simulation Layer"
        direction TB
        SimConfig["config.py"]:::data
        SimUtils["utils.py"]:::data
        ExtSys["Extended_sysmdl.py"]:::data
        LinSys["Linear_sysmdl.py"]:::data
        LCAParams["parameters.py (Linear_CA)"]:::data
        LCAData[(decimated_dt1e-2_T100_r0_randnInit.pt)]:::datastore
        LCanParams["parameters.py (Linear_canonical)"]:::data
        LCanData[(2x2_rq020_T100.pt)]:::datastore
        LorParams["parameters.py (Lorenz_Atractor)"]:::data
        LorData[(data_gen.pt)]:::datastore
    end

    %% Pipeline Layer
    subgraph "Pipeline Layer"
        direction TB
        Pipeline["Pipeline_EKF.py"]:::control
    end

    %% Compute Modules - Classical Filters
    subgraph "Filtering Layer (Classical Filters)"
        direction TB
        LinKF["Linear_KF.py"]:::compute
        EKF["EKF.py"]:::compute
        KFTest["KalmanFilter_test.py"]:::compute
        EKFTest["EKF_test.py"]:::compute
    end

    %% Compute Modules - Neural Network
    subgraph "Neural-Network Filter"
        direction TB
        KNet["KalmanNet_nn.py"]:::compute
    end

    %% Visualization
    subgraph "Visualization Layer"
        direction TB
        Plot["Plot.py"]:::visual
    end

    %% Data Flow
    %% Orchestrator to Simulation
    ML1 -->|"init"| SimConfig
    ML2 -->|"init"| SimConfig
    ML3 -->|"init"| SimConfig
    ML4 -->|"init"| SimConfig
    ML5 -->|"init"| SimConfig

    %% Simulation generates data
    SimConfig -->|"calls utils & models"| SimUtils
    SimUtils -->|"uses sysmdl definitions"| ExtSys
    SimUtils -->|"uses sysmdl definitions"| LinSys
    SimConfig -->|"load params"| LCAParams
    SimConfig -->|"load params"| LCanParams
    SimConfig -->|"load params"| LorParams
    LCAParams -->|"generate"| LCAData
    LCanParams -->|"generate"| LCanData
    LorParams -->|"generate"| LorData

    %% Orchestrator invokes Pipeline
    ML1 -->|"invoke"| Pipeline
    ML2 -->|"invoke"| Pipeline
    ML3 -->|"invoke"| Pipeline
    ML4 -->|"invoke"| Pipeline
    ML5 -->|"invoke"| Pipeline

    %% Pipeline reads/writes datasets
    Pipeline -->|".pt read/write"| LCAData
    Pipeline -->|".pt read/write"| LCanData
    Pipeline -->|".pt read/write"| LorData

    %% Pipeline uses filters and KNet
    Pipeline -->|"compute"| LinKF
    Pipeline -->|"compute"| EKF
    Pipeline -->|"compute"| KNet

    %% Pipeline outputs to Plot
    ML1 -->|"invoke"| Plot
    ML2 -->|"invoke"| Plot
    ML3 -->|"invoke"| Plot
    ML4 -->|"invoke"| Plot
    ML5 -->|"invoke"| Plot

    %% Click events
    click ML1 "https://github.com/kalmannet/kalmannet_tsp/blob/main/main_linear_CA.py"
    click ML2 "https://github.com/kalmannet/kalmannet_tsp/blob/main/main_linear_canonical.py"
    click ML3 "https://github.com/kalmannet/kalmannet_tsp/blob/main/main_lor_DT.py"
    click ML4 "https://github.com/kalmannet/kalmannet_tsp/blob/main/main_lor_DT_NLobs.py"
    click ML5 "https://github.com/kalmannet/kalmannet_tsp/blob/main/main_lor_decimation.py"
    click SimConfig "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/config.py"
    click SimUtils "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/utils.py"
    click ExtSys "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Extended_sysmdl.py"
    click LinSys "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Linear_sysmdl.py"
    click LCAParams "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Linear_CA/parameters.py"
    click LCAData "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Linear_CA/data/decimated_dt1e-2_T100_r0_randnInit.pt"
    click LCanParams "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Linear_canonical/parameters.py"
    click LCanData "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Linear_canonical/data/2x2_rq020_T100.pt"
    click LorParams "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Lorenz_Atractor/parameters.py"
    click LorData "https://github.com/kalmannet/kalmannet_tsp/blob/main/Simulations/Lorenz_Atractor/data/data_gen.pt"
    click LinKF "https://github.com/kalmannet/kalmannet_tsp/blob/main/Filters/Linear_KF.py"
    click EKF "https://github.com/kalmannet/kalmannet_tsp/blob/main/Filters/EKF.py"
    click KFTest "https://github.com/kalmannet/kalmannet_tsp/blob/main/Filters/KalmanFilter_test.py"
    click EKFTest "https://github.com/kalmannet/kalmannet_tsp/blob/main/Filters/EKF_test.py"
    click KNet "https://github.com/kalmannet/kalmannet_tsp/blob/main/KNet/KalmanNet_nn.py"
    click Pipeline "https://github.com/kalmannet/kalmannet_tsp/blob/main/Pipelines/Pipeline_EKF.py"
    click Plot "https://github.com/kalmannet/kalmannet_tsp/blob/main/Plot.py"

    %% Styles
    classDef compute fill:#AED6F1,stroke:#000;
    classDef data fill:#ABEBC6,stroke:#000;
    classDef control fill:#F8C471,stroke:#000;
    classDef visual fill:#D7BDE2,stroke:#000;
    classDef datastore fill:#F2D7D5,stroke:#000,shape:cylinder;
```
