MoleculeModify

gives a molecule or list of molecules derived from the molecule mol by applying the modification "mod".

gives a molecule or list of molecules derived from the molecule mol by applying the modification "mod" with additional specifications specs.

MoleculeModify["mod"]

represents an operator form of MoleculeModify that can be applied to a molecule.

Details and Options

Atom Modifications

Operations that modify the molecule's atom list:

	{"AddAtom",atom}	add a disconnected atom
	{"AddAtom",{atom₁,atom₂,…}}	add a list of atoms
	{"DeleteAtom",a}	delete the atom with index a
	{"DeleteAtom",{a₁,a₂,…}}	delete the indicated atoms
	{"ReplaceAtom",aatom}	replace the atom with index a with atom
	{"ReplaceAtom",{a₁atom₁,…}}	replace atoms a_i with atom_i

atom should have one of the following forms:

	"sym"	atom with atomic symbol "sym" (e.g. "C", "Cl")
	Entity["Element",element]	atom of a given element
	Entity["Isotope",isotope]	atom of the specified isotope
	Atom["sym","prop"val,…]	atom with specified properties

"AddAtom" will add a disconnected atom, with no bonds to the rest of the molecule. To add a new atom and bond together use "AddBond".
"DeleteAtom" will remove any bonds to the atom in question.
When removing or replacing an atom, the number of explicit hydrogen atoms may be adjusted to maintain proper valence. Disconnected hydrogen atoms will be removed. To disable this behavior, use the option ValenceErrorHandlingFalse.
Implicit hydrogen atoms are added to the added atoms as normal. To disable implicit hydrogens, use "HydrogenCount"None in the new atom specification.
Operations that modify atom properties:

	{"SetFormalCharge",aval}	set the formal charge of the atom with index a to val
	{"SetMassNumber",aval}	set the mass number of the atom with index a to val
	{"SetUnpairedElectronCount",aval}	set the number of radical electrons for the given atom

To change a property for multiple atoms, use a list of rules {a₁val₁,a₂val₂,…}.

Bond Modifications

Operations that modify the molecule's bond list:

	{"AddBond",{a₁,a₂}}	add a single bond between atoms with indices a₁ and a₂
	{"AddBond",Bond[{a₁,a₂},"type"]}	add a bond of the given type between the given atoms
	{"AddBond",Bond[{a₁,atom},type]}	a bond between an atom with index a₁ and a new atom represented by atom
	{"DeleteBond",{a₁,a₂}}	remove the bond between the atoms with the given indices
	{"SetBondType",{a₁,a₂}"type"}	set the bond type for the bond between atoms with indices a₁ and a₂

General Modifications

	"SetAromaticity"	convert localized single and double bonds to aromatic
	"Kekulize"	convert aromatic bonds to localized single and double bonds
	{"RenumberAtoms",{a₁,a₂,…}}	reorder the atoms list so that the atom with index a_i appears at position i in the atoms list
	{"SetMetaInformation",meta}	set the molecule's MetaInformation to meta, which should be an association or key-value pair
	"MakeHydrogensExplicit"	convert any implicit hydrogens to explicit
	"MakeHydrogensImplicit"	remove explicit hydrogen atoms when their presence can be inferred by normal valence rules

Stereochemistry Modifications

Information about a molecule's 3D arrangement, independent of the 3D geometry, is stored in the StereochemistryElements option value. The following operations modify the stereo elements:

	"AssignStereochemistryFromCoordinates"	assign tetrahedral and double bond stereochemistry elements from 3D coordinates
	"RemoveStereochemistry"	remove any defined stereochemistry

To change the defined stereochemistry for an atom or bond, use one of the following operations:
{"SetAtomChirality",aval} set the chiral value for an atom to "R" or "S"

{"SetBondStereo",{a₁,a₂}val} set the bond stereo value to either "E" or "Z"
Changing the stereo for an atom or bond will affect the 3D coordinates that are generated on demand. If the molecule contains 3D coordinates already, these are discarded when changing the stereochemistry.

Substructure Replacement

	{"ReplaceSubstructure",pattrepl}	replace all occurrences of patt with repl
	{"ReplaceSubstructure",pattrepl,attchmts}	replace patt with repl, using the specified attachment points between pattern and replacement
	{"ReplaceSubstructureList",pattrepl}	replace each occurrence of patt with repl and return a list

Here repl should be a Molecule object or SMILES string, and patt can have one of the following forms:

	MoleculePattern[…]	a valid molecule pattern object
	{a₁,a₂,…}	a list of atom indices constituting a connected substructure
	{{a₁,a₂,…},{b₁,b₂,…},…}	a list of lists of atom indices, each of which will be replaced with repl

attchmts should be a list of rules {p₁r₁,…} from pattern atom index to replacement atom index. If no attachment points are provided, the first and last atoms from the pattern and replacement are matched.

Generating Coordinates

