Class Agents

Class Agents#

Class Documentation#

class Agents#

Public Functions

Count getNumAgents() const#

Returns the number of alive agents present in this agents collection.

Count getNumAgentObjects() const#

Returns the number of all agent slots present in this agents collection (some can be terminated).

EntityHandle getHandle() const#

Returns the handle associated with this Agents object that was set at construction.

std::shared_ptr<Places> getAssociatedPlaces() const#
template<typename ArgCollection, internal::type_deduction::require_contiguous_collection_of_trivial_t<ArgCollection> = 0>
void initializeInitialAgents(FunctionId functionId, const ArgCollection &args)#

Initialize the initial set of Agent instances by calling a member function on all the instances with separated argument value for each of them

Warning

This method should only be called after attributes are configured and before the simulation starts

Template Parameters:

ArgCollection – the type of the collection holding the argument values for each initial Agent instance

Parameters:

  • functionId – the id of the function to be invoked for doing the initialization

  • args – a collection of argument values, one for each initial Agent instance

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

Executes the specified function on each Agent instance within this Agents 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 id of the function to be invoked

  • argument – the argument to be passed to each Agent instance

  • 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 specified function on each Agent instance within this Agents with the provided argument.

Template Parameters:

ArgType – the type of the argument for the invoked function

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the argument value that should be passed to each Agent instance for invoking the function

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

Executes the specified function on each Agent instance within this Agents with the provided argument, where the argument is a collection of values

Template Parameters:

ArgCollection – the type of the collection holding the argument values

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the collection of argument values that should be passed to each Agent instance for invoking the function

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 specified function on each Agent instance within this Agents with the provided argument, where the argument is a collection of values

Parameters:

  • functionId – the id of the function to be invoked

  • argument – the collection of argument values that should be passed to each Agent instance for invoking the function

void callAll(FunctionId functionId)#

Executes the specified function on each Agent instance within this Agents without arguments

Parameters:

functionId – the id of the function to be invoked

void callAll(FunctionId functionId, thrust::device_ptr<void> argument)#

Executes the given functionId on each Agent element within this Agents with the provided argument. In this version, the argument should already be on the device. We will not copy the argument to the device again.

Parameters:

  • functionId – the function id passed to each Agent element

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

void manageAll()#

Executes agent termination / migration / spawning, which was initiated since the previous call to manageAll()

template<typename T>
void setAttribute(AttrTag tag, Count32 elementCount)#

Add an attribute to all the Agent 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::Agents::finalizeAttributes function to update the attributes info on the device.

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.

template<typename T>
void setAttribute(AttrTag tag, Count32 elementCount, T defaultValue)#

Add an attribute to all the Agent 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::Agents::finalizeAttributes function to update the attributes info on the device.

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.

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 Agent 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 Agent 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 Agent 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 Agent*, PtrType> unsafeGetRawStoragePtr(DeviceRank deviceRank) const#

Get the raw pointer of the contiguous storage of all the Agent 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 Agent 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 Agent instances that are not alive)

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.

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

template<typename AttributeType>
void setAttribute(const AttrTag tag, const Count32 elementCount, AttributeType defaultValue)#