Release Notes: Keep Version 1.4
------------------------------------------
Contents
1.0 Introduction
2.0 KeLP1.3 to KeLP1.4 code conversion and interoperability
3.0 Known bugs and problems
-----------------------------------------

1.0		Introduction
	KeLP v.1.4 (Abstract KeLP) represents a paradigm shift from earlier
versions of KeLP.  Users who do not need the new capabilities are welcome
to continue using KeLP v1.3, which we will continue to support for the 
forseable future.  These notes are for users who wish to make legacy KeLP 
applications conform to the KeLP v.1.4 specification

	Although we have tried to minimize the impact of introducing the
Patch abstraction and class DataFactory on legacy applications we have not
been able to avoid it altogether.  The following section details changes 
which may need to be made to legacy applications in order for them to work
properly under KeLP v1.4.


2.0	KeLP2.3 to KeLP2.4 code conversion and interoperability
 
2.1 for_all decprecated.
	The "for_all" macro for parlallel iteration is no longer supported.
nodeIterator supersedes the for_all macro used for the same purpose in the
previous versions of KeLP.  Users must replace 

   for_all (I,X)
      do something with X(i)
   end_for_all

with
   for (nodeIterator iter(X); iter; ++iter) {
      int i = iter();	   // current index	
      do something with X(i)
   }


2.2   Mover template parameters changed
	Classes Mover and VectorMover were previously templated on both the 
data holder class and the data type held, e.g. 

MoverX< GridX< double>, double >.

   The greater flexibility required by Abstract KeLP has lead us to delete
the second template parameter, so the previous example would become

MoverX< GridX< double> >	

    User declarations of Mover and VectorMover objects must be changed to be 
consistent with these new definitions.


	A PERL SCRIPT WHICH HANDLES THE ABOVE TWO CHANGES AUTOMATICALLY IS
INCLUDED IN THIS RELEASE.  
	Simply run the script KeLP3to4.pl in your top level application 
directory.  It will work its way recursively through all the .C and .h files in
your directory structure, replacing any for_all loops with nodeIterator loops 
and changing Mover delarations to the new format.
	
	Caveats:  
	a) If you have derived your own Mover and named it anything but
	   ______Mover?  the script won't find it.  E.g
		myMover3< GridX< double>, double >
		will be found and fixed,
		MoverMine3< GridX< double>, double >
		will be missed and the user must make the required changes
		by hand.

	b) The script will not find macro expansion file and user script
	   files.


2.3	Grid ownership eliminated and XArray indexing changed

	The Patch abstraction has required decoupling
the local data container (Grid) from global information about its owning
processor.  Class Grid no longer has an XObject as a data member.  The
access functions owner() and local_object() have been deprecated.  
Code which depends on these functions must be rewritten!

	Ownership information can still be obtained by reference to the XArray
member function.

int j = Xgrid(i).owner(); //ERROR. Calls a nonexistent Grid member 
//   function
int j = Xgrid.owner(i); //OK. Calls a XArray member function.

	a) Discussion

	In earlier versions of KeLP, each XArray element contained metadata 
for the full global array of Grids.  Each processor then allocated storage 
for only those Grids which it "owned".  Thus it was possible to refer to an
arbitrary Grid by indexing into the XArray.  This essentially duplicated
the full metadata already contained in the FloorPlan member.  

The following code would have been permitted

XArray2<Grid2<double> > Xgrid 
for(int i = 0; i < NGRIDS; i++)
{
	if(Xgrid(i).local_object()  // is this Grid on this processor?
	{ 
	    //do something to Xgrid(i)
	    }
}

	In Abstract KeLP this has been modified.  The data member of each 
XArray element is now an array of only those Grids which "live" on the local
processor.  A KeLP Iterator must be used to iterate over the Grids in an
XArray.

for (nodeIterator ni(Xgrid); ni; ++ni) {
     i = ni();
     // //do something to Xgrid(i)
}


2.4		Name Change to Grid Buffer Packing Functions
	
	The names of the following member functions of class GridX have been 
changed to be consistent with the Patch specification

CopyRegion   --> Copy
PackRegion   --> SerializeOut
UnpackRegion --> SerializeIn

	User code which calls these functions must be changed accordingly.  
Typically this would only occur if you have written your own Mover or 
derived a class from Grid.

2.5		"alloc" deleted as XArray argument.

	The XArray constructor and instantiate function formerly took a flag 
which told it whether or not to allocate storage in its Grid members.  This 
is no longer supported.

KeLP1.3	   XArrayX(const FloorPlanX &D, const int alloc = TRUE);
KelP1.4    XArrayX(const FloorPlanX &D, const Region1 comps = Region1(1,1),
      const DataFactoryX<UserPatch>& factory = DataFactoryX<UserPatch> ())

	For a detailed example of how to create an XArray of empty Grids, 
see the KeLP Reference Manual, section 2.6.

2.6	Application code need to #include "Grid.h"
------------------------------------------------------------------------------




3.0 Known bugs and problems
	We are aware of the following problems in the current KeLP release.  
Fixes will be made available as soon as possible.

3.1 dGrid single argument constructor doesn't work
	Objects declared using the constructor
   dGrid3(const Decomposition3& D, const int alloc=TRUE): 
        XArray3<GridBlock3<T> >(D,alloc), _decomp(D)  {}
 fail, e.g.
   dGrid3<complex > V(Dt);
   dGrid3<complex > W(Dt);
   dGrid3<double> eTerms(Dt);
 won't work properly.

  Instead, declare empty dGrids...
   dGrid3<complex > V,W;
   dGrid3<double> eTerms;

 ...and use the instantiate() member function.
   V.instantiate(Dt);
   W.instantiate(Dt);
   eTerms.instantiate(Dt);

3.3  Example application won't run on Cray T3E.
  
	The sample applications supplied with the KeLP package run correctly on
all supported platforms (IBM SP2, SP3, Sun Solaris, Linux, Cray T3E) with one
exception:

	On the Cray T3E, the NAS-MG benchmark exits prematurely without error 
message but dumping a core file.