net.sf.octet.builder
Class AbstractRepresentationBuilder

java.lang.Object
  net.sf.octet.builder.AbstractRepresentationBuilder

All Implemented Interfaces:

RepresentationBuilder

Direct Known Subclasses:

AbstractMoleculeBuilder

public abstract class AbstractRepresentationBuilder

extends java.lang.Object

implements RepresentationBuilder

An abstract implementation of the RepresentationBuilder interface. Use AbstractRepresentationBuidler as a starting point for more specific molecular representation builders. To do so, extend AbstractRepresentationBuilder, provide overrides for the createAtom and createAtomPair methods, and access the builder's state with getAtomTemplates(), getAtomPairs(), getAtoms, and getBondingSystemTemplates.

Author:

Richard Apodaca

Nested Class Summary

protected class	AbstractRepresentationBuilder.AtomTemplate A template for the construction of represenation-specific atoms.
protected class	AbstractRepresentationBuilder.BondingSystemTemplate A template for the construction of represenation-specific bonding systems.
protected class	AbstractRepresentationBuilder.ConfigurationTemplate A template for the construction of represenation-specific configurations.
protected class	AbstractRepresentationBuilder.ConformationTemplate A template for the construction of represenation-specific conformations.
protected class	AbstractRepresentationBuilder.GammaSequenceTemplate A template for the construction of represenation-specific gamma sequences.
protected class	AbstractRepresentationBuilder.HalfPlaneTemplate A template for the construction of represenation-specific half planes.
protected class	AbstractRepresentationBuilder.OrbitalTemplate A template for the construction of represenation-specific orbitals.
protected class	AbstractRepresentationBuilder.PaddleWheelTemplate A template for the construction of represenation-specific paddle wheels.

Constructor Summary

protected

AbstractRepresentationBuilder() Default constructor.

Method Summary

AtomProxy	addAtom(IsotopicDistribution distribution) Returns an AtomProxy representing an Atom containing the specified IsotopicDistribution.
BondingSystemProxy	addBondingSystem() Creates a new BondingSystem and adds it to the current representation.
ConfigurationProxy	addConfiguration(AtomProxy atom) Returns a proxy for a Configuration to be associated with atom.
void	addElectron(OrbitalProxy orbital, boolean spinUp) Populates orbital with one electron of spin spinUp.
GammaSequenceProxy	addGammaSequence(AtomProxy start) Creates a new GammaSequence beginning at start and adds it to the representation under construction.
HalfPlaneProxy	addHalfPlane(ConfigurationProxy configuration, AtomProxy neighbor) Returns a proxy for a HalfPlane to be associated with configuration and the specified neighboring atom neighbor.
HalfPlaneProxy	addHalfPlane(GammaSequenceProxy sequence) Returns a proxy for a HalfPlane to be associated with sequence.
void	addHydrogens(AtomProxy atom, int hydrogenCount) Modifies by hydrogenCount the number of virtual hydrogen atoms associated with atom.
OrbitalProxy	addOrbital(AtomProxy atom) Creates a new, empty, nonbonding Orbital localized on atom.
void	connect(AtomProxy source, AtomProxy target, BondingSystemProxy system) Connects source with target within the BondingSystem denoted by system.
void	connect(AtomProxy atom, GammaSequenceProxy sequence) Adds atom to sequence.
void	constrainCenter(AtomProxy atom, HalfPlaneProxy plane) Constrains atom to lie on the horizontal line bisecting plane.
void	constrainLower(AtomProxy atom, HalfPlaneProxy plane) Constrains atom to lie within the lower portion of the HalfPlane represented by plane.
void	constrainUpper(AtomProxy atom, HalfPlaneProxy plane) Constrains atom to lie within the upper portion of the HalfPlane represented by plane.
protected abstract Atom	createAtom(IsotopicDistribution distribution) Override this method to generate a specialized Atom implementation from distribution.
protected abstract AtomPair	createAtomPair(Atom source, Atom target) Override this method to generate a specialized AtomPair implementation from source and target.
void	flush() Clears the instruction queue.
protected java.util.List	getAtomPairs() Returns an unmodifiable List of AtomPairs currently used by this AbstractRepresenationBuilder.
protected java.util.List	getAtoms() Returns an unmodifiable List of Atoms currently used by this AbstractRepresenationBuilder.
protected java.util.List	getAtomTemplates() Returns an unmodifiable List of AtomTemplates currently used by this AbstractRepresenationBuilder.
protected java.util.List	getBondingSystemTemplates() Returns an unmodifiable List of BondingSystemTemplates currently used by this AbstractRepresenationBuilder.
protected AbstractRepresentationBuilder.ConformationTemplate	getConformationTemplate() Returns the ConformationTemplate currently used by this AbstractRepresenationBuilder.
void	ionizeAntibondingElectrons(BondingSystemProxy system, int electronCount) Modifies by electronCount the number of antibonding electrons belonging to system.
void	ionizeAtom(AtomProxy atom, int electronCount) Modifies by electronCount the number of electrons belonging to atom.
void	ionizeBondingElectrons(BondingSystemProxy system, int electronCount) Modifies by electronCount the number of bonding electrons belonging to system.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractRepresentationBuilder

