Class HostAgentAPI

Class Documentation

class 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, detail::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

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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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:

  • exception::UnsupportedVarType – Array variables are not supported

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

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

template<typename InT>
std::pair<double, double> meanStandardDeviation(const std::string &variable) const

Returns the mean and standard deviation of the specified variable in the agent population The return value is a pair, where the first item holds the mean and the second item the standard deviation.

Note

If you only require the mean, it is more efficient to use sum()/count()

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:

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

  • exception::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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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, InT value) const

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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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, unsigned int histogramBins, InT lowerBound, 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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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, unsigned int histogramBins, InT lowerBound, InT upperBound) const
template<typename InT, typename reductionOperatorT>
InT reduce(const std::string &variable, reductionOperatorT reductionOperator, 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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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, 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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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:

  • exception::UnsupportedVarType – Array variables are not supported

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

  • exception::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