WOLFRAM

Wolfram Language & System Documentation Center

MoleculeSubstructureCases[mol,patt]

gives a list of molecule substructures representing each occurrence of patt in mol.

MoleculeSubstructureCases[mol,patt,n]

includes only the first n substructures.

MoleculeSubstructureCases[mol,patt,n,"prop"]

gives a list with the given property for each substructure.

Details and Options
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Options  
IgnoreStereochemistry  
IncludeHydrogens  
Overlaps  
Neat Examples  
See Also
Related Guides
History
Cite this Page

MoleculeSubstructureCases

MoleculeSubstructureCases[mol,patt]

gives a list of molecule substructures representing each occurrence of patt in mol.

MoleculeSubstructureCases[mol,patt,n]

includes only the first n substructures.

MoleculeSubstructureCases[mol,patt,n,"prop"]

gives a list with the given property for each substructure.

Details and Options

  • MoleculeSubstructureCases is used to find functional groups or other structural motifs within a molecule.
  • "prop" can be one of the following:
  • "MoleculeSubstructure"MoleculeSubstructure objects
    "AtomList"list of matching atoms
    "BondLists"list of matching bonds
    "AtomIndices"list of matching atom indices
    "BondIndices"list of matching bond indices
  • MoleculeSubstructureCases takes the following options:
  • IgnoreStereochemistry Falsewhether to ignore stereochemistry
    IncludeHydrogens Automaticwhether to include hydrogen atoms
    Overlaps Falsewhether to include matches that overlap
  • By default, substructure matches are pruned to remove multiple matches to the same set of atoms. Use the option Overlaps->True to disable this behavior.

Examples

open all close all

Basic Examples  (1)

Find all occurrences of a six-membered aromatic ring in a molecule:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"C", "C", "C", "C", "N", "S", "O", "O", "C", "C", "C", "C", "C", "C", "S", "C", "N", "C", Atom["C", "HydrogenCount" -> 1], Atom["C", "HydrogenCount" -> 1], "C", "C", "C", "C", "C", "C", "C", "N", "C", "O", "O", Atom["C", "HydrogenCo ... 32, "Direction" -> "Clockwise"], Association["StereoType" -> "Tetrahedral", "ChiralCenter" -> 35, "Direction" -> "Counterclockwise"], Association["StereoType" -> "Tetrahedral", "ChiralCenter" -> 36, "Direction" -> "Clockwise"]}}], MoleculePattern["a1aaaaa1"]]

Find only the first occurrence:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"C", "C", "C", "C", "N", "S", "O", "O", "C", "C", "C", "C", "C", "C", "S", "C", "N", "C", Atom["C", "HydrogenCount" -> 1], Atom["C", "HydrogenCount" -> 1], "C", "C", "C", "C", "C", "C", "C", "N", "C", "O", "O", Atom["C", "HydrogenCo ... 32, "Direction" -> "Clockwise"], Association["StereoType" -> "Tetrahedral", "ChiralCenter" -> 35, "Direction" -> "Counterclockwise"], Association["StereoType" -> "Tetrahedral", "ChiralCenter" -> 36, "Direction" -> "Clockwise"]}}], MoleculePattern["a1aaaaa1"], 1]

Scope  (4)

Use an atomic symbol string as a pattern:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"O", "H", "H"}, {Bond[{1, 2}, "Single"], Bond[{1, 3}, "Single"]}, {}], "O"]
Wolfram Language code: MoleculeSubstructureCases[Molecule[{"O", "H", "H"}, {Bond[{1, 2}, "Single"], Bond[{1, 3}, "Single"]}, {}], "H"]

Indicate charge or mass number in the atomic symbol:

Wolfram Language code: m = Molecule[{Atom["C"], Atom["C", "MassNumber" -> 14], Atom["O"], Atom["O", "FormalCharge" -> -1], Atom["H"], Atom["H"], Atom["H"]}, {Bond[{1, 2}, "Single"], Bond[{2, 3}, "Double"], Bond[{2, 4}, "Single"], Bond[{1, 5}, "Single"], Bond[{1, 6}, "Single"], Bond[{1, 7}, "Single"]}];
Wolfram Language code: MoleculeSubstructureCases[m, Atom["O", "FormalCharge" -> -1]]
Wolfram Language code: MoleculeSubstructureCases[m, Atom["C", "MassNumber" -> 14]]

Use Atom to make a more general pattern. Find all charged atoms:

Wolfram Language code: MoleculeSubstructureCases[Entity["Chemical", "Methyl4Nitrobutyrate"], Atom["FormalCharge" -> Except[0]]]

Find positively charged atoms:

Wolfram Language code: MoleculeSubstructureCases[Entity["Chemical", "Methyl4Nitrobutyrate"], Atom["FormalCharge" -> GreaterThan[0]]]

Find negatively charged atoms:

