rename array domain into array dimensions

* Rename ArrayDomainRange to ArrayDimsIndexRange
* Replace term domain by dimensions where appropriate
* Update images

docs/index.rst

@@ -31,7 +31,7 @@ LLAMA is licensed under the LGPL3+.
 
    pages/install
    pages/introduction
-   pages/domains
+   pages/dimensions
    pages/views
    pages/virtualrecord
    pages/iteration

docs/pages/api.rst

@@ -26,14 +26,14 @@ Useful helpers
    :members:
 .. doxygenfunction:: llama::structName
 
-Array domain
------------
+Array dimensions
+----------------
 
-.. doxygenstruct:: llama::ArrayDomain
+.. doxygenstruct:: llama::ArrayDims
 
-.. doxygenstruct:: llama::ArrayDomainIndexIterator
+.. doxygenstruct:: llama::ArrayDimsIndexIterator
    :members:
-.. doxygenstruct:: llama::ArrayDomainIndexRange
+.. doxygenstruct:: llama::ArrayDimsIndexRange
    :members:
 
 Record dimension
@@ -112,11 +112,11 @@ Mappings
 Common utilities
 ^^^^^^^^^^^^^^^^
 
-.. doxygenstruct:: llama::mapping::LinearizeArrayDomainCpp
+.. doxygenstruct:: llama::mapping::LinearizeArrayDimsCpp
    :members:
-.. doxygenstruct:: llama::mapping::LinearizeArrayDomainFortran
+.. doxygenstruct:: llama::mapping::LinearizeArrayDimsFortran
    :members:
-.. doxygenstruct:: llama::mapping::LinearizeArrayDomainMorton
+.. doxygenstruct:: llama::mapping::LinearizeArrayDimsMorton
    :members:
 
 Tree mapping

docs/pages/blobs.rst

@@ -62,8 +62,8 @@ Creating a small view of :math:`4 \times 4` may look like this:
 
 .. code-block:: C++
 
-    using ArrayDomain = llama::ArrayDomain<2>;
-    constexpr ArrayDomain miniSize{4, 4};
+    using ArrayDims = llama::ArrayDims<2>;
+    constexpr ArrayDims miniSize{4, 4};
 
     using Mapping = /* some simple mapping */;
     using BlobAllocator = llama::bloballoc::Stack<

docs/pages/domains.rst → docs/pages/dimensions.rst

@@ -1,37 +1,36 @@
 .. include:: common.rst
 
-.. _label-domains:
+.. _label-dimensions:
 
 Dimensions
 ==========
 
-As mentioned in the section before, LLAMA distinguishes between the array domain and the record dimension.
-The most important difference is that the array domain is defined at *run time* whereas the record dimension is defined at *compile time*.
+As mentioned in the section before, LLAMA distinguishes between the array and the record dimensions.
+The most important difference is that the array dimensions are defined at *run time* whereas the record dimension is defined at *compile time*.
 This allows to make the problem size itself a run time value but leaves the compiler room to optimize the data access.
 
 .. _label-ad:
 
-Array domain
-------------
+Array dimensions
+----------------
 
-The array domain is an :math:`N`-dimensional array with :math:`N` itself being a
+The array dimensions are an :math:`N`-dimensional array with :math:`N` itself being a
 compile time value but with run time values inside. LLAMA brings its own
 :ref:`array class <label-api-array>` for such kind of data structs which is
 ready for interoperability with hardware accelerator C++ dialects such as CUDA
 (Nvidia) or HIP (AMD), or abstraction libraries such as the already mentioned
 alpaka.
 
-A definition of a three-dimensional array domain of the size
-:math:`128 \times 256 \times 32` looks like this:
+A definition of three array dimensions of the size :math:`128 \times 256 \times 32` looks like this:
 
 .. code-block:: C++
 
-    llama::ArrayDomain arrayDomainSize{128, 256, 32};
+    llama::ArrayDims arrayDimsSize{128, 256, 32};
 
 The template arguments are deduced by the compiler using `CTAD <https://en.cppreference.com/w/cpp/language/class_template_argument_deduction>`_.