protected AbstractRepresentationBuilder()

Default constructor.

Method Detail

flush

public void flush()

Description copied from interface: RepresentationBuilder

Clears the instruction queue. This returns the RepresentationBuilder to a state in which it is ready to start building a new representation.

Specified by:

flush in interface RepresentationBuilder

addBondingSystem

public BondingSystemProxy addBondingSystem()

Description copied from interface: RepresentationBuilder

Creates a new BondingSystem and adds it to the current representation.

Specified by:

addBondingSystem in interface RepresentationBuilder

Returns:

a proxy to the created BondingSystem

connect

public void connect(AtomProxy source,
                    AtomProxy target,
                    BondingSystemProxy system)

Description copied from interface: RepresentationBuilder

Connects source with target within the BondingSystem denoted by system. The designation of source and target are not be meaningful. connect produces bonding arrangements suitable for extended pi-systems, organometallic complexes, unoccupied molecular orbitals, and purely electrostatic interactions.

Specified by:

connect in interface RepresentationBuilder

Parameters:

source - the proxy for the source atom

target - the proxy for the target atom

system - the proxy for the bonding system

ionizeAtom

public void ionizeAtom(AtomProxy atom,
                       int electronCount)

Description copied from interface: RepresentationBuilder

Modifies by electronCount the number of electrons belonging to atom. Positive values of electronCount are interpreted as oxidation (electron removal); negative values are interpreded as reduction (electron addition).

Specified by:

ionizeAtom in interface RepresentationBuilder

Parameters:

atom - the proxy for the atom to ionize

electronCount - the number of electrons, positive for oxidation and negative for reduction

addHydrogens

public void addHydrogens(AtomProxy atom,
                         int hydrogenCount)

Description copied from interface: RepresentationBuilder

Modifies by hydrogenCount the number of virtual hydrogen atoms associated with atom. Positive values of hydrogenCount are interpreted as addition of virtual hydrogens; negative values are interpreted as removal of virtual hydrogens. Invocation of addHydrogens also modifies by -hydrogenCount the ionization state of atom.

A "virtual hyrogen" is a hydrogen associated with an atom, but not formally part of the moelcular graph. Many toolkits enable the use of hydrogen-suppressed molecular graphs. This greatly reduces the overhead that would otherwise be incurred by representing hydrogen atoms as nodes in the molecular graph. In most cases, these "implicit hydrogens" are automatically detected. Unfortunately, this system is hard to codify and is well-known for being error-prone.

The intent of the addHydrogens method is enable hydrogen-suppressed graphs to be used within Octet, but to remove the ambiguity associated with automatic hydrogen atom perception. Hydrogen atoms can be explicity placed into molecular graphs with addAtom. Conversely, hydrogen-suppressed molecular graphs can also be generated by using addHydrogens. The same representation may mix both graph-based hydrogens and virtual hydrogens.

Open valencies (i.e. unpaired electrons) not satisfied either through explicit hydrogen addition via addAtom or association with addHydrogens will be interpreted as nonbonding electrons. It is the responsibility of clients to ensure that the correct number of hydrogens is associated with each atom in the molecular representations they construct with RepresentationBuilder.

Specified by:

addHydrogens in interface RepresentationBuilder

