Document PETA Stage A/B results for fixed hyperbolic lift

README.md

@@ -10,83 +10,87 @@ tags:
   - clip
   - promptpar
   - hi-mapper
+  - vit
 pipeline_tag: feature-extraction
 ---
 
-# HI-Mapper (code only)
+# HI-Mapper — PromptPAR hyperbolic branch
 
-Hyperbolic hierarchy mapper for pedestrian attribute recognition (PromptPAR).
-This Hub repo contains **source code only** — **no trained weights**.
+Hyperbolic hierarchy mapper for PromptPAR, with the **fixed Euclidean → Lorentz lift**
+(running-norm scaler, stable distance, entailment cones). This repo includes
+**source code** plus the **two ViT weights PromptPAR needs to run**.
 
-HI-Mapper lifts Euclidean region / CLIP features into the Lorentz hyperboloid,
-builds a fixed depth-3 anatomical tree, and supervises it with entailment cones,
-sibling separation, and radius ordering (MERU / HyCoCLIP style). An optional
-attribute-grounded entailment term maps PETA-style attribute prefixes onto tree
-nodes. An optional HypDAE-style hyperbolic diffusion decoder is included.
+## Weights
 
-## Contents
+| File | Role | Size |
+|------|------|------|
+| `weights/ViT-L-14.pt` | OpenAI CLIP ViT-L/14 (PromptPAR backbone) | ~890 MB |
+| `weights/jx_vit_base_p16_224-80ecf9dd.pth` | ImageNet ViT-B/16 (MM-former blocks init) | ~331 MB |
+
+```bash
+hf download ZACK777/hi-mapper --local-dir ./hi-mapper
+# then point PromptPAR at:
+#   .cache/clip/ViT-L-14.pt  ← copy from weights/ViT-L-14.pt
+#   jx_vit_base_p16_224-80ecf9dd.pth ← copy from weights/
+```
+
+## Code
 
 ```
 hi_mapper/
-  __init__.py          # public exports
-  lorentz.py           # Lorentz manifold + EuclideanToLorentz lift
-  tree.py              # hierarchical / attribute entailment losses
-  hi_mapper.py         # DivHiMapper + PETA attr grouping
-  hyp_diffusion.py     # optional hyperbolic diffusion decoder
-  ARCHITECTURE.md      # detailed architecture notes
+  lorentz.py      # Lorentz manifold + EuclideanToLorentz
+  tree.py         # entailment / sibling / radius losses
+  hi_mapper.py    # DivHiMapper + PETA attr grouping
+  hyp_diffusion.py
 ```
 
-## Install
+## PETA results (new Euclidean→hyperbolic lift)
 
-```bash
-pip install torch
-# then copy hi_mapper/ into your project, or:
-git clone https://huggingface.co/ZACK777/hi-mapper
-```
+Dataset: **PETA**, PromptPAR flags: `--use_textprompt --use_div --use_vismask --use_GL --use_mm_former`.
+HI-Mapper default: `c=0.2`, `hi_mapper_w=0.1`, warmup 3 epochs, `--use_attr_hierarchy`.
 
-Requires PyTorch. No Hub weights are downloaded.
+### Stage A — 1-epoch do-no-harm gate
 
-## Quick start
+| Config | epoch-1 mA | Acc | F1 | notes |
+|--------|------------|-----|-----|-------|
+| **A_control** (no HI-Mapper) | 0.6102 | 0.4972 | 0.6412 | baseline |
+| A_default (HI-Mapper) | **0.6375** | 0.5059 | 0.6492 | +2.7 pts vs control |
+| A_attr | 0.6375 | 0.5059 | 0.6492 | same as default (attr on) |
+| A_r15 (`hyp_target_radius=1.5`) | **0.6406** | 0.4981 | 0.6407 | best epoch-1 |
+| A_prompt | 0.6345 | 0.5050 | 0.6483 | |
+| A_w030 (`hi_mapper_w=0.3`) | 0.6286 | 0.4894 | 0.6339 | |
 
-```python
-import torch
-from hi_mapper import DivHiMapper, build_attr_groups
-
-# region tokens: [B, 5, D] = global + 4 anatomical leaves
-B, D = 2, 768
-region_tokens = torch.randn(B, 5, D)
-cls = torch.randn(B, D)
-
-mapper = DivHiMapper(
-    feat_dim=D,
-    curvature=0.2,
-    target_radius=1.0,
-    attr_groups=None,  # or build_attr_groups(attr_names)
-)
-root, mid, leaves, hier_loss, prompt_loss, attr_loss = mapper(
-    region_tokens, cls
-)
-```
+All HI-Mapper configs beat the no-HI-Mapper control at epoch 1 (old broken lift was ~0.615 and *below* historical baseline).
+
+### Stage B — compressed 15-epoch (partial: epochs 1–3 before interrupt)
 
-## Geometry notes
+| Epoch | Control mA | HI-Mapper mA | HI-Mapper Acc | HI-Mapper F1 | `hi_mapper_loss` (epoch avg) |
+|-------|------------|--------------|---------------|--------------|------------------------------|
+| 1 | 0.6102 | **0.6175** | 0.5139 | 0.6578 | 1.720 |
+| 2 | 0.6337 | **0.6720** | 0.5288 | 0.6677 | 1.029 |
+| 3 | 0.6943 | **0.6997** | 0.5634 | 0.6957 | **0.187** |
 
-- `EuclideanToLorentz` uses a running-norm scaler (not LayerNorm) so relative
-  norms — and thus hyperbolic radii — stay meaningful.
-- Distance uses a numerically stable `asinh` form; Minkowski products run in
-  float64 intermediates.
-- Entailment uses half-aperture / exterior-angle cones (`K=0.1`).
+Key signal vs the old broken lift: hierarchical loss no longer floors at ~0.20 from epoch 1; it falls **1.72 → 0.19** by epoch 3 while mA stays ahead of the matched control.
 
-## Integration
+> Full 15-epoch Stage B and 100-epoch final runs were interrupted; re-launch to complete the table.
 
-Designed as a drop-in branch for PromptPAR / CLIP-based PAR models. See
-`hi_mapper/ARCHITECTURE.md` for the tree layout, losses, and optional decoder.
+### Reference (published PromptPAR, PETA)
 
-## Citation / context
+mA **88.76** / Acc **82.84** / F1 **89.18** (TCSVT 2024) — requires full 100-epoch cosine schedule.
 
-Built for hyperbolic hierarchical regularisation on top of PromptPAR-style
-region tokens. Related ideas: MERU, HyCoCLIP, HypDAE, Khrulkov et al. (δ-hyperbolicity).
+## Quick start
+
+```python
+import torch
+from hi_mapper import DivHiMapper
+
+mapper = DivHiMapper(feat_dim=768, curvature=0.2, target_radius=1.0)
+root, mid, leaves, hier_loss, prompt_loss, attr_loss = mapper(
+    torch.randn(2, 5, 768), torch.randn(2, 768)
+)
+```
 
 ## License
 
-Apache-2.0 (code). Upstream PromptPAR / CLIP licenses still apply if you use
-those backbones.
+Apache-2.0 for HI-Mapper code. CLIP / ViT checkpoints retain their original licenses
+(OpenAI CLIP; Google / timm ImageNet ViT-B/16).