Crate subsume 

subsume

Geometric region embeddings for subsumption, entailment, and logical query answering.

subsume provides framework-agnostic traits and concrete backends for geometric embeddings – boxes, cones, octagons, Gaussians, and hyperbolic intervals – that encode hierarchical relationships through geometric containment. If region A contains region B (B ⊆ A), then A subsumes B: the more general concept contains the more specific one.

Getting Started

Goal	Start here
Understand the core abstraction	Box trait, BoxError
Use probabilistic (Gumbel) boxes	GumbelBox trait, gumbel module
Use octagon embeddings (box + diagonal constraints)	NdarrayOctagon, octagon module
Fuzzy query answering (t-norms)	TNorm, TConorm, fuzzy module
Load a knowledge graph dataset	Dataset, Triple
Train box embeddings (ndarray)	ndarray_backend, TrainingConfig
Evaluate with link prediction	evaluate_link_prediction, training::metrics

Why regions instead of points?

Point embeddings (TransE, RotatE) work for link prediction but cannot encode containment, volume, or set operations. Regions become necessary when the task requires:

• Subsumption: box A inside box B means A is-a B
• Generality: large volume = broad concept, small volume = specific
• Intersection: combining two concepts (A ∧ B) yields a valid region
• Negation: cone complement is another cone (FOL queries with ¬)

For standard triple scoring, points are simpler and equally accurate. For ontology completion (EL++), taxonomy expansion, and logical query answering, regions are structurally required.

Key Concepts

Box embeddings represent concepts as hyperrectangles. Unlike point vectors, boxes have volume, which encodes generality: a broad concept (“animal”) is a large box containing smaller boxes (“dog”, “cat”).

Gumbel boxes solve the local identifiability problem of hard boxes by modeling coordinates as Gumbel random variables. This ensures dense gradients throughout training – hard boxes create flat regions where gradients vanish.

Containment probability measures entailment (P(B ⊆ A)), while overlap probability measures relatedness without strict hierarchy. These two scores are the primary outputs of box embedding models.

Module Organization

Core traits and geometry

• box_trait – the Box trait: containment, overlap, volume
• gumbel – the GumbelBox trait: probabilistic box operations
• octagon – octagon error types (implementations in ndarray_backend)
• cone – cone error types (implementations in ndarray_backend)
• hyperbolic – Poincare ball embeddings for tree-like hierarchies
• sheaf – sheaf neural networks for transitivity/consistency on graphs
• gaussian – diagonal Gaussian box embeddings (KL, Bhattacharyya)

Representations and scoring

• distance – Query2Box distance scoring
• fuzzy – t-norms, t-conorms, and negation for fuzzy query answering (FuzzQE)

Ontology and taxonomy

• el – EL++ ontology embedding primitives (Box2EL / TransBox)
• taxonomy – TaxoBell-format taxonomy dataset loader
• taxobell – TaxoBell combined training loss

Training and evaluation

• dataset – load WN18RR, FB15k-237, YAGO3-10, and similar KG datasets
• trainable – TrainableBox and TrainableCone with learnable parameters
• trainer – negative sampling, loss computation, link prediction evaluation
• training – rank-based metrics (MRR, Hits@k, Mean Rank, nDCG)
• optimizer – AMSGrad state management
• utils – numerical stability (log-space volume, stable sigmoid, Gumbel operations)

Backends (feature-gated)

• ndarray_backend – NdarrayBox, NdarrayGumbelBox, distance functions (feature = ndarray-backend, on by default)
• candle_backend – CandleBox, CandleGumbelBox with GPU support (feature = candle-backend)

Feature Flags

Feature	Default	Provides
ndarray-backend	yes	ndarray_backend module, enables rand
candle-backend	no	candle_backend module (GPU via candle)
rand	no	Negative sampling utilities in trainer

Example

use subsume::{Box, GumbelBox};

// Framework-agnostic: works with NdarrayBox, CandleBox, or your own impl
fn compute_entailment<B: Box>(
    premise: &B,
    hypothesis: &B,
    temp: B::Scalar,
) -> Result<B::Scalar, subsume::BoxError> {
    premise.containment_prob(hypothesis, temp)
}

References

