Acts as the central hub for an iterative algorithm. More...

#include <IterationPack_Algorithm.hpp>

Inheritance diagram for IterationPack::Algorithm:

Classes
class	AlgorithmInterrupted
	Thrown if Algorithm was interrupted by the user. More...

class	AlreadyExists
	Thrown if name already exists. More...

struct	assoc_steps_ele_t

class	DoesNotExist
	Thrown if name or id does not exist. More...

class	InvalidConfigChange
	Thrown if a member function is called while `this` is in an invalid running state.. More...

class	InvalidControlProtocal
	Thrown if an invalid control protocal is used. More...

class	InvalidRunningState
	Thrown if a member function is called while `this` is in an invalid running state.. More...

class	name_comp

struct	step_ptr_and_name

Public Member Functions
	STANDARD_MEMBER_COMPOSITION_MEMBERS (std::string, interrupt_file_name)
	Name of an file that will cause the algorithm to terminate. More...

Static Public Member Functions
static void	interrupt ()

Private Types
enum	ETerminateStatus { STATUS_KEEP_RUNNING, STATUS_TERMINATE_TRUE, STATUS_TERMINATE_FALSE }

enum	{ NUM_STEP_TIME_STATS = 5 }

typedef step_ptr_and_name < step_ptr_t >	steps_ele_t

typedef std::deque< steps_ele_t >	steps_t

typedef step_ptr_and_name < step_ptr_t >	assoc_steps_ele_list_ele_t

typedef std::list < assoc_steps_ele_list_ele_t >	assoc_steps_ele_list_t

typedef std::deque < assoc_steps_ele_t >	assoc_steps_t

typedef std::vector< double >	step_times_t

typedef void(AlgorithmStep::*	inform_func_ptr_t )(Algorithm &algo, poss_type step_poss, EDoStepType type, poss_type assoc_step_poss)

Private Member Functions
poss_type	validate (poss_type step_poss, int past_end=0) const
	Validate a step_poss and throw a DoesNotExist exception if it does not. More...

poss_type	validate (const assoc_steps_ele_list_t &assoc_list, poss_type assoc_step_poss, int past_end=0) const
	Validate an assoc_step_poss and throw a DoesNotExist exception if it does not. More...

void	change_running_state (ERunningState running_state)
	Change the running state. More...

void	validate_in_state (ERunningState running_state) const
	Validate that `this` is in a specific running state. More...

void	validate_not_in_state (ERunningState running_state) const
	Validate that `this` is not in a specific running state. More...

void	validate_not_curr_step (poss_type step_poss) const
	Validate that the step_poss in not the current step. More...

void	validate_not_next_step (const std::string &step_name) const
	Validate that the step_name in not the next step. More...

steps_t::iterator	step_itr (const std::string &step_name)
	Find a step given its name and throw a DoesNotExist exception if not found. More...

steps_t::const_iterator	step_itr (const std::string &step_name) const

steps_t::iterator	step_itr_and_assert (const std::string &step_name)
	Find a step given its name and throw a DoesNotExist exception if not found. More...

steps_t::const_iterator	step_itr_and_assert (const std::string &step_name) const

bool	imp_do_step (poss_type step_poss)

bool	imp_do_assoc_steps (EAssocStepType type)

void	imp_inform_steps (inform_func_ptr_t inform_func_ptr)

void	imp_print_algorithm (std::ostream &out, bool print_steps) const

EDoStepType	do_step_type (EAssocStepType assoc_step_type)
	EAssocStepType -> EDoStepType. More...

EAlgoReturn	finalize_algorithm (EAlgoReturn algo_return)

void	compute_final_time_stats () const

void	look_for_interrupt ()

Static Private Member Functions
static assoc_steps_ele_list_t::iterator	assoc_step_itr (assoc_steps_ele_list_t &assoc_list, const std::string &assoc_step_name)
	Find a an associated step given its name and throw a DoesNotExist exception if not found. More...

static assoc_steps_ele_list_t::const_iterator	assoc_step_itr (const assoc_steps_ele_list_t &assoc_list, const std::string &assoc_step_name)

Private Attributes
AlgorithmState *	state

AlgorithmTracker *	track

AlgorithmStep *	steps

ERunningState	running_state_

size_t	first_k_

size_t	max_iter_

