API stability policy¶

This page states the public API contract for graphchem and how version numbers relate to compatible change.

A markdown copy for contributors browsing the source tree without a docs build is kept at API_STABILITY.md in the repository root.

GraphChem builds graph neural network models for molecular (fuel) property prediction from SMILES, using RDKit for perception and PyTorch Geometric for graphs and message passing.

Frozen public surface¶

The following imports are the supported surface and must remain drop-in compatible within the 2.3.x / 2.4.x compatibility series:

from graphchem import __version__

from graphchem.data import MoleculeGraph, MoleculeDataset

from graphchem.datasets import (
    load_cn, load_lhv, load_mon, load_ron, load_ysi,
)

from graphchem.nn import MoleculeGCN

from graphchem.preprocessing import (
    get_ring_size,
    atom_to_str,
    bond_to_str,
    Tokenizer,
    MoleculeEncoder,
    load_encoder,
)

Parameter names and defaults for these callables and constructors are frozen. Additive optional keyword arguments may be introduced when they do not change existing call sites. Renaming exports, making new arguments required, changing primary return container types or shapes, or changing documented exception types for existing failure modes requires an explicit, versioned compatibility decision.

Top-level re-exports of submodule symbols (beyond __version__) are not required for compatibility. Callers should import from the submodules above.

Signature contracts¶

Keyword names and defaults must remain compatible (additive optional kwargs only):

MoleculeGraph(atom_attr, bond_attr, connectivity, target=None)
MoleculeDataset(graphs)

MoleculeGCN(
    atom_vocab_size,
    bond_vocab_size,
    output_dim,
    embedding_dim=128,
    n_messages=2,
    n_readout=2,
    readout_dim=64,
    p_dropout=0.0,
    aggr="add",
    act_fn=...,  # default: torch.nn.functional.softplus
)

MoleculeEncoder(smiles)          # smiles: list[str]
MoleculeEncoder.encode(smiles)   # -> (atom_tensor, bond_tensor, connectivity)
MoleculeEncoder.encode_many(...)
MoleculeEncoder.save(filename)
load_encoder(filename)

Tokenizer.__call__(...)
# Tokenizer.train, Tokenizer.unknown, Tokenizer.vocab_size

get_ring_size(obj, max_size=12)
atom_to_str(atom)
bond_to_str(bond)

load_cn()
load_lhv()
load_mon()
load_ron()
load_ysi()

Behavioral contracts¶

Contract	Detail
Bond duplication	`MoleculeEncoder.encode()` produces `2 × num_bonds` bond features
Target shape	`MoleculeGraph` enforces `y.shape[0] == 1`
Featurizer strings	`atom_to_str` / `bond_to_str` tuple-string format drives vocabularies
Encoder persistence	`MoleculeEncoder.save` / `load_encoder` remain pickle-compatible
GCN outputs	`MoleculeGCN.forward(data)` returns `(out, out_atom, out_bond)`
`n_readout=0`	Returns pooled embeddings without a readout MLP
Dataset loaders	`load_*()` → `(list[str], torch.Tensor)` with stable column semantics
Invalid SMILES	`MoleculeEncoder` raises `ValueError` on unparsable SMILES

Versioning¶

Patch / compatible minor (``2.3.x`` / ``2.4.x``): bug fixes that restore documented behavior; tooling; documentation; dependency range changes proven by encoding/oracle tests; additive optional kwargs with defaults matching today; clearer error messages of the same exception type. Featurizer string schemas and pickle encoder load must continue to work.
Modernization release (``2.3.4``): the API-stable modernization program ships as ``2.3.4`` at the end of Phase 5. Phases 1–4 remain on tip 2.3.3 until that bump.
Later minor (``2.4.x``): reserved for additive, still API-compatible work after 2.3.4. Explicitly deferred from the 2.3.4 modernization release:
- optional JSON/msgpack encoder serialization (pickle remains)
- optional CLI entry points
- optional pretrained model weights
- benchmark harness
Major (``3.0.0``): featurizer string schema changes that break existing encoders; removal of pickle load; changes to forward return arity/shapes; dataset content revisions that change labels for the same SMILES.

Oracle parity as a release gate¶

Regression oracles in the test suite (fixed SMILES encodings, encoder round-trips, and end-to-end smoke paths) are part of the compatibility contract for the 2.3.x / 2.4.x series.

Fixture values are self-consistency anchors for the declared RDKit and GraphChem versions, not independent literature tables, unless explicitly expanded later.

Runtime prerequisites¶

GraphChem depends on RDKit, NumPy, PyTorch, and PyTorch Geometric. Platform-specific wheel installation may require following the upstream install guides linked from Installation.