Creating agent(s) from agent functions.

What we have for memory vectors is actually an heterogeneous vector where every vector can store different types. Each element has type details stored with it. What we actually need is a hetrogeneous collection of homogenous vectors. This will require a special templated vector which stores the type info once. This is currently preventing the implementation of the GPU memory mapping.

Type check is required for below functions :
template<typename T, unsigned int N> __device__ T FLAMEGPU_API::getVariable(const char(&variable_name)[N]);
and
template<typename T, unsigned int N> __device__ void FLAMEGPU_API::setVariable(const char(&variable_name)[N], T value)

Provide a hello-world esque example which can be used with some script(s) to create a new example.

Possibly implement with a function pointer. This will make dependency analysis for concurrency checking more difficult.

http://docs.flamegpu.com/en/master/flamegpu/modelspec.html?highlight=global%20function#function-conditions

Perhaps for milestone 2 after first alpha release.

Implement the Circles model. In flame gpu 1 we have the following 4 versions:

• CirclesBruteForce_double
• CirclesBruteForce_float
• CirclesPartitioning_double
• CirclesPartitioning_float

Hi,

How many agents are you expecting to be able to run on the same simulation? In 2010 FLAME was designed for 10^6 agents ([http://www.ifaamas.org/Proceedings/aamas2010/pdf/04%20Demos/D-10.pdf]). Are you expecting to run more?

Regards,
Ezequiel

In FLAMEGPU2 we are allowed to add multiple functions to the same simulation layer. We need to check if these functions belong to the same agent or not. Are these functions independent of each other?

    SimulationLayer moveStay_layer(simulation, "move_layer");
    moveStay_layer.addAgentFunction("move");
    moveStay_layer.addAgentFunction("stay");
    simulation.addSimulationLayer(moveStay_layer);

Read (potentially modified) agent data on the host in init/exit/step functions.

I have added todo items in the code. Currently one of the tests fails but should not. Additional tests need adding.

We can reduce the number of exceptions by adding more detail in the error string

Example model demonstrating the use of analytics functions

Implement the Boids example model.

FLAME GPU 1 provides 3 versions:

• Boids_BruteForce
• Boids_Partitioning
• Boids_PartitioningVecTypes

We also need to address behaviour at the edge of the simualted region.

Traditionally F1 used wrapping, but agents did not interact with agents at the other end of continuous space.

Options could be:

• Implement message wrapping
  • as a spatial message spetialisation?
  • Add an easy way for distance checks, which ideally could be applied to wrapped brute force comms too?
• Bouncing?
  • Agents currently clamp within the bounds, but no changes are made to the force (so they continue to attempt to leave). Implementing bouncing (or nullifying their outwards movement) is a possible solution. Unsure what the general consensus is for boids implementations / in the literature.

Use curand for random number generation in agent functions when requested.

Should be seedable from the host.

http://docs.flamegpu.com/en/master/flamegpu/modelspec.html?highlight=global%20function#global-function-conditions

Implement host functions which automatically run at the correct point in the simulation.

• Init
• Step
• Exit

Currently a number of std:exceptions are in the code and need replacing.

Can now use pushBackInstance or getInstance

It may be worth using a linter such as cpplint to adhere to some code style rules, which can be factored in as a CI phase to enforce usage.

cpplint seems sensible as it supports cuda and is readily installable via pip. It can also be configured to suppress rules we do not wish to adhere to if required.

Death of agents from device agent functions.

1. Abstract State Reader Class
2. Concrete XML Reader
3. Concrete Binary Reader

Readers need to support reading of

• Agent populations
• Environment

Implement common analytics functions to be called from the host using cub. Including atleast the following

• min
• max
• reduce
• count

Host functions as a part of layers.

Ideally these should be able to execute concurrently with agent functions in the same layer, though this would have to be clearly documented.

Not an urgent feature, complicates dependency analysis

Implement the GameOfLife example model. This may require discrete agents, or at least be a demonstration of implementing a discrete model with FLAME GPU 2

Possibly false positive. Needs checking in valgrind.

Add instrumentation tools for simple performance analysis, along with NVTX based markers for more advanced profiling. Introduce a profile build configuration which enables this

• Instrumentation
  • --timing flag for simple timing
  • Make timing values programatically accessible, rather than just output to stdout? This would need to be recorded regardless of the presence of --timing
  • Simulation timing
  • Pre/Post Simulation timing (for transparency).
  • Timing per Iteration - there will be variance in some iterations due to buffer growth etc.
  • Timing per layer (per agent function not viable if concurrency is enabled)
• NVTX
  • NVTX linked
  • NVTX utiltiity class (include/util/nvtx.h)
  • Tests (not sure how) - not programatically testable?
  • Doxygen docs (guarded by macros)
  • Better NVTX ranges (probably during #379).
    • Include a range for the call to simulate
    • Ideally capture Agent population generation - may have to go in the indiviudal model, or as part of #246
• Output simulation/ensemble information to disk, (potentially/optionally) including timing info (total, per step etc?), population data, GPU executed on, Driver version, CUDA version, FLAMEGPU version, user-provided model verisoning? etc.

For Cmake, enabling NVTX could be handeld something along the lines of:
(but maybe just for the profile target, and make it so that if NVTX is not found it builds without)

# Switch to enable NVTX ranges for profiling
option(USE_NVTX "Build with NVTX" ON)
if(USE_NVTX)
  message("-- Using NVTX")
  find_library(NVTX_LIBRARY nvToolsExt HINTS /usr/local/cuda/lib64)
  target_link_libraries(flamegpu2 ${NVTX_LIBRARY})
  set(CUDA_NVCC_FLAGS  ${CUDA_NVCC_FLAGS}; -DUSE_NVTX)
endif(USE_NVTX)

Hi,

According to my understanding the agents of a simulation run must be specified individually in the XML file under the "iterations" directory. Is there a way to automatically generate agents within the code itself instead of manually specifying the agents, individually?

Thank you!
Chathika

• Check agent population name
• Check setting and getting variable functions
  • the variable type is correct?
  • accessing a wrong variable
• maximum population size
• accessing agents more than population size
• access population data with multiple states for the same agent
• accessing agent population that is not set

Example model demonstrating the creation of agents from init / step functions.

• Data copied back from device without simulating any function
• Data copied back from device after simulating a function
• Data copied back from device after simulating functions concurrently (this is to test CUDA streams)
• check function pointer signature

1. Abstract State Writer Class
2. Concrete XML Writer
3. Concrete Binary Writer

Readers need to support reading of

• Agent populations
• Environment

Currently, the mapRuntimeVariables function, does the mapping for all the variables. It's been agreed to modify this later, so we only map the variables that are used within a function during the simulation.

We should observe the following rules when using includes

1. Only include what is absolutely required with a header! Includes in source are fine.
2. For each folder their should be a hierarchy of dependencies for includes. I.e. ModelDescription should include AgentDescription, AgentDescription should include StateDescription and FunctionDescription. For dependencies the other way forward declarations should be used to avoid circular dependencies. This ensures that to use all the model classes only the top level class ModelDEscritpion needs to be improted by a user.
3. Each class "should" be able to be built in a new project by including the header in a main source file. If it does not build then the dependencies are wrong.

This is not the case in examples like caffe....

A suggestion: assign a DOI to the repo to be able to cite it in papers.
https://guides.github.com/activities/citable-code/

Doxygen template - header file:

#ifndef CLASSNAME_H
#define CLASSNAME_H

// TODO_add_include_files


/**
 * @file
 * @author  TODO_name, TODO_organization
 * @date    TODO_dd_mmm_yyyy  
 * @brief TODO_one_line_description_of_class.
 *
 * TODO_longer_description_of_class_meant_for_users._Developer_details_should_
 * be_put_in_the_.cpp_implementation
 * 
 * \todo
 */

class ClassName { 
    public:
        /** TODO_describe_ctor. */
        ClassName();
        /** TODO_describe_dtor. */
        virtual ~ClassName();

        /** TODO_describe_accessor.
         * @return TODO_describe_return value. */
        int getSomeMember() const { return m_someMember; }
        /** TODO_describe_mutator.
         * @param someMember TODO_describe_input_param. */
        void setSomeMember(int someMember) { m_someMember = someMember; }

    protected:
        /**
         * TODO_description_of_function.
         * @param someParam TODO_describe_parameter.
         * @return TODO_describe_return_value.
         */
        virtual int someFunction(int someParam);

    private:
       int m_someMember;   // TODO_purpose_and_units.
}; 

#endif // CLASSNAME_H

Doxygen template - cpp file:

/******************************************************************************
 * 
 ****************************************************************************** 
 * Author  TODO_name, TODO_organization
 * Date    TODO_dd_mmm_yyyy
 *
 * See <CLASS_NAME>.h for a description of this code 
 *****************************************************************************/


// TODO_add_include_files
#include "CppTemplate.h"


ClassName::ClassName() {
    // TODO_implement
}

ClassName::~ClassName() {
    // TODO_implement
}

// TODO_describe_implemetation_details_for_developers
int ClassName::someFunction(int someParam) {
    // TODO_implement
    return 0;
}

Taken from https://modelingguru.nasa.gov/docs/DOC-1684

• Check the agent name and size
• Check agent variable type, number
• Check function and message names
• Check if a specific function exists

CUDA Boost test is not supported in VS when compiled with NVCC. No problem occurs when compiled on Ubuntu using the command line.

Provide functionality to sort agents if requested in an init/step/exit function

See http://docs.flamegpu.com/en/master/flamegpu/api.html#sorting-agents

Used by PedestrianLOD example, see PedestrianPopulation.cu:generate_agent_keyvalue_pairs and PedestrianPopulation.cu:generate_instances_and_LOD

• Verify the correction of simulation functions by printing a 'hello' only
• Check if the function name exists by throwing an exception
  • checking the number of layers and functions per layers
• access to the same variable by 2 functions from the same agent should not be possible

If nvcc is already on the path then it only be overwritten if CUDA_PATH is defined.