Geometric region embeddings for subsumption, entailment, and logical query answering. Boxes, cones, octagons, Gaussians, hyperbolic intervals, and sheaf networks. Ndarray and Candle backends. The only published Rust crate for geometric knowledge graph embeddings.

(a) Containment: nested boxes encode taxonomic is-a relationships. (b) Gumbel soft boundary: temperature controls membership sharpness. (c) Octagon: diagonal constraints cut corners for tighter volume bounds.

The ndarray backend is the primary workhorse with full geometry support. The candle backend provides GPU-accelerated box operations for training workflows.

[dependencies]
subsume = { version = "0.2.1", features = ["ndarray-backend"] }
ndarray = "0.16"

use subsume::ndarray_backend::NdarrayBox;
use subsume::Box as BoxTrait;
use ndarray::array;

// Box A: [0,0,0] to [1,1,1] (general concept)
let premise = NdarrayBox::new(array![0., 0., 0.], array![1., 1., 1.], 1.0)?;

// Box B: [0.2,0.2,0.2] to [0.8,0.8,0.8] (specific, inside A)
let hypothesis = NdarrayBox::new(array![0.2, 0.2, 0.2], array![0.8, 0.8, 0.8], 1.0)?;

// Containment probability: P(B inside A)
let p = premise.containment_prob(&hypothesis, 1.0)?;
assert!(p > 0.9);

cargo run -p subsume --example containment_hierarchy    # taxonomic is-a relationships with nested boxes
cargo run -p subsume --example gumbel_box_exploration   # Gumbel boxes, soft containment, temperature effects
cargo run -p subsume --example cone_training            # training cone embeddings on a taxonomy
cargo run -p subsume --example box_training             # training box embeddings on a 25-entity taxonomy
cargo run -p subsume --example taxobell_demo            # TaxoBell Gaussian box losses on a mini taxonomy
cargo run -p subsume --example query2box                # Query2Box: multi-hop queries, box intersection, distance scoring
cargo run -p subsume --example octagon_demo             # octagon embeddings: diagonal constraints, containment, volume
cargo run -p subsume --example fuzzy_query              # fuzzy query answering: t-norms, De Morgan duality, rankings
cargo run -p subsume --example el_training              # EL++ box embeddings on a biomedical-style ontology
cargo run -p subsume --features candle-backend --example taxobell_training  # TaxoBell MLP encoder training (Candle)

See examples/README.md for a guide to choosing the right example.

cargo test -p subsume

Unit, property, and doc tests covering:

• Box geometry: intersection, union, containment, overlap, distance, volume, truncation
• Gumbel boxes: membership probability, temperature edge cases, Bessel volume
• Cones: angular containment, negation closure, aperture bounds
• Octagon: intersection closure, containment, Sutherland-Hodgman volume
• Fuzzy: t-norm/t-conorm commutativity, associativity, De Morgan duality
• Gaussian boxes, EL++ ontology losses, sheaf networks, hyperbolic geometry
• Training: MRR, Hits@k, NDCG, calibration, negative sampling, AMSGrad

Point embeddings (TransE, RotatE, ComplEx) represent entities as vectors. They work well for link prediction -- RotatE hits 0.476 MRR on WN18RR, BoxE hits 0.451. For standard triple scoring, points are simpler and equally accurate.

Regions become necessary when the task requires structure that points cannot encode:

Three tasks where point embeddings structurally fail:

1. Ontology completion (EL++): "Dog is-a Animal" requires representing one concept's extension as a subset of another's. Points have no containment. Box2EL, TransBox, and DELE use boxes for this and outperform point baselines on Gene Ontology, GALEN, and Anatomy by wide margins.

2. Logical query answering (∧, ∨, ¬): multi-hop KG queries with conjunction, disjunction, and negation need set operations. ConE handles all three (MRR 52.9 on FB15k EPFO+negation queries vs Query2Box's 41.0 and BetaE's 44.6). Points cannot attempt negation queries at all.

3. Taxonomy expansion: inserting a new concept at the right depth requires knowing both what it is (similarity) and how general it is (volume). TaxoBell uses Gaussian boxes where KL divergence gives asymmetric parent-child containment for free.

If your task is link prediction or entity similarity, use RotatE. If you need containment, set operations, or volume, you need regions.

Containment loss under increasing coordinate noise for Gumbel, Gaussian, and hard boxes. Gumbel boxes remain stable at perturbation levels where other formulations fail.

Gumbel boxes model coordinates as Gumbel random variables, creating soft boundaries that provide dense gradients throughout training. Hard boxes create flat regions where gradients vanish; Gumbel boxes solve this local identifiability problem (Dasgupta et al., 2020). As shown above, this also makes containment robust to coordinate noise -- Gumbel containment loss stays near zero even at high perturbation levels where Gaussian boxes fail completely.

25-entity taxonomy learned over 200 epochs. Left: total violation drops 3 orders of magnitude. Right: containment probabilities converge to 1.0 at different rates depending on hierarchy depth. Reproduce: cargo run --example box_training or uv run scripts/plot_training.py.

• Nickel & Kiela (2017). "Poincare Embeddings for Learning Hierarchical Representations"
• Vilnis et al. (2018). "Probabilistic Embedding of Knowledge Graphs with Box Lattice Measures"
• Li et al. (2019). "Smoothing the Geometry of Probabilistic Box Embeddings" (ICLR 2019)
• Abboud et al. (2020). "BoxE: A Box Embedding Model for Knowledge Base Completion"
• Dasgupta et al. (2020). "Improving Local Identifiability in Probabilistic Box Embeddings"
• Ren et al. (2020). "Query2Box: Reasoning over Knowledge Graphs using Box Embeddings"
• Hansen & Ghrist (2019). "Toward a Spectral Theory of Cellular Sheaves"
• Bodnar et al. (2022). "Neural Sheaf Diffusion: A Topological Perspective on Heterophily and Oversmoothing in GNNs"
• Zhang & Wang (2021). "ConE: Cone Embeddings for Multi-Hop Reasoning over Knowledge Graphs"
• Chen et al. (2022). "Fuzzy Logic Based Logical Query Answering on Knowledge Graphs"
• Jackermeier et al. (2023). "Dual Box Embeddings for the Description Logic EL++"
• Yang, Chen & Sattler (2024). "TransBox: EL++-closed Ontology Embedding"
• Bourgaux et al. (2024). "Knowledge Base Embeddings: Semantics and Theoretical Properties" (KR 2024)
• Charpenay & Schockaert (2024). "Capturing Knowledge Graphs and Rules with Octagon Embeddings"
• Lacerda et al. (2024). "Strong Faithfulness for ELH Ontology Embeddings" (TGDK 2024)
• Huang et al. (2023). "Concept2Box: Joint Geometric Embeddings for Learning Two-View Knowledge Graphs"
• Mashkova et al. (2024). "DELE: Deductive EL++ Embeddings for Knowledge Base Completion"
• Yang & Chen (2025). "Achieving Hyperbolic-Like Expressiveness with Arbitrary Euclidean Regions"
• Mishra et al. (2026). "TaxoBell: Gaussian Box Embeddings for Self-Supervised Taxonomy Expansion" (WWW '26)

• hyperball -- hyperbolic geometry primitives (direct dependency for Poincare/Lorentz embeddings)

MIT OR Apache-2.0