Class Place

• Defined in File Place.h

Class Documentation

class Place

Place v2 is a new version of the Place class that is intended to boost performance by extracting the place state from the place class. As a result, the Place v2 class does not contain the PlaceState object anymore. But you can still get attributes from it using getAttribute() function. See functions below.

Public Types

using MemoryOrder = MemoryOrder

Public Functions

__universal__ inline explicit Place(const Index localIndex)

The constructor called on the GPU device.

Parameters:

localIndex – The local index of the Place instance within the current block (including Ghost Regions).

__universal__ inline virtual ~Place()

__device__ virtual void callMethod(FunctionId functionId, void *arg) = 0

Called by MASS while executing Places.callAll(). This is intended to be a switch statement where each user-implemented function is mapped to a funcID, and is passed ‘args’ when called.

Parameters:

• functionId – The ID of the function to be called.

• arg – A pointer to the arguments passed to the function.

__device__ inline Index getIndex() const

Returns the flattened index of this Place within the complete Places grid.

__device__ inline Index getLocalIndex() const

Return the flattened local index of this Place within the block on the current device

__device__ inline bool isGhost() const

Whether this Place instance is within a ghost region

__device__ inline Index32 getFlattenBlockIndex() const

Get the flattened block index on the current device

__device__ inline Count getNumPlaces() const

Returns the number of Place object.

Note

Currently, this info is stored as a constant (and the only one) in the device, which we are assuming there is only one Places that is created by users during the simulation. If there will be multiple Places in the future, we will need to maybe store this info in each Place object of each Places object. The way we do it now is to read the constant from the device. In this way, we do not need to store the info in each Place object, which can save a lot of memory.

__device__ inline ArrayAttrPtr<Index> getNeighbors()

Belows are getters for pre-defined attributes of Place.

Returns the indices within the complete Places grid of the neighboring instances of this Place.

The length of the returned array is MASS_MAX_NEIGHBORS.

Warning

Previously the indices returned by this method is mainly used for feeding into the getAttribute method for faster access of attribute values of the neighbors (though it’s actually not faster at all). However, such patten is not possible anymore in a multi-GPUs context. So carefully think whether you truly need this method and consider using getNeighborsPtr method instead.

__device__ inline ArrayAttrPtr<Place*> getNeighborsPtr()

Returns the pointer to the neighbors of this Place.

The length of the returned array is MASS_MAX_NEIGHBORS.

__device__ inline ArrayAttrPtr<Offset32> getNeighborOffsets()

Returns the neighbors’ relative offsets of this Place.

The length of the returned array is MASS_MAX_NEIGHBORS.

__device__ inline ArrayAttrPtr<Agent*> getAgents()

Returns the array of Agent instances residing in this Place.

A non-null slot indicates an Agent instance there

The length of the returned array is MASS_MAX_AGENTS.

__device__ inline Count32 getAgentPopulation() const

Gets the number of Agents currently residing in this place.

__device__ inline ArrayAttrPtr<Agent*> getPotentialAgents()

Returns the potential Agents that are going to migrate to this Place.

The length of the returned array is MASS_MAX_POTENTIAL_AGENTS.

__device__ inline Count32 getPotentialPopulation() const

Gets the number of potential Agents that are going to migrate to this place.

template<typename T>
__device__ ArrayAttrPtr<const T> getAttribute(AttrTag tag, Count elementCount) const

End of getters for pre-defined attributes of Place.

Resolve the pointer to the value of an attribute identified by the attribute tag

Template Parameters:

T – the type of the attribute value

Parameters:

• tag – The tag of the attribute.

• elementCount – The length of the attribute (length set when adding an attribute).

Returns:

A pointer to the attribute value

template<typename T>
__device__ ArrayAttrPtr<T> getAttribute(AttrTag tag, Count elementCount)

Resolve the pointer to the value of an attribute identified by the attribute tag

Template Parameters:

T – the type of the attribute value

Parameters:

• tag – the tag of the attribute

• elementCount – the length of the attribute (length set when adding an attribute)

Returns:

A pointer to the attribute value

