Class CUDAAgent

Inheritance Relationships

Base Type

Class Documentation

class CUDAAgent : public flamegpu::detail::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::shared_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, 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, detail::CUDAScatter &scatter, unsigned int streamId, 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

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

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

Parameters:

state – The state to return information about

virtual CAgentDescription 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, detail::CUDAScatter &scatter, unsigned int streamId, 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(unsigned int, const std::string &, 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, detail::CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream)

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

See also

CUDAFatAgent::transitionState(unsigned int, const std::string &, const std::string &, 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, detail::CUDAScatter &scatter, unsigned int streamId, 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(unsigned int, 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, unsigned int newSize, char *const d_inBuff, const VarOffsetStruct &offsets, detail::CUDAScatter &scatter, unsigned int streamId, 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, detail::CUDAScatter &scatter, unsigned int streamId, cudaStream_t stream)

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

See also

HostAgentAPI::sort(const std::string &, HostAgentAPI::Order, int, int)

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, detail::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, unsigned int newSize, detail::CUDAScatter &scatter, unsigned int streamId, 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&, unsigned int, 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, std::shared_ptr<const detail::CUDAMacroEnvironment> macro_env, const std::unordered_map<std::string, std::shared_ptr<CUDAEnvironmentDirectedGraphBuffers>> &directed_graphs, 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

  • directed_graphs – Map of directed graphs 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, std::shared_ptr<const detail::CUDAMacroEnvironment> macro_env, const std::unordered_map<std::string, std::shared_ptr<CUDAEnvironmentDirectedGraphBuffers>> &directed_graphs, 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

  • directed_graphs – Map of directed graphs 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, unsigned int streamId, 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, unsigned int count, unsigned int offset, CUDAScatter &scatter, unsigned int streamId, 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, 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 struct visualiser::AgentVisData