Metadata-Version: 2.4
Name: dnnlpy
Version: 2026.6.11
Summary: A utility library for deep learning notes, providing common functions and tools to support the main content of the deep learning notes collection.
Keywords: deep learning notes,library,utilities
Author: Yunjie Lin
Author-email: Yunjie Lin <jshn9510@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: numpy>=2.4.0,<2.5.0
Requires-Dist: matplotlib>=3.11.0,<3.12.0
Requires-Dist: torch>=2.12.0,<2.13.0
Requires-Dist: pytest>=9.0.0,<9.1.0 ; extra == 'test'
Requires-Python: >=3.12, <3.15
Project-URL: Homepage, https://github.com/jshn9515/deep-learning-notes
Provides-Extra: test
Description-Content-Type: text/markdown

# dnnlpy

**dnnlpy** is the companion Python package for **Deep Learning Notes Library**.

It provides code examples, helper functions, and small utilities used throughout the tutorial, similar in spirit to the `d2l` package for _Dive into Deep Learning_.

The package structure is similar to PyTorch, but keeps a clear boundary between reusable neural network building blocks and complete model implementations:

- `dnnlpy.nn` contains general neural network modules, such as attention layers, positional encodings, and other reusable components.
- `dnnlpy.nn.functional` contains stateless helper functions, such as functional attention implementations.
- `dnnlpy.models` contains higher-level model architectures or model-specific components, such as ViT, DDPM, or other models introduced in the notes.

The APIs are designed to feel close to their PyTorch counterparts where practical, while still keeping the code lightweight and easy to read for tutorial purposes.

This package is intended as a lightweight code supplement rather than a general-purpose deep learning framework. Its goal is to make the examples in the notes easier to run, reuse, and extend.

## What is this package for?

The `dnnlpy` package is designed to support the code in the **Deep Learning Notes Library** tutorial.

It can be used to:

- Organize example code from the notes
- Provide reusable utility functions
- Reduce repeated boilerplate in notebooks and scripts
- Make tutorial examples easier to reproduce

In short, this package serves as the code companion to the tutorial.

## Requirements

- Python 3.14 or newer
- PyTorch 3.10 or newer

## Installation

This project uses [uv](https://docs.astral.sh/uv/) for package management.

```bash
git clone https://github.com/jshn9515/deep-learning-notes.git
cd dnnlpy
uv pip install .
```

If you want to modify the package while working through the notes, editable installation is recommended:

```bash
uv pip install -e .
```

This way, changes to the source code take effect immediately without reinstalling the package each time.

## Examples

After installation, you can import reusable neural network modules from `dnnlpy.nn`:

```python
import torch
import dnnlpy.nn as dnn

attn = dnn.MultiheadAttention(embed_dim=16, num_heads=4)

query = torch.randn(2, 8, 16)
key = torch.randn(2, 8, 16)
value = torch.randn(2, 8, 16)

output = attn(query, key, value)
```

You can also import stateless functions from `dnnlpy.nn.functional`:

```python
import torch
import dnnlpy.nn.functional as dF

query = torch.randn(2, 4, 8, 16)
key = torch.randn(2, 4, 8, 16)
value = torch.randn(2, 4, 8, 16)

output, weights = dF.scaled_dot_product_attention(
    query,
    key,
    value,
    need_weights=True,
)
```

Higher-level model architectures live under `dnnlpy.models`:

```python
import torch
from dnnlpy.models.vit import ViTForImageClassification

model = ViTForImageClassification(
    image_size=224,
    patch_size=16,
    in_channels=3,
    num_classes=1000,
    embed_dim=768,
    num_heads=12,
    num_layers=12,
)

images = torch.randn(2, 3, 224, 224)
logits = model(images)
```

The `dnnlpy.models.mlp` package contains small NumPy modules for teaching manual
forward and backward passes:

```python
import dnnlpy.models.mlp as mlp
import numpy as np

model = mlp.MLP(input_dim=4, hidden_dim=8, num_classes=3)
loss_fn = mlp.CrossEntropyLoss()
optimizer = mlp.SGD(model.parameters(), lr=0.1)

x = np.random.randn(2, 4)
targets = np.array([0, 2])

logits = model(x)
loss = loss_fn(logits, targets)
model.backward(loss_fn.backward())

optimizer.step()
optimizer.zero_grad()
```

A simple rule of thumb is:

- Use `dnnlpy.nn` when a component is reusable across many models.
- Use `dnnlpy.models` when the code represents a complete architecture or is tightly coupled to one model family.

## License

This project is licensed under the **MIT License**.
