Package chemaxon.marvin.plugin

Class CalculatorPlugin

java.lang.Object
chemaxon.marvin.plugin.CalculatorPlugin
All Implemented Interfaces:
TaggedCalculator, chemaxon.license.Licensable
Direct Known Subclasses:
AlignmentPlugin, ConformerPlugin, ElementalAnalyserPlugin, GeometryPlugin, IonChargePlugin, IsoelectricPointPlugin, IUPACNamingPlugin, logDPlugin, logPPlugin, MajorMicrospeciesAccessorPlugin, MajorMicrospeciesPlugin, MarkushEnumerationPlugin, MolecularDynamicsPlugin, pKaPlugin, RefractivityPlugin, ResonancePlugin, StereoisomerPlugin, StructuralFrameworksPlugin, TautomerizationPlugin, TopologyAnalyserPlugin
@PublicApi public abstract class CalculatorPlugin extends Object implements chemaxon.license.Licensable, TaggedCalculator
Common base class for calculator plugins. Provides a uniform framework for plugin calculations and calculation result queries.

API usage examples:

  • Charge calculation for one input molecule. This example shows the general API usage. Plugin specific API usage examples can be found in the specific plugin class headers. 
    
    // fill parameters
    Properties params = new Properties();
    params.put("precision", "3");
    params.put("type", "total,sigma");

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

    // set plugin parameters
    plugin.setParameters(params);

    // set target molecule
    Molecule mol = MolImporter.importMol("Clc1cc(Cl)c(Cl)cc1");
    plugin.setMolecule(mol);

    // run the calculation
    plugin.run();

    // get the calculation results
    Object[] types = plugin.getResultTypes(); // now this is {"total", "sigma"}
    for (int i=0; i < types.length; ++i) {
        Object type = types[i];
        System.out.println();
        System.out.println(type + " charge: ");
        System.out.println("atom\tcharge");
        int count = plugin.getResultCount(type); // now this is the atom count
        for (int j=0; j < count; ++j) {
            Object result = plugin.getResult(type, j); // now this is the charge value on atom j
            String rtext = plugin.getResultAsString(type, j, result); // string representation
            System.out.println((j+1)+"\t"+rtext);
        }
    }

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

