# nucleonautomation/pyceler architecture

> Architecture diagram of the GitHub repository nucleonautomation/pyceler, 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/nucleonautomation/pyceler
- Repository: https://github.com/nucleonautomation/pyceler

## Overview

PyCeler analyzes Python source, identifies eligible numeric loops, generates readable Cython or native extensions, then validates and measures candidate implementations to select guarded runtime behavior with Python fallback. The graph preserves the documented optimization families and separates analysis, lowering, build, and selection. Source excerpts expose several internal dependencies; other subsystem links reflect README-level workflow and capabilities rather than inspection of unsampled implementations.

Main entry points: [`PyCeler/Native_Optimizer.py`](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Native_Optimizer.py) (Candidate optimization), [`PyCeler/Common_Analysis.py`](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Common_Analysis.py) (Shared loop analysis), [`PyCeler/Fast_Math.py`](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Fast_Math.py) (Numeric expression lowering), [`PyCeler/__init__.py`](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/__init__.py) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User API and analysis"]
  node_api["Public API<br/>[__init__.py]"]
  node_compile["Compile workflow<br/>[Compile.py]"]
  node_analyze["Source analysis<br/>[Source_Analyzer.py]"]
end

subgraph group_lowering["Analysis and lowering"]
  node_common["Shared loop analysis<br/>[Common_Analysis.py]"]
  node_math["Math contracts<br/>[Math_Registry.py]"]
  node_maps["Math maps<br/>[Math_Maps.py]"]
  node_numeric["Numeric regions<br/>[Numeric_Regions.py]"]
  node_array["Array regions<br/>[Array_Regions.py]"]
  node_fastmath["Numeric expression lowering<br/>[Fast_Math.py]"]
  node_emitter["Region code emitter"]
  node_arraykernel["Array kernel generation"]
  node_numerickernel["Numeric kernel generation"]
  node_helpers["Pure helper calls<br/>[Helper_Kernel.py]"]
  node_iterators["Iterator kernels<br/>[Iterator_Kernel.py]"]
  node_lists["Numeric list kernels"]
  node_filters["Indexed distance filters<br/>[Indexed_Filters.py]"]
  node_direct["Direct Cython bindings<br/>[Direct_Source.py]"]
end

subgraph group_build["Native build"]
  node_build["Cython native build<br/>[Native_Build.py]"]
end

subgraph group_selection["Validation and selection"]
  node_optimizer["Candidate optimization"]
  node_worker["Behavior and timing worker"]
  node_policy["Backend selection policy"]
  node_runtime["Runtime guards and fallback"]
end

node_user(("Python developer"))
node_cython["Cython toolchain"]

node_user -->|"calls"| node_api
node_api -->|"analyzes source"| node_analyze
node_api -->|"converts or compiles"| node_compile
node_compile -.->|"plans loops"| node_common
node_common -->|"checks calls"| node_math
node_array -->|"plans regions"| node_numeric
node_array -->|"uses analysis"| node_common
node_numeric -->|"uses analysis"| node_common
node_numeric -->|"plans expressions"| node_fastmath
node_maps -->|"inspects math calls"| node_math
node_maps -->|"plans fast math"| node_fastmath
node_arraykernel -->|"emits regions"| node_emitter
node_arraykernel -->|"lowers expressions"| node_fastmath
node_numerickernel -->|"emits regions"| node_emitter
node_numerickernel -->|"lowers expressions"| node_fastmath
node_compile -.->|"builds candidates"| node_build
node_build -->|"invokes compiler"| node_cython
node_optimizer -->|"builds variants"| node_build
node_optimizer -->|"measures candidates"| node_worker
node_optimizer -->|"selects candidates"| node_policy
node_optimizer -->|"uses runtime resources"| node_runtime
node_worker -->|"applies selection rules"| node_policy
node_runtime -->|"falls back to Python"| node_user

