path: root/doc/MigrationGuide.txt

        EINSTEIN THORN-CONVERSION USERS GUIDE



This guide is structured in four parts: 

1) changes in the FORTRAN/C source files
2) the new parameter system
3) the new RFR interface
4) the new GridFuncList



________________________________________________________________________

1)     CHANGES IN THE FORTRAN/C SOURCE FILES

This part should be quite straight forward for most thorns (those not
using special macros or data structures)

You have to do the following:

- move "cactus.h" to "cctk.h", so put
     #include "cctk.h"

- to include parameters, use 
     #include "cctk_Parameters.h"

- to declare arguments, use
     #include "cctk_Arguments.h"

- C programmers now need to declare their own standard libraries

- the macro argument CACTUS or any particular one, like 
  BONAMASSO_EVOLUTION_ARGS has to be replaced by CCTK_ARGUMENTS,
  in case of fortran routine and by CCTK_ARGUMENTS in case of
  C routine.
  In order to declare it, use DECLARE_CCTK_ARGUMENTS (fortran case)
  or DECLARE_CCTK_ARGUMENTS (C case)

- replace DECLARE_PARSER with DECLARE_CCTK_PARAMETERS. 
  
- Fortran programmers should declare 
     DECLARE_CCTK_FUNCTIONS 

  wherever you need to read parameters or call flesh functions.  For
  comparing string-valued parameters you should use CCTK_Equals. Note
  that since CCTK_Equals returns an INTEGER, you cannot say

  if (CCTK_Equals(mypar,"thispar")) then

  you must say 

  if (CCTK_Equ(mypar,"thispar").eq.1) then

  (some compilers will not insist on this). To make this easier,
  there is a macro CCTK_EQUALS which you can use as a logical

  if (CCTK_EQUALS(mypar,"thispar")) then

  (Unfortunately this means that some compilers will complain
  if you declare "integer CCTK_EQUALS" instead of the correct
  "integer CCTK_Equals")
 
- the MACROS CONFORMAL_METRIC, NON_CONFORMAL_METRIC, SHIFT_ACTIVE,
  SHIFT_INACTIVE no longer exist.  Please see the documentation for
  CactusEinstein/ADMBase and CactusEinstein/StaticConformal for  
  the new usage.

- the extrinsic curvature has changed name from hxx etc to kxx etc.

- the Bona Masso variables should not be assumed to be available anymore.

- the point macros, say CACTUS_POINT, BONAMASSO_EVOLUTION_POINT, are no
  longer available. If you need them you have to manage it yourself. As
  long as I know, we (Palma group) were the only ones using it.

- FLESHPARS is also gone 

- contains has been replaced by CCTK_Equals, which is used like this:
                 if (CCTK_Equals(model,"flatty").eq.1) then
  1 stands for TRUE, of course.
  Equals has a different meaning than contains. Equals means exactly
  that (but is case independent), so you can no longer have different 
  words separate by blank spaces in the parameter files. 
  As a consequence any multi-purpose parameter has to be broken into
  a set of them. You might have to think carefully about how to rewrite
  the part of the code dealing with this. This can be the more tiresome
  part, depending on the thorn [Note by Cactus Maint: but the benefits 
  will become apparent].

- nx,ny,nz has died, changed to the more general cctk_lsh(DIM), so do 

      nx = cctk_lsh(1)
      ny = cctk_lsh(2)
      nz = cctk_lsh(3)
  if you are so lazy...

  and dt to cctk_delta_time, dx,dy,dz to cctk_delta_space(DIM)

  so in fortran:
      dt = cctk_delta_time
      dx = cctk_delta_space(1)
      dy = cctk_delta_space(2)
      dz = cctk_delta_space(3)

  or in C:
      dt = cctk_delta_time
      dx = cctk_delta_space(0)
      dy = cctk_delta_space(1)
      dz = cctk_delta_space(2)

  is enough again
   
- in make.code.defn you have to specify all your files in a single SRCS line,
  both fortran and C ones, e.g.

 SRCS = choosefluxes.F fluxes.F \
        source_addPN.F source_addY.F source_shift.F sources.F \
        BonaMasso_Evolution.F BM_ini_flat.F\
        vectorini_point.F enfmom.F\
        evolsources.F macflux.F machog.F 

- all file names must be unique

_________________________________________________________________________


2) THE NEW PARAMETER SYSTEM

The former parameter definition file no longer exists.
Now you have "param.ccl", a ccl file (see below), to make up for it.

The vocabulary includes:

  > shares:thorn_which_I_share_a_parameter_from

      this allows you to access restructed parameters from other thorns,e.g.

      friend:admcoupling

  > restricted:
    whatever parameter definition following can just be used by other thorns

  > private:
    whatever parameter definition following can just be used by this very
    thorn. No one else.

  > global:
    whatever parameter definition following can be used by any thorn.
    [Note by Cactus Maint: in general, you shouldn't need any public 
    parameters]

After this statements you define parameters by

PARAMETER_TYPE parameter_name "Meaningful comment"
{
 range :: "Comment for range"
} default_value

: as range means any value


Examples:

INTEGER nholes "number of black holes"
{
 1:4 :: "Only coded up to 4 black holes"
} 1

INTEGER ADM_ICN_itnum_min "minimum number of iterations of ICN"
{
 1: :: ""
} 1

REAL bm_f "f factor on lapse"
{
 : :: ""
} 2.0

BOOLEAN evolve_metric "Choose whether to evolve the metric"
{
} "yes"

KEYWORD system_type "Which one of the BMA systems?"
{
   "linear"    :: "Linearized Einstein equantions"
   "ricci      :: "Ricci system"
   "einstein " :: "Einstein system"
} "einstein"

[Note from Cactus Maint: Try and fill in the ranges for your parameters,
since these are checked for each parameter file]

Notice that strings are now keywords. In the parameters file their 
value can just be adjusted to one of the allowed values. Otherwise
you will be warned you have been bad.

You can extend the range of the parameters belonging to a thorn
which you share parameters from. Example:

shares:admbase

EXTEND KEYWORD evolution_method ""
{
   "BMA" :: "Evolve using BMA evolution scheme"
}

Of course all this does not come without modification in the parameter
files. First, because of multiple-purpose parameters are now 
forbidden, as pointed above in the CCTK_Equals comment. And second,
your parameters have name and surnames. You can have in principle
the same private parameters in different thorns with different 
purposes, and they shouldn't conflict with each other.
For instance,

admbase::evolution_method        =    "ADM"    

The old flesh parameters now belong to some implementation or another, like
driver::global_nx

or have cctk status:

cctk_initial_time  =     0.  
cctk_itlast        =     100

etc.
 
_________________________________________________________________________

3) THE NEW SCHEDULE INTERFACE

The RFR interface between thorns and flesh has been replaced by a
scheduling interface.  The data is no longer in a C/FORTRAN file,
but in a ccl file ("schedule.ccl") and includes storage and communication 
information for the variables (in Cactus 3 this was in the GridFuncList).

The vocabulary is 

STORAGE:  somethingtostore

Example:______________________________

if (CCTK_Equals(evolution_system,"BMA"))
{

########### what to store #######################################
  STORAGE: alpha_derivatives,metric_derivatives,vees,traces

  # shift treatment
  if (!CCTK_Equals(shift,"none")) 
  {
    STORAGE: shift_deriv
  }

  .... 
}

End of Example________________________

For the meaning of alpha_derivatives,metric_derivatives,... see the last
example in next section 4). Basically they are groups of variables dealt
together.

To schedule routines the language is as follows:

  schedule YourRoutine at ScheduleTime
  {
    LANG: Language
  } "RFR comment"

For instance:

  schedule BonaMasso_evolution at CCTK_EVOL
  {
    LANG: Fortran
  } "Evolve with BMA system"

Instead of calling Sync, you should now declare that a group of
variables should be synced at the end of a routine, e.g.

  schedule BonaMasso_evolution at CCTK_EVOL
  {
    LANG: Fortran
    SYNC: bm_vars
  } "Evolve with BMA system"


See the manual for a complete list of Schedule times.

As you can see the cactus language ccl is heavily inspired in C. You
can use equals ==, or ||, else if,... For those ignorant of C, check
the different *.ccl files in different thorns. It's quite
self-explaining.


__________________________________________________________________

4) THE NEW GRIDFUNCLIST

The Cactus 3  GridFuncList is now replaced by "interface.ccl", with
a brand new vocabulary. You have to rewrite from scratch.
As seen above, some information for variables at old GridFuncList files are 
now to be specified in "schedule.ccl" 

*new vocabulary:

   > implements
         for instance,   

         implements:bm

         it means that this file implements a set of arguments,
         called bm in this case. This are the arguments passed
         to your routines in the thorn. Several thorns can use the
         same name. This is crucial for dealing with 
         conflicts and redundancies between thorns.

    > inherits
         for instance, 

         inherits: admbase

         the arguments passed to the routines of this thorn will
         include "public" stuff of admbase implementation in
         einsteins's interface.ccl.

    > protected

         protected:    herewhatyouwanttoprotect

         what follows is just passed to thorns which explicitly 
         request it

    > private

         private:     herewhatisdarkandhidden

         what follows is never passed to any other thorn

    > public

         public :     herewhatistobesharedwithanythorn

         what follows is always visible; don't place anything you don't 
         want to be modified here.


* the way to state variables is now (example)

      real metric type = GF
      {
        gxx,gxy,gxz,gyy,gyz,gzz
      } "Some kind of comment"

   "real"  is the type, so integer,...
   "type =" specifies GF (GridFunction) in this case; can also be
            SCALAR,...

   As you can see, the variables can be now packed in groups, so they
   are easily passed and assigned storage and communications features
   coherently.

   This example, therefore, shows how to create a set of
   6 3D double precision variables

_________________________________________________________________________



                        EPILOG

Ok, have you carefully followed all the steps? Right. Now try to compile
(gmake nameofnewconfiguration). You can have different configurations,
even on the same architecture.
Doesn't work, does it?
You may try to reboot the origin at this point. It should help. If it
doesn't, you have a bug! (or Cactus 4 has it)

After two hours of debugging the code compiles and links, so you 
think you are done. Wrong. Remember you still have to rewrite all your
parameter files...

Enjoy!