# th1275/sparse_numba architecture

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

- Interactive diagram: https://gitdiagram.com/th1275/sparse_numba
- Repository: https://github.com/th1275/sparse_numba

## Overview

Sparse_Numba exposes sparse linear-system solving from Numba-compiled code. The main workflow accepts CSC arrays and explicit backend/ordering choices, validates and dispatches factorization and solve operations, then returns status codes and solutions; callers can reuse handles to solve repeatedly, refactor values, and free them. Legacy backend interfaces also support COO/CSR conversion. The graph preserves the SuperLU, UMFPACK, and Eigen branches and the shared symbol/handle layers. Some native wrapper-to-library links are dashed because the sampled excerpts do not show their call sites.

Main entry points: [`sparse_numba/api.py`](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/api.py) (Solver API), [`sparse_numba/sparse_superlu/superlu_wrapper.c`](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_superlu/superlu_wrapper.c) (SuperLU wrapper), [`sparse_numba/sparse_umfpack/umfpack_wrapper.c`](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_umfpack/umfpack_wrapper.c) (UMFPACK wrapper), [`sparse_numba/sparse_numba_registry.h`](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_numba_registry.h) (Handle registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Solver API<br/>[api.py]"]
  node_errors["Status errors<br/>[errors.py]"]
end

subgraph group_formats["Sparse Formats"]
  node_conversion["Format conversion"]
end

subgraph group_superlu["SuperLU Backend"]
  node_slu_py["SuperLU interface"]
  node_slu_native["SuperLU wrapper<br/>[superlu_wrapper.c]"]
  node_superlu_lib["SuperLU library"]
end

subgraph group_umfpack["UMFPACK Backend"]
  node_umf_py["UMFPACK interface"]
  node_umf_native["UMFPACK wrapper<br/>[umfpack_wrapper.c]"]
  node_umf_lib["User SuiteSparse"]
end

subgraph group_eigen["Eigen Backend"]
  node_eigen_py["Eigen interface"]
  node_eigen_native["Eigen wrapper<br/>[eigen_wrapper.cpp]"]
  node_eigen_lib["Eigen library"]
end

subgraph group_internals["Runtime Internals"]
  node_symbols["Symbol registry<br/>[_symbols.py]"]
  node_handles["Handle registry"]
end

node_caller(("Numba caller"))

node_caller -->|"calls"| node_api
node_api -->|"dispatches"| node_slu_native
node_api -->|"dispatches"| node_umf_native
node_api -->|"dispatches"| node_eigen_py
node_api -->|"raises"| node_errors
node_slu_py -->|"delegates to"| node_api
node_umf_py -->|"delegates to"| node_api
node_slu_py -->|"converts via"| node_conversion
node_umf_py -->|"converts via"| node_conversion
node_slu_py -.->|"calls"| node_slu_native
node_umf_py -.->|"calls"| node_umf_native
node_eigen_py -.->|"calls"| node_eigen_native
node_slu_native -.->|"solves with"| node_superlu_lib
node_umf_native -.->|"loads and calls"| node_umf_lib
node_eigen_native -.->|"solves with"| node_eigen_lib
node_api -->|"registers symbols"| node_symbols
node_symbols -.->|"declares interface"| node_handles
node_slu_native -->|"stores handles"| node_handles
node_umf_native -->|"stores handles"| node_handles
node_eigen_native -->|"uses registry"| node_handles

click node_api "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/api.py"
click node_errors "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/errors.py"
click node_conversion "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/conversion/matrix_conversion_numba.py"
click node_slu_py "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_superlu/superlu_numba_interface.py"
click node_slu_native "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_superlu/superlu_wrapper.c"
click node_umf_py "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_umfpack/umfpack_numba_interface.py"
click node_umf_native "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_umfpack/umfpack_wrapper.c"
click node_eigen_py "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_eigen/eigen_numba_interface.py"
click node_eigen_native "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_eigen/eigen_wrapper.cpp"
click node_symbols "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/_symbols.py"
click node_handles "https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_numba_registry.h"

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_errors toneBlue
class node_conversion toneAmber
class node_slu_py,node_slu_native,node_superlu_lib toneMint
class node_umf_py,node_umf_native,node_umf_lib toneRose
class node_eigen_py,node_eigen_native,node_eigen_lib,node_caller toneIndigo
class node_symbols,node_handles toneTeal
```

## Components

### Public API

- [Solver API](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/api.py): `sparse_numba/api.py`
- [Status errors](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/errors.py): `sparse_numba/errors.py`

### Sparse Formats

- [Format conversion](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/conversion/matrix_conversion_numba.py): `sparse_numba/conversion/matrix_conversion_numba.py`

### SuperLU Backend

- [SuperLU interface](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_superlu/superlu_numba_interface.py): `sparse_numba/sparse_superlu/superlu_numba_interface.py`
- [SuperLU wrapper](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_superlu/superlu_wrapper.c): `sparse_numba/sparse_superlu/superlu_wrapper.c`
- **SuperLU library**

### UMFPACK Backend

- [UMFPACK interface](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_umfpack/umfpack_numba_interface.py): `sparse_numba/sparse_umfpack/umfpack_numba_interface.py`
- [UMFPACK wrapper](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_umfpack/umfpack_wrapper.c): `sparse_numba/sparse_umfpack/umfpack_wrapper.c`
- **User SuiteSparse**

### Eigen Backend

- [Eigen interface](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_eigen/eigen_numba_interface.py): `sparse_numba/sparse_eigen/eigen_numba_interface.py`
- [Eigen wrapper](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_eigen/eigen_wrapper.cpp): `sparse_numba/sparse_eigen/eigen_wrapper.cpp`
- **Eigen library**

### Runtime Internals

- [Symbol registry](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/_symbols.py): `sparse_numba/_symbols.py`
- [Handle registry](https://github.com/th1275/sparse_numba/blob/main/sparse_numba/sparse_numba_registry.h): `sparse_numba/sparse_numba_registry.h`

### Other components

- **Numba caller**

## Connections

- Numba caller → Solver API: calls (evidence: `README.md`)
- Solver API → SuperLU wrapper: dispatches (evidence: `sparse_numba/api.py`)
- Solver API → UMFPACK wrapper: dispatches (evidence: `sparse_numba/api.py`)
- Solver API → Eigen interface: dispatches (evidence: `sparse_numba/api.py`)
- Solver API → Status errors: raises (evidence: `sparse_numba/api.py`)
- SuperLU interface → Solver API: delegates to (evidence: `sparse_numba/sparse_superlu/superlu_numba_interface.py`)
- UMFPACK interface → Solver API: delegates to (evidence: `sparse_numba/sparse_umfpack/umfpack_numba_interface.py`)
- SuperLU interface → Format conversion: converts via (evidence: `sparse_numba/sparse_superlu/superlu_numba_interface.py`)
- UMFPACK interface → Format conversion: converts via (evidence: `sparse_numba/sparse_umfpack/umfpack_numba_interface.py`)
- SuperLU interface → SuperLU wrapper: calls
- UMFPACK interface → UMFPACK wrapper: calls
- Eigen interface → Eigen wrapper: calls
- SuperLU wrapper → SuperLU library: solves with
- UMFPACK wrapper → User SuiteSparse: loads and calls
- Eigen wrapper → Eigen library: solves with
- Solver API → Symbol registry: registers symbols (evidence: `sparse_numba/api.py`)
- Symbol registry → Handle registry: declares interface
- SuperLU wrapper → Handle registry: stores handles (evidence: `sparse_numba/sparse_superlu/superlu_wrapper.c`)
- UMFPACK wrapper → Handle registry: stores handles (evidence: `sparse_numba/sparse_umfpack/umfpack_wrapper.c`)
- Eigen wrapper → Handle registry: uses registry (evidence: `sparse_numba/sparse_eigen/eigen_wrapper.cpp`)