Metadata-Version: 2.4
Name: netcl
Version: 0.1.1
Summary: PyOpenCL-based deep learning playground with autograd, kernels, and high-level APIs.
Author: netcl contributors
License: MIT
Project-URL: Repository, https://bbwebservice.online/lukas/netcl
Keywords: opencl,deep-learning,autograd,gpu
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pyopencl>=2022.3
Dynamic: license-file

# netcl – PyOpenCL Deep Learning Playground

`netcl` is an experimental PyOpenCL-based deep learning framework. It combines low-level kernels (Conv/Matmul/Elementwise) with a lightweight autograd engine and a high-level API (Modules, Trainer, Serializer), without pulling in other DL frameworks.

## Installation
```bash
pip install .
```
Requirements: Python ≥ 3.10, NumPy, PyOpenCL, and an available OpenCL device.

## Quick Start (MNIST mini-MLP)
```python
import numpy as np
from netcl.core.device import manager
from netcl.nn.layers import Sequential, Flatten, Linear, ReLU
from netcl import autograd as ag
from netcl.optim import Adam
from netcl.core.tensor import Tensor

dev = manager.default()
q = dev.queue

model = Sequential(
    Flatten(),
    Linear(q, in_features=28*28, out_features=128),
    ReLU(),
    Linear(q, in_features=128, out_features=10),
)
opt = Adam(model.parameters(), lr=5e-3)

def one_hot(y, n=10):
    oh = np.zeros((y.shape[0], n), dtype=np.float32)
    oh[np.arange(y.shape[0]), y] = 1
    return oh

xb = np.random.randn(32, 1, 28, 28).astype(np.float32)
yb = one_hot(np.random.randint(0, 10, size=(32,)))

tape = ag.Tape()
ag.set_current_tape(tape)
x = ag.tensor(Tensor.from_host(q, xb))
y = ag.tensor(Tensor.from_host(q, yb))
logits = model(x)
loss = ag.cross_entropy(logits, y)
tape.backward(loss)
opt.step(); opt.zero_grad()
ag.set_current_tape(None)
```

## Key Features
- **Autograd**: Tape-based, core ops (Matmul, Conv2d, Pooling, Elementwise) with backward.
- **Modules/High-Level API**: `Linear`, `Conv2d`, `BatchNorm2d`, `Sequential`, `@model` decorator, Trainer.
- **Optimizations**: Conv algo heuristics/autotuning, optional mixed precision, buffer pool.
- **Serialization**: Save `Sequential` models as JSON (architecture) + NPZ (weights) via `netcl.io.serialization`.

## Save & Load a Model
```python
from netcl.io.serialization import save_model, load_model
save_model(model, "checkpoints/mnist_mlp")
model2 = load_model("checkpoints/mnist_mlp")  # queue auto="default"
```

## Notes
- Tests are not installed. For local dev: `python -m pytest`.
- For performance: increase batch size, minimize augment, optionally mixed precision (`Trainer(..., mixed_precision=True)`).
- Conv algorithms pick optimized paths automatically; env flags like `NETCL_CONV_AUTOTUNE=1` enable tuning.
