Version Compatibility

Reference examples tested with: RDKit 2024.09+ (Open3DAlign), USRCAT 1.2+, ShaEP 1.7+, ROCS (OpenEye, commercial).

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Shape Similarity

Hard rules

1. No fabricated citations. Every cited work must resolve to a verifiable
2. No claim without provenance. Every quantitative or factual claim
3. No silent failure. Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero. A skill that silently swallows errors is a violation.

When to use

Load this skill when the user asks a question that matches its declared trigger conditions (see the frontmatter description for the most common ones). Do not load it for questions outside its scope — defer to the appropriate ORS skill instead.

When NOT to use

Do not load this skill if the question is in a sibling skill's domain (see ## Cross-references), if the user explicitly asks for a different tool, or if the task is outside the skill's declared category.

Shape Method Taxonomy

Decision: For commercial pipelines, ROCS is the gold standard. For open-source, Open3DAlign is the most accurate; USRCAT is the fastest for ultralarge libraries.

Decision Tree by Scenario

Tanimoto-Combo Scoring (ROCS Standard)

Tanimoto-Combo = (Tanimoto_shape + Tanimoto_color) / 2

• Tanimoto_shape: volume overlap normalized
• Tanimoto_color: pharmacophore feature overlap

In ROCS production, hits with TanimotoCombo > 0.7 are typically followed up.

USRCAT (Ultra-Fast Shape Recognition + Atom Types)

USRCAT extends Ultrafast Shape Recognition (USR) with atom-type information. Each molecule is represented as a 60-dimensional moment vector (12 moments × 5 atom types).

Goal: Encode a molecule into the 60-D USRCAT moment vector and score similarity against another molecule for alignment-free shape search.

Approach: Parse the SMILES, add hydrogens, generate one 3D conformer with ETKDGv3, compute USRCAT descriptors, and apply the inverse-mean-absolute-difference similarity to a second descriptor vector.

from usrcat import compute_usrcat_descriptors, compute_similarity

mol = Chem.MolFromSmiles('CCO')
mol = Chem.AddHs(mol)
AllChem.EmbedMolecule(mol, AllChem.ETKDGv3())

descriptors = compute_usrcat_descriptors(mol)
# Returns numpy array of 60 floats: 12 USR moments x 5 atom types
# (hydrophobic, aromatic, acceptor, donor, anion/cation)
# Similarity between two descriptor vectors: 1 / (1 + mean_abs_difference)

similarity = compute_similarity(desc1, desc2)  # 0-1, higher = more similar

Speed: O(N) descriptor calculation (no alignment); O(1) similarity comparison. Suitable for >10M compound libraries.

Limit: USRCAT is a coarse approximation. Predictive for analog identification; less precise for scaffold hopping.

Open3DAlign (RDKit)

Open3DAlign performs iterative alignment to maximize volume overlap:

Goal: Align a target molecule onto a query in 3D and score volume overlap with Open3DAlign.

Approach: Build 3D structures for query and target (parse SMILES, add hydrogens, ETKDG embed), run GetO3A to find the best alignment, then call Align() for the in-place RMSD and Score() for the overlap score.

from rdkit.Chem import rdMolAlign

query = Chem.MolFromSmiles('CCC(=O)Nc1ccccc1')
query = Chem.AddHs(query)
AllChem.EmbedMolecule(query, AllChem.ETKDGv3())

target = Chem.MolFromSmiles('CCC(=O)Nc1ccc(F)cc1')
target = Chem.AddHs(target)
AllChem.EmbedMolecule(target, AllChem.ETKDGv3())

O3A = rdMolAlign.GetO3A(target, query)
rmsd = O3A.Align()  # aligns target to query in place
score = O3A.Score()

GetO3A finds best alignment between conformers; Align() aligns and returns RMSD; Score() returns Open3DAlign score (similar to TanimotoCombo).

Open3DAlign vs ROCS: Open3DAlign is open-source and competitive on small benchmarks; slower than ROCS at scale.

Conformer-Ensemble Shape Searching

For each library molecule, generate ensemble of conformers; pick best-shape conformer:

Goal: Run shape-similarity search over a conformer ensemble per library molecule so bound-conformer-like shapes are recovered.

Approach: For each library molecule, add hydrogens, embed n_conf conformers with ETKDGv3, MMFF-optimize, score each conformer against the query with Open3DAlign, and keep the best score per molecule.

def shape_search_ensemble(query_mol, library_mols, n_conf=20):
    hits = []
    for target in library_mols:
        target = Chem.AddHs(target)
        AllChem.EmbedMultipleConfs(target, numConfs=n_conf,
                                    params=AllChem.ETKDGv3())
        AllChem.MMFFOptimizeMoleculeConfs(target)

        scores = []
        for c in range(target.GetNumConformers()):
            O3A = rdMolAlign.GetO3A(target, query_mol, prbCid=c)
            scores.append(O3A.Score())
        hits.append((target, max(scores)))
    return sorted(hits, key=lambda x: x[1], reverse=True)

