# haleqiu/airimu architecture

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

- Interactive diagram: https://gitdiagram.com/haleqiu/airimu
- Repository: https://github.com/haleqiu/airimu

## Overview

##### Project Type and Purpose
- AirIMU is a machine‐learning pipeline for inertial odometry with uncertainty propagation.
- It trains, infers, and evaluates a neural model that takes raw IMU (accelerometer + gyroscope) sequences as input and outputs state estimates (e.g., velocity) and their uncertainties.

##### High‐Level File/Module Structure
- configs/…
- datasets/… – dataset‐specific settings (paths, sampling rates, window sizes)
- exp/… – experiment configurations (which dataset + model hyperparameters)
- train/ – global training config (e.g., default seqlen)
- datasets/… – PyTorch‐style Dataset classes that load raw IMU + ground‐truth pose/velocity
- model/… – network definitions
- net.py – overall network class
- cnn.py – convolutional feature extractor
- code.py – uncertainty‐code layers
- loss_func.py & losses.py – training objectives
- train.py – entry point for training (loads config → dataset → model → optimizer → loop)
- inference.py – runs a forward pass on test sequences, writes net_output.pickle
- evaluation/evaluate_state.py – consumes net_output.pickle + ground truth to produce metrics
- utils/… – helpers for differentiation, integration, visualization

##### Main Components and Data Flow
[Configs] → [Dataset Loader] → [DataLoader (PyTorch)] → [Model (net.py)] →
[Loss Computation] → [Optimizer/Checkpointing] → [Inference] → [Evaluation]

##### Inputs and Outputs of the Model
a. Input “X”:
- B = batch size (e.g., 32)
- T = sequence length (configurable, e.g., 200 timesteps)
- 6 channels: [ax, ay, az, wx, wy, wz]
– ax, ay, az in m/s²;
– wx, wy, wz in rad/s
- Optionally, initial orientation/state if configured (e.g., gravity vector).
b. Output “Y”:
- D = state dimension (e.g., 3 velocities + code dims for covariance)
- Uncertainty codes or covariance matrices (embedded within a code vector of size C).
- At inference, outputs are dumped to net_output.pickle for later evaluation.

##### Key Architectural Patterns and Principles
- Modular separation of concerns:
- Configuration ←→ Data IO ←→ Model ←→ Loss ←→ Training Loop
- PyTorch + pypose for automatic differentiation on SE(3)/rotation manifolds
- Experiment reproducibility via structured config files under configs/exp and configs/datasets
- Logging integration with wandb (optional via --log)

##### Detailing the Input Format
- Model → Output as:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configurations
    subgraph "Configurations"
        CM["/ Config Manager /"]:::config
        DC["/ Dataset Configs /"]:::config
        EC["/ Experiment Configs /"]:::config
        GC["/ Global Training Config /"]:::config
    end

    %% External Data Sources
    subgraph "External Datasets"
        Euroc[(EuRoC)]:::data
        KITTI[(KITTI)]:::data
        TUM[(TUM VI)]:::data
        SubT[(SubT-MRS)]:::data
    end

    %% Data Ingestion
    DR["Dataset Reader"]:::code
    DL["DataLoader"]:::code

    %% Model Pipeline
    subgraph "Model Graph"
        CNN["cnn.py"]:::code
        CODE["code.py"]:::code
        NET["net.py"]:::code
        OTH["others.py"]:::code
    end

    %% Loss and Training
    LM["Loss Module"]:::code
    OP["Optimizer & Checkpoint"]:::code

    %% Inference & Evaluation
    IS["Inference Script"]:::code
    NO["net_output.pickle"]:::data
    ET["Evaluation Tool"]:::code

    %% Top-to-bottom layout
    CM -->|".conf key:value"| DR
    DC -->|"dataset settings"| DR
    EC -->|"experiment settings"| DR
    GC -->|"train.conf defaults"| DR

    Euroc --> DR
    KITTI --> DR
    TUM --> DR
    SubT --> DR

    DR -->|"PyTorch Tensor\n(B,T,6):[ax,ay,az,wx,wy,wz]"| DL
    DL -->|"batch & shuffle"| CNN
    CNN --> CODE
    CODE --> NET
    NET --> LM
    LM -->|"loss value"| OP

    %% Training flow (red)
    OP -.->|"checkpoint"| NET
    NET -.->|"updated weights"| OP

    %% Inference & eval flow (black)
    OP -->|"final model"| IS
    IS -->|"Tensor (B,T,D):velocity & code"| NO
    NO -->|"pickle"| ET
    ET -->|"metrics output"| ET

    %% Click events
    click CM "https://github.com/haleqiu/airimu/tree/main/configs/"
    click DC "https://github.com/haleqiu/airimu/tree/main/configs/datasets/"
    click EC "https://github.com/haleqiu/airimu/tree/main/configs/exp/"
    click GC "https://github.com/haleqiu/airimu/blob/main/configs/train/train.conf"
    click DR "https://github.com/haleqiu/airimu/blob/main/datasets/dataset.py"
    click DL "https://github.com/haleqiu/airimu/blob/main/datasets/dataset_utils.py"
    click CNN "https://github.com/haleqiu/airimu/blob/main/model/cnn.py"
    click CODE "https://github.com/haleqiu/airimu/blob/main/model/code.py"
    click NET "https://github.com/haleqiu/airimu/blob/main/model/net.py"
    click OTH "https://github.com/haleqiu/airimu/blob/main/model/others.py"
    click LM "https://github.com/haleqiu/airimu/blob/main/model/loss_func.py"
    click OP "https://github.com/haleqiu/airimu/blob/main/train.py"
    click IS "https://github.com/haleqiu/airimu/blob/main/inference.py"
    click ET "https://github.com/haleqiu/airimu/blob/main/evaluation/evaluate_state.py"

    %% Styles
    classDef config fill:#f96,stroke:#333,stroke-width:1px;
    classDef code fill:#6cf,stroke:#333,stroke-width:1px;
    classDef data fill:#9f9,stroke:#333,stroke-width:1px;
```