double	max_run_time_

ETerminateStatus	terminate_status_

poss_type	next_step_poss_

const std::string *	next_step_name_

bool	do_step_next_called_

poss_type	curr_step_poss_

std::string	saved_curr_step_name_

std::string	saved_next_step_name_

bool	reconfigured_

steps_t	steps_

assoc_steps_t	assoc_steps_

bool	algo_timing_

step_times_t	step_times_

bool	time_stats_computed_

double	total_time_

Static Private Attributes
static const int	TIME_STAT_TOTALS_OFFSET = 0

static const int	TIME_STAT_AV_OFFSET = 1

static const int	TIME_STAT_MIN_OFFSET = 2

static const int	TIME_STAT_MAX_OFFSET = 3

static const int	TIME_STAT_PERCENT_OFFSET = 4

Public types
enum	{ DOES_NOT_EXIST = 1000 }

enum	ERunningState { NOT_RUNNING = 0, RUNNING = 1, RUNNING_BEING_CONFIGURED = 2 }

typedef Teuchos::RCP < AlgorithmState >	state_ptr_t

typedef Teuchos::RCP < AlgorithmTracker >	track_ptr_t

typedef Teuchos::RCP < AlgorithmStep >	step_ptr_t

typedef size_t	poss_type

Constructors & destructors
	Algorithm ()
	Constructs an algorithm with no steps and a default of max_iter() == 100. More...

virtual	~Algorithm ()

�std comp� members for state
void	set_state (const state_ptr_t &state)

state_ptr_t &	get_state ()

const state_ptr_t &	get_state () const

AlgorithmState &	state ()

const AlgorithmState &	state () const

�std comp� members for track
void	set_track (const track_ptr_t &track)

track_ptr_t &	get_track ()

const track_ptr_t &	get_track () const

AlgorithmTracker &	track ()

const AlgorithmTracker &	track () const

Maximum iterations
virtual void	max_iter (size_t max_iter)

virtual size_t	max_iter () const

Maximum runtime (in minutes)
virtual void	max_run_time (double max_iter)
	Set the maximum runtime (in minues) The runtime is checked at the end of each iteration and if it exceeds this value then the algorithm is terminated. More...

virtual double	max_run_time () const

Step information & access
virtual int	num_steps () const
	Return the number of main steps. More...

virtual poss_type	get_step_poss (const std::string &step_name) const
	Return the possition in the major loop of a named step. More...

virtual const std::string &	get_step_name (poss_type step_poss) const
	Return the name of a step given its possition. More...

virtual step_ptr_t &	get_step (poss_type step_poss)
	Return the RCP<...> object for the step object at step_poss. More...

virtual const step_ptr_t &	get_step (poss_type step_poss) const

Pre/post step information & access
virtual int	num_assoc_steps (poss_type step_poss, EAssocStepType type) const
	Return the number of pre or post steps for the main step step_poss. More...

virtual poss_type	get_assoc_step_poss (poss_type step_poss, EAssocStepType type, const std::string &assoc_step_name) const
	Return the possition of the pre or post step for the main step_poss. More...

virtual const std::string &	get_assoc_step_name (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss) const
	Return the name of the pre or post step at step_poss and at assoc_step_poss. More...

virtual step_ptr_t &	get_assoc_step (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss)
	Return the RCP<...> object for the associated step object at step_poss and assoc_step_poss. More...

virtual const step_ptr_t &	get_assoc_step (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss) const

Step manipulation
virtual void	insert_step (poss_type step_poss, const std::string &step_name, const step_ptr_t &step)
	Insert a step object with the name `step_name` into the possition `step_poss`. More...

virtual void	change_step_name (poss_type step_poss, const std::string &new_name)
	Change the name of an existing step. More...

virtual void	replace_step (poss_type step_poss, const step_ptr_t &step)
	Replace the step object of an existing step. More...

virtual void	remove_step (poss_type step_poss)
	Remove an existing step object and all of its pre and post steps. More...

Pre/post step manipulation
virtual void	insert_assoc_step (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss, const std::string &assoc_step_name, const step_ptr_t &assoc_step)
	Insert an pre or post step into for the main step step_poss into the possition assoc_step_poss. More...