Parameters:

atom - the proxy for the atom that will be modified

hydrogenCount - the number of implicit hydrogens, positive values for additions, and negative values for removal

ionizeBondingElectrons

public void ionizeBondingElectrons(BondingSystemProxy system,
                                   int electronCount)

Description copied from interface: RepresentationBuilder

Modifies by electronCount the number of bonding electrons belonging to system. Positive values of electronCount are interpreted as oxidation (electron removal); negative values are interpreded as reduction (electron addition).

Specified by:

ionizeBondingElectrons in interface RepresentationBuilder

Parameters:

system - the proxy for the BondingSystem to ionize

electronCount - the number of electrons, positive for oxidation and negative for reduction

ionizeAntibondingElectrons

public void ionizeAntibondingElectrons(BondingSystemProxy system,
                                       int electronCount)

Description copied from interface: RepresentationBuilder

Modifies by electronCount the number of antibonding electrons belonging to system. Positive values of electronCount are interpreted as oxidation (electron removal); negative values are interpreded as reduction (electron addition).

Specified by:

ionizeAntibondingElectrons in interface RepresentationBuilder

Parameters:

system - the proxy for the BondingSystem to ionize

electronCount - the number of electrons, positive for oxidation and negative for reduction

addConfiguration

public ConfigurationProxy addConfiguration(AtomProxy atom)

Description copied from interface: RepresentationBuilder

Returns a proxy for a Configuration to be associated with atom.

Specified by:

addConfiguration in interface RepresentationBuilder

Parameters:

atom - the proxy to the Atom for which a Configuration should be created

Returns:

a proxy for a Configuration to be associated with atom

addHalfPlane

public HalfPlaneProxy addHalfPlane(ConfigurationProxy configuration,
                                   AtomProxy neighbor)

Description copied from interface: RepresentationBuilder

Returns a proxy for a HalfPlane to be associated with configuration and the specified neighboring atom neighbor. The order in which HalfPlanes are added will result in a clockwise distribution about the axis defined from the atom associated with configuration to neighbor.

Specified by:

addHalfPlane in interface RepresentationBuilder

Parameters:

configuration - the Configuration

neighbor - the neighbor of the Atom associated with configuration

Returns:

a proxy for a HalfPlane to be associated with configuration and the specified neighboring atom neighbor

constrainUpper

public void constrainUpper(AtomProxy atom,
                           HalfPlaneProxy plane)

Description copied from interface: RepresentationBuilder

Constrains atom to lie within the upper portion of the HalfPlane represented by plane. The order in which Atoms are added defines the ordering in the resulting HalfPlane; Atoms added first are considered closer to the horizontal line bisecting plane.

Specified by:

constrainUpper in interface RepresentationBuilder

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

constrainLower

public void constrainLower(AtomProxy atom,
                           HalfPlaneProxy plane)

Description copied from interface: RepresentationBuilder

Constrains atom to lie within the lower portion of the HalfPlane represented by plane. The order in which Atoms are added defines the ordering in the resulting HalfPlane; Atoms added first are considered closer to the horizontal line bisecting plane.

Specified by:

constrainLower in interface RepresentationBuilder

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

constrainCenter

public void constrainCenter(AtomProxy atom,
                            HalfPlaneProxy plane)

Description copied from interface: RepresentationBuilder

Constrains atom to lie on the horizontal line bisecting plane.

Specified by:

constrainCenter in interface RepresentationBuilder

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

addGammaSequence

public GammaSequenceProxy addGammaSequence(AtomProxy start)

Description copied from interface: RepresentationBuilder

Creates a new GammaSequence beginning at start and adds it to the representation under construction.

Note: each GammaSequence is specified only once. Thus, it is not necessary, for example, to specify both A-B and B-A GammaSequences, where A and B refer to two neighboring nonterminal atoms.

Specified by:

addGammaSequence in interface RepresentationBuilder

Parameters:

start - the source of the GammaSequence

Returns:

a proxy for the new GammaSequence

connect

public void connect(AtomProxy atom,
                    GammaSequenceProxy sequence)

Description copied from interface: RepresentationBuilder

Adds atom to sequence.

