# mayitzin/ahrs architecture

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

- Interactive diagram: https://gitdiagram.com/mayitzin/ahrs
- Repository: https://github.com/mayitzin/ahrs

## Overview

#### Purpose and Public Surface
AHRS is a pure-Python, NumPy-based library for prototyping, teaching, and validating attitude/heading estimation for moving sensor systems. It is a library rather than a service or application. Primary import surface: `ahrs/__init__.py`; estimator namespace: `ahrs/filters/__init__.py`.

#### Primary Estimation Pipeline
Callers provide time-series gyroscope, accelerometer, and optionally magnetometer vectors to an estimator class. The estimator computes orientation, typically as an `N x 4` quaternion sequence (`Q`), using either reference-vector alignment (Wahba-style) or gyroscope integration with corrective fusion. Key implementations: `ahrs/filters/madgwick.py`, `ahrs/filters/ekf.py`, `ahrs/filters/ukf.py`.

#### Estimator Families
`ahrs/filters/` is the central algorithm boundary and exposes interchangeable estimators with broadly consistent sensor-data inputs. It includes direct/reference-vector solvers (Davenport, QUEST, TRIAD, FLAE), complementary and gradient filters, and state estimators/Kalman variants. Representative paths: `ahrs/filters/quest.py`, `ahrs/filters/complementary.py`, `ahrs/filters/fkf.py`.

#### Orientation Representation and Linear Algebra
Shared mathematical representations isolate algorithms from rotation-conversion details. Quaternion and quaternion-array types derive from NumPy arrays; DCM operations and orientation conversions support input/output transformation, interpolation, integration, and rotation. Paths: `ahrs/common/quaternion.py`, `ahrs/common/dcm.py`, `ahrs/common/orientation.py`.

#### Coordinate Frames and Physical References
Frame transforms and physical constants establish the reference conventions consumed by estimators and geodetic utilities, including ECEF, ENU, geodetic, and attitude-frame conversions. Paths: `ahrs/common/frames.py`, `ahrs/common/constants.py`, `ahrs/utils/wgs84.py`.

#### Sensor Synthesis, Geodesy, and Magnetic Models
Utilities can generate synthetic MARG sensor streams from orientations and derive gravity/geomagnetic references. World Magnetic Model coefficient files are package data, not remote dependencies; models cover 2015, 2020, and 2025. Paths: `ahrs/utils/sensors.py`, `ahrs/utils/wmm.py`, `ahrs/utils/WMM2025/WMM.COF`.

#### Runtime, Packaging, and Delivery
Runtime requires Python 3.9+ and has NumPy as its material dependency. Package metadata/build configuration is in `pyproject.toml`; GitHub Actions executes the Python workflow at `.github/workflows/python-app.yml`. Documentation is a Sphinx project published through Read the Docs configuration: `docs/source/conf.py`, `.readthedocs.yml`.