virtual void	remove_assoc_step (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss)
	Remove an pre or post step for the main step step_poss in the possition assoc_step_poss. More...

Runtime configuration updating control
ERunningState	running_state () const
	Return the current running state of `this` algorithm object. More...

virtual void	begin_config_update ()
	Changes from running_state() == RUNNING to running_state() == RUNNING_BEING_CONFIGURED. More...

virtual void	end_config_update ()
	Changes from running_state() == RUNNING_BEING_CONFIGURED to running_state() == RUNNING. More...

Algorithmic control
virtual void	do_step_next (const std::string &step_name)
	Called by step objects to set the step (given its name) that `this` will envoke the next time `this` calls a step. More...

virtual void	do_step_next (poss_type step_poss)
	Called by step objects to set the step (given its possition) that `this` will envoke the next time `this` calls a step. More...

virtual const std::string &	what_is_next_step_name () const
	Returns the name of the next step `this` will call the next time it calls a step. More...

virtual poss_type	what_is_next_step_poss () const
	Returns the possition of the next step `this` will call the next time it calls a step. More...

virtual bool	do_step (const std::string &step_name)
	Calls `do_step()` on all of the pre step objects the step object and the post step objects in order for the step named `step_name`. More...

virtual bool	do_step (poss_type step_poss)
	Call `do_step()` on all of the pre step objects the step object and the post step objects in order for the step in the possition `step_poss`. More...

virtual void	terminate (bool success)
	Called by step objects to terminate the algorithm. More...

Start iterations
virtual EAlgoReturn	do_algorithm (poss_type step_poss=1)
	Called by clients to begin an algorithm. More...

Algorithm information output
virtual void	print_steps (std::ostream &out) const
	Print out just a listing of the steps, their positions in the algorithm and the subclasses. More...

virtual void	print_algorithm (std::ostream &out) const
	Print out the entire algorithm by calling `print_step(...)` on the step objects. More...

Algorithm Timing
virtual void	set_algo_timing (bool algo_timing)
	Causes algorithm to be timed. More...

virtual bool	algo_timing () const

virtual void	print_algorithm_times (std::ostream &out) const
	Outputs table of times for each step, cummulative times and other statistics. More...

void	get_step_times_k (int offset, double step_times[]) const
	Returns the step_times for iteration offset. More...

void	get_final_step_stats (size_t step, double total, double average, double min, double max, double *percent) const
	Returns the final statistics for a given step Do not call when algorithm is running. More...

Detailed Description

Acts as the central hub for an iterative algorithm.

This class is the center for a framework for iterative algorithms. These iterative algorithms are of the form:

Step1------>Step2------>Step3------>Step4------>Step5
 /|\         /|\         /|\          |           |
  |           |           |_Minor L 1_|           |
  |           |                       |           |
  |           |_____Minor Loop 2______|           |
  |                                               |
  |_______________Major Loop (k = k+1)____________|

For the typical iteration the steps are executed sequantially from Step1 to Step2 and then control loops around the Major Loop to Step1 again. Durring some iterations however Minor Loop 1 may be executed several times before control is continued alone the major loop. The same may also apply to Minor Loop 2.

To allow for greater algorithmic control any step object can take over the role of Algorithm and take over complete control the algorithm. For examle, Step 4 may need to Execute Step1->Step3->Step2->Step5 before returning algorithmic control to Algorithm.

Algorithm executes the steps of the algorithm through step objects of the base type AlgorithmStep. In addition to major step objects as shown above there are also PreStep and PostStep objects. These are steps that are intimatly associated with a major step object and will always (well almost always) be exectuted alone with a major step.

ToDo: Finish documentation.

These functions provide information as to the number of major steps , their possitions given their names and their names given their possitions.

In addition, access is given to the step objects themselves through the RCP<...> objects that are used to manage thier memory. Using this type of direct access allows clients to take over memory management if needed and to call the step objects in any order and thereby taking over control of the algorithm.

These functions can be invoked in any state of the algorithm.

Note that the currently running algorithm can always be interupted by invoking the SIGINT signal (i.e. Ctrl-C) from the console.

Definition at line 114 of file IterationPack_Algorithm.hpp.

Member Typedef Documentation

typedef Teuchos::RCP<AlgorithmState> IterationPack::Algorithm::state_ptr_t