When a molecule is plotted in 3D or 2D, coordinates are taken from the AtomCoordinates and AtomDiagramCoordinates option values, respectively. If no coordinates are present in the molecule expression, they are generated automatically.
The following operations will precompute the automatic coordinates and return a Molecule object containing them:

	"ComputeAtomCoordinates"	compute automatic 3D coordinates for the molecule
	{"ComputeAtomCoordinates",opts}	compute atom coordinates using the options opts
	{"GenerateConformers",n}	compute 3D coordinates n times with a different seed value and return a list of molecules
	"ComputeAtomDiagramCoordinates"	compute 2D coordinates

"ComputeAtomCoordinates" will make all implicit hydrogens explicit in order to embed the molecule.
"ComputeAtomCoordinates" takes the following options:

"Canonicalize"	True	whether to canonicalize the coordinates
"EnergyMinimize"	True	whether to run a force-field minimization on the coordinates
RandomSeeding	1234	how to seed randomness

"GenerateConformers" will return unminimized conformers by default.
"ComputeAtomDiagramCoordinates" will make implicit those hydrogens attached to carbon, and make explicit those attached to a heteroatom, to match the default output of MoleculePlot. Use {"ComputeAtomDiagramCoordinates",IncludeHydrogensTrue} to include all atoms.

Geometry Modifications

To change the coordinates for a single atom, use:
{"SetAtomPosition",a{x,y,z}} set the position of the specified atom
To canonicalize atom coordinates without changing internal geometry, use:
"CanonicalizeAtomCoordinates" translate the molecule's center of mass to the origin and align the principal axes with the Cartesian axes
For general geometry transformations use the following:
{"TransformAtomCoordinates",tfun} apply the transformation function tfun to the coordinates
Here tfun should be a TransformationFunction object, e.g. TranslationTransform, ReflectionTransform, etc., or any arbitrary function that operates on and returns a QuantityArray object.
The following operations modify the internal coordinates:

	{"SetBondLength", {a₁,a₂}val}	set the bond length between the specified atoms
	{"SetBondAngle", {a₁,a₂,a₃}val}	set the angle between the specified atoms
	{"SetTorsionAngle",{a₁,a₂,a₃,a₄}val}	set the torsion angle for a group of four consecutively bonded atoms

These operations also support a list of length or angle changes, e.g. {{a₁,a₂}val₁,…}.
Here val should be a Quantity object or numeric. If numeric, the units are taken to be "Angstroms" or "AngularDegrees".
For "SetBondLength", atoms a₁ and a₂ must be bonded and the bond between them should not be in a ring. All atoms connected to atom a₂ are moved.
For "SetBondAngle", atoms {a₁,a₂} and {a₂,a₃} should be bonded and both bonds should not be in rings. All atoms connected to atom a₃ are moved.
For "SetTorsionAngle", atoms {a₁,a₂}, {a₂,a₃} and {a₃,a₄} should be bonded, and bond {a₂,a₃} should not be in a ring. All atoms connected to atom a₄ are moved.
To minimize the coordinates with respect to the MMFF force field, use the following:

	"EnergyMinimizeAtomCoordinates"	minimize the total force-field energy
	{"EnergyMinimizeAtomCoordinates",ff}	minimize the energy using the force field ff, one of "UFF", "MMFF94" or "MMFF94s"
	{"EnergyMinimizeAtomCoordinates",constraints}	minimize the energy with the given constraints added to the force field

constraints should be a list of bond, angle or torsion constraints of the following forms:

	{a₁,a₂}d	specify a distance between two atoms
	{a₁,a₂,a₃}θ	specify an angle among three atoms
	{a₁,a₂,a₃,a₄}θ	specify a torsion angle among four atoms
	<\|…\|>	an association with keys "Atoms", "Value" and "ForceConstant"

Examples

open allclose all

Basic Examples (4)

Add a carbon atom to propane:

Add a bond to the new atom:

Add a bond to turn hexane into cyclohexane:

Delete a bond to convert cyclohexane to hexane:

Replace all nitro groups in TNT with methyl groups:

Use "ReplaceSubstructureList" to replace one nitro group at a time:

Scope (37)

"AddAtom" (1)

Add an atom to a molecule:

Add a list of atoms:

"AddBond" (1)

Add a bond to a molecule:

Add a list of bonds to a molecule:

"AssignStereochemistryFromCoordinates" (1)

Use a molecule's 3D coordinates to infer stereochemistry. First create a molecule with atoms, bonds and coordinates, but no defined stereochemistry:

"CanonicalizeAtomCoordinates" (1)

Import a structure from an "XYZ" file and canonicalize the 3D coordinates:

After importing, compute the molecule's center of mass and principal axes:

"CanonicalizeAtomCoordinates" will translate the molecule, move the center of mass to the origin and rotate to align the principal axes with the Cartesian axes:

"ComputeAtomCoordinates" (2)

