BioSimSpace.Align.matchAtoms(molecule0, molecule1, scoring_function='RMSD align', matches=1, return_scores=False, prematch={}, use_rdkit_prematch=False, timeout=5.0000 secs, match_light=True, property_map0={}, property_map1={}, verbose=False)

Find mappings between atom indices in molecule0 to those in molecule1. Molecules are aligned using a Maximum Common Substructure (MCS) search. When requesting more than one match, the mappings will be sorted using a scoring function and returned in order of best to worst score. (Note that, depending on the scoring function the “best” score may have the lowest value.)

  • molecule0 (Molecule) – The molecule of interest.

  • molecule1 (Molecule) – The reference molecule.

  • scoring_function (str) –

    The scoring function used to match atoms. Available options are:
    • ”RMSD”

      Calculate the root mean squared distance between the coordinates of atoms in molecule0 to those that they map to in molecule1.

    • ”RMSD align”

      Align molecule0 to molecule1 based on the mapping before computing the above RMSD score.

  • matches (int) – The maximum number of matches to return. (Sorted in order of score).

  • return_scores (bool) – Whether to return a list containing the scores for each mapping.

  • prematch (dict) – A pre-match to use as the basis of the search.

  • use_rdkit_prematch (bool) – Whether to use a pre-match generated by RDKit. This option is only considered if no user pre-match dictionary has been specified.

  • timeout (Time) – The timeout for the matching algorithm.

  • match_light (bool) – Whether to match light atoms.

  • property_map0 (dict) – A dictionary that maps “properties” in molecule0 to their user defined values. This allows the user to refer to properties with their own naming scheme, e.g. { “charge” : “my-charge” }

  • property_map1 (dict) – A dictionary that maps “properties” in molecule1 to their user defined values.

  • verbose (bool) – Whether to print status information from the matcher.


matches – The best atom mapping, a list containing a user specified number of the best mappings ranked by their score, or a tuple containing the list of best mappings and a list of the corresponding scores.

Return type

dict, [dict], ([dict], list)


Find the best maximum common substructure mapping between two molecules.

>>> import BioSimSpace as BSS
>>> mapping = BSS.Align.matchAtoms(molecule0, molecule1)

Find the 5 best mappings.

>>> import BioSimSpace as BSS
>>> mappings = BSS.Align.matchAtoms(molecule0, molecule1, matches=5)

Find the 5 best mappings along with their ranking scores.

>>> import BioSimSpace as BSS
>>> mappings, scores = BSS.Align.matchAtoms(molecule0, molecule1, matches=5, return_scores=True)

Find the best mapping that contains a prematch (this is a dictionary mapping atom indices in molecule0 to those in molecule1).

>>> import BioSimSpace as BSS
>>> from Sire.Mol import AtomIdx
>>> mapping = BSS.Align.matchAtoms(molecule0, molecule1, prematch={AtomIdx(0), AtomIdx(10)})

Find the best mapping, excluding light atoms.

>>> import BioSimSpace as BSS
>>> mapping = BSS.Align.matchAtoms(molecule0, molecule1, match_light=False)