# waleed-sh/mlx-sparse architecture

> Architecture diagram of the GitHub repository waleed-sh/mlx-sparse, 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/waleed-sh/mlx-sparse
- Repository: https://github.com/waleed-sh/mlx-sparse

## Overview

mlx-sparse is a Python-facing MLX sparse-array library backed by native C++ primitives, with CPU kernels and Metal support for fixed-shape operations. Users construct or generate COO/CSR/CSC matrices, operate on or convert them, and may pass them to iterative solvers, factorizations, or spectral routines. The graph retains those documented capabilities and the native-kernel layer; some subsystem connections are documented only at package level because their implementation files were not sampled.

Main entry points: [`mlx_sparse/_native.py`](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_native.py) (Native dispatch), [`mlx_sparse/_construct.py`](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_construct.py) (Construction), [`mlx_sparse/linalg/_iterative.py`](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_iterative.py) (Iterative solvers), [`src/bindings.cpp`](https://github.com/waleed-sh/mlx-sparse/blob/main/src/bindings.cpp) (C++ bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Array API"]
  node_construct["Construction<br/>[_construct.py]"]
  node_coo["COO arrays<br/>[_coo.py]"]
  node_csr["CSR arrays<br/>[_csr.py]"]
  node_csc["CSC arrays<br/>[_csc.py]"]
  node_validation["Validation<br/>[_validation.py]"]
  node_ops["Sparse operations<br/>[_ops.py]"]
  node_typing["Array types<br/>[_typing.py]"]
end

subgraph group_kernels["Native Operations"]
  node_native["Native dispatch<br/>[_native.py]"]
  node_fallback["Python fallback<br/>[_fallback.py]"]
  node_bindings["C++ bindings<br/>[bindings.cpp]"]
  node_common["Kernel utilities<br/>[common.h]"]
  node_parallel["CPU parallelism<br/>[cpu_parallel.h]"]
end

subgraph group_linalg["Sparse Linear Algebra"]
  node_iterative["Iterative solvers<br/>[_iterative.py]"]
  node_preconditioners["Preconditioners<br/>[preconditioners.py]"]
  node_factorizations["Direct factors<br/>[_factorizations.py]"]
  node_spectral["Spectral routines<br/>[_eigen.py]"]
  node_triangular["Triangular solves"]
  node_linalg_common["Solver utilities<br/>[common.h]"]
  node_accelerate["Accelerate solves<br/>[solve.h]"]
end

subgraph group_extras["Generation and Runtime"]
  node_random["Random arrays<br/>[__init__.py]"]
  node_random_native["Native sampling<br/>[random.h]"]
  node_runtime["Device runtime<br/>[runtime.py]"]
  node_host["Host utilities<br/>[_host.py]"]
end

node_user(("Python user"))

node_user -->|"constructs"| node_construct
node_construct -->|"validates"| node_validation
node_construct -->|"creates"| node_coo
node_construct -->|"creates"| node_csr
node_construct -->|"creates"| node_csc
node_user -->|"uses"| node_coo
node_user -->|"uses"| node_csr
node_user -->|"uses"| node_csc
node_coo -->|"dispatches"| node_native
node_csr -->|"dispatches"| node_native
node_csc -->|"dispatches"| node_native
node_native -->|"falls back"| node_fallback
node_native -.->|"dispatches"| node_bindings
node_bindings -.->|"uses"| node_common
node_bindings -.->|"uses"| node_parallel
node_user -->|"operates on"| node_ops
node_user -->|"solves with"| node_iterative
node_iterative -->|"uses"| node_preconditioners
node_iterative -->|"dispatches"| node_native
node_user -->|"factorizes"| node_factorizations
node_user -->|"computes spectra"| node_spectral
node_user -->|"solves triangular systems"| node_triangular
node_user -->|"generates arrays"| node_random
node_random -->|"requests sampling"| node_native
node_native -.->|"dispatches"| node_random_native
node_user -->|"selects device"| node_runtime
node_preconditioners -->|"applies kernels"| node_native
node_preconditioners -.->|"may use"| node_accelerate
node_triangular -->|"uses utilities"| node_linalg_common
node_triangular -->|"uses"| node_parallel
node_validation -->|"reads metadata"| node_host
node_iterative -.->|"uses utilities"| node_linalg_common

click node_construct "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_construct.py"
click node_coo "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_coo.py"
click node_csr "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_csr.py"
click node_csc "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_csc.py"
click node_validation "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_validation.py"
click node_ops "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_ops.py"
click node_typing "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_typing.py"
click node_native "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_native.py"
click node_fallback "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_fallback.py"
click node_bindings "https://github.com/waleed-sh/mlx-sparse/blob/main/src/bindings.cpp"
click node_common "https://github.com/waleed-sh/mlx-sparse/blob/main/src/common/common.h"
click node_parallel "https://github.com/waleed-sh/mlx-sparse/blob/main/src/common/cpu_parallel.h"
click node_iterative "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_iterative.py"
click node_preconditioners "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/preconditioners.py"
click node_factorizations "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_factorizations.py"
click node_spectral "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_eigen.py"
click node_triangular "https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/triangular_solve/triangular_solve.cpp"
click node_linalg_common "https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/common/common.h"
click node_accelerate "https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/accelerate/solve/solve.h"
click node_random "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/random/__init__.py"
click node_random_native "https://github.com/waleed-sh/mlx-sparse/blob/main/src/random/random.h"
click node_runtime "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/runtime.py"
click node_host "https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_host.py"

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_construct,node_coo,node_csr,node_csc,node_validation,node_ops,node_typing,node_user toneBlue
class node_native,node_fallback,node_bindings,node_common,node_parallel toneAmber
class node_iterative,node_preconditioners,node_factorizations,node_spectral,node_triangular,node_linalg_common,node_accelerate toneMint
class node_random,node_random_native,node_runtime,node_host toneRose
```

## Components

### Array API

- [Construction](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_construct.py): `mlx_sparse/_construct.py`
- [COO arrays](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_coo.py): `mlx_sparse/_coo.py`
- [CSR arrays](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_csr.py): `mlx_sparse/_csr.py`
- [CSC arrays](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_csc.py): `mlx_sparse/_csc.py`
- [Validation](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_validation.py): `mlx_sparse/_validation.py`
- [Sparse operations](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_ops.py): `mlx_sparse/_ops.py`
- [Array types](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_typing.py): `mlx_sparse/_typing.py`

### Native Operations

- [Native dispatch](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_native.py): `mlx_sparse/_native.py`
- [Python fallback](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_fallback.py): `mlx_sparse/_fallback.py`
- [C++ bindings](https://github.com/waleed-sh/mlx-sparse/blob/main/src/bindings.cpp): `src/bindings.cpp`
- [Kernel utilities](https://github.com/waleed-sh/mlx-sparse/blob/main/src/common/common.h): `src/common/common.h`
- [CPU parallelism](https://github.com/waleed-sh/mlx-sparse/blob/main/src/common/cpu_parallel.h): `src/common/cpu_parallel.h`

### Sparse Linear Algebra

- [Iterative solvers](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_iterative.py): `mlx_sparse/linalg/_iterative.py`
- [Preconditioners](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/preconditioners.py): `mlx_sparse/linalg/preconditioners.py`
- [Direct factors](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_factorizations.py): `mlx_sparse/linalg/_factorizations.py`
- [Spectral routines](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/linalg/_eigen.py): `mlx_sparse/linalg/_eigen.py`
- [Triangular solves](https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/triangular_solve/triangular_solve.cpp): `src/linalg/triangular_solve/triangular_solve.cpp`
- [Solver utilities](https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/common/common.h): `src/linalg/common/common.h`
- [Accelerate solves](https://github.com/waleed-sh/mlx-sparse/blob/main/src/linalg/accelerate/solve/solve.h): `src/linalg/accelerate/solve/solve.h`

### Generation and Runtime

- [Random arrays](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/random/__init__.py): `mlx_sparse/random/__init__.py`
- [Native sampling](https://github.com/waleed-sh/mlx-sparse/blob/main/src/random/random.h): `src/random/random.h`
- [Device runtime](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/runtime.py): `mlx_sparse/runtime.py`
- [Host utilities](https://github.com/waleed-sh/mlx-sparse/blob/main/mlx_sparse/_host.py): `mlx_sparse/_host.py`

### Other components

- **Python user**

## Connections

- Python user → Construction: constructs
- Construction → Validation: validates (evidence: `mlx_sparse/_construct.py`)
- Construction → COO arrays: creates (evidence: `mlx_sparse/_construct.py`)
- Construction → CSR arrays: creates (evidence: `mlx_sparse/_construct.py`)
- Construction → CSC arrays: creates (evidence: `mlx_sparse/_construct.py`)
- Python user → COO arrays: uses
- Python user → CSR arrays: uses
- Python user → CSC arrays: uses
- COO arrays → Native dispatch: dispatches (evidence: `mlx_sparse/_coo.py`)
- CSR arrays → Native dispatch: dispatches (evidence: `mlx_sparse/_csr.py`)
- CSC arrays → Native dispatch: dispatches (evidence: `mlx_sparse/_csc.py`)
- Native dispatch → Python fallback: falls back (evidence: `mlx_sparse/_native.py`)
- Native dispatch → C++ bindings: dispatches
- C++ bindings → Kernel utilities: uses
- C++ bindings → CPU parallelism: uses
- Python user → Sparse operations: operates on
- Python user → Iterative solvers: solves with
- Iterative solvers → Preconditioners: uses (evidence: `mlx_sparse/linalg/_iterative.py`)
- Iterative solvers → Native dispatch: dispatches (evidence: `mlx_sparse/linalg/_iterative.py`)
- Python user → Direct factors: factorizes
- Python user → Spectral routines: computes spectra
- Python user → Triangular solves: solves triangular systems
- Python user → Random arrays: generates arrays
- Random arrays → Native dispatch: requests sampling (evidence: `mlx_sparse/random/__init__.py`)
- Native dispatch → Native sampling: dispatches
- Python user → Device runtime: selects device
- Preconditioners → Native dispatch: applies kernels (evidence: `mlx_sparse/linalg/preconditioners.py`)
- Preconditioners → Accelerate solves: may use
- Triangular solves → Solver utilities: uses utilities (evidence: `src/linalg/triangular_solve/triangular_solve.cpp`)
- Triangular solves → CPU parallelism: uses (evidence: `src/linalg/triangular_solve/triangular_solve.cpp`)
- Validation → Host utilities: reads metadata (evidence: `mlx_sparse/_validation.py`)
- Iterative solvers → Solver utilities: uses utilities
