Metadata-Version: 2.4
Name: omnimalloc
Version: 1.0.0
Summary: Your one-stop shop for static memory allocation.
Keywords: memory,allocation,allocator,static-allocation
Author-Email: Fabian Peddinghaus <fabianpedd@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/fpedd/omnimalloc
Project-URL: Repository, https://github.com/fpedd/omnimalloc
Project-URL: Issues, https://github.com/fpedd/omnimalloc/issues
Requires-Python: >=3.10
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: all
Requires-Dist: deap>=1.4.0; extra == "all"
Requires-Dist: huggingface-hub>=0.35.0; extra == "all"
Requires-Dist: matplotlib>=3.10.0; extra == "all"
Requires-Dist: numpy>=1.25.0; extra == "all"
Requires-Dist: onnx>=1.19.0; extra == "all"
Requires-Dist: tqdm>=4.66.0; extra == "all"
Description-Content-Type: text/markdown

<h1 align="center">OmniMalloc</h1>

<p align="center">State-of-the-art static memory allocation for neural networks.</p>

<p align="center">
  <a href="https://github.com/fpedd/omnimalloc/actions/workflows/checks.yml"><img src="https://img.shields.io/github/actions/workflow/status/fpedd/omnimalloc/checks.yml?branch=main&label=checks" alt="Checks"></a>
  <a href="https://github.com/fpedd/omnimalloc/actions/workflows/build.yml"><img src="https://img.shields.io/github/actions/workflow/status/fpedd/omnimalloc/build.yml?branch=main&label=build" alt="Build"></a>
  <a href="https://pypi.org/project/omnimalloc/"><img src="https://img.shields.io/pypi/v/omnimalloc" alt="PyPI"></a>
  <a href="https://pypi.org/project/omnimalloc/"><img src="https://img.shields.io/pypi/pyversions/omnimalloc" alt="Python versions"></a>
  <a href="https://github.com/fpedd/omnimalloc/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/omnimalloc" alt="License"></a>
</p>

OmniMalloc is a Python library for static memory allocation: given buffers
with known sizes and lifetimes, assign offsets so that peak memory is minimized.
This is the memory-planning step at the heart of ML compilers, embedded
runtimes, and accelerator toolchains.

It ships a collection of allocators and allocation algorithms behind one API,
implemented with an efficient C++ backend. This includes SuperMalloc, a new
allocator that outperforms the best open-source alternatives (see benchmarks
below). OmniMalloc also provides a rich benchmark harness and visualization
tools to develop and evaluate new allocation strategies.

## Installation

Install the latest release from PyPI:

```bash
pip install omnimalloc
```

Or install the development version directly from GitHub:

```bash
pip install git+https://github.com/fpedd/omnimalloc.git
```

## Usage

```python
import omnimalloc as om

pool = om.Pool(
    id="pool",
    allocations=(
        om.Allocation(id=0, size=64, start=0, end=10),
        om.Allocation(id=1, size=64, start=12, end=20),
        om.Allocation(id=2, size=32, start=5, end=15),
    ),
)

pool = om.allocate(pool, allocator="supermalloc", validate=True)

print(pool.size)  # 96
print([alloc.offset for alloc in pool.allocations])  # [0, 0, 64]
```

Lifetimes are half-open, `[start, end)`: an allocation ending at `t` and one
starting at `t` never conflict, so they may share the same addresses.

On a real problem, the result looks like this: 308 buffers of an ML workload
packed with no wasted memory.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fpedd/omnimalloc/main/assets/allocation_dark.svg">
    <img src="https://raw.githubusercontent.com/fpedd/omnimalloc/main/assets/allocation_light.svg" alt="A solved allocation problem rendered as offset/time rectangles">
  </picture>
</p>

See [examples](examples/) for allocator selection, visualization, custom
allocation sources, and benchmarking.

## Benchmarks

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fpedd/omnimalloc/main/assets/hero_dark.svg">
    <img src="https://raw.githubusercontent.com/fpedd/omnimalloc/main/assets/hero_light.svg" alt="Solution quality vs. solve time across allocators">
  </picture>
</p>

All figures on this page are generated from a deterministic benchmark run by
[`scripts/generate_readme_assets.py`](scripts/generate_readme_assets.py).
Run your own campaigns with the [benchmark harness](examples/05_benchmark.py).

## Development

```bash
# Initial setup
git clone git@github.com:fpedd/omnimalloc.git
cd omnimalloc
uv sync --all-extras --group dev

# Run tests, linting, type checking
uv run pytest
uv run ruff check --fix && uv run ruff format && uv run ty check

# Setup pre-commit hooks (run once)
uv run pre-commit install

# Run pre-commit checks manually
uv run pre-commit run --all-files
```

## License

Copyright 2025-2026 Fabian Peddinghaus. Licensed under Apache 2.0 License. See [LICENSE](LICENSE) for details.
