Skip to content
Projects

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.

How these counts are measured

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 Learning

README.md

Original

CI Status ruff ty Test coverage percentage

PyPi Status GitHub release (latest by date) pyversions License

Huggingface Spaces Open in Colab

Documentation Status

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

Open In Colab

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

Models for vision tasks

Vision-related operations

Trying something else than Adam

More goodies

Documentation

The full package documentation is available here for detailed specifications.

Demo app

The project includes a minimal demo app using Gradio

demo_app

You can check the live demo, hosted on :hugs: HuggingFace Spaces :hugs: over here :point_down: Hugging Face Spaces

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.