Class HostAgentAPI

Class Documentation

class flamegpu::HostAgentAPI

Collection of HostAPI functions related to agents

Mostly provides access to reductions over agent variables

Public Types

enum Order

Sort ordering Ascending or Descending

Values:

enumerator Asc
enumerator Desc

Public Functions

inline HostAgentAPI(HostAPI &_api, AgentInterface &_agent, const std::string &_stateName, const VarOffsetStruct &_agentOffsets, HostAPI::AgentDataBuffer &_newAgentData)

Construct a new HostAgentAPI instance for a specified agent type and state

Parameters
  • _api – Parent HostAPI instance

  • _agent – Agent object holding the agent data

  • _stateName – Name of the agent state to be represented

  • _agentOffsets – Layout of memory within the Host Agent Birth data structure (_newAgentData)

  • _newAgentData – Structure containing agents birthed via Host Agent Birth

~HostAgentAPI()

Destructor

Ensures any changes to agent data or births are synchronised prior to the host function returning.

inline HostAgentAPI(const HostAgentAPI &other)

Copy constructor Not actually sure this is required

HostNewAgentAPI newAgent()

Creates a new agent in the current agent and returns an object for configuring it’s member variables

This mode of agent creation is more efficient than manipulating the vector returned by getPopulationData(), as it batches agent creation to a single scatter kernel if possible (e.g. no data dependencies).

unsigned int count()
template<typename InT>
InT sum(const std::string &variable) const

Wraps cub::DeviceReduce::Sum()

Parameters

variable – The agent variable to perform the sum reduction across

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT, typename OutT>
OutT sum(const std::string &variable) const

Wraps cub::DeviceReduce::Sum()

Parameters

variable – The agent variable to perform the sum reduction across

Template Parameters
  • OutT – The template arg, ‘OutT’ can be used if the sum is expected to exceed the representation of the type being summed

  • InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT>
InT min(const std::string &variable) const

Wraps cub::DeviceReduce::Min()

Parameters

variable – The agent variable to perform the lowerBound reduction across

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT>
InT max(const std::string &variable) const

Wraps cub::DeviceReduce::Max()

Parameters

variable – The agent variable to perform the upperBound reduction across

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT>
unsigned int count(const std::string &variable, const InT &value)

Wraps thrust::count(), to count the number of occurences of the provided value

Parameters
  • variable – The agent variable to perform the count reduction across

  • value – The value to count occurences of

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT>
std::vector<unsigned int> histogramEven(const std::string &variable, const unsigned int &histogramBins, const InT &lowerBound, const InT &upperBound) const

Wraps cub::DeviceHistogram::HistogramEven()

Note

2nd template arg can be used if calculation requires higher bit type to avoid overflow

Parameters
  • variable – The agent variable to perform the reduction across

  • histogramBins – The number of bins the histogram should have

  • lowerBound – The (inclusive) lower sample value boundary of lowest bin

  • upperBound – The (exclusive) upper sample value boundary of upper bin

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT, typename OutT>
std::vector<OutT> histogramEven(const std::string &variable, const unsigned int &histogramBins, const InT &lowerBound, const InT &upperBound) const
template<typename InT, typename reductionOperatorT>
InT reduce(const std::string &variable, reductionOperatorT reductionOperator, const InT &init) const

Wraps cub::DeviceReduce::Reduce(), to perform a reduction with a custom operator

Parameters
  • variable – The agent variable to perform the reduction across

  • reductionOperator – The custom reduction function

  • init – Initial value of the reduction

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename InT, typename OutT, typename transformOperatorT, typename reductionOperatorT>
OutT transformReduce(const std::string &variable, transformOperatorT transformOperator, reductionOperatorT reductionOperator, const OutT &init) const

Wraps thrust::transformReduce(), to perform a custom transform on values before performing a custom reduction

Parameters
  • variable – The agent variable to perform the reduction across

  • transformOperator – The custom unary transform function

  • reductionOperator – The custom binary reduction function

  • init – Initial value of the reduction

Template Parameters

InT – The type of the variable as specified in the model description hierarchy

Throws
template<typename VarT>
void sort(const std::string &variable, Order order, int beginBit = 0, int endBit = sizeof(VarT) * 8)

Sorts agents according to the named variable

Note

An optional bit subrange [begin_bit, end_bit) of differentiating variable bits can be specified. This can reduce overall sorting overhead and yield a corresponding performance improvement.

Note

The sort provides no guarantee of stability

Parameters
  • variable – The agent variable to sort the agents according to

  • order – Whether the agents should be sorted in ascending or descending order of the variable

  • beginBit – Advanced Option, see note

  • endBit – Advanced Option, see note

Template Parameters

VarT – The type of the variable as specified in the model description hierarchy

Throws
template<typename Var1T, typename Var2T>
void sort(const std::string &variable1, Order order1, const std::string &variable2, Order order2)

Sort agents according to two variables e.g. [1:c, 3:b, 1:b, 1:a] -> [1:a, 1:b, 1:c, 3:b]

Parameters
  • variable1 – This variable will be the main direction that agents are sorted

  • order1 – The order that variable 1 should be sorted according to

  • variable2 – Agents with equal variable1’s, will be sorted according this this variable

  • order2 – The order that variable 2 should be sorted according to

Throws
Template Parameters
  • Var1T – The type of variable1 as specified in the model description hierarchy

  • Var2T – The type of variable2 as specified in the model description hierarchy

DeviceAgentVector getPopulationData()

Downloads the current agent state from device into an AgentVector which is returned

This function is considered expensive, as it triggers a high number of host-device memory transfers. It should be used as a last resort