Skip to content

GenMol — molecule generation

GenMol is a β-VAE over SMILES strings. Given a causal target, the pipeline samples it for candidate molecules; on its own it is a small generative model you can sample, interpolate in, or condition on properties.

SMILES ──► Encoder (3-layer bidirectional GRU) ──► μ, log σ²
                                                      │
                                                 z ~ N(μ, σ²)
                                                      │
         Decoder (autoregressive GRU) ◄───────────────┘
                │
            SMILES

The shipped checkpoint

A trained model ships inside the wheel, so generation works on a fresh install with no download and no training step:

>>> from neorx.genmol import load_pretrained
>>> model, tokenizer = load_pretrained()
>>> tokenizer.vocab_size
34
>>> sum(p.numel() for p in model.parameters())
4140322
>>> model.latent_dim
128

4.1 M parameters, a 128-dimensional latent space, and a 34-token vocabulary learned from ChEMBL 36.

The loader raises rather than degrading

load_pretrained never returns an untrained model. A randomly initialised VAE emits plausible-looking SMILES, so silent degradation here would be undetectable downstream — a missing or corrupt asset raises GenMolAssetError instead.

>>> from neorx.genmol import GenMolAssetError
>>> issubclass(GenMolAssetError, RuntimeError)
True

Sampling

>>> import torch
>>> from neorx.genmol import generate
>>> from neorx.molscreen import parse_smiles
>>> _ = torch.manual_seed(0)
>>> molecules = generate(model, tokenizer, n=20)
>>> 0 < len(molecules) <= 20
True
>>> all(parse_smiles(s) is not None for s in molecules)
True

generate validates with RDKit and deduplicates by default, so it returns at most n molecules. Both are switchable:

>>> _ = torch.manual_seed(0)
>>> raw = generate(model, tokenizer, n=20, validate=False, deduplicate=False)
>>> len(raw)
20

This page quotes no validity rate, deliberately

NeoRx's README reports 97% validity. That figure is not reproduced here, because nothing in this repository traces it to a run — and a quick local sample disagreed with it by enough that repeating either number would be guessing which one is right.

Measure it yourself rather than taking a figure on trust. validity is the fraction of raw decoder output that RDKit can parse, so the sample has to come from generate(..., validate=False, deduplicate=False) — passing it an already-filtered list measures the filter, not the model:

import torch
from neorx.genmol import load_pretrained, generate
from neorx.genmol.evaluation import validity

model, tokenizer = load_pretrained()
torch.manual_seed(0)
raw = generate(model, tokenizer, n=1000,
               validate=False, deduplicate=False)
print(validity(raw))

The result moves with the seed, the sample size and the PyTorch build, which is why no number from one run belongs on this page and why this block is not a doctest. A rate worth citing comes from the genmol-eval experiment, which writes a run record naming the code SHA, the dependency versions and the platform — see Experiments and run records.

Evaluating a sample

>>> from neorx.genmol.evaluation import validity, uniqueness, internal_diversity
>>> validity(["CCO", "c1ccccc1", "not-a-molecule"])
0.6666666666666666
>>> uniqueness(["CCO", "CCO", "c1ccccc1"])
0.6666666666666666

novelty compares against a reference set, internal_diversity averages pairwise Tanimoto distance, and compute_all_metrics runs the set. neorx.genmol.evaluation.distribution adds property-distribution comparison and a KS test against a reference library.

Interpolating in latent space

A VAE's selling point is a smooth latent space: nearby points should decode to similar molecules, which makes interpolation between two known drugs meaningful.

>>> from neorx.genmol import interpolate
>>> _ = torch.manual_seed(0)
>>> path = interpolate(model, tokenizer,
...                    "CC(=O)Oc1ccccc1C(O)=O",      # aspirin
...                    "CN1CCC[C@H]1c1cccnc1",       # nicotine
...                    n_steps=5)
>>> len(path)
5

The decoded path is not shown here, and that is deliberate: on this pair with this checkpoint, all five steps decode to the same molecule. The latent neighbourhood between these two points is flatter than the interpolation story implies. Treat interpolate as a tool for inspecting the latent space rather than as a source of novel candidates, and check what it actually returns for your pair.

Conditional generation

MolCVAE conditions on three scalar properties — molecular weight, LogP and QED — by concatenating a property vector to both the encoder input and the decoder's latent vector, so structure and properties are disentangled and you can ask for a target profile at generation time.

>>> from neorx.genmol import MolCVAE, PropertyNormalizer
>>> cvae = MolCVAE(vocab_size=tokenizer.vocab_size)
>>> cvae.latent_dim
128

No conditional checkpoint ships with the package; MolCVAE needs training before it generates anything meaningful. Use generate_conditional once you have one.

Training your own

>>> from neorx.genmol import TrainConfig
>>> config = TrainConfig()
>>> config.epochs, config.lr, config.grad_clip
(100, 0.001, 1.0)
>>> config.beta_start, config.beta_end, config.anneal_epochs
(0.01, 1.0, 10)

The KL annealing schedule is the part worth understanding. β on the KL term rises linearly from 0.01 to 1.0 over the first ten epochs; without annealing the model falls into posterior collapse, where the encoder ignores its input and the decoder degenerates into an unconditional language model that happens to emit valid SMILES.

From the command line:

neorx genmol download            # drug-like molecules from ChEMBL
neorx genmol train               # train the VAE
neorx genmol generate --n 100
neorx genmol evaluate
neorx genmol interpolate
neorx genmol screen              # pipe generated molecules through MolScreen

Design notes

GRU rather than LSTM — fewer parameters and faster training; SMILES sequences under 120 tokens do not need LSTM's extra gates.

Teacher forcing during training: the decoder receives the ground-truth previous token rather than its own prediction, which stabilises early training.

Three-layer bidirectional encoder, so the representation sees both forward and backward context in the string.

Next in the pipeline

Generated molecules go to MolScreen for drug-likeness and DockBot for binding, then to the composite scorer.