Since:
Marvin 3.0

  • Field Details

    • KEEP_HYDROGENS

      protected static final String KEEP_HYDROGENS
      See Also:

    • TRUE

      protected static final String TRUE
      See Also:

    • keepHydrogens

      protected boolean keepHydrogens

    • PLUGIN_DIR

      public static final String PLUGIN_DIR
      The plugin directory (relative to CLASSPATH).
      See Also:

    • PLUGIN_CLASS_KEY

      public static final String PLUGIN_CLASS_KEY
      Plugin class key in manifest.
      See Also:

    • CRITICAL_ERROR_MSG

      protected static final String CRITICAL_ERROR_MSG
      Critical error message.
      See Also:

    • INCORRECT_AROMATIC_NITROGEN_REMARK

      protected static final String INCORRECT_AROMATIC_NITROGEN_REMARK
      Incorrect aromatic nitrogen remark.
      See Also:

    • INSTABLE_TAUTOMERIC_FORM_REMARK

      protected static final String INSTABLE_TAUTOMERIC_FORM_REMARK
      Instable tautomeric form remark.
      See Also:

    • COVALENT_HYDRATION_ERROR_REMARK

      protected static final String COVALENT_HYDRATION_ERROR_REMARK
      Covalent hydration error remark.
      See Also:

    • licenseEnvironment

      protected String licenseEnvironment
      Member storing license environment.

    • RED

      public static final int RED
      Constant storing the red rgb value (the acidic pKa result color).
      See Also:

    • BLUE

      public static final int BLUE
      Constant storing the blue rgb value (the basic pKa result color).
      See Also:

    • CALCRGB_OFF

      protected static final int CALCRGB_OFF
      Calculator rgb offset.
      See Also:

    • ATOM

      public static final int ATOM
      Calculation domain type: calculation refers to atoms.
      See Also:

    • MOLECULE

      public static final int MOLECULE
      Calculation domain type: calculation refers to the molecule.
      See Also:

    • MOLECULES

      public static final int MOLECULES
      Calculation domain type: calculation refers to multiple molecule output.
      Since:
      Marvin 5.2
      See Also:

    • NAN

      protected static final Double NAN
      Double constant for Double.NaN.

    • EPSILON

      public static final double EPSILON
      The microspecies is ignored if its distribution is less than EPSILON for all pH values.
      See Also:

    • explicitHydrogens

      protected List<CalculatorPlugin.HydrogenData> explicitHydrogens
      explicit hydrogens of the input molecule stored here key: index of the "parent" atom on the input molecule value: the hydrogen atom

  • Constructor Details

    • CalculatorPlugin

      protected CalculatorPlugin()
      Constructor. Initializes decimal format.

    • CalculatorPlugin

      protected CalculatorPlugin(Consumer<Molecule> sgExpander, Consumer<Molecule> sgContractor)
      Constructor.
      Parameters:
      sgExpander - Method to use to expand sgroups.
      sgContractor - Method to use to contract sgroups.

  • Method Details

    • getPluginResource

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JAN_01_2026) public static URL getPluginResource(String path)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Separate jars are no longer provided for each calculator plugin, so this related method will be removed without replacement.
      Returns the plugin JAR as resource URL, given the JAR file path relatively to the "plugins" directory.
      Parameters:
      path - is the relative jar file path
      Returns:
      the corresponding resource URL

    • readAttribute

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JAN_01_2026) public static String readAttribute(String attribute, String jar) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Jar attributes are no longer used to store information related to calculator plugins. No replacement.
      Reads an attribute from JAR manifest.
      Parameters:
      attribute - is the attribute name
      jar - is the JAR file name
      Returns:
      the attribute value, or null if not exists
      Throws:
      PluginException
      Since:
      Marvin 4.0

    • create

      public static CalculatorPlugin create(String className) throws PluginException
      Loads a plugin from the classpath based on its fully qualified name.
      Parameters:
      className - the plugin class name
      Returns:
      the created plugin
      Throws:
      PluginException - if the class name is null, or the class cannot be found, or it is not a subclass of CalculatorPlugin, or it cannot be instantiated using its no-arg constructor

    • create

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JAN_01_2026) public static CalculatorPlugin create(String clname, String jar) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Loading plugins from plugin-specific jars is no longer supported, use create(String) instead.
      Loads a plugin, first tries to load it from CLASSPATH, then from JAR. If the plugin class name is null then it is read from the manifest attribute PLUGIN_CLASS_KEY.
      Parameters:
      clname - is the plugin class name
      jar - is the plugin JAR file name
      Returns:
      the created plugin
      Throws:
      PluginException
      Since:
      Marvin 4.0

    • loadPluginClass

      public static Class<? extends CalculatorPlugin> loadPluginClass(String className) throws PluginException
      Loads a plugin class from the classpath based on its fully qualified name.
      Parameters:
      className - the plugin class name
      Returns:
      the plugin class
      Throws:
      PluginException - if the class name is null, or the class cannot be found, or it is not a subclass of CalculatorPlugin

    • loadPluginClass

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JAN_01_2026) public static Class<? extends CalculatorPlugin> loadPluginClass(String clname, String jar) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Loading plugins from plugin-specific jars is no longer supported, use loadPluginClass(String) instead.
      Loads a plugin class, first tries to load it from CLASSPATH, then from JAR. If the plugin class name is null then it is read from the manifest attribute PLUGIN_CLASS_KEY.
      Parameters:
      clname - is the plugin class name
      jar - is the plugin JAR file name
      Returns:
      the plugin class
      Throws:
      PluginException

    • loadClass

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JAN_01_2026) public final Class<?> loadClass(String clname) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      An instance-specific class loader is no longer used by this method. Use Class.forName(String) instead.
      Loads a class from the classpath.
      Parameters:
      clname - is the class name
      Returns:
      the Class object, or null if could not be loaded
      Throws:
      PluginException
      Since:
      Marvin 4.0

    • isRgrouped

      protected static boolean isRgrouped(Molecule mol)
      Returns true if molecule with R-groups.
      Parameters:
      mol - is the molecule
      Returns:
      true if molecule with R-groups

    • containsPseudoAtom

      protected static boolean containsPseudoAtom(Molecule mol)
      Returns true if molecule contains pseudo atom.
      Parameters:
      mol - the molecule to examine
      Returns:
      true if the molecule contains pseudo atom, false otherwise

    • containsMulticenterSgroup

      protected static boolean containsMulticenterSgroup(Molecule mol)
      Decides whether a molecule contains Multicenter S-groups.
      Parameters:
      mol - the molecule to examine
      Returns:
      true if the molecule contains at least one MulticenterSgroup false otherwise.

    • containsSRUSgroup

      protected static boolean containsSRUSgroup(Molecule mol)
      Decides whether a molecule contains SRU S-groups.
      Parameters:
      mol - the molecule to examine
      Returns:
      true if the molecule contains at least one SRU S-group false otherwise.

    • containsCoordinateBond

      protected static boolean containsCoordinateBond(MoleculeGraph mol)
      Decides whether a molecule graph contains coordinate bonds.
      Parameters:
      mol - the molecule to examine
      Returns:
      true if the molecule contains at least one coordinate bond false otherwise.

    • dehydrogenize

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) protected static void dehydrogenize(Molecule mol)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Hydrogenize.convertExplicitHToImplicit(MoleculeGraph, int) with parameter MolAtom.ALL_H does the same.
      Makes all explicit H-s implicit.
      Parameters:
      mol - is the molecule

    • removeWhitespace

      protected static String removeWhitespace(String str)
      Removes whitespace characters from the given string.
      Parameters:
      str - is the string
      Returns:
      the string without whitespace characters

    • getDocument

      public static MDocument getDocument(Molecule structure)
      Returns encapsulating document, creates it if needed.
      Parameters:
      structure - the molecule
      Returns:
      the encapsulating document
      Since:
      Marvin 5.0

    • isLicensed

      public boolean isLicensed()
      Returns true if the plugin is licensed. The license checking is based on the product name, returned by getProductName().
      Specified by:
      isLicensed in interface chemaxon.license.Licensable
      Returns:
      true if the plugin is licensed

    • setLicenseEnvironment

      public void setLicenseEnvironment(String env)
      Sets license environment to be stored.
      Specified by:
      setLicenseEnvironment in interface chemaxon.license.Licensable
      Parameters:
      env - environment String to be stored and passed to the LicenseHandler in the isLicensed method

    • checkLicense

      protected final void checkLicense()

    • getProductName

      public abstract String getProductName()
      Returns the product identifier of the plugin as given by LicenseManager. The name is used by the isLicensed() method.
      Returns:
      product identifier or a default string

    • checkType

      protected void checkType(String type, String[] typerange) throws PluginException
      Checks result types.
      Parameters:
      type - is the type given by the user
      typerange - is the array containing the valid types
      Throws:
      PluginException - if the user-type is not contained in the type-range

    • getDoublePrecision

      public final int getDoublePrecision()
      Returns the precision. This is the max. number of fractional digits.
      Returns:
      the precision

    • setDoublePrecision

      protected final void setDoublePrecision(String pr)
      Sets the precision in the decimal format. This is done according to the user defined precision value: 0..8 means maximal number of fractional digits, ending padded with zeros (e.g. 12.56 -> 12.5600 for precision 4). 'inf' means maximal number of digits set to 10, no padding zeros (e.g. 12.56 -> 12.56)
      Parameters:
      pr - is the precision string ("0"..."8" or "inf")

    • setDoublePrecision

      public final void setDoublePrecision(int precision)
      Sets the double -> string conversion precision (maximal number of fraction digits) with zero-padding (12.56 -> 12.5600 if precision=4).
      Parameters:
      precision - is the precision

    • setDoublePrecision

      public final void setDoublePrecision(int precision, boolean pad)
      Sets the double -> string conversion precision (maximal number of fraction digits).
      Parameters:
      precision - is the precision
      pad - is true if fractional ending zeros should be printed e.g. 12.56 -> 12.56 if precision=4, pad=false 12.56 -> 12.5600 if precision=4, pad=true

    • format

      public final String format(double x)
      Converts a double into String, applying the maximum number of fractional digits specified.
      Parameters:
      x - is the double value to be converted
      Returns:
      the result as String
      See Also:

    • format

      public final String format(double x, int intlen)
      Converts a double into String, applying the maximum number of fractional digits specified. Adds leading spaces to ensure the given integral part length.
      Parameters:
      x - is the double value to be converted
      intlen - is the required integral part length
      Returns:
      the result as String
      See Also:

    • format

      public final StringBuffer format(double x, StringBuffer s)
      Converts a double into String, applying the maximum number of fractional digits specified. Appends the result to the specified StringBuffer.
      Parameters:
      x - is the double value to be converted
      s - is the StringBuffer to be used
      Returns:
      the StringBuffer with the current item appended
      See Also:

    • format

      public final String format(double[][] t, int intlen)
      Converts a double[][] 2xN table to a 2-column tab-separated string representation of the table.
      Parameters:
      t - is the table
      intlen - is the required integral part length
      Returns:
      the string representation

    • 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.
      Parameters:
      pmon - is the progress monitor, may be null

    • setMolecule

      public final Molecule setMolecule(Molecule mol) throws PluginException
      Sets the input molecule after standardization. Standardization includes plugin specific standardization (e.g. dehydrogenize, aromatize) and sgroup expansion. The input molecule is left unchanged (it is cloned for standardization).
      Parameters:
      mol - is the input molecule
      Returns:
      the molecule to be used for atom indexing
      Throws:
      PluginException - on error

    • setMolecule

      public Molecule setMolecule(Molecule mol, boolean st) throws PluginException
      Sets the input molecule after an optional standardization. Standardization includes plugin specific standardization (e.g. dehydrogenize, aromatize) and sgroup expansion. The input molecule is left unchanged (it is cloned if standardization is required).
      Parameters:
      mol - is the input molecule
      st - is true if standardization is required
      Returns:
      the molecule to be used for atom indexing
      Throws:
      PluginException - on error

    • setMolecule

      public Molecule setMolecule(Molecule mol, boolean st, boolean om) throws PluginException
      Sets the input molecule after an optional standardization and/or modification. Standardization includes plugin specific standardization (e.g. dehydrogenize, aromatize) and sgroup expansion, modification usually means taking a microspecies form, or the major tautomeric form of the input molecule (usually optional). The input molecule is left unchanged (it is cloned before standardization/modification if required).
      Parameters:
      mol - is the input molecule
      st - is true if standardization is required
      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 molecule to be used for atom indexing
      Throws:
      PluginException - on error
      See Also:

    • setMolecule

      protected Molecule setMolecule(Molecule mol, boolean st, boolean om, boolean storeExplicitHydrogens) throws PluginException
      Throws:
      PluginException

    • setAtomIndexMap

      protected boolean setAtomIndexMap(int[] map)

    • getAtomIndexMap

      protected int[] getAtomIndexMap()

    • getExplicitHydrogenData

      protected List<CalculatorPlugin.HydrogenData> getExplicitHydrogenData(Molecule cmol, int n)

    • createModifiedInputMolecule

      protected Molecule createModifiedInputMolecule(Molecule mol) throws PluginException
      Returns the modified input molecule (e.g. microspecies, major tautomeric form). This method is used for modifying the input molecule set by setMolecule(Molecule) before passing the molecule to the calulation with setInputMolecule(Molecule) method. The default implementation returns the input molecule itself.
      Parameters:
      mol - is the input molecule
      Returns:
      the modified input molecule
      Throws:
      PluginException

    • getInputMolDim

      public int getInputMolDim()
      Returns the input molecule dimension.
      Returns:
      the input molecule dimension

    • getCalcMolecule

      public Molecule getCalcMolecule()
      Returns the molecule used in the calculation. This can be a standardized and/or modified version (e.g. microspecies, major tautomeric form) of the input molecule. Standardized if parameter 'st' is set to true in setMolecule(chemaxon.struc.Molecule, boolean) or setMolecule(chemaxon.struc.Molecule, boolean, boolean). Input molecule is modified, if the plugin overrides the createModifiedInputMolecule(Molecule) mehod.
      Returns:
      the molecule used in the calculation
      Since:
      Marvin 4.1

    • 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. If handlesMultiFragmentMolecules() returns false then takes the largest fragment (measured by atom count). The cloned molecule is standardized by standardize(Molecule). Sets the atomIndexMap: atomIndexMap[i] is the index in the standardized molecule of the i-th atom in the original molecule or -1 if this atom has been removed.
      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

    • createStandardizedMolecule

      protected Molecule createStandardizedMolecule(Molecule mol) throws PluginException
      Creates standardized molecule, the original input molecule is cloned. If handlesMultiFragmentMolecules() returns false then takes the largest fragment (measured by atom count). The cloned molecule is standardized by standardize(Molecule). Sets the atomIndexMap: atomIndexMap[i] is the index in the standardized molecule of the i-th atom in the original molecule or -1 if this atom has been removed.
      Parameters:
      mol - is the input molecule
      Returns:
      the standardized molecule
      Throws:
      PluginException - on error
      Since:
      Marvin 5.0

    • getMainMolecule

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) protected Molecule getMainMolecule(Molecule mol) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use createModifiedInputMolecule(Molecule) instead
      Returns the molecule form with largest distribution. Returns a microspecies with largest distribution on a given pH if pH is different from Double.NaN, otherwise returns the input molecule itself. The default implementation returns the input molecule itself.
      Parameters:
      mol - is the input molecule
      Returns:
      the molecule form with largest distribution
      Throws:
      PluginException

    • getDisplayMolecule

      protected Molecule getDisplayMolecule() throws PluginException
      Returns the molecule object to be used for GUI display. Plugins will add atom labels and/or molecule properties to display plugin results in the molecule. The default implementation returns the original molecule.
      Returns:
      the molecule object to be used for GUI display
      Throws:
      PluginException - on error

    • 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. The default implementation returns false.
      Returns:
      true if the plugin handles multifragment molecules, false otherwise

    • isMsCalc

      protected boolean isMsCalc()
      Returns true if microspecies calculation. The default implementation returns false.
      Returns:
      false

    • setParameters

      public void setParameters(Properties params) throws PluginException
      Sets the input parameters for the plugin.
      Parameters:
      params - is the parameter table
      Throws:
      PluginException - on error

    • setChemicalTermsParameters

      @Deprecated public final void setChemicalTermsParameters(Properties params, String arg) throws PluginException
      Deprecated.
      For internal use only.
      Sets the input parameters and the argument string as specified in Chemical Terms expressions.
      Parameters:
      params - the parameter table
      arg - The argument, or null if it is not set. Its meaning is implementation-dependent.
      Throws:
      PluginException - on error

    • setChemicalTermsArgument

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

    • getpH

      public double getpH()
      Returns the pH where the major microspecies should be taken. Returns Double.NaN if no microspecies calculation required.
      Returns:
      the pH where the major microspecies should be taken or Double.NaN if no microspecies calculation

    • checkMolecule

      public void checkMolecule(Molecule mol) throws PluginException
      Checks the input molecule. Throws exception if the molecule is not accepted as input molecule, otherwise does nothing (simply returns). The default implementation refuses query molecules, molecules with SRU S-groups, molecules with multicenter S-groups and molecules with coordinate bonds.
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - with error message for the user if the molecule is refused

    • getQueryMoleculeErrorMessage

      protected static String getQueryMoleculeErrorMessage(Molecule mol)

    • setInputMolecule

      protected abstract void setInputMolecule(Molecule mol) throws PluginException
      Sets the input molecule.
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - on error

    • run

      public abstract boolean run() throws PluginException
      Runs the tool.
      Returns:
      true if the calculation was successful, false on calculation problems
      Throws:
      PluginException - on error
      See Also:

    • isOK

      public boolean isOK()
      Returns true if no calculation error, false on error. This is the same as the return value of the last call to run(). The default implementation returns true if both getErrorMessage() and getWarningMessage() return the empty string.
      Returns:
      true if no calculation error or warning
      Since:
      Marvin 4.0

    • getErrorMessage

      public String getErrorMessage()
      Returns the calculation error information message if run() returned false (calculation error). The default implementation returns the empty string.
      Returns:
      the calculation error information message

    • getWarningMessage

      public String getWarningMessage()
      Returns the calculation warning information message. The default implementation returns the empty string.
      Returns:
      the calculation warning information message

    • getResultMessage

      public final String getResultMessage()
      Returns the plugin calculation error message, error or warning.
      Returns:
      the plugin calculation error message

    • getRemark

      public String getRemark()
      Returns the calculation remark. While in case of warning or error returned in getErrorMessage() or getWarningMessage() there is no calculation result, in case of a remark the calculation can be performed although the result may not be correct or precise - depending on the remark. The default implementation returns null.
      Returns:
      the calculation remark

    • getResultTypes

      public Object[] getResultTypes()
      Returns the result types. The default implementation returns null.
      Returns:
      the result types

    • getTypeString

      public String getTypeString(Object type)
      Returns a string representation of the given type. The default implementation returns type.toString().
      Parameters:
      type - is the type object
      Returns:
      the type string

    • getResultDomain

      public int getResultDomain(Object type)
      Returns the calculation domain ATOM, MOLECULE or MOLECULES. The default implementation returns MOLECULE.
      Parameters:
      type - is the result type
      Returns:
      the calculation domain
      See Also:

    • canRepeat

      public boolean canRepeat()
      Returns true if repeatedly running the same plugin object while getting the results on the GUI is allowed, false otherwise. For internal use.
      Returns:
      true if allowed, false otherwise
      Since:
      Marvin 5.2

    • getResultCount

      public int getResultCount(Object type)
      Returns the number of result items for the given result key. The default implementation returns 1.
      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 type and index. The default implementation returns null.
      Parameters:
      type - is the result type
      index - is the result index
      Returns:
      the result item for the specified type 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. The default implementation returns null.
      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

    • getResultsAsString

      public String getResultsAsString(Object type, int index, Object result) throws PluginException
      Returns the specified result with possible subresults. (items separated by "|" characters) (e.g. both pKa values instead of the most significant pKa) in String format.
      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

    • getResultAsRGB

      public int getResultAsRGB(Object type, int index, Object result) throws PluginException
      Returns the specified result color as int format (alpha<<24 + red<<16 + green<<8 + blue).
      Parameters:
      type - is the result type
      index - is the result index
      result - is the result item
      Returns:
      the specified result in color as int
      Throws:
      PluginException - if an invalid result item is given

    • getResultsAsRGB

      public long getResultsAsRGB(Object type, int index, Object result) throws PluginException
      Returns the specified result color(s) as int format (alpha<<24 + red<<16 + green<<8 + blue). (e.g. both pKa colors instead of the most significant pKa color) as long (lower and upper bits).
      Parameters:
      type - is the result type
      index - is the result index
      result - is the result item
      Returns:
      the specified result in color as int
      Throws:
      PluginException - if an invalid result item is given

    • isNegligibleResult

      public boolean isNegligibleResult(Object type, int index, Object result) throws PluginException
      Returns whether the result can be ignored. Can be used to filter out out-of range values. The default implementation returns false.
      Parameters:
      type - is the result type
      index - is the result index
      result - is the result object
      Returns:
      true if the result can be ignored
      Throws:
      PluginException

    • getResult

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public Object getResult(Object type, String arg) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Some implementations of this method modify the state of the plugin, which is a very confusing behavior, so the method is now deprecated and should no longer be used. If you used this method with an index argument, parse the index instead, and call getResult(Object, int). Otherwise, call the appropriate setter method of the plugin to configure it with the argument, and call getResult(Object, int) with a 0 index.
      Returns the result item for the specified argument string. The default implementation calls getResult(Object, int) with the argument string converted to an integer (result index).
      Parameters:
      type - is the result type
      arg - is the argument string
      Returns:
      the result item for the specified type and argument string
      Throws:
      PluginException - if the result cannot be returned
      See Also:

    • getResultMolecule

      public Molecule getResultMolecule() throws PluginException
      Returns the result molecule for display. Atomic results are stored in atom extra labels (MolAtom.getExtraLabel()). Molecular results are stored in molecule properties with keys being the result types (MPropHandler.convertToString(MPropertyContainer, String)).
      Returns:
      the result molecule
      Throws:
      PluginException - on error
      Since:
      Marvin 4.0

    • getResultMolecules

      public Molecule[] getResultMolecules() throws PluginException
      Returns the result molecule array for display. The display of the molecules in array have to be implemented in a class derived from CalculatorPluginDispaly class (example: MultipleDataDisplay class). Atomic results are stored in atom extra labels (MolAtom.getExtraLabel()). Molecular results are stored in molecule properties with keys being the result types (MPropHandler.convertToString(MPropertyContainer, String)).
      Returns:
      the result molecule array
      Throws:
      PluginException - on error
      Since:
      Marvin 4.1

    • getResultSource

      public 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. The default implementation returns null.
      Returns:
      the document source interface
      Throws:
      PluginException - on error
      Since:
      Marvin 5.0

    • getResultDomain

      public int getResultDomain()
      Returns the calculation domain ATOM, MOLECULE or MOLECULES. for the first result type.
      Returns:
      the calculation domain

    • getResultCount

      public int getResultCount()
      Returns the number of result items for the first result type.
      Returns:
      the number of result items
      See Also:

    • getResult

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

    • getResult

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public Object getResult(String arg) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Some implementations of this method modify the state of the plugin, which is a very confusing behavior, so the method is now deprecated and should no longer be used. If you used this method with an index argument, parse the index instead, and call getResult(Object, int). Otherwise, call the appropriate setter method of the plugin to configure it with the argument, and call getResult(Object, int) with a 0 index.
      Returns the result item for the specified argument string. The default implementation calls getResult(Object, int) with the argument string converted to an integer (result index) and with the first result type.
      Parameters:
      arg - is the argument string
      Returns:
      the result item for the first result type and the given argument string
      Throws:
      PluginException - if the result cannot be returned
      See Also:

    • getResultAsString

      public String getResultAsString(int index, Object result) throws PluginException
      Returns the specified result in String format for the first result type.
      Parameters:
      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

    • getResultsAsString

      public String getResultsAsString(int index, Object result) throws PluginException
      Returns the specified result with possible subresults. (items separated by "|" characters) (e.g. both pKa values instead of the most significant pKa) in String format.
      Parameters:
      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

    • getResultAsRGB

      public int getResultAsRGB(int index, Object result) throws PluginException
      Returns the specified result color as int format (alphainvalid input: '<'invalid input: '<'24 + redinvalid input: '<'invalid input: '<'16 + greeninvalid input: '<'invalid input: '<'8 + blue). for the first result type.
      Parameters:
      index - is the result index
      result - is the result item
      Returns:
      the specified result in color as int format
      Throws:
      PluginException - if an invalid result item is given

    • getResultsAsRGB

      public long getResultsAsRGB(int index, Object result) throws PluginException
      Returns the specified result color(s) as int format (alpha<<24 + red<<16 + green<<8 + blue). (e.g. both pKa colors instead of the most significant pKa color) as long (lower and upper bits).
      Parameters:
      index - is the result index
      result - is the result item
      Returns:
      the specified result in color as int
      Throws:
      PluginException - if an invalid result item is given

    • getAtomCount

      public final int getAtomCount()
      Returns the number of atoms in the input molecule.
      Returns:
      the number of atoms in the input molecule

    • getAtomIndex

      public final int getAtomIndex(int index)
      Returns the atom index in the standardized molecule, or the atom index itself if the input molecule has not been standardized.
      Parameters:
      index - is the atom index in the input molecule
      Returns:
      the corresponding atom index in the standardized molecule, -1 if the atom has been removed

    • getAtomIndexMapping

      public final IntUnaryOperator getAtomIndexMapping()
      Returns an immutable function of the current atom index mapping from the original molecule to standardized one. The result will behave exactly like getAtomIndex(int) until a new molecule is set on this plugin. If a new molecule is set, getAtomIndex(int) will reflect the new mapping, whereas the function returned by this method will always represent the mapping at the time of its creation.
      Returns:
      an immutable function of the current atom index mapping
      See Also:

    • isInputMoleculeAromatized

      public final boolean isInputMoleculeAromatized()
      Returns true if the input molecule has aromatic bond.
      Returns:
      true if the input molecule has aromatic bond

    • standardize

      public void standardize(Molecule mol)
      Standardizes the molecule by performing the transformations necessary to run the plugin (aromatize, dehydrogenize, bring nitro groups to common form, ...). This implementation performs the following transformations:
      • aromatization
      • nitro group transformation: [O-:1][N+:2] >> [O:1]=[N:2], [NH1+:1][O-:2] >> [H:3][O:2][N:1]
      • sulphynil group transformation: [#6][S+:1]([#6])[#8-:2] >> [#6][S:1]([#6])=[O:2]
      To be overridden by subclasses that require other standardization (or none at all). TODO: replace by call to chemaxon.standardizer.Standardizer
      Parameters:
      mol - is the molecule to be standardized

    • standardizeIonicGroups

      protected static void standardizeIonicGroups(Molecule mol)
      Default standardization:
      • nitro groups: [O-:1][N+:2] >> [O:1]=[N:2], [NH1+:1][O-:2] >> [H:3][O:2][N:1]
      • sulphynil groups: [#6][S+:1]([#6])[#8-:2]>>[#6][S:1]([#6])=[O:2]
      Parameters:
      mol - is the molecule to be standardized

    • isMultiThreadedRunEnabled

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

    • restoreExplicitHydrogens

      protected boolean restoreExplicitHydrogens(Molecule molecule)
      When the input molecule is set, the explicit H-s may be stored setMolecule(Molecule, boolean, boolean, boolean) The parameter should be topologically equal to the input molecule for a successfull restore.
      Parameters:
      molecule - the molecule to put the H-s on
      Returns:
      true if the restore was successful, false otherwise

    • setKeepHydrogens

      protected void setKeepHydrogens(Properties properties)

    • arrangeHydrogenIncerments

      protected void arrangeHydrogenIncerments(Molecule mol, int atomIndex, String label, double hydrogenIncrement)

    • getOriginalMolecule

      protected Molecule getOriginalMolecule()

    • addInputChecker

      public void addInputChecker(TaggedCalculatorInputChecker checker)
      Adds the specified input checker to this plugin. The checker will be called on the input molecule when it is passed to either checkMolecule(chemaxon.struc.Molecule) or setMolecule(chemaxon.struc.Molecule).

    • addHeavyAtomLimitChecker

      public void addHeavyAtomLimitChecker(int limit)
      Creates an input checker by calling CalculatorInputChecker.heavyAtomLimit(int) and adds it to this plugin.