# sfwa/ukf architecture

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

- Interactive diagram: https://gitdiagram.com/sfwa/ukf
- Repository: https://github.com/sfwa/ukf

## Overview

##### Project type and purpose
- This is an open‑source C++ library (“UKF”) that implements multiple variants of the Unscented Kalman Filter (standard UKF, square‑root UKF, optimized SR‑UKF) for state and parameter estimation.
- Primary goal: deliver a header‑only, template‑based library with zero or minimal dynamic memory use, suitable for embedded systems.

##### File structure
- Top‐level:
- CMakeLists.txt + .github/workflows/cmake.yml → build system and CI pipeline
- /UKF → core library headers (StateVector, MeasurementVector, Core, SquareRootCore, Integrators, Types, Config)
- benchmark/ → benchmarking executables against different UKF implementations
- examples/ → sample applications in C++ and Python wrappers (AHRS, SFWA‑UKF)
- test/ → unit test suite exercising core classes and algorithms
- patch/ → third‑party patch for Eigen
- Key architectural pattern: template‐metaprogrammed, policy‑based design. Core algorithms are generic on StateVector and MeasurementVector types and on Integrator policies.

##### README for additional insights
- Library depends on Eigen for linear algebra.
- Three extension points required by the user: StateVector specialization (fields), MeasurementVector specialization (fixed/dynamic), Core specialization (with choice of integrator).
- Build targets: library (header + inline code), unittest, benchmark, examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Extensions
    subgraph "User Extensions"
        UE1["Process Model Specialization"]:::user
        UE2["Measurement Model Specialization"]:::user
        UE3["State/Measurement Field Definitions"]:::user
    end

    %% Core Library
    subgraph "UKF Core Library"
        SV["StateVector"]:::core
        MV["MeasurementVector"]:::core
        CORE["Core & SquareRootCore"]:::core
        INT["Integrator (e.g., RK4)"]:::core
        TYPES["Types & Aliases"]:::core
        CFG["Config"]:::core
    end

    %% External Dependency
    Eigen["Eigen (External Dependency)"]:::external

    %% Build & CI Infrastructure
    subgraph "Infra: Build & CI"
        CMAKE["CMakeLists.txt"]:::infra
        CI["GitHub Actions (cmake.yml)"]:::infra
    end

    %% Consumers
    subgraph "Consumers"
        subgraph "Tests"
            TTS["Unit Test Suite"]:::test
        end
        subgraph "Benchmarks"
            BEN["Benchmark Harness"]:::bench
        end
        subgraph "Examples"
            EX1["Example Apps (C++ & Python)"]:::ex
        end
    end

    %% Connections
    UE1 -->|injects into| CORE
    UE2 -->|injects into| MV
    UE3 -->|injects into| SV
    CORE -->|uses| Eigen
    INT -->|uses| Eigen
    SV -->|uses| Eigen
    MV -->|uses| Eigen

    CMAKE -->|builds| SV
    CMAKE -->|builds| MV
    CMAKE -->|builds| CORE
    CMAKE -->|builds| INT
    CMAKE -->|builds| TYPES
    CMAKE -->|builds| CFG
    CMAKE -->|builds| TTS
    CMAKE -->|builds| BEN
    CMAKE -->|builds| EX1

    CI -->|runs| CMAKE

    %% Click Events
    click SV "https://github.com/sfwa/ukf/blob/master/include/UKF/StateVector.h"
    click MV "https://github.com/sfwa/ukf/blob/master/include/UKF/MeasurementVector.h"
    click CORE "https://github.com/sfwa/ukf/blob/master/include/UKF/Core.h"
    click INT "https://github.com/sfwa/ukf/blob/master/include/UKF/Integrator.h"
    click TYPES "https://github.com/sfwa/ukf/blob/master/include/UKF/Types.h"
    click CFG "https://github.com/sfwa/ukf/blob/master/include/UKF/Config.h"
    click Eigen "https://github.com/sfwa/ukf/blob/master/patch/eigen-3.2.8-no-malloc-in-llt.patch"
    click CMAKE "https://github.com/sfwa/ukf/blob/master/CMakeLists.txt"
    click CI "https://github.com/sfwa/ukf/blob/master/.github/workflows/cmake.yml"
    click TTS "https://github.com/sfwa/ukf/tree/master/test"
    click BEN "https://github.com/sfwa/ukf/tree/master/benchmark"
    click EX1 "https://github.com/sfwa/ukf/tree/master/examples"

    %% Styles
    classDef core fill:#B3CDE3,stroke:#333,stroke-width:1px
    classDef user fill:#C7E9C0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef infra fill:#FDB462,stroke:#333,stroke-width:1px
    classDef test fill:#80B1D3,stroke:#333,stroke-width:1px
    classDef bench fill:#FB8072,stroke:#333,stroke-width:1px
    classDef ex fill:#DECBE4,stroke:#333,stroke-width:1px
```
