Remove dmapped from docs (chapel-lang#23440)

Replace various uses of `dmapped` throughout the docs with distribution
factory functions due to `dmapped` being unstable.

Also adds documentation for the `createDomain` methods on `blockDist`,
`cyclicDist`, and `stencilDist` that were missing documentation.

- [x] paratest
- [x] inspected docs

[ reviewed by @mppf ] - Thanks!

modules/dists/BlockCycDist.chpl

@@ -172,7 +172,7 @@ of tasks on each Locale for data parallelism.
 The ``rank`` and ``idxType`` arguments are inferred from the
 ``startIdx`` argument unless explicitly set.
 They must match the rank and index type of the domains
-"dmapped" using that blockCycDist instance.
+created using that blockCycDist instance.
 
 
 **Data-Parallel Iteration**

modules/dists/BlockDist.chpl

@@ -189,7 +189,7 @@ of the locale to which it is mapped.
 
     const Space = {1..8, 1..8};
     const Dist = new blockDist(boundingBox=Space);
-    const D = Space dmapped Dist;
+    const D = Dist.createDomain(Space);
     var A: [D] int;
 
     forall a in A do
@@ -272,11 +272,13 @@ The helper methods on ``blockDist`` have the following signatures:
 
   .. function:: proc type blockDist.createDomain(dom: domain, targetLocales = Locales)
 
-    Create a block-distributed domain.
+    Create a block-distributed domain. The provided domain is used as the
+    ``boundingBox``.
 
   .. function:: proc type blockDist.createDomain(rng: range(?)..., targetLocales = Locales)
 
-    Create a block-distributed domain from a series of ranges.
+    Create a block-distributed domain from a series of ranges. The ranges
+    are also used to construct the ``boundingBox``.
 
   .. function:: proc type blockDist.createArray(dom: domain, type eltType, targetLocales = Locales)
 
@@ -324,6 +326,16 @@ The helper methods on ``blockDist`` have the following signatures:
     .. Warning::
       ``blockDist.createArray`` with an ``initExpr`` formal is unstable and may change in a future release
 
+  .. function:: proc blockDist.createDomain(dom: domain(?))
+
+    Create a block-distributed domain over an existing ``blockDist`` by copying
+    the index space from the passed domain.
+
+  .. function:: proc blockDist.createDomain(rng: range(?)...)
+
+    Create a block-distributed domain from a series of ranges over an existing
+    ``blockDist``.
+
 **Sparse Subdomains**
 
 When a ``sparse subdomain`` is created from a block-distributed

modules/dists/CyclicDist.chpl

@@ -97,7 +97,7 @@ to the ID of the locale to which it is mapped.
     use CyclicDist;
 
     const Dist = new cyclicDist(startIdx=(1,1));
-    const D = {1..8, 1..8} dmapped Dist;
+    const D = cyclicDist.createDomain({1..8, 1..8});
     var A: [D] int;
 
     forall a in A do
@@ -178,15 +178,17 @@ and arrays using `(1, 1)` as the starting index:
 
 The helper methods on ``Cyclic`` have the following signatures:
 
-  .. function:: proc type cyclicDist.createDomain(dom: domain, targetLocales = Locales)
+  .. function:: proc type cyclicDist.createDomain(dom: domain(?), targetLocales = Locales)
 
-    Create a cyclic-distributed domain.
+    Create a cyclic-distributed domain. The lower bounds of the domain are used
+    as the starting indices.
 
   .. function:: proc type cyclicDist.createDomain(rng: range(?)..., targetLocales = Locales)
 
-    Create a cyclic-distributed ddomain from a series of ranges.
+    Create a cyclic-distributed domain from a series of ranges. The lower
+    bounds of the ranges are used as the starting indices.
 
-  .. function:: proc type cyclicDist.createArray(dom: domain, type eltType, targetLocales = Locales)
+  .. function:: proc type cyclicDist.createArray(dom: domain(?), type eltType, targetLocales = Locales)
 
     Create a default-initialized cyclic-distributed array whose indices
     match those of the given domain.
@@ -196,7 +198,7 @@ The helper methods on ``Cyclic`` have the following signatures:
     Create a default-initialized cyclic-distributed array using a
     domain constructed from the series of ranges.
 
-  .. function:: proc type cyclicDist.createArray(dom: domain, type eltType, initExpr, targetLocales = Locales)
+  .. function:: proc type cyclicDist.createArray(dom: domain(?), type eltType, initExpr, targetLocales = Locales)
 
     Create a cyclic-distributed array whose indices match those of the
     given domain.
@@ -226,6 +228,15 @@ The helper methods on ``Cyclic`` have the following signatures:
     * an array of compatible size and type — the array will be assigned into
       the distributed array
 
+  .. function:: proc cyclicDist.createDomain(dom: domain(?))
+
+    Create a cyclic-distributed domain over an existing ``cyclicDist`` by copying
+    the index space from the passed domain.
+
+  .. function:: proc cyclicDist.createDomain(rng: range(?)...)
+
+    Create a cyclic-distributed domain from a series of ranges over an existing
+    ``cyclicDist``.
 
 **Limitations**
 

modules/dists/StencilDist.chpl

@@ -216,11 +216,13 @@ config param disableStencilLazyRAD = defaultDisableLazyRADOpt;
 
   .. function:: proc type stencilDist.createDomain(dom: domain, targetLocales = Locales, fluff, periodic = false)
 
-    Create a stencil-distributed domain.
+    Create a stencil-distributed domain. The provided domain is used as the
+    ``boundingBox``.
 
   .. function:: proc type stencilDist.createDomain(rng: range(?)..., targetLocales = Locales, fluff, periodic = false)
 
-    Create a stencil-distributed domain from a series of ranges.
+    Create a stencil-distributed domain from a series of ranges. The ranges
+    are also used to construct the ``boundingBox``.
 
   .. function:: proc type stencilDist.createArray(dom: domain, type eltType, targetLocales = Locales, fluff, periodic = false)
 
@@ -234,7 +236,7 @@ config param disableStencilLazyRAD = defaultDisableLazyRADOpt;
 
   .. function:: proc type stencilDist.createArray(dom: domain, type eltType, initExpr, targetLocales = Locales, fluff, periodic = false)
 
-    Create a stencil-distributed whose indices match those of the
+    Create a stencil-distributed array whose indices match those of the
     given domain.
 
     The array's values are initialized using ``initExpr`` which can be any of
@@ -262,6 +264,16 @@ config param disableStencilLazyRAD = defaultDisableLazyRADOpt;
     * an array of compatible size and type — the array will be assigned into
       the distributed array
 
+  .. function:: proc stencilDist.createDomain(dom: domain(?))
+
+    Create a stencil-distributed domain over an existing ``blockDist`` by copying
+    the index space from the passed domain.
+
+  .. function:: proc stencilDist.createDomain(rng: range(?)...)
+
+    Create a stencil-distributed domain from a series of ranges over an existing
+    ``blockDist``.
+
 
   Note that the ``fluff`` argument in the above methods defaults to a
   tuple of *n* zeros, where *n* is the domain's rank or the number of
@@ -279,7 +291,7 @@ config param disableStencilLazyRAD = defaultDisableLazyRADOpt;
 
     const Space = {1..10, 1..10};
     const Dist = new stencilDist(boundingBox=Space, fluff=(1,1));
-    const D = Space dmapped Dist;
+    const D = Dist.createDomain(Space);
     var A : [D] int;
 
     forall (i,j) in D with (ref A) do

modules/dists/dims/BlockDim.chpl

@@ -57,7 +57,7 @@ a convenient replacement for the ``boundingBox`` argument,
 which specifies the bounding box in this dimension.
 
 The ``idxType``, whether provided or inferred, must match
-the index type of the domains "dmapped" using the corresponding
+the index type of the domains created using the corresponding
 ``dimensionalDist2D`` distribution.
 */
 record BlockDim {

modules/packages/LinearAlgebra.chpl

@@ -3480,11 +3480,11 @@ module Sparse {
 
 
   @chpldoc.nodoc
-  /* Returns ``true`` if the array is dmapped to ``CS`` layout. */
+  /* Returns ``true`` if the array is distributed with the CS layout. */
   proc isCSArr(A: []) param { return isCSType(A.domain.distribution.type); }
 
   @chpldoc.nodoc
-  /* Returns ``true`` if the domain is dmapped to ``CS`` layout. */
+  /* Returns ``true`` if the domain is distributed with the CS layout. */
   proc isCSDom(D: domain) param { return isCSType(D.distribution.type); }
 
 

test/release/examples/primers/chplvis/chplvis2.chpl

@@ -13,7 +13,7 @@ proc main() {
 
    // Create a couple of domains and a block mapped data array.
    const Domain = { 1 .. ncells };
-   const mapDomain = Domain dmapped blockDist(Domain);
+   const mapDomain = blockDist.createDomain(Domain);
 
    var  data : [mapDomain] int = 1;
 
@@ -23,7 +23,7 @@ proc main() {
    // First computation step ... a simple forall
    // Even though the data is distributed, the computation is
    // on Locale 0.  chplvis shows no computation on locales
-   // other than 0.   Domain is not dmapped.
+   // other than 0.   Domain is not distributed.
    forall i in Domain with (ref data) do data[i] += here.id + 1;
 
    // Write the result, we want to see the results of the above

test/release/examples/primers/chplvis/chplvis3.chpl

@@ -27,12 +27,13 @@ const space = {1..n, 1..n};
 const bspace = {0..n+1, 0..n+1};
 const bsouth = {n+1..n+1, 1..n};
 
-// Dmapped versions of the domains
-const R = space dmapped blockDist(boundingBox=bspace);
-const BigR = bspace dmapped blockDist(boundingBox=bspace);
-const South = bsouth dmapped blockDist(boundingBox=bspace);
+// distributed versions of the domains
+const bd = new blockDist(boundingBox=bspace);
+const R = bd.createDomain(space);
+const BigR = bd.createDomain(bspace);
+const South = bd.createDomain(bsouth);
 
-// Dmapped arrays
+// distributed arrays
 var A : [BigR] real;
 var Temp : [R] real;
 var Diff   : [R] real;

test/release/examples/primers/chplvis/chplvis4.chpl

@@ -8,7 +8,7 @@ use VisualDebug;
 use BlockDist;
 
 const space =  { 0 .. #numLocales };
-const Dspace = space dmapped blockDist (boundingBox=space);
+const Dspace = blockDist.createDomain(space);
 
 startVdebug("E4");
 

test/release/examples/primers/distributions.chpl

@@ -54,9 +54,25 @@ const Space = {1..n, 1..n};
 // domain.
 //
 const BlkDist = new blockDist(boundingBox=Space);
-const BlockSpace = Space dmapped BlkDist;
+const BlockSpace = BlkDist.createDomain(Space);
 var BA: [BlockSpace] int;
 
+/*
+The above could also be shortened to one of the following for convenience:
+
+.. code-block:: chapel
+
+	const BlockSpace = blockDist.createDomain(Space);  
+	const BA: [BlockSpace] int;
+
+or:
+
+.. code-block:: chapel
+
+	const BA = blockDist.createArray(Space);
+
+*/
+
 //
 // To illustrate how the index set is distributed across locales,
 // we'll use a forall loop to initialize each array element to the
@@ -124,7 +140,7 @@ var MyLocales: [MyLocaleView] locale = reshape(Locales, MyLocaleView);
 //
 
 const BlkDist2 = new blockDist(boundingBox=Space, targetLocales=MyLocales);
-const BlockSpace2 = Space dmapped BlkDist2;
+const BlockSpace2 = BlkDist2.createDomain(Space);
 var BA2: [BlockSpace2] int;
 
 //
@@ -161,9 +177,26 @@ for (L, ML) in zip(BA2.targetLocales(), MyLocales) do
 // indices that precede the distribution's starting index.
 //
 const CycDist = new cyclicDist(startIdx=Space.low);
-const CyclicSpace = Space dmapped CycDist;
+const CyclicSpace = CycDist.createDomain(Space);
 var CA: [CyclicSpace] int;
 
+/*
+As with ``blockDist``, the above could also be shortened to one of the
+following expressions for convenience:
+
+.. code-block:: chapel
+
+	const CyclicSpace = cyclicDist.createDomain(Space);  
+	const CA: [CyclicSpace] int;
+
+or:
+
+.. code-block:: chapel
+
+	const CA = cyclicDist.createArray(Space);
+
+*/
+
 forall ca in CA do
   ca = here.id;
 

test/release/examples/primers/forallLoops.chpl

@@ -150,14 +150,15 @@ Its parallel iterator will determine how this loop is parallelized.
 if A were a distributed array, its parallel iterator would also
 determine iteration locality.
 
-Domains declared without a ``dmapped`` clause, including
-default rectangular and default associative domains, as well as
-arrays over such domains, provide both serial and parallel
-iterators. So do domains distributed over standard distributions,
-such as blockDist and cyclicDist (:ref:`primers-distributions`), and
-arrays over such domains. The parallel iterators provided
-by standard distributions place each loop iteration on the
-locale where the corresponding index or array element is placed.
+Domains declared without a distribution (see :ref:`primers-distributions`),
+including default rectangular and default associative domains,
+as well as arrays over such domains, provide both serial and parallel
+iterators. So do domains distributed over standard multi-locale distributions,
+such as blockDist and cyclicDist, and arrays over such domains. The
+parallel iterators provided by standard multi-locale distributions place each loop
+iteration on the locale where the corresponding index or array element
+is placed.
+
 
 Task Intents and Shadow Variables
 ---------------------------------