Note: each GammaSequence is specified only once. Thus, it is not necessary, for example, to specify both A-B and B-A GammaSequences, where A and B refer to two neighboring nonterminal atoms.

Specified by:

connect in interface RepresentationBuilder

Parameters:

atom - the AtomProxy to add to sequence

sequence - the GammaSequence to be extended by atom

addHalfPlane

public HalfPlaneProxy addHalfPlane(GammaSequenceProxy sequence)

Description copied from interface: RepresentationBuilder

Returns a proxy for a HalfPlane to be associated with sequence. The order in which HalfPlanes are added will result in a clockwise distribution about the axis defined by sequence, with the first atom in the gamma sequence at the bottom and the last atom at the top.

Specified by:

addHalfPlane in interface RepresentationBuilder

Parameters:

sequence - a proxy to the GammaSequence

Returns:

a proxy for a HalfPlane to be associated with sequence

addOrbital

public OrbitalProxy addOrbital(AtomProxy atom)

Description copied from interface: RepresentationBuilder

Creates a new, empty, nonbonding Orbital localized on atom. Returns an OrbitalProxy that can be used to to subsequently populate the underlying Orbital with Electrons.

Specified by:

addOrbital in interface RepresentationBuilder

Parameters:

atom - the AtomProxy on which to localize an Orbital

Returns:

a proxy for the Orbital

addElectron

public void addElectron(OrbitalProxy orbital,
                        boolean spinUp)

Description copied from interface: RepresentationBuilder

Populates orbital with one electron of spin spinUp. If true , spinUp results in an Electron with a positive spin. If false, spinUp results in an Electron with a negative spin.

Invocation of addElectron does not change the number of electrons otherwise associated with the atom owning orbital. Thus, the electron populating orbital is generated de novo, rather than being taken from the associated atom representation. To "transfer" an electron from an atom representation to an orbital associated with it, both addElectron and ionizeAtom will be necessary.

Specified by:

addElectron in interface RepresentationBuilder

Parameters:

orbital - the OrbitalProxy in which to specify an electron

spinUp - true for positive spin, or false for negative spin

addAtom

public AtomProxy addAtom(IsotopicDistribution distribution)

Description copied from interface: RepresentationBuilder

Returns an AtomProxy representing an Atom containing the specified IsotopicDistribution.

Specified by:

addAtom in interface RepresentationBuilder

Parameters:

distribution - the IsotopicDistribtion to be associated with an Atom

Returns:

a proxy for the Atom

getAtoms

protected java.util.List getAtoms()

Returns an unmodifiable List of Atoms currently used by this AbstractRepresenationBuilder.

Returns:

an unmodifiable List of Atoms currently used by this AbstractRepresenationBuilder

getAtomTemplates

protected java.util.List getAtomTemplates()

Returns an unmodifiable List of AtomTemplates currently used by this AbstractRepresenationBuilder.

Returns:

an unmodifiable List of AtomTemplates currently used by this AbstractRepresenationBuilder

getAtomPairs

protected java.util.List getAtomPairs()

Returns an unmodifiable List of AtomPairs currently used by this AbstractRepresenationBuilder.

Returns:

an unmodifiable List of AtomPairs currently used by this AbstractRepresenationBuilder

getBondingSystemTemplates

protected java.util.List getBondingSystemTemplates()

Returns an unmodifiable List of BondingSystemTemplates currently used by this AbstractRepresenationBuilder.

Returns:

an unmodifiable List of BondingSystemTemplates currently used by this AbstractRepresenationBuilder

getConformationTemplate

protected AbstractRepresentationBuilder.ConformationTemplate getConformationTemplate()

Returns the ConformationTemplate currently used by this AbstractRepresenationBuilder.

Returns:

the ConformationTemplate currently used by this AbstractRepresenationBuilder

createAtom

protected abstract Atom createAtom(IsotopicDistribution distribution)

Override this method to generate a specialized Atom implementation from distribution.

Parameters:

distribution - the IsotopicDistribution to be used by the Atom

Returns:

a specialized Atom implementation

createAtomPair

protected abstract AtomPair createAtomPair(Atom source,
                                           Atom target)

Override this method to generate a specialized AtomPair implementation from source and target.

Parameters:

source - the source Atom

target - the target Atom

Returns:

a specialized AtomPair implementation