From b3f5ff1ed0ba67f6c72c2f11986fbd8146a2a7f3 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Wed, 13 Dec 2023 12:14:36 -0800 Subject: [PATCH 1/8] added documentation for IndexLayout --- docs/sphinx/user_guide/feature/view.rst | 49 +++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index f4499207dd..d2e166657e 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -330,6 +330,55 @@ indices by :math:`N`, :: } } +Index Layout +^^^^^^^^^^^^^ +``RAJA::IndexLayout`` is a layout that uses an index list to access entries of a +view. This layout requires an indexing strategy for each dimension, which +determines how to map a given input index to an entry within a view. + +Three indexing strategies are natively supported in RAJA: +DirectIndex, IndexList, and ConditionalIndexList. DirectIndex maps an input +index to itself, and does not take any arguments as its constructor. The +IndexList strategy takes a reference to an array containing the list of relevant +indices to map. With this strategy, a given input index is mapped to the entry +in its list corresponding to that index. Lastly, the ConditionalIndexStrategy +takes a reference to an array containing an index list. When the referenced index +list is non-null, the ConditionalIndex strategy is equivalent to that +of the IndexList. Otherwise, if the index list provided to the constructor is a +null pointer, the ConditionalIndexList maps an input index to itself (same as +the DirectIndex strategy). The ConditionalIndexList strategy is useful if the +index list can potentially be unused for some situations. + +A simple illustrative example is shown below:: + + int data[2][3]; + + for (int i = 0; i < 2; i ++ ) { + for (int j = 0; j < 3; j ++ ) { + // fill data[i][j]... + } + } + + int index_list[2] = {1,2}; + + auto index_tuple = camp::tuple, RAJA::IndexList<>>( + RAJA::DirectIndex<>(), RAJA::IndexList<>{&index_list[0]}); + + auto index_layout = RAJA::make_index_layout(index_tuple, 2, 3); + auto view = RAJA::make_index_view(&data[0][0], index_layout); + +In the above example, a two-dimensional index layout is created with extents 2 +and 3 for the first and second dimension (respectively). a DirectIndex strategy +is implemented for the first dimension and an index list with the entries {1,2} +is used for the second dimension. With this layout, the view created in the +last line above will determine the entry along the first dimension based on the +first input index provided, and the second provided index will be mapped to +that corresponding entry of the index_list for the second dimension. For +Example, the value stored in view(1,0) will correspond to the value in +data[1][0]. In this case, the DirectIndex strategy maps the first argument in +the call to view(1,0) to that same value, and the IndexList maps the second +argument to the first index in the index_list. + ------------------- RAJA Index Mapping ------------------- From b29edf620c0a0bb7303d4c2fe34eccd387948d87 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Wed, 20 Dec 2023 13:40:31 -0800 Subject: [PATCH 2/8] made corrections to documentation and small typo fix in comments of IndexLayout unit test --- docs/sphinx/user_guide/feature/view.rst | 43 ++++++++++++---------- test/unit/view-layout/test-indexlayout.cpp | 4 +- 2 files changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index d2e166657e..ad06859fd1 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -331,23 +331,23 @@ indices by :math:`N`, :: } Index Layout -^^^^^^^^^^^^^ -``RAJA::IndexLayout`` is a layout that uses an index list to access entries of a -view. This layout requires an indexing strategy for each dimension, which -determines how to map a given input index to an entry within a view. +^^^^^^^^^^^^ + +``RAJA::IndexLayout`` is a layout that uses an indexing strategy for each +dimension to determine how to map a given input index to an entry within a view. Three indexing strategies are natively supported in RAJA: DirectIndex, IndexList, and ConditionalIndexList. DirectIndex maps an input -index to itself, and does not take any arguments as its constructor. The +index to itself, and does not take any arguments in its constructor. The IndexList strategy takes a reference to an array containing the list of relevant indices to map. With this strategy, a given input index is mapped to the entry in its list corresponding to that index. Lastly, the ConditionalIndexStrategy -takes a reference to an array containing an index list. When the referenced index -list is non-null, the ConditionalIndex strategy is equivalent to that +takes a reference to an array containing an index list. When the referenced +index list is non-null, the ConditionalIndex strategy is equivalent to that of the IndexList. Otherwise, if the index list provided to the constructor is a null pointer, the ConditionalIndexList maps an input index to itself (same as -the DirectIndex strategy). The ConditionalIndexList strategy is useful if the -index list can potentially be unused for some situations. +the DirectIndex strategy). The ConditionalIndexList strategy is useful when the +index list is not initialized for some situations. A simple illustrative example is shown below:: @@ -361,23 +361,28 @@ A simple illustrative example is shown below:: int index_list[2] = {1,2}; - auto index_tuple = camp::tuple, RAJA::IndexList<>>( + auto index_tuple = RAJA::tuple, RAJA::IndexList<>>( RAJA::DirectIndex<>(), RAJA::IndexList<>{&index_list[0]}); auto index_layout = RAJA::make_index_layout(index_tuple, 2, 3); auto view = RAJA::make_index_view(&data[0][0], index_layout); + int val0 = view(1,0); // val0 is entry in data[1][1] + int val1 = view(1,1); // val1 is entry in data[1][2] + In the above example, a two-dimensional index layout is created with extents 2 -and 3 for the first and second dimension (respectively). a DirectIndex strategy +and 3 for the first and second dimension, respectively. A DirectIndex strategy is implemented for the first dimension and an index list with the entries {1,2} -is used for the second dimension. With this layout, the view created in the -last line above will determine the entry along the first dimension based on the -first input index provided, and the second provided index will be mapped to -that corresponding entry of the index_list for the second dimension. For -Example, the value stored in view(1,0) will correspond to the value in -data[1][0]. In this case, the DirectIndex strategy maps the first argument in -the call to view(1,0) to that same value, and the IndexList maps the second -argument to the first index in the index_list. +is used for the second dimension. With this layout, the view created above will +choose the entry along the first dimension based on the first input index +provided, and the second provided index will be mapped to that corresponding +entry of the index_list for the second dimension. Some examples are shown in +the last two lines above. + +.. note:: There is currently no bounds checking implemented for IndexLayout. + When using the IndexList or ConditionalIndexList strategies, it is + the user's responsibility to know the extents of the index lists + when accessing data from a view. ------------------- RAJA Index Mapping diff --git a/test/unit/view-layout/test-indexlayout.cpp b/test/unit/view-layout/test-indexlayout.cpp index c84223358a..bd7effa8d4 100644 --- a/test/unit/view-layout/test-indexlayout.cpp +++ b/test/unit/view-layout/test-indexlayout.cpp @@ -213,11 +213,11 @@ TEST(IndexLayout, View2DLayout) * the direct index used along the 0-axis and * the index list {1,2} used along the 1-axis and * pass to a 2D view of size 2x3 with the each entry being i*j - * for i,j in [0,2)x[0,3) (e.g. view(1,2) = 1*2, view(0,3) = 0*3, etc..) + * for i,j in [0,2)x[0,3) (e.g. view(1,2) = 1*2, view(0,2) = 0*2, etc..) * Examples: * (index layout index -> view index -> view at index) * index_layout(0,1) -> view(0,2) -> 0 - * index_layout(2,0) -> view(2,1) -> 2 + * index_layout(1,0) -> view(1,1) -> 1 */ Index_type data[2][3]; From b14874c6d53cecf9416635f733395b18b4c8cb47 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Fri, 22 Dec 2023 10:57:31 -0800 Subject: [PATCH 3/8] more fixes to IndexLayout documentation --- docs/sphinx/user_guide/feature/view.rst | 29 +++++++++++++------------ 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index ad06859fd1..0675891443 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -333,21 +333,21 @@ indices by :math:`N`, :: Index Layout ^^^^^^^^^^^^ -``RAJA::IndexLayout`` is a layout that uses an indexing strategy for each -dimension to determine how to map a given input index to an entry within a view. +``RAJA::IndexLayout`` is a layout that can use an index list to map +input indices to an entry within a view. Each dimension of the layout +can have its own indexing strategy to determine this mapping. Three indexing strategies are natively supported in RAJA: DirectIndex, IndexList, and ConditionalIndexList. DirectIndex maps an input index to itself, and does not take any arguments in its constructor. The -IndexList strategy takes a reference to an array containing the list of relevant -indices to map. With this strategy, a given input index is mapped to the entry -in its list corresponding to that index. Lastly, the ConditionalIndexStrategy -takes a reference to an array containing an index list. When the referenced -index list is non-null, the ConditionalIndex strategy is equivalent to that -of the IndexList. Otherwise, if the index list provided to the constructor is a -null pointer, the ConditionalIndexList maps an input index to itself (same as -the DirectIndex strategy). The ConditionalIndexList strategy is useful when the -index list is not initialized for some situations. +IndexList strategy takes a pointer to an array of indices. With this strategy, +a given input index is mapped to the entry in its list corresponding to that +index. Lastly, the ConditionalIndexStrategy takes a pointer to an array of +indices. When the pointer is not a nullptr, the ConditionalIndex strategy is +equivalent to that of the IndexList. If the index list provided to +the constructor is a null pointer, the ConditionalIndexList is +identical to the DirectIndex strategy. The ConditionalIndexList strategy +is useful when the index list is not initialized for some situations. A simple illustrative example is shown below:: @@ -376,13 +376,14 @@ is implemented for the first dimension and an index list with the entries {1,2} is used for the second dimension. With this layout, the view created above will choose the entry along the first dimension based on the first input index provided, and the second provided index will be mapped to that corresponding -entry of the index_list for the second dimension. Some examples are shown in -the last two lines above. +entry of the index_list for the second dimension. .. note:: There is currently no bounds checking implemented for IndexLayout. When using the IndexList or ConditionalIndexList strategies, it is the user's responsibility to know the extents of the index lists - when accessing data from a view. + when accessing data from a view. It is also the user's + responsibility to ensure the index lists being used reside in the + same memory space as the data stored in the view. ------------------- RAJA Index Mapping From 29fea12e1465d0ba0251813ad50342fba62569da Mon Sep 17 00:00:00 2001 From: gberg617 <63525600+gberg617@users.noreply.github.com> Date: Fri, 22 Dec 2023 13:33:59 -0800 Subject: [PATCH 4/8] Update docs/sphinx/user_guide/feature/view.rst Co-authored-by: Jason Burmark --- docs/sphinx/user_guide/feature/view.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index 0675891443..885154a688 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -367,8 +367,8 @@ A simple illustrative example is shown below:: auto index_layout = RAJA::make_index_layout(index_tuple, 2, 3); auto view = RAJA::make_index_view(&data[0][0], index_layout); - int val0 = view(1,0); // val0 is entry in data[1][1] - int val1 = view(1,1); // val1 is entry in data[1][2] + assert( view(1,0) == data[1][1] ); + assert( &view(1,1) == &data[1][2] ); In the above example, a two-dimensional index layout is created with extents 2 and 3 for the first and second dimension, respectively. A DirectIndex strategy From 6fff43324a55b56f950583fb73c1b0b4aa6d98cf Mon Sep 17 00:00:00 2001 From: gberg617 Date: Fri, 22 Dec 2023 14:47:28 -0800 Subject: [PATCH 5/8] format index strategy names --- docs/sphinx/user_guide/feature/view.rst | 59 +++++++++++++------------ 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index 885154a688..034466aad1 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -333,21 +333,23 @@ indices by :math:`N`, :: Index Layout ^^^^^^^^^^^^ -``RAJA::IndexLayout`` is a layout that can use an index list to map -input indices to an entry within a view. Each dimension of the layout -can have its own indexing strategy to determine this mapping. - -Three indexing strategies are natively supported in RAJA: -DirectIndex, IndexList, and ConditionalIndexList. DirectIndex maps an input -index to itself, and does not take any arguments in its constructor. The -IndexList strategy takes a pointer to an array of indices. With this strategy, -a given input index is mapped to the entry in its list corresponding to that -index. Lastly, the ConditionalIndexStrategy takes a pointer to an array of -indices. When the pointer is not a nullptr, the ConditionalIndex strategy is -equivalent to that of the IndexList. If the index list provided to -the constructor is a null pointer, the ConditionalIndexList is -identical to the DirectIndex strategy. The ConditionalIndexList strategy -is useful when the index list is not initialized for some situations. +``RAJA::IndexLayout`` is a layout that can use an index list to map input +indices to an entry within a view. Each dimension of the layout can have its +own indexing strategy to determine this mapping. + +Three indexing strategies are natively supported in RAJA: ``RAJA::DirectIndex``, +``RAJA::IndexList``, and ``RAJA::ConditionalIndexList``. ``RAJA::DirectIndex`` +maps an input index to itself, and does not take any arguments in its +constructor. The ``RAJA::IndexList`` strategy takes a pointer to an array of +indices. With this strategy, a given input index is mapped to the entry in its +list corresponding to that index. Lastly, the +``RAJA::ConditionalIndexStrategy`` takes a pointer to an array of indices. When +the pointer is not a nullptr, the ``RAJA::ConditionalIndex`` strategy is +equivalent to that of the ``RAJA::IndexList``. If the index list provided to +the constructor is a null pointer, the ``RAJA::ConditionalIndexList`` is +identical to the ``RAJA::DirectIndex`` strategy. The +``RAJA::ConditionalIndexList`` strategy is useful when the index list is not +initialized for some situations. A simple illustrative example is shown below:: @@ -371,19 +373,20 @@ A simple illustrative example is shown below:: assert( &view(1,1) == &data[1][2] ); In the above example, a two-dimensional index layout is created with extents 2 -and 3 for the first and second dimension, respectively. A DirectIndex strategy -is implemented for the first dimension and an index list with the entries {1,2} -is used for the second dimension. With this layout, the view created above will -choose the entry along the first dimension based on the first input index -provided, and the second provided index will be mapped to that corresponding -entry of the index_list for the second dimension. - -.. note:: There is currently no bounds checking implemented for IndexLayout. - When using the IndexList or ConditionalIndexList strategies, it is - the user's responsibility to know the extents of the index lists - when accessing data from a view. It is also the user's - responsibility to ensure the index lists being used reside in the - same memory space as the data stored in the view. +and 3 for the first and second dimension, respectively. A ``RAJA::DirectIndex`` +strategy is implemented for the first dimension and ``RAJA::IndexList`` is used +with the entries for the second dimension with the list {1,2}. With this +layout, the view created above will choose the entry along the first dimension +based on the first input index provided, and the second provided index will be +mapped to that corresponding entry of the index_list for the second dimension. + +.. note:: There is currently no bounds checking implemented for + ``RAJA::IndexLayout``. When using the ``RAJA::IndexList`` or + ``RAJA::ConditionalIndexList`` strategies, it is the user's + responsibility to know the extents of the index lists when accessing + data from a view. It is also the user's responsibility to ensure + the index lists being used reside in the same memory space as the + data stored in the view. ------------------- RAJA Index Mapping From 454676824fd031586d6468662e05279e8b538483 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Fri, 22 Dec 2023 15:54:04 -0800 Subject: [PATCH 6/8] tried taking out a few extra RAJA namespace in text --- docs/sphinx/user_guide/feature/view.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index 034466aad1..702b4570b7 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -338,17 +338,17 @@ indices to an entry within a view. Each dimension of the layout can have its own indexing strategy to determine this mapping. Three indexing strategies are natively supported in RAJA: ``RAJA::DirectIndex``, -``RAJA::IndexList``, and ``RAJA::ConditionalIndexList``. ``RAJA::DirectIndex`` +``RAJA::IndexList``, and ``RAJA::ConditionalIndexList``. ``DirectIndex`` maps an input index to itself, and does not take any arguments in its -constructor. The ``RAJA::IndexList`` strategy takes a pointer to an array of +constructor. The ``IndexList`` strategy takes a pointer to an array of indices. With this strategy, a given input index is mapped to the entry in its list corresponding to that index. Lastly, the -``RAJA::ConditionalIndexStrategy`` takes a pointer to an array of indices. When -the pointer is not a nullptr, the ``RAJA::ConditionalIndex`` strategy is -equivalent to that of the ``RAJA::IndexList``. If the index list provided to -the constructor is a null pointer, the ``RAJA::ConditionalIndexList`` is -identical to the ``RAJA::DirectIndex`` strategy. The -``RAJA::ConditionalIndexList`` strategy is useful when the index list is not +``ConditionalIndexStrategy`` takes a pointer to an array of indices. When +the pointer is not a nullptr, the ``ConditionalIndex`` strategy is +equivalent to that of the ``IndexList``. If the index list provided to +the constructor is a null pointer, the ``ConditionalIndexList`` is +identical to the ``DirectIndex`` strategy. The +``ConditionalIndexList`` strategy is useful when the index list is not initialized for some situations. A simple illustrative example is shown below:: @@ -373,16 +373,16 @@ A simple illustrative example is shown below:: assert( &view(1,1) == &data[1][2] ); In the above example, a two-dimensional index layout is created with extents 2 -and 3 for the first and second dimension, respectively. A ``RAJA::DirectIndex`` -strategy is implemented for the first dimension and ``RAJA::IndexList`` is used +and 3 for the first and second dimension, respectively. A ``DirectIndex`` +strategy is implemented for the first dimension and ``IndexList`` is used with the entries for the second dimension with the list {1,2}. With this layout, the view created above will choose the entry along the first dimension based on the first input index provided, and the second provided index will be mapped to that corresponding entry of the index_list for the second dimension. .. note:: There is currently no bounds checking implemented for - ``RAJA::IndexLayout``. When using the ``RAJA::IndexList`` or - ``RAJA::ConditionalIndexList`` strategies, it is the user's + ``IndexLayout``. When using the ``IndexList`` or + ``ConditionalIndexList`` strategies, it is the user's responsibility to know the extents of the index lists when accessing data from a view. It is also the user's responsibility to ensure the index lists being used reside in the same memory space as the From dbaa1c37e5301a905786ee8e0cbe5351f86cc3b6 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Tue, 23 Jan 2024 13:20:11 -0800 Subject: [PATCH 7/8] minor re-wording --- docs/sphinx/user_guide/feature/view.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index 702b4570b7..3d3f24d448 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -334,8 +334,8 @@ Index Layout ^^^^^^^^^^^^ ``RAJA::IndexLayout`` is a layout that can use an index list to map input -indices to an entry within a view. Each dimension of the layout can have its -own indexing strategy to determine this mapping. +indices to an entry within a view. Each dimension of the layout is required to +have its own indexing strategy to determine this mapping. Three indexing strategies are natively supported in RAJA: ``RAJA::DirectIndex``, ``RAJA::IndexList``, and ``RAJA::ConditionalIndexList``. ``DirectIndex`` @@ -344,7 +344,7 @@ constructor. The ``IndexList`` strategy takes a pointer to an array of indices. With this strategy, a given input index is mapped to the entry in its list corresponding to that index. Lastly, the ``ConditionalIndexStrategy`` takes a pointer to an array of indices. When -the pointer is not a nullptr, the ``ConditionalIndex`` strategy is +the pointer is not a null pointer, the ``ConditionalIndex`` strategy is equivalent to that of the ``IndexList``. If the index list provided to the constructor is a null pointer, the ``ConditionalIndexList`` is identical to the ``DirectIndex`` strategy. The From 3e7079f7ba4534d544ebb6a9d242bab856ffb4b5 Mon Sep 17 00:00:00 2001 From: gberg617 Date: Wed, 24 Jan 2024 08:42:10 -0800 Subject: [PATCH 8/8] small change to get tests to re-run --- docs/sphinx/user_guide/feature/view.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/user_guide/feature/view.rst b/docs/sphinx/user_guide/feature/view.rst index 3d3f24d448..ca28e1db1b 100644 --- a/docs/sphinx/user_guide/feature/view.rst +++ b/docs/sphinx/user_guide/feature/view.rst @@ -365,7 +365,7 @@ A simple illustrative example is shown below:: auto index_tuple = RAJA::tuple, RAJA::IndexList<>>( RAJA::DirectIndex<>(), RAJA::IndexList<>{&index_list[0]}); - + auto index_layout = RAJA::make_index_layout(index_tuple, 2, 3); auto view = RAJA::make_index_view(&data[0][0], index_layout);