HI-Mapper — PromptPAR hyperbolic branch

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.

Weights

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

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/
  lorentz.py      # Lorentz manifold + EuclideanToLorentz
  tree.py         # entailment / sibling / radius losses
  hi_mapper.py    # DivHiMapper + PETA attr grouping
  hyp_diffusion.py

PETA results (new Euclidean→hyperbolic lift)

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.

Stage A — 1-epoch do-no-harm gate

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

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)

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

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.

Full 15-epoch Stage B and 100-epoch final runs were interrupted; re-launch to complete the table.

Reference (published PromptPAR, PETA)

mA 88.76 / Acc 82.84 / F1 89.18 (TCSVT 2024) — requires full 100-epoch cosine schedule.

Quick start

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 for HI-Mapper code. CLIP / ViT checkpoints retain their original licenses (OpenAI CLIP; Google / timm ImageNet ViT-B/16).