BALL::AssignBondOrderProcessor Class Reference
[Miscellaneous]

Bond Order assignment processor. More...

#include <assignBondOrderProcessor.h>

Inheritance diagram for BALL::AssignBondOrderProcessor:

[legend]


Classes
struct	Default
	Default values for options. More...
struct	Option
	Option names. More...
Public Member Functions
	BALL_CREATE (AssignBondOrderProcessor)
Constructors and Destructors
	AssignBondOrderProcessor ()
	Default Constructor.
	AssignBondOrderProcessor (const AssignBondOrderProcessor &abop)
	Copy Construcor.
virtual	~AssignBondOrderProcessor ()
	Destructor.
Processor-related methods
virtual bool	start ()
	Processor method which is called before the operator()-call.
void	clear ()
	Clears the datastructures.
virtual Processor::Result	operator() (AtomContainer &ac)
	Operator () for the processor.
virtual bool	finish ()
	Processor method which is called after the operator()-call.
Accessors
Size	getNumberOfAddedHydrogens (Position i)
	Returns the number of added hydrogens in Solution i.
Size	getNumberOfComputedSolutions ()
	Returns the number of already computed solutions.
AtomContainer *	getAtomContainer ()
	Returns a pointer to the original Molecule as AtomContainer.
AtomContainer const *	getAtomContainer () const
	Returns a nonmutable pointer to the original Molecule as AtomContainer.
const System &	getSolution (Position i) throw (Exception::IndexOverflow)
	Returns a reference to the original system to which solution i was applied.
float	getTotalCharge (Position i)
	Returns the total charge of solution i.
float	getTotalPenalty (Position i)
	Returns the total penalty of solution i.
int	getNumberOfNodeExpansions (Position i)
int	getQueueSize (Position i)
bool	apply (Position i)
	Applies the i-th precomputed bond order combination.
void	resetBondOrders ()
	Reset all bond orders and assigned hydrogens.
bool	computeNextSolution (bool apply_solution=true)
	Computes and applies one of the next best solutions.
void	setDefaultOptions ()
	Resets the options to default values.
float	evaluatePenalty (AtomContainer *ac)
	Evaluates the AtomContainer ac's bond orders as specified in the Options and returns the computed penalty.
Assignment
AssignBondOrderProcessor &	operator= (const AssignBondOrderProcessor &abop)
	assignment operator
Public Attributes
Public Attributes
Options	options
	options
Protected Types
enum	HEURISTIC_INDEX { SIMPLE, MEDIUM, TIGHT }
Protected Member Functions
bool	readOptions_ ()
	Reads, checks and stores the options.
bool	readAtomPenalties_ () throw (Exception::FileNotFound())
	Reads and stores the penalty-INIFile (for example BondOrder.ini).
bool	preassignPenaltyClasses_ ()
	Assigns every atom of the AtomContainer to which the processor is applied to a block of possible valences and the corresponding penalties.
int	getPenaltyClass_ (Atom *atom)
	Finds the first matching SMARTS-expression in the penalty-vector and returns its index.
bool	precomputeBondLengthPenalties_ ()
	Precomputes for every bond of the AtomContainer, to which the processor is applied to, the possible bond length penalties resulting from deviation of the actual bond length to a standard length for bonds with same atom types and the chosen bond order.
float	computeVirtualHydrogens_ (Atom *atom)
	Adds missing hydrogens as virtual hydrogens to the given Atom, determines the possible penalty blocks, and returns the maximal possible atom type penalty.
bool	apply_ (Solution_ &solution)
	Applies the given solution.
void	storeOriginalConfiguration_ ()
	Stores the original configuration of the atom container.
int	getQueueSize_ (const Solution_ &sol)
float	getTotalCharge_ (const Solution_ &sol)
	Returns the total charge of a solution.
float	getTotalPenalty_ (const Solution_ &sol)
	Returns the total penalty of the given solution.
int	getNumberOfNodeExpansions_ (const Solution_ &sol)
bool	performBranchAndBound_ ()
vector< PQ_Entry_ >	performGreedy_ (PQ_Entry_ &entry, Size greedy_k=10)
bool	performAStarStep_ ()
	Computes a next solution in the ASTAR - algorithm.
bool	estimatePenalty_ (PQ_Entry_ &entry, bool include_heuristic_term=true)
	Estimates the objective function f = g* + h* of the ASTAR - algorithm, if include_heuristic_term == true, otherwise compute only f = g*.
float	estimateAtomTypePenalty_ (Atom *atom, Index atom_index, int fixed_valence, int fixed_virtual_order, int num_free_bonds, PQ_Entry_ &entry)
	Estimates the atom type penalty for a given unclosed atom.
float	estimateBondLengthPenalty_ (Index atom_index, const vector< Bond * > &free_bonds, int fixed_virtual_order, int fixed_valence, int num_free_bonds)
	Estimates the bond length penalty for a given unclosed atom.
Protected Attributes
bool	valid_
	Processor is in a useable valid state.
bool	evaluation_mode_
	Processor is in an evaluation mode. Default is false.
