Substructure & MCS Search for Chemical Graphs

SMSD Pro is an open-source toolkit for exact substructure search and maximum common substructure (MCS) finding in chemical graphs. It runs on Java, C++ (header-only), and Python, with GPU acceleration (CUDA + Apple Metal). Built on established algorithms from the graph-isomorphism literature (VF2++, McSplit, McGregor, Horton, Vismara).

Copyright (c) 2018-2026 Syed Asad Rahman — BioInception PVT LTD

<dependency>
  <groupId>com.bioinceptionlabs</groupId>
  <artifactId>smsd</artifactId>
  <version>6.2.1</version>
</dependency>

curl -LO https://github.com/asad/SMSD/releases/download/v6.2.1/smsd-6.2.1-jar-with-dependencies.jar

java -jar smsd-6.2.1-jar-with-dependencies.jar \
  --Q SMI --q "c1ccccc1" --T SMI --t "c1ccc(O)cc1" --json -

pip install smsd

import smsd

result = smsd.substructure_search("c1ccccc1", "c1ccc(O)cc1")
mcs    = smsd.mcs("c1ccccc1", "c1ccc2ccccc2c1")

# Tautomer-aware MCS
mcs    = smsd.mcs("CC(=O)C", "CC(O)=C", tautomer_aware=True)

# Similarity upper bound (fast pre-filter)
sim    = smsd.similarity("c1ccccc1", "c1ccc(O)cc1")

fp     = smsd.fingerprint("c1ccccc1", kind="mcs")

# Circular fingerprint (ECFP4 equivalent, tautomer-aware)
ecfp4 = smsd.circular_fingerprint("c1ccccc1", radius=2, fp_size=2048)

SMSD works standalone or alongside RDKit. Use RDKit for parsing, descriptors, and drawing; use SMSD for fast MCS and substructure matching.

RDKit molecules + SMSD matching (recommended for existing RDKit workflows):

from rdkit import Chem
import smsd

mol1 = Chem.MolFromSmiles("c1ccccc1")
mol2 = Chem.MolFromSmiles("c1ccc(O)cc1")

# MCS via SMSD -- pass RDKit Mol objects directly
result = smsd.mcs_rdkit(mol1, mol2)

# Substructure search
mapping = smsd.substructure_rdkit(mol1, mol2)

# Convert once, reuse with any SMSD function
g = smsd.from_rdkit(mol1)
sim = smsd.similarity(g, smsd.from_rdkit(mol2))

SMSD standalone (no RDKit needed):

import smsd

result = smsd.mcs("c1ccccc1", "c1ccc(O)cc1")
mapping = smsd.substructure_search("c1ccccc1", "c1ccc(O)cc1")
sim = smsd.similarity("c1ccccc1", "c1ccc(O)cc1")

CDK (Java) for parsing + SMSD for matching:

import com.bioinception.smsd.core.*;
import org.openscience.cdk.silent.SilentChemObjectBuilder;
import org.openscience.cdk.smiles.SmilesParser;

SmilesParser sp = new SmilesParser(SilentChemObjectBuilder.getInstance());
var mol1 = sp.parseSmiles("c1ccccc1");
var mol2 = sp.parseSmiles("c1ccc(O)cc1");

SMSD smsd = new SMSD(mol1, mol2, new ChemOptions());
boolean isSub = smsd.isSubstructure();
var mcs = smsd.findMCS();

Performance note: RDKit is an optional dependency -- SMSD does not require it. The helpers convert via a SMILES round-trip (sub-millisecond overhead). For batch workloads, convert once with from_rdkit() and reuse the MolGraph objects.

Use SMSD for matching, RDKit for visualization and export:

import smsd

# Depict MCS with highlighted atoms (works in Jupyter)
img = smsd.depict_mcs("c1ccccc1", "c1ccc(O)cc1")
img.save("mcs.png")

# Depict substructure match
img = smsd.depict_substructure("c1ccccc1", "c1ccc(O)cc1")

# Generate SVG
svg = smsd.to_svg("c1ccccc1")

