Package org.openscience.cdk.group

Interface AtomContainerDiscretePartitionRefiner

All Superinterfaces:
DiscretePartitionRefiner
public interface AtomContainerDiscretePartitionRefiner extends DiscretePartitionRefiner
A tool for determining the automorphism group of the atoms in a molecule, or for checking for a canonical form of a molecule. If two atoms are equivalent under an automorphism in the group, then roughly speaking they are in symmetric positions in the molecule. For example, the C atoms in two methyl groups attached to a benzene ring are 'equivalent' in this sense.

There are a couple of ways to use it - firstly, get the automorphisms.

     IAtomContainer ac = ... // get an atom container somehow
     AtomContainerDiscretePartitionRefiner refiner = 
          PartitionRefinement.forAtoms().create()
     PermutationGroup autG = refiner.getAutomorphismGroup(ac);
     for (Permutation automorphism : autG.all()) {
         ... // do something with the permutation
     }

Another is to check an atom container to see if it is canonical:

     IAtomContainer ac = ... // get an atom container somehow
     AtomContainerDiscretePartitionRefiner refiner = 
          PartitionRefinement.forAtoms().create()
     if (refiner.isCanonical(ac)) {
         ... // do something with the atom container
     }
Note that it is not necessary to call refine(IAtomContainer) before either of these methods. However if both the group and the canonical check are required, then the code should be: 
     AtomContainerDiscretePartitionRefiner refiner = 
          PartitionRefinement.forAtoms().create()
     refiner.refine(ac);
     boolean isCanon = refiner.isCanonical();
     PermutationGroup autG = refiner.getAutomorphismGroup();
This way, the refinement is not carried out multiple times.

  • Method Details

    • refine

      void refine(IAtomContainer atomContainer)
      Refine an atom container, which has the side effect of calculating the automorphism group. If the group is needed afterwards, call DiscretePartitionRefiner.getAutomorphismGroup() instead of getAutomorphismGroup(IAtomContainer) otherwise the refine method will be called twice.
      Parameters:
      atomContainer - the atomContainer to refine

    • refine

      void refine(IAtomContainer atomContainer, Partition partition)
      Refine an atom partition based on the connectivity in the atom container.
      Parameters:
      atomContainer - the atom container to use
      partition - the initial partition of the atoms

    • isCanonical

      boolean isCanonical(IAtomContainer atomContainer)
      Checks if the atom container is canonical. Note that this calls refine(org.openscience.cdk.interfaces.IAtomContainer) first.
      Parameters:
      atomContainer - the atom container to check
      Returns:
      true if the atom container is canonical

    • getAutomorphismGroup

      PermutationGroup getAutomorphismGroup(IAtomContainer atomContainer)
      Gets the automorphism group of the atom container. By default it uses an initial partition based on the element symbols (so all the carbons are in one cell, all the nitrogens in another, etc). If this behaviour is not desired, then use the AtomDiscretePartitionRefiner.ignoreElements flag in the constructor.
      Parameters:
      atomContainer - the atom container to use
      Returns:
      the automorphism group of the atom container

    • getAutomorphismGroup

      PermutationGroup getAutomorphismGroup(IAtomContainer atomContainer, PermutationGroup group)
      Speed up the search for the automorphism group using the automorphisms in the supplied group. Note that the behaviour of this method is unknown if the group does not contain automorphisms...
      Parameters:
      atomContainer - the atom container to use
      group - the group of known automorphisms
      Returns:
      the full automorphism group

    • getAutomorphismGroup

      PermutationGroup getAutomorphismGroup(IAtomContainer atomContainer, Partition initialPartition)
      Get the automorphism group of the molecule given an initial partition.
      Parameters:
      atomContainer - the atom container to use
      initialPartition - an initial partition of the atoms
      Returns:
      the automorphism group starting with this partition

    • getAutomorphismPartition

      Partition getAutomorphismPartition(IAtomContainer atomContainer)
      Get the automorphism partition (equivalence classes) of the atoms.
      Parameters:
      atomContainer - the molecule to calculate equivalence classes for
      Returns:
      a partition of the atoms into equivalence classes