net.sf.octet.builder
Interface RepresentationBuilder

All Known Subinterfaces:

FlexMolWriter, MoleculeBuilder, MoleculeQueryBuilder

All Known Implementing Classes:

AbstractMoleculeBuilder, AbstractRepresentationBuilder, BasicFlexMolWriter, BasicMoleculeBuilder, BasicMoleculeQueryBuilder

public interface RepresentationBuilder

A builder of molecular representations. RepresentationBuilder decouples the process of constructing a molecular representation from its implementation, allowing each to vary independently. Molecular representation schemes can vary significantly in their performance characteristics and interfaces. Tight coupling of a representation scheme to a representation build process, as is done in nearly all molecular informatics toolkits, locks developers into a single molecular representation scheme. RepresentatationBuilder is designed to to remedy this situation.

The reasons for constructing a molecular representation vary widely. In some cases, a representation will be written directly to disk or line output. In others, a graph traversal will be performed. Still other uses may involve rendering a molecule in 2-D or 3-D. Each of these tasks will have an optimal representation scheme; this may be a series of ASCII characters, a molecular graph, or a set of polygons, respectively.

RepresentationBuilder presents a uniform abstraction layer to code that needs to generate a particular molecular representation. Thus, the same code that generates benzene as a Molecule can also be used to generate benzene as a FlexMol document. RepresentationBuilder is completely unaware of the type of representation a client is constructing and instead is only aware of a request to construct a representation.

RepresentationBuilder uses two design patterns: "Proxy" and "Builder". In the terminology of the Builder Pattern, RepresentationBuilder is the "builder" and a client that uses it is a "director". Using the Proxy Pattern prevents RepresentationBuilder from refering to implementation-specific components.

Clients may build a valid representation using any sequence of method calls, without an exception being thrown during the build process. For example, if ionization of a BondingSystem results in a temporarily negative electron count, RepresentationBuilder will proceed without throwing an exception.

RepresentationBuilder clients may assume that Atoms are electrically neutral after being added. In other words, ionization occurs from an electron count that is initially set to the Atom's proton count.

No automatic perception of implicit hydrogen count is performed by RepresenationBuilder instances. Clients directly using RepresentationBuilder are, as a result, responsible for ensuring that the appropriate number of virtual hydrogens are added by invoking addHydrogens.

Example usage of RepresentationBuilder can be found in net.sf.octet.util.RepresentationKit.

The code fragment below creates a benzene molecule, which is represented as 1,3,5-cyclohexatriene:

 RepresentationBuilder builder = ...; // get the builder
 IsotopicDistribution carbon =
   AtomicSystem.getNaturalAbundance(AtomicSystem.getSymbol("C"));

 AtomProxy c1 = builder.addAtom(carbon);
 AtomProxy c2 = builder.addAtom(carbon);
 AtomProxy c3 = builder.addAtom(carbon);
 AtomProxy c4 = builder.addAtom(carbon);
 AtomProxy c5 = builder.addAtom(carbon);
 AtomProxy c6 = builder.addAtom(carbon);

 BuilderKit.connectSingle(c1, c2, builder);
 BuilderKit.connectDouble(c2, c3, builder);
 BuilderKit.connectSingle(c3, c4, builder);
 BuilderKit.connectDouble(c4, c5, builder);
 BuilderKit.connectSingle(c5, c6, builder);
 BuilderKit.connectDouble(c6, c1, builder);
 
 builder.addImplicitHydrogens(c1, 1);
 builder.addImplicitHydrogens(c2, 1);
 builder.addImplicitHydrogens(c3, 1);
 builder.addImplicitHydrogens(c4, 1);
 builder.addImplicitHydrogens(c5, 1);
 builder.addImplicitHydrogens(c6, 1);
 

Author:

Richard Apodaca

See Also:

"Builder Pattern (GoF95)", "Proxy Pattern (GoF95)", RepresentationKit

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.
void	flush() Clears the instruction queue.
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.

Method Detail

flush

public void flush()

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

addBondingSystem

public BondingSystemProxy addBondingSystem()

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

Returns:

a proxy to the created BondingSystem

connect

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

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.

Parameters:

source - the proxy for the source atom

target - the proxy for the target atom

system - the proxy for the bonding system

Throws:

NoSuchProxyException - if source, target, or system are not found

