Metadata-Version: 2.3
Name: vizopt
Version: 0.0.4
Summary: Mathematical optimization for data visualization
Author: Spectalizer
Author-email: Spectalizer <spectalizer@protonmail.com>
Requires-Dist: jax==0.9.1
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: networkx>=3.6.1
Requires-Dist: optax>=0.2.6
Requires-Dist: pandas>=3.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Python: >=3.13, <3.14.1
Project-URL: repository, https://github.com/spectalizer/vizopt/
Description-Content-Type: text/markdown

# vizopt

Mathematical optimization for data visualization, specifically designed for graph layouts with hierarchical inclusion constraints ("bubble layouts").

Uses JAX for automatic differentiation and JIT compilation to efficiently optimize layouts via gradient descent.

Read the documentation [https://spectalizer.github.io/vizopt/](https://spectalizer.github.io/vizopt/).

## Installation

```bash
pip install vizopt
```

## Quick Start

```python
import numpy as np
from vizopt.templates import circle_packing

# Define circle radii
rng = np.random.default_rng(0)
radii = rng.uniform(0.1, 1.0, size=20).tolist()

# Pack circles to minimize overlap and bounding box size
positions = circle_packing.optimize_circle_packing(
    radii=radii,
    weight_total_size=10.0,
    collision_offset=0.05,
    optim_kwargs={"n_iters": 3000, "learning_rate": 0.01},
)
# positions is a list of (x, y) tuples, one per circle
```

## Features

- Multi-objective optimization (edge lengths, compactness, collision avoidance, inclusion constraints)
- Efficient JAX-based gradient descent with JIT compilation
- Handles arbitrary hierarchical inclusion relationships
- NetworkX integration with a consistent DiGraph convention: **parent → child edges** (`(u, v)` means `v ⊂ u`)

## Examples

See [examples/examples_with_bubbles.ipynb](examples/examples_with_bubbles.ipynb) for detailed usage.

## License

MIT

## For developers

### Documentation

Using Zensical.

`uv run zensical serve`

`uv run python scripts/nb_to_md.py --execute examples/circle_packing.ipynb docs/examples/from-notebook-circle-packing.md`