Definition at line 121 of file IterationPack_Algorithm.hpp.

typedef Teuchos::RCP<AlgorithmTracker> IterationPack::Algorithm::track_ptr_t

Definition at line 123 of file IterationPack_Algorithm.hpp.

typedef Teuchos::RCP<AlgorithmStep> IterationPack::Algorithm::step_ptr_t

Definition at line 125 of file IterationPack_Algorithm.hpp.

typedef size_t IterationPack::Algorithm::poss_type

Definition at line 127 of file IterationPack_Algorithm.hpp.

typedef step_ptr_and_name<step_ptr_t> IterationPack::Algorithm::steps_ele_t

private

Definition at line 684 of file IterationPack_Algorithm.hpp.

typedef std::deque<steps_ele_t> IterationPack::Algorithm::steps_t

private

Definition at line 686 of file IterationPack_Algorithm.hpp.

typedef step_ptr_and_name<step_ptr_t> IterationPack::Algorithm::assoc_steps_ele_list_ele_t

private

Definition at line 689 of file IterationPack_Algorithm.hpp.

typedef std::list<assoc_steps_ele_list_ele_t> IterationPack::Algorithm::assoc_steps_ele_list_t

private

Definition at line 691 of file IterationPack_Algorithm.hpp.

typedef std::deque<assoc_steps_ele_t> IterationPack::Algorithm::assoc_steps_t

private

Definition at line 706 of file IterationPack_Algorithm.hpp.

typedef std::vector<double> IterationPack::Algorithm::step_times_t

private

Definition at line 723 of file IterationPack_Algorithm.hpp.

typedef void(AlgorithmStep::* IterationPack::Algorithm::inform_func_ptr_t)(Algorithm &algo,poss_type step_poss,EDoStepType type,poss_type assoc_step_poss)

private

Definition at line 736 of file IterationPack_Algorithm.hpp.

Member Enumeration Documentation

anonymous enum

Enumerator
DOES_NOT_EXIST

Definition at line 129 of file IterationPack_Algorithm.hpp.

enum IterationPack::Algorithm::ERunningState

Enumerator
NOT_RUNNING
RUNNING
RUNNING_BEING_CONFIGURED

Definition at line 131 of file IterationPack_Algorithm.hpp.

enum IterationPack::Algorithm::ETerminateStatus

private

Enumerator
STATUS_KEEP_RUNNING
STATUS_TERMINATE_TRUE
STATUS_TERMINATE_FALSE

Definition at line 709 of file IterationPack_Algorithm.hpp.

anonymous enum

private

Enumerator
NUM_STEP_TIME_STATS

Definition at line 733 of file IterationPack_Algorithm.hpp.

Constructor & Destructor Documentation

IterationPack::Algorithm::Algorithm ( )

Constructs an algorithm with no steps and a default of max_iter() == 100.

Definition at line 104 of file IterationPack_Algorithm.cpp.

IterationPack::Algorithm::~Algorithm ( )

virtual

Definition at line 138 of file IterationPack_Algorithm.cpp.

Member Function Documentation

IterationPack::Algorithm::STANDARD_MEMBER_COMPOSITION_MEMBERS	(	std::string	,
		interrupt_file_name
	)

Name of an file that will cause the algorithm to terminate.

If interrupt_file_name()!="" then the file interrupt_file_name() will be looked for in the current directory and if it exists, it will be read to determine how the algorithm should be terminated. The format of this file is as follows:

abort_mode  terminate_bool

Above, abort_mode can be: a for "abort the program immediately", s for "Gracefully terminate the algorithm at the end of this step", i for "Gracefully terminate the algorithm at the end of this iteration"

If the option abort_mode is set to s or i then the the value of terminate_bool must be set to t for "true" or f for "false". If this abort_mode is set ot a then the value of terminate_bool is not read.

Note that the option values abort_mode and terminate_bool are simple char data objects and the only requirement is that they be seperated by whitespace.

If the format of this file is not as described above, then an exception will be thrown (which will have the affect of aborting the process most likely).

The default is interrupt_file_name()=="" which means that this file will not be looked for.

void IterationPack::Algorithm::set_state ( const state_ptr_t & state )

inline

Definition at line 940 of file IterationPack_Algorithm.hpp.

Algorithm::state_ptr_t & IterationPack::Algorithm::get_state ( )

