---
license: apache-2.0
library_name: pytorch
tags:
  - hyperbolic
  - lorentz
  - hierarchy
  - entailment
  - pedestrian-attribute-recognition
  - clip
  - promptpar
  - hi-mapper
  - vit
pipeline_tag: feature-extraction
---

# 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 |

```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/
  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

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