Upload folder using huggingface_hub

README.md

@@ -0,0 +1,52 @@
+---
+datasets:
+- jgalego/knot2vec-diagrams
+library_name: pytorch
+license: mit
+model_name: knot2vec
+pipeline_tag: feature-extraction
+tags:
+- knot-theory
+- embeddings
+- contrastive-learning
+- weird2vec
+---
+
+# knot2vec
+
+Embeddings for knot diagrams. Two diagrams of the same knot, however tangled, should land close together; diagrams of different knots should land apart. Part of Weird2Vec, embedding models for data nobody embeds.
+
+> [!NOTE]
+> **What is a knot diagram?** A knot is a closed loop in space. Drawn on paper it becomes a diagram: a curve with crossings, each marked over or under. The same knot has infinitely many diagrams, related by Reidemeister moves. Telling whether two diagrams show the same knot is hard; this model learns a fast, approximate answer.
+
+## 🚀 Usage
+
+The repo holds the script that trained the model, so one command embeds a [PD code](https://knotinfo.org/descriptions/pd_notation.html) and names the nearest catalogued knots:
+
+```
+uv run https://huggingface.co/jgalego/knot2vec/resolve/main/knot2vec.py embed --pd "[[1,5,2,4],[3,1,4,6],[5,3,6,2]]"
+```
+
+It prints the five nearest of the 12,965 prime knots up to 13 crossings, guesses for signature, determinant and hyperbolic volume, and the 256-dimensional embedding.
+
+## 🧶 Data
+
+[jgalego/knot2vec-diagrams](https://huggingface.co/datasets/jgalego/knot2vec-diagrams): every prime knot up to 13 crossings in [KnotInfo](https://knotinfo.org/), with invariants, and diagrams of each knot scrambled by random Reidemeister moves in [SnapPy](https://snappy.computop.org/). 10% of the knots are held out of training entirely.
+
+## 🏋️ Training
+
+A diagram becomes its Gauss sequence: walk the knot and, at each crossing, record whether the strand passes over or under and the crossing's sign. Crossings are named by first visit and the walk starts at a random edge. A transformer encodes the sequence, and a contrastive loss pulls two scrambles of the same knot together against the rest of the batch. Small heads predict signature, determinant and volume.
+
+Not trained yet.
+
+## 📊 Results
+
+Each test diagram is a fresh scramble. The model names it by the nearest canonical KnotInfo diagram among all 12,965 knots. *Seen* knots were in training, as other diagrams; *unseen* knots never were.
+
+Not evaluated yet.
+
+## ⚠️ Limitations
+
+- Prime knots up to 13 crossings only, and only the chirality KnotInfo lists; a mirror image is a different input.
+- Nearest-neighbour naming is a guess, not a proof. Use SnapPy or KnotInfo to confirm.
+- Diagrams over 64 crossings are out of range.