IterationPack: General framework for building iterative algorithms  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Classes | Public Member Functions | List of all members
IterationPack::Algorithm Class Reference

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

#include <IterationPack_Algorithm.hpp>

Classes

class  AlgorithmInterrupted
 Thrown if Algorithm was interrupted by the user. More...
 
class  AlreadyExists
 Thrown if name already exists. More...
 
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...
 

Public Member Functions

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

Public types

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

Member Enumeration Documentation

anonymous enum

Definition at line 129 of file IterationPack_Algorithm.hpp.

enum IterationPack::Algorithm::ERunningState

Definition at line 131 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

Postconditions:

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:

Postconditions:

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:

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:

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:

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:

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:

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:

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:

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

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.

The documentation for this class was generated from the following files:
Generated on Wed Dec 2 2015 08:49:41 for IterationPack: General framework for building iterative algorithms by   doxygen 1.8.6