BALL::AssignBondOrderProcessor Class Reference
[Miscellaneous]

Assignment of bond orders from topology information. More...

#include <BALL/STRUCTURE/assignBondOrderProcessor.h>

Inheritance diagram for BALL::AssignBondOrderProcessor:

Classes
struct	Algorithm
struct	Default
	Default values for options. More...
struct	Heuristic
struct	Option
	Option names. More...
class	PQ_Entry_
class	Solution_
Public Member Functions
Constructors and Destructors

	AssignBondOrderProcessor ()
	Default Constructor.
virtual	~AssignBondOrderProcessor ()
	Destructor.
Processor-related methods

virtual bool	start ()
	Processor method which is called before the operator()-call.
void	clear ()
virtual Processor::Result	operator() (AtomContainer &ac)
virtual bool	finish ()
	Processor method which is called after the operator()-call.
Accessors

Size	getNumberOfAddedHydrogens (Position i)
Size	getNumberOfComputedSolutions ()
AtomContainer *	getAtomContainer ()
AtomContainer const *	getAtomContainer () const
const System &	getSolution (Position i) throw (Exception::IndexOverflow)
float	getTotalCharge (Position i)
float	getTotalPenalty (Position i=0)
int	getNumberOfNodeExpansions (Position i)
int	getQueueSize (Position i)
bool	apply (Position i)
void	resetBondOrders ()
bool	computeNextSolution (bool apply_solution=true)
void	setDefaultOptions ()
float	evaluatePenalty (AtomContainer *ac)
Public Attributes
Public Attributes

Options	options
	options
Protected Types
enum	HEURISTIC_INDEX { SIMPLE, MEDIUM, TIGHT }
Protected Member Functions
bool	readOptions_ ()
bool	readAtomPenalties_ () throw (Exception::FileNotFound())
bool	preassignPenaltyClasses_ ()
int	getPenaltyClass_ (Atom *atom)
bool	precomputeBondLengthPenalties_ ()
float	computeVirtualHydrogens_ (Atom *atom)
bool	apply_ (Solution_ &solution)
void	storeOriginalConfiguration_ ()
int	getQueueSize_ (const Solution_ &sol)
float	getTotalCharge_ (const Solution_ &sol)
float	getTotalPenalty_ (const Solution_ &sol)
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)
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.
	AssignBondOrderProcessor (const AssignBondOrderProcessor &abop)
AssignBondOrderProcessor &	operator= (const AssignBondOrderProcessor &abop)
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_
vector< 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

Assignment of bond orders from topology information.

Bond Order Assignment Processor 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);
    }

Definition at line 85 of file assignBondOrderProcessor.h.

Member Enumeration Documentation

enum BALL::AssignBondOrderProcessor::HEURISTIC_INDEX [protected]

Enumerator:

SIMPLE
MEDIUM
TIGHT

Definition at line 840 of file assignBondOrderProcessor.h.

Constructor & Destructor Documentation

BALL::AssignBondOrderProcessor::AssignBondOrderProcessor ( )

Default Constructor.

virtual BALL::AssignBondOrderProcessor::~AssignBondOrderProcessor ( ) [virtual]

Destructor.

BALL::AssignBondOrderProcessor::AssignBondOrderProcessor ( const AssignBondOrderProcessor & abop ) [protected]

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.

bool BALL::AssignBondOrderProcessor::apply_ ( Solution_ & solution ) [protected]

Applies the given solution.

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

float BALL::AssignBondOrderProcessor::estimateAtomTypePenalty_	(	Atom *	atom,
		Index	atom_index,
		int	fixed_valence,
		int	fixed_virtual_order,
		int	num_free_bonds,
		PQ_Entry_ &	entry
	)			`[protected]`

Estimates the atom type penalty for a given unclosed atom.

float BALL::AssignBondOrderProcessor::estimateBondLengthPenalty_	(	Index	atom_index,
		const vector< Bond * > &	free_bonds,
		int	fixed_virtual_order,
		int	fixed_valence,
		int	num_free_bonds
	)			`[protected]`

Estimates the bond length penalty for a given unclosed atom.

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.

virtual bool BALL::AssignBondOrderProcessor::finish ( ) [virtual]

Processor method which is called after the operator()-call.

Reimplemented from BALL::UnaryProcessor< AtomContainer >.

AtomContainer const* BALL::AssignBondOrderProcessor::getAtomContainer ( ) const [inline]

Returns a nonmutable pointer to the original Molecule as AtomContainer.

Definition at line 344 of file assignBondOrderProcessor.h.

AtomContainer* BALL::AssignBondOrderProcessor::getAtomContainer ( ) [inline]

Returns a pointer to the original Molecule as AtomContainer.

Definition at line 340 of file assignBondOrderProcessor.h.

Size BALL::AssignBondOrderProcessor::getNumberOfAddedHydrogens ( Position i ) [inline]

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

Definition at line 311 of file assignBondOrderProcessor.h.

Size BALL::AssignBondOrderProcessor::getNumberOfComputedSolutions ( ) [inline]

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

Definition at line 335 of file assignBondOrderProcessor.h.

int BALL::AssignBondOrderProcessor::getNumberOfNodeExpansions ( Position i ) [inline]

Definition at line 397 of file assignBondOrderProcessor.h.

int BALL::AssignBondOrderProcessor::getNumberOfNodeExpansions_ ( const Solution_ & sol ) [inline, protected]

Definition at line 717 of file assignBondOrderProcessor.h.

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

int BALL::AssignBondOrderProcessor::getQueueSize ( Position i ) [inline]

Definition at line 414 of file assignBondOrderProcessor.h.

int BALL::AssignBondOrderProcessor::getQueueSize_ ( const Solution_ & sol ) [inline, protected]

Definition at line 671 of file assignBondOrderProcessor.h.

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 ) [inline]

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.

Definition at line 361 of file assignBondOrderProcessor.h.

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

Returns the total charge of a solution.

Parameters:

sol

solution, whose charge should be computed.

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

Definition at line 679 of file assignBondOrderProcessor.h.

float BALL::AssignBondOrderProcessor::getTotalPenalty ( Position i = 0 ) [inline]

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;

Definition at line 380 of file assignBondOrderProcessor.h.

float BALL::AssignBondOrderProcessor::getTotalPenalty_ ( const Solution_ & sol ) [inline, 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;

Definition at line 697 of file assignBondOrderProcessor.h.

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

AssignBondOrderProcessor& BALL::AssignBondOrderProcessor::operator= ( const AssignBondOrderProcessor & abop ) [protected]

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

Computes a next solution in the ASTAR - algorithm.

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

vector<PQ_Entry_> BALL::AssignBondOrderProcessor::performGreedy_	(	PQ_Entry_ &	entry,
		Size	greedy_k = `10`
	)			`[protected]`

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: