netcl 0.1.1

PyOpenCL-based deep learning playground with autograd, kernels, and high-level APIs.

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

pip install .

Requirements: Python ≥ 3.10, NumPy, PyOpenCL, and an available OpenCL device.

Quick Start (MNIST mini-MLP)

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

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.