Termination Conditions
----------------------

Author: Tom Goodale
Date: February 2001
Status: updated specification witha cancelling 

What
----

Mechanism for deciding at each timestep whether to terminate Cactus.


Why
---

We want to be able to terminate Cactus cleanly for a variety of reasons ...

  - to trap signals sent to indicate e.g. termination of batch queue time
  - want to run for a specified CPU time or wallclock time 
  - violation of a contract 
  - a thorn has decided there is no point carrying on
  - a general expression has returned true 
  - a user has interactively requested the simulation to stop.


Implementation
--------------

Flesh has a function

int CCTK_TerminationReached(cGH *)

which is called by the evolution loop before starting an iteration.  This
returns true (1) if code should terminate, or false (0) otherwise.

There are (at least) three ways to signal that this routine should return
true.

1)
void CCTK_TerminateNext(void)

which flags an unconditional true return from CCTK_TerminationReached.

2) 
int CCTK_TerminationFunction(int (*)(cGH *, void *), void *)

which registers a function to be called from CCTK_TerminationReached, and
some data to be passed to it.  This registered function takes the cGH, and
also a data pointer, which is registered at the same time as the function.

The registered function should return true or false as per 
CCTK_TerminationReached.

The return code of the registration function should be a handle which can be used
to remove the registered function from the termination list.

3)
int CCTK_TerminationCondition(const char *)

This registers an expression suitable for the expression parser;  when the
expression evaluates to true, CCTK_TerminationReached returns true.

The expression parser would need to be moved into the flesh.

Eventually it should be made capable of doing reductions/interpolations on
grid variables, or to extract data at specific poinys, for the full use of
this to be made.  However that can wait until 4.1.

The return code of the registration function should be a handle which can be used
to remove the registered expression from the termination list.


To remove a function or expression from the list of conditions to be tested, we
also have

int CCTK_TerminationRemove(int)

which takes the handle returned by CCTK_TerminationFunction or CCTK_TerminationCondition.