Package chemaxon.marvin.calculations

Class TautomerizationPlugin

java.lang.Object
chemaxon.marvin.plugin.CalculatorPlugin
chemaxon.marvin.calculations.TautomerizationPlugin
All Implemented Interfaces:
TaggedCalculator, chemaxon.license.Licensable
@PublicAPI public final class TautomerizationPlugin extends CalculatorPlugin
Plugin class for generating tautomer structures.

API usage example: 

    // read input molecule
    MolImporter mi = new MolImporter("test.mol");
    Molecule mol = mi.read();

    // create plugin
    TautomerizationPlugin plugin = new TautomerizationPlugin();

    // set dominant tautomer distribution calculation
    plugin.setDominantTautomerDistributionCalculation(true);

    // set pH (consider pH effect at this pH; only has effect when dominant tautomers are generated)
    plugin.setpH(7.4);

    // set the input molecule
    plugin.setMolecule(mol);

    // run the calculation
    plugin.run();

    // get the dominant tautomers
    System.out.println("Dominant tautomer distribution");
    int count = plugin.getStructureCount();
    for (int i=0; i < count; ++i) {
        Molecule tautomer = plugin.getStructure(i);
        double distribution = plugin.getDominantTautomerDistribution(i);
        System.out.println(tautomer.toFormat("smiles") + "  " + distribution);
    }

For concurrent plugin example applications using ChemAxon's concurrent framework, refer to the Concurrent plugin examples.

Since:
Marvin 4.0

  • Field Details

    • warningMsgOn

      public static boolean warningMsgOn

  • Constructor Details

    • TautomerizationPlugin

      public TautomerizationPlugin()
      Constructor. Creates the tautomerization object.

  • Method Details

    • getProductName

      public String getProductName()
      Returns the product identifier of the plugin as given by LicenseManager.
      Specified by:
      getProductName in class CalculatorPlugin
      Returns:
      The identifier LicenseManager.ISOMERS_PLUGIN_GROUP

    • hasTautomers

      public static boolean hasTautomers(Molecule mol)
      Returns if a molecule has tautomers.
      Parameters:
      mol - the molecule
      Returns:
      true if molecule has tautomers
      Since:
      Marvin 5.12

    • handlesMultiFragmentMolecules

      public boolean handlesMultiFragmentMolecules()
      Returns true if the plugin handles multifragment molecules, false otherwise. In the latter case the plugin takes the fragment with more atoms if a multifragment molecule is given as input. Returns true if parameter "single" is set to "false", false otherwise (default: false).
      Overrides:
      handlesMultiFragmentMolecules in class CalculatorPlugin
      Returns:
      true if the plugin handles multifragment molecules, false otherwise

    • setProgressMonitor

      public void setProgressMonitor(MProgressMonitor pmon)
      Sets a progress observer to be used in run() to display progress status. Short calculations may ignore the observer object. The default implementation does nothing.
      Overrides:
      setProgressMonitor in class CalculatorPlugin
      Parameters:
      pmon - is the progress monitor, may be null

    • setParameters

      public void setParameters(Properties params) throws PluginException
      Sets the input parameters for the plugin. Tautomerization parameters and value ranges:
      • single: "true" if single fragment mode (calculation is performed separately for each fragment) (default: "false")
      • type: structure,structures,count
      • max: max structure count
      • pH: consider pH effect at this pH (default: Double.NaN - do not consider pH effect)
      • symfilter: true if filter symmetrical structures, false if allow duplicates (default: true)
      • canonical: "true" if canonical form should be taken (default: "false")
      • major: "true" if major tautomer should be taken (default: "false")
      • dominants: "true" if take dominant tautomers, "false" otherwise (default: "false")
      • distribution: "true" if calculate dominant tautomer distribution, "false" otherwise (default: "false")
      Overrides:
      setParameters in class CalculatorPlugin
      Parameters:
      params - is the parameter table
      Throws:
      PluginException - on error

    • setChemicalTermsArgument

      @Deprecated protected void setChemicalTermsArgument(String arg) throws PluginException
      Deprecated.
      Description copied from class: CalculatorPlugin
      Sets the argument string as specified in Chemical Terms expressions. This method may only be called from CalculatorPlugin.setChemicalTermsParameters(Properties, String).
      Overrides:
      setChemicalTermsArgument in class CalculatorPlugin
      Parameters:
      arg - The argument, never null. Its meaning is implementation-dependent.
      Throws:
      PluginException - on error

    • setCleanResultStructures

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public void setCleanResultStructures(boolean clean)
      Deprecated, for removal: This API element is subject to removal in a future version.
      obsolete method
      Sets 2D cleaning of the result structures: if true then the changed atoms in tautomers returned by getStructure(int) are partial cleaned in 2D. Should be called before setting input molecule. Default: false.
      Parameters:
      clean - if true then result structures are cleaned in 2D
      Since:
      Marvin 5.1.2

    • getChangedAtomIndexes

      public int[] getChangedAtomIndexes()
      Returns the indexes of the atoms changed during tautomerization. Should be called after run(). Returns null if none of the atoms has changed. For internal use only.
      Returns:
      the indexes of the changed atoms
      Since:
      Marvin 5.12

    • setSymmetryFiltering

      public void setSymmetryFiltering(boolean filtering)
      Sets symmetry fitlering: if true then symmetrical structures are filtered out, otherwise symmetrical structures are returned as duplicates. Symmetry filtering is always performed when canonical tautomer form is taken, regardless of the actual setting of the filtering parameter. Default: true.
      Parameters:
      filtering - is true if symmetrical structures should be filtered out
      See Also:

    • setMaxStructureCount

      public void setMaxStructureCount(int max)
      Sets the maximum number of structures to be generated. This number is the sum of unique tautomeric count and degenerated tautomeric count. Note: getStructure(int) returns only the unique tautomers, getStructureCount() returns unique tautormer count. Default: 1000.
      Parameters:
      max - is the maximum number of structures to be generated
      Since:
      Marvin 4.1

    • setpH

      public void setpH(double pH)
      Sets the pH to be considered in dominant tautomer generation. By default, no pH effect considered (Double.NaN).
      Parameters:
      pH - is the pH value
      See Also:

    • setTimeLimit

      public void setTimeLimit(double t)
      Sets an upper time limit for the canonical tautomer generation. By default, no time limit considered (Double.NaN).
      Parameters:
      t - is the maximum allowed calculation time/molecule. It should be given in second.
      See Also:

    • setMaximumTautomerizationPathLength

      public void setMaximumTautomerizationPathLength(int length)
      Sets the maximum allowed length of the tautomerization path in chemical bonds. If length = 0 is set then no limit is applied. Default: 4.
      Parameters:
      length - is the maximum allowed tautomerization path length
      Since:
      Marvin 4.1.11

    • setProtectAromaticity

      public void setProtectAromaticity(boolean pa)
      Sets aromaticity protection: if true then aromatic bonds are not modified by the tautomer generator. Has no effect in case of generic tautomer. Default: true.
      Parameters:
      pa - is true if aromaticity should be protected
      Since:
      Marvin 5.0.2

    • setProtectCharge

      public void setProtectCharge(boolean pc)
      Sets charge protection: if true then the charge of charged atoms are not modified by the tautomer generator. Has no effect in case of generic tautomer. Default: false.
      Parameters:
      pc - is true if charges should be protected
      Since:
      Marvin 5.0.1

    • setExcludeAntiAromaticCompounds

      public void setExcludeAntiAromaticCompounds(boolean aa)
      Sets whether antiaromatic compounds should be generated. If true then antiaromatic compounds are not generated. Has no effect in case of generic tautomer. Default: true.
      Parameters:
      aa - is true if antiaromatic compounds should not be generated
      Since:
      Marvin 5.0.1

    • setProtectDoubleBondStereo

      public void setProtectDoubleBondStereo(boolean protect)
      Sets double bond stereo protection: if true then double bonds stereo information is preserved by the tautomer generator. Has no effect in case of generic tautomer. Default: false.
      Parameters:
      protect - is true if double bond stereo information should be protected by the tautomer generator
      Since:
      Marvin 5.1

    • setProtectAllTetrahedralStereoCenters

      public void setProtectAllTetrahedralStereoCenters(boolean protect)
      Sets the protection of all tetrahedral stereo centers: if true then all tetrahedral stereo information is preserved by the tautomer generator. Default: false.
      Parameters:
      protect - is true if all tetrahedral stereo information should be preserved by the tautomer generator
      Since:
      Marvin 5.1

    • setProtectLabeledTetrahedralStereoCenters

      public void setProtectLabeledTetrahedralStereoCenters(boolean protect)
      Sets the protection of labeled tetrahedral stereo centers: if true then labeled tetrahedral stereo centers are protected by the tautomer generator. Has no effect in case of generic tautomer. Default: false.
      Parameters:
      protect - is true if labeled tetrahedral stereo centers should be protected by the tautomer generator
      Since:
      Marvin 5.1

    • setProtectEsterGroups

      public void setProtectEsterGroups(boolean protect)
      Sets the protection of ester groups: if true then ester groups are excluded from the tautomerization. Default: true. Has no effect in case of generic tautomer.
      Parameters:
      protect - is true if ester groups should be excluded from the tautomerization
      Since:
      Marvin 5.3

    • setRingChainTautomerizationAllowed

      public void setRingChainTautomerizationAllowed(boolean allowed)
      Sets if ring tautomers are allowed or not.
      Default true
      Since:
      Marvin 5.8

    • setInputMoleculeModified

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public void setInputMoleculeModified(boolean inputMoleculeModified)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Not used.
      Sets whether the input molecule should be modified and returned as calculation result. Default: false.
      Parameters:
      inputMoleculeModified - is true if input molecule should be modified, false if it should be preserved
      Since:
      Marvin 4.1

    • checkMolecule

      public void checkMolecule(Molecule mol) throws PluginException
      Checks the input molecule. Throws exception if the molecule contains R-groups.
      Overrides:
      checkMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - with error message for the user if the molecule is refused

    • createStandardizedMolecule

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) protected Molecule createStandardizedMolecule(Molecule mol, boolean om) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use createStandardizedMolecule(Molecule) instead
      Creates standardized molecule, the original input molecule is cloned only if the original molecule should not be modified.
      Overrides:
      createStandardizedMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      om - is true if original input molecule is to be used for atom indexing false if modified molecule is to be used for atom indexing
      Returns:
      the standardized molecule
      Throws:
      PluginException - on error
      See Also:

    • createStandardizedMolecule

      protected Molecule createStandardizedMolecule(Molecule mol) throws PluginException
      Creates standardized molecule, the original input molecule is cloned only if the original molecule should not be modified.
      Overrides:
      createStandardizedMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      Returns:
      the standardized molecule
      Throws:
      PluginException - on error
      See Also:

    • getExplicitHydrogenData

      protected List<CalculatorPlugin.HydrogenData> getExplicitHydrogenData(Molecule cmol, int n)
      Overrides:
      getExplicitHydrogenData in class CalculatorPlugin

    • setMolecule

      protected Molecule setMolecule(Molecule mol, boolean st, boolean om, boolean storeExplicitHydrogens) throws PluginException
      Overrides:
      setMolecule in class CalculatorPlugin
      Throws:
      PluginException

    • setInputMolecule

      protected void setInputMolecule(Molecule mol) throws PluginException
      Sets the input molecule.
      Specified by:
      setInputMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - on error

    • setTakePartialNeutralization

      public void setTakePartialNeutralization(boolean pn)
      Sets if partial neutralization prior to canonical tauotmer generation is allowed or not.
      Parameters:
      pn - if true then partial neutralization is allowed
      Since:
      Marvin 5.5

    • setWigglyBondVisibility

      public void setWigglyBondVisibility(boolean vis)
      Sets how wiggly bonds connected to double bonds are displayed.
      For internal use only.
      Parameters:
      vis - if true then wiggly bonds connected to double bonds are show as wiggly bonds, if false then wiggly bonds connected to double bonds are show as single bonds
      Since:
      Marvin 5.5

    • setTakeCanonicalForm

      public void setTakeCanonicalForm(boolean canonical)
      Sets whether canonical form should be generated. Default: false.
      Parameters:
      canonical - is true if canonical form should be generated
      Since:
      Marvin 4.1
      See Also:

    • setTakeStandardForm

      public void setTakeStandardForm(boolean s)
      For internal use only.
      Since:
      Marvin 5.5

    • setNormalTautomerGenerationMode

      public void setNormalTautomerGenerationMode(boolean normal)
      Generates only normal tautomers.
      Since:
      Marvin 14.4.13

    • setDiaStereoIsomerMixtureAllowedState

      public void setDiaStereoIsomerMixtureAllowedState(boolean dsma)

    • setRationalTautomerGenerationMode

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public void setRationalTautomerGenerationMode(boolean rational)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Generates only rational tautomers. Use setNormalTautomerGenerationMode(boolean) instead

    • setTakeGenericTautomer

      public void setTakeGenericTautomer(boolean generic)
      Sets whether generic tautomer should be generated. If generic tautomer is generated then all protect options except "protect all tetrahedral stereo centers" are ignored. Default: false.
      Parameters:
      generic - is true if generic tautomer should be generated
      Since:
      Marvin 5.1
      See Also:

    • setTakeGenericTautomer

      public void setTakeGenericTautomer(boolean generic, boolean nGeneric)

    • setTakeMostStableTautomer

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public void setTakeMostStableTautomer(boolean mostStable)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Call setTakeMajorTautomer(boolean) instead.
      Sets whether most stable tautomer should be generated. Default: false.
      Parameters:
      mostStable - is true if most stable tautomer should be generated
      Since:
      Marvin 5.1
      See Also:

    • setTakeMajorTautomer

      public void setTakeMajorTautomer(boolean major)
      Sets whether major tautomer should be generated. Default: false.
      Parameters:
      major - is true if major tautomer should be generated
      Since:
      Marvin 5.2.2
      See Also:

    • setTakeDominantTautomers

      public void setTakeDominantTautomers(boolean dominants)
      Sets whether dominant tautomers should be generated. Default: false.
      Parameters:
      dominants - is true if dominant structures should be generated
      See Also:

    • setDominantTautomerDistributionCalculation

      public void setDominantTautomerDistributionCalculation(boolean distrib)
      Sets dominant tautomer distribution calculation: if true then dominant tautomer distribution is calculated. Use getStructure(int) to get the dominant tautomer structure and getDominantTautomerDistribution(int) to get its distribution.
      Parameters:
      distrib - if true then dominant tautomer distribution calculation is performed
      Since:
      Marvin 4.1.11
      See Also:

    • run

      public boolean run() throws PluginException
      Calculates the tautomers.
      Specified by:
      run in class CalculatorPlugin
      Returns:
      true if the calculation was successful, false if the number of ionizable atoms exceeds the specified limit
      Throws:
      PluginException - on error
      See Also:

    • getDominantTautomerDistribution

      public double getDominantTautomerDistribution(int index)
      Returns the distribution of the dominant tautomer. Dominant tautomers are ordered by distribution: first (index = 0) is the major tautomer with largest distribution, followed by other dominant tautomers in descending distribution order. Use getStructure(int) to get the dominant tautomer structure.
      Parameters:
      index - is the dominant tautomer index
      Returns:
      the distribution of the dominant tautomer
      Since:
      Marvin 4.1.11
      See Also:

    • getNewOldIndexMap

      public int[] getNewOldIndexMap()
      Returns:
      the index mapping relations between the implicit-explicit molecule forms new -> old mapping , atom indexing starts form "0" e.g. if the "2" is the new index in the implicitized form then the "map[2]" will be the old index in the explicit form

    • getOldNewIndexMap

      public int[] getOldNewIndexMap()
      Returns:
      the index mapping relations between the explicit- implicit molecule forms old -> new mapping , atom indexing starts form "0" e.g. if the "2" is the old index in the explicit form then the "map[2]" will be the new index in the implicitized form

    • getResultSource

      public chemaxon.marvin.plugin.PluginMDocSource getResultSource() throws PluginException
      Returns the result as a document source object. This is useful for displaying the molecules in a viewer dynamically as they become available instead of collecting all results before display.
      Overrides:
      getResultSource in class CalculatorPlugin
      Returns:
      the document source interface
      Throws:
      PluginException - on error
      Since:
      Marvin 5.0

    • getStructureCount

      public int getStructureCount()
      Returns the number of different tautomers.
      Returns:
      the number of different structures
      See Also:

    • getStructure

      public Molecule getStructure(int index)
      Returns a tautomer.
      Parameters:
      index - is the structure index
      Returns:
      the structure
      See Also:

    • getStructures

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public Molecule[] getStructures()
      Deprecated, for removal: This API element is subject to removal in a future version.
      since Marvin 5.9 replaced by getStructure(int)
      Returns tautomers in Molecule[] array..
      Returns:
      tautomers
      See Also:

    • getResultTypes

      public Object[] getResultTypes()
      Returns the result types.
      Overrides:
      getResultTypes in class CalculatorPlugin
      Returns:
      the result types

    • getResultDomain

      public int getResultDomain(Object type)
      Returns the calculation domain.
      Overrides:
      getResultDomain in class CalculatorPlugin
      Parameters:
      type - is the result type
      Returns:
      the calculation domain
      See Also:

    • getResultCount

      public int getResultCount(Object type)
      Returns the number of result items for the given result key.
      Overrides:
      getResultCount in class CalculatorPlugin
      Parameters:
      type - is the result type
      Returns:
      the number of result items
      See Also:

    • getResult

      public Object getResult(Object type, int index) throws PluginException
      Returns the result item for the specified key and index.
      Overrides:
      getResult in class CalculatorPlugin
      Parameters:
      type - is the result type
      index - is the result index
      Returns:
      the result item for the specified key and index
      Throws:
      PluginException - if the result cannot be returned
      See Also:

    • getResultAsString

      public String getResultAsString(Object type, int index, Object result) throws PluginException
      Returns the specified result in String format.
      Overrides:
      getResultAsString in class CalculatorPlugin
      Parameters:
      type - is the result type
      index - is the result index
      result - is the result item
      Returns:
      the specified result in String format
      Throws:
      PluginException - if an invalid result item is given

    • getRemark

      public String getRemark()
      Returns a warning message if there are no tautomers, null otherwise.
      Overrides:
      getRemark in class CalculatorPlugin
      Returns:
      a warning message if there are no tautomers

    • getErrorMessage

      public String getErrorMessage()
      Returns the calculation error information message or the empty string if there is no error.
      Overrides:
      getErrorMessage in class CalculatorPlugin
      Returns:
      the calculation error information message

    • getTitle

      public String getTitle()
      Returns the frame title.
      Returns:
      the frame title
      Since:
      Marvin 5.2

    • standardize

      public void standardize(Molecule mol)
      Standardizes the molecule. This is the same as the default standardization, but performs daylight aromatization.
      Overrides:
      standardize in class CalculatorPlugin
      Parameters:
      mol - is the molecule to be standardized

    • isMultiThreadedRunEnabled

      public boolean isMultiThreadedRunEnabled()
      For internal use only.
      Overrides:
      isMultiThreadedRunEnabled in class CalculatorPlugin
      Returns:
      true if multi-threaded run is enabled

    • getWarningMessage

      public String getWarningMessage()
      Description copied from class: CalculatorPlugin
      Returns the calculation warning information message. The default implementation returns the empty string.
      Overrides:
      getWarningMessage in class CalculatorPlugin
      Returns:
      the calculation warning information message

    • tags

      public Set<CalculatorTag> tags()
      Description copied from interface: TaggedCalculator
      Returns the set of tags reported by this calculator. The same tags should be returned unless the calculator is modified using a mutator method, e.g. if some settings are changed.

      New tags can be introduced and reported in the future by existing calculators, so do not depend on the exact set of reported tags, only check for the presence of certain tags.

      Returns:
      the tags