Metadata-Version: 2.2
Name: magnetron
Version: 0.1.5
Summary: High-performance, lightweight deep-learning library with a PyTorch like API and GPU support.
Keywords: machine-learning,deep-learning,neural-networks,gpu,simd
Author-Email: Mario Sieg <mario.sieg.64@gmail.com>
License: Copyright 2025 Mario Sieg
         
         Licensed under the Apache License, Version 2.0 (the "License");
         you may not use this file except in compliance with the License.
         You may obtain a copy of the License at
         
             http://www.apache.org/licenses/LICENSE-2.0
         
         Unless required by applicable law or agreed to in writing, software
         distributed under the License is distributed on an "AS IS" BASIS,
         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
         See the License for the specific language governing permissions and
         limitations under the License.
         
Requires-Python: >=3.10
Provides-Extra: examples
Requires-Dist: tokenizers; extra == "examples"
Requires-Dist: rich; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Requires-Dist: huggingface_hub; extra == "examples"
Provides-Extra: test
Requires-Dist: ruff; extra == "test"
Requires-Dist: torch; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: transformers; extra == "test"
Requires-Dist: tiktoken; extra == "test"
Requires-Dist: matplotlib; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pyinstrument; extra == "test"
Requires-Dist: rich; extra == "test"
Description-Content-Type: text/markdown

[![Stargazers][stars-shield]][stars-url]
[![Forks][forks-shield]][forks-url]
[![Issues][issues-shield]][issues-url]
![GitHub Actions Workflow Status][ci-shield]

<br />
<div align="center">
  <a href="https://github.com/MarioSieg/magnetron">
    <img src="https://raw.githubusercontent.com/MarioSieg/magnetron/develop/media/logo.png" alt="Magnetron Logo" width="200" height="200">
  </a>

<h3 align="center">magnetron</h3>
  <p align="center">
    A compact, PyTorch-style machine learning framework written in C and modern Python.
    <br />
    Designed for speed, clarity, and portability - from desktop to embedded.
    <br /><br />
    <a href="https://github.com/MarioSieg/magnetron/blob/develop/docs/4.%20Operator%20Cheatsheet.md"><strong>Documentation »</strong></a>
    <br /><br />
    <a href="https://github.com/MarioSieg/magnetron/blob/master/examples/qwen3">Qwen3 Example</a>
    ·
    <a href="https://github.com/MarioSieg/magnetron/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
    ·
    <a href="https://github.com/MarioSieg/magnetron/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
  </p>
</div>

---

## 📖 About

**Magnetron** is a lightweight, research-grade machine learning framework that mirrors the usability of PyTorch - but built entirely from scratch.  
Its C99 core, wrapped in a modern Python API, provides dynamic computation graphs, automatic differentiation, and high-performance operators with zero external dependencies.

Originally designed for constrained or experimental environments, Magnetron scales from small embedded systems to full desktop inference and training.  
A CUDA backend and mixed-precision support are currently in development.

---

### ⚡ Highlights

- **PyTorch-like API**  
  Familiar syntax for building and training models - easy to pick up, minimal to extend.

- **Dynamic autograd engine**  
  Eager execution with full gradient tracking on computation graphs.

- **Optimized C99 backend**  
  Custom tensor engine with SIMD acceleration (SSE, AVX2, AVX-512, NEON) and multithreaded execution.

- **Minimal dependencies**  
  No third-party math libraries; only **CFFI** is required for the Python interface.

- **Lightweight neural modules**  
  Includes `Linear`, `Sequential`, `ReLU`, `Tanh`, `Sigmoid`, `LayerNorm`, `Embedding`, and more.

- **Rich data types with many operators**  
  Supports `bfloat16`, `float16`, `float32`, `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, and `boolean`.

- **Custom serialization format**  
  Fast, portable model saving and loading through Magnetron’s own binary tensor format.

- **Clean diagnostics**  
  Readable validation and error messages for faster debugging and experimentation.

---

## 🚀 Example Models

| Example                                          | Description                                                                                     |
|--------------------------------------------------|-------------------------------------------------------------------------------------------------|
| [Qwen3 Inference](examples/qwen3/)               | Transformer-based text generation using pretrained Qwen3 weights, loaded from custom .mag file. |
| [GPT-2 Inference](examples/gpt2/)                | Transformer-based text generation using pretrained GPT-2 weights.                               |
| [Autoencoder](examples/ae/)                      | Image reconstruction using a small dense encoder–decoder network.                               |
| [Linear Regression](examples/linear_regression/) | Fits a linear model to noisy synthetic data.                                                    |
| [XOR](examples/xor/)                             | Trains a small neural network to learn the XOR logical function.                                |

---

## 📦 Installation

Make sure you are inside a **Python virtual environment** before installing.

**With uv**
```bash
uv pip install magnetron
```

**With pip**
```bash
pip install magnetron
```

## 🤝 Contributing
Contributions are welcome!  
Please open issues for ideas, or submit pull requests for new **features**.  
PRs that only fix typos or minor formatting will not be accepted.

## 📜 License
(c) 2026 Mario Sieg - mario.sieg.64@gmail.com<br>
Distributed under the Apache 2 License.
See `LICENSE` for more information.

## 🧩 Similar Projects

* [GGML](https://github.com/ggerganov/ggml)
* [TINYGRAD](https://github.com/tinygrad/tinygrad)
* [MICROGRAD](https://github.com/karpathy/micrograd)

[contributors-shield]: https://img.shields.io/github/contributors/MarioSieg/magnetron.svg?style=for-the-badge
[contributors-url]: https://github.com/MarioSieg/magnetron/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/MarioSieg/magnetron.svg?style=for-the-badge
[forks-url]: https://github.com/MarioSieg/magnetron/network/members
[stars-shield]: https://img.shields.io/github/stars/MarioSieg/magnetron.svg?style=for-the-badge
[stars-url]: https://github.com/MarioSieg/magnetron/stargazers
[issues-shield]: https://img.shields.io/github/issues/MarioSieg/magnetron.svg?style=for-the-badge
[issues-url]: https://github.com/MarioSieg/magnetron/issues
[license-shield]: https://img.shields.io/github/license/MarioSieg/magnetron.svg?style=for-the-badge
[license-url]: https://github.com/MarioSieg/magnetron/blob/master/LICENSE.txt
[ci-shield]: https://img.shields.io/github/actions/workflow/status/MarioSieg/magnetron/cmake-python-multi-platform.yml?style=for-the-badge
