Skip to content

Notebooks and Tutorials

The repository ships a maintained notebook set that mirrors the main code paths. These notebooks are tutorial-style companions to the documentation, not separate experimental branches.

How to Use Them

  • read the corresponding site page first if you want the conceptual overview
  • open the notebook locally in Jupyter or your IDE
  • treat the notebook as the interactive version of the same maintained workflow

Start Jupyter from the repo root with:

jupyter lab

Notebook Map

Notebook Focus When to use it Link
01_prepare_data.ipynb dataset construction and split logic when you want to inspect the processed CSV pipeline interactively Open on GitHub
02_train.ipynb TGNN-Solv training, optional Stage 0 pretraining, and encoder/config variants when you want to step through the curriculum, --pretrain, and tuned TGNN follow-up configs Open on GitHub
03_inference.ipynb single-point inference, temperature scan, and AD/OOD checks when you want to inspect one system manually Open on GitHub
04_evaluation.ipynb metrics, uncertainty, calibration, and error analysis when you want richer post-hoc analysis than the quick CLI Open on GitHub
05_baselines.ipynb DirectGNN, descriptor baselines, RF, and external baselines when you are comparing TGNN against non-physics alternatives Open on GitHub
06_ablations.ipynb ablation reading and architectural comparisons when you want to isolate which component is helping Open on GitHub
07_temperature.ipynb temperature dependence, ideal solubility, and van't Hoff analysis when you want to inspect thermal trends rather than aggregate metrics Open on GitHub
08_optuna_tuning.ipynb Optuna-based hyperparameter tuning when you want interactive tuning for TGNN, GPS TGNN, descriptor-augmented TGNN, and DirectGNN families Open on GitHub

How They Map to the Site

Site page Notebook companion
Data Preparation 01_prepare_data.ipynb
Training 02_train.ipynb
Evaluation & Inference 03_inference.ipynb, 04_evaluation.ipynb
Baselines 05_baselines.ipynb
Experiments & Benchmarks 06_ablations.ipynb, 07_temperature.ipynb, 08_optuna_tuning.ipynb

For a first pass through the project:

  1. 01_prepare_data.ipynb
  2. 02_train.ipynb
  3. 03_inference.ipynb
  4. 04_evaluation.ipynb

Then move on to the experiment notebooks depending on your question:

  • architecture choices: 06_ablations.ipynb
  • temperature behavior: 07_temperature.ipynb
  • tuning: 08_optuna_tuning.ipynb

Important Scope Note

The notebooks are kept aligned with the maintained implementation, but the reproducible default remains the grouped CLI surface under:

  • scripts/data/
  • scripts/training/
  • scripts/evaluation/
  • scripts/experiments/

Use notebooks for inspection and explanation, and the CLIs for reproducible batch runs.

Current alignment notes:

  • 02_train.ipynb now covers both notebook-driven Stage 0 and the maintained CLI path through scripts/training/train.py --pretrain / scripts/training/train_with_pretrain.py
  • 08_optuna_tuning.ipynb mirrors the current OptunaTuner model aliases, including GPS and descriptor-augmented TGNN variants

Current scope note:

  • the formal benchmark-adapter API
  • checksum-based benchmark-release freezing
  • the thermodynamic stress suite

are currently CLI-first rather than notebook-first surfaces.