inline

Definition at line 944 of file IterationPack_Algorithm.hpp.

const Algorithm::state_ptr_t & IterationPack::Algorithm::get_state ( ) const

inline

Definition at line 948 of file IterationPack_Algorithm.hpp.

AlgorithmState& IterationPack::Algorithm::state ( )

const AlgorithmState& IterationPack::Algorithm::state ( ) const

void IterationPack::Algorithm::set_track ( const track_ptr_t & track )

inline

Definition at line 962 of file IterationPack_Algorithm.hpp.

Algorithm::track_ptr_t & IterationPack::Algorithm::get_track ( )

inline

Definition at line 966 of file IterationPack_Algorithm.hpp.

const Algorithm::track_ptr_t & IterationPack::Algorithm::get_track ( ) const

inline

Definition at line 970 of file IterationPack_Algorithm.hpp.

AlgorithmTracker& IterationPack::Algorithm::track ( )

const AlgorithmTracker& IterationPack::Algorithm::track ( ) const

void IterationPack::Algorithm::max_iter ( size_t max_iter )

virtual

Definition at line 143 of file IterationPack_Algorithm.cpp.

size_t IterationPack::Algorithm::max_iter ( ) const

virtual

Definition at line 146 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::max_run_time ( double max_iter )

virtual

Set the maximum runtime (in minues) The runtime is checked at the end of each iteration and if it exceeds this value then the algorithm is terminated.

Definition at line 151 of file IterationPack_Algorithm.cpp.

double IterationPack::Algorithm::max_run_time ( ) const

virtual

Definition at line 154 of file IterationPack_Algorithm.cpp.

int IterationPack::Algorithm::num_steps ( ) const

virtual

Return the number of main steps.

Definition at line 160 of file IterationPack_Algorithm.cpp.

Algorithm::poss_type IterationPack::Algorithm::get_step_poss ( const std::string & step_name ) const

virtual

Return the possition in the major loop of a named step.

If a step with this name does not exist then the value DOES_NOT_EXIST will be returned.

Definition at line 163 of file IterationPack_Algorithm.cpp.

const std::string & IterationPack::Algorithm::get_step_name ( poss_type step_poss ) const

virtual

Return the name of a step given its possition.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 169 of file IterationPack_Algorithm.cpp.

Algorithm::step_ptr_t & IterationPack::Algorithm::get_step ( poss_type step_poss )

virtual

Return the RCP<...> object for the step object at step_poss.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 172 of file IterationPack_Algorithm.cpp.

const Algorithm::step_ptr_t & IterationPack::Algorithm::get_step ( poss_type step_poss ) const

virtual

Definition at line 175 of file IterationPack_Algorithm.cpp.

int IterationPack::Algorithm::num_assoc_steps	(	poss_type	step_poss,
		EAssocStepType	type
	)		const

virtual

Return the number of pre or post steps for the main step step_poss.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 180 of file IterationPack_Algorithm.cpp.

Algorithm::poss_type IterationPack::Algorithm::get_assoc_step_poss	(	poss_type	step_poss,
		EAssocStepType	type,
		const std::string &	assoc_step_name
	)		const

virtual

Return the possition of the pre or post step for the main step_poss.

If a pre or post step does not exist with the name assoc_step_name then a value of DOES_NOT_EXIST will be retruned.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 183 of file IterationPack_Algorithm.cpp.

const std::string & IterationPack::Algorithm::get_assoc_step_name	(	poss_type	step_poss,
		EAssocStepType	type,
		poss_type	assoc_step_poss
	)		const

virtual

Return the name of the pre or post step at step_poss and at assoc_step_poss.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)
1 <= assoc_step_poss && assoc_step_poss <= num_assoc_steps(step_poss,type) (throw DoesNotExist)

Definition at line 192 of file IterationPack_Algorithm.cpp.

Algorithm::step_ptr_t & IterationPack::Algorithm::get_assoc_step	(	poss_type	step_poss,
		EAssocStepType	type,
		poss_type	assoc_step_poss
	)

virtual

Return the RCP<...> object for the associated step object at step_poss and assoc_step_poss.

Preconditions:

1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)
1 <= assoc_step_poss && assoc_step_poss <= num_assoc_steps(step_poss,type) (throw DoesNotExist)