std::map< Bond *, short >	bond_fixed_
std::vector< Bond * >	free_bonds_
HashMap< Bond *, Index >	bond_to_index_
std::vector< Bond * >	index_to_bond_
HashMap< Atom *, int >	number_of_virtual_hydrogens_
std::vector< int >	virtual_bond_index_to_number_of_virtual_hydrogens_
Size	num_of_virtual_bonds_
vector< Atom * >	virtual_bond_index_to_atom_
HashMap< Atom *, int >	atom_to_virtual_bond_index_
Bond *	virtual_bond_
std::vector< Bond * >	ilp_index_to_free_bond_
Position	ilp_number_of_free_bonds_
float	ilp_const_penalty_
Position	total_num_of_bonds_
int	num_of_free_bonds_
std::vector< Position >	fixed_val_
vector< Solution_ >	solutions_
Solution_	starting_configuration_
float	atom_type_normalization_factor_
float	bond_length_normalization_factor_
int	last_applied_solution_
AtomContainer *	ac_
int	max_bond_order_
float	alpha_
int	max_number_of_solutions_
bool	compute_also_non_optimal_solutions_
bool	add_missing_hydrogens_
bool	compute_also_connectivity_
bool	use_fine_penalty_
HEURISTIC_INDEX	heuristic_index_
float	greedy_atom_type_penalty_
float	greedy_bond_length_penalty_
int	greedy_node_expansions_
std::priority_queue< PQ_Entry_ >	queue_
	The priority queue.
vector< int >	penalties_
vector< Position >	block_to_start_idx_
vector< Size >	block_to_length_
vector< int >	block_to_start_valence_
vector< std::pair< String, String > >	block_definition_
vector< vector< int > >	atom_to_block_
HashMap< Bond *, vector< float > >	bond_lengths_penalties_
int	step_
Timer	timer_
Friends
class	Solution
class	PQ_Entry_

Detailed Description

Bond Order assignment processor.

Assignment of bond orders from topology information.

Called with default options the processor computes up to Default::MAX_NUMBER_OF_SOLUTIONS many possible bond orders with optimal value and applies the first solution found to the given AtomContainer ac_.

All further optimal solutions can be applied by calling the method apply() . Additional solutions can be computed by calling the method computeNextSolution().

Example code:

    AssignBondOrderProcessor bop; 
    bop.options.setBool(AssignBondOrderProcessor::Option::COMPUTE_ALSO_NON_OPTIMAL_SOLUTIONS, true);
    ...
    sys.apply(bop);
    i = bop.getNumberOfComputedSolutions();
    bop.apply(i-1);
    ... 
    while (bop.computeNextSolution())
    {
        i++;
        bop.apply(i);
    }

Member Function Documentation

bool BALL::AssignBondOrderProcessor::apply ( Position i )

Applies the i-th precomputed bond order combination.

Set the AtomContainer ac_'s bond orders to the ones found in the (already computed!) i-th solution, start counting in 0!

NOTE: All virtual hydrogens added to the processed AtomContainer by a previous call of apply will be deleted by the current call!

Parameters:

i

index of the solution, whose bond orders should be assigned.

Returns:: bool - true if the i-th solution is valid, false otherwise.

void BALL::AssignBondOrderProcessor::clear ( )

Clears the datastructures.

NOTE: The options remain! Use setDefaultOptions() to clear the options.

bool BALL::AssignBondOrderProcessor::computeNextSolution ( bool apply_solution = true )

Computes and applies one of the next best solutions.

Ignores the options MAX_NUMBER_OF_SOLUTIONS and COMPUTE_ALSO_NON_OPTIMAL_SOLUTIONS .

Returns:: bool - false if no further solution can be found.

float BALL::AssignBondOrderProcessor::computeVirtualHydrogens_ ( Atom * atom ) [protected]

Adds missing hydrogens as virtual hydrogens to the given Atom, determines the possible penalty blocks, and returns the maximal possible atom type penalty.

"virtual" means that NO atoms and bonds are added to the AtomContainer.

Parameters:

atom

the atom, to which the virtual hydrogens should be added.

Returns:: float - the max possible penalty the atom can get, if hydrogen(s) are added.

See also:: Option::ADD_HYDROGENS

bool BALL::AssignBondOrderProcessor::estimatePenalty_	(	PQ_Entry_ &	entry,
		bool	include_heuristic_term = `true`
	)			`[protected]`

Estimates the objective function f = g* + h* of the ASTAR - algorithm, if include_heuristic_term == true, otherwise compute only f = g*.

The result is stored in the PQ_Entry_ entry's member estimated_atom_type_penalty.

Return values:

	bool	- true, if the entry is still valid.
	bool	- false otherwise.

float BALL::AssignBondOrderProcessor::evaluatePenalty ( AtomContainer * ac )

Evaluates the AtomContainer ac's bond orders as specified in the Options and returns the computed penalty.

Parameters:

ac

AtomContainer, whose bond orders should be evalated.

Returns:: float - computed penalty, -1 if current assignment is not valid or includes aromatic bonds.

Size BALL::AssignBondOrderProcessor::getNumberOfAddedHydrogens ( Position i )

Returns the number of added hydrogens in Solution i.

Returns:: Size - number of hydrogens added in Solution i.

See also:: Option::COMPUTE_ALSO_NON_OPTIMAL_SOLUTIONS
Option::MAX_NUMBER_OF_SOLUTIONS

References BALL::LogStream::error().

Size BALL::AssignBondOrderProcessor::getNumberOfComputedSolutions ( )

Returns the number of already computed solutions.

NOTE: Having applied the operator with option ALGORITHM::ASTAR this method returns the number of optimal solutions+1!

Returns:: Size - number of already computed solutions.

See also:: Option::COMPUTE_ALSO_NON_OPTIMAL_SOLUTIONS
Option::MAX_NUMBER_OF_SOLUTIONS

int BALL::AssignBondOrderProcessor::getPenaltyClass_ ( Atom * atom ) [protected]

Finds the first matching SMARTS-expression in the penalty-vector and returns its index.

Return values:

int

- -1 if there is no matching expression

const System& BALL::AssignBondOrderProcessor::getSolution ( Position i ) throw (Exception::IndexOverflow)

Returns a reference to the original system to which solution i was applied.

NOTE: This method has the same effect as calling apply(i)!

Parameters:

i

index of the solution, whose bond order assignment should be applied.

Returns:: const System& - the original system with bond order assignment of solution i. If i is invalid, an Exception is thrown.

float BALL::AssignBondOrderProcessor::getTotalCharge ( Position i )

Returns the total charge of solution i.

Parameters:

i

index of the solution, whose charge should be computed.

Returns:: float - total charge of solution i.

References BALL::LogStream::error(), and BALL::Maths::max().

float BALL::AssignBondOrderProcessor::getTotalCharge_ ( const Solution_ & sol ) [protected]

Returns the total charge of a solution.

Parameters:

sol

solution, whose charge should be computed.

Returns:: float - total charge of the given solution.

float BALL::AssignBondOrderProcessor::getTotalPenalty ( Position i )

Returns the total penalty of solution i.

Parameters:

i

index of the solution, whose penalty should be returned.

Returns:: float - total penalty of solution i.

See also:: Option:: BOND_LENGTH_WEIGHTING;

References BALL::LogStream::error(), and BALL::Maths::max().

float BALL::AssignBondOrderProcessor::getTotalPenalty_ ( const Solution_ & sol ) [protected]

Returns the total penalty of the given solution.

Parameters:

sol

solution, whose penalty should be returned.

Returns:: float - total penalty of solution i.

See also:: Option::BOND_LENGTH_WEIGHTING;

virtual Processor::Result BALL::AssignBondOrderProcessor::operator() ( AtomContainer & ac ) [virtual]

Operator () for the processor.

Called with Default-options the processor computes all possible bond orders with optimal value and applies the first solution to the given AtomContainer ac_.

NOTE: Having used the Algorithm::A_STAR-option (default) the method getNumberOfComputedSolutions() will return the number of optimal solutions+1!

Parameters:

ac

the AtomContainer to which the processor is applied.

Reimplemented from BALL::UnaryProcessor< AtomContainer >.

bool BALL::AssignBondOrderProcessor::preassignPenaltyClasses_ ( ) [protected]

Assigns every atom of the AtomContainer to which the processor is applied to a block of possible valences and the corresponding penalties.

Return values:

	bool	- false if the AtomContainer to which the processor is applied to has an atom with no matching penalty block.
	bool	- true otherwise

bool BALL::AssignBondOrderProcessor::precomputeBondLengthPenalties_ ( ) [protected]

Precomputes for every bond of the AtomContainer, to which the processor is applied to, the possible bond length penalties resulting from deviation of the actual bond length to a standard length for bonds with same atom types and the chosen bond order.

If there is no information for certain atom pairs, penalty 0 is assumed. In case of incomplete information, we assume the missing bond orders to be really unlikely and we set a penalty to 2* max_deviation_found (for this bond).

Return values:

	bool	- false if the AtomContainer is invalid or the processor is in an invalid state
	bool	- true otherwise

bool BALL::AssignBondOrderProcessor::readAtomPenalties_ ( ) throw (Exception::FileNotFound()) [protected]

Reads and stores the penalty-INIFile (for example BondOrder.ini).

Returns:: bool - false if the INIFile could not be read correctly.

bool BALL::AssignBondOrderProcessor::readOptions_ ( ) [protected]

Reads, checks and stores the options.

Returns:: bool - false if one of the options got an invalid value.
bool - true otherwise

void BALL::AssignBondOrderProcessor::resetBondOrders ( )

Reset all bond orders and assigned hydrogens.

Resets the AtomContainer we are operating on to the bond order configuration it had before applying the AssignBondOrderProcessor.

BALL::AssignBondOrderProcessor Class Reference [Miscellaneous]

Classes

Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Function Documentation

BALL::AssignBondOrderProcessor Class Reference
[Miscellaneous]