Class Places

Class Places#

Class Documentation#

class Places#

Public Functions

Dimension getDimensions() const#

Returns the number of dimensions in this plaPlacesces object. (I.e. 2D, 3D, etc…)

Returns:

the number of dimensions in this Places object.

const NDSize &getSize() const#

Returns the actual N-dimensional size of this Places.

Returns:

the N-dimensional size

Count getNumPlaces() const#

Returns the number of Place object present in this Places collection.

Returns:

the number of Place object present in this Places collection.

EntityHandle getHandle() const#

Returns the handle associated with this Places object.

Returns:

the handle associated with this Places object.

void callAll(FunctionId functionId, const void *argument, ByteCount argSize)#

Executes the function by given functionId on each Place element within this Places with the provided argument.

Attention

It is recommended to use the other overload that takes the typed argument directly for better experience. Only use this overload when you only got a void pointer or type erasure is required.

Parameters:

  • functionId – the function id passed to each Place element

  • argument – the argument to be passed to each Place element

  • argSize – the size in bytes of the argument

template<typename ArgType, internal::type_deduction::require_non_ptr_single_trivial_t<ArgType> = 0>
void callAll(FunctionId functionId, const ArgType &argument)#

Executes the function by given functionId on each Place element within this Places with the provided argument.

Template Parameters:

ArgType – the type of the argument

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the argument value to be passed to each function invocation

template<typename ArgCollection, internal::type_deduction::require_contiguous_collection_of_trivial_t<ArgCollection> = 0>
void callAll(FunctionId functionId, const ArgCollection &argument)#

Executes the function by given functionId on each Place element within this Places with the provided argument, where the argument is a collection of some values.

Template Parameters:

ArgCollection – the type of the argument (must be a collection)

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the argument value to be passed to each function invocation

template<typename ArgType, internal::type_deduction::require_non_ptr_single_trivial_t<ArgType> = 0>
void callAll(FunctionId functionId, std::initializer_list<ArgType> argument)#

Executes the function by given functionId on each Place element within this Places with the provided argument, where the argument is a collection of some values.

Template Parameters:

ArgType – the type of each element in the argument collection

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the argument value to be passed to each function invocation

void callAll(FunctionId functionId)#

Executes the function by given functionId on each Place element within this Places with no argument

Parameters:

functionId – the id of the function to be invoked

template<typename ArgCollection, internal::type_deduction::require_contiguous_collection_of_trivial_t<ArgCollection> = 0>
void callAllWithPerPlaceArg(FunctionId functionId, const ArgCollection &args)#

Executes the function by the given functionId on each Place element within this Places with separated arguments for each element

Template Parameters:

ArgCollection – the type of the argument collection

Parameters:

  • functionId – the id of the function to be invoked

  • args – the collection of argument values, where each value is for one Place element

template<typename OffsetCollection, internal::type_deduction::require_contiguous_collection_of_type_t<OffsetCollection, const NDOffset> = 0>
void updateNeighbours(const OffsetCollection &neighbourOffsets)#

Update the neighbour information for all the Place instances within this Places

Template Parameters:

OffsetCollection – the type representing the neighbor information for each Place instance, must be a collection of mass::NDOffset

Parameters:

neighbourOffsets – the new neighbor information for each Place instance, represented as a collection of N-dimensional offset values

void updateNeighbours(std::initializer_list<NDOffset> neighbourOffsets)#

Update the neighbour information for all the Place instances within this Places

Parameters:

neighbourOffsets – the new neighbor information for each Place instance, represented as a collection of N-dimensional offset values

template<typename AttrTagCollection, internal::type_deduction::require_contiguous_collection_of_type_t<AttrTagCollection, const AttrTag> = 0>
void syncPlaceBorder(const AttrTagCollection &attrsToSync)#

Share attribute values of the Place instances at the boundary of each block with its neighbors

Template Parameters:

AttrTagCollection – the type representing a collection of attribute tags

Parameters:

attrsToSync – the collection of tags of the attributes that should be included in this sharing process. If empty, fall back to include the attributes configured by the mass::Places::addAttrsForSyncBorder / mass::Places::setAttrsForSyncBorder functions

void syncPlaceBorder(std::initializer_list<AttrTag> attrsToSync = {})#

Share attribute values of the Place instances at the boundary of each block with its neighbors

Parameters:

attrsToSync – the collection of tags of the attributes that should be included in this sharing process. If empty, fall back to include the attributes configured by the mass::Places::addAttrsForSyncBorder / mass::Places::setAttrsForSyncBorder functions

void exchangeAll(std::vector<int*> *destinations) = delete#
void exchangeAll(std::vector<int*> *destinations, int functionId, void *argument = nullptr, int argSize = 0) = delete#

This function causes all Place elements to exchange information about their neighbors and to call the function specified with functionId on each of the places afterwards.

