From a51dafa730941df268fffb33fcc2a5480aab74e1 Mon Sep 17 00:00:00 2001 From: Jeremiah Corrado Date: Mon, 18 Sep 2023 12:09:34 -0600 Subject: [PATCH 1/4] doc changes for transition from dmapped to distribution-factory-methods Signed-off-by: Jeremiah Corrado --- modules/dists/BlockCycDist.chpl | 2 +- modules/dists/BlockDist.chpl | 17 ++++++++++++++--- modules/dists/CyclicDist.chpl | 22 ++++++++++++++++------ modules/dists/StencilDist.chpl | 19 +++++++++++++++---- modules/dists/dims/BlockDim.chpl | 2 +- modules/packages/LinearAlgebra.chpl | 4 ++-- 6 files changed, 49 insertions(+), 17 deletions(-) diff --git a/modules/dists/BlockCycDist.chpl b/modules/dists/BlockCycDist.chpl index e4dd38461de6..a9d1d3516ba0 100644 --- a/modules/dists/BlockCycDist.chpl +++ b/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** diff --git a/modules/dists/BlockDist.chpl b/modules/dists/BlockDist.chpl index 879642b2bf50..41028f6d3d88 100644 --- a/modules/dists/BlockDist.chpl +++ b/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,15 @@ 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``. + + .. 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 diff --git a/modules/dists/CyclicDist.chpl b/modules/dists/CyclicDist.chpl index 8aeaa87ee732..7208050e6926 100644 --- a/modules/dists/CyclicDist.chpl +++ b/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,14 @@ 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``. + + .. function:: proc cyclicDist.createDomain(rng: range(?)...) + + Create a cyclic-distributed domain from a series of ranges over an existing + ``cyclicDist``. **Limitations** diff --git a/modules/dists/StencilDist.chpl b/modules/dists/StencilDist.chpl index 12670c963a21..5ccf2ed2d899 100644 --- a/modules/dists/StencilDist.chpl +++ b/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,15 @@ 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``. + + .. 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 +290,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 diff --git a/modules/dists/dims/BlockDim.chpl b/modules/dists/dims/BlockDim.chpl index ee5cfcca94b3..aa2b821e8ee6 100644 --- a/modules/dists/dims/BlockDim.chpl +++ b/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 { diff --git a/modules/packages/LinearAlgebra.chpl b/modules/packages/LinearAlgebra.chpl index c85debd217b5..94e6f3a11a2b 100644 --- a/modules/packages/LinearAlgebra.chpl +++ b/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 mapped to 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 mappd to the ``CS`` layout. */ proc isCSDom(D: domain) param { return isCSType(D.distribution.type); } From 6247d823541a48c4a90855a8f484869fd69a1696 Mon Sep 17 00:00:00 2001 From: Jeremiah Corrado Date: Mon, 18 Sep 2023 13:10:59 -0600 Subject: [PATCH 2/4] primer updates to remove dmapped keyword Signed-off-by: Jeremiah Corrado --- .../examples/primers/chplvis/chplvis2.chpl | 4 +- .../examples/primers/chplvis/chplvis3.chpl | 11 +++--- .../examples/primers/chplvis/chplvis4.chpl | 2 +- .../examples/primers/distributions.chpl | 39 +++++++++++++++++-- .../release/examples/primers/forallLoops.chpl | 14 +++---- 5 files changed, 52 insertions(+), 18 deletions(-) diff --git a/test/release/examples/primers/chplvis/chplvis2.chpl b/test/release/examples/primers/chplvis/chplvis2.chpl index 4b679301404b..6940d0ed8907 100644 --- a/test/release/examples/primers/chplvis/chplvis2.chpl +++ b/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 diff --git a/test/release/examples/primers/chplvis/chplvis3.chpl b/test/release/examples/primers/chplvis/chplvis3.chpl index 2635642fed92..bdaa47108102 100644 --- a/test/release/examples/primers/chplvis/chplvis3.chpl +++ b/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; diff --git a/test/release/examples/primers/chplvis/chplvis4.chpl b/test/release/examples/primers/chplvis/chplvis4.chpl index 623179a9ac7d..fc684c83dc88 100644 --- a/test/release/examples/primers/chplvis/chplvis4.chpl +++ b/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"); diff --git a/test/release/examples/primers/distributions.chpl b/test/release/examples/primers/distributions.chpl index 5d3c8dbbbc18..400d6143f8f0 100644 --- a/test/release/examples/primers/distributions.chpl +++ b/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(); 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:c + +.. code-block:: chapel + + const CA = cyclicDist.createArray(Space); + +*/ + forall ca in CA do ca = here.id; diff --git a/test/release/examples/primers/forallLoops.chpl b/test/release/examples/primers/forallLoops.chpl index 3d1cb7e2e433..ba0de612b333 100644 --- a/test/release/examples/primers/forallLoops.chpl +++ b/test/release/examples/primers/forallLoops.chpl @@ -150,14 +150,14 @@ 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 +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 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. +such as blockDist and cyclicDist, 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. Task Intents and Shadow Variables --------------------------------- From c297b2c7bc654f71d31c30a12b6ea9a94cf5ce46 Mon Sep 17 00:00:00 2001 From: Jeremiah Corrado Date: Mon, 18 Sep 2023 13:36:03 -0600 Subject: [PATCH 3/4] fix docs typo Signed-off-by: Jeremiah Corrado --- test/release/examples/primers/distributions.chpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/release/examples/primers/distributions.chpl b/test/release/examples/primers/distributions.chpl index 400d6143f8f0..ef534ea49126 100644 --- a/test/release/examples/primers/distributions.chpl +++ b/test/release/examples/primers/distributions.chpl @@ -54,7 +54,7 @@ const Space = {1..n, 1..n}; // domain. // const BlkDist = new blockDist(boundingBox=Space); -const BlockSpace = BlkDist.createDomain(); +const BlockSpace = BlkDist.createDomain(Space); var BA: [BlockSpace] int; /* From 79982a023280888f173097fbc4e483280998f292 Mon Sep 17 00:00:00 2001 From: Jeremiah Corrado Date: Mon, 18 Sep 2023 14:17:57 -0600 Subject: [PATCH 4/4] address review feedback on doc changes Signed-off-by: Jeremiah Corrado --- modules/dists/BlockDist.chpl | 3 ++- modules/dists/CyclicDist.chpl | 3 ++- modules/dists/StencilDist.chpl | 3 ++- modules/packages/LinearAlgebra.chpl | 4 ++-- test/release/examples/primers/distributions.chpl | 2 +- test/release/examples/primers/forallLoops.chpl | 5 +++-- 6 files changed, 12 insertions(+), 8 deletions(-) diff --git a/modules/dists/BlockDist.chpl b/modules/dists/BlockDist.chpl index 41028f6d3d88..64b5e41ef2a0 100644 --- a/modules/dists/BlockDist.chpl +++ b/modules/dists/BlockDist.chpl @@ -328,7 +328,8 @@ The helper methods on ``blockDist`` have the following signatures: .. function:: proc blockDist.createDomain(dom: domain(?)) - Create a block-distributed domain over an existing ``blockDist``. + Create a block-distributed domain over an existing ``blockDist`` by copying + the index space from the passed domain. .. function:: proc blockDist.createDomain(rng: range(?)...) diff --git a/modules/dists/CyclicDist.chpl b/modules/dists/CyclicDist.chpl index 7208050e6926..420ed78d0997 100644 --- a/modules/dists/CyclicDist.chpl +++ b/modules/dists/CyclicDist.chpl @@ -230,7 +230,8 @@ The helper methods on ``Cyclic`` have the following signatures: .. function:: proc cyclicDist.createDomain(dom: domain(?)) - Create a cyclic-distributed domain over an existing ``cyclicDist``. + Create a cyclic-distributed domain over an existing ``cyclicDist`` by copying + the index space from the passed domain. .. function:: proc cyclicDist.createDomain(rng: range(?)...) diff --git a/modules/dists/StencilDist.chpl b/modules/dists/StencilDist.chpl index 5ccf2ed2d899..9519411cd4f5 100644 --- a/modules/dists/StencilDist.chpl +++ b/modules/dists/StencilDist.chpl @@ -266,7 +266,8 @@ config param disableStencilLazyRAD = defaultDisableLazyRADOpt; .. function:: proc stencilDist.createDomain(dom: domain(?)) - Create a stencil-distributed domain over an existing ``blockDist``. + Create a stencil-distributed domain over an existing ``blockDist`` by copying + the index space from the passed domain. .. function:: proc stencilDist.createDomain(rng: range(?)...) diff --git a/modules/packages/LinearAlgebra.chpl b/modules/packages/LinearAlgebra.chpl index 94e6f3a11a2b..27618e88d4cd 100644 --- a/modules/packages/LinearAlgebra.chpl +++ b/modules/packages/LinearAlgebra.chpl @@ -3480,11 +3480,11 @@ module Sparse { @chpldoc.nodoc - /* Returns ``true`` if the array is mapped to the ``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 mappd to the ``CS`` layout. */ + /* Returns ``true`` if the domain is distributed with the CS layout. */ proc isCSDom(D: domain) param { return isCSType(D.distribution.type); } diff --git a/test/release/examples/primers/distributions.chpl b/test/release/examples/primers/distributions.chpl index ef534ea49126..19b503485d6a 100644 --- a/test/release/examples/primers/distributions.chpl +++ b/test/release/examples/primers/distributions.chpl @@ -189,7 +189,7 @@ following expressions for convenience: const CyclicSpace = cyclicDist.createDomain(Space); const CA: [CyclicSpace] int; -or:c +or: .. code-block:: chapel diff --git a/test/release/examples/primers/forallLoops.chpl b/test/release/examples/primers/forallLoops.chpl index ba0de612b333..408eee1c9cdc 100644 --- a/test/release/examples/primers/forallLoops.chpl +++ b/test/release/examples/primers/forallLoops.chpl @@ -153,12 +153,13 @@ determine iteration locality. 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 distributions, +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 distributions place each loop +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 ---------------------------------