Examples

Every example in the examples/ directory is a single, runnable script that trains/evaluates on synthetic data and saves a publication-grade, magma-themed figure. Run any of them with:

uv run python examples/<name>.py

Example	What it shows
The q-Gaussian family	Compact support (q < 1), Gaussian (q = 1) and heavy tails (1 < q < 3), with samples overlaid on the analytic density.
Fitting q by maximum likelihood	Recovers a hidden generating q by gradient descent on the q-Gaussian log-likelihood — q is just a differentiable parameter.
Derivative-free optimization	An animated q-exponential-weighted search (contour + 3-D surface) whose heavy tails (q > 1) escape a decoy minimum that traps greedy q = 1.
Label-noise robustness	Bounded Tsallis cross-entropy (q < 1) vs. the Shannon baseline, and a learnable q that discovers the robust regime on its own.
Node classification under noise	A GCN with learnable Tsallis q stays robust to noisy training labels, while the Shannon baseline propagates the errors across the graph.
Exploration on a bandit	A tsallis_entmax policy whose learnable q anneals exploration into exploitation for the lowest cumulative regret.
Sparse self-attention	Attention pooling with tsallis_entmax; a learnable q recovers sparse, signal-focused attention as distractors grow.
Learning q in attention	Animated: watch the attention q being learned — as q rises toward sparsemax, the attention map sharpens onto the informative tokens.

The recurring theme: q as a learnable parameter

Five of the seven examples make q itself trainable, and the headline result is consistent: gradient descent reliably discovers a useful entropic index, with no grid search.

• Classification — the learned loss q settles in the robust regime (q ≈ 0.3) and matches the best hand-tuned fixed q at every noise level.

• Node classification — on a graph, the learned GCN loss q settles in the robust regime and stays accurate as label noise the Shannon baseline amplifies grows.

• Attention — the learned attention q converges near sparsemax (q ≈ 2.0), zeroing out distractor tokens.

• Reinforcement learning — the learned policy q rises over training, annealing exploration into exploitation.