Update README - Run 20251012_191456

README.md

@@ -0,0 +1,212 @@
+---
+language: en
+license: mit
+tags:
+- image-classification
+- imagenet
+- multi-scale
+- crystal-geometry
+- david
+datasets:
+- imagenet-1k
+metrics:
+- accuracy
+model-index:
+- name: David-partial_shared-hierarchical_tree
+  results:
+  - task:
+      type: image-classification
+    dataset:
+      name: ImageNet-1K
+      type: imagenet-1k
+    metrics:
+    - type: accuracy
+      value: 66.69
+---
+
+# David: Multi-Scale Crystal Classifier
+
+**David** is a multi-scale deep learning classifier that uses crystal geometry (pentachora/4-simplexes) 
+as class prototypes with role-weighted similarity computation (Rose Loss).
+
+## Model Details
+
+### Architecture
+- **Preset**: balanced
+- **Sharing Mode**: partial_shared
+- **Fusion Mode**: hierarchical_tree
+- **Scales**: [256, 512, 768, 1024]
+- **Feature Dim**: 512
+- **Parameters**: 8,758,271
+
+### Training Configuration
+- **Dataset**: AbstractPhil/imagenet-clip-features-orderly
+- **Model Variant**: ['clip_vit_b32', 'clip_vit_laion_b32']
+- **Epochs**: 10
+- **Batch Size**: 1024
+- **Learning Rate**: 0.01
+- **Rose Loss Weight**: 0.2 → 0.8
+- **Cayley Loss**: True
+
+## Performance
+
+### Best Results
+- **Validation Accuracy**: 66.69%
+- **Best Epoch**: 0
+- **Final Train Accuracy**: 54.53%
+
+### Per-Scale Performance
+- **Scale 256**: 66.69%
+
+
+## Usage
+
+### Quick Model Lookup
+
+**Check `MODELS_INDEX.json` in the repo root** - it lists all trained models sorted by accuracy with links to weights and configs.
+
+### Repository Structure
+
+```
+AbstractPhil/david-shared-space/
+├── MODELS_INDEX.json                # 📊 Master index of all models (sorted by accuracy)
+├── README.md                         # This file
+├── best_model.json                   # Latest best model info
+├── weights/
+│   └── david_balanced/
+│       └── 20251012_191456/
+│           ├── MODEL_SUMMARY.txt     # 🎯 Human-readable performance summary
+│           ├── training_history.json # 📈 Epoch-by-epoch training curve
+│           ├── best_model_acc66.69.safetensors  # ⭐ Accuracy in filename!
+│           ├── best_model_acc66.69_metadata.json
+│           ├── final_model.safetensors
+│           ├── checkpoint_epoch_X_accYY.YY.safetensors
+│           ├── david_config.json
+│           └── train_config.json
+└── runs/
+    └── david_balanced/
+        └── 20251012_191456/
+            └── events.out.tfevents.* # TensorBoard logs
+```
+
+### Loading the Model
+
+```python
+from geovocab2.train.model.core.david import David, DavidArchitectureConfig
+from huggingface_hub import hf_hub_download
+
+# Browse available models in MODELS_INDEX.json first!
+
+# Specify model variant and run
+model_name = "david_balanced"
+run_id = "20251012_191456"
+accuracy = "66.69"  # From MODELS_INDEX.json
+
+# Download config
+config_path = hf_hub_download(
+    repo_id="AbstractPhil/david-shared-space", 
+    filename=f"weights/{model_name}/{run_id}/david_config.json"
+)
+config = DavidArchitectureConfig.from_json(config_path)
+
+# Download weights (accuracy in filename!)
+weights_path = hf_hub_download(
+    repo_id="AbstractPhil/david-shared-space", 
+    filename=f"weights/{model_name}/{run_id}/best_model_acc{accuracy}.safetensors"
+)
+
+# Download training history (optional - see full training curve)
+history_path = hf_hub_download(
+    repo_id="AbstractPhil/david-shared-space", 
+    filename=f"weights/{model_name}/{run_id}/training_history.json"
+)
+
+# Load model
+from safetensors.torch import load_file
+david = David.from_config(config)
+david.load_state_dict(load_file(weights_path))
+david.eval()
+```
+
+### Inference
+
+```python
+import torch
+import torch.nn.functional as F
+
+# Assuming you have CLIP features (512-dim for ViT-B/16)
+features = get_clip_features(image)  # [1, 512]
+
+# Load anchors
+anchors_dict = torch.load("anchors.pth")
+
+# Forward pass
+with torch.no_grad():
+    logits, _ = david(features, anchors_dict)
+    predictions = logits.argmax(dim=-1)
+```
+
+## Architecture Overview
+
+### Multi-Scale Processing
+David processes inputs at multiple scales (256, 512, 768, 1024), 
+allowing it to capture both coarse and fine-grained features.
+
+### Shared Representation Space
+This variation shares multiple versions of clip-vit models in the same representation space.
+
+### Crystal Geometry
+Each class is represented by a pentachoron (4-simplex) in embedding space with 5 vertices:
+- **Anchor**: Primary class representative
+- **Need**: Complementary direction
+- **Relation**: Contextual alignment
+- **Purpose**: Functional direction
+- **Observer**: Meta-perspective
+
+### Rose Loss
+Similarity computation uses role-weighted cosine similarities:
+```
+score = w_anchor * sim(z, anchor) + w_need * sim(z, need) + ...
+```
+
+### Fusion Strategy
+**hierarchical_tree**: Intelligently combines predictions from multiple scales.
+
+## Training Details
+
+### Loss Components
+- **Cross-Entropy**: Standard classification loss
+- **Rose Loss**: Pentachora role-weighted margin loss (weight: 0.2→0.8)
+- **Cayley Loss**: Geometric regularization (enabled)
+
+### Optimization
+- **Optimizer**: AdamW
+- **Weight Decay**: 1e-05
+- **Scheduler**: cosine_restarts
+- **Gradient Clip**: 10.0
+- **Mixed Precision**: False
+
+## Citation
+
+```bibtex
+@software{david_classifier_2025,
+  title = {David: Multi-Scale Crystal Classifier},
+  author = {AbstractPhil},
+  year = {2025},
+  url = {https://huggingface.co/AbstractPhil/david-shared-space},
+  note = {Run ID: 20251012_191456}
+}
+```
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+Built with crystal lattice geometry and multi-scale deep learning.
+Special thanks to Claude (Anthropic) for debugging assistance.
+
+---
+
+*Generated on 2025-10-12 19:18:12*