charm4py.Array is a type of distributed collection where chares have
n-dimensional indexes (represented by an integer n-tuple), and members can exist
anywhere on the system. As such, there can
be zero or multiple elements of a chare array on a given PE, and elements can
migrate between PEs.
Arrays are created using the following syntax:
charm4py.Array(chare_type, dims=None, ndims=-1, args=, map=None) where
chare_type is the type of chares that will constitute the array.
There are two modes to create an array:
- Specifying the bounds.
dimsis an n-tuple indicating the size of each dimension. The number of elements that will be created is the product of the sizes of every dimension. For example,
dims=(2,3,5)will create an array of 30 chares with 3D indexes.
- Empty array of unspecified bounds, when
ndimsindicates the number of dimensions to be used for indexes.
argsis the list of arguments to pass to the constructor of each element.
mapcan be optionally used to specify an
ArrayMapfor initial mapping of chares to PEs (see below). It must be a proxy to the map. If unspecified, the system will choose a default mapping.
The call to create an array returns a proxy to the array.
Any number of arrays (of the same or different chare types) can be created. Each array that is created has a unique integer identifier, called the “Array ID”.
The call to create an array returns immediately without waiting for all the
elements to be created. See
charm.awaitCreation() for one mechanism to wait
Arrays with unspecified bounds support dynamic insertion of elements via the array proxy (see below). Note that these types of arrays can be sparse in the sense that elements need not have contiguous indexes. Elements can be inserted in any order, from any location, at any time.
An Array proxy references a chare array and its elements. An array proxy is returned
when creating an Array (see above) and can also be accessed from the attribute
of the elements of the array (see Chare). Like any proxy, array proxies
can be sent to any chares in the system.
- aid: The ID of the array that the proxy references.
- ndims: Number of dimensions of the indexes used by the array.
- elemIdx: This is an empty tuple if the proxy references the whole array, otherwise it is the index of an individual element in the array.
- self[index]: return a new proxy object which references the element in the array
with the given
- self.ckInsert(index, args=, onPE=-1): Insert an element with
indexinto the array. This is only valid for arrays that were created empty (with unspecified bounds).
argsis the list of arguments passed to the constructor of the element.
onPEcan be used to indicate on which PE to create the element.
- self.ckDoneInserting(): This must be used when finished adding elements with
ArrayMap is a special type of Group whose function is to customize the initial
mapping of chares to PEs for a chare Array.
A custom ArrayMap is defined by writing a new class that inherits from
and defining the method
procNum(self, index), which receives the index of an array element,
and returns the PE number where that element must be created.
To use an ArrayMap, it must first be created like any other Group, and the proxy to the map must be passed to the Array constructor (see above).
Note that array elements may migrate after creation and the ArrayMap only determines the initial placement.