IllegalRepresentationException - if source or target can not be connected through system, as is the case, for example, when they are already connected through system

ionizeAtom

public void ionizeAtom(AtomProxy atom,
                       int electronCount)

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).

Parameters:

atom - the proxy for the atom to ionize

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

Throws:

NoSuchProxyException - if atom is not found

addHydrogens

public void addHydrogens(AtomProxy atom,
                         int hydrogenCount)

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.

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

Throws:

NoSuchProxyException - if atom is not found

ionizeBondingElectrons

public void ionizeBondingElectrons(BondingSystemProxy system,
                                   int electronCount)

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).

Parameters:

system - the proxy for the BondingSystem to ionize

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

Throws:

NoSuchProxyExcpetion - if system is not found

ionizeAntibondingElectrons

public void ionizeAntibondingElectrons(BondingSystemProxy system,
                                       int electronCount)

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).

Parameters:

system - the proxy for the BondingSystem to ionize

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

Throws:

NoSuchProxyExcpetion - if system is not found

addConfiguration

public ConfigurationProxy addConfiguration(AtomProxy atom)

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

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

Throws:

IllegalRepresentationException - if atom as already been assigned a Configuration

NoSuchProxyException - if atom is not found

addHalfPlane

public HalfPlaneProxy addHalfPlane(ConfigurationProxy configuration,
                                   AtomProxy neighbor)

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.

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

Throws:

NoSuchProxyException - if either configuration or neighbor are not recognized

IllegalRepresentationException - if a HalfPlane can not be added, for example, due to lack of connectivity of the Atom associated with configuration and neighbor

constrainUpper

public void constrainUpper(AtomProxy atom,
                           HalfPlaneProxy plane)

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.

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

Throws:

java.lang.IllegalArgumentException - if atom can not be added to plane, for example because it has inadequate connectivity

NoSuchProxyException - if either atom or plane are not found

constrainLower

public void constrainLower(AtomProxy atom,
                           HalfPlaneProxy plane)

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.

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

Throws:

java.lang.IllegalArgumentException - if atom can not be added to plane, for example because it has inadequate connectivity

NoSuchProxyException - if either atom or plane are not found

constrainCenter

public void constrainCenter(AtomProxy atom,
                            HalfPlaneProxy plane)

Constrains atom to lie on the horizontal line bisecting plane.

Parameters:

atom - the proxy to the Atom to constrain

plane - the plane in which to constrain atom

Throws:

IllegalRepresentationException - if atom can not be added to plane. One reason could be that plane already has a center Atom. Another reason could be that plane does not support a center Atom because it belongs to a GammaSequence

NoSuchProxyException - if either atom or plane are not found

addGammaSequence

public GammaSequenceProxy addGammaSequence(AtomProxy start)

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.

Parameters:

start - the source of the GammaSequence

Returns:

a proxy for the new GammaSequence

Throws:

NoSuchProxyException - if start is not found

connect

public void connect(AtomProxy atom,
                    GammaSequenceProxy sequence)

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.

Parameters:

atom - the AtomProxy to add to sequence

sequence - the GammaSequence to be extended by atom

Throws:

NoSuchProxyException - if atom or sequence are not found

IllegalRepresentationException - if atom can not be connected through sequence

addHalfPlane

public HalfPlaneProxy addHalfPlane(GammaSequenceProxy sequence)

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.

Parameters:

sequence - a proxy to the GammaSequence

Returns:

a proxy for a HalfPlane to be associated with sequence

addOrbital

public OrbitalProxy addOrbital(AtomProxy atom)

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.

Parameters:

atom - the AtomProxy on which to localize an Orbital

Returns:

a proxy for the Orbital

Throws:

NoSuchProxyException - if atom can not be found

addElectron

public void addElectron(OrbitalProxy orbital,
                        boolean spinUp)

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.

Parameters:

orbital - the OrbitalProxy in which to specify an electron

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

Throws:

NoSuchProxyException - if orbital can not be found

IllegalRepresentationException - if orbital already contains two electrons, or if an electron of spin spinUp is already present in orbital

addAtom

public AtomProxy addAtom(IsotopicDistribution distribution)

Returns an AtomProxy representing an Atom containing the specified IsotopicDistribution.

Parameters:

distribution - the IsotopicDistribtion to be associated with an Atom

Returns:

a proxy for the Atom