mattbitzesty/pino-source-code

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

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