frgfm/holocron
frgfm/holocron has 327 GitHub stars and 47 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-18 01:29 UTC. Last push 2026-11-14.
Measured star growth
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- 0
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
PyTorch implementations of recent Computer Vision tricks (ReXNet, RepVGG, Unet3p, YOLOv4, CIoU loss, AdaBelief, PolyLoss, MobileOne). Other additions: AdEMAMix
Machine LearningREADME.md
Original
Implementations of recent Deep Learning tricks in Computer Vision, easily paired up with your favorite framework and model zoo.
Holocrons were information-storage datacron devices used by both the Jedi Order and the Sith that contained ancient lessons or valuable information in holographic form.
Source: Wookieepedia
Quick Tour
Holocron provides research implementations with PyTorch interfaces. Implementations and training recipes may differ from a paper author's code. This example uses an explicit checkpoint and its preprocessing and labels:
import torch
from PIL import Image
from holocron.models.classification import ResNet18_Checkpoint, resnet18
checkpoint = ResNet18_Checkpoint.IMAGENETTE.value
model = resnet18(checkpoint=checkpoint).eval()
image = Image.open(path_to_an_image).convert("RGB")
input_tensor = checkpoint.transforms()(image).unsqueeze(0)
with torch.inference_mode():
probabilities = model(input_tensor).squeeze(0).softmax(dim=0)
class_idx = probabilities.argmax().item()
label = checkpoint.meta.categories[class_idx]
confidence = probabilities[class_idx].item()
print(label, confidence)
Pretrained models
An architecture may be available without pretrained weights. See the checkpoint list and loading guide for classification datasets, metrics and weight compatibility, and the support status for other tasks. Most classification checkpoints target Imagenette (10 classes); selected ReXNet variants also provide ImageNet-1K weights (1,000 classes).
Use the checkpoint's preprocessing and category metadata, as shown above.
A matching model name does not make torchvision or timm weights compatible.
To adapt pretrained weights to your own classes, load them before replacing the
classifier; see the transfer-learning guide.
Legacy weight loaders log a warning and keep the affected model's initial
parameters when no weights are available. YOLO26 builders instead raise
ValueError for pretrained=True. No full detection checkpoints are published; a pretrained
classification backbone is not a pretrained detector. Train models without
weights with the reference scripts.
Loss functions
PolyLoss expects raw logits and either torch.int64 class indices or soft
class probabilities. See the loss input guide and runnable example
for tensor shapes, target types and the current ignore_index limitations.
Installation
Prerequisites
Python 3.11 (or higher) and uv/pip are required to install Holocron.
Latest stable release
You can install the last stable release of the package using pypi as follows:
pip install pylocron
Developer mode
Alternatively, if you wish to use the latest features of the project that haven't made their way to a release yet, you can install the package from source (install Git first):
git clone https://github.com/frgfm/Holocron.git
pip install -e Holocron/.
Paper references
PyTorch layers for every need
- Activation: HardMish, NLReLU, FReLU
- Loss: Focal Loss, MultiLabelCrossEntropy, MixupLoss, ClassBalancedWrapper, ComplementCrossEntropy, MutualChannelLoss, DiceLoss, PolyLoss
- Convolutions: NormConv2d, Add2d, SlimConv2d, PyConv2d, Involution
- Regularization: DropBlock
- Pooling: BlurPool2d, SPP, ZPool
- Attention: SAM, LambdaLayer, TripletAttention
Models for vision tasks
- Image Classification: Res2Net (based on the great implementation from Ross Wightman), Darknet-24, Darknet-19, Darknet-53, CSPDarknet-53, ResNet, ResNeXt, TridentNet, PyConvResNet, ReXNet, SKNet, RepVGG, ConvNeXt, MobileOne.
- Object Detection: YOLOv1, YOLOv2, YOLOv4
- Semantic Segmentation: U-Net, UNet++, UNet3+
Vision-related operations
Trying something else than Adam
- Optimizer: LARS, Lamb, TAdam, AdamP, AdaBelief, Adan, and customized versions (RaLars), AdEMAMix
- Optimizer wrapper: Lookahead, Scout (experimental)
More goodies
Documentation
The full package documentation is available here for detailed specifications.
Demo app
The project includes a minimal demo app using Gradio

