Metadata-Version: 2.4
Name: sdhd
Version: 0.1.0
Summary: Stochastic-depth ResNet training library extracted from a thesis project
Project-URL: Homepage, https://github.com/gerageragera39/sdhd
Project-URL: Repository, https://github.com/gerageragera39/sdhd
Project-URL: Documentation, https://github.com/gerageragera39/sdhd/tree/main/sdhd/docs
Project-URL: Issues, https://github.com/gerageragera39/sdhd/issues
Author: Herman Dihtenko
License: MIT License
        
        Copyright (c) 2026 Herman
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: computer-vision,deep-learning,pytorch,resnet,stochastic-depth
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pillow>=10.0
Requires-Dist: torch>=2.1
Requires-Dist: torchvision>=0.16
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: lmdb
Requires-Dist: lmdb>=1.4; extra == 'lmdb'
Description-Content-Type: text/markdown

# sdhd

**sdhd** stands for **Stochastic Depth for High-Depth residual networks**.

It is a reusable Python library extracted from my thesis codebase on stochastic-depth regularization for residual CNNs.

## What the library provides

- ResNet models **without** stochastic depth;
- ResNet models **with stochastic depth** in two modes:
  - **per-batch** gating,
  - **per-sample** gating;
- CIFAR-style residual networks with 3x3 basic blocks;
- bottleneck residual networks (ResNet-50 / ResNet-101 style);
- folder-based image loading;
- CIFAR-100 loading;
- LMDB-backed datasets for large-scale training;
- a generic PyTorch training loop with checkpoint save/load support;
- a small command-line interface for training experiments.

## Installation

### Local editable install
```bash
pip install -e ./sdhd
```

### With LMDB support
```bash
pip install -e './sdhd[lmdb]'
```

## Quick examples

### Build a CIFAR-style model
```python
from sdhd import StochasticDepthConfig, CIFARResNetConfig, build_cifar_resnet

sd = StochasticDepthConfig(enabled=True, mode="sample", final_survival_prob=0.5)
config = CIFARResNetConfig(depth=110, num_classes=100, stochastic_depth=sd)
model = build_cifar_resnet(config)
```

### Build a bottleneck ResNet
```python
from sdhd import StochasticDepthConfig, BottleneckResNetConfig, build_bottleneck_resnet

sd = StochasticDepthConfig(enabled=True, mode="batch", final_survival_prob=0.5)
config = BottleneckResNetConfig(depth=50, num_classes=365, stochastic_depth=sd)
model = build_bottleneck_resnet(config)
```

### Create CIFAR-100 dataloaders
```python
from sdhd import create_cifar100_dataloaders

train_loader, test_loader = create_cifar100_dataloaders("/path/to/cifar100", batch_size=256)
```

### Train a built-in ResNet in one function call
```python
from sdhd import TrainerConfig, train_resnet

trainer = TrainerConfig(epochs=5, lr=0.01, output_dir="runs/example", compile_model=False)
result = train_resnet(
    architecture="bottleneck",
    dataset_type="folder",
    data_dir="/path/to/dataset",
    depth=50,
    batch_size=8,
    trainer_config=trainer,
    enable_sd=True,
    sd_mode="sample",
)
print(result.best_val_accuracy)
```

### Train your own custom PyTorch model
```python
import torch.nn as nn
from sdhd import TrainerConfig, train_custom_model

model = nn.Sequential(
    nn.Flatten(),
    nn.Linear(3 * 224 * 224, 102),
)

trainer = TrainerConfig(epochs=5, lr=0.01, output_dir="runs/custom", compile_model=False)
result = train_custom_model(
    model,
    dataset_type="folder",
    data_dir="/path/to/dataset",
    batch_size=8,
    trainer_config=trainer,
)
print(result.best_val_accuracy)
```

### Lower-level training API
```python
from sdhd import TrainerConfig, train_classifier

trainer = TrainerConfig(epochs=100, lr=0.1, output_dir="runs/example")
result = train_classifier(model, train_loader, test_loader, trainer)
print(result.best_val_accuracy)
```

## CLI

After installation, you can run:

```bash
sdhd-train --help
```

Or:

```bash
python -m sdhd --help
```

## Thesis background

This package comes from a thesis project on **stochastic depth for regularizing residual CNNs**. The main thesis-specific contributions preserved in this library are:

- explicit support for **per-sample** vs **per-batch** stochastic depth;
- stochastic depth for **bottleneck residual blocks**;
- support for **large-scale LMDB datasets**.

## Full documentation

The package keeps its public-facing documentation concentrated in this README, in-code docstrings, and the printable LaTeX manual:

- `docs/tex/sdhd_manual.tex`

Additional private/helper Markdown notes for workspace management are intentionally kept outside the standalone `sdhd` repository.

## Release and maintenance

Use GitHub Releases together with Trusted Publishing to publish to PyPI.

## Recommendation for the LaTeX manual

Keep the LaTeX source in the repository and optionally publish the compiled PDF through GitHub Releases. PyPI should stay focused on the concise package README.
