# justkroft/option-implied-moments architecture

> Architecture diagram of the GitHub repository justkroft/option-implied-moments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justkroft/option-implied-moments
- Repository: https://github.com/justkroft/option-implied-moments

## Overview

Option Implied Moments is a Python library that estimates risk-neutral variance, skewness, and kurtosis from option data. Its principal workflow accepts a Polars DataFrame, filters and groups out-of-the-money options, packs group data for a Cython extension, and returns a DataFrame of moments. The README describes Cython as the NumPy-to-C bridge and says groups are processed in parallel with OpenMP. The Cython sources were not excerpted, so those links rely on documented behavior; internal C numerical stages are supported by the excerpted C source.

Main entry points: [`src/option_implied_moments/option_implied_moments.py`](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py) (Moments API), [`src/option_implied_moments/ext/trapezoid_rnm.pyx`](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_rnm.pyx) (Group dispatcher), [`src/option_implied_moments/ext/trapezoid_core.c`](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c) (Black-Scholes pricing), [`src/option_implied_moments/ext/omp_utils.pyx`](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/omp_utils.pyx) (OpenMP controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python API"]
  node_api["Moments API"]
  node_prepare["Filter and group"]
  node_pack["CSR packing"]
end

subgraph group_bridge["Cython bridge"]
  node_dispatch["Group dispatcher<br/>[trapezoid_rnm.pyx]"]
  node_threads["OpenMP controls<br/>[omp_utils.pyx]"]
end

subgraph group_numerics["C numerics"]
  node_pricing["Black-Scholes pricing<br/>[trapezoid_core.c]"]
  node_integration["Trapezoid integration<br/>[trapezoid_core.c]"]
  node_moments["Moment calculation<br/>[trapezoid_core.c]"]
end

node_caller(("Library caller"))
node_input["Option data"]
node_result["Moments DataFrame"]

node_caller -->|"calls"| node_api
node_input -->|"provides"| node_api
node_api -->|"prepares"| node_prepare
node_prepare -->|"assembles"| node_pack
node_pack -->|"calls"| node_dispatch
node_dispatch -->|"prices options"| node_pricing
node_dispatch -->|"parallelizes groups"| node_threads
node_pricing -->|"feeds prices"| node_integration
node_integration -->|"computes moments"| node_moments
node_api -->|"returns"| node_result

click node_api "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py"
click node_prepare "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py"
click node_pack "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py"
click node_dispatch "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_rnm.pyx"
click node_threads "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/omp_utils.pyx"
click node_pricing "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c"
click node_integration "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c"
click node_moments "https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c"

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_api,node_prepare,node_pack toneBlue
class node_dispatch,node_threads toneAmber
class node_pricing,node_integration,node_moments toneMint
class node_caller,node_input,node_result toneIndigo
```

## Components

### Python API

- [Moments API](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py): `src/option_implied_moments/option_implied_moments.py`
- [Filter and group](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py): `src/option_implied_moments/option_implied_moments.py`
- [CSR packing](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/option_implied_moments.py): `src/option_implied_moments/option_implied_moments.py`

### Cython bridge

- [Group dispatcher](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_rnm.pyx): `src/option_implied_moments/ext/trapezoid_rnm.pyx`
- [OpenMP controls](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/omp_utils.pyx): `src/option_implied_moments/ext/omp_utils.pyx`

### C numerics

- [Black-Scholes pricing](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c): `src/option_implied_moments/ext/trapezoid_core.c`
- [Trapezoid integration](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c): `src/option_implied_moments/ext/trapezoid_core.c`
- [Moment calculation](https://github.com/justkroft/option-implied-moments/blob/main/src/option_implied_moments/ext/trapezoid_core.c): `src/option_implied_moments/ext/trapezoid_core.c`

### Other components

- **Library caller**
- **Option data**
- **Moments DataFrame**

## Connections

- Library caller → Moments API: calls (evidence: `README.md`)
- Option data → Moments API: provides (evidence: `src/option_implied_moments/option_implied_moments.py`)
- Moments API → Filter and group: prepares (evidence: `src/option_implied_moments/option_implied_moments.py`)
- Filter and group → CSR packing: assembles (evidence: `src/option_implied_moments/option_implied_moments.py`)
- CSR packing → Group dispatcher: calls (evidence: `src/option_implied_moments/option_implied_moments.py`)
- Group dispatcher → Black-Scholes pricing: prices options (evidence: `README.md`)
- Group dispatcher → OpenMP controls: parallelizes groups (evidence: `README.md`)
- Black-Scholes pricing → Trapezoid integration: feeds prices (evidence: `src/option_implied_moments/ext/trapezoid_core.c`)
- Trapezoid integration → Moment calculation: computes moments (evidence: `src/option_implied_moments/ext/trapezoid_core.c`)
- Moments API → Moments DataFrame: returns (evidence: `src/option_implied_moments/option_implied_moments.py`)
