README.md

---
title: Crystal Embedder
emoji: 🔮
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit
---

# Crystal-Embedder

Compute **Tri-Fusion physics embeddings** for crystal structures.

## What it does

This service takes a crystal structure in CIF format and returns a 2738-dimensional embedding vector that captures:

| Component | Dimensions | Description |
|-----------|------------|-------------|
| **Orb-v3** | 1792 | Force field features (PyTorch) |
| **l-MM** | 758 | Electronic structure features (TensorFlow/MEGNet) |
| **l-OFM** | 188 | Orbital field matrix features (TensorFlow/MEGNet) |
| **Total** | **2738** | Concatenated, L2-normalized |

## API

### `POST /embed`

Compute embedding for a CIF structure.

**Request:**
```json
{
  "cif": "data_Si\n_cell_length_a 5.43..."
}
```

**Response:**
```json
{
  "vector": [0.123, -0.456, ...],
  "dims": 2738
}
```

### `GET /health`

Health check endpoint.

**Response:**
```json
{
  "status": "healthy",
  "models_loaded": true,
  "vector_dims": 2738
}
```

## Example Usage

```python
import httpx

cif_content = open("structure.cif").read()

response = httpx.post(
    "https://hafnium49-crystal-embedder.hf.space/embed",
    json={"cif": cif_content},
    timeout=60
)

embedding = response.json()["vector"]
print(f"Embedding shape: {len(embedding)}")  # 2738
```

## Performance

- **Latency:** ~15 seconds per structure (CPU-only)
- **Memory:** ~8GB peak during inference
- **Cold start:** ~2 minutes (model loading)

## Local Development

```bash
# Build
docker build -t crystal-embedder .

# Run
docker run -p 7860:7860 crystal-embedder

# Test
curl http://localhost:7860/health
```

## Powered By

- [MatterVial](https://github.com/rogeriog/MatterVial) - Physics embeddings
- [pymatgen](https://pymatgen.org/) - Crystal structure parsing
- [FastAPI](https://fastapi.tiangolo.com/) - Web framework