Class MaxCommonSubstructure
- All Implemented Interfaces:
chemaxon.license.Licensable
- Direct Known Subclasses:
BuildupMcs
,MaxCliqueMcs
An instance of the default MCS algorithm implementation can be created using newInstance()
or
newInstance(McsSearchOptions)
. The provided MCS algorithms are powerful heuristic methods, which typically
find large common substructures in a short time. However, they do not always provide the exact optimal result due to
the complexity of the MCS problem (especially for large molecules). Furthermore, as the algorithms perform
randomized search, different results might be obtained for equivalent molecule representations.
Warning: MCS algorithms do not perform transformations on the input molecules, so you should be aware of
aromatization
(and other standardization actions) before using them.
Features: Query and target structures basically play the same role in MCS search except for query features: a query molecule may contain generic query atoms (A, Q, M, X, list atom, not list atom, etc.) and query bonds (any, single or double, etc.), but query properties (e.g., valence, hydrogen count) are ignored. If exact query atom/bond matching is set to true, then generic atoms and bonds are allowed in both molecules, but they are matched in exact manner. Reactions are also supported, but Markush structures are not.
Typical usage:
MaxCommonSubstructure mcs = MaxCommonSubstructure.newInstance(); mcs.setMolecules(queryMol, targetMol); McsSearchResult result = mcs.find(); System.out.println("Atoms in MCS: " + result.getAtomCount()); System.out.println("Bonds in MCS: " + result.getBondCount()); System.out.println("MCS molecule: " + MolExporter.exportToFormat(result.getAsMolecule(), "smiles"));
-
Field Summary
Modifier and TypeFieldDescriptionstatic final long
Default random seed.protected static final System.Logger
Logger object.protected com.chemaxon.search.vf2.Vf2Matcher
The matcher object containing the preprocessed query and target molecules.protected Molecule
Query molecule (it is neither cloned nor modified).protected long
Random seed (0 means using the current time).protected SearchMode
Search mode.protected final McsSearchOptions
Search options.protected Molecule
Target molecule (it is neither cloned nor modified).protected long
Time limit in milliseconds (-1 means disabled). -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionfinal float
Calculates an upper bound on the similarity of the query and target molecules with respect to the specified search options.final int
Calculates an upper bound on the number of bonds the maximum common substructure may contain with respect to the specified search options.final McsSearchResult
find()
Performs MCS search according to the specified options.protected abstract McsSearchResult
findMcs()
Finds the MCS and all related data (fragments and mappings).final Molecule
getQuery()
Gets the query structure.final long
Gets the random seed value.final SearchMode
Gets the current search mode.final McsSearchOptions
Returns the search options used by this instance.final Molecule
Gets the target structure.final long
Gets the maximum allowed MCS search time in milliseconds.final boolean
Returns whether there are more results available.final boolean
Returns information about the licensing of the product.static MaxCommonSubstructure
Creates a new instance of MCS search algorithm using the default search options.static MaxCommonSubstructure
newInstance
(McsSearchOptions searchOpts) Creates a new instance of MCS search algorithm using the given search options.final McsSearchResult
Finds the next MCS search result according to the specified options.final void
Sets the license environment.final void
setMolecules
(Molecule query, Molecule target) Sets the two molecular structures to be matched.final void
Sets the query structure.final void
setRandomSeed
(long seed) Sets the random seed value.final void
setSearchMode
(SearchMode mode) Sets the search mode that controls the running time and the accuracy of the algorithm.final void
Sets the target structure.final void
setTimeLimit
(long maxMilliseconds) Sets the maximum allowed time for MCS search.
-
Field Details
-
DEFAULT_RANDOM_SEED
public static final long DEFAULT_RANDOM_SEEDDefault random seed.- See Also:
-
randomSeed
protected long randomSeedRandom seed (0 means using the current time). -
searchMode
Search mode. -
timeLimit
protected long timeLimitTime limit in milliseconds (-1 means disabled). -
queryMol
Query molecule (it is neither cloned nor modified). -
targetMol
Target molecule (it is neither cloned nor modified). -
searchOpts
Search options. -
LOG
Logger object. -
matcher
protected com.chemaxon.search.vf2.Vf2Matcher matcherThe matcher object containing the preprocessed query and target molecules.
-
-
Constructor Details
-
MaxCommonSubstructure
-
-
Method Details
-
newInstance
Creates a new instance of MCS search algorithm using the default search options.MaxCliqueMcs
implementation is used, which turned out to be the most efficient and robust according to our benchmark tests.- Returns:
- a new instance of the default algorithm implementation
- See Also:
-
newInstance
Creates a new instance of MCS search algorithm using the given search options.MaxCliqueMcs
implementation is used, which turned out to be the most efficient and robust according to our benchmark tests.- Parameters:
searchOpts
- the search options (not null)- Returns:
- a new instance of the default algorithm implementation
-
isLicensed
public final boolean isLicensed()Returns information about the licensing of the product.- Specified by:
isLicensed
in interfacechemaxon.license.Licensable
- Returns:
- true if the product is correctly licensed
-
setLicenseEnvironment
Sets the license environment.- Specified by:
setLicenseEnvironment
in interfacechemaxon.license.Licensable
-
setMolecules
Sets the two molecular structures to be matched.- Parameters:
query
- query molecule (not null)target
- target molecule (not null)
-
setQuery
Sets the query structure.- Parameters:
query
- query molecule (not null)
-
setTarget
Sets the target structure.- Parameters:
target
- target molecule (not null)
-
getQuery
Gets the query structure.- Returns:
- the query molecule
-
getTarget
Gets the target structure.- Returns:
- the target molecule
-
getSearchOptions
Returns the search options used by this instance. For more information, seeMcsSearchOptions
.- Returns:
- search options (not null)
-
setSearchMode
Sets the search mode that controls the running time and the accuracy of the algorithm. The default option isSearchMode.NORMAL
. For more information, seeSearchMode
.- Parameters:
mode
- search mode (not null)
-
getSearchMode
Gets the current search mode. For more information, seeSearchMode
.- Returns:
- current search mode (not null)
-
setTimeLimit
public final void setTimeLimit(long maxMilliseconds) Sets the maximum allowed time for MCS search. If the given limit is exceeded, the search process terminates with the best result obtained so far. When searching for multiple results (without changing the input molecules), the time limit is applied only to the first call ofnextResult()
(orhasNextResult()
).This is an optional limit, which is set to 1 minute by default. You can use a negative parameter value to disable it.
If the search process seems to be too slow, consider using
FAST
search mode instead of decreasing the time limit (seesetSearchMode(SearchMode)
).- Parameters:
maxMilliseconds
- maximum running time in milliseconds (negative value means disabled)
-
getTimeLimit
public final long getTimeLimit()Gets the maximum allowed MCS search time in milliseconds. If no such limit is specified, this method returns -1. For more information, seesetTimeLimit()
.- Returns:
- maximum running time in milliseconds or -1 if no such limit is specified
-
setRandomSeed
public final void setRandomSeed(long seed) Sets the random seed value. 0 means using the current time.- Parameters:
seed
- random seed
-
getRandomSeed
public final long getRandomSeed()Gets the random seed value. 0 means using the current time.- Returns:
- seed random seed
-
find
Performs MCS search according to the specified options. This method returns a valid result object even if the MCS is empty or the search time limit is reached.If multiple MCS results are desired, use
hasNextResult()
andnextResult()
.- Returns:
- the
McsSearchResult
object containing the found common substructure - Throws:
IllegalStateException
- if the input molecules are not set before calling this method or the method is called more than once for the same input moleculesCancellationException
- if the thread has been interrupted
-
hasNextResult
public final boolean hasNextResult()Returns whether there are more results available. SeenextResult()
.- Returns:
- true if
nextResult()
can be called to obtain a newMcsSearchResult
object - Throws:
IllegalStateException
- if the input molecules are not set before calling this methodCancellationException
- if the thread has been interrupted
-
nextResult
Finds the next MCS search result according to the specified options. The first call to this method always returns a valid result object, even if the MCS is empty or the search time limit is reached.If multiple search results are desired, this method can be called repeatedly. The results typically correspond to equivalent common substructures but with different mappings. (See
McsSearchResult
for more information.) When this method is called multiple times,hasNextResult()
should be called first to avoid exception.The search state is reset after a call to
setQuery(Molecule)
,setTarget(Molecule)
orsetMolecules(Molecule, Molecule)
.- Returns:
- the
McsSearchResult
object containing the found common substructure - Throws:
IllegalStateException
- if the input molecules are not set before the first call to this method or there are no more results to returnCancellationException
- if the thread has been interrupted
-
calculateUpperBound
public final int calculateUpperBound()Calculates an upper bound on the number of bonds the maximum common substructure may contain with respect to the specified search options. The returned value is an upper bound onMcsSearchResult.getBondCount()
.As this method is much faster than executing the MCS algorithm (
find()
), it can be used for pre-filtering.- Returns:
- an upper bound on the size (bond count) of the MCS
- Throws:
IllegalStateException
- if the input molecules are not setCancellationException
- if the thread has been interrupted
-
calculateSimilarityUpperBound
public final float calculateSimilarityUpperBound()Calculates an upper bound on the similarity of the query and target molecules with respect to the specified search options. The returned value is an upper bound onMcsSearchResult.getSimilarity()
.As this method is much faster than executing the MCS algorithm (
find()
), it can be used for pre-filtering.- Returns:
- an upper bound on the (MCS based) similarity of the query and the target
- Throws:
IllegalStateException
- if the input molecules are not setCancellationException
- if the thread has been interrupted
-
findMcs
Finds the MCS and all related data (fragments and mappings). Deriving classes must implement this method to calculate an (approximate) maximum common substructure after internal data structures are properly initialized.For internal use only.
-