• Vilnis et al. (2018), “Probabilistic Embedding of Knowledge Graphs with Box Lattice Measures”
• Abboud et al. (2020), “BoxE: A Box Embedding Model for Knowledge Base Completion”
• Li et al. (2019), “Smoothing the Geometry of Probabilistic Box Embeddings” (ICLR 2019)
• Dasgupta et al. (2020), “Improving Local Identifiability in Probabilistic Box Embeddings”
• Chen et al. (2021), “Uncertainty-Aware Knowledge Graph Embeddings” (UKGE)
• Lee et al. (2022), “Box Embeddings for Event-Event Relation Extraction” (BERE)
• Cao et al. (2024, ACM Computing Surveys), “KG Embedding: A Survey from the Perspective of Representation Spaces” – positions box/cone/octagon embeddings within the broader KGE taxonomy (Euclidean, hyperbolic, complex, geometric)
• Bourgaux et al. (2024, KR), “Knowledge Base Embeddings: Semantics and Theoretical Properties”
• Lacerda et al. (2024, TGDK), “Strong Faithfulness for ELH Ontology Embeddings”
• Yang & Chen (2025), “RegD: Achieving Hyperbolic-Like Expressiveness with Arbitrary Euclidean Regions” – source of the depth/boundary dissimilarity metrics in distance

Re-exports

pub use box_trait::Box;

pub use box_trait::BoxError;

pub use gumbel::GumbelBox;

pub use cone::ConeError;

pub use hyperbolic::hierarchy_preserved;ndarray-backend

pub use hyperbolic::pairwise_distances;ndarray-backend

pub use hyperbolic::Curvature;ndarray-backend

pub use hyperbolic::HyperbolicError;ndarray-backend

pub use hyperbolic::PoincareBallPoint;ndarray-backend

pub use dataset::Dataset;

pub use dataset::DatasetError;

pub use dataset::DatasetStats;

pub use dataset::Triple;

pub use distance::query2box_distance;

pub use optimizer::get_learning_rate;

pub use optimizer::AMSGradState;

pub use trainable::TrainableBox;

pub use trainable::TrainableCone;

pub use trainer::compute_cone_analytical_gradients;

pub use trainer::compute_cone_pair_loss;

pub use trainer::evaluate_link_prediction;

pub use trainer::log_training_result;

pub use trainer::ConeEmbeddingTrainer;

pub use trainer::EvaluationResults;

pub use trainer::NegativeSamplingStrategy;

pub use trainer::TrainingConfig;

pub use trainer::TrainingResult;

pub use trainer::generate_negative_samples;rand

pub use trainer::generate_negative_samples_from_pool_with_rng;rand

pub use trainer::generate_negative_samples_from_sorted_pool_with_rng;rand

pub use trainer::generate_negative_samples_with_rng;rand

pub use trainer::SortedEntityPool;rand

pub use training::metrics::hits_at_k;

pub use training::metrics::mean_rank;

pub use training::metrics::mean_reciprocal_rank;

pub use training::metrics::ndcg;

pub use sheaf::consistency_score;

pub use sheaf::diffuse_until_convergence;

pub use sheaf::DenseRestriction;

pub use sheaf::DiffusionConfig;

pub use sheaf::LaplacianType;

pub use sheaf::RestrictionMap;

pub use sheaf::SheafEdge;

pub use sheaf::SheafError;

pub use sheaf::SheafGraph;

pub use sheaf::SimpleSheafGraph;

pub use sheaf::Stalk;

pub use sheaf::VecStalk;

pub use gaussian::bhattacharyya_coefficient;

pub use gaussian::bhattacharyya_distance;

pub use gaussian::kl_divergence as gaussian_kl_divergence;

pub use gaussian::sigma_ceiling_loss;

pub use gaussian::sigma_clipping_loss;

pub use gaussian::volume_regularization as gaussian_volume_regularization;

pub use gaussian::GaussianBox;

pub use taxonomy::TaxonomyDataset;

pub use taxonomy::TaxonomyNode;

pub use taxobell::CombinedLossResult;

pub use taxobell::TaxoBellConfig;

pub use taxobell::TaxoBellLoss;

pub use taxobell_encoder::evaluate_taxobell;candle-backend

pub use taxobell_encoder::train_taxobell;candle-backend

pub use taxobell_encoder::Mlp;candle-backend

pub use taxobell_encoder::TaxoBellEncoder;candle-backend

pub use taxobell_encoder::TaxoBellEvalResult;candle-backend

pub use taxobell_encoder::TaxoBellTrainingConfig;candle-backend