click node_api "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/__init__.py"
click node_compile "https://github.com/nucleonautomation/pyceler/blob/main/Compile.py"
click node_analyze "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Source_Analyzer.py"
click node_common "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Common_Analysis.py"
click node_math "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Math_Registry.py"
click node_maps "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Math_Maps.py"
click node_numeric "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Regions.py"
click node_array "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Array_Regions.py"
click node_fastmath "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Fast_Math.py"
click node_emitter "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Region_Emitter.py"
click node_arraykernel "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Array_Region_Kernel.py"
click node_numerickernel "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Region_Kernel.py"
click node_helpers "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Helper_Kernel.py"
click node_iterators "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Iterator_Kernel.py"
click node_lists "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/List_Grid_Kernel.py"
click node_filters "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Indexed_Filters.py"
click node_direct "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Direct_Source.py"
click node_build "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Native_Build.py"
click node_optimizer "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Native_Optimizer.py"
click node_worker "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Selection_Worker.py"
click node_policy "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Selection_Policy.py"
click node_runtime "https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Runtime_Resources.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_api,node_compile,node_analyze toneBlue
class node_common,node_math,node_maps,node_numeric,node_array,node_fastmath,node_emitter,node_arraykernel,node_numerickernel,node_helpers,node_iterators,node_lists,node_filters,node_direct toneAmber
class node_build toneMint
class node_optimizer,node_worker,node_policy,node_runtime toneRose
class node_user,node_cython toneIndigo
```

## Components

### User API and analysis

- [Public API](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/__init__.py): `PyCeler/__init__.py`
- [Compile workflow](https://github.com/nucleonautomation/pyceler/blob/main/Compile.py): `Compile.py`
- [Source analysis](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Source_Analyzer.py): `PyCeler/Source_Analyzer.py`

### Analysis and lowering

- [Shared loop analysis](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Common_Analysis.py): `PyCeler/Common_Analysis.py`
- [Math contracts](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Math_Registry.py): `PyCeler/Math_Registry.py`
- [Math maps](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Math_Maps.py): `PyCeler/Math_Maps.py`
- [Numeric regions](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Regions.py): `PyCeler/Numeric_Regions.py`
- [Array regions](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Array_Regions.py): `PyCeler/Array_Regions.py`
- [Numeric expression lowering](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Fast_Math.py): `PyCeler/Fast_Math.py`
- [Region code emitter](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Region_Emitter.py): `PyCeler/Numeric_Region_Emitter.py`
- [Array kernel generation](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Array_Region_Kernel.py): `PyCeler/Array_Region_Kernel.py`
- [Numeric kernel generation](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Numeric_Region_Kernel.py): `PyCeler/Numeric_Region_Kernel.py`
- [Pure helper calls](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Helper_Kernel.py): `PyCeler/Helper_Kernel.py`
- [Iterator kernels](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Iterator_Kernel.py): `PyCeler/Iterator_Kernel.py`
- [Numeric list kernels](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/List_Grid_Kernel.py): `PyCeler/List_Grid_Kernel.py`
- [Indexed distance filters](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Indexed_Filters.py): `PyCeler/Indexed_Filters.py`
- [Direct Cython bindings](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Direct_Source.py): `PyCeler/Direct_Source.py`

### Native build

- [Cython native build](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Native_Build.py): `PyCeler/Native_Build.py`

### Validation and selection

- [Candidate optimization](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Native_Optimizer.py): `PyCeler/Native_Optimizer.py`
- [Behavior and timing worker](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Selection_Worker.py): `PyCeler/Selection_Worker.py`
- [Backend selection policy](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Selection_Policy.py): `PyCeler/Selection_Policy.py`
- [Runtime guards and fallback](https://github.com/nucleonautomation/pyceler/blob/main/PyCeler/Runtime_Resources.py): `PyCeler/Runtime_Resources.py`

### Other components

- **Python developer**
- **Cython toolchain**

## Connections

- Python developer → Public API: calls (evidence: `README.md`)
- Public API → Source analysis: analyzes source (evidence: `README.md`)
- Public API → Compile workflow: converts or compiles (evidence: `README.md`)
- Compile workflow → Shared loop analysis: plans loops
- Shared loop analysis → Math contracts: checks calls (evidence: `PyCeler/Common_Analysis.py`)
- Array regions → Numeric regions: plans regions (evidence: `PyCeler/Array_Regions.py`)
- Array regions → Shared loop analysis: uses analysis (evidence: `PyCeler/Array_Regions.py`)
- Numeric regions → Shared loop analysis: uses analysis (evidence: `PyCeler/Numeric_Regions.py`)
- Numeric regions → Numeric expression lowering: plans expressions (evidence: `PyCeler/Numeric_Regions.py`)
- Math maps → Math contracts: inspects math calls (evidence: `PyCeler/Math_Maps.py`)
- Math maps → Numeric expression lowering: plans fast math (evidence: `PyCeler/Math_Maps.py`)
- Array kernel generation → Region code emitter: emits regions (evidence: `PyCeler/Array_Region_Kernel.py`)
- Array kernel generation → Numeric expression lowering: lowers expressions (evidence: `PyCeler/Array_Region_Kernel.py`)
- Numeric kernel generation → Region code emitter: emits regions (evidence: `PyCeler/Numeric_Region_Kernel.py`)
- Numeric kernel generation → Numeric expression lowering: lowers expressions (evidence: `PyCeler/Numeric_Region_Kernel.py`)
- Compile workflow → Cython native build: builds candidates
- Cython native build → Cython toolchain: invokes compiler (evidence: `README.md`)
- Candidate optimization → Cython native build: builds variants (evidence: `PyCeler/Native_Optimizer.py`)
- Candidate optimization → Behavior and timing worker: measures candidates (evidence: `PyCeler/Native_Optimizer.py`)
- Candidate optimization → Backend selection policy: selects candidates (evidence: `PyCeler/Native_Optimizer.py`)
- Candidate optimization → Runtime guards and fallback: uses runtime resources (evidence: `PyCeler/Native_Optimizer.py`)
- Behavior and timing worker → Backend selection policy: applies selection rules (evidence: `PyCeler/Selection_Worker.py`)
- Runtime guards and fallback → Python developer: falls back to Python (evidence: `README.md`)