Main entry points: [`ahrs/filters/__init__.py`](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/__init__.py) (Estimator namespace), [`ahrs/common/quaternion.py`](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/quaternion.py) (Quaternion types), [`ahrs/__init__.py`](https://github.com/mayitzin/ahrs/blob/master/ahrs/__init__.py) (AHRS package), [`ahrs/utils/sensors.py`](https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/sensors.py) (Sensor synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_package["AHRS package<br/>Python library<br/>[__init__.py]"]
  node_filter_namespace["Estimator namespace<br/>Python exports<br/>[__init__.py]"]
  node_sensor_inputs["Sensor time series<br/>input data"]
  node_orientation_output["Quaternion sequence<br/>output data"]
end

subgraph group_filters["Estimator Algorithms"]
  node_reference_solvers["Reference-vector solvers<br/>filter family<br/>[quest.py]"]
  node_complementary_filter["Complementary fusion<br/>filter<br/>[complementary.py]"]
  node_madgwick["Madgwick filter<br/>gradient fusion filter<br/>[madgwick.py]"]
  node_kalman_filters["Kalman estimators<br/>filter family<br/>[ekf.py]"]
  node_fast_kalman["Fast Kalman filter<br/>[fkf.py]"]
end

subgraph group_math["Math &amp; Frames"]
  node_quaternions["Quaternion types<br/>NumPy representation<br/>[quaternion.py]"]
  node_dcm["Direction cosine matrices<br/>rotation representation<br/>[dcm.py]"]
  node_orientation["Orientation conversions<br/>rotation utilities<br/>[orientation.py]"]
  node_frames["Coordinate frames<br/>frame transforms<br/>[frames.py]"]
  node_constants["Physical constants<br/>reference data<br/>[constants.py]"]
end

subgraph group_utils["Models &amp; Utilities"]
  node_sensors["Sensor synthesis<br/>[sensors.py]"]
  node_wgs84["WGS84 geodesy<br/>geodetic utility<br/>[wgs84.py]"]
  node_wmm["World Magnetic Model<br/>geomagnetic utility<br/>[wmm.py]"]
  node_wmm_coefficients["WMM 2025 coefficients<br/>package data<br/>[WMM.COF]"]
end

subgraph group_delivery["Build &amp; Delivery"]
  node_package_build["Package build<br/>Python packaging<br/>[pyproject.toml]"]
  node_ci["Python CI<br/>GitHub Actions workflow<br/>[python-app.yml]"]
  node_docs["Sphinx documentation<br/>documentation project<br/>[conf.py]"]
  node_readthedocs["Read the Docs config<br/>documentation delivery<br/>[.readthedocs.yml]"]
end

node_package -->|"exports"| node_filter_namespace
node_sensor_inputs -->|"provided to estimators"| node_filter_namespace
node_filter_namespace -->|"exposes"| node_reference_solvers
node_filter_namespace -->|"exposes"| node_complementary_filter
node_filter_namespace -->|"exposes"| node_madgwick
node_filter_namespace -->|"exposes"| node_kalman_filters
node_filter_namespace -->|"exposes"| node_fast_kalman
node_reference_solvers -->|"computes"| node_orientation_output
node_complementary_filter -->|"computes"| node_orientation_output
node_madgwick -->|"computes"| node_orientation_output
node_kalman_filters -->|"computes"| node_orientation_output
node_fast_kalman -->|"computes"| node_orientation_output
node_filter_namespace -->|"uses"| node_quaternions
node_quaternions -->|"converts with"| node_dcm
node_quaternions -->|"supports"| node_orientation
node_filter_namespace -->|"uses reference conventions"| node_frames
node_filter_namespace -->|"uses"| node_constants
node_sensors -->|"generates"| node_sensor_inputs
node_sensors -->|"uses orientations"| node_quaternions
node_wgs84 -->|"supports"| node_frames
node_wmm_coefficients -->|"loaded by"| node_wmm
node_wmm -->|"provides magnetic reference"| node_filter_namespace
node_package_build -->|"builds"| node_package
node_ci -->|"validates"| node_package_build
node_docs -.->|"documents"| node_package
node_readthedocs -->|"publishes"| node_docs

click node_package "https://github.com/mayitzin/ahrs/blob/master/ahrs/__init__.py"
click node_filter_namespace "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/__init__.py"
click node_reference_solvers "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/quest.py"
click node_complementary_filter "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/complementary.py"
click node_madgwick "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/madgwick.py"
click node_kalman_filters "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/ekf.py"
click node_fast_kalman "https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/fkf.py"
click node_quaternions "https://github.com/mayitzin/ahrs/blob/master/ahrs/common/quaternion.py"
click node_dcm "https://github.com/mayitzin/ahrs/blob/master/ahrs/common/dcm.py"
click node_orientation "https://github.com/mayitzin/ahrs/blob/master/ahrs/common/orientation.py"
click node_frames "https://github.com/mayitzin/ahrs/blob/master/ahrs/common/frames.py"
click node_constants "https://github.com/mayitzin/ahrs/blob/master/ahrs/common/constants.py"
click node_sensors "https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/sensors.py"
click node_wgs84 "https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/wgs84.py"
click node_wmm "https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/wmm.py"
click node_wmm_coefficients "https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/WMM2025/WMM.COF"
click node_package_build "https://github.com/mayitzin/ahrs/blob/master/pyproject.toml"
click node_ci "https://github.com/mayitzin/ahrs/blob/master/.github/workflows/python-app.yml"
click node_docs "https://github.com/mayitzin/ahrs/blob/master/docs/source/conf.py"
click node_readthedocs "https://github.com/mayitzin/ahrs/blob/master/.readthedocs.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_filter_namespace,node_sensor_inputs,node_orientation_output toneBlue
class node_reference_solvers,node_complementary_filter,node_madgwick,node_kalman_filters,node_fast_kalman toneAmber
class node_quaternions,node_dcm,node_orientation,node_frames,node_constants toneMint
class node_sensors,node_wgs84,node_wmm,node_wmm_coefficients toneRose
class node_package_build,node_ci,node_docs,node_readthedocs toneIndigo
```

## Components

### Public API

- [AHRS package](https://github.com/mayitzin/ahrs/blob/master/ahrs/__init__.py): Python library · Primary import surface. · `ahrs/__init__.py`
- [Estimator namespace](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/__init__.py): Python exports · Interchangeable estimator classes. · `ahrs/filters/__init__.py`
- **Sensor time series**: input data · Gyroscope, accelerometer, and optional magnetometer vectors.
- **Quaternion sequence**: output data · Typically an N x 4 orientation sequence (Q).

### Estimator Algorithms

- [Reference-vector solvers](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/quest.py): filter family · Davenport, QUEST, TRIAD, and FLAE alignment methods. · `ahrs/filters/quest.py`
- [Complementary fusion](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/complementary.py): filter · `ahrs/filters/complementary.py`
- [Madgwick filter](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/madgwick.py): gradient fusion filter · `ahrs/filters/madgwick.py`
- [Kalman estimators](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/ekf.py): filter family · EKF, UKF, and fast Kalman variants. · `ahrs/filters/ekf.py`
- [Fast Kalman filter](https://github.com/mayitzin/ahrs/blob/master/ahrs/filters/fkf.py): filter · `ahrs/filters/fkf.py`

### Math & Frames

- [Quaternion types](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/quaternion.py): NumPy representation · Quaternion and quaternion-array operations. · `ahrs/common/quaternion.py`
- [Direction cosine matrices](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/dcm.py): rotation representation · `ahrs/common/dcm.py`
- [Orientation conversions](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/orientation.py): rotation utilities · Conversion, interpolation, integration, and rotation operations. · `ahrs/common/orientation.py`
- [Coordinate frames](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/frames.py): frame transforms · ECEF, ENU, geodetic, and attitude-frame conversions. · `ahrs/common/frames.py`
- [Physical constants](https://github.com/mayitzin/ahrs/blob/master/ahrs/common/constants.py): reference data · `ahrs/common/constants.py`

### Models & Utilities

- [Sensor synthesis](https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/sensors.py): utility · Generates synthetic MARG streams from orientations. · `ahrs/utils/sensors.py`
- [WGS84 geodesy](https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/wgs84.py): geodetic utility · `ahrs/utils/wgs84.py`
- [World Magnetic Model](https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/wmm.py): geomagnetic utility · Derives geomagnetic references from packaged coefficients. · `ahrs/utils/wmm.py`
- [WMM 2025 coefficients](https://github.com/mayitzin/ahrs/blob/master/ahrs/utils/WMM2025/WMM.COF): package data · Bundled magnetic-model coefficients; 2015 and 2020 are also included. · `ahrs/utils/WMM2025/WMM.COF`

### Build & Delivery

- [Package build](https://github.com/mayitzin/ahrs/blob/master/pyproject.toml): Python packaging · Python 3.9+ runtime with NumPy dependency. · `pyproject.toml`
- [Python CI](https://github.com/mayitzin/ahrs/blob/master/.github/workflows/python-app.yml): GitHub Actions workflow · `.github/workflows/python-app.yml`
- [Sphinx documentation](https://github.com/mayitzin/ahrs/blob/master/docs/source/conf.py): documentation project · Published via Read the Docs. · `docs/source/conf.py`
- [Read the Docs config](https://github.com/mayitzin/ahrs/blob/master/.readthedocs.yml): documentation delivery · `.readthedocs.yml`

## Connections

- AHRS package → Estimator namespace: exports
- Sensor time series → Estimator namespace: provided to estimators
- Estimator namespace → Reference-vector solvers: exposes
- Estimator namespace → Complementary fusion: exposes
- Estimator namespace → Madgwick filter: exposes
- Estimator namespace → Kalman estimators: exposes
- Estimator namespace → Fast Kalman filter: exposes
- Reference-vector solvers → Quaternion sequence: computes
- Complementary fusion → Quaternion sequence: computes
- Madgwick filter → Quaternion sequence: computes
- Kalman estimators → Quaternion sequence: computes
- Fast Kalman filter → Quaternion sequence: computes
- Estimator namespace → Quaternion types: uses
- Quaternion types → Direction cosine matrices: converts with
- Quaternion types → Orientation conversions: supports
- Estimator namespace → Coordinate frames: uses reference conventions
- Estimator namespace → Physical constants: uses
- Sensor synthesis → Sensor time series: generates
- Sensor synthesis → Quaternion types: uses orientations
- WGS84 geodesy → Coordinate frames: supports
- WMM 2025 coefficients → World Magnetic Model: loaded by
- World Magnetic Model → Estimator namespace: provides magnetic reference
- Package build → AHRS package: builds
- Python CI → Package build: validates
- Sphinx documentation → AHRS package: documents
- Read the Docs config → Sphinx documentation: publishes