pub use taxobell_encoder::TrainingSnapshot;candle-backend

pub use el::compose_roles;

pub use el::disjointness_loss;

pub use el::el_inclusion_loss;

pub use el::existential_box;

pub use el::intersection_nonempty_loss;

pub use el::translate;

pub use el_training::evaluate_subsumption;rand

pub use el_training::train_el_embeddings;rand

pub use el_training::Axiom;rand

pub use el_training::ElTrainingConfig;rand

pub use el_training::ElTrainingResult;rand

pub use el_training::Ontology;rand

pub use fuzzy::fuzzy_negation;

pub use fuzzy::tconorm_lukasiewicz;

pub use fuzzy::tconorm_max;

pub use fuzzy::tconorm_probabilistic;

pub use fuzzy::tnorm_lukasiewicz;

pub use fuzzy::tnorm_min;

pub use fuzzy::tnorm_product;

pub use fuzzy::TConorm;

pub use fuzzy::TNorm;

pub use octagon::OctagonError;

pub use utils::bessel_log_volume;

pub use utils::bessel_side_length;

pub use utils::gumbel_lse_max;

pub use utils::gumbel_lse_min;

pub use utils::gumbel_membership_prob;

pub use utils::log_space_volume;

pub use utils::map_gumbel_to_bounds;

pub use utils::sample_gumbel;

pub use utils::softplus;

pub use utils::stable_logsumexp;

pub use utils::stable_sigmoid;

pub use utils::EULER_GAMMA;

pub use utils::MAX_TEMPERATURE;

pub use utils::MIN_TEMPERATURE;

Modules

box_trait

Core Box trait: containment probability, overlap, volume, and intersection. Core trait for box embeddings.

candle_backendcandle-backend

Candle backend: CandleBox, CandleGumbelBox with GPU acceleration.

cone

Cone embeddings: angular containment on the unit sphere, with negation support. Error types for cone embeddings.

dataset

Knowledge graph dataset loading (WN18RR, FB15k-237, YAGO3-10, and similar formats). Utilities for loading and parsing knowledge graph datasets.

distance

Distance metrics: Query2Box distance scoring. Distance metrics for box embeddings.

el

EL++ ontology embedding primitives (Box2EL / TransBox). EL++ ontology embedding primitives.

el_trainingrand

EL++ ontology embedding training: axiom parsing, training loop, evaluation. End-to-end EL++ ontology embedding training.

fuzzy

Fuzzy set-theoretic operators: t-norms, t-conorms, and negation (FuzzQE). Fuzzy set-theoretic operators: t-norms, t-conorms, and negation.

gaussian

Diagonal Gaussian box embeddings for taxonomy expansion (TaxoBell). Diagonal Gaussian box embeddings for taxonomy expansion.

gumbel

GumbelBox trait: probabilistic boxes with Gumbel-distributed coordinates. Gumbel box embeddings for probabilistic containment.

hyperbolicndarray-backend

Poincare ball embeddings for tree-like hierarchical structures.

ndarray_backendndarray-backend

Ndarray backend: NdarrayBox, NdarrayGumbelBox, optimizer, and learning rate scheduler.

octagon

Octagon embeddings: axis-aligned polytopes with diagonal constraints (IJCAI 2024). Error types for octagon embeddings.

optimizer

AMSGrad optimizer state and learning rate utilities. Optimizer implementations for box embeddings.

sheaf

Sheaf neural networks: algebraic consistency enforcement on graphs.

taxobell

TaxoBell combined training loss for taxonomy expansion. TaxoBell combined training loss for taxonomy expansion.

taxobell_encodercandle-backend

TaxoBell MLP encoder and training loop with candle autograd.

taxonomy

Taxonomy dataset loading for the TaxoBell format (.terms / .taxo / dic.json). Taxonomy dataset loading for the TaxoBell format.

trainable

Learnable box and cone representations with gradient-compatible parameters. Trainable geometric representations with learnable parameters.

trainer

Training loop utilities: negative sampling, loss kernels, link prediction evaluation. Training utilities for box embeddings: negative sampling, loss kernels, and evaluation.

training

Evaluation and diagnostics: rank metrics, calibration, gradient flow, quality analysis. Rank-based evaluation metrics for link prediction and knowledge graph tasks.

utils

Numerical stability: log-space volume, stable sigmoid, Gumbel operations. Numerical stability utilities for box embeddings.