QWE AI Academy By the end of this guide you’ll have REINVENT 4.7 installed, a working RNN prior loaded from Zenodo, and a first reinforcement-learning run producing new SMILES against a scoring function you control. As of November 2026, v4.7 is the latest release. Setup is where most people trip – so we walk backwards from a working run through every failure mode.
The original MolecularAI/Reinvent repository is archived and read-only. All active development is on REINVENT 4. If you’re following a tutorial that still uses input.py some_running_mode.json, close it.
What you’re actually installing
Four generators. Three optimization algorithms. One command-line entry point. REINVENT 4 is an open-source generative AI tool for small molecule design, published by AstraZeneca’s Molecular AI group under Apache 2.0 (github.com/MolecularAI/REINVENT4). The generators cover de novo design, scaffold decoration, linker design, and molecule optimization. They’re paired with three optimization algorithms: transfer learning, reinforcement learning, and curriculum learning. Configuration is TOML or JSON – though as of v4.7, the shipped examples are TOML-only (more on that below).
The RL loop is worth understanding before you touch a config file. The de novo generator is an RNN trained on ChEMBL v22. During an RL run, the agent starts as a copy of that prior, samples SMILES, and gets scored by a Multi-Parameter Optimization function. The reward is the augmented likelihood: log P_aug(x) = log P_prior(x) + MPO(x). That formula, documented in the uncertainty-aware RL paper on arXiv, is doing exactly what it looks like – pulling the agent toward higher-scoring chemistry while keeping it tethered to drug-like space via the prior.
That tether is the design choice that makes REINVENT different from unconstrained generative models. If your MPO is badly calibrated, the agent drifts toward whatever it can exploit – not toward useful molecules. Reward design is the real work here, not the install.
The 2024 Journal of Cheminformatics paper is the best reference before your first serious run.
System requirements
REINVENT is Linux-first. macOS and Windows paths exist but expect friction. Check the README for current hardware minimums – the numbers shift between releases. What doesn’t shift: Python must be 3.10, and your NVIDIA driver must support CUDA 12.6 or newer. The PyTorch index for CUDA 12.6 is pre-configured in pyproject.toml. A driver mismatch won’t stop pip install – it’ll stop your first run. That’s the trap.
| Component | Required | Notes |
|---|---|---|
| OS | Linux (Ubuntu 20.04+) | Ubuntu 22.04 preferred |
| Python | 3.10 | 3.11 may work; 3.10 is tested |
| GPU | Optional | CPU works, slowly; NVIDIA CUDA 12.6+ driver if using GPU |
| Dependency manager | uv (current) or conda + pip | uv respects the lock file |
Install REINVENT 4.7 (uv sync path)
The README’s primary path is now uv. It’s faster than pip and – the important part – it respects the lock file so you get reproducible installs.
git clone --depth 1 https://github.com/MolecularAI/REINVENT4.git
cd REINVENT4
uv sync # core dependencies
# optional extras:
uv sync --extra isim # iSIM similarity tracking in TensorBoard
uv sync --extra all # + OpenEye ROCS (needs a license)After that, a reinvent script lands on your PATH. That’s the entry point for every run.
Legacy path still works if your HPC modules don’t have uv:
conda create --name reinvent4 python=3.10
conda activate reinvent4
cd REINVENT4
python install.py cu126 # explicit CUDA tag - do not skip thisAlways pass an explicit CUDA tag to install.py. Skip it and you may get cu130 wheels on a CUDA 12.x host. The install succeeds. Then
torch.cuda.init()explodes at runtime.
Smoke test: sampling config
Grab a pretrained prior from Zenodo – all public prior models are hosted there. Download reinvent.prior (the de novo RNN) and place it under priors/.
Minimal sampling config, save as sampling.toml:
run_type = "sampling"
device = "cuda:0" # or "cpu"
json_out_config = "_sampling.json"
[parameters]
model_file = "priors/reinvent.prior"
output_file = "sampled.csv"
num_smiles = 100
unique_molecules = true
randomize_smiles = truereinvent -l sampling.log sampling.toml
reinvent --version # confirms the binary is on PATH100 rows of valid SMILES in sampled.csv means the install is real. Zero rows or a CUDA error – keep reading.
The v4.7 gotchas
1. The CUDA 13 driver wall
This one has burned a lot of HPC installs. Per GitHub issue #351, REINVENT 4.8.24 pulls PyTorch cu130 wheels. On a host with CUDA 12.x drivers, you get: RuntimeError: The NVIDIA driver on your system is too old (found version 12080). The pip install completes without complaint. The crash only appears at runtime when CUDA initializes.
Fix: force CUDA 12.8 wheels explicitly.
conda create -n reinvent4 python=3.10
conda activate reinvent4
python install.py cu128On uv, override the torch index URL in pyproject.toml to https://download.pytorch.org/whl/cu128 before running uv sync.
2. install.py hard-pins torch – breaks AMD and non-standard CUDA
Turns out install.py forces a specific PyTorch build, which fails entirely on AMD ROCm. The fix, documented by AMD’s ROCm team on their MI300X blog post: remove the torch and torchvision entries from pyproject.toml before install, then install your preferred PyTorch build manually and run pip install --no-deps .. Same trick works outside Docker – sed them out, install, proceed.
3. v4.7 quietly removed JSON config examples
The catch: per the v4.7 release notes, JSON configuration examples were removed from the repo and a conversion script was added in their place. Old JSON configs still parse – but copy-paste from a 2024 tutorial and you’ll silently miss scoring components that were renamed. Convert first with the bundled script, run second.
4. No official Docker image
As of v4.7, there’s no AstraZeneca-published image on Docker Hub. Every containerized deployment online – AMD’s, various academic labs’ – is a homegrown Dockerfile. If reproducibility matters for your team, pin the git SHA and the lock file. Don’t rely on an image someone else built.
Upgrade and uninstall
Minor version bump: git pull && uv sync, usually enough. Jumping from v3 to v4, or moving off the archived MolecularAI/Reinvent repo – treat it as a fresh install. The codebase was rewritten, configs are incompatible, and the entry point changed from input.py to reinvent.
To remove: conda env remove -n reinvent4, then delete the cloned repo. Prior model files under priors/ and TensorBoard logs won’t be touched – delete those manually if disk space matters.
FAQ
Do I need a GPU to run REINVENT 4?
No. CPU works. For anything beyond a quick smoke test – thousands of RL steps against a docking scorer – you’ll want a GPU or you’ll be waiting a long time.
Why does my RL run produce the same molecules over and over?
Mode collapse: the agent found a high-scoring local minimum and stopped exploring. Two things usually help – turn on the diversity filter in your TOML, and lower sigma in the RL parameters block. But if your MPO is dominated by a single component (QED alone, say), the agent will exploit it regardless of those settings. The augmented likelihood formula is doing exactly what it’s told. The fix is upstream in the reward design: balance the scoring function first, then adjust RL hyperparameters. Retuning sigma on a bad MPO just changes how fast the collapse happens.
Can I use a custom scoring function like a docking score or QSAR model?
Yes – drop a Python file under reinvent_plugins/components/ and it registers automatically. No __init__.py in that directory, though.
Next step: Once reinvent sampling.toml produces valid SMILES, swap run_type = "sampling" for run_type = "staged_learning", wire in a scoring function, and start your first RL job.