Class CUDAAgent

Defined in File CUDAAgent.h

Inheritance Relationships

Base Type

public flamegpu::AgentInterface (Class AgentInterface)

Class Documentation

class CUDAAgent : public flamegpu::AgentInterface 

This is the regular CUDAAgent It provides access to the device buffers representing the states of a particular agent However it does not own these buffers, they are owned by it’s parent CUDAFatAgent, as buffers are shared with all mapped agents too.

Public Types

typedef std::map<const std::string, std::unique_ptr<jitify::experimental::KernelInstantiation>> CUDARTCFuncMap: map of agent function name to RTC function instance

typedef std::map<const std::string, std::unique_ptr<detail::curve::CurveRTCHost>> CUDARTCHeaderMap

typedef std::pair<const std::string, std::unique_ptr<jitify::experimental::KernelInstantiation>> CUDARTCFuncMapPair: Element type of CUDARTCFuncMap

Public Functions

CUDAAgent(const AgentData &description, const CUDASimulation &_cudaSimulation)

Normal constructor

Parameters

description – Agent description of the agent
_cudaSimulation – Parent CUDASimulation of the agent

CUDAAgent(const AgentData &description, const CUDASimulation &_cudaSimulation, const std::unique_ptr<CUDAAgent> &master_agent, const std::shared_ptr<SubAgentData> &mapping)

Subagent form constructor, used when creating a CUDAAgent for a mapped agent within a submodel

Parameters

description – Agent description of the agent
_cudaSimulation – Parent CUDASimulation of the agent
master_agent – The (parent) agent which this is agent is mapped to
mapping – Mapping definition for how this agent is connected with its master agent.

void mapRuntimeVariables(const AgentFunctionData &func, const unsigned int &instance_id) const

Uses the cuRVE runtime to map the variables used by the agent function to the cuRVE library so that can be accessed by name within a n agent function

Note

TODO: This could be improved by iterating the variable list within the state_list, rather than individually looking up vars (the two lists should have all the same vars)

Note

This should probably be addressed when curve is updated to not use individual memcpys

Parameters

func – The function.
instance_id – The CUDASimulation instance_id of the parent instance. This is added to the hash, to differentiate instances