-The full type of :cpp:`arrayDomainSize` is :cpp:`llama::ArrayDomain<3>`.
+The full type of :cpp:`arrayDimsSize` is :cpp:`llama::ArrayDims<3>`.
 
-.. _label-dd:
+.. _label-rd:
 
 Record dimension
 ----------------

docs/pages/introduction.rst

@@ -100,16 +100,16 @@ The core data structure of LLAMA is the :ref:`View <label-view>`,
 which holds the memory for the data and provides methods to access the data space.
 In order to create a view, a `Mapping` is needed which is an abstract concept.
 LLAMA offers many kinds of mappings and users can also provide their own mappings.
-Mappings are constructed from a :ref:`record dimension <label-rd>`, containing tags, and an :ref:`Array domain <label-ad>`.
+Mappings are constructed from a :ref:`record dimension <label-rd>`, containing tags, and :ref:`array dimensions <label-ad>`.
 In addition to a mapping defining the memory layout, an array of :ref:`Blobs <label-blobs>` is needed for a view, supplying the actual storage behind the view.
 A blob is any object representing a contiguous chunk of memory, byte-wise addressable using :cpp:`operator[]`.
 A suitable Blob array is either directly provided by the user or built using a :ref:`BlobAllocator <label-bloballocators>` when a view is created by a call to `allocView`.
 A blob allocator is again an abstract concept and any object returning a blob of a requested size when calling :cpp:`operator()`.
 LLAMA comes with a set of predefined blob allocators and users can again provider their own.
 
 Once a view is created, the user can navigate on the data managed by the view.
-On top of a view, a :ref:`VirtualView <label-virtualview>` can be created, offering access to a subrange of the array domain.
-Elements of the array domain, called records, are accessed on both, View and VirtualView, by calling :cpp:`operator()` with an instance of the array domain.
+On top of a view, a :ref:`VirtualView <label-virtualview>` can be created, offering access to a subspace of the array dimensions.
+Elements of the array dimensions, called records, are accessed on both, View and VirtualView, by calling :cpp:`operator()` with an array dimensions coordinate as instance of :cpp:`ArrayDims`.
 This access returns a :ref:`VirtualRecord <label-virtualrecord>`, allowing further access using the tags from the record dimension, until eventually a reference to actual data in memory is returned.
 
 

docs/pages/iteration.rst

@@ -5,18 +5,18 @@
 Iteration
 =========
 
-Array domain iterating
-----------------------
+Array dimensions iteration
+--------------------------
 
-The array domain spans an N-dimensional space of integral indices.
+The array dimensions span an N-dimensional space of integral indices.
 Sometimes we just want to quickly iterate over all coordinates in this index space.
-This is what :cpp:`llama::ArrayDomainRange` is for, which is a range in the C++ sense and
+This is what :cpp:`llama::ArrayDimsIndexRange` is for, which is a range in the C++ sense and
 offers the :cpp:`begin()` and  :cpp:`end()` member functions with corresponding iterators to support STL algorithms or the range-for loop.
 
 .. code-block:: C++
 