Critical: Single-conformer shape search misses ~30% of true hits because the wrong conformer is sampled. Always use ensemble.

ESP Similarity (Electrostatic)

ShaEP and ESPSim extend shape with electrostatic surface potential overlap. For ESP-relevant pharmacophores (binding pockets with strong electrostatics):

shaep --query query.mol2 --target target.mol2 --output match.sdf \
      --esp-weight 0.5

ESP scoring catches electrostatic-equivalent bioisosteres that pure shape misses (carboxylate vs tetrazole same charge).

Shape vs ECFP4 Complementarity

The shape >> ECFP4 quadrant is the scaffold-hopping gold:

Goal: Identify scaffold-hop candidates that are 3D-shape-similar but 2D-chemotype-dissimilar to the query.

Approach: Run the conformer-ensemble shape search, keep hits above a shape Tanimoto cutoff, then retain only those whose ECFP4 Tanimoto to the query is below an ECFP4 dissimilarity cutoff.

def scaffold_hop_candidates(query_mol, library, shape_threshold=0.7,
                            ecfp_threshold=0.5):
    shape_hits = shape_search_ensemble(query_mol, library)
    candidates = []
    for target, shape_score in shape_hits:
        if shape_score >= shape_threshold:
            ecfp_sim = ecfp_tanimoto(query_mol, target)
            if ecfp_sim < ecfp_threshold:
                candidates.append((target, shape_score, ecfp_sim))
    return candidates

Per-Tool Failure Modes

USRCAT -- false positive on small molecules

Trigger: Library has many fragment-sized compounds. " Mechanism: USRCAT moments dominated by overall shape; small molecules look "similar" if shape resemble.

Symptom: Many fragment hits; not pharmacophore-relevant.

Fix: Filter by MW (>= 200); use Open3DAlign for rescoring.

Open3DAlign -- slow on large library

Trigger: Million-compound library, full alignment.

Mechanism: Open3DAlign is iterative; O(N) per molecule.

Symptom: Hours of compute.

Fix: Pre-filter with USRCAT (fast), Open3DAlign on top 10k.

Shape only -- wrong stereochemistry match

Trigger: Mirror-image of correct binder.

Mechanism: Pure shape Tanimoto symmetric under chirality inversion.

Symptom: Enantiomer of inactive scores as hit.

Fix: Validate hits by 3D pose; check stereochemistry.

ROCS color -- bioisostere missed

Trigger: -COOH replaced by -SO3H or tetrazole.

Mechanism: Default color types may not equate these bioisosteres.

Symptom: Known bioisostere doesn't score high.

Fix: Use color-only scoring without size penalty; or pharmacophore-feature-equivalence.

Conformer not bioactive

Trigger: Library compound generated conformer is not the bound conformation.

Mechanism: ETKDGv3 generates plausible conformers; bound conformer may be higher energy.

Symptom: Known active doesn't shape-match query.

Fix: Use larger conformer ensemble; weight by Boltzmann; or use CREST + GFN2-xTB for high-quality sampling.

Field-based methods slower

Trigger: ShaEP or ESPSim on production library.

Mechanism: Field-based methods compute Gaussian fields per molecule.

Symptom: 10-100x slower than ROCS shape-only.

Fix: Use as second-stage rescore; not primary screen.

Reconciliation: Shape vs Pharmacophore

Use shape for broad search (high recall, moderate precision); use pharmacophore for refinement (lower recall, high precision).

Common Errors

References

• Hawkins et al., J. Med. Chem. 50:74 -- ROCS algorithm.
• Schreyer & Blundell, J. Cheminformatics 4:27 -- USRCAT.
• Vainio & Johnson, J. Chem. Inf. Model. 47:2462 -- ShaEP.
• Liu et al., J. Chem. Inf. Model. (2024) -- Open3DAlign improvements.
• Roy et al., J. Med. Chem. 65:11875 -- shape-based VS modern review.

Related Skills

• chemoinformatics/molecular-io - Parse query and library
• chemoinformatics/conformer-generation - Generate 3D conformer ensembles
• chemoinformatics/similarity-searching - 2D similarity comparison
• chemoinformatics/pharmacophore-modeling - Pharmacophore alternative
• chemoinformatics/scaffold-analysis - 2D scaffold analysis
• chemoinformatics/virtual-screening - Shape as pre-filter to docking

Cross-references

Other skills in this category:

• admet-prediction
• conformer-generation
• covalent-design
• docking-rescoring
• free-energy-calculations
• generative-design
• molecular-descriptors
• molecular-io
• molecular-standardization
• pharmacophore-modeling
• pose-validation
• protac-degraders
• qsar-modeling
• retrosynthesis
• scaffold-analysis
• similarity-searching
• substructure-search
• virtual-screening

Changelog

• 1.1.0 (migration) — Bulk-migrated to v0.4.0 schema: canonical metadata block, base Hard rules, Cross-references. Body content unchanged; author should review and fill in any domain-specific extensions to the Hard rules.
• 1.0.0 — Initial release.