IterationPack::Algorithm Class Reference

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

#include <IterationPack_Algorithm.hpp>

List of all members.

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.

Public types



enum  
  More...
enum  ERunningState
  More...
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.
virtual ~Algorithm ()
 

«std comp» members for state



void set_state (const state_ptr_t &state)
 
state_ptr_tget_state ()
 
const state_ptr_tget_state () const
 
AlgorithmStatestate ()
 
const AlgorithmStatestate () const
 

«std comp» members for track



void set_track (const track_ptr_t &track)
 
track_ptr_tget_track ()
 
const track_ptr_tget_track () const
 
AlgorithmTrackertrack ()
 
const AlgorithmTrackertrack () 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_tget_step (poss_type step_poss)
 Return the RCP<...> object for the step object at step_poss.
virtual const step_ptr_tget_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_tget_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.
virtual const step_ptr_tget_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.

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 101 of file IterationPack_Algorithm.hpp.


Member Typedef Documentation

Definition at line 108 of file IterationPack_Algorithm.hpp.

Definition at line 110 of file IterationPack_Algorithm.hpp.

Definition at line 112 of file IterationPack_Algorithm.hpp.

Definition at line 114 of file IterationPack_Algorithm.hpp.


Member Enumeration Documentation

anonymous enum

Definition at line 116 of file IterationPack_Algorithm.hpp.

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

IterationPack::Algorithm::~Algorithm (  )  [virtual]

Definition at line 125 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 927 of file IterationPack_Algorithm.hpp.

Algorithm::state_ptr_t & IterationPack::Algorithm::get_state (  )  [inline]

Definition at line 931 of file IterationPack_Algorithm.hpp.

const Algorithm::state_ptr_t & IterationPack::Algorithm::get_state (  )  const [inline]

Definition at line 935 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 949 of file IterationPack_Algorithm.hpp.

Algorithm::track_ptr_t & IterationPack::Algorithm::get_track (  )  [inline]

Definition at line 953 of file IterationPack_Algorithm.hpp.

const Algorithm::track_ptr_t & IterationPack::Algorithm::get_track (  )  const [inline]

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

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

const Algorithm::step_ptr_t & IterationPack::Algorithm::get_step ( poss_type  step_poss  )  const [virtual]

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

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:

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 RCP<...> object for the associated step object at step_poss and assoc_step_poss.

Preconditions:

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

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

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:

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

Postconditions:

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:

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:

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:

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

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:

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


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Friends
Generated on Wed Apr 13 10:09:06 2011 for IterationPack: General framework for building iterative algorithms by  doxygen 1.6.3