How to generate an index list

Table of Contents

• Introduction
• Index vector
• Index stripes
• Index section
• Index list collection
• Index modifier
• Empty index list

Introduction

Index lists are just lists that contain a number of indices. Identical indices can occur multiple times in an index list. They have no notion 2D or 3D decompostions.

However, you are still able to describe any type of decompostion using such an index list. The most general index list type is the index vector. The yaxt library provides other index list types that ease the generation of an index list for most decompostion types.

The presented examples can be found here

Index vector

Xt_idxlist xt_idxvec_new(const Xt_int *idxlist, int num_indices);

The index vector takes an array of indices as input and generates an index list from that. It is most efficient for random decompostions. Since it stores a copy of the input array within the index list, it is not recommand to be used for index list that can be described more compact with other index list types.

index vector decomposition example

    Xt_int indices[] = {0,3,32,26,44,14,48};
    int num_indices = sizeof(indices)/sizeof(indices[0]);
 
    Xt_idxlist idxvec = xt_idxvec_new(indices, num_indices);

Index stripes

xt_idxstripes_new(struct Xt_stripe const * stripes, int num_stripes);

If you have a number of indices that have identical strides, then it might be more efficient to use the index stripes to describe your decomposition.

index stripes decomposition example

    struct Xt_stripe stripes[] = {{.start = 0, .nstrides = 17, .stride = 3}};
    int num_stripes = sizeof(stripes)/sizeof(stripes[0]);
 
    Xt_idxlist idxstripes = xt_idxstripes_new(stripes, num_stripes);

Index section

Xt_idxlist xt_idxsection_new(Xt_int start, int num_dimensions,
                             const Xt_int global_size[num_dimensions],
                             const int local_size[num_dimensions],
                             const Xt_int local_start[num_dimensions]);

A very common decomposition is the partioning into n-dimensional blocks. For this decomposition type the index section is recommanded. Some advanced features of index sections are described in Features of index sections.

index section decomposition example

    Xt_int start = 0;
    int num_dimensions = 2;
    Xt_int global_size[2] = {5,10};
    int local_size[2] = {3,4};
    Xt_int local_start[2] = {2,3};
 
    Xt_idxlist idxsection
      = xt_idxsection_new(start, num_dimensions, global_size,
                          local_size, local_start);

Index list collection

xt_idxlist_collection_new(Xt_idxlist *idxlists, int num_idxlists);

Index list collections can be used to combine a number of index list of any type into a new index list.

index list collection decomposition example

    Xt_int start = 0;
    int num_dimensions = 2;
    Xt_int global_size[2] = {5,10};
    int local_size[2][2] = {{2,2},{3,4}};
    Xt_int local_start[2][2] = {{0,0},{2,6}};
 
    Xt_idxlist idxlists[]
      = {xt_idxsection_new(start, num_dimensions, global_size,
                           local_size[0], local_start[0]),
         xt_idxsection_new(start, num_dimensions, global_size,
                           local_size[1], local_start[1])};
    int num_idxlists = sizeof(idxlists) / sizeof(idxlists[0]);
 
    Xt_idxlist idxcollection
      = xt_idxlist_collection_new(idxlists, num_idxlists);

Index modifier

The index modifier can be used to generate an index list based on an existing one. In the new index list all occurences of indices listed in the first index list of the modifier are replaces by the respective indices in the second list.

Xt_idxlist xt_idxmod_new(Xt_idxlist patch_idxlist,
                         struct Xt_modifier *modifier,
                         int modifier_num, int *mstate);

index modifier decomposition example

    Xt_int start = 0;
    int num_dimensions = 2;
    Xt_int global_size[2] = {5,10};
    int local_size[2] = {3,3};
    Xt_int local_start[2] = {2,0};
 
    Xt_idxlist source_list = xt_idxsection_new(start, num_dimensions,
                                               global_size, local_size,
                                               local_start);
 
    struct Xt_stripe extract_stripes[2] = {{.start = 0, .nstrides = 5, .stride = 10},
                                           {.start = 9, .nstrides = 5, .stride = 10}};
    struct Xt_stripe substitute_stripes[2] = {{.start = 8, .nstrides = 5, .stride = 10},
                                              {.start = 1, .nstrides = 5, .stride = 10}};
    struct Xt_modifier modifier[] = {{.extract = xt_idxstripes_new(extract_stripes, 2),
                                      .subst   = xt_idxstripes_new(substitute_stripes, 2)}};
    int num_modifier = sizeof(modifier) / sizeof(modifier[0]);
 
    Xt_idxlist target_list = xt_idxmod_new(source_list, modifier, num_modifier, NULL);

Empty index list

Xt_idxlist xt_idxempty_new(void);

The empty index contains no indices. It handles the non-existing indices with good performance.

    Xt_idxlist empty_list;
 
    empty_list = xt_idxempty_new();