template<typename T>
__device__ AttrPtr<const T> getAttribute(AttrTag tag) const

Resolve the pointer to the value of an attribute identified by the attribute tag, where the attribute should have elementCount == 1.

Template Parameters:

T – the type of the attribute value

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ AttrPtr<T> getAttribute(AttrTag tag)

Resolve the pointer to the value of an attribute identified by the attribute tag, where the attribute should have elementCount == 1.

Template Parameters:

T – the type of the attribute value

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ ArrayAttrPtr<T> getArrAttribute(AttrTag tag)

Resolve the pointer to the value of an attribute identified by the attribute tag, where the attribute should have elementCount > 1.

Template Parameters:

T – the type of each element of the attribute

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ ArrayAttrPtr<const T> getArrAttribute(AttrTag tag) const

Resolve the pointer to the value of an attribute identified by the attribute tag, where the attribute should have elementCount > 1.

Template Parameters:

T – the type of each element of the attribute

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ AttrPtr<const T> getSharedAttribute(AttrTag tag) const

Resolve the pointer to the value of a shared attribute identified by the attribute tag, where the attribute should have elementCount == 1.

Template Parameters:

T – the type of the attribute value

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ ArrayAttrPtr<const T, byteCountOf(T)> getSharedArrAttribute(AttrTag tag) const

Resolve the pointer to the value of a shared attribute identified by the attribute tag, where the attribute should have elementCount > 1.

Template Parameters:

T – the type of each element of the attribute

Parameters:

tag – the tag of the attribute

Returns:

A pointer to the attribute value

template<typename T>
__device__ ArrayAttrPtr<T> getAttribute(Index destLocalIndexWithGhost, AttrTag tag, Count elementCount) const

Get an attribute of another Place by attribute tag (name set by user when adding an attribute). For more information about the tag and length, please refer to Places::setAttribute().

Parameters:

• destLocalIndexWithGhost – The index of the destination Place.

• tag – The tag of the attribute.

• elementCount – The length of the attribute (length set when adding an attribute).

Returns:

A pointer to the attribute, whether 1D or 2D.

__device__ inline void initMeta(const internal::EntityDeviceMeta *const entityMeta)

Initialize this Place instance with the pointer to the shared metadata structure on device

Parameters:

entityMeta – pointer to the shared metadata structure

__device__ inline bool removeAgent(const Agent *const agent)

Removes the specified Agent from the array of resident Agents in this place.

Parameters:

agent – The Agent to be removed.

__device__ inline void addMigratingAgent(Agent *agent)

Adds an agent to an array of agents who expressed an intention to migrate to this place. The agents which will be officially accepted for migration by a place during the Agents::manageAll() call.

Attention

This is a utility function used within the library.

Note

This function “unofficially” adds an agent to the place. It adds the agent to Place->POTENTIAL_AGENTS attribute, which will be further procesed by Place::resolveMigrationConflicts() to determine which Agent(s) will be “officially” added to the place by Place::addAgent().

Parameters:

agent – The Agent to be added.

__device__ void resolveMigrationConflicts()

The default migration conflict resolution algorithm selects the agent with the lowest index, in case several agents intend to migrate to the same place. This method can be overloaded in the derived Place class if the application requires a different conflict resolution mechanism.

We resolve conflicts by selecting the agent with the lowest index. If more than 1 Agent can reside in a place, we select the first N Agents with the lower index

__device__ inline void clearNeighbors()

Clears all neighbors of this place. Clears the neighbors, neighborOffsets, and neighborsPtr attributes.

__device__ inline void _initSpacialInfo(const Index flattenGlobalIndex, const Index32 flattenBlockIndex, const bool isGhost)

Initialize the spatial information of this Place instance, including the flattened index within the complete Places grid, the flattened index of the block on the current device, and whether this instance is within a Ghost Region.

Parameters:

• flattenGlobalIndex – the flattened index within the complete Place grid

• flattenBlockIndex – the flattened index of the block on the current device

• isGhost – whether this instance is within a Ghost Region

Protected Attributes

internal::EntityDeviceHandleStorage storage