| ---
|
| license: cc-by-nc-4.0
|
| library_name: pytorch
|
| tags:
|
| - chemistry
|
| - molecular-representation
|
| - graph-transformer
|
| - grasp
|
| - ablation
|
| ---
|
|
|
| # GRASP-A3
|
|
|
| The completed Step 2 encoder from the full-size A3 experiment: **93,089,496 encoder
|
| parameters**, 12 layers and width 768. This is the exact checkpoint evaluated in
|
| the A3 OpenADMET comparison, converted to safetensors without changing tensors.
|
| The repository includes an installable loader with A3’s factorized atom pipeline, model configuration, provenance, validation and evaluation tables.
|
|
|
| ## Test in Google Colab
|
|
|
| 1. [Download the quickstart notebook](https://huggingface.co/caithmac/GRASP-A3/resolve/main/GRASP_A3_Colab_Quickstart.ipynb?download=true).
|
| 2. Open [Google Colab](https://colab.research.google.com/) and upload it using
|
| **File → Upload notebook**.
|
| 3. Use a fresh Python runtime. A GPU is optional for the small smoke test; select
|
| one in **Runtime → Change runtime type** if you want GPU inference.
|
| 4. Run the cells in order. No Hugging Face login is required for this public model.
|
|
|
| The notebook resolves a single immutable Hub revision, verifies the audited loader
|
| and safetensors hashes, loads A3 and saves example embeddings. It also provides an
|
| optional own-CSV fine-tuning template. Only run that template after supplying
|
| separate train/validation CSVs; the default smoke test does not start benchmark training.
|
| The notebook stops if the published weights/loader differ from the audited release.
|
|
|
| The bundled loader is required: older GRASP notebooks that install an earlier
|
| loader must update their install cell before using A3. Restart a runtime if it has
|
| already imported an older `grasp` module. `AutoModel` is not the loading API for
|
| this release; use `GRASPEncoder` as shown below.
|
|
|
| ## Install and encode
|
|
|
| Use Python **3.10–3.13** and install the A3-compatible loader wheel:
|
|
|
| ```bash
|
| python -m pip install "https://huggingface.co/caithmac/GRASP-A3/resolve/main/grasp_molecular-0.1.2-py3-none-any.whl"
|
| ```
|
|
|
| Restart a notebook kernel if it already imported an older `grasp` package.
|
| The older A1/A2 loader does not support A3's factorized inputs.
|
|
|
| ```python
|
| from grasp import GRASPEncoder
|
|
|
| encoder = GRASPEncoder.from_pretrained("caithmac/GRASP-A3")
|
| vectors = encoder.encode(["CCO", "N[C@@H](C)C(=O)O"])
|
| print(vectors.shape) # (2, 768)
|
| ```
|
|
|
| The default device is CUDA when available, otherwise CPU. Use `device="cpu"` when
|
| loading to select CPU explicitly. The repository also includes `example.py` for a small embedding smoke test. Embeddings are final-layer CLS vectors.
|
|
|
| ## Fine-tune on your own task
|
|
|
| Use separate train and validation CSVs with `smiles,target` columns:
|
|
|
| ```python
|
| from grasp.train import fit
|
| from grasp import GRASPPredictor
|
|
|
| fit(model_source="caithmac/GRASP-A3", train_csv="train.csv", valid_csv="valid.csv",
|
| output_dir="my_a3_predictor", task="regression", method="full")
|
| predictor = GRASPPredictor.from_pretrained("my_a3_predictor")
|
| predictions = predictor.predict(["CCO"])
|
| ```
|
|
|
| Tasks are `regression` or `binary`; binary targets must be 0/1. Adaptation methods
|
| are `full`, `lora` and `frozen`. The predictor learns a four-layer mixture and atom
|
| attention pooling plus a nonlinear task head. The package includes an encoder,
|
| not pretrained endpoint-specific prediction heads. Training-set/validation-set
|
| overlap is rejected by canonical molecular identity.
|
|
|
| ## Inputs and training
|
|
|
| A3 retains A2's bond and stereo channels and omits absolute positions. Seven
|
| categorical atom fields replace the opaque atom embedding: element, degree, total
|
| hydrogens, formal charge, aromaticity, ring membership and hybridization. Input
|
| schema version 1 distinguishes PAD, UNKNOWN, MASK and CLS. Isotope mass is not an
|
| explicit field. The loader preserves salts, charges, tautomers and specified
|
| stereochemistry as parsed by RDKit; it does not silently standardize them.
|
|
|
| Step 1 used the recorded 1,538,242,560-presentation ZINC20 budget. Presentations
|
| are not a guarantee of unique molecule coverage. A3 also changed the generator
|
| targets and whole-atom corruption to operate on seven fields. Therefore this is
|
| a **joint representation/training-objective ablation**, not a representation-only
|
| causal experiment. GDES remains the embedding-sharing mechanism.
|
|
|
| Step 2 used the same audited **511,897 molecules, 642 binary assay tasks and
|
| 50,000 updates** as the matched arms. Continuous and censored ChEMBL supervision
|
| has not been added to this checkpoint. Source checkpoint SHA256:
|
|
|
| `ff491d5dcb183d5771abc102ebfcad0ba4c031adbf4077858484e50698a914b2`
|
|
|
| ## Evaluation and validation
|
|
|
| On the three shared OpenADMET cluster splits, matched replicate 0, A3's mean
|
| endpoint MAE is **0.358857**, versus A2 0.366232, A1 0.368588 and matched
|
| original-architecture control 0.370232. A3 is lower on 16/23 endpoints versus A2.
|
| See `evaluation/endpoint_comparison.csv`. Those scores use full encoder fine-tuning
|
| with the mixed-layer predictor; they are not scores for frozen CLS embeddings.
|
| The macro mixes endpoint scales and is descriptive. One pretrained checkpoint per
|
| arm does not establish repeat-stable superiority or chemical causality.
|
|
|
| `validation_report.json` records actual installed-wheel checks: tensor identity,
|
| strict loading, parity with EIDF inputs/embeddings, stereo/permutation controls and
|
| tiny adaptation/save-reload smoke checks. The loader test suite covers original
|
| GRASP/A1/A2 compatibility and A3's feature, adaptation and schema paths. Tiny fits
|
| are software checks, not new benchmark measurements. The package accepts at most
|
| 511 atoms plus CLS; long-molecule transfer has not been established here.
|
|
|
| At this release (2026-10-27), TDC evaluation for A3 is deferred in the experiment queue. AqSolDB remains
|
| blocked with its official test unchanged. No new benchmark-overlap audit or GPU
|
| performance benchmark was performed for this package.
|
|
|
| ## License and contents
|
|
|
| Weights and MolE-derived code use CC BY-NC 4.0 (`LICENSE`, `vendor/MOLE_LICENSE`).
|
| The bundled DeBERTa code uses the MIT license (`vendor/DEBERTA_LICENSE`). See NOTICE.
|
| This package includes safetensors, configuration, legacy graph-preprocessing
|
| vocabulary, the installable loader, provenance, validation, evaluation tables and
|
| an example. The vocabulary is retained for graph preprocessing; A3's embedding
|
| lookup uses the seven factorized tables.
|
|
|
| Python 3.10–3.13 is supported by package metadata; Python 3.12 is the tested local
|
| runtime. RDKit is pinned to 2025.3.6 to preserve the feature schema. Exact tested
|
| package versions are recorded in `requirements-tested.txt`. The release smoke checks were run on local CPU;
|
| a Google-hosted Colab GPU runtime was not executed during publication.
|
|
|
