D4CMPP2 0.4.0__py3-none-any.whl

D4CMPP2/src/utils/featureizer.py

@@ -0,0 +1,202 @@
+import numpy as np
+import os
+import hashlib
+
+import rdkit.Chem as Chem
+from rdkit.Chem import AllChem, MACCSkeys
+
+class InvalidAtomError(Exception):
+    pass
+
+def get_graph_features(mol):
+    return np.array(MACCSkeys.GenMACCSKeys(mol)).astype(float)
+
+def get_atom_features(mol):
+    atom_features = []
+    for atom in mol.GetAtoms():
+        atom_features.append(atom_feature(atom))
+    return np.concatenate(atom_features, axis=0)
+
+def get_atom_features_and_graph_feature(mol, graph_featurizer=None):
+    atom_features = get_atom_features(mol)
+
+    if graph_featurizer is not None:
+        graph_feature = graph_featurizer(mol)
+    else:
+        graph_feature = get_graph_features(mol)
+    graph_feature = np.tile(graph_feature, (atom_features.shape[0],1))
+    return atom_features, graph_feature
+
+def get_bond_features(mol):
+    bond_features = []
+    for bond in mol.GetBonds():
+        bond_features.append(bond_feature(bond))
+    if len(bond_features) == 0:
+        return np.zeros((1, 10))
+    return np.concatenate(bond_features, axis=0)
+
+
+def bond_feature(bond):
+    features = np.concatenate([bond_type(bond),
+                               bond_stereo(bond)
+                            ], axis=0).reshape(1,-1)
+    
+    return features
+
+def generate_conformer(mol, save_conf = True, xyz_path = None):
+    smiles = Chem.MolToSmiles(mol)
+    if mol is None:
+        return None
+    mol = Chem.AddHs(mol)
+    AllChem.EmbedMolecule(mol)
+    AllChem.EmbedMultipleConfs(mol, 10) 
+    li = AllChem.UFFOptimizeMoleculeConfs(mol, maxIters=5000)
+    eg_li = [e if s==0 else np.inf for s,e in li ]
+    idx = eg_li.index(min(eg_li))
+    conf = mol.GetConformer(idx)
+    if save_conf:
+        save_xyz(smiles, conf, xyz_path)
+    return conf
+
+def get_conformer(mol, do_optimize=False, xyz_path = None):
+    smiles = Chem.MolToSmiles(mol)
+    if mol is None:
+        return None
+    
+    if xyz_path is not None:
+        pos, atoms = load_xyz(smiles, xyz_path)
+    if pos is None and do_optimize:
+        return generate_conformer(mol, save_conf=True ,xyz_path = xyz_path)
+    elif pos is None:
+        return None
+    
+    conf = Chem.Conformer()
+    for i in range(len(atoms)):
+        conf.SetAtomPosition(i, pos[i])
+    return conf
+    
+def save_xyz(smiles, conf, xyz_path):
+    mol = Chem.MolFromSmiles(smiles)
+    m = hashlib.sha256()
+    m.update(smiles.encode('utf-8'))
+    name = m.hexdigest()
+    result=f'{mol.GetNumAtoms()} #{smiles}\n'
+    result+=f'# {Chem.GetFormalCharge(mol)} 1\n'
+    for i, atom in enumerate(mol.GetAtoms()):
+        positions = conf.GetAtomPosition(i)
+        result+=f'{atom.GetSymbol()} {positions.x} {positions.y} {positions.z}\n'
+    with open(f'{xyz_path}/{name}.xyz','w') as t:
+        t.write(result)
+    return name
+
+def load_xyz(smiles,xyz_path):
+    m = hashlib.sha256()
+    m.update(smiles.encode('utf-8'))
+    name = m.hexdigest()
+    path = os.path.join(xyz_path,name+'.xyz')
+    if not os.path.exists(path):
+        return None, None
+    m = hashlib.sha256()
+    m.update(smiles.encode('utf-8'))
+    name = m.hexdigest()
+    with open(path,'r') as t:
+        file= t.read()
+    xyzs = file.split("\n")[2:]
+    pos = []
+    atoms = []
+    for xyz in xyzs:
+        space = '\t' if '\t' in xyz else ' ' 
+        a = xyz.split(space)
+        if len(a)!=4 and len(a)!=5: break
+        pos.append(np.array([to_float(a[1]),to_float(a[2]),to_float(a[3])]))
+        atoms.append(a[0])
+    return np.stack(pos), atoms
+
+def to_float(a):
+    try:
+        return float(a)
+    except ValueError as exc:
+        if '*^' in a:
+            return float(a.replace('*^','e'))
+        raise ValueError(
+            f"XYZ coordinate {a!r} is not numeric. Check the cached XYZ file."
+        ) from exc
+
+
+def get_bond_features_conformer(mol, conf=None, xyz_path=None):
+    if conf is None:
+        conf = get_conformer(mol, do_optimize=True, xyz_path=xyz_path)
+
+    bond_features = []
+    for bond in mol.GetBonds():
+        bond_features.append(bond_feature_conformer(bond, conf))
+    return np.concatenate(bond_features, axis=0)
+
+def bond_feature_conformer(bond, conf):
+    features = np.concatenate([bond_type(bond),
+                               bond_stereo(bond),
+                               bond_length(bond, conf)
+                            ], axis=0).reshape(1,-1)
+    return features
+
+def bond_length(bond, conf):
+    src_pos = conf.GetAtomPosition(bond.GetBeginAtomIdx())
+    dst_pos = conf.GetAtomPosition(bond.GetEndAtomIdx())
+    return np.array([np.linalg.norm(src_pos-dst_pos)]).astype(float)
+
+def atom_feature(atom):
+    features = np.concatenate([atom_symbol_HNums(atom),
+                                atom_degree(atom),
+                                atom_Aroma(atom),
+                                atom_Hybrid(atom),
+                                atom_ring(atom),
+                                atom_FC(atom)
+                            ], axis=0).reshape(1,-1)
+    
+    return features
+
+def bond_type(bond):
+    return np.array(one_of_k_encoding(str(bond.GetBondType()),['SINGLE', 'DOUBLE', 'TRIPLE', 'AROMATIC'])).astype(int)
+
+def bond_stereo(bond):
+    return np.array(one_of_k_encoding(str(bond.GetStereo()),['STEREONONE', 'STEREOANY', 'STEREOZ', 'STEREOE'])).astype(int)
+
+def atom_symbol_HNums(atom):
+    
+    return np.array(one_of_k_encoding(atom.GetSymbol(),
+                                      ['C', 'N', 'O','S', 'H', 'F', 'Cl', 'Br', 'I', 'Se', 'Te','Si','P','B','Sn','Ge'])+
+                    one_of_k_encoding(atom.GetTotalNumHs(), [0, 1, 2, 3, 4]))
+
+
+def atom_degree(atom):
+    return np.array(one_of_k_encoding(atom.GetDegree(), [0, 1, 2, 3, 4, 5 ,6])).astype(int) 
+
+
+def atom_Aroma(atom):
+    return np.array([atom.GetIsAromatic()]).astype(int)
+
+
+def atom_Hybrid(atom):
+    return np.array(one_of_k_encoding(str(atom.GetHybridization()),['S','SP','SP2','SP3','SP3D','SP3D2'],'S')).astype(int)
+
+
+def atom_ring(atom):
+    return np.array([atom.IsInRing()]).astype(int)
+
+
+def atom_FC(atom):
+    return np.array(one_of_k_encoding(atom.GetFormalCharge(), [-4,-3,-2,-1, 0, 1, 2, 3, 4])).astype(int)
+
+
+def one_of_k_encoding(x, allowable_set,default=None):
+    if x not in allowable_set:
+        if default is not None:
+            return list(map(lambda s: default == s, allowable_set))
+        raise InvalidAtomError("input {0} not in allowable set{1}:".format(x, allowable_set))
+    return list(map(lambda s: x == s, allowable_set))
+
+def triplet_feature(mol, conf, atom1, atom2, atom3):
+    return np.array([rdMolTransforms.GetAngleRad(conf, atom1, atom2, atom3)]).astype(float)
+
+
+