In addition to the fuctionality of the standard exchangeAllPlaces function specified above it also takes functionId as a parameter and arguments to that function. When the data is collected from the neighboring places, the specified function is executed on all of the places with specified parameters. The rationale behind implemening this version of exchangeAllPlaces is performance optimization: the data cached during data collection step can be used for the data calculation and thus minimize the number of memeory fetches and improve performance.

Parameters:

  • destinations – A vector of relative indexes of neighbors.

  • functionId – The ID of the user defined function.

  • argument – The function argument. Can be NULL.

  • argSize – The size of argument in bytes. If argument == NULL, argSize is not used.

void exchangeAll(int nNeighbors) = delete#

This function causes all Place elements to exchange information about their neighbors.

Unlike the standard exchangeAllPlaces function, this function uses the NEIGHBOR_OFFSETS attribute array to determine the neighbors of each place where the standard exchangeAllPlaces function uses the input vector of relative indexes of neighbors.

The NEIGHBOR_OFFSETS attribute array should be set by the user before calling this function.

Parameters:

nNeighbors – The number of neighbors for each place.

void exchangeAll(int nNeighbors, int functionId, void *argument = nullptr, int argSize = 0) = delete#

This function causes all Place elements to exchange information about their neighbors and to call the function specified with functionId on each of the places afterwards.

Unlike the standard exchangeAllPlaces function, this function uses the NEIGHBOR_OFFSETS attribute array to determine the neighbors of each place where the standard exchangeAllPlaces function uses the input vector of relative indexes of neighbors.

The NEIGHBOR_OFFSETS attribute array should be set by the user before calling this function.

Parameters:

  • nNeighbors – The number of neighbors for each place.

  • functionId – The ID of the user defined function.

  • argument – The function argument. Can be NULL.

  • argSize – The size of argument in bytes. If argument == NULL, argSize is not used.

thrust::device_ptr<Place> getDevPointer() const#

Returns the pointer to dev Places object.

Index getRowMajorIdx(const NDIndex &index) const#

Returns the row major index of the given coordinates. For instance, in an int[3][5] Places, the element (1,3) will have the row major index of 8.

This is the inverse function of getIndexVector()

Parameters:

index – a series of ints ordered rowIdx,colIdx,ZIdx,etc… that specify a single element in this places object. The number of elements must be equal to the number of dimensions in this places object. All indices must be non-negative.

Returns:

an int representing the row-major index where this element is stored.

Index getRowMajorIdx(const int ndIndex[]) const#
NDIndex getIndexVector(Index rowMajorIdx) const#

This function will take a valid (in bounds) row-major index for this places object and return a vector that contains the row, col, z, etc… indices for the place element at the given row major index.

This is the inverse function of getRowMajorIdx(…)

Parameters:

rowMajorIdx – the index of an element in a flattened mult-dimensional array. Must be non-negative.

Returns:

a vector<int> with the multi-dimensional indices of the element.

template<typename AttributeType>
void setAttribute(AttrTag tag, Count32 elementCount, std::optional<AttributeType> defaultValue = std::nullopt, bool permanentlyExcludedFromSyncBorder = false)#

Add an attribute to all the Place instances.

This function is the pre-stage of adding attributes, it only adds the attribute on the host. When all attributes have been added, call the mass::Places::finalizeAttributes function to update the attributes info on the device.

Warning

The permanentlyExcludedFromSyncBorder parameter is mainly designed for internal implementation. For most of the user-defined attributes, it should be false. Only set it to true when you are 100% sure what you are doing.

Parameters:

  • tag – the unique tag of the new attribute, used as an identifier

  • elementCount – the num of elements of the attribute. If the value is larger than 1, the attribute is a 2D attribute (or array attribute). The value must not be less than 1.

  • defaultValue – the default value of the attribute. This attribute value of every Place instance will be initialized to this value.

  • permanentlyExcludedFromSyncBorder – whether this attribute should be permanently excluded when calling mass::Places::syncPlaceBorder.

template<typename AttributeType, internal::type_deduction::require_non_ptr_single_trivial_t<AttributeType> = 0>
void setSharedAttribute(AttrTag tag, const AttributeType &value)#

Add a Shared Attribute holding a single constant value shared by all the Place instances

Template Parameters:

AttributeType – the type of the attribute

Parameters:

  • tag – the unique tag of the new attribute, used as an identifier

  • value – the value of the attribute, which is not mutable after being set here

template<typename AttributeCollection, internal::type_deduction::require_contiguous_collection_of_trivial_t<AttributeCollection> = 0>
void setSharedAttribute(AttrTag tag, const AttributeCollection &values)#

Add a Shared Attribute holding an array of constant values shared by all the Place instances

Template Parameters:

AttributeCollection – the collection type holding the values of the Shared Attribute

