Class HostAgentAPI

Class Documentation

class HostAgentAPI

Public Types

enum Order

Values:

enumerator Asc
enumerator Desc

Public Functions

inline HostAgentAPI(HostAPI &_api, AgentInterface &_agent, const std::string &_stateName, const VarOffsetStruct &_agentOffsets, HostAPI::AgentDataBuffer &_newAgentData)
~HostAgentAPI()
inline HostAgentAPI(const HostAgentAPI &other)
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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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
  • UnsupportedVarType – Array variables are not supported

  • InvalidAgentVar – If the agent does not contain a variable of the same name

  • InvalidVarType – If the passed variable type does not match that specified in the model description hierarchy

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