This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

This function can be used to change the tautomer state or a fix a broken valence state in a 3D molecule, based on a reference state (not required to be 3D). The function matches the substructures and transfers the state of the reference, like bond-orders, formal charge assignments, and hydrogen assignments to the input molecule. The input molecule can be smaller than the reference molecule, as this is intended to work for small molecule crystal structures where part of the molecule can have been degraded in the experiment. It also works for molecules that have been covalently bound to a protein, such that there is an R-group in place of the broken covalent bond. Due to symmetries in the substructure graph match, that are not unique in 3D, the function returns an iterator of output molecules where the state of the reference has been applied. An simple example would be a 3D molecule with two carboxylic acid groups on either side of a beneze ring. If the state being applied has one neutral carboxylic acid, and one negatively charged, two output molecules would have to be generated. While they are symmetric, if the 3D molecule is bound in a protein pocket, the two groups are not identical and one very likely fits the local environment better than the other, which will need to be checked.


The state of hydrogens being implicit or explicit in the output will match that of the state of the reference molecle.


The function currently ignores chirality of the two molecules, since this cannot be changed in a 3D molecule without conformational changes. However, the function will attempt to transfer chiral information on atoms and bonds from the reference state by setting the OEAtomBase::SetChiral flag to match the OEAtomBase::HasStereoSpecified flag from the reference state. The user is expected to call OE3DToAtomStereo to convert the chiral flag to atoms with specified stereo on 3D molecules.

OESystem::OEIterBase<OEMolBase> *
             OEApplyStateFromRef(const OEMolBase& input, const OEMolBase& refMol)

OESystem::OEIterBase<OEMolBase> *
             OEApplyStateFromRef(const OEMolBase& input, const std::string& refSmiles)

The SMILES version uses OEMolToSmiles to convert the incoming smiles to a molecule usable for the substructure search.

See also