You can check the live demo, hosted on :hugs: HuggingFace Spaces :hugs: over here :point_down:
Reference scripts
Reference scripts are provided to train your models using holocron on famous public datasets. Those scripts currently support the following vision tasks:
YOLO training status
YOLOv4's training implementation has been repaired and verified with regression tests and a reproducible CPU fixed-batch learning check. With a frozen pretrained Imagenette CSPDarknet53-Mish backbone, it produces correctly labeled detections with IoUs of 0.81 and 0.79 on two synthetic examples, with finite losses and gradients and a saved checkpoint. See the detection guide for the command, matched control, and CUDA/VOC smoke recipe.
Full CUDA/VOC training on the repaired implementation remains pending; the synthetic result does not establish dataset accuracy or reproduce the paper. YOLOv1/v2 loss behavior is unchanged, with regression coverage for shared inference changes. YOLOv3 is not implemented as a detector; the Darknet-53 classification backbone is available. No pretrained detection checkpoints are published.
Latency benchmark
Pareto-optimal Imagenette checkpoints for accuracy and latency, on CPU or GPU:
| Model | Acc@1 | Params | CPU (ms) | MPS (ms) |
|---|---|---|---|---|
mobileone_s0 |
88.08% | 4.3M | 6.7 | 1.7 |
mobileone_s1 |
91.26% | 3.6M | 11.8 | 1.9 |
mobileone_s2 |
91.31% | 5.9M | 14.4 | 2.4 |
resnet18 |
93.61% | 11.2M | 16.4 | 2.7 |
darknet19 |
93.86% | 19.8M | 19.2 | 3.1 |
rexnet1_0x |
94.39% | 3.5M | 19.8 | 6.5 |
rexnet1_5x |
94.47% | 7.8M | 30.3 | 6.6 |
resnext50_32x4d |
94.55% | 23.0M | 33.2 | 7.4 |
resnet50d |
94.65% | 23.5M | 28.4 | 7.6 |
rexnet1_3x |
94.88% | 5.9M | 26.1 | 8.2 |
rexnet2_0x |
95.24% | 13.8M | 39.5 | 7.7 |
rexnet2_2x |
95.44% | 16.7M | 43.8 | 8.6 |
Median batch-1 latency per architecture at 224×224 on an Apple M3 Pro (one CPU thread, or its GPU via MPS), PyTorch 2.13. See the checkpoint table for all 31 checkpoints and the measurement guide to reproduce on your hardware:
uv sync --locked --extra scripts
uv run --no-sync python scripts/eval_latency.py rexnet1_0x --device cpu
Docker container
If you wish to deploy containerized environments, you can use the provided Dockerfile to build a docker image:
make build-api
Minimal API template
Looking for a boilerplate to deploy a model from Holocron with a REST API? Thanks to the wonderful FastAPI framework, you can do this easily.
Deploy your API locally
Run your API in a docker container as follows:
make start-api
In order to stop the container, use make stop-api
What you have deployed
Your API is now running on port 8080, with its documentation http://localhost:8080/redoc and requestable routes:
import requests
with open("/path/to/your/img.jpeg", "rb") as f:
data = f.read()
response = requests.post("http://localhost:8080/classification", files={"file": data}).json()
Citation
If you wish to cite this project, feel free to use this BibTeX reference:
@software{Fernandez_Holocron_2020,
author = {Fernandez, François-Guillaume},
month = {5},
title = {{Holocron}},
url = {https://github.com/frgfm/Holocron},
year = {2020}
}
Contributing
Any sort of contribution is greatly appreciated!
You can find a short guide in CONTRIBUTING to help grow this project!
License
Distributed under the Apache 2.0 License. See LICENSE for more information.