void setPopulationData(const AgentVector &population, const std::string &state_name, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Copies population data from the provided host object To the device buffers held by this object (overwriting any existing agent data) Also updates population size, clears disabled agents

Note

Scatter is required for initialising submodel vars

Parameters

population – An AgentVector object with the same internal AgentData description, to provide the input data
state_name – The agent state to add the agents to
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void getPopulationData(AgentVector &population, const std::string &state_name) const

Copies population data the device buffers held by this object To the hosts object (overwriting any existing agent data)

Parameters

population – An AgentVector object with the same internal AgentData description, to receive the output data
state_name – The agent state to get the agents from

virtual unsigned int getStateSize(const std::string &state) const override

Returns the number of alive and active agents in the named state

Parameters: state – The state to return information about

unsigned int getStateAllocatedSize(const std::string &state) const

Returns the number of alive and active agents in the named state

Parameters: state – The state to return information about

virtual const AgentData &getAgentDescription() const override: Returns the Agent description which this CUDAAgent represents.

virtual void *getStateVariablePtr(const std::string &state_name, const std::string &variable_name) override: Returns the device pointer to the buffer for the associated state and variable

Note

This returns data_condition, such that the buffer does not include disabled agents

void processDeath(const AgentFunctionData &func, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Processes agent death, this call is forwarded to the fat agent All disabled agents are scattered to swap Only alive agents with deathflag are scattered

See also

CUDAFatAgent::processDeath(const unsigned int &, const std::string &, const unsigned int &)

Parameters

func – The agent function condition being processed
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void transitionState(const std::string &_src, const std::string &_dest, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Transitions all active agents from the source state to the destination state

See also

CUDAFatAgent::transitionState(const unsigned int &, const std::string &, const std::string &, const unsigned int &)

Parameters

_src – The source state
_dest – The destination state
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void processFunctionCondition(const AgentFunctionData &func, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Scatters agents based on their output of the agent function condition Agents which failed the condition are scattered to the front and marked as disabled Agents which pass the condition are scattered to after the disabled agents

See also

CUDAFatAgent::processFunctionCondition(const unsigned int &, const unsigned int &)

Note

Named state must not already contain disabled agents

Note

The disabled agents are re-enabled using clearFunctionCondition(const std::string &)

Parameters

func – The agent function being processed
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void scatterHostCreation(const std::string &state_name, const unsigned int &newSize, char *const d_inBuff, const VarOffsetStruct &offsets, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Scatters agents from the provided device buffer, this is used for host agent creation The device buffer must be packed according to the param offsets

Parameters

state_name – The state agents are scattered into
newSize – The number of new agents
d_inBuff – The device buffer containing the new agents
offsets – This defines how the memory is laid out within d_inBuff
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void scatterSort_async(const std::string &state_name, CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream)

Sorts all agent variables according to the positions stored inside Message Output scan buffer

Parameters

state_name – The state agents are scattered into
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void mapNewRuntimeVariables_async(const CUDAAgent &func_agent, const AgentFunctionData &func, unsigned int maxLen, CUDAScatter &scatter, unsigned int instance_id, cudaStream_t stream, unsigned int streamId)

Allocates a buffer for storing new agents into and uses the cuRVE runtime to map variables for use with an agent function that has device agent birth

Note

This method is async, the stream used it not synchronised

Parameters

func_agent – The Cuda agent which the agent function belongs to (required so that RTC function instances can be obtained)
func – The agent function being processed
maxLen – The maximum number of new agents (this will be the size of the agent state executing func)
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
instance_id – The CUDASimulation instance_id of the parent instance. This is added to the hash, to differentiate instances
stream – The CUDA stream used to execute the initialisation of the new agent databuffers
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers

void releaseNewBuffer(const AgentFunctionData &func)

Releases the buffer that was storing new age data

Parameters: func – The function.

void scatterNew(const AgentFunctionData &func, const unsigned int &newSize, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Scatters agents from the currently assigned device agent birth buffer (see member variable newBuffs) The device buffer must be packed in the same format as mapNewRuntimeVariables(const AgentFunctionData&, const unsigned int &, const unsigned int &)

Parameters

func – The agent function being processed
newSize – The maximum number of new agents (this will be the size of the agent state executing func)
scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void clearFunctionCondition(const std::string &state)

Reenables all disabled agents within the named state

Parameters: state – The named state to enable all agents within

void addInstantitateRTCFunction(const AgentFunctionData &func, const std::shared_ptr<EnvironmentManager> &env, const CUDAMacroEnvironment &macro_env, bool function_condition = false)

Instantiates a RTC Agent function (or agent function condition) from agent function data description containing the source.

Uses Jitify to create an instantiation of the program. Any compilation errors in the user provided agent function will be reported here.

Parameters

func – The Agent function data structure containing the src for the function
env – Object containing environment properties for the simulation instance
macro_env – Object containing environment macro properties for the simulation instance
function_condition – If true then this function will instantiate a function condition rather than an agent function

Throws

exception::InvalidAgentFunc – thrown if the user supplied agent function has compilation errors

void addInstantitateFunction(const AgentFunctionData &func, const std::shared_ptr<EnvironmentManager> &env, const CUDAMacroEnvironment &macro_env, bool function_condition = false)

Instantiates the curve instance for an (non-RTC) Agent function (or agent function condition) from agent function data description containing the source.

This performs CUDA allocations, so must be performed after CUDA device selection/context creation

Parameters

func – The Agent function data structure containing the details of the function
env – Object containing environment properties for the simulation instance
macro_env – Object containing environment macro properties for the simulation instance
function_condition – If true then this function will instantiate a function condition rather than an agent function

const jitify::experimental::KernelInstantiation &getRTCInstantiation(const std::string &function_name) const

Returns the jitify kernel instantiation of the agent function. Will throw an exception::InvalidAgentFunc excpetion if the function name does not have a valid instantiation

Parameters: function_name – the name of the RTC agent function or the agent function name suffixed with condition (if it is a function condition)

detail::curve::CurveRTCHost &getRTCHeader(const std::string &function_name) const

detail::curve::HostCurve &getCurve(const std::string &function_name) const

Returns the host interface for managing the curve instance for the named agent function

Parameters: function_name – The name of the agent’s agent function, to return the curve instance for

const CUDARTCFuncMap &getRTCFunctions() const: Returns the CUDARTCFuncMap

void initUnmappedVars(CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Resets the number of agents in any unmapped statelists to 0 They count as unmapped if they are not mapped to a master state, sub mappings will be reset

Parameters

scatter – Scatter instance and scan arrays to be used (CUDASimulation::singletons->scatter)
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void initExcludedVars(const std::string &state, const unsigned int &count, const unsigned int &offset, CUDAScatter &scatter, const unsigned int &streamId, const cudaStream_t &stream)

Initialises any agent variables within the CUDAFatAgentStateList of state which are not present in the agent-state’s CUDAAgentStateList

Parameters

state – Affected state
count – Number of variables to init
offset – Offset into the buffer of agents to init
scatter – Scatter instance and scan arrays to be used
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers
stream – CUDA stream to be used for async CUDA operations

void cullAllStates(): Resets the number of agents in every statelist to 0

void cullUnmappedStates(): Resets the number of agents in any unmapped statelists to 0 They count as unmapped if they are not mapped to a master state, sub mappings will be reset

void resizeState(const std::string &state, unsigned int minSize, bool retainData, cudaStream_t stream)

Resize the state underlying buffers This is triggered on the CUDAFatAgentStateList, so unmapped agent variables are also resized

Parameters

state – The minimum number of agents that must be representable
minSize – The minimum number of agents that must be representable
retainData – If true existing buffer data is retained
stream – The stream to be used for memcpys if data is retained

void setStateAgentCount(const std::string &state, const unsigned int &newSize)

Updates the number of alive agents, does not affect disabled agents or change agent data

Parameters

state – The state to affect
newSize – Number of active agents

Throws

exception::InvalidMemoryCapacity – If the new number of disabled + active agents would exceed currently allocated buffer capacity

std::list<std::shared_ptr<VariableBuffer>> getUnboundVariableBuffers(const std::string &state)

Returns a list of variable buffers attached to bound agents, not available in this agent

Note

This access is only intended for DeviceAgentVector’s correctly handling of subagents

Parameters: state – The state affected state

virtual id_t nextID(unsigned int count = 1) override

Returns the next free agent id, and increments the ID tracker by the specified count

Parameters: count – Number that will be added to the return value on next call to this function
Returns: An ID that can be assigned to an agent that wil be stored within this CUDAAgent’s CUDAFatAgent

id_t *getDeviceNextID(): Returns a device pointer to the value returns by nextID(0) If the device value is changed, then the internal ID counter must be updated via CUDAAgent::scatterNew()

void assignIDs(HostAPI &hostapi, CUDAScatter &scatter, cudaStream_t stream, unsigned int streamId)

Assigns IDs to any agents who’s ID has the value ID_NOT_SET

Parameters

hostapi – HostAPI object, this is used to provide cub temp storage
scatter – Scatter instance and scan arrays to be used
stream – The CUDAStream to use for CUDA operations
streamId – The stream index to use for accessing stream specific resources such as scan compaction arrays and buffers

virtual void setPopulationVec(const std::string &state_name, const std::shared_ptr<DeviceAgentVector_impl> &d_vec)

Used to allow HostAgentAPI to store a persistent DeviceAgentVector

Parameters

state_name – Agent state to affect
d_vec – The DeviceAgentVector to be stored

virtual std::shared_ptr<DeviceAgentVector_impl> getPopulationVec(const std::string &state_name)

Used to allow HostAgentAPI to retrieve a stored DeviceAgentVector

Parameters: state_name – Agent state to affect

virtual void resetPopulationVecs(): Used to allow HostAgentAPI to clear the stored DeviceAgentVector Any changes will be synchronised first

Friends

friend class visualiser::AgentVis