Proposal for formalising the use of CactusEinstein/SpaceMask
------------------------------------------------------------

(Denis Pollney pollney@aei.mpg.de, 9 Oct 2002)

The Spacemask thorn, and the associated spacemask::emask grid function
were created to provide a grid function whose value could be used to
classify points on the grid. The following text outlines a proposal
for formalising the use of the mask as a collection of bits which can
be set to represent given states. Possible states are registered at
program initialisation. Mask states are set and checked using
functions provided by the SpaceMask thorn.


* Current use of SpaceMask:

The spacemask::emask is currently only used by various
excision-related thorns at the AEI. In particular, once the
CactusEinstein/AHFinder determines a region to excise based on the
apparent horizon location, it sets the mask to
  1.0 at regular grid points
  0.0 at points which are to be excised
The Excision/LegoExcision thorn can also set the emask to
  0.5 at boundary points of the excised region

(The AEIDevelopment/MaskIso thorn can be used in place of the AHFinder
to set the mask according to the same convention.)


* Requirements of the mask:

Though this convention is in place for historical reasons, the
specific usage of values of emask has not been fixed in any global
way. It would be desirable if there was a mechanism for thorn
developers to use the mask to classify grid points according to their
needs. One can imagine defining different boundary conditions on
different faces of the grid, or on regions located within the grid,
based on mask values. Regions of the grid requiring different
evolution equations (eg. interior vs exterior of stars) or difference
techniques could be identified using the mask. Etc.

This could be accomplished using seperate masks for each type of
classification, though it would by quite inefficient (currently, emask
is a CCTK_REAL which keeps track of only three possible
states). Better would be to develop a method to pack more information
into a single global mask, which was the original intention behind the
creation of the CactusEinstein/SpaceMask thorn and spacemask::emask
grid function.

This will require a mechanism which allows individual thorns to set
and evaluate values of the mask without interfering with values set by
other thorns. Similarly, there needs to be methods for reading mask
information at a point unambiguously and quickly.


* Proposed mechanism:

The basic mechanism could be to register certain bits in the emask
value to represent individual states, and provide routines for setting
and checking these states.

For instance, if the emask were 8 bits long (00000000), then the first
two bits (xx000000) could be registered as bits corresponding to
excision at startup, and the three particular excision states
registered as 00000000=normal, 01000000=boundary, and
10000000=excised. Later in the code, routines needing to determine the
excision state of a point would check the value of the appropriate
excision bits of the mask.


The following functions would do the job:

int SpaceMask_RegisterType (char* type_name, int nstates, **state_list)
  - type_name: a string identifying the type, eg. "excision"
  - nstates: the number of states needed for the given type
  - state_list: a list of states for the given type, eg.
      {"normal", "boundary", "excised"}
    This function will set aside the number of bits of emask required
    to hold the required number of states.
  Returns an error flag.

int SpaceMask_SetState (int* mask, int ijk, char* type_name, char* state,
                        int point)
  - mask: pointer to the mask data
  - ijk: the particular index of mask to be set
  - type_name: the identifier of the type to set, eg. "excision"
  - state: the state to set, eg. "excised"
  - point: the point on the grid to be set, eg. ijk
  Returns an error flag.

int SpaceMask_CheckState (int* mask, int ijk, char* type_name, char* state,
                          int npoint)
  (as above)
  Returns TRUE if npoint is set to the specified state


* Example:

At some point in startup, the excision thorn would claim some bits
in emask using a function such as:

void Excise_SetupMask(void)
  {
    char* excision_states[3] = {"standard", "boundary", "excised"};
    int ierr;

    ierr = SpaceMask_RegisterType("excision", 3, excision_states);

    if (ierr<0) CCTK_WARN(0, "Couldn't allocate excision mask!")
  }


The mask could later be set by the horizon finder (or whatever) using:

  ...
  for (ijk=0; ijk<npoints; ++ijk)
    {
      if (is_inside_horizon(ijk)) 
        SpaceMask_SetState("excision", "excised", ijk);
      else if (is_excision_boundary(ijk))
        SpaceMask_SetState("excision", "boundary", ijk);
      else
        SpaceMask_SetState("excision", "standard", ijk);
    }
  ...


* More efficient alternative Set/Check functions:

It will be important to be able to perform mask state checks quickly.
To avoid string comparisons, etc., within the iteration loop,
functions which perform direct bitwise operations on the mask can be
defined. First, the bit-fields corresponding to registered
types/states are obtained using the following functions:

int type_bits = SpaceMask_GetTypeBits (char* type_name)
  - type_name: the name of the type, eg. "excision"
  Returns a bit mask, with 1's set on the active bits for the given
  type.
  Eg. if the first two bits of emask are allocated for "excision"
  then this would return 11000000

int state_bits = SpaceMask_GetStateBits (char* type_name, char* state)
  - type_name: the name of the type, eg. "excision"
  - state: the particular state to be checked/set, eg. "excised"
  Returns a bit mask corresponding to the given state.
  Eg. in the example above, 00000000 for "normal", 01000000 for "boundary",
  and 10000000 for "excised"

[The above prototypes assume the mask is an int, and the examples only
list 8-bits.]

The corresponding Set/Check functions are:

int SpaceMask_SetStateBits (int* mask, int ijk, int type_bits, 
                            int state_bits)
  Performs the operation:
    mask[ijk] = (mask[ijk] & !type_bits) | state_bits
  Returns an error code.

int SpaceMask_CheckStateBits (int* mask, int ijk, int type_bits,
                              int state_bits)
  Returns the result of:
    (mask[ijk] & type_bits) == state_bits


* Example:

To set the mask using the bitwise functions, the following code would do:

  { 
    int MASK_EXCISE, MASK_EXCISE_STD;

    MASK_EXCISE = SpaceMask_GetTypeBits ("excision");
    MASK_EXCISE_STD = SpaceMask_GetStateBits ("excision", "standard");

    for (ijk=0; ijk<npoints; ++ijk)
      SpaceMask_SetStateBits (MASK_EXCISE, MASK_EXCISE_STD, ijk);
  }


* Other points:

- Currently the mask is a CCTK_REAL. This is partly for a technical reason:
  the grid symmetries in CactusEinstein/CartGrid3D can only handle real-valued
  GFs. In principle, if emask is eventually used as simply a bit-field as
  proposed, then we'll likely need to switch it to a CCTK_INT8.

- It might be desirable to allow thorn writers to add states to a given
  type. So if a type "point_type" has states "a", "b", "c" by default,
  then another thorn might like to add the state "d" to the same type.
  Unfortunately, since the thorn which registered "point_type" also
  had to allocate a certain number of bits for it, there might not be
  room for the extra state.
  In principle there could be a
    SpaceMask_AppendStatesToType (char* type_name, int nstates, 
                                  char** state_list)
  function which would check for this and dynamically add extra bits to
  "point_type" if needed and the bits are available.