omnibias-graph

From relations to soft assignments. Spectral operators and matrix relaxations expose graph structure.

Static poster · Narrow-screen animation · How this visual is computed

An affinity or cost matrix enters; spectral graph operators, embeddings, soft orderings or assignment matrices leave. Graph-aware models can compose these outputs with trainable features while respecting each relaxation’s constraints.

The animation uses computed outputs to explain this package. Frame transitions are illustrative unless a training step is explicitly identified; it is not a performance comparison.

API reference · Source · Tests · Talk to Derivon

The mathematical connection

Temperature-like sharpening controls selected soft assignment and sorting operators. Ties and finite iteration residuals must remain visible when interpreting a hardened result. Spectral Laplacians are a separate graph-calculus operation, not automatically a temperature limit. Bias collapse is consumed only where a differentiated model explicitly uses the shared derivative tower.

Run this README

The examples use omnibias-graph[torch] on Python >=3.10. Their installed-wheel profile selects runtime features, not an editable workspace. Install the prepared prerelease from PyPI:

python -m pip install --pre "omnibias-graph[torch]==0.1.0a2"

For local development before publication, build and test the coordinated wheelhouse using the release guide. The package's wheel profile executes the examples below outside the source checkout.

Existing published consumers may need historical primitive versions; see the compatibility policy.

Why this package exists

Graph Laplacians describe connectivity and diffusion; smooth assignment matrices provide a route from discrete matching choices to trainable scores. Graph puts these reusable operations in one primitive so application packages can focus on their objective and decoding policy.

What you can build

• Laplacians, spectral embeddings and heat-kernel operations.
• Sinkhorn normalization, soft sorting and soft top-k.
• Torch and JAX realizations plus arrangement-related operators.

Use spectral operators for geometry-aware representations and smooth relaxations when a downstream loss must influence assignment scores. Combinatorial applications, routing workflows and shape models live in consumers. A matrix relaxation is a component of those products rather than a complete optimizer.

A working example

import torch
from omnibias.graph.torch.ops import graph_laplacian, sinkhorn_normalize

adjacency = torch.tensor([[0., 1., 0.], [1., 0., 1.], [0., 1., 0.]])
L = graph_laplacian(adjacency)
assert torch.allclose(L.sum(dim=1), torch.zeros(3))
scores = torch.eye(3, requires_grad=True)
assignment = sinkhorn_normalize(scores, n_iters=30)
(assignment * torch.arange(9).reshape(3, 3)).sum().backward()
assert scores.grad is not None

Choose the right contract

Repeated eigenvalues can make eigenvector gradients ambiguous. Sinkhorn uses a finite iteration budget, so row and column constraints need tolerances. A doubly stochastic matrix is not a permutation until decoded, and a low-temperature choice still needs handling of ties and numerical range.

Explore and validate

The API guide contains the generated module/export inventory. Use it to find the focused implementation rather than guessing a symbol from another package. The capability map connects the primitives to larger scientific workflows.

From the main repository, run the package’s regression suite:

uv run pytest packages/omnibias-graph/tests -q

License

AGPL-3.0-or-later or commercial. See LICENSE and the licensing policy. Comply with the AGPL terms or obtain a signed commercial grant; commercial use alone does not require payment. Commercial terms describe the alternative. Previously distributed Apache editions, where applicable, retain their original grants.