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 Summary

Modifier and Type	Method and Description
PermutationGroup	getAutomorphismGroup(IAtomContainer atomContainer) Gets the automorphism group of the atom container.
PermutationGroup	getAutomorphismGroup(IAtomContainer atomContainer, Partition initialPartition) Get the automorphism group of the molecule given an initial partition.
PermutationGroup	getAutomorphismGroup(IAtomContainer atomContainer, PermutationGroup group) Speed up the search for the automorphism group using the automorphisms in the supplied group.
Partition	getAutomorphismPartition(IAtomContainer atomContainer) Get the automorphism partition (equivalence classes) of the atoms.
boolean	isCanonical(IAtomContainer atomContainer) Checks if the atom container is canonical.
void	refine(IAtomContainer atomContainer) Refine an atom container, which has the side effect of calculating the automorphism group.
void	refine(IAtomContainer atomContainer, Partition partition) Refine an atom partition based on the connectivity in the atom container.

Methods inherited from interface org.openscience.cdk.group.DiscretePartitionRefiner

firstIsIdentity, getAutomorphismGroup, getAutomorphismPartition, getBest, getFirst

Method Detail

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