-    llama::ArrayDomain<2> ad{3, 3};
-    llama::ArrayDomainIndexRange range{ad};
+    llama::ArrayDims<2> ad{3, 3};
+    llama::ArrayDimsIndexRange range{ad};
 
     std::for_each(range.begin(), range.end(), [](auto coord) {
         // coord is {0, 0}, {0, 1}, {0, 2}, {1, 0}, {1, 1}, {1, 2}, {2, 0}, {2, 1}, {2, 2}
@@ -27,7 +27,7 @@ offers the :cpp:`begin()` and  :cpp:`end()` member functions with corresponding
     }
 
 
-Record dimension iterating
+Record dimension iteration
 --------------------------
 
 The record dimension is iterated using :cpp:`llama::forEachLeaf`.
@@ -114,7 +114,7 @@ Having an iterator to a view opens up the standard library for use in conjunctio
 
 .. code-block:: C++
 
-    using ArrayDomain = llama::ArrayDomain<1>;
+    using ArrayDims = llama::ArrayDims<1>;
     // ...
     auto view = llama::allocView(mapping);
 
@@ -136,8 +136,8 @@ Since virtual records interact with each other based on the tags and not the und
 
 .. code-block:: C++
 
-    auto aosView = llama::allocView(llama::mapping::AoS<ArrayDomain, RecordDim>{arrayDomain});
-    auto soaView = llama::allocView(llama::mapping::SoA<ArrayDomain, RecordDim>{arrayDomain});
+    auto aosView = llama::allocView(llama::mapping::AoS<ArrayDims, RecordDim>{arrayDimsSize});
+    auto soaView = llama::allocView(llama::mapping::SoA<ArrayDims, RecordDim>{arrayDimsSize});
     // ...
     std::copy(begin(aosView), end(aosView), begin(soaView));
 

docs/pages/mappings.rst

@@ -5,8 +5,8 @@
 Mappings
 ========
 
-One of the core tasks of LLAMA is to map an address from the array domain and
-record dimension to some address in the allocated memory space.
+One of the core tasks of LLAMA is to map an address from the array and
+record dimensions to some address in the allocated memory space.
 This is particularly challenging if the compiler shall still be able to optimize the resulting
 memory accesses (vectorization, reordering, aligned loads, etc.).
 The compiler needs to **understand** the semantic of the mapping at compile time.
@@ -26,19 +26,19 @@ The view requires each mapping to fulfill the following concept:
 
     template <typename M>
     concept Mapping = requires(M m) {
-        typename M::ArrayDomain;
+        typename M::ArrayDims;
         typename M::RecordDim;
         { M::blobCount } -> std::convertible_to<std::size_t>;
         llama::Array<int, M::blobCount>{}; // validates constexpr-ness
         { m.blobSize(std::size_t{}) } -> std::same_as<std::size_t>;
-        { m.blobNrAndOffset(typename M::ArrayDomain{}) } -> std::same_as<NrAndOffset>;
+        { m.blobNrAndOffset(typename M::ArrayDims{}) } -> std::same_as<NrAndOffset>;
     };
 
-That is, each mapping type needs to expose the types :cpp:`M::ArrayDomain` and :cpp:`M::RecordDim`.
+That is, each mapping type needs to expose the types :cpp:`M::ArrayDims` and :cpp:`M::RecordDim`.
 Furthermore, each mapping needs to provide a static constexpr member variable :cpp:`blobCount` and two member functions.
 :cpp:`blobSize(i)` gives the size in bytes of the :cpp:`i`\ th block of memory needed for this mapping.
 :cpp:`i` is in the range of :cpp:`0` to :cpp:`blobCount - 1`.
-:cpp:`blobNrAndOffset(ad)` implements the core mapping logic by translating a array domain coordinate :cpp:`ad` into a value of :cpp:`llama::NrAndOffset`, containing the blob number of offset within the blob where the value should be stored.
+:cpp:`blobNrAndOffset(ad)` implements the core mapping logic by translating an array coordinate :cpp:`ad` into a value of :cpp:`llama::NrAndOffset`, containing the blob number of offset within the blob where the value should be stored.
 
 AoS mappings
 ------------
@@ -49,12 +49,12 @@ However, they do not vectorize well in practice.
 
 .. code-block:: C++
 
-    llama::mapping::AoS<ArrayDomain, RecordDim> mapping{arrayDomainSize};
-    llama::mapping::AoS<ArrayDomain, RecordDim, true> mapping{arrayDomainSize}; // respect alignment
-    llama::mapping::AoS<ArrayDomain, RecordDim, true
-        llama::mapping::LinearizeArrayDomainFortran> mapping{arrayDomainSize}; // respect alignment, column major
+    llama::mapping::AoS<ArrayDims, RecordDim> mapping{arrayDimsSize};
+    llama::mapping::AoS<ArrayDims, RecordDim, true> mapping{arrayDimsSize}; // respect alignment
+    llama::mapping::AoS<ArrayDims, RecordDim, true
+        llama::mapping::LinearizeArrayDimsFortran> mapping{arrayDimsSize}; // respect alignment, column major
 
-By default, the :cpp:`ArrayDomain` is linearized using :cpp:`llama::mapping::LinearizeArrayDomainCpp` and the layout is tightly packed.
+By default, the :cpp:`ArrayDims` is linearized using :cpp:`llama::mapping::LinearizeArrayDimsCpp` and the layout is tightly packed.
 LLAMA provides the aliases :cpp:`llama::mapping::AlignedAoS` and :cpp:`llama::mapping::PackedAoS` for convenience.
 
 
@@ -63,7 +63,7 @@ but, since the mapping code is more complicated, compilers currently fail to aut
 
 .. code-block:: C++
 
-    llama::mapping::AoSoA<ArrayDomain, RecordDim, Lanes> mapping{arrayDomainSize};
+    llama::mapping::AoSoA<ArrayDims, RecordDim, Lanes> mapping{arrayDimsSize};
 
 .. _label-tree-mapping:
 
@@ -77,12 +77,12 @@ This layout auto vectorizes well in practice.
 
 .. code-block:: C++
 
-    llama::mapping::SoA<ArrayDomain, RecordDim> mapping{arrayDomainSize};
-    llama::mapping::SoA<ArrayDomain, RecordDim, true> mapping{arrayDomainSize}; // separate blob for each attribute
-    llama::mapping::SoA<ArrayDomain, RecordDim, true,
-        llama::mapping::LinearizeArrayDomainFortran> mapping{arrayDomainSize}; // separate blob for each attribute, column major
+    llama::mapping::SoA<ArrayDims, RecordDim> mapping{arrayDimsSize};
+    llama::mapping::SoA<ArrayDims, RecordDim, true> mapping{arrayDimsSize}; // separate blob for each attribute
+    llama::mapping::SoA<ArrayDims, RecordDim, true,
+        llama::mapping::LinearizeArrayDimsFortran> mapping{arrayDimsSize}; // separate blob for each attribute, column major
 
-By default, the :cpp:`ArrayDomain` is linearized using :cpp:`llama::mapping::LinearizeArrayDomainCpp` and the layout is mapped into a single blob.
+By default, the :cpp:`ArrayDims` is linearized using :cpp:`llama::mapping::LinearizeArrayDimsCpp` and the layout is mapped into a single blob.
 LLAMA provides the aliases :cpp:`llama::mapping::SingleBlobSoA` and :cpp:`llama::mapping::MultiBlobSoA` for convenience.
 
 
@@ -96,25 +96,25 @@ The AoSoA mapping has a mandatory additional parameter specifying the number of
 
 .. code-block:: C++
 
-    llama::mapping::AoSoA<ArrayDomain, RecordDim, 8> mapping{arrayDomainSize}; // inner array has 8 values
-    llama::mapping::AoSoA<ArrayDomain, RecordDim, 8,
-        llama::mapping::LinearizeArrayDomainFortran> mapping{arrayDomainSize}; // inner array has 8 values, column major
+    llama::mapping::AoSoA<ArrayDims, RecordDim, 8> mapping{arrayDimsSize}; // inner array has 8 values
+    llama::mapping::AoSoA<ArrayDims, RecordDim, 8,
+        llama::mapping::LinearizeArrayDimsFortran> mapping{arrayDimsSize}; // inner array has 8 values, column major
 
-By default, the :cpp:`ArrayDomain` is linearized using :cpp:`llama::mapping::LinearizeArrayDomainCpp`.
+By default, the :cpp:`ArrayDims` is linearized using :cpp:`llama::mapping::LinearizeArrayDimsCpp`.
 
 LLAMA also provides a helper :cpp:`llama::mapping::maxLanes` which can be used to determine the maximum vector lanes which can be used for a given record dimension and vector register size.
 In this example, the inner array a size of N so even the largest type in the record dimension can fit N times into a vector register of 256bits size (e.g. AVX2).
 
 .. code-block:: C++
 
-    llama::mapping::AoSoA<ArrayDomain, RecordDim,
-        llama::mapping::maxLanes<RecordDim, 256>> mapping{arrayDomainSize};
+    llama::mapping::AoSoA<ArrayDims, RecordDim,
+        llama::mapping::maxLanes<RecordDim, 256>> mapping{arrayDimsSize};
 
 
 One mapping
 -----------
 
-The One mapping is intended to map all coordinates in the array domain onto the same memory location.
+The One mapping is intended to map all coordinates in the array dimensions onto the same memory location.
 This is commonly used in  the `llama::One` virtual record, but also offers interesting applications in conjunction with the `llama::mapping::Split` mapping.
 
 
@@ -129,9 +129,9 @@ The remaining record dimension is mapped using a second mapping.
 
 .. code-block:: C++
 
-    llama::mapping::Split<ArrayDomain, RecordDim,
+    llama::mapping::Split<ArrayDims, RecordDim,
         llama::RecordCoord<1>, llama::mapping::SoA, llama::mapping::PackedAoS>
-            mapping{arrayDomainSize}; // maps the subtree at index 1 as SoA, the rest as packed AoS
+            mapping{arrayDimsSize}; // maps the subtree at index 1 as SoA, the rest as packed AoS
 
 Split mappings can be nested to map a record dimension into even fancier combinations.
 
@@ -145,7 +145,7 @@ WARNING: The tree mapping is currently not maintained and we consider deprecatio
 
 The LLAMA tree mapping is one approach to archieve the goal of mixing different mapping approaches.
 Furthermore, it tries to establish a general mapping description language and mapping definition framework.
-Let's take the example record dimension from the :ref:`domain section<label-domains>`:
+Let's take the example record dimension from the :ref:`dimensions section<label-dimensions>`:
 
 .. image:: ../images/layout_tree.svg
 
@@ -155,9 +155,9 @@ representing the repetition of branches and to define tree operations which
 create new trees out of the old ones while providing methods to translate tree
 coordinates from one tree to another.
 
-This is best demonstrated by an example. First of all the array domain needs to be
-represented as such an tree too. Let's assume a array domain of
-:math:`128 \times 64`:
+This is best demonstrated by an example.
+First of all the array dimensions needs to be represented as such an tree too.
+Let's assume array dimensions of :math:`128 \times 64`:
 
 .. image:: ../images/ud_tree_2.svg
 
@@ -166,8 +166,8 @@ The record dimension is already a tree, but as it has no run time influence, onl
 
 .. image:: ../images/layout_tree_2.svg
 
-Now the two trees are connected so that we can represent array domain and record
-dimension with one tree:
+Now the two trees are connected so that we can represent array and record
+dimensions with one tree:
 
 .. image:: ../images/start_tree_2.svg
 
@@ -189,7 +189,7 @@ Struct of array but with a padding after each 1024 elements may look like this:
 The size of the leaf type in "pad" of course needs to be determined based on the
 desired aligment and sub tree sizes.
 
-Such a tree (with smaller array domain for easier drawing) …
+Such a tree (with smaller array dimensions for easier drawing) …
 
 .. image:: ../images/example_tree.svg
 
@@ -208,19 +208,19 @@ a further constructor parameter for the instantiation of this tuple.
     };
 
     using Mapping = llama::mapping::tree::Mapping<
-        ArrayDomain,
+        ArrayDims,
         RecordDim,
         decltype(treeOperationList)
     >;
 
     Mapping mapping(
-        arrayDomainSize,
+        arrayDimsSize,
         treeOperationList
     );
 
     // or using CTAD and an unused argument for the record dimension:
     llama::mapping::tree::Mapping mapping(
-        arrayDomainSize,
+        arrayDimsSize,
         llama::Tuple{
             llama::mapping::tree::functor::LeafOnlyRT()
         },