README.md

---
title: PINO
emoji: 🧪
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit
---

# PINO — Physics-Informed Neural Olfaction

End-to-end fragrance intelligence: from molecular structure and Dortmund-UNIFAC thermodynamics to a multi-task transformer that predicts time-resolved odor trajectories.

## What it does

PINO combines a first-principles evaporation engine with a Physics-Informed Mixture Transformer (PIMT):

1. **Thermodynamic simulation** — Dortmund-Modified UNIFAC activity coefficients, stiff ODE evaporation, and headspace concentration profiles.
2. **Empirical bootstrap dataset** — 5,600+ real-world records (single-molecule controls + multi-component blends), all cut with a commercial 15% concentrate / 85% ethanol solvent envelope and padded to a fixed 49-step temporal grid.
3. **Multi-task transformer** — predicts objective odor trajectories, seasonality, gender/wearability profiles, and continuous alignment to the Principal Odor Map using an adaptive loss balancer.
4. **Formula generation** — CMA-ES-based inverse-design composer that evolves blends against a sensory brief while respecting IFRA limits.

## Quick start

```bash
# Install
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Run tests (112 passed, 4 skipped)
python -m pytest tests/ -q

# Train the two-arm representation A/B locally (Morgan vs genuine OpenPOM)
python src/pino/train.py --structural-source morgan     --epochs 6 --checkpoint-name pimt_ab_morgan.pt
python src/pino/train.py --structural-source openpom_256 --epochs 6 --checkpoint-name pimt_ab_openpom.pt

# Single preregistered readout on the frozen benchmarks (once per arm)
python scripts/evaluate_frozen_benchmarks.py --checkpoint models/pimt_ab_openpom.pt \
  --structural-source openpom_256 --arm-label openpom_256 --output artifacts/frozen_eval_openpom_256.json

# Paper artifacts: canonical data macros + figures (from on-disk artifacts only)
python scripts/export_paper_data.py        # -> artifacts/paper_data.yaml
python scripts/generate_paper_figures.py   # -> figures/*.pdf
```

GPU training runs on Hugging Face Jobs against the published
`mattbitzesty/pino-source-code` model repo (`scripts/hf_gpu_ab_job.py`,
`scripts/hf_stats_job.py`); the legacy substantivity-GBM path is
`scripts/pimt_v9_train_publish.py`.

## Repository layout

| Path | Purpose |
|------|---------|
| `src/pino/thermo/` | VLE, evaporation, IFRA, natural-oil profiles, OAV semantics |
| `src/pino/pimt_model.py` | `FragranceTrajectoryDataset` and `PhysicsInformedMixtureTransformer` |
| `src/pino/train.py` | Training loop with `AdaptiveLossBalancer` and molecule-disjoint split |
| `src/pino/heads.py` | PIMT output heads: objective, subjective, continuous alignment |
| `src/pino/optimizer.py` / `cli.py` | Generative inverse-design composer |
| `scripts/` | Dataset generation, HF job entrypoint, diagnostic scripts |
| `data/` | Registry, empirical dataset, literature formulas, Pyrfume annotations |
| `tests/` | Pytest suite for the thermodynamic engine |

## Key design decisions

- **Natural oils are expanded** into pure constituent CASes before VLE so the engine runs real Dortmund-UNIFAC instead of falling back to Raoult's law.
- **All formulas are treated as 15% perfume oil concentrate + 85% ethanol**, mirroring real commercial fragrance products.
- **Molecule-disjoint train/validation split** prevents data leakage: if a molecule appears in a training formula, it never appears in validation.
- **Pure single-molecule controls follow the same molecule-disjoint split** as blends, so held-out compounds are not reintroduced through anchor records.
- **Adaptive loss balancing** (4 tasks: objective MSE, seasonality, wearability, continuous alignment) removes hand-tuned loss coefficients.
- **Continuous alignment head** replaces the legacy InfoNCE contrastive head with dense cosine similarity on the Principal Odor Map.

## Open design decisions

- **Representation (RESOLVED by ablation, 2026-07-17):** genuine 256-dim OpenPOM v1.0.0 beats the 138-dim Morgan fallback on every frozen predictive task (substantivity, odor-threshold, descriptor). See `artifacts/representation_ablation/`. Training now supports both via `--structural-source morgan|openpom_256` (input dim 151 vs 269); a two-arm A/B trains each once and evaluates on the frozen benchmarks head-to-head.
- **Objective target space (OPEN):** the curated 138-dim Pyrfume single-label basis vs the full molequles multi-tag vocabulary (575 tags at ≥10 occurrences, ~10 tags/CAS, mined from Arctander/Goodscents/TGSC monograph text). The richer space may be more insightful but changes the objective head, loss, and metrics. The 575-dim multi-hot target matrix is built (`data/molequles_tag_matrix.json`) and held as an ablation arm; attribution is cleaner if it lands after the representation A/B is read out.
- **Prospective formula benchmark:** 40 in-silico preregistered formulas from a 51-material hobbyist palette (option held open for a community physical-compounding arm). Intended family-profile labels are sequestered (`labels.sequestered.json`, `access=evaluation_only`) and forbidden in training/model selection.