Definition at line 202 of file IterationPack_Algorithm.cpp.

const Algorithm::step_ptr_t & IterationPack::Algorithm::get_assoc_step	(	poss_type	step_poss,
		EAssocStepType	type,
		poss_type	assoc_step_poss
	)		const

virtual

Definition at line 212 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::insert_step	(	poss_type	step_poss,
		const std::string &	step_name,
		const step_ptr_t &	step
	)

virtual

Insert a step object with the name step_name into the possition step_poss.

All the steps at and after step_poss are pushed back one possition unless step_poss == num_steps() + 1 in which case the new step is appended to the end. Initiaily this step will have no pre or post steps associated with it.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= ste_poss && step_poss <= num_steps() + 1 (throw DoesNotExist)
step.get() != NULL (throw std::invalid_argument)

Definition at line 224 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::change_step_name	(	poss_type	step_poss,
		const std::string &	new_name
	)

virtual

Change the name of an existing step.

None of the pre or post steps for the existing step are changes.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= poss && poss <= num_steps() (throw DoesNotExist)

Definition at line 249 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::replace_step	(	poss_type	step_poss,
		const step_ptr_t &	step
	)

virtual

Replace the step object of an existing step.

None of the pre or post steps for the existing step are changes.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= poss && poss <= num_steps() (throw DoesNotExist)

Definition at line 259 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::remove_step ( poss_type step_poss )

virtual

Remove an existing step object and all of its pre and post steps.

All of the steps after step_poss will have thier possitions decreased by one.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= poss && poss <= num_steps() (throw DoesNotExist)

Definition at line 266 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::insert_assoc_step	(	poss_type	step_poss,
		EAssocStepType	type,
		poss_type	assoc_step_poss,
		const std::string &	assoc_step_name,
		const step_ptr_t &	assoc_step
	)

virtual

Insert an pre or post step into for the main step step_poss into the possition assoc_step_poss.

All of the pre or post steps at and after assoc_step_poss will be pushed back one possition.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= step_poss && step_poss <= num_steps() + 1 (throw DoesNotExist)
1 <= assoc_step_poss && assoc_step_poss <= num_assoc_steps(step_poss,type) + 1 (throw DoesNotExist)
assoc_step.get() != NULL (throw std::invalid_argument)

Definition at line 285 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::remove_assoc_step	(	poss_type	step_poss,
		EAssocStepType	type,
		poss_type	assoc_step_poss
	)

virtual

Remove an pre or post step for the main step step_poss in the possition assoc_step_poss.

All of the pre or post steps after assoc_step_poss will be pushed forward one possition to fill in the hole.

Preconditions:

running_state() != RUNNING] (throw InvalidRunningState)
1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)
1 <= assoc_step_poss && assoc_step_poss <= num_assoc_steps(step_poss,type) (throw DoesNotExist)

Definition at line 317 of file IterationPack_Algorithm.cpp.

Algorithm::ERunningState IterationPack::Algorithm::running_state ( ) const

inline

Return the current running state of this algorithm object.

Definition at line 984 of file IterationPack_Algorithm.hpp.

void IterationPack::Algorithm::begin_config_update ( )

virtual

Changes from running_state() == RUNNING to running_state() == RUNNING_BEING_CONFIGURED.

Must be called before the algorithm's configuration can be changed while it is running.

Preconditions:

running_state() == RUNNING] (throw InvalidRunningState)

Postconditions:

running_state() == RUNNING_BEING_CONFIGURED]

Definition at line 331 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::end_config_update ( )

virtual

Changes from running_state() == RUNNING_BEING_CONFIGURED to running_state() == RUNNING.

Must be called after the algorithm's configuration can be changed while it is running.

Preconditions:

running_state() == RUNNING_BEING_CONFIGURED] (throw InvalidRunningState)

Postconditions:

running_state() == RUNNING]

Definition at line 339 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::do_step_next ( const std::string & step_name )

virtual

Called by step objects to set the step (given its name) that this will envoke the next time this calls a step.

Preconditions:

running_state() == RUNNING (throw InvalidRunningState)
get_step_poss(step_name) != DOES_NOT_EXIST (throw DoesNotExist)

Definition at line 363 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::do_step_next ( poss_type step_poss )

virtual