Wolfram Language code: MoleculeSubstructureCases[Entity["Chemical", "Methyl4Nitrobutyrate"], Atom["FormalCharge" -> LessEqualThan[-1]]]

Use Bond to define a pattern for any double bond:

Wolfram Language code: m = Molecule["2-[[(1E,4E)-1,5-bis(5-nitrofuran-2-yl)penta-1,4-dien-3-ylidene]amino]guanidine"]
Wolfram Language code: MoleculeSubstructureCases[m, Bond[_, "Double"], All, "Bonds"]

Find only double bonds with a nitrogen atom:

Wolfram Language code: MoleculeSubstructureCases[m, Bond[{"N", _}, "Double"], All, "BondIndices"]

Find double bonds with a charged atom:

Wolfram Language code: MoleculeSubstructureCases[m, Bond[{Atom["FormalCharge" -> Except[0]], _}, "Double"]]

Options  (3)

IgnoreStereochemistry  (1)

By default, stereoisomers do not match:

Wolfram Language code: MoleculeSubstructureCases[Molecule["l-alanine"], MoleculePattern["C[C@@H](N)C(=O)O"]]

Use IgnoreStereochemistryTrue to get a positive match:

Wolfram Language code: MoleculeSubstructureCases[Molecule["l-alanine"], MoleculePattern["C[C@@H](N)C(=O)O"], IgnoreStereochemistry -> True]

IncludeHydrogens  (1)

By default, substructure matching is performed using a molecule's hydrogen-suppressed graph, unless the pattern contains explicit hydrogen atoms:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"C", "C", "C", "Cl"}, {Bond[{1, 2}, "Single"], Bond[{2, 3}, "Single"], Bond[{2, 4}, "Single"]}, {}], Bond[{"C", "H"}, "Single"], All, "AtomIndices"]

Some matches to hydrogen will be missed for more involved patterns. In the following example, the pattern is for a carbon atom bonded to either a hydrogen or chlorine atom, but only finds the C-Cl bond:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"C", "C", "C", "Cl"}, {Bond[{1, 2}, "Single"], Bond[{2, 3}, "Single"], Bond[{2, 4}, "Single"]}, {}], Bond[{"C", Atom["AtomicNumber" -> (1 | 17)]}, "Single"], All, "AtomIndices"]

Use the option IncludeHydrogensTrue to make sure hydrogens are treated as explicit for the purposes of pattern matching:

Wolfram Language code: MoleculeSubstructureCases[Molecule[{"C", "C", "C", "Cl"}, {Bond[{1, 2}, "Single"], Bond[{2, 3}, "Single"], Bond[{2, 4}, "Single"]}, {}], Bond[{"C", Atom["AtomicNumber" -> (1 | 17)]}, "Single"], All, "AtomIndices", IncludeHydrogens -> True]

Overlaps  (1)

By default, substructure matches are pruned to remove multiple matches to the same set of atoms:

Wolfram Language code: MoleculeSubstructureCases[Molecule["hexane"], MoleculePattern["CCCCC"], All, "AtomIndices"]

Use the option OverlapsTrue to find all possible matchings between the pattern and molecule:

Wolfram Language code: MoleculeSubstructureCases[Molecule["hexane"], MoleculePattern["CCCCC"], All, "AtomIndices", Overlaps -> True]

Neat Examples  (1)

Monoterpenes are naturally occurring molecules that contain two 5-carbon isoprene units:

Wolfram Language code: monoterpenePattern = MoleculePattern["[#6]~[#6](~[#6])~[#6]~[#6].[#6]~[#6](~[#6])~[#6]~[#6]"]

Here is the monoterpene menthol:

Wolfram Language code: mol = Molecule[Entity["Chemical", "DLMenthol"]]

Find all the ways the two isoprene units can be mapped onto the menthol molecule:

Wolfram Language code: MoleculeSubstructureCases[mol, monoterpenePattern, Overlaps -> True]//Short

Visualize the substructures in place:

Wolfram Language code: Multicolumn[MoleculePlot /@ %]
Wolfram Research (2026), MoleculeSubstructureCases, Wolfram Language function, https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html.

Text

Wolfram Research (2026), MoleculeSubstructureCases, Wolfram Language function, https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html.

CMS

Wolfram Language. 2026. "MoleculeSubstructureCases." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html.

APA

Wolfram Language. (2026). MoleculeSubstructureCases. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html

BibTeX

@misc{reference.wolfram_2026_moleculesubstructurecases, author="Wolfram Research", title="{MoleculeSubstructureCases}", year="2026", howpublished="\url{https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html}", note=[Accessed: 12-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_moleculesubstructurecases, organization={Wolfram Research}, title={MoleculeSubstructureCases}, year={2026}, url={https://reference.wolfram.com/language/ref/MoleculeSubstructureCases.html}, note=[Accessed: 12-June-2026]}