When a molecule is created from an identifier like a SMILES string or name, coordinates are not computed immediately:

Use "ComputeAtomCoordinates" to compute the coordinates and store them in the molecule expression:

Generate different conformations using the RandomSeeding option:

The resulting molecules have different conformational energy:

"ComputeAtomDiagramCoordinates" (2)

When a molecule is visualized in 2D using MoleculePlot, hydrogen atoms attached to carbon atoms are hidden by default. Only the hydroxyl hydrogen is shown by default in octanol:

"ComputeAtomDiagramCoordinates" will remove those hydrogens that are not shown, and make explicit those that are shown:

The coordinates are now stored in the molecule expression:

As there is only one hydrogen shown by default, the returned molecule has one explicit hydrogen:

The coordinates match exactly those used in a molecule plot:

Compute the atom diagram coordinates showing the default hydrogens, all hydrogens or none:

"DeleteAtom" (2)

Convert hexanol to hexane using "DeleteAtom":

Find an Entity to match:

When an atom is deleted, any hydrogens attached to it are also removed, and unfilled valences on heavy atoms are filled by implicit hydrogens. Use ValenceErrorHandling->False to disable this behavior and leave unpaired electrons instead:

"DeleteBond" (2)

Delete an acyclic bond to create disconnected structures:

Delete a ring bond:

"EnergyMinimizeAtomCoordinates" (1)

Import a structure from an "XYZ" file and use the MMFF force field to minimize the energy:

Verify that the conformational energy has lowered:

Show the new structure together with the old:

"GenerateConformers" (1)

It is often desirable to have a set of conformations for a molecule, for example, to sample a larger portion of the energy landscape. Generate 100 conformers for cyclohexane:

The conformers will have a large energy spread:

After minimizing the conformations using a force field, they fall into two groups energetically:

These groupings correspond to the so-called "chair" and "twist-boat" conformations, which are global and local minima on the potential energy surface, respectively. Select one conformer from each group and plot in 3D:

"Kekulize" (1)

By default, aromatic molecules have delocalized "Aromatic" bond types:

"MakeHydrogensImplicit" (1)

Remove all the hydrogen atoms from a molecule:

"RemoveStereochemistry" (1)

Remove explicit stereo information from a molecule, leaving the chirality undefined:

"RenumberAtoms" (1)

Change the ordering of atoms in a molecule:

"ReplaceAtom" (1)

Replace specific atoms in a molecule with a different atom type; for example, convert acetic acid to thioacetic acid:

"ReplaceSubstructure" (1)

Replace the hydroxyl in the aliphatic D ring of estradiol with a carbonyl to make estrone:

"ReplaceSubstructureList" (1)

Make each of the methyl ethers of glycerol:

"SetAromaticity" (1)

Change localized single and double bonds to aromatic:

"SetAtomChirality" (1)

Convert D-glucose to D-mannose:

"SetAtomPosition" (1)

Import a molecule and set the coordinate for a single atom:

"SetBondAngle" (3)

Set the angle between three atoms:

Set multiple bond angles:

Angles cannot be set for nonbonded atoms:

Bond angles in a ring cannot be set:

"SetBondLength" (1)

Set the distance between two bonded atoms:

"SetBondStereo" (1)

Convert natural E-cinnamaldehyde to the Z-form:

"SetBondType" (1)

"SetFormalCharge" (1)

Make the zwitterion of phenylalanine:

"SetMassNumber" (1)

Label the C-2 of mevalonolactone with ¹³C by setting the mass number to 13:

Use AtomList to find the labeled carbon:

Label the 5-pro-S hydrogen of mevalonolactone with deuterium by setting the mass number to 2:

"SetMetaInformation" (1)

Often, laboratories use a compound numbering system for samples and notebooks, and these identification numbers are used by chemists when writing internal reports, research papers and patents. Use the molecule's meta-information to store this kind of data.

Add metadata to a molecule:

Store experimental data in this property:

Use an empty association to remove the metadata:

"SetTorsionAngle" (1)

Set the geometry of a molecule to a desired conformation, for example, for an internal hydrogen bond:

"SetUnpairedElectronCount" (1)

Create a hydroxy radical by modifying water:

"TransformAtomCoordinates" (2)

Create a copy of a molecule with the coordinates translated in space:

Create a molecule's enantiomer using ReflectionTransform:

Neat Examples (1)

Add distance constraints to the MMFF force field to find a conformation with a given distance between two atoms. First, create the base molecule:

Find the two atoms that are farthest away in the standard configuration:

The default conformation has these two atoms 32 ångströms apart:

Use "EnergyMinimizeAtomCoordinates" to find new conformations with specific separations for these atoms:

Verify that the returned geometries match the requirement and get the force field energies:

Top

	{"SetAtomChirality",aval}	set the chiral value for an atom to "R" or "S"
	{"SetBondStereo",{a₁,a₂}val}	set the bond stereo value to either "E" or "Z"