Graph descriptors for machine learning¶

The per-atom and per-bond quantities a graph neural network reads, in one call each, computed the same way the reference implementation computes them.


`Mol.atom_descriptors()`	twelve values per atom
`Mol.bond_descriptors()`	seven values per bond

>>> import omgkit
>>> m = omgkit.parse_smiles("CC(=O)Oc1ccccc1C(=O)O"); m.sanitize()
>>> m.atom_descriptors()[1]
{'atomic_num': 6, 'total_degree': 3, 'formal_charge': 0,
 'chiral_tag': 'unspecified', 'total_num_hs': 0, 'hybridization': 'sp2',
 'is_aromatic': False, 'is_in_ring': False, 'mass': 12.011,
 'electronegativity': 2.55, 'gasteiger_charge': 0.3075...,
 'gasteiger_valid': True}
>>> m.bond_descriptors()[1]
{'begin': 1, 'end': 2, 'order': 'double', 'is_conjugated': True,
 'is_in_ring': False, 'stereo': 'none', 'stereo_atoms': None}

What you get¶

Per atom¶

Key	Type
`atomic_num`	`int`	element; `0` is the wildcard `*`
`total_degree`	`int`	explicit neighbours plus total hydrogens
`formal_charge`	`int`
`chiral_tag`	`str`	`unspecified`, `cw`, `ccw`, `allene`, `square_planar`, `trigonal_bipyramidal`, `octahedral`
`total_num_hs`	`int`	declared + implied; not free-standing `[H]` atoms in the graph
`hybridization`	`str`	`unspecified`, `s`, `sp`, `sp2`, `sp3`, `sp2d`, `sp3d`, `sp3d2`
`is_aromatic`	`bool`
`is_in_ring`	`bool`
`mass`	`float`	the exact mass of the labelled nuclide if an isotope was given, otherwise the standard atomic weight
`electronegativity`	`float \\| None`	Pauling
`gasteiger_charge`	`float`	Gasteiger–Marsili partial charge (PEOE)
`gasteiger_valid`	`bool`	whether the line above is a real number

Per bond¶

Key	Type
`begin`, `end`	`int`	atom indices
`order`	`str`	`unspecified`, `single`, `double`, `triple`, `quadruple`, `aromatic`, `dative`
`is_conjugated`	`bool`
`is_in_ring`	`bool`
`stereo`	`str`	`none`, `cis`, `trans` (see below)
`stereo_atoms`	`tuple[int, int] \\| None`	the two atoms `stereo` is measured against

Descriptors, not an encoding¶

Categorical values come back as names — "sp3", "ccw" — never one-hot vectors and never integer codes. Which elements go in your vocabulary, whether you keep an "other" bucket, how you scale the three continuous values: those are decisions belonging to your featurizer, and freezing one model's answer into a library would make it wrong for the next model. Integer codes would be worse still: they are invisible when they shift.

Building a 45-dimensional atom vector on top is a dozen lines:

ELEMENTS = ["C", "N", "O", "F", "P", "S", "Cl", "Br", "I"]
ATOMIC_NUMS = [6, 7, 8, 9, 15, 16, 17, 35, 53]

def one_hot(value, vocabulary):
    """Last slot is the 'other' bucket."""
    v = [0] * (len(vocabulary) + 1)
    v[vocabulary.index(value) if value in vocabulary else -1] = 1
    return v

def atom_vector(d):
    return (
        one_hot(d["atomic_num"], ATOMIC_NUMS)
        + one_hot(d["total_degree"], list(range(6)))
        + one_hot(d["formal_charge"], [-2, -1, 0, 1, 2])
        + one_hot(d["hybridization"], ["sp", "sp2", "sp3", "sp3d", "sp3d2"])
        + [d["is_aromatic"] * 1, d["is_in_ring"] * 1]
        + [d["mass"] * 0.01]
        + [(d["electronegativity"] or 2.0) / 4]
        + [d["gasteiger_charge"] if d["gasteiger_valid"] else 0.0]
        + [d["gasteiger_valid"] * 1]
    )

