Overview

Event2Vector is a framework for learning representations of discrete event sequences. Inspired by the geometric structures found in neural representations, this model uses a simple, additive recurrent structure to create composable and interpretable embeddings.

Key Concepts

• Linear Additive Hypothesis: The core idea behind Event2Vector is that the representation of an event sequence can be modeled as the vector sum of the embeddings of its individual events. This allows for intuitive vector arithmetic, enabling the composition and decomposition of event trajectories.
• Euclidean and Hyperbolic Models: Event2Vector is offered in two geometric variants:
  • Euclidean model: Uses standard vector addition, providing a straightforward, flat geometry for event trajectories.
  • Hyperbolic model: Employs Möbius addition, which is better suited for hierarchical data structures, as it can embed tree-like patterns with less distortion.
• Estimator API: A scikit-learn style Event2Vec estimator exposes fit, fit_transform, and transform, enabling drop-in use inside pipelines while keeping the compositional recurrent loss from the paper.
• Padded batching: Optional padding allows entire minibatches of variable-length sequences to be processed in parallel, significantly accelerating training on large corpora without changing model behavior.

For more details, check Sulc A., Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences

Example Applications

• Substack Post: Geometry of Groceries https://sulcantonin.substack.com/p/the-geometry-of-groceries
• Substack Post: The Geometry of Language Families https://sulcantonin.substack.com/p/the-geometry-of-language-families

Installation

Install the package directly from PyPI:

pip install event2vector

Or install from source:

git clone https://github.com/sulcantonin/event2vec_public.git
cd event2vec_public
pip install .

Estimator API

The Event2Vec class mirrors scikit-learn transformers so it can slot into existing NLP pipelines:

from event2vector import Event2Vec

model = Event2Vec(
    num_event_types=len(vocab),
    geometry="euclidean",
    embedding_dim=128,
    pad_sequences=True,
    num_epochs=50,
)
model.fit(train_sequences, verbose=True)
train_embeddings = model.transform(train_sequences) 

Hyperbolic variant (training + using trained weights):

from event2vector import Event2Vec, HyperbolicUtils
import torch

hyp_model = Event2Vec(
    num_event_types=len(vocab),
    geometry="hyperbolic",
    curvature=1.0,
    embedding_dim=128,
    pad_sequences=True,
    num_epochs=50,
)
hyp_model.fit(train_sequences, verbose=True)

# Use the trained weights: encode sequences and query the decoder
seq_embeddings = hyp_model.transform(test_sequences, as_numpy=False)
torch_model = hyp_model.model

# Hyperbolic addition + distance between two datapoints (Poincaré ball)
u = seq_embeddings[0]
v = seq_embeddings[1]
uv_added = HyperbolicUtils.mobius_add(u, v, hyp_model.curvature)
uv_dist = HyperbolicUtils.poincare_dist_sq(u, v, hyp_model.curvature).sqrt()

Key methods:

• fit: optimizes embeddings with the additive loss from the paper.
• fit_transform: convenience helper returning the encoded sequences after fitting.
• transform: freezes weights and encodes arbitrary sequences, optionally returning PyTorch tensors for downstream models.
• most_similar: gensim-style nearest-neighbor lookup over learned event embeddings using tokens or full sequences as queries.
• pad_sequences=True: enables fully vectorized batches with masking for substantial throughput gains on large corpora.

Device control: set use_gpu=False to force CPU even if CUDA/MPS is present, or pass an explicit device (e.g., "cuda:0" or "cpu"). On Apple Silicon the rotation geometry defaults to the CPU, because MPS has no matrix_exp kernel and the CPU is faster for it; pass device="mps" to override.

Geometries (v0.2)

Beyond euclidean and hyperbolic, the estimator exposes the paper's pilot geometries as first-class geometry= backbones, each the natural home of a structure the additive endpoint cannot carry. They share the same estimator and a generic gyrogroup/Lie-group left-cancellation reconstruction loss.

from event2vector import Event2Vec

# one unified curvature dial: kappa<0 hyperbolic, 0 Euclidean, >0 spherical
model = Event2Vec(num_event_types=len(vocab), geometry="stereographic", kappa=-1.0)

# non-commutative orientation (SO(3))
model = Event2Vec(num_event_types=len(vocab), geometry="rotation", rotation_n=3)

# product of a hyperbolic and a spherical factor
model = Event2Vec(num_event_types=len(vocab), geometry="product", product_kappas=(-1.0, 1.0))

Reproduce the curvature sweep on a real knowledge graph (auto-downloads WN18RR):

python3 -m scripts.run_kg_curvature   # next-relation accuracy vs kappa

Brown Corpus POS tagging example

After installation, you can try to run Brown Part-of-Speech tagging example from the paper.

python3 -m examples.prepare_brown_data
python3 -m examples.train_brown_data
python3 -m examples.visualize_brown_corpus

Minimal example script

The repository includes a runnable minimal example that trains a tiny model end-to-end and prints example outputs (loss, embeddings, and nearest tokens). Run it from the repo root:

python3 examples/minimal_example.py

To try a hyperbolic run, open examples/minimal_example.py and set geometry="hyperbolic" in the Event2Vec constructor, then rerun the script.

Reproducing the paper experiments

The journal experiments are built around domains with exact ground truth for the additive structure, so interpretability is measured rather than visualized:

# Physics (nuclear decay) + Math (group sequences): exact-ground-truth centerpiece
python3 -m scripts.run_centerpiece --seeds 5 --epochs 20 --out results/centerpiece

# Synthetic life-path workbench (order-sensitivity-vs-curvature, additivity decay)
python3 -m scripts.run_lifepath --seeds 5 --out results/lifepath

Datasets live in event2vector/datasets/ and all return a uniform record (sequences, processed_sequences, vocab, labels, graph):

• make_decay(): radioactive decay chains; each event is an exact (ΔZ, ΔN) so additivity coincides with conservation laws (metric: operator_recovery).
• make_group(name): Cayley-graph walks on abelian/non-abelian groups; the additive endpoint provably equals the abelianization (metric: abelianization_gap).
• make_lifepath(), load_brown(): controlled synthetic + real (POS) workbench.
• load_gdelt(), load_sec_8k(), load_synthea(), ...: real-world event streams (require a public data download; see each loader's docstring).

Metrics (event2vector.metrics) and the seeded harness (event2vector.eval) are reusable across datasets; baselines (GRU/LSTM/Transformer/Word2Vec) are in event2vector.baselines. Run the test suite with pytest tests/ -q.

References

For citations please use following Bibtex.

@article{sulc2025event2vec,
  title={Event2Vec: A Geometric Approach to Learning Composable Representations of Event Sequences},
  author={Sulc, Antonin},
  journal={arXiv preprint arXiv:2509.12188},
  year={2025}
}