## Representation A/B (two-arm, single readout)

Trained and evaluated **once per arm** on the frozen benchmarks. Authoritative
run: **20 epochs on T4 GPU** against the expanded **20-triplet** benchmark.
Results live in `mattbitzesty/pino-pimt-representation-ab` (public model repo).

| Metric | Morgan (151-d) | Genuine OpenPOM (269-d) |
|---|---|---|
| Final validation total loss (best epoch) | 0.3959 | **0.3600** |
| Substitution triplets (n=20, chance=0.5) | 0.30 | **0.45** |
| Prospective family cosine (n=40) | 0.5378 | **0.6121** |

- **Genuine OpenPOM ahead on all three metrics.** Largest margin on prospective
  family-profile agreement (+0.074), most pronounced in citrus-cologne (0.56 vs
  0.26, where Morgan collapses). Honest caveat: both arms are below chance on
  triplets (0.30/0.45) — a reported negative, not a win.
- **Model-free ablation** (`artifacts/representation_ablation/`): OpenPOM beats
  Morgan on every frozen predictive task (5-fold paired bootstrap CIs) — the
  statistically strongest case.
- **CPU run (6 epochs, n=8)** was directional only and is superseded by the GPU run.
- Triplet benchmark expanded 8 → 20 by mining `material_profiles` (molequles) for
  trade-name → SMILES in `scripts/build_substitution_triplets.py`, resolving
  proprietary trade materials (Isobutavan, Canthoxal, Neofolione, Indocolore,
  Centifolether, Romandolide, …). All 12 new triplets carry authoritative
  Fraterworks preference provenance + verified structural discordance.

## Paper package

The paper build pulls facts from a single canonical source and renders figures
from on-disk artifacts — no retraining, no HF calls:

- `scripts/export_paper_data.py` → `artifacts/paper_data.yaml`: 49 lowerCamel
  `data_macros` for the autopaper pipeline (builder prefixes `D`, digits→words;
  e.g. `pomThreshRho` → `\DPomThreshRho`). Sourced verbatim from the frozen
  ablation, the v10_line_drawn substantivity GBM, and the A/B frozen readout,
  plus dataset curation stats and honest negatives.
- `scripts/generate_paper_figures.py` → `figures/*.pdf`: (a) ablation grouped
  bars + 95% CI, (b) UMAP of genuine OpenPOM embeddings by odor family,
  (c) objective-head trajectory pred-vs-target (sparsity annotated).

## Training-readiness gate

Training is gated by `scripts/freeze_representation_validation.py`, which inspects on-disk artifacts and reports `READY_FOR_TRAINING` only when all five checks pass: genuine-POM asset present, representation ablation complete, ≥1 discordant substitution triplet admitted, 30–50 prospective formulas frozen, and prospective labels sequestered. Current status: `artifacts/training_readiness.json`.

## Telemetry to verify on first HF training run

- **Step 1:** `AdaptiveLossBalancer` weights should be uniform (~0.25 each).
- **Step 10:** weights should shift dynamically as tasks progress at different rates.
- **Alignment loss:** starts near 1.0 and trends downward as the backbone organizes odor descriptors.
- **Validation loss:** reflects formulas whose active molecules are absent from training; mixed-boundary formulas are excluded to preserve isolation.

## Relation to the Principal Odor Map (Lee et al., Science 2023)

PINO does not compete with Google's Principal Odor Map — it **builds on it** and
extends it to a harder problem:

| | POM (Lee et al. 2023) | PINO |
|---|---|---|
| Object | single molecule | multi-component blend |
| Output | static odor descriptors | time-resolved odor trajectory (49 steps) |
| Physics | none | Dortmund-UNIFAC evaporation |
| Validation | human panel, 400 novel odorants | frozen in-silico benchmarks |
| Human validation | yes (n=15 panel) | not yet (future work) |
| Formulation / IFRA | no | yes |

POM validated odor *description* for single molecules against a trained human
panel. PINO consumes that map as an input representation (the OpenPOM arm) and
shows, in a controlled two-arm A/B plus a model-free ablation, that the perceptual
representation is also the right foundation for **blend-trajectory** modeling —
a task POM did not address. The controlled comparison (paired bootstrap CIs +
identical-corpus two-arm training) is methodologically tighter than POM's
transfer-study baselines. The acknowledged gap vs POM is human-panel prospective
validation; PINO's prospective eval is in-silico against sequestered intended
profiles.

## License

MIT — see `LICENSE`.