'dmap', "domain map", and 'dmapped' updates in the spec (#23522)

This PR makes the following changes to the language spec:

* Rename "domain map" to "distribution", based on a group discussion.
* Remove the `dmap` type, since we are moving away from it.
* Indicate that `dmapped` is unstable.
* Switch from "domain map class" to "distribution record".
* Switch from `Block` to `blockDist`.
* General text and link improvements.

r: @dlongnecke-cray

Author: vasslitvinov

doc/rst/language/spec/arrays.rst

@@ -11,15 +11,14 @@ of homogeneous type. Since Chapel domains support a rich variety of
 index sets, Chapel arrays are also richer than the traditional linear or
 rectilinear array types in conventional languages. Like domains, arrays
 may be distributed across multiple locales without explicitly
-partitioning them using Chapel’s Domain
-Maps (:ref:`Chapter-Domain_Maps`).
+partitioning them using Chapel’s :ref:`distributions <Chapter-Domain_Maps>`.
 
-Parallel Safety with respect to Arrays (and Domains)
-----------------------------------------------------
+Parallel Safety with respect to Arrays
+--------------------------------------
 
 Users must take care when applying operations to arrays and domains
-concurrently from distinct tasks. For more information see the parallel safety
-section for domains (:ref:`Domain_and_Array_Parallel_Safety`).
+concurrently from distinct tasks. For more information see
+:ref:`the Parallel Safety section for domains <Domain_and_Array_Parallel_Safety>`.
 
 .. _Array_Types:
 
@@ -314,7 +313,7 @@ Runtime Representation of Array Values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The runtime representation of an array in memory is controlled by its
-domain’s domain map. Through this mechanism, users can reason about and
+domain’s distribution. Through this mechanism, users can reason about and
 control the runtime representation of an array’s elements. See
  :ref:`Chapter-Domain_Maps` for more details.
 
@@ -825,7 +824,7 @@ in :ref:`Formal_Arguments_of_Generic_Array_Types`.
 If a formal array argument specifies a domain as part of its type
 signature, the domain of the actual argument must represent the same
 index set. If the formal array’s domain was declared using an explicit
-domain map, the actual array’s domain must use an equivalent domain map.
+distribution, the actual array’s domain must use an equivalent distribution.
 
 .. _Array_Promotion_of_Scalar_Functions:
 

doc/rst/language/spec/domain-maps.rst

@@ -2,88 +2,76 @@
 
 .. _Chapter-Domain_Maps:
 
-===========
-Domain Maps
-===========
+=============
+Distributions
+=============
 
-A domain map specifies the implementation of the domains and arrays that
+A distribution, also called a *domain map*,
+specifies the implementation of the domains and arrays that
 are *mapped* using it. That is, it defines how domain indices and array
 elements are mapped to locales, how they are stored in memory, and how
 operations such as accesses, iteration, and slicing are performed. Each
-domain and array is mapped using some domain map.
+domain and array is mapped using some distribution.
 
-A domain map is either a *layout* or a *distribution*. A layout
-describes domains and arrays that exist on a single locale, whereas a
-distribution describes domains and arrays that are partitioned across
-multiple locales.
+In general, a distribution describes domains and arrays
+that are partitioned across multiple locales.
+A *layout* is a distribution that describes domains and arrays
+that exist on a single locale.
 
-A domain map is represented in the program with an instance of a *domain
-map class*. Chapel provides a set of standard domain map classes. Users
-can create domain map classes as well.
+A distribution is represented in the program with an instance of a
+*distribution record*. Chapel provides a set of standard distributions.
+Users can create distributions as well.
 
-Domain maps are presented as follows:
+Distributions are presented as follows:
 
--  domain maps for domain types :ref:`Domain_Maps_For_Types`,
-   domain values :ref:`Domain_Maps_For_Values`, and arrays
-   :ref:`Domain_Maps_For_Arrays`
+-  distributions for
+   :ref:`domain types <Domain_Maps_For_Types>`,
+   :ref:`domain values <Domain_Maps_For_Values>`,
+   :ref:`arrays <Domain_Maps_For_Arrays>`
 
--  domain maps are not retained upon domain assignment
-   :ref:`Domain_Maps_Not_Assigned`
+-  :ref:`distributions are not retained upon domain assignment <Domain_Maps_Not_Assigned>`
 
--  standard layouts and distributions, such as Block and Cyclic, are
-   documented under
-   :ref:`Standard Layouts and Distributions <layouts_and_distributions>`
+-  :ref:`Standard Layouts and Distributions <layouts_and_distributions>`,
+   such as Block and Cyclic
 
--  specification of user-defined domain maps is forthcoming; please
+-  specification of user-defined distributions is forthcoming; please
    refer to the
    :ref:`Domain Map Standard Interface technical note <readme-dsi>`
 
 .. _Domain_Maps_For_Types:
 
-Domain Maps for Domain Types
-----------------------------
+Distributions for Domain Types
+------------------------------
 
-Each domain type has a domain map associated with it. This domain map is
+Each domain type has a distribution associated with it. This distribution is
 used to map all domain values of this type
-(:ref:`Domain_Maps_For_Values`).
+(see :ref:`Domain_Maps_For_Values`).
 
-If a domain type does not have a domain map specified for it explicitly
-as described below, a default domain map is provided by the Chapel
-implementation. Such a domain map will typically be a layout that maps
-the entire domain to the locale on which the domain value is created or
+If a domain type does not have a distribution specified for it explicitly
+as described below, a default distribution is provided by the Chapel
+implementation. Such a distribution will typically be a layout that maps
+the entire domain to the locale on which the current task is executed or
 the domain or array variable is declared.
 
-A domain map can be specified explicitly by providing a *dmap value* in
-a ``dmapped`` clause:
-
-
+A distribution can be specified explicitly using a ``dmapped`` clause:
 
 .. code-block:: syntax
 
    mapped-domain-type:
-     domain-type 'dmapped' dmap-value
+     domain-type 'dmapped' distribution-record
 
-   dmap-value:
+   distribution-record:
      expression
 
-A dmap value consists of an instance of a domain map class wrapped in an
-instance of the predefined record ``dmap``. The domain map class is
-chosen and instantiated by the user. ``dmap`` behaves like a generic
-record with a single generic field, which holds the domain map instance.
-
-   *Example*.
+where the ``distribution-record`` expression produces
+an instance of a distribution record.
 
-   The code 
+.. warning::
 
-   .. code-block:: chapel
-
-      use BlockDist;
-      var MyBlockDist: dmap(Block(rank=2));
-
-   declares a variable capable of storing dmap values for a
-   two-dimensional Block distribution. The Block distribution is
-   described in more detail in the standard library documentation.
-   See the module documentation for :mod:`BlockDist`.
+   The ``dmapped`` keyword and the ``dmapped`` clause
+   are currently unstable and may change in the future.
+   Factory functions provided by the desired distribution,
+   when available, should be used instead.
 
 ..
 
@@ -94,9 +82,10 @@ record with a single generic field, which holds the domain map instance.
    .. code-block:: chapel
 
       use BlockDist;
-      var MyBlockDist: dmap(Block(rank=2)) = new dmap(new Block({1..5,1..6}));
+      var MyBlockDist = new blockDist({1..5,1..6});
 
-   creates a dmap value wrapping a two-dimensional Block distribution
+   creates an instance of the Block distribution record
+   for two-dimensional domains and arrays
    with a bounding box of ``{1..5, 1..6}`` over all of the locales.
 
    *Example*.
@@ -106,17 +95,16 @@ record with a single generic field, which holds the domain map instance.
    .. code-block:: chapel
 
       use BlockDist;
-      var MyBlockDist = new dmap(new Block({1..5,1..6}));
+      var MyBlockDist = new blockDist({1..5,1..6});
       type MyBlockedDom = domain(2) dmapped MyBlockDist;
 
-   defines a two-dimensional rectangular domain type that is mapped
-   using a Block distribution.
+   defines the type of two-dimensional rectangular domains
+   that are mapped using a Block distribution.
 
 The following syntactic sugar is provided within the ``dmapped`` clause.
-If a ``dmapped`` clause starts with the name of a domain map class, it
+If a ``dmapped`` clause starts with the name of a distribution record, it
 is considered to be an initialization expression as if preceded by
-``new``. The resulting domain map instance is wrapped in a newly-created
-instance of ``dmap`` implicitly.
+``new``.
 
    *Example*.
 
@@ -125,23 +113,23 @@ instance of ``dmap`` implicitly.
    .. code-block:: chapel
 
       use BlockDist;
-      type BlockDom = domain(2) dmapped Block({1..5,1..6});
+      type BlockDom = domain(2) dmapped blockDist({1..5,1..6});
 
    is equivalent to 
 
    .. code-block:: chapel
 
       use BlockDist;
-      type BlockDom = domain(2) dmapped new dmap(new Block({1..5,1..6}));
+      type BlockDom = domain(2) dmapped new blockDist({1..5,1..6});
 
 .. _Domain_Maps_For_Values:
 
-Domain Maps for Domain Values
------------------------------
+Distributions for Domain Values
+-------------------------------
 
-A domain value is always mapped using the domain map of that value’s
+A domain value is always mapped using the distribution of that value's
 type. The type inferred for a domain literal
-(:ref:`Rectangular_Domain_Values`) has a default domain map.
+(see :ref:`Rectangular_Domain_Values`) has a default distribution.
 
    *Example*.
 
@@ -151,22 +139,19 @@ type. The type inferred for a domain literal
 
       use BlockDist;
       var MyDomLiteral = {1..2,1..3};
-      var MyBlockedDom: domain(2) dmapped Block({1..5,1..6}) = MyDomLiteral;
-
-   ``MyDomLiteral`` is given the inferred type of the domain literal and
-   so will be mapped using a default map. MyBlockedDom is given a type
-   explicitly, in accordance to which it will be mapped using a Block
-   distribution.
-
-A domain value’s map can be changed explicitly with a ``dmapped``
-clause, in the same way as a domain type’s map.
+      var MyBlockedDom: domain(2) dmapped blockDist({1..5,1..6}) = MyDomLiteral;
 
+   ``MyDomLiteral`` is a domain literal and so will be mapped using
+   a default distribution. MyBlockedDom is given a type explicitly,
+   therefore it will be mapped using a Block distribution.
 
+A domain value's distribution can be specified explicitly with a ``dmapped``
+clause, in the same way as a domain type's distribution.
 
 .. code-block:: syntax
 
    mapped-domain-expression:
-     domain-expression 'dmapped' dmap-value
+     domain-expression 'dmapped' distribution-record
 
 ..
 
@@ -177,18 +162,18 @@ clause, in the same way as a domain type’s map.
    .. code-block:: chapel
 
       use BlockDist;
-      var MyBlockedDomLiteral1 = {1..2,1..3} dmapped new dmap(new Block({1..5,1..6}));
-      var MyBlockedDomLiteral2 = {1..2,1..3} dmapped Block({1..5,1..6});
+      var MyBlockedDomLiteral1 = {1..2,1..3} dmapped new blockDist({1..5,1..6});
+      var MyBlockedDomLiteral2 = {1..2,1..3} dmapped blockDist({1..5,1..6});
 
    both ``MyBlockedDomLiteral1`` and ``MyBlockedDomLiteral2`` will be
    mapped using a Block distribution.
 
 .. _Domain_Maps_For_Arrays:
 
-Domain Maps for Arrays
-----------------------
+Distributions for Arrays
+------------------------
 
-Each array is mapped using the domain map of the domain over which the
+Each array is mapped using the distribution of the domain over which the
 array was declared.
 
    *Example*.
@@ -198,20 +183,20 @@ array was declared.
    .. code-block:: chapel
 
       use BlockDist;
-      var Dom: domain(2) dmapped Block({1..5,1..6}) = {1..5,1..6};
+      var Dom: domain(2) dmapped blockDist({1..5,1..6}) = {1..5,1..6};
       var MyArray: [Dom] real;
 
-   the domain map used for ``MyArray`` is the Block distribution from
+   the distribution used for ``MyArray`` is the Block distribution from
    the type of ``Dom``.
 
 .. _Domain_Maps_Not_Assigned:
 
-Domain Maps Are Not Retained upon Domain Assignment
----------------------------------------------------
+Distributions Are Not Retained upon Domain Assignment
+-----------------------------------------------------
 
-Domain assignment (:ref:`Domain_Assignment`) transfers only the
+:ref:`Domain assignment <Domain_Assignment>` transfers only the
 index set of the right-hand side expression. The implementation of the
-left-hand side domain expression, including its domain map, is
+left-hand side domain expression, including its distribution, is
 determined by its type and so does not change upon a domain assignment.
 
    *Example*.
@@ -221,10 +206,10 @@ determined by its type and so does not change upon a domain assignment.
    .. code-block:: chapel
 
       use BlockDist;
-      var Dom1: domain(2) dmapped Block({1..5,1..6}) = {1..5,1..6};
+      var Dom1: domain(2) dmapped blockDist({1..5,1..6}) = {1..5,1..6};
       var Dom2: domain(2) = Dom1;
 
-   ``Dom2`` is mapped using the default distribution, despite ``Dom1``
+   ``Dom2`` is mapped using a default distribution, despite ``Dom1``
    having a Block distribution.
 
 ..
@@ -236,11 +221,11 @@ determined by its type and so does not change upon a domain assignment.
    .. code-block:: chapel
 
       use BlockDist;
-      var Dom1: domain(2) dmapped Block({1..5,1..6}) = {1..5,1..6};
+      var Dom1: domain(2) dmapped blockDist({1..5,1..6}) = {1..5,1..6};
       var Dom2 = Dom1;
 
    ``Dom2`` is mapped using the same distribution as ``Dom1``. This is
    because the declaration of ``Dom2`` lacks an explicit type specifier
    and so its type is defined to be the type of its initialization
    expression, ``Dom1``. So in this situation the effect is that the
-   domain map does transfer upon an initializing assignment.
+   distribution does transfer upon initialization.

doc/rst/language/spec/domains.rst

@@ -72,8 +72,8 @@ domain’s relationship with subdomains, index
 types (:ref:`Index_Types`), and
 arrays (:ref:`Association_of_Arrays_to_Domains`).
 
-The runtime representation of a domain is controlled by its domain map.
-Domain maps are presented in :ref:`Chapter-Domain_Maps`.
+The runtime representation of a domain is controlled by its distribution,
+see :ref:`Distributions <Chapter-Domain_Maps>`.
 
 .. _Domain_and_Array_Parallel_Safety:
 
@@ -427,7 +427,7 @@ Simple Subdomain Types and Values
 A subdomain is a domain whose indices are guaranteed to be a subset of
 those described by another domain known as its *parent domain*. A
 subdomain has the same type as its parent domain, and by default it
-inherits the domain map of its parent domain. All domain types support
+inherits the distribution of its parent domain. All domain types support
 subdomains.
 
 Simple subdomains are subdomains which are not sparse. Sparse subdomains
@@ -446,7 +446,7 @@ subdomains, unless it is specifically distinguished as one or the other.
    Subdomains are provided in Chapel for a number of reasons: to
    facilitate the ability of the compiler or a reader to reason about
    the inter-relationship of distinct domain variables; to support the
-   author’s ability to omit redundant domain mapping specifications; to
+   author’s ability to omit redundant distribution specifications; to
    support the compiler’s ability to reason about the relative alignment
    of multiple domains; and to improve the compiler’s ability to prove
    away bounds checks for array accesses.
@@ -811,7 +811,7 @@ be defined with either a domain or a list of ranges.
 
 The result of slicing, or a *slice*, is a new domain value that
 represents the intersection of the index set of the domain being sliced
-and the index set being applied. The type and domain map of the slice
+and the index set being applied. The type and distribution of the slice
 match the domain being sliced.
 
 Slicing can also be performed on an array, resulting in aliasing a
@@ -881,7 +881,7 @@ The ``#`` operator can be applied to dense rectangular domains with a
 tuple argument whose size matches the rank of the domain (or optionally
 an integer in the case of a 1D domain). The operator produces a new domain
 obtained by applying the ``#`` operator to each of the component ranges
-of the argument domain, with the same domain map as the argument.
+of the argument domain, with the same distribution as the argument.
 
 .. _Adding_and_Removing_Domain_Indices:
 

doc/rst/language/spec/expressions.rst

@@ -348,8 +348,8 @@ Precedence and Associativity
 | ``**``             | right          | exponentiation                       |
 +--------------------+----------------+--------------------------------------+
 | | ``reduce``       | left           | | reduction                          |
-| | ``scan``         | scan           | | scan                               |
-| | ``dmapped``      |                | | domain map application             |
+| | ``scan``         |                | | scan                               |
+| | ``dmapped``      |                | | application of a distribution      |
 |                    |                |                                      |
 +--------------------+----------------+--------------------------------------+
 | | prefix ``!``     | right          | | logical negation                   |