net.sf.octet.query
Class BasicMoleculeQueryBuilder

java.lang.Object
  net.sf.octet.query.BasicMoleculeQueryBuilder

All Implemented Interfaces:

MoleculeQueryBuilder, RepresentationBuilder

public class BasicMoleculeQueryBuilder

extends java.lang.Object

implements MoleculeQueryBuilder

A default implementation of the MoleculeQueryBuilder interface. BasicMoleculeQueryBuilder enables the use of custom MoleculeQueryStrategies to promote flexibility.

Author:

Richard Apodaca

Constructor Summary

BasicMoleculeQueryBuilder(MoleculeQueryStrategy strategy)
Constructs a fully functional BasicMoleculeQueryBuilder that uses the specified MoleculeQueryStrategy.

Method Summary

AtomProxy	addAtom(AtomQuery query) Returns an AtomProxy representing the specified AtomQuery.
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.
MoleculeQuery	releaseQuery() Returns the MoleculeQuery under construction by this MoleculeQueryBuilder and resets the instruction queue.

Methods inherited from class java.lang.Object

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

Constructor Detail

BasicMoleculeQueryBuilder

public BasicMoleculeQueryBuilder(MoleculeQueryStrategy strategy)

Constructs a fully functional BasicMoleculeQueryBuilder that uses the specified MoleculeQueryStrategy.

Method Detail

addAtom

public AtomProxy addAtom(AtomQuery query)

Description copied from interface: MoleculeQueryBuilder

Returns an AtomProxy representing the specified AtomQuery. Rather than matching an exact atomic representation, as is performed when an IsotopicDistribution is used as a parameter, the resulting MoleculeQuery will match query.

Specified by:

addAtom in interface MoleculeQueryBuilder

Parameters:

query - the AtomQuery that will be matched

Returns:

an AtomProxy representing the specified AtomQuery

releaseQuery

public MoleculeQuery releaseQuery()

Description copied from interface: MoleculeQueryBuilder

Returns the MoleculeQuery under construction by this MoleculeQueryBuilder and resets the instruction queue.

Specified by:

releaseQuery in interface MoleculeQueryBuilder

Returns:

the MoleculeQuery under construction by this MoleculeQueryBuilder

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