Parameters:

  • tag – the unique tag of the new attribute, used as an identifier

  • values – the collection of values for initializing the array of values of the attribute. Not mutable after being set here

template<typename AttributeType, internal::type_deduction::require_non_ptr_single_trivial_t<AttributeType> = 0>
void setSharedAttribute(AttrTag tag, std::initializer_list<AttributeType> values)#

Add a Shared Attribute holding an array of constant values shared by all the Place instances

Parameters:

  • tag – the unique tag of the new attribute, used as an identifier

  • values – the collection of values for initializing the array of values of the attribute. Not mutable after being set here

std::vector<AttrTag> getAttributeTags() const#

Get the attributes tags.

Returns:

the array of attribute tags

std::vector<std::vector<void*>> getAttributeDevPtrs() const#

Get the attributes devPtrs.

Returns:

the array of attribute device pointers

std::vector<std::vector<ByteCount>> getAttributePitch() const#

Get the attributes pitch.

Returns:

the array of attribute pitch. If the attribute is 1D, then the pitch is 0.

const AttributeMeta &getAttributeMeta(AttrTag tag) const#

Retrieve the metadata of an attribute

Parameters:

tag – the tag of the attribute for retrieving the metadata

Returns:

the metadata of the requested attribute

const SharedAttributeMeta &getSharedAttributeMeta(AttrTag tag) const#

Retrieve the metadata of a shared attribute

Parameters:

tag – the tag of the shared attribute for retrieving the metadata

Returns:

the metadata of the requested shared attribute

std::pair<const Place*, PtrType> unsafeGetRawStoragePtr(DeviceRank deviceRank) const#

Get the raw pointer of the contiguous storage of all the Place instances on a certain device, together with the type of pointer

Parameters:

deviceRank – the rank of the device for retrieving the pointer

Returns:

the raw pointer and pointer type of the storage of all the Place instances on the requested device

template<typename AttributeType>
RawAttributeLocalStorageSnapshot<AttributeType> getRawAttributeLocalStorageSnapshot(DeviceRank deviceRank, AttrTag tag) const#

Get a snapshot of the raw storage of an attribute on a certain device (including Place instances within the ghost regions)

Template Parameters:

AttributeType – type of the attribute value

Parameters:

  • deviceRank – rank of the device for getting the snapshot

  • tag – tag of the attribute for getting the snapshot

Returns:

the snapshot of raw storage of the specified attribute on the specified device

void finalizeAttributes()#

Finalize the attributes. After adding attributes using the setAttribute() function, this function must be called to update the attributes info on the device. Otherwise, the attributes will not be updated on the device.

void removeAttrsFromSyncBorder(std::initializer_list<AttrTag> tags)#

Exclude a set of attributes from the syncPlaceBorder process

Parameters:

tags – tags of the attributes to be excluded

template<typename AttrTagCollection, internal::type_deduction::require_contiguous_collection_of_type_t<AttrTagCollection, const AttrTag> = 0>
void removeAttrsFromSyncBorder(const AttrTagCollection &tags)#

Exclude a set of attributes from the syncPlaceBorder process

Parameters:

tags – tags of the attributes to be excluded

void addAttrsForSyncBorder(std::initializer_list<AttrTag> tags)#

Include a set of attributes for the syncPlaceBorder process

Parameters:

tags – tags of the attributes to be included

template<typename AttrTagCollection, internal::type_deduction::require_contiguous_collection_of_type_t<AttrTagCollection, const AttrTag> = 0>
void addAttrsForSyncBorder(const AttrTagCollection &tags)#

Include a set of attributes for the syncPlaceBorder process

Parameters:

tags – tags of the attributes to be included

void setAttrsForSyncBorder(std::initializer_list<AttrTag> tags)#

Specify a set of attributes for the syncPlaceBorder process while overwriting existing configuration

Parameters:

tags – tags of the attributes to be included

template<typename AttrTagCollection, internal::type_deduction::require_contiguous_collection_of_type_t<AttrTagCollection, const AttrTag> = 0>
void setAttrsForSyncBorder(const AttrTagCollection &tags)#

Specify a set of attributes for the syncPlaceBorder process while overwriting existing configuration

Parameters:

tags – tags of the attributes to be included

void resetIncludedAttrForSyncBorder()#

Reset the attributes included for the syncPLaceBorder process to the default configuration, which is all the attribute excluding REAL_ADDR and those already being excluded permanently

template<typename AttributeType>
std::vector<std::unique_ptr<AttributeType[]>> downloadAttributes(AttrTag tag)#

Download the attributes from the device.

Parameters:

tag – the attribute tag.

Returns:

An array of buffers containing the attribute values

Public Static Functions

static Offset relativeIndexToOffset(const NDOffset &relativeIndex, const NDSize &size, MemoryOrder majorType)#