Skip to main content

Crate hyperball

Crate hyperball 

Source
Expand description

Hyperbolic geometry for embedding hierarchical structures.

Embed trees and hierarchies in low dimensions where Euclidean would need thousands.

§Which Model Should I Use?

TaskModelWhy
Learning embeddingsLorentzModelStable gradients everywhere
VisualizationPoincareBallBounded, intuitive
Mixed hierarchy + similarityConsider mixed-curvatureBest of both

§Why Hyperbolic?

YearObservationImplication
2017Trees embed poorly in Euclidean spaceNeed exponential dims
2017Hyperbolic space has exponential volumeTrees embed naturally
2018Lorentz model more stableBetter for optimization
2021Mixed-curvature spacesBest of both worlds

Key insight: Hyperbolic space has exponentially growing volume with radius, just like trees have exponentially growing nodes with depth. A 10-dimensional hyperbolic space can embed trees that would require thousands of Euclidean dimensions.

§The Two Models

ModelRepresentationProsCons
Poincaré BallUnit ballIntuitive, conformalGradients vanish at boundary
Lorentz (Hyperboloid)Upper sheet of hyperboloidStable gradientsLess intuitive

For learning, prefer Lorentz: gradients are well-behaved everywhere. For visualization, prefer Poincaré: it’s a bounded disk.

§Mathematical Background

The Poincaré ball model represents hyperbolic space as the interior of a unit ball with the metric:

ds² = (2/(1-||x||²))² ||dx||²

As points approach the boundary (||x|| → 1), distances grow infinitely— this is how infinite hierarchical depth fits in finite Euclidean volume.

§When to Use

  • Taxonomies: WordNet, Wikipedia categories
  • Organizational hierarchies: Company structures, file systems
  • Evolutionary trees: Phylogenetics, language families
  • Social networks: Often have hierarchical community structure

§When NOT to Use

  • Flat structures: No hierarchy to exploit (use Euclidean)
  • Grid-like data: Images, audio (use CNN/RNN)
  • Very shallow trees: Depth < 5, Euclidean often suffices

§Connection to Intrinsic Dimension

Local Intrinsic Dimensionality (LID) can help decide between hyperbolic and Euclidean embeddings:

  • Low LID + hierarchical structure: Use hyperbolic (Poincaré/Lorentz)
  • High LID + uniform structure: Use Euclidean (HNSW, IVF-PQ)
  • Variable LID across regions: Consider mixed-curvature spaces

Research (D-Mercator, 2023) shows that networks with low intrinsic dimension in hyperbolic space exhibit high navigability—meaning greedy routing succeeds. This connects to HNSW’s small-world navigation: graphs with low effective dimension are easier to search.

See jin::lid for LID estimation utilities.

§References

§Foundational

  • Nickel & Kiela (2017), “Poincare Embeddings for Learning Hierarchical Representations” – introduced hyperbolic embeddings for ML.
  • Nickel & Kiela (2018), “Learning Continuous Hierarchies in the Lorentz Model” – showed the Lorentz model is more stable for optimization.
  • Ganea, Becigneul, Hofmann (2018), “Hyperbolic Neural Networks” – foundational hyperbolic NN layers using Mobius gyrovector operations.
  • Chami et al. (2019), “Hyperbolic Graph Convolutional Neural Networks” – GCNs in hyperbolic space.

§Capacity and training

  • Kratsios et al. (2023), “Capacity Bounds for Hyperbolic Neural Network Representations of Latent Tree Structures” – proves that 2D hyperbolic space suffices for embedding any tree with bounded distortion; justifies the low-dimensional regime this library targets.
  • Yang et al. (2023), “Hyperbolic Representation Learning: Revisiting and Advancing” (ICML) – training tricks (gradient clipping, LR scheduling) matter as much as model choice; practical guidance for users of this library.

§Flow matching and geometry

  • Chen & Lipman (2023), “Riemannian Flow Matching on General Geometries” – foundational for hyperbolic flow matching via the Manifold trait.
  • Zaghen et al. (2025), “Towards Variational Flow Matching on General Geometries” (RG-VFM).

§Mixed curvature (future direction)

  • Di Giovanni et al. (2022), “Heterogeneous Manifolds for Curvature-Aware Graph Embedding” – mixed-curvature product spaces (hyperbolic x spherical x Euclidean) as a natural extension when data has both hierarchical and cyclical structure.

§General geometric deep learning

  • Bronstein et al. (2021/2025), “Geometric Deep Learning” (book/course) – see geometricdeeplearning.com.

Re-exports§

pub use lorentz::LorentzModel;

Modules§

core
Backend-agnostic hyperbolic primitives.
lorentz
Lorentz (hyperboloid) model of hyperbolic space.

Structs§

PoincareBall
Poincare ball model of hyperbolic geometry.