docs.rs failed to build subsume-0.17.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Visit the last successful build: subsume-0.7.2

subsume

Region embeddings for entailment and set containment.

subsume represents concepts as geometric regions. A general concept contains the regions for its more specific concepts, so containment becomes the scoring operation for hierarchy, ontology, and set-query tasks.

Box embedding concepts

(a) Containment: nested boxes encode is-a relationships. (b) Gumbel soft boundary: temperature controls membership sharpness.

Install

[dependencies]
subsume = "0.17.1"
ndarray = "0.16"

The default features include the ndarray backend and knowledge-graph dataset helpers. GPU training examples use Burn through burn-ndarray or burn-wgpu.

Usage

use ndarray::array;
use subsume::{ndarray_backend::NdarrayBox, HyperBox};

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

// B is the specific concept inside A.
let hypothesis = NdarrayBox::new(array![0.2, 0.2, 0.2], array![0.8, 0.8, 0.8], 1.0)?;

let p = premise.containment_prob(&hypothesis)?;
assert!(p > 0.9);

Triple convention: the head box contains the tail box. For datasets where triples are (child, hypernym, parent), pass reverse=True to the Python loader or reverse the triples before training.

Training

use std::path::Path;
use subsume::{dataset::load_dataset, BoxEmbeddingTrainer, TrainingConfig};

let dataset = load_dataset(Path::new("data/wn18rr"))?;
let interned = dataset.into_interned();
let train: Vec<_> = interned.train.iter().map(|t| (t.head, t.relation, t.tail)).collect();

let config = TrainingConfig { learning_rate: 0.01, epochs: 50, ..Default::default() };
let mut trainer = BoxEmbeddingTrainer::new(config, 32);
let result = trainer.fit(&train, None, None)?;
println!("MRR: {:.3}", result.final_results.mrr);

Python bindings are published as subsumer:

pip install subsumer

See subsume-python/README.md for Python examples.

Choosing A Geometry

Task	Start with	Notes
Containment hierarchy	`NdarrayBox` or `NdarrayGumbelBox`	Boxes have volume and intersection; Gumbel boxes give dense gradients
Logical queries with negation	Cone or subspace	Cones and subspaces support complement-like operations
Taxonomy expansion with uncertainty	Gaussian boxes	KL gives asymmetric containment; Bhattacharyya gives overlap
EL++ ontology completion	`el`, `transbox`	Uses axiom losses rather than plain triple scoring
Tree-like hierarchies in low dimension	Hyperbolic intervals or balls	Useful when depth is the main structure

The full geometry table is in docs/geometries.md. Scores are monotone within a geometry but not calibrated across geometries; see cargo run --example region_generic.

Why Regions

Point embeddings such as TransE, RotatE, and ComplEx work well for ordinary link prediction. Regions are useful when the task needs structure that points do not have:

Need	Point embeddings	Region embeddings
Containment	No interior	Box nesting
Generality	No volume	Larger region = broader concept
Intersection	No set operation	Box intersection
Negation	No complement	Cone or subspace complement
Uncertainty	Extra model-specific machinery	Region size or Gaussian variance

For background, see Why Regions, Not Points and docs/SUBSUMPTION_HISTORY.md.

Examples

cargo run --example containment_hierarchy
cargo run --example box_training
cargo run --example el_training

The full example map is in examples/README.md.

Benchmarks

EL++ ontology completion results and reproduction commands are in docs/benchmarks.md. The current strongest results are on NF3 existential restrictions, with MRR 0.21-0.37 across GALEN, GO, and Anatomy in the recorded single-run Burn benchmark.

subsume 0.17.1