# Export to SDF file
mols = [smsd.parse_smiles(s) for s in ["CCO", "c1ccccc1", "CC(=O)O"]]
smsd.export_sdf(mols, "output.sdf")

# Convert to RDKit Mol for any RDKit function
rdmol = smsd.to_rdkit(smsd.parse_smiles("c1ccccc1"))

git clone https://github.com/asad/SMSD.git
# Add SMSD/cpp/include to your include path — no other dependencies needed

#include "smsd/smsd.hpp"

auto mol1 = smsd::parseSMILES("c1ccccc1");
auto mol2 = smsd::parseSMILES("c1ccc(O)cc1");

bool isSub = smsd::isSubstructure(mol1, mol2, smsd::ChemOptions{});
auto mcs   = smsd::findMCS(mol1, mol2, smsd::ChemOptions{}, smsd::McsOptions{});

git clone https://github.com/asad/SMSD.git
cd SMSD

# Java
mvn -U clean package

# C++
mkdir cpp/build && cd cpp/build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Python
cd python && pip install -e .

docker build -t smsd .
docker run --rm smsd --Q SMI --q "c1ccccc1" --T SMI --t "c1ccc(O)cc1" --json -

Same machine, same Python process, best of 5 runs. Full data: benchmarks/results_python.tsv

SMSD faster on 17/19 pairs. Speedups range from 1.5x to 11,200x. Bold = SMSD found a larger MCS. timeout = 10 s limit.

28/28 pairs correct — all match CDK. Cached speedup: 2x-16x faster across all pairs.

Run python benchmarks/benchmark_python_vs_rdkit.py to reproduce.

VF2++ (Juttner & Madarasi 2018) with FASTiso/VF3-Light matching order, 3-level NLF pruning, bit-parallel candidate domains, and GPU-accelerated domain initialization (CUDA + Metal).

Horton's candidate generation + 2-phase GF(2) elimination (Vismara 1997) for relevant cycles, orbit-based grouping for Unique Ring Families (URFs).

Preset profiles: ChemOptions() (default), .tautomerProfile(), .fmcsProfile() (RDKit-compatible)

Solvent-aware tautomers (Tier 2 pKa): opts.withSolvent(Solvent.DMSO) adjusts tautomer equilibrium weights for non-aqueous environments.

GPU acceleration covers RASCAL batch screening and domain initialization. Recursive backtracking (VF2++, BK, McSplit) runs on CPU. Dispatch: CUDA -> Metal -> OpenMP -> sequential.

Every release includes all platforms:

# Native installer — download .dmg / .msi / .deb, double-click, done

# CLI
java -jar smsd-6.2.1-jar-with-dependencies.jar --Q SMI --q "c1ccccc1" --T SMI --t "c1ccc(O)cc1" --json -

# Docker CLI
docker build -t smsd .
docker run --rm smsd --Q SMI --q "c1ccccc1" --T SMI --t "c1ccc(O)cc1" --json -

# Python
pip install smsd

• 1,082 Java tests (7 consolidated suites) — heterocycles, reactions, drug pairs, tautomers, stereochemistry, ring perception, URF families, hydrogen handling, adversarial edge cases, fast-path validation, solvent corrections
• 170 C++ tests (3 suites) — 63 core + 91 parser (including SMARTS X primitive) + 16 batch/GPU
• 1,003 diverse molecules — all parse correctly in C++ SMILES parser
• AddressSanitizer — zero memory errors
• Python tests — full API coverage including hydrogen handling and charged species

If you use SMSD Pro in your research, please cite:

Rahman SA, Bashton M, Holliday GL, Schrader R, Thornton JM. Small Molecule Subgraph Detector (SMSD) toolkit. Journal of Cheminformatics, 1:12, 2009. DOI: 10.1186/1758-2946-1-12

GitHub renders a "Cite this repository" button from CITATION.cff.

Syed Asad Rahman — BioInception PVT LTD

Copyright (c) 2018-2026 BioInception PVT LTD. Algorithm Copyright (c) 2009-2026 Syed Asad Rahman.

Apache License 2.0 — see LICENSE and NOTICE