IterationPack: General framework for building iterative algorithms : IterationPack::Algorithm Class Reference

List of all members.


Public types
typedef Teuchos::RefCountPtr< AlgorithmState >	state_ptr_t

typedef Teuchos::RefCountPtr< AlgorithmTracker >	track_ptr_t

typedef Teuchos::RefCountPtr< AlgorithmStep >	step_ptr_t

typedef size_t	poss_type

enum
	More...
enum	ERunningState
	More...
Constructors & destructors
	Algorithm ()
	Constructs an algorithm with no steps and a default of max_iter() == 100.
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.
virtual double	max_run_time () const

Step information & access
virtual int	num_steps () const
	Return the number of main steps.
virtual poss_type	get_step_poss (const std::string &step_name) const
	Return the possition in the major loop of a named step.
virtual const std::string &	get_step_name (poss_type step_poss) const
	Return the name of a step given its possition.
virtual step_ptr_t &	get_step (poss_type step_poss)
	Return the RefCountPtr<...> object for the step object at step_poss.
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.
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.
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.
virtual step_ptr_t &	get_assoc_step (poss_type step_poss, EAssocStepType type, poss_type assoc_step_poss)
	Return the RefCountPtr<...> object for the associated step object at step_poss and assoc_step_poss.
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`.
virtual void	change_step_name (poss_type step_poss, const std::string &new_name)
	Change the name of an existing step.
virtual void	replace_step (poss_type step_poss, const step_ptr_t &step)
	Replace the step object of an existing step.
virtual void	remove_step (poss_type step_poss)
	Remove an existing step object and all of its pre and post steps.
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.
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.
Runtime configuration updating control
ERunningState	running_state () const
	Return the current running state of `this` algorithm object.
virtual void	begin_config_update ()
	Changes from running_state() == RUNNING to running_state() == RUNNING_BEING_CONFIGURED.
virtual void	end_config_update ()
	Changes from running_state() == RUNNING_BEING_CONFIGURED to running_state() == RUNNING.
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.
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.
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.
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.
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`.
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`.
virtual void	terminate (bool success)
	Called by step objects to terminate the algorithm.
Start iterations
virtual EAlgoReturn	do_algorithm (poss_type step_poss=1)
	Called by clients to begin an algorithm.
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.
virtual void	print_algorithm (std::ostream &out) const
	Print out the entire algorithm by calling `print_step(...)` on the step objects.
Algorithm Timing
virtual void	set_algo_timing (bool algo_timing)
	Causes algorithm to be timed.
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.
void	get_step_times_k (int offset, double step_times[]) const
	Returns the step_times for iteration offset.
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.
Public Member Functions
void	interrupt_file_name (const std::string &interrupt_file_name)
	Name of an file that will cause the algorithm to terminate.

Detailed Description

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.

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

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

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

IterationPack::Algorithm::Algorithm

(

)

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

Definition at line 91 of file IterationPack_Algorithm.cpp.

Member Function Documentation

void IterationPack::Algorithm::interrupt_file_name ( const std::string & interrupt_file_name ) [inline]

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.

Definition at line 193 of file IterationPack_Algorithm.hpp.

void IterationPack::Algorithm::max_iter ( size_t max_iter ) [virtual]

Definition at line 130 of file IterationPack_Algorithm.cpp.

size_t IterationPack::Algorithm::max_iter ( ) const [virtual]

Definition at line 133 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 138 of file IterationPack_Algorithm.cpp.

double IterationPack::Algorithm::max_run_time ( ) const [virtual]

Definition at line 141 of file IterationPack_Algorithm.cpp.

int IterationPack::Algorithm::num_steps ( ) const [virtual]

Return the number of main steps.

Definition at line 147 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 150 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 156 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 167 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 170 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 179 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 RefCountPtr<...> 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 189 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 211 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 236 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 253 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 272 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 304 of file IterationPack_Algorithm.cpp.

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 318 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 326 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 350 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 359 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 368 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 380 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 386 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 392 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 400 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 557 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.

Definition at line 564 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 576 of file IterationPack_Algorithm.cpp.

bool IterationPack::Algorithm::algo_timing ( ) const [virtual]

Definition at line 581 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 585 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 702 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 725 of file IterationPack_Algorithm.cpp.

IterationPack::Algorithm Class Reference

Public types

Constructors & destructors

«std comp» members for state

«std comp» members for track

Maximum iterations

Maximum runtime (in minutes)

Step information & access

Pre/post step information & access

Step manipulation

Pre/post step manipulation

Runtime configuration updating control

Algorithmic control

Start iterations

Algorithm information output

Algorithm Timing

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation