TimeLevels
----------

Author: Gabrielle Allen
Date: March 2001
Status: Imminently to be implemented

What
----

* We have timelevels in Cactus because of supporting AMR

* They are a real pain.

* People should only be changing the "next" timelevel,
  all other timelevels should be read-only, but we can't enforce this.

* We don't want to have to introduce timelevel arguments to all APIs
  Most Cactus APIs will assume they are being called for the current
  timelevel (but it looks like we will have to do this for CCTK_Interp,
  CCTK_Reduce, CCTK_Output, Elliptic solvers?

* What to do with initial data where you need to fill in all the previous
  timesteps as well? Keep rotating?

Current Implementation
----------------------

If you have the variable phi defined in the interface.ccl with 4 timelevels
you get

phi_n, phi, phi_p, phi_p_p

when the timelevels rotate the process is (driver dependent?)

phi_p_p = phi_p
phi_p   = phi
phi     = phi_n
phi_n is undefined

*** NOTE THAT AFTER THE TIMELEVELS ARE ROTATED phi_n SHOULD BE CONSIDERED
*** UNDEFINED ... since the driver should have the choice of how to 
*** implement timelevels for optimisation, convenience etc 

At the moment, we have the following situation

------------------------------------------
i -> i+1
PRESTEP
EVOL (fill out phi_n)

t -> t+dt	(you may think this is a bizarre place to update 
                 the time but it got put there so people can do 
                 their own output in POSTSTEP and get the right 
		 time ... but this should move to after POSTSTEP)

POSTSTEP

ROTATE (phi_n becomes undefined, phi is now "read-only")

ANALYSIS -> OUTPUT   (now this is problem is analysis used multiple
	              timelevels)
------------------------------------------

New Implementation
------------------

1. Renaming: 

   We are going to rename the variables so that e.g.

   phi is always the "next" timelevel

   phi_p, phi_p_p etc will be past timelevels

2. Calling structure

   initial
   poststep
   analysis

   loop:
     rotate
     t=t+dt
     it=it+1
     prestep 
     evolve
     poststep
     analysis

3. As a ***second step*** we will renumber the timelevels, currently
   if you have 3 timelevels, then 

   current	new
   timelevel    timelevel    old      new
   index        index        name     name

   2            0            phi_n    phi
   1		1            phi      phi_p
   0            2            phi_p    phi_p_p

   which will make things easier since timelevel 0 will always be the
   one you should work with.