# lucid-official/lucid architecture

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

- Interactive diagram: https://gitdiagram.com/lucid-official/lucid
- Repository: https://github.com/lucid-official/lucid

## Overview

Lucid is an Apple-Silicon deep-learning framework: Python tensors and neural-network modules run through a custom C++ engine with distinct CPU and GPU backends. The documented training path builds a model, computes a loss, evaluates it, runs reverse-mode backward, and steps an optimizer. The graph also preserves the model zoo, compilation, and Core ML export. Relationships are based on README architecture/workflow statements and the supplied source index; unsampled implementation details are not inferred.

Main entry points: [`lucid/nn/module.py`](https://github.com/lucid-official/lucid/blob/main/lucid/nn/module.py) (NN Modules), [`lucid/_C/core/TensorImpl.h`](https://github.com/lucid-official/lucid/blob/main/lucid/_C/core/TensorImpl.h) (Tensor State), [`lucid/_C/ops`](https://github.com/lucid-official/lucid/tree/main/lucid/_C/ops) (C++ Operations), [`lucid/_tensor/tensor.py`](https://github.com/lucid-official/lucid/blob/main/lucid/_tensor/tensor.py) (Tensor Wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_python_api["Lucid API<br/>[__init__.py]"]
  node_tensor["Tensor Wrapper<br/>[tensor.py]"]
  node_nn_modules["NN Modules<br/>[module.py]"]
  node_nn_parameters["Parameters<br/>[parameter.py]"]
  node_dispatch["Op Dispatch<br/>[_dispatch.py]"]
  node_op_adapters["Op Adapters<br/>[_adapters.py]"]
  node_promotion["Type Promotion<br/>[_promotion.py]"]
end

subgraph group_engine["Tensor Engine"]
  node_tensor_impl["Tensor State<br/>[TensorImpl.h]"]
  node_storage[("Tensor Storage<br/>[Storage.h]")]
  node_autograd["Autograd Engine<br/>[Engine.cpp]"]
  node_ops["C++ Operations"]
end

subgraph group_compute["Compute Backends"]
  node_cpu["CPU Backend"]
  node_gpu["GPU Backend"]
end

subgraph group_training["Training Features"]
  node_optimizer["Optimizers<br/>[Optimizer.cpp]"]
  node_model_zoo["Model Zoo"]
end

subgraph group_deployment["Compile and Export"]
  node_compile["Graph Compilation"]
  node_coreml["Core ML Export<br/>[_build.py]"]
end

node_user(("Framework User"))

node_user -->|"uses"| node_python_api
node_python_api -->|"exposes"| node_tensor
node_tensor -->|"dispatches ops"| node_dispatch
node_dispatch -->|"uses promotion"| node_promotion
node_op_adapters -->|"calls engine"| node_tensor_impl
node_nn_modules -->|"owns state"| node_nn_parameters
node_nn_modules -->|"computes with"| node_tensor
node_tensor_impl -->|"holds storage"| node_storage
node_tensor_impl -->|"tracks gradients"| node_autograd
node_autograd -->|"backpropagates ops"| node_ops
node_ops -->|"runs on CPU"| node_cpu
node_ops -->|"runs on GPU"| node_gpu
node_user -->|"builds model"| node_nn_modules
node_nn_modules -->|"backward pass"| node_autograd
node_nn_modules -->|"steps parameters"| node_optimizer
node_user -->|"selects model"| node_model_zoo
node_nn_modules -.->|"may compile"| node_compile
node_user -->|"exports model"| node_coreml
node_compile -.->|"may target"| node_coreml

click node_python_api "https://github.com/lucid-official/lucid/blob/main/lucid/__init__.py"
click node_tensor "https://github.com/lucid-official/lucid/blob/main/lucid/_tensor/tensor.py"
click node_nn_modules "https://github.com/lucid-official/lucid/blob/main/lucid/nn/module.py"
click node_nn_parameters "https://github.com/lucid-official/lucid/blob/main/lucid/nn/parameter.py"
click node_dispatch "https://github.com/lucid-official/lucid/blob/main/lucid/_dispatch.py"
click node_op_adapters "https://github.com/lucid-official/lucid/blob/main/lucid/_ops/_adapters.py"
click node_promotion "https://github.com/lucid-official/lucid/blob/main/lucid/_promotion.py"
click node_tensor_impl "https://github.com/lucid-official/lucid/blob/main/lucid/_C/core/TensorImpl.h"
click node_storage "https://github.com/lucid-official/lucid/blob/main/lucid/_C/core/Storage.h"
click node_autograd "https://github.com/lucid-official/lucid/blob/main/lucid/_C/autograd/Engine.cpp"
click node_ops "https://github.com/lucid-official/lucid/tree/main/lucid/_C/ops"
click node_cpu "https://github.com/lucid-official/lucid/tree/main/lucid/_C/backend/cpu"
click node_gpu "https://github.com/lucid-official/lucid/tree/main/lucid/_C/backend/gpu"
click node_optimizer "https://github.com/lucid-official/lucid/blob/main/lucid/_C/optim/Optimizer.cpp"
click node_model_zoo "https://github.com/lucid-official/lucid/tree/main/lucid/models"
click node_compile "https://github.com/lucid-official/lucid/tree/main/lucid/compile"
click node_coreml "https://github.com/lucid-official/lucid/blob/main/lucid/coreml/_build.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_python_api,node_tensor,node_nn_modules,node_nn_parameters,node_dispatch,node_op_adapters,node_promotion,node_user toneBlue
class node_tensor_impl,node_storage,node_autograd,node_ops toneAmber
class node_cpu,node_gpu toneMint
class node_optimizer,node_model_zoo toneRose
class node_compile,node_coreml toneIndigo
```

## Components

### Python API

- [Lucid API](https://github.com/lucid-official/lucid/blob/main/lucid/__init__.py): `lucid/__init__.py`
- [Tensor Wrapper](https://github.com/lucid-official/lucid/blob/main/lucid/_tensor/tensor.py): `lucid/_tensor/tensor.py`
- [NN Modules](https://github.com/lucid-official/lucid/blob/main/lucid/nn/module.py): `lucid/nn/module.py`
- [Parameters](https://github.com/lucid-official/lucid/blob/main/lucid/nn/parameter.py): `lucid/nn/parameter.py`
- [Op Dispatch](https://github.com/lucid-official/lucid/blob/main/lucid/_dispatch.py): `lucid/_dispatch.py`
- [Op Adapters](https://github.com/lucid-official/lucid/blob/main/lucid/_ops/_adapters.py): `lucid/_ops/_adapters.py`
- [Type Promotion](https://github.com/lucid-official/lucid/blob/main/lucid/_promotion.py): `lucid/_promotion.py`

### Tensor Engine

- [Tensor State](https://github.com/lucid-official/lucid/blob/main/lucid/_C/core/TensorImpl.h): `lucid/_C/core/TensorImpl.h`
- [Tensor Storage](https://github.com/lucid-official/lucid/blob/main/lucid/_C/core/Storage.h): `lucid/_C/core/Storage.h`
- [Autograd Engine](https://github.com/lucid-official/lucid/blob/main/lucid/_C/autograd/Engine.cpp): `lucid/_C/autograd/Engine.cpp`
- [C++ Operations](https://github.com/lucid-official/lucid/tree/main/lucid/_C/ops): `lucid/_C/ops`

### Compute Backends

- [CPU Backend](https://github.com/lucid-official/lucid/tree/main/lucid/_C/backend/cpu): `lucid/_C/backend/cpu`
- [GPU Backend](https://github.com/lucid-official/lucid/tree/main/lucid/_C/backend/gpu): `lucid/_C/backend/gpu`

### Training Features

- [Optimizers](https://github.com/lucid-official/lucid/blob/main/lucid/_C/optim/Optimizer.cpp): `lucid/_C/optim/Optimizer.cpp`
- [Model Zoo](https://github.com/lucid-official/lucid/tree/main/lucid/models): `lucid/models`

### Compile and Export

- [Graph Compilation](https://github.com/lucid-official/lucid/tree/main/lucid/compile): `lucid/compile`
- [Core ML Export](https://github.com/lucid-official/lucid/blob/main/lucid/coreml/_build.py): `lucid/coreml/_build.py`

### Other components

- **Framework User**

## Connections

- Framework User → Lucid API: uses (evidence: `README.md`)
- Lucid API → Tensor Wrapper: exposes (evidence: `lucid/__init__.py`)
- Tensor Wrapper → Op Dispatch: dispatches ops (evidence: `lucid/_tensor/tensor.py`)
- Op Dispatch → Type Promotion: uses promotion (evidence: `lucid/_dispatch.py`)
- Op Adapters → Tensor State: calls engine (evidence: `lucid/_ops/_adapters.py`)
- NN Modules → Parameters: owns state (evidence: `lucid/nn/parameter.py`)
- NN Modules → Tensor Wrapper: computes with (evidence: `README.md`)
- Tensor State → Tensor Storage: holds storage (evidence: `lucid/_C/core/TensorImpl.h`)
- Tensor State → Autograd Engine: tracks gradients (evidence: `README.md`)
- Autograd Engine → C++ Operations: backpropagates ops (evidence: `lucid/_C/autograd/Engine.cpp`)
- C++ Operations → CPU Backend: runs on CPU (evidence: `README.md`)
- C++ Operations → GPU Backend: runs on GPU (evidence: `README.md`)
- Framework User → NN Modules: builds model (evidence: `README.md`)
- NN Modules → Autograd Engine: backward pass (evidence: `README.md`)
- NN Modules → Optimizers: steps parameters (evidence: `README.md`)
- Framework User → Model Zoo: selects model (evidence: `README.md`)
- NN Modules → Graph Compilation: may compile (evidence: `README.md`)
- Framework User → Core ML Export: exports model (evidence: `README.md`)
- Graph Compilation → Core ML Export: may target