D4CMPP2/src/utils/functional_group.csv

@@ -0,0 +1,169 @@
+Name,Formula,SMARTS,Priority,,
+Sulfur,S,[S;!R],-1,,
+Nitrogen,N,[N;!R],-1,,
+Oxygen,O,[O;!R],-1,,
+Alkane,RH,[C;!R],-1,,
+Methyl,C,[CH3],0,,
+Ethyl,CC,[CH2][CH3],0,,
+Prophyl,CCC,[CH2][CH2][CH3],0,,
+Alkene,R2C=CR2,[C;!R]=[C;!R],1,,
+Alkyne,RC≡CR',[C;!R]#[C;!R],1,,
+Allene,R2C=C=CR2,[C;!R]=[C;!R]=[C;!R],1,,
+Cumulene,R2C=C=C=CR2,[C;!R]=[C;!R]=[C;!R]=[C;!R],1,,
+Fluoro,RF,F,1,,
+Chloro,RCl,[Cl],1,,
+Bromo,RBr,[Br],1,,
+Iodo,RI,I,1,,
+Ether,ROR',[OH0;!R],1,,
+Alcohol,ROH,[OH1],1,,
+Aldehyde,RCHO,[CH1;!R]=O,1,,
+Ketone-O,RCOR',[OX1;+0],1,,
+Ketone,RCOR',[CX3;!R]=O,1,,
+Amine,RNH2,[NH2],1,,
+Aldimine / Imine,RCHNH2,[CH1]=[NH1],1,,
+Nitrile / Cyanide,,C#N,1,,
+Isocyanide / Isonitrile,,[N+]#[C-],1,,
+Azide,,N=[N+]=[N-],1,,
+Azo compound / Diimide / Diazene,,[NH0]=[NH0],1,,
+Diazonium salt,,[N+]#N,1,,
+Hydrazine,,[NX3][NX3],1,,
+Enamine,,C=CN,1,,`
+Hydroxylamine,,N[OH1],1,,
+Amine oxide / N-oxide,,[N+;D4][O-],1,,
+Cyanate,,OC#N,1,,
+Isocyanate,,N=C=O,1,,
+Nitro compound,,[N+](=O)[O-],1,,
+Nitroso,,N=O,1,,
+Nitrite,,ON=O,1,,
+Nitrate,,O[N+](=O)[O-],1,,
+Thioether,RSR',[SD2],1,,
+Thiol,RSH,[SH1],1,,
+Thial / Thioaldehyde,RCHS,[CH1](=S),1,,
+Thione / Thioketone,RCSR',[CD3](=S),1,,
+phosphate,,P(=O)(O)(O)(O),1,,
+Carboxylic Acid,RCO2H,[CH0;!R](=O)[OH1],2,,
+Acyl halide,RCOX,"[CH0;!R](=O)[F,Cl,I,Br]",2,,
+Ester,RCO2R',[CH0;!R](=O)[OH0],2,,
+Hydroperoxide,ROOH,[OH0][OH1],2,,
+Peroxide,ROOR',[OH0;!R][OH0;!R],2,,
+Ketene,RC(=C=O)R',[CX3]=C=O,2,,
+Ketimine / Imine,,[CX3]=[NH0],2,,
+Ketenimine,,[CX3]=C=N,2,,
+Carbodiimide,,[NH0]=C=[NH0],2,,
+Amidine,,[CH0;!R](=[NH1])[NH2],2,,
+Amidrazone,,[CH0;!R](=[NH1])[NH1][NH2],2,,
+Guanidine,,N[CH0;!R](=[NH1])[NH1][NH2],2,,
+Hydrazone,,[CX3;!R]=N[NH2],2,,
+Aminal,,[CX4;!R](N)(N),2,,
+Hemiaminal,,[CX4;!R](N)O,2,,
+Aldoxime,,[CH1]=N[OH1],2,,
+Ketoxime,,[CH0;D3]=N[OH1],2,,
+Aldoxime ether,,[CH1]=N[OH0],2,,
+Ketoxime ether,,[CH0;X3]=N[OH0],2,,
+Amide,,[CH0;!R](=O)N,2,,
+Carbamic acid,,NC(=O)[OH1],2,,
+Carbamate,,NC(=O)[OH0],2,,
+Urea,,NC(=O)N,2,,
+Isourea,,NC(=[NH1])O,2,,
+Carbamic acyl halide,,"NC(=O)[F,Cl,I,Br]",2,,
+Acyl cyanide,,[CH0](=O)C#N,2,,
+[[Thioic O-acid]],RC(S)OH,[CH0](=S)[OH1],2,,
+[[Thioic S-acid]],RC(O)SH,[CH0](=O)[SH1],2,,
+Dithioic acid,RCS2H,[CH0](=S)[SH1],2,,
+Thioyl_halide,RCSX,"[CH0](=S)[F,Cl,Br,I]",2,,
+[[Thioic O-ester]],RC(S)OR',[CH0](=S)[OH0],2,,
+[[Thioic S-ester]],RC(O)SR',[CH0](=O)[SH0],2,,
+Dithioic ester,RCS2R',[CH0](=S)[SH0],2,,
+Sulfuric acid,SO3,[SH0](=O)(=O)O,3,,
+Peroxy acid,RCO3H,[CH0;!R](=O)O[OH1],3,,
+Anhydride,RCOOCOR',[CH0;!R](=O)O[CH0](=O),3,,
+Carbonate,ROCOOR',[OH0;!R]C(=O)[OH0],3,,
+Hydrate,RC(OH)(OH)R',[CD4]([OH1])[OH1],3,,
+Hemiacetal,RCH(OR')(OH),[CH1]([OH0])[OH1],3,,
+Acetal,RCH(OR')(OR''),[CH1]([OH0])[OH0],3,,
+Hemiketal,RC(OR'')(OH)R',[CX4]([OH0])[OH1],3,,
+Ketal,RC(OR'')(OR''')R',[CX4]([OH0])[OH0],3,,
+Orthoester,RC(OR')(OR'')(OR'''),[CX4]([OH0])([OH0])[OH0],3,,
+Orthocarbonate,ROC(OR')(OR'')(OR'''),O[CX4](O)(O)O,3,,
+Enol,RC(OH)=CR'2,[CH0;!R]([OH1])=[CD3],3,,
+Enol ether,RC(OR')=CR''2,[CH0;!R]([OH0])=[CD3],3,,
+Hydroxamic acid,,[CH0;!R](=O)[NH0]([OH1]),3,,
+Imide,,[CH0;!R](=O)[NH0][CH0](=O),3,,
+Imidoester,,[CH0;!R](=N)N,3,,
+Imidoyl halide,,"[CH0;!R](=N)[F,Cl,Br,I]",3,,
+Hydrazide,,[CH0;!R](=O)NN,3,,
+Semicarbazide,,[NX3]C(=O)N[NX3],3,,
+Semicarbazone,,[NX3]C(=O)N[NX2],3,,
+α-lactone,,C1(=O)OC1,5,,
+β-lactone,,C1(=O)OCC1,5,,
+γ-lactone,,C1(=O)OCCC1,5,,
+δ-lactone,/,C1(=O)OCCCC1,5,,
+ε-lactone,,C1(=O)OCCCCC1,5,,
+α-Lactam,,C1(=O)[NH1]C1,5,,
+β-Lactam,,C1(=O)[NH1]CC1,5,,
+γ-Lactam,,C1(=O)[NH1]CCC1,5,,
+δ-Lactam,,C1(=O)[NH1]CCCC1,5,,
+ε-Lactam,,C1(=O)[NH1]CCCCC1,5,,
+Epoxide,/,O1CC1,5,,
+ethylenamine,,C1CN1,5,,
+trymethylene oxide,,C1COC1,5,,
+tetrahydrofuran,,C1CCOC1,5,,
+pyrrolidine,,C1CCNC1,5,,
+pyran,,C1=CCOC=C1,5,,
+piperidine,,C1CCNCC1,5,,
+dioxane,,C1COCCO1,5,,
+morpholine,,C1COCCN1,5,,
+Unknown tetra ring,,[R]1@[R]@[R]@[R]@1,5,,
+Unknown penta ring,,[R]1@[R]@[R]@[R]@[R]@1,5,,
+Unknown hexa ring,,[R]1@[R]@[R]@[R]@[R]@[R]@1,5,,
+Unknown septa ring,,[R]1@[R]@[R]@[R]@[R]@[R]@[R]@1,5,,
+Unknown octa ring,,[R]1@[R]@[R]@[R]@[R]@[R]@[R]@[R]@1,5,,
+Unknown nona ring,,[R]1@[R]@[R]@[R]@[R]@[R]@[R]@[R]@[R]@1,5,,
+Unknown deca ring,,[R]1@[R]@[R]@[R]@[R]@[R]@[R]@[R]@[R]@[R]@1,5,,
+Unknown tetra aromatic ring,,[a]1[a][a][a]1,5,,
+Unknown penta aromatic ring,,[a]1[a][a][a][a]1,5,,
+Unknown hexa aromatic ring,,[a]1[a][a][a][a][a]1,5,,
+Unknown septa aromatic ring,,[a]1[a][a][a][a][a][a]1,5,,
+Unknown octa aromatic ring,,[a]1[a][a][a][a][a][a][a]1,5,,
+Unknown nona aromatic ring,,[a]1[a][a][a][a][a][a][a][a]1,5,,
+Unknown deca aromatic ring,,[a]1[a][a][a][a][a][a][a][a][a]1,5,,
+furan,,c1ccoc1,6,,
+thiophene,,c1ccsc1,6,,
+pyrrole,,c1ccnc1,6,,
+Benzene,,c1ccccc1,6,,
+pyridine,,c1ccncc1,6,,
+imidazole,,c1cncn1,6,,
+thiazole,,c1cscn1,6,,
+pyrimidine,,c1cncnc1,6,,
+naphthalene,,c1ccc2ccccc2c1,9,,
+anthracene,,c1ccc2cc3ccccc3cc2c1,9,,
+phenanthrene,,c1ccc2c(c1)ccc1ccccc12,9,,
+chrysene,,c1ccc2c(c1)ccc1c3ccccc3ccc21,9,,
+pyrene,,c1cc2ccc3cccc4ccc(c1)c2c34,9,,
+corannulene,,c1cc2ccc3ccc4ccc5ccc1c1c2c3c4c51,9,,
+coronene,,c1cc2ccc3ccc4ccc5ccc6ccc1c1c2c3c4c5c61,9,,
+pentalene,,C1=CC2=CC=CC2=C1,9,,
+indene,,C1=Cc2ccccc2C1,9,,
+azulene,,c1ccc2cccc-2cc1,9,,
+heptalene,,C1=CC=C2C=CC=CC=C2C=C1,9,,
+biphenylene,,c1ccc2c(c1)-c1ccccc1-2,9,,
+as-indacene,,C1=Cc2c3c(ccc2=C1)=CC=C3,9,,
+s-indacene,,C1=Cc2cc3c(cc2=C1)C=CC=3,9,,
+acenaphthylene,,C1=Cc2cccc3cccc1c23,9,,
+fluorene,,c1ccc2c(c1)Cc1ccccc1-2,9,,
+phenalene,,C1=Cc2cccc3cccc(c23)C1,9,,
+perylene,,c1cc2cccc3c4cccc5cccc(c(c1)c23)c54,9,,
+indole,,c1ccc2nccc2c1,9,,
+isoindole,,c1ccc2cncc2c1,9,,
+indolizine,,c1ccn2cccc2c1,9,,
+quinoline,,c1ccc2ncccc2c1,9,,
+isoquinoline,,c1ccc2cnccc2c1,9,,
+purine,,c1ncc2ncnc2n1,9,,
+carbazole,,c1ccc2c(c1)nc1ccccc12,9,,
+dibenzofuran,,c1ccc2c(c1)oc1ccccc12,9,,
+2H-chromoene,,C1=Cc2ccccc2OC1,9,,
+xanthene,,c1ccc2c(c1)Cc1ccccc1O2,9,,
+porphyrin,,C1=Cc2cc3ccc(cc4nc(cc5ccc(cc1n2)[nH]5)C=C4)[nH]3,9,,
+chlorin,,C1=Cc2cc3ccc(cc4nc(cc5ccc(cc1n2)[nH]5)CC4)[nH]3,9,,
+BODIPY,,F[B-]1(F)N2C=CC=C2C=C2C=CC=[N+]12,9,,
+phthalocyanine,,c1ccc2c(c1)-c1nc-2nc2[nH]c(nc3nc(nc4[nH]c(n1)c1ccccc41)-c1ccccc1-3)c1ccccc21,9,,

D4CMPP2/src/utils/graph_cache.py

@@ -0,0 +1,213 @@
+"""Versioned graph-cache identity, validation, and atomic persistence."""
+
+import hashlib
+import importlib.metadata
+import json
+import os
+import re
+import uuid
+from pathlib import Path
+
+import torch
+from torch_geometric.data import Data, HeteroData
+
+
+GRAPH_CACHE_SCHEMA_VERSION = 2
+GRAPH_FEATURE_CONTRACT_VERSION = 1
+ISA_RELATIONS = (
+    ("r_nd", "r2r", "r_nd"),
+    ("r_nd", "r2i", "i_nd"),
+    ("i_nd", "i2i", "i_nd"),
+    ("i_nd", "i2d", "d_nd"),
+    ("d_nd", "d2d", "d_nd"),
+    ("d_nd", "d2r", "r_nd"),
+)
+
+
+def _package_version(name):
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _file_sha256(path):
+    if not path or not Path(path).is_file():
+        return None
+    digest = hashlib.sha256()
+    with open(path, "rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _ordered_smiles_sha256(smiles):
+    encoded = json.dumps([str(value) for value in smiles], ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def safe_cache_component(value):
+    name = Path(os.fspath(value).replace("\\", "/")).name
+    name = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._")
+    return name or "data"
+
+
+def build_graph_recipe(manager, column):
+    """Return deterministic identity metadata for one molecule-column cache."""
+    is_isa = str(manager.graph_type).startswith("img")
+    functional_group = None
+    if is_isa:
+        candidate = Path(manager.config.get("MODEL_PATH", "")) / "functional_group.csv"
+        functional_group = candidate if candidate.is_file() else manager.config.get("FRAG_REF")
+    recipe = {
+        "graph_backend": "pyg",
+        "graph_schema_version": GRAPH_CACHE_SCHEMA_VERSION,
+        "feature_contract_version": GRAPH_FEATURE_CONTRACT_VERSION,
+        "graph_type": manager.graph_type,
+        "molecule_column": column,
+        "explicit_h": column in manager.explicit_h_columns,
+        "row_count": len(manager._molecule_smiles[column]),
+        "ordered_smiles_sha256": _ordered_smiles_sha256(manager._molecule_smiles[column]),
+        "node_dim": manager.gg.node_dim,
+        "edge_dim": manager.gg.edge_dim,
+        "max_dist": manager.config.get("max_dist", 4) if is_isa else None,
+        "functional_group_sha256": _file_sha256(functional_group) if is_isa else None,
+        "versions": {
+            "d4cmpp2": _package_version("D4CMPP2"),
+            "rdkit": _package_version("rdkit"),
+            "torch": torch.__version__,
+            "torch_geometric": _package_version("torch-geometric"),
+        },
+    }
+    identity = dict(recipe)
+    identity.pop("versions")
+    serialized = json.dumps(identity, sort_keys=True, separators=(",", ":"))
+    recipe["fingerprint"] = hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+    return recipe
+
+
+def cache_path(manager, column, recipe):
+    parts = [
+        safe_cache_component(manager.data),
+        safe_cache_component(column),
+        safe_cache_component(manager.graph_type),
+    ]
+    if column in manager.explicit_h_columns:
+        parts.append("explicitH")
+    parts.extend(["pyg", "v2", recipe["fingerprint"][:16]])
+    return Path(manager.config["GRAPH_DIR"]) / ("_".join(parts) + ".pt")
+
+
+def legacy_cache_paths(manager, column):
+    base = f"{manager.data}_{column}_{manager.graph_type}"
+    if column in manager.explicit_h_columns:
+        base += "_explicitH"
+    root = Path(manager.config["GRAPH_DIR"])
+    return root / f"{base}_pyg_v1.pt", root / f"{base}.bin"
+
+
+def atomic_save_graph_cache(payload, path):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    staging = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        torch.save(payload, staging)
+        os.replace(staging, path)
+    finally:
+        if staging.exists():
+            staging.unlink()
+
+
+def _validate_tensor(tensor, name, expected_rows=None, expected_columns=None, floating=None):
+    if not isinstance(tensor, torch.Tensor):
+        raise ValueError(f"{name} must be a torch.Tensor, got {type(tensor).__name__}.")
+    if expected_rows is not None and tensor.shape[0] != expected_rows:
+        raise ValueError(f"{name} rows={tensor.shape[0]}, expected {expected_rows}.")
+    if expected_columns is not None and (tensor.ndim != 2 or tensor.shape[1] != expected_columns):
+        raise ValueError(f"{name} shape={tuple(tensor.shape)}, expected (*, {expected_columns}).")
+    if floating is True and not tensor.is_floating_point():
+        raise ValueError(f"{name} dtype={tensor.dtype}, expected a floating dtype.")
+    if tensor.is_floating_point() and tensor.numel() and not bool(torch.isfinite(tensor).all()):
+        raise ValueError(f"{name} contains NaN or infinite values.")
+
+
+def _validate_edge_alignment(edge_index, edge_attr, name):
+    if edge_attr.shape[0] != edge_index.shape[1]:
+        raise ValueError(
+            f"{name} edge feature rows={edge_attr.shape[0]}, "
+            f"but edge_index contains {edge_index.shape[1]} edges."
+        )
+
+
+def validate_graph(graph, recipe, index):
+    prefix = f"graphs[{index}]"
+    if str(recipe["graph_type"]).startswith("img"):
+        if not isinstance(graph, HeteroData):
+            raise ValueError(f"{prefix} must be HeteroData, got {type(graph).__name__}.")
+        missing_nodes = [node for node in ("r_nd", "i_nd", "d_nd") if node not in graph.node_types]
+        missing_relations = [relation for relation in ISA_RELATIONS if relation not in graph.edge_types]
+        if missing_nodes or missing_relations:
+            raise ValueError(
+                f"{prefix} is missing node types {missing_nodes} or relations {missing_relations}."
+            )
+        _validate_tensor(graph["r_nd"].x, f"{prefix}.r_nd.x", expected_columns=recipe["node_dim"], floating=True)
+        for relation in ISA_RELATIONS:
+            _validate_tensor(graph[relation].edge_index, f"{prefix}.{relation}.edge_index", expected_rows=2)
+        r2r = graph["r_nd", "r2r", "r_nd"]
+        _validate_tensor(
+            r2r.edge_attr,
+            f"{prefix}.r2r.edge_attr",
+            expected_columns=recipe["edge_dim"],
+            floating=True,
+        )
+        _validate_edge_alignment(r2r.edge_index, r2r.edge_attr, f"{prefix}.r2r")
+        d2d = graph["d_nd", "d2d", "d_nd"]
+        _validate_tensor(
+            d2d.edge_attr,
+            f"{prefix}.d2d.edge_attr",
+            expected_columns=recipe["max_dist"],
+            floating=True,
+        )
+        _validate_edge_alignment(d2d.edge_index, d2d.edge_attr, f"{prefix}.d2d")
+        return
+    if not isinstance(graph, Data) or isinstance(graph, HeteroData):
+        raise ValueError(f"{prefix} must be Data, got {type(graph).__name__}.")
+    _validate_tensor(graph.x, f"{prefix}.x", expected_columns=recipe["node_dim"], floating=True)
+    _validate_tensor(graph.edge_index, f"{prefix}.edge_index", expected_rows=2)
+    if graph.edge_index.dtype != torch.long:
+        raise ValueError(f"{prefix}.edge_index dtype={graph.edge_index.dtype}, expected torch.int64.")
+    _validate_tensor(graph.edge_attr, f"{prefix}.edge_attr", expected_columns=recipe["edge_dim"], floating=True)
+    _validate_edge_alignment(graph.edge_index, graph.edge_attr, prefix)
+
+
+def validate_payload(payload, expected_recipe, expected_smiles, path):
+    if not isinstance(payload, dict):
+        raise ValueError(f"Graph cache {str(path)!r} must contain a dictionary payload.")
+    actual_recipe = payload.get("recipe")
+    if not isinstance(actual_recipe, dict):
+        raise ValueError(f"Graph cache {str(path)!r} has no v2 recipe metadata.")
+    for field, expected in expected_recipe.items():
+        if field == "versions":
+            continue
+        actual = actual_recipe.get(field)
+        if actual != expected:
+            raise ValueError(
+                f"Graph cache {str(path)!r} recipe mismatch for {field!r}: "
+                f"actual={actual!r}, expected={expected!r}. Regenerate this cache from the source CSV."
+            )
+    smiles = payload.get("smiles")
+    if [str(value) for value in smiles or []] != [str(value) for value in expected_smiles]:
+        raise ValueError(
+            f"Graph cache {str(path)!r} ordered SMILES do not match the source CSV. "
+            "Regenerate this cache from the current data."
+        )
+    graphs = payload.get("graphs")
+    if not isinstance(graphs, list) or len(graphs) != len(expected_smiles):
+        raise ValueError(
+            f"Graph cache {str(path)!r} graph count is "
+            f"{len(graphs) if isinstance(graphs, list) else type(graphs).__name__}, "
+            f"expected {len(expected_smiles)}. Regenerate this cache."
+        )
+    for index, graph in enumerate(graphs):
+        validate_graph(graph, expected_recipe, index)
+    return graphs, list(payload.get("graph_errors") or [])