Two ways a value can be missing¶

electronegativity is None when the element has no accepted Pauling value — the noble gases, and Pm, Eu, Tb, Yb, Fr. That is different from "not measured yet" and different from zero.

gasteiger_valid is False when the atom falls outside the Gasteiger parameter set, which covers H, C, N, O, F, Si, P, S, Cl, Br, I, B, Be, Mg and Al. Most metals do not, and the failure spreads along the graph: a carbon bonded to a sodium ends up with a nan charge too. Across the five corpora the gate runs on (9 088 molecules), 4 226 atoms came out invalid — and RDKit produces nan for exactly the same ones.

Both are reported honestly rather than filled in with a default. A default would merge "we do not know" with "the value happens to be that", and your featurizer is exactly the code that needs to tell those apart — which is what the gasteiger_valid flag is for.

`cis`/`trans`, not `Z`/`E`¶

Z and E are defined by CIP priority, and omgkit does not implement CIP ranking. What you get instead is the geometry relative to the two atoms named in stereo_atoms, matching RDKit's SetBondStereoFromDirections (STEREOCIS/STEREOTRANS) rather than AssignStereochemistry's STEREOZ/STEREOE.

The two carry the same geometric information: given the reference atoms you can convert one to the other by ranking them yourself. That is why stereo_atoms is part of the descriptor and not an extra — read on its own, stereo means nothing, because on a tetrasubstituted double bond a different choice of reference flips the label.

Sanitize first¶

Aromaticity, ring membership, hybridization, conjugation and implicit hydrogen counts are all filled in by sanitization; double-bond geometry is filled in by the step right after it. Mol.sanitize() does both.

Skipping it does not raise — you get a full set of descriptors made of parse-time placeholders.

The Rust API¶

use omgkit_chem::{atom_descriptors, bond_descriptors, sanitize};

let mut m = omgkit_io::smiles::parse("C/C=C/C(=O)O")?;
sanitize(&mut m)?;
omgkit_io::stereo::perceive_bond_stereo(&mut m);   // see below

let a = atom_descriptors(&m);   // Vec<AtomDescriptors>
let b = bond_descriptors(&m);   // Vec<BondDescriptors>
assert!(a[0].gasteiger_is_valid());

The enums come back as enums here (Hybridization::Sp3, BondStereo::Trans), not as strings — the strings exist only at the Python boundary, where there is no enum to hand over.

Rust callers must make that second call themselves

Mol.sanitize() in Python runs two things: omgkit_chem::sanitize, and then omgkit_io::stereo::perceive_bond_stereo, which turns the / and \ of the input into the double bond's own cis/trans property. The second lives in omgkit-io, a sibling of omgkit-chem rather than a dependency, so sanitize cannot call it.

Skipping it does not raise. Every bond just reports BondStereo::None, and nothing about the result looks wrong.

How this is checked¶

Sixteen of the nineteen values are compared against RDKit atom-by-atom and bond-by-bond over five corpora (9 088 molecules) by harness/check_descriptors.py, which runs in CI. Seven deliberate divergences are pinned by name, each one a documented blind spot on the reference side — for instance RDKit cannot represent allene axial chirality at all.

Which three are not in that count, and where each is guarded instead:

Not compared there	Why	Guarded by
`begin`, `end`	bond endpoints, not descriptors	the graph itself
`stereo_atoms`	the reference atoms a `stereo` value is measured against	`harness/check_bond_stereo.py`

And two things that gate can see only partly:

the value of the Pauling electronegativity — RDKit exposes no API for it, so a unit test in omgkit-core pins the table instead;
the value of stereo (cis vs trans) — compared by harness/check_bond_stereo.py, not here; this gate only checks which bonds carry a configuration.

All of that is written down in the judge's own header, along with the mutation runs that establish it.