Called by step objects to set the step (given its possition) that this will envoke the next time this calls a step.

Preconditions:

running_state() == RUNNING (throw InvalidRunningState)
1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 372 of file IterationPack_Algorithm.cpp.

const std::string & IterationPack::Algorithm::what_is_next_step_name ( ) const

virtual

Returns the name of the next step this will call the next time it calls a step.

Preconditions:

running_state() != NOT_RUNNING (throw InvalidRunningState)

Definition at line 381 of file IterationPack_Algorithm.cpp.

Algorithm::poss_type IterationPack::Algorithm::what_is_next_step_poss ( ) const

virtual

Returns the possition of the next step this will call the next time it calls a step.

Preconditions:

running_state() != NOT_RUNNING (throw InvalidRunningState)

Definition at line 387 of file IterationPack_Algorithm.cpp.

bool IterationPack::Algorithm::do_step ( const std::string & step_name )

virtual

Calls do_step() on all of the pre step objects the step object and the post step objects in order for the step named step_name.

This operation is called by step objects that need to take over control of the algorithm at some point.

If any of the of the pre or post objects or the step object returns false, then this operation immediatly returns false. It is assumed that if any step object returns false from its do_step() that it has either also called terminate() or do_step_next().

Preconditions:

running_state() == RUNNING (throw InvalidRunningState)
get_step_poss(step_name) != DOES_NOT_EXIST (throw DoesNotExist)

Definition at line 393 of file IterationPack_Algorithm.cpp.

bool IterationPack::Algorithm::do_step ( poss_type step_poss )

virtual

Call do_step() on all of the pre step objects the step object and the post step objects in order for the step in the possition step_poss.

This operation is called by step objects that need to take over control of the algorithm at some point.

If any of the of the pre or post objects or the step object returns false, then this operation immediatly returns false. It is assumed that if any step object returns false from do step that it has either also called terminate() or do_step_next().

Preconditions:

running_state() == RUNNING (throw InvalidRunningState)
1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

Definition at line 399 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::terminate ( bool success )

virtual

Called by step objects to terminate the algorithm.

Calling with success == true cause do_algorithm() to completely return TERMINATE_TRUE and with success == false return TERMINATE_FALSE.

Preconditions:

running_state() == RUNNING (throw InvalidRunningState)

Definition at line 405 of file IterationPack_Algorithm.cpp.

EAlgoReturn IterationPack::Algorithm::do_algorithm ( poss_type step_poss = 1 )

virtual

Called by clients to begin an algorithm.

Preconditions:

this->get_track() != NULL (throw ???)
running_state() == NOT_RUNNING (throw InvalidRunningState)
1 <= step_poss && step_poss <= num_steps() (throw DoesNotExist)

This operation acts as the central hub for the algorithm. It calls the do_step(i) each i = 1,...,num_steps() and then loops around again for the major loop. If do_step(i) returns false then it goes executes the step specified by the do_step_next() operation which the step object supposivly called. If a step object returns false but does not call do_step_next() to specify a step to jump to, then this will throw an InvalidControlProtocal exception.

Before the algorithm is started, this calls track().initialize(). At the end of each iteration this calls track().output_iteration(*this) and state().next_iteration(). It then checks if state.k() - k_start >= max_iter(). If it is then the do_algorithm() immediatly terminates with a value of MAX_ITER_EXCEEDED after it passes MAX_ITER_EXCEEDED to track().output_final(). If the maxinum runtime this->max_run_time() is exceeded then MAX_RUN_TIME_EXCEEDED will be passed to track().output_final() and this function will return track().output_final(). If the algorithm throws any exception then track().output_final() will be called with the value TERMINATE_FALSE and this exception will be rethrown clean out of here.

Any step object can cause the algorithm to terminate by calling terminate(success). This operation will then immediatly return TERMINATE_TRUE if success == true and TERMINATE_FALSE if success == false.

The algorithm starts on the step specified with step_poss.

Definition at line 413 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::print_steps ( std::ostream & out ) const

virtual

Print out just a listing of the steps, their positions in the algorithm and the subclasses.

Definition at line 570 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::print_algorithm ( std::ostream & out ) const

virtual

Print out the entire algorithm by calling print_step(...) on the step objects.

Reimplemented in MoochoPack::NLPAlgo.

Definition at line 577 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::set_algo_timing ( bool algo_timing )

virtual

Causes algorithm to be timed.

Call with algo_timing == true before do_algorithm() to have the algorithm timed.

Do not call when algorithm is running.

Definition at line 589 of file IterationPack_Algorithm.cpp.

bool IterationPack::Algorithm::algo_timing ( ) const

virtual

Definition at line 594 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::print_algorithm_times ( std::ostream & out ) const

virtual

Outputs table of times for each step, cummulative times and other statistics.

Call after do_algorithm() has executed to get a table of times.

Do not call when algorithm is running.

Definition at line 598 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::get_step_times_k	(	int	offset,
		double	step_times[]
	)		const

Returns the step_times for iteration offset.

Parameters

offset	[in] The interation offset to retrieve times for.
step_times	[out] Array (size `this->num_steps() + 1`) with the output step times (in seconds) for iteration `k+offset`. The last entry `step_times[this->num_steps()]` gives the total time for the entire iteration.

Preconditions:

offset <= 0 (throw std::invalid_argument)

Note that offset must be a nonpositive number since we can only retreve timings from the current or previous iterations.

Definition at line 715 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::get_final_step_stats	(	size_t	step,
		double *	total,
		double *	average,
		double *	min,
		double *	max,
		double *	percent
	)		const

Returns the final statistics for a given step Do not call when algorithm is running.

Definition at line 738 of file IterationPack_Algorithm.cpp.

Algorithm::poss_type IterationPack::Algorithm::validate	(	poss_type	step_poss,
		int	past_end = `0`
	)		const

private

Validate a step_poss and throw a DoesNotExist exception if it does not.

Definition at line 1024 of file IterationPack_Algorithm.cpp.

Algorithm::poss_type IterationPack::Algorithm::validate	(	const assoc_steps_ele_list_t &	assoc_list,
		poss_type	assoc_step_poss,
		int	past_end = `0`
	)		const

private

Validate an assoc_step_poss and throw a DoesNotExist exception if it does not.

Definition at line 1034 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::change_running_state ( ERunningState running_state )

private

Change the running state.

Definition at line 816 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::validate_in_state ( ERunningState running_state ) const

private

Validate that this is in a specific running state.

Definition at line 839 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::validate_not_in_state ( ERunningState running_state ) const

private

Validate that this is not in a specific running state.

Definition at line 849 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::validate_not_curr_step ( poss_type step_poss ) const

private

Validate that the step_poss in not the current step.

Definition at line 858 of file IterationPack_Algorithm.cpp.

void IterationPack::Algorithm::validate_not_next_step ( const std::string & step_name ) const

private

Validate that the step_name in not the next step.

Definition at line 866 of file IterationPack_Algorithm.cpp.

Algorithm::steps_t::iterator IterationPack::Algorithm::step_itr ( const std::string & step_name )

inlineprivate

Find a step given its name and throw a DoesNotExist exception if not found.

Definition at line 990 of file IterationPack_Algorithm.hpp.

Algorithm::steps_t::const_iterator IterationPack::Algorithm::step_itr ( const std::string & step_name ) const

inlineprivate

Definition at line 997 of file IterationPack_Algorithm.hpp.

Algorithm::steps_t::iterator IterationPack::Algorithm::step_itr_and_assert ( const std::string & step_name )

private

Find a step given its name and throw a DoesNotExist exception if not found.

Definition at line 875 of file IterationPack_Algorithm.cpp.

Algorithm::steps_t::const_iterator IterationPack::Algorithm::step_itr_and_assert ( const std::string & step_name ) const

private

Definition at line 886 of file IterationPack_Algorithm.cpp.

Algorithm::assoc_steps_ele_list_t::iterator IterationPack::Algorithm::assoc_step_itr	(	assoc_steps_ele_list_t &	assoc_list,
		const std::string &	assoc_step_name
	)

inlinestaticprivate

Find a an associated step given its name and throw a DoesNotExist exception if not found.

Definition at line 1004 of file IterationPack_Algorithm.hpp.

Algorithm::assoc_steps_ele_list_t::const_iterator IterationPack::Algorithm::assoc_step_itr	(	const assoc_steps_ele_list_t &	assoc_list,
		const std::string &	assoc_step_name
	)