FLAME GPU Technical Report and User Guide
Contents
1. 1 1 High Level Overview of FLAME GPU Technically the FLAME GPU framework is not a simulator it is instead a template based simulation environment that maps formal descriptions of agents into simulation code The representation of an agent is based on the concept of a communicating X Machine which is an extension to the Finite State Machine which includes memory Whilst the X Machine has very formal definition X M achine agents can be thought of a state machines which are able to communicate via messages which are stored in a globally accessible message lists Agent functionality is exposed as a set of state transition functions which move agents from one internal state to another Upon changing state agents update their internal memory through the influence of messages which may be either used as input by iterating message lists or as output where information may be passed to the message lists for other agents to read FLAME GPU uses agent function scripting for this purpose where script is defined in a number of Agent Function Files Simulation models are specified using a format called X Machine Mark up Language XM M L which is XML syntax with Schemas governing the content A typically XM M L model file consists of a definition of a number of X Machine agents including state and memory information as well as a set of agent transition functions a number of message types each of which has a globally accessible message list and a set of sim2. float avg x avg y agv z Get the first location messages xmachine message location location message message get first location message location messages partition matrix xmemory x xmemory y xmemory z Loop through the messages while message if in range message xmemory if message gt id xmemory id avg x message gt x avg y message gt y avg z message gt z countt Move onto next location message message get_next_location_message message location_messages partition matrix if count avg_x count avg_y count avg_z count xmemory gt x avg x SMALL NUMBER xmemory y avg y SMALL NUMBER xmemory gt z avg z SMALL NUMBER return 0 35 3 Discrete Partitioned Message Iteration For discretely partitioned messages the dynamically generated message API functions differ from those of non partitioned only in that two additional parameters must be passed to the get first message API function The two integer arguments represent the position which the agent would like to read messages from within the cellular environment as with spatially partitioning this is usually the agent position These values of these arguments must therefore be within the width and height of the message space itself the square of the messages buf ferSi ze In addition to the additional arguments the discrete message API functions also
3. xmachine memory agent name list output agents xmachine message message name list input messages xmachine message message name PBM input message PBM xmachine message message name list output messages RNG rand48 rand48 3 9 Setting Simulation Constants Global Variables Simulation constants defined within the environment section of the XM M L model definition may be directly referenced within an agent function using the name specified within the variable definition see section 2 2 1 It is not possible to set constant variables within an agent function however the simulation API creates methods for setting simulation constants which may be called either at the start of the simulation either manually or within an initialisation function or between simulation iterations for example as part of an interactive visualisation The code below demonstrates the function prototype for setting a simulation constant with the name A CONSTANT extern C void set A CONSTANT float h A CONSTANT The function is declared using the extern keyword which allows it to be linked to by externally compiled code such as a visualisation or custom simulation loop 18 FLAM E GPU Technical Report and User Guide 3 9 1 Initialisation Functions Any initialisation functions defined within the XM M L model file see section 2 2 3 are expected to be declared within an agent function code file and will automatically be called before the first
4. 0 The description element arrayLength element and defaultValue element are all optional The below code shows the specification of two constant variables the first represents a single int constant with a default value of 1 the second indicates an int array of length 5 Details on how to set constant variables is described in section 3 9 lt gpu constants gt lt gpu variable gt lt type gt int lt type gt lt name gt const_variable lt name gt lt description gt none lt description gt lt defaultValue gt 1 lt defaultValue gt FLAM E GPU Technical Report and User Guide lt gpu variable gt lt gpu variable gt lt type gt int lt type gt lt name gt const_array_variable lt name gt lt description gt none lt description gt lt arrayLength gt 5 lt arrayLength gt lt gpu variable gt lt gpu constants gt 222 Function Files The functionFiles element is not optional and must contain a single file element which defines the name of a source code file which holds the scripted agent functions More details on the format of the function file are given in Chapter 3 The example below shows the correct XM L format for a function file named functions c lt gpu functionFiles gt lt file gt functions c lt file gt gpu functionFiles 22 3 Initialisation Functions Initialisation functions are user defined functions which can be used to set constant global variables Any initialisation functions defined within the
5. agent which is in the correct start state and meets any of the defined function conditions Agent function scripts are defined using a simple C based syntax with the agent function declarations and more specifically the function arguments dependant on the XMML function definition The use of message input and output as well as random number generation will all change the function arguments in a way which is described within this section Likewise the simulation API functions for message communication are dependent on the definition of the simulation model contained with the XM M L model definition A single C source file is required to hold all agent function declarations and must contain an include directive for the file header h which contains model specific agent and message structures Agent functions are free to use many features of common C syntax with the following important exceptions e Globally Defined Variables i e Variables declared outside of any function scope Are not permitted and should instead be defined as global variables within the XM M L model file and used as described in section 2 2 1 Note The use of pre processor macro directives for constants is supported and can be freely used without restriction 12 FLAM E GPU Technical Report and User Guide e Include Directives Are permitted however as agent functions are functions which are run on the GPU during simulation they may not call non GPU code This implies that includ
6. and Options FLAM E GPU simulations require a number of arguments depending on either console or visualisation mode Both are described in the following subsections 4 5 1 Console Mode Simulation executables built for console execution require two arguments usage shown below The first of which is a file location for an initial agent XML file containing the initial agent data The second argument is the number of simulation iterations which should be processed A number of optional CUDA arguments may also be passed i e device 1 to specify the second CUDA enabled GPU device within the host machine should be used for simulation if required FLAMEGPU_simulation exe XML model data Iterations Optional CUDA arguments The result of running the simulation will be a number of output XML files which will be numbered from 1 to n where n is the number of simulations specified by the iterations argument It is possible to turn XML output on or off by changing the definition of the OUTPUT_TO_XML macro located within the main xsit template to true 1 false 0 22 FLAM E GPU Technical Report and User Guide 4 5 2 Visualisation Mode Simulation executables built for visualisation require only a single argument usage shown below which is the same as the first argument for with console execution an initial agent XML file The number of simulations iterations is not required as the simulation will run indefinitely until the visualisation is close
7. in either a 3D environment i e agents with x y and z variables A spatially partitioned message scheme requires the specification of both a radius and a set of environment bounds The radius represents the range in which message iteration will extend to from its originating point The environment bounds represent the size of the space which massages may exist within If a message falls outside of the environment bounds then it will be bound to the nearest possible location within it The space within the defined bounds is partitioned according to the radius with a total of P partitions in each dimension where for each dimension P ceiling max bound min bound radius The partitions dimensions are then used to construct a partition boundary matrix an example of use within message iteration is provided in section 3 5 2 which holds the indices of messages within each area of partitioned space Spatially partitioned message iteration can then iterate a varying number of messages from a fixed number of adjacent partitions in partition space to ensure each message within the specified radius has been considered The following example defines a spatial partition in three dimensions For continuously spaced agents in 2D space P should be equal to 1 and therefore a zmin of 0 would require a zmax value equal to radius even in this case a message variable With name z is still required FLAM E GPU Technical Report and User Guide lt gpu partiti
8. init Functions element are called a single time by the automatically generated simulation code in the order that they appear during the initialisation of the simulation If an initFunctions element is specified there must be at least a single initFunction child element with a unique name Section 3 9 1 demonstrates how to specify initialisation functions within a function file lt qpu initFunctions gt lt Qpu initFunction gt lt gpu name gt initConstants lt gpu name gt lt gpu initFunction gt lt gpu initFunctions gt 2 3 Defining an X Machine Agent A XMML model file must contain a single xagents element which in turn must define at least a single xagent An xagent is an agent representation of an X Machine and consists of a name optional description an internal memory set M in the formal definition a set of agent functions or next state partial functions F in the formal definition and a set of states Q in the formal definition In addition to this FLAM EGPU requires two additional pieces of information which are not required in the original XM ML specification at ype and a bufferSize The type element refers to the type of agent with respect to its relation with its spatial environment An agent type can be either discrete Or continuous discrete agents occupy non mobile 2D discrete spatial partitions cellular automaton where as cont inuous agents are assumed to occupy a continuous Space environment although in reality they
9. lt agentVariable gt lhs operator amp lt operator lt rhs gt lt condition gt Ine agentVariable variable name2 agentVariable lt 7 Lhs gt lt operator gt lt operator gt pb alor lt value gt 1 lt value gt lt rhs gt lt condition gt lt 7 vhs lt condition gt In the above example the function condition generates the following pseudo code function guard variable name lt variable_name2 1 The condition element may refer to any logical operator Care must be taken when using angled brackets which in standard form will cause the XML syntax to become invalid Rather than the left hand bracket less than the correct xml syntax of lt should be used Likewise the right hand bracket greater than should be replaced with sgt 2 5 5 Global Function Conditions An agent global function condition is similar to an agent function in its syntax however it acts as a global switch to determine if the function should be applied to either all or none of the agents within the correct state specified by currentState In the case of every agent evaluating the global function condition to true or to the value specified by the must EvaluateTo element the agent function is applied to all of the agents In the case that any of the agents evaluate the global function condition to false or to the logical opposite of the value specified by the mustEvaluateTo element then the agent function will be appl
10. name likewise each message defines a structure with the name xmachine message message name ln both cases the structures contain a number of private variables prefixed with an underscore which are used by the API functions and should not be modified directly In addition to this the simulation API defines structures of arrays to hold agent and message list information Agent lists are named xmachine memory agent name list and message lists are named xmachine message message name list These lists are passed as arguments to agent functions and should only be used in conjunction with the simulation API functions for message iteration and the adding of messages and agents List structures should never be accessed directly as doing so will produce undefined behaviour 3 3 ABasic Agent Function Updating and Agents Memory The following example shows a simplistic agent function named unction1 which has no message input or output and only updates the agents internal memory All FLAME GPU agent functions are first prefixed with the macro definition FLAME GPU FUNC In this basic example the agent function has only a single argument a pointer to an agent structure of type xmachine memory myAgent Called xmemory In the below example the agent name is myAgent and the agent memory contains two variables x and no movements of type 1oat and int respectively The return type of FLAME GPU functions is always int A return value of anything ot
11. which replaces the dynamically generated visualisation source file The physical folders of the SDK structure a self explanatory however it is worth noting that executable files generated by the Visual Studio build processes are output in the SDKs bin folder which also contains the CUDA run time dlls 4 4 3 Build Processes The Visual Studio build process consists of a number of stages which call various tools compilers and linkers The first of these is the FLAME GPU build tool described in more detail in the following section which generates the dynamic simulation code from the FLAM E GPU templates and mode file Following this the simulation code within the Dynamic Code folder is built using the CUDA build rule which compiles the source files using NVIDIAs nvcc CUDA compiler Finally any C or C source files are compiled using M SVC compiler and are then linked with the CUDA object files to produce the executable To start the build processes select the Build menu followed by Build Solution or use the F7 hotkey If the first build step in the Visual Studio skips the FLAM E GPU build tool a complete rebuilt can be forced by selecting the Build menu followed by Rebuild Solution or Ctrl Alt F7 4 4 4 FLAME GPU Build Rule Options The FLAME GPU build rule is configured by selecting the XM ML model file properties Within the Build rue the XSLT options tab Figure 2 allows individual template file transformations to be toggled on or
12. with no shared message input or output layers layer gpu layerFunction lt name gt functionl lt name gt gpu layerFunction lt gpu layerFunction gt name function2 name gpu layerFunction layer layer gpu layerFunction name function3 name gpu layerFunction layer lt layers gt 2 7 Initial XML Agent Data The initial agent data information is stored in an XML file which is used passed to the simulator as a parameter before running the simulation Within this initial agent data XML file a single states element contains a single iteration number itno and any number including 0 of xagent elements The syntax of the xagent element depends on the agent definitions contained within the XMML model definition file A name element is always required and must represent an agent name contained within a xgents gpu agent name element in the XM ML model definition Following 11 FLAM E GPU Technical Report and User Guide this an element may exist for each of the named agents memory variables xagents gpu agent memory gpu variable name Each named element is then expected to contain a value of the same t ype as the agent memory variable defined If the initial agent data XM L file neglects to specify the value of a variable defined within an agents memory then the value is assumed to be zero If an element defines a variable name which does not exist within the XMML model definition then
13. D should be used or continuous where a parameter value of CONTINUOUS should be used spaced agents If a template parameter value is not specified then the simulation will assume a DISCRETE_2D value which will work in either case but is more computationally expensive The API function has a single argument a pointer to a RNG rand48 structure which contains random seeds and is passed to agent functions which specify a true value for the RNG element in the XMML function definition The example below shows a simple agent function with no input or outputs demonstrating the random number generation to determine if the agent should die m define DEATH RATE 0 1f FLAME GPU FUNC int kill agent xmachine memory myAgent agent RNG rand48 rand48 float random int die die 0 agent does not die random rnd lt CONTINUOUS gt rand48 if random lt DEATH_RATE die 1 agent dies return die 3 8 Summary of Agent Function Arguments Agent functions may use any combination of message input output agent output and random number generation resulting in a large number of agent function arguments which are expected to be in a specific and pre defined order The following pseudo code demonstrates the order of a function containing all possible arguments When specifying an agent function declaration this order must be observed FLAME GPU FUNC int function xmachine memory agent name agent
14. FLAM E GPU Technical Report and User Guide 1 Introduction Agent Based Modelling ABM is a technique for the computational simulation of complex interacting systems through the specification of the behaviour of a number of autonomous individuals acting simultaneously This is a bottom up approach in contrast with the top down one of modelling the behaviour of the whole system through dynamic mathematical equations The focus on individuals is considerably more computationally demanding but provides a natural and flexible environment for studying systems demonstrating emergent behaviour Despite the obvious parallelism traditionally frameworks for ABM fail to exploit this and are often based on highly serialised algorithms for manipulating mobile discrete agents Such an approach has serious implications placing stringent limitations on both the scale of models and the speed at which they may be simulated The purpose of the Flexible Large Scale Agent Modelling Environment FLAM E framework is to address the limitations of previous agent modelling software by targeting the high performance Graphics Processing Unit GPU architecture The FLAME GPU framework is designed with parallelism in mind and as such allows agent models to scale to massive sizes and ensures simulations run within reasonable time constrains In addition to this visualisation is easily achievable as simulation data is held entirely within GPU memory where it can be rendered directly
15. FLAM E GPU Technical Report and User Guide simulation source files The template also generates function prototypes for simulation functions and functions which are visible externally within custom C or C code e main xslt This template file generates a source file which defines the main execution entry point function which is responsible for handling command line options and initialising the GPU device e io xslt This template file generates a source file which contains functions for loading initial agent XML data files see section 2 7 into the simulation and saving the simulation state back into XM L format e simulation xslt This template file generates a source file containing the host side simulation code which includes loading data to and from the GPU device and making a number of CUDA kernel calls which perform the simulation process e FLAMEGPU kernels xslt This template file generates a CUDA header file which contains the CUDA kernels and device functions which make up the simulation e visualisation xslt This template file generates a source file which will allow basic visualisation of the simulation using sphere based representation of agents in 3D space The source file is responsible for CUDA OpenGL interoperability and rending using OpenGL The source file includes a visualisation h file containing a number of definitions and variables which is not generated by any templates and should be specified manually 4 4 Co
16. FLAME GPU Technical Report and User Guide Document Version 1 0 For FLAME GPU 1 0 4 Dr Paul Richmond Research Associate Department of Automatic Control and Systems Engineering ACSE Member of the Computer Graphics Group Department of Computer Science The University of Sheffield P Richmond Sheffield ac uk www paulrichmond staff shef ac uk www flamegpu com Document Contents I Jntrod ctiof usos iui ca sarieestesahcicdecenisabiaiticadnscaaahisaniiiteceisstaniiasahenenne k 1 1 High Level Overview of FLAME GPUs anon amor eden nme ae mie bens 1 12 Phurposeor This Document sso utin aset tan Cd ed ance pt Cu Cu eui eum dn 2 2 FLAMEGPU Model Specification eene 3 23 JUnbFoQuctloliss mese lac raat Rate aussen hs ate San ha erm MA Mad atu di m A ITE 3 2 2 ihe Environment nes reed oet ettet ates MEAE rR te ee nae rm ER 3 2 2 1 Simulation Constants Global Variables ehe erbe daots 3 2 2 2 Function Files Mo RHEINE NE ERE E WEE 4 2 2 3 IrittralisablO TW PUTICEOR Soon bo om rreb eee eth ei esp a eh tre bre tbt o m n ii bei rerit 4 2 3 Defining an X Machine Bib ssp iach datu va addo ota ue RR RAS d 4 2 3 1 Xena qe shan stasateonnstoned niiae t E o Me has Danadhaashaatiaaseonntoond Gale 5 2 3 2 Agent SALES rr M m 5 24 Defining Messages soe otc ete eL e t 6 2 4 1 pulses Sus ar e 6 2 4 2 Non partitioned MasSqugs usiuisotisibtis ntur aee edant lees md Y DR ee Pu es eve redo 7 2 4 3 Discrete Partitioned M
17. GPU Modelling and Simulation Processes 1 2 Purpose of This Document The purpose of this document is to describe the functional parts which make up a FLAME GPU simulation as well as providing guidance on how to use the FLAME GPU SDK Chapter 2 describes in detail the syntax and format of the XM M L Model file Chapter 3 describes the syntax of use of agent function scripts and how to use the dynamic simulation API and Chapter 4 describes how to generate simulation code and run simulations from within the Visual Studio IDE This document does not act as a review of background material relating to GPU agent modelling nor does it provide details on FLAM E GPUs implementation or descriptions of the FLAM E GPU examples For more in depth background material on agent based simulation on the GPU the reader is directed towards the following document Richmond Paul Walker Dawn Coakley Simon Romano Daniela 2010 High Performance Cellular Level Agent based Simulation with FLAM E for the GPU Briefings in Bioinformatics 11 3 pages 334 47 For details on the implementation including algorithms and techniques the reader is directed towards the following publication Richmond Paul 2011 Template Driven Agent Based Modelling and Simulation with CUDA GPU Computing Gems Emerald Edition Wen mei Hwu Editor Morgan Kaufmann M arch 2011 ISBN 978 0 12 384988 5 Richmond Paul Coakley Simon Romano Daniela 2009 A High Performance Agent Based Mod
18. PI ssseeeenennemen nnns 17 3 7 Using Random Number Generatlonias 0cnnnad ance Annan anedae ePIbnebD 18 3 8 Summary of Agent Function Arguments seen nnns 18 3 9 Setting Simulation Constants Global Variables sen 18 3 9 1 I itialisation EUTIEM DS mete nebat onn tse ENR 19 4 FLAME GPU Simulation and Visualisation sss 19 4l introduction ieie ea rue o de Hr rero Ere Puicet ec e Hite 19 42 Generating a Functions File Template nennen 19 4 3 FLAMEGPU Template FES uci ccrto ter erede b bee bnt tu a Ne etes tarte teta d tib te ka pie 19 4 4 Compilation Using Visual Studio sosta tectae etn nd a tect atl at 20 44 1 Visual Studio Project Build Configurations sse b ten veto E Ne t E ha EMO 20 4 4 2 Visual Studio Project Virtual File Structure eennnm 20 4 4 3 SE igeracc ATTAT EE 21 4 4 4 FLAME GPU Build Rule ODUOFSu iare nter erred rre erasa Eh abs 21 4 4 5 Visual Studio Launch Configuration Command Arguments sess 22 4 5 Simulation Execution M odes and Options 2 2 erano ei da eal nha Eua bus Matias 22 45 1 Console Mode xsitestha tret rsittera emp e Ep eet ifa bed A 22 4 5 2 Visualisation Modes 4c eot nts a ete reru oeste rito icti cien 23 46 Creating a Custom Visualisation iium rette te tho b te bite tato Mk o tenes 23 8 Pertormance TID5cssisehon Quito uriaudiss siters tos codi etait COS Coe raul AT 23
19. SSapBs cededtex otto tetas han Rae tod dton Gib eodo boite had itae sb ao 7 2 4 4 Spatially Partitioned M essages seeeeenennnnnnnnennnnennn nnne nns 7 25 Defining an Agent function eene enne nennen nnne 8 25 1 Agent Function Message INpUts ir crt te rote tete Rea tetto pes boe ine ts 8 2 5 2 Agent Function M essage DUEDEOES 296 che chem bec oss ort enis Pus uti reste totas 9 2 5 3 Agent Function X Agent OULDUES uana testen Dua Ru kd aordo quta ea OR NS 9 2 5 4 F rictiori COnditlofis iere iere ee pa dero rette m vOv tes AARRE 9 2 5 5 Global Function CodItORs coena ote coe eruta RR DAE REP SERES Cur E REDIERE A EXE EEE 10 205 FubcBonEayefo oco mca oro Dr Hr DR rh PERRA 11 24 MAI ALM LAGGED abstain otio tuit tho x detener uela odes often ass 11 3 FLAMEGPU Agent Function Scripts and the Simulation API 12 31 SHINO CUICCIO dot OE IUE RR 12 3 2 Agent and Message Data Structures esses nnne 13 3 3 A Basic Agent Function Updating and Agents M emory sseee emm 13 34 Use of the Message Output Simulation API eene 14 35 Use of the Message Input Simulation API eene 14 3 5 1 Non Partitioned M essage Iteration eene 14 3 5 2 Spatially Partitioned M essage Iteration eene 15 3 5 3 Discrete Partitioned M essage Iteration eee 16 3 6 Use ofthe Agent Output Simulation A
20. a warning is generated and the value is ignored The example below represents a single agent corresponding to the agent definition in section 2 3 lt states gt itno 0O itno xagent lt name gt AgentName lt name gt ei d gt 1 lt 7id gt lt x gt 21 088 lt x gt lt y gt 12 834 lt y gt 295 367 z5 xagent lt xagent gt lt xagent gt lt states gt Care must be taken in ensuring that the set of initial data for the simulation does not exceed any of the defined buf ferSize i e the maximum number of a given type of agents for any of the agents If buffer size is exceeded during initial loading of the initial agent data then the simulation will produce an error Another special case to consider is the use of 2D discrete agents where the number of agents within the set of initial agent data must match exactly the buf ferSize which must also be a power of 2 defined within the XMML models agent definition Furthermore the simulation will expect to find initial agents stored within the XML file in row wise ascending order 3 FLAMEGPU Agent Function Scripts and the Simulation API 3 1 Introduction Agent function scripts define the behaviour of agents by describing changes to memory and through the iteration and creation of messages and new agents The behaviour of the agent function is described from the perspective of a single agent however the simulator will apply in parallel the same agent function code to each
21. cal Report and User Guide will reduce performance The following is a list of performance tips for creating FLAM E GPU model files General Usage of FLAM E GPU e FLAMEGPU is optimal where there are very large numbers of relatively simple agents which can be parallelised e Populations of agents with very low numbers will perform poorly in extreme cases slower than if they were simulated using the CPU If you require an agent population with very few agents consider writing some custom CPU simulation code and transferring any important information into simulation constants to be read by larger agent populations during the FLAME GPU simulation step e Outputting information to disk XML files is painfully slow in comparison with simulation Speeds so consider outputting information visually or only after larger numbers of simulation iterations Model Specification e Minimise the number of variables with agents and message data where possible e Try to conceptualise and fully specify the model before completing the agent functions script to avoid making mistakes with agent function arguments Try to think in terms of X Machines agents Agent Function Scripting e Small compute intensive agent functions are more efficient than functions which only iterate messages Try to minimise the number of times message lists are iterated e Keep agent functions small and do not define more local variables than is strictly required Reuse local variable
22. ction Layers Function layers represent the control flow of the simulation processes The sequence of layers defines the sequential order in which agent functions are executed Complete execution of every layer of agent functions represents a single simulation itteration which may be repeated any number of times Syntatically within the model definition a single Layers element must contain at least one or more layer element Each layer element may contain at least one or more gpu layerFunction element which defines only a name which must relate to a function name specified within a correspeonding xagents gpu xagent functions gpu function name Within a given layer the order of execution of layer functions should not be assumed to be sequential although in the current version of the software it is future versions will execute functions within the same layer in parallel For the same reason functions within the same layer should not have any communication or internal dependencies for example via message communications or execution order dependency in which case they should instead be represented within separate layers which guarantee execution order and global synchronisation between the functions The below example demonstrates the syntax of specifying a simulation consisting of three agent functions There are no dependencies between functionl and function2 which in this case can be thought of as being functions from two different agents definitions
23. d As with console execution it is possible to specify optional CUDA arguments Usage main XML model data Optional CUDA arguments Many of the options for the default visualisation are contained within the visualisation h header file and include the following e SIMULATION DELAY Many simulations are executed extremely quickly making visualisation a blur This definition allows an artificial delay by executing this number of visualisation draw loops before each simulation iteration is processed e WINDOW WIDTH and WINDOW HEIGHT Specifies the size of the visualisation window e NEAR CLIP and FAR CLIP Specifies the near an far clipping plane used for OpenGL rendering e SPHERE SLICES The number of slices used to create the sphere geometry representing a single agent in the visualisation e SPHERE STACKS The number of stacks used to create the sphere geometry representing a single agent in the visualisation e SPHERE RADIUS The physical size of the sphere geometry representing a single agent in the visualisation This will need to be a sensible value which corresponds with the environment size and agent locations within your model simulation e VIEW DISTANCE The camera viewing distance Again this will need to be a sensible value which corresponds with the environment size and agent locations within your model simulation e LIGHT POSITION The visualisation will contain a single light source which will be located at this positi
24. elling Framework on Graphics Card Hardware with CUDA Proc of 8th Int Conf on Autonomous Agents and Multi Agent Systems AAMAS 2009 M ay 10 15 2009 Budapest Hungary Some examples of FLAM E GPU models are described in the following publications Richmond Paul Coakley Simon Romano Daniela 2009 Cellular Level Agent Based Modelling on the Graphics Processing Unit Proc of HiBi09 High Performance Computational Systems Biology 14 16 October 2009 Trento Italy additional detail in the BiB paper FLAM E GPU Technical Report and User Guide Karmakharm Twin Richmond Paul Romano Daniela 2010 Agent based Large Scale Simulation of Pedestrians With Adaptive Realistic Navigation Vector Fields To appear in Proc of Theory and Practice of Computer Graphics TPCG 2010 6 8th September 2010 Sheffield UK 2 FLAMEGPU Model Specification 2 1 Introduction FLAME GPU models are specified using XML format within an XM ML document The syntax of the model file is governed by two XM L Schemas an abstract base Schema describes the syntax of a basic XMML agent model compatible with HPC and CPU versions of the FLAME framework and a concrete GPU Schema extension this to add various bits of additional model information Within this chapter the XML namespace xmins gpu is used to qualify the XML elements which extend the basic Schema representation A high level overview of a an XM M L model file is described below with various sections wit
25. empty agent function declarations automatically using your XM ML model file Once this has been generated the agent function scripts can be implemented within the function declarations rather easily Care must however be taken in ensuring that if the XM M L model file is later modified that the agent function arguments are updated manually where necessary Likewise be careful not to overwrite any existing function source file when generating a new one using the XSLT template Generation of blank function source files is not incorporated into the visual studio template project and must be manually accomplished A NET based XSLT processor is provided within the FLAME GPU SDK for this purpose XSLTProcessor exe located in the tool folder and can be used via the command line as follows or via the GenerateFunctionsFileTemplate batch file located in the tools folder of the FLAME GPU SDK XSLTProcessor exe XMLModelFile xml functions xslt functions c Alternatively any compliant XSLT processor such as Xalan Unicorn or even Firefox web browser can be used 4 3 FLAME GPU Template Files The FLAM E GPU SDK contains a number of xslt templates which are used to generate the dynamic simulation code A brief summary of the functionality and contents of each template file is as follows e header xslt This template file generates a header file which contains any agent and message data structures which are common in many of the other dynamically generated 19
26. fferent results depending on it capability It is therefore left to the user to experiment with different message partitioning types within a simulation The example below shows the format of the partitioningNone element tag gpu partitioningNone 2 4 3 Discrete Partitioned Messages Discrete partitioned messages are messages which may only originate from non mobile discrete agents cellular automaton A discrete partitioning message scheme requires the specification of a radius Which indicates the range in in 2D discrete space which a message iteration will extend to A radius value of 0 indicates that only a single message will be returned from message iteration A value of greater than 0 indicates that message iteration will loop through radius in both the x and a y dimension e g a range of 1 will iterate 3x3 9 messages a range of 2 will iterate 5x5 25 In addition to this the agent memory is expected to contain x and y variables of type int As with discrete agents it is important to ensure that messages using discrete partitioning use only supported buffer sizes power of 2 and squarely divisible The width and height of the discrete message space is then defined as the square of the buf ferSize value lt gpu partitioningDiscrete gt lt gpu radius gt 1 lt gpu radius gt lt gpu partitioningDiscrete gt 2 44 Spatially Partitioned Messages Spatially partitioned messages are messages which originate from continuous spaced agents
27. follow the input message list in the list of agent function arguments As with non partitioned messages the first argument of the get first message API function is the input message list The second argument is the PBM and the subsequent 3 arguments represent the position which the agent would like to read messages from which in almost all cases is the agent position The get next message API function differs only from the non partitioned example in that the PBM is passed as an additional parameter The example below shows the same example as in the previous section but using a spatially partitioned message type rather than the non partitioned type The differences between the function arguments in the previous section are highlighted in red as is the use of a helper function in_range The purpose of the in_range function is to check the distance between the agent position and the message This is 15 FLAM E GPU Technical Report and User Guide important as the messages returned by the get next message function represent any messages within the same or adjacent partitioning cells to the position specified by the get first message API function On average roughly 1 3 of these values will be within the actually range specified by the message definitions range value FLAME GPU FUNC int input messages xmachine memory location xmemory xmachine message location list location messages xmachine message location PBM partition matrix int count
28. ge output using single message type This will assume every agent outputs a message if the functions script fails to output a message for every agent a message with default values of 0 will be created instead lt outputs gt lt gopusoutput gt lt messageName gt message_name lt messageName gt lt gpu type gt single_message lt gpu type gt fgpuioutpute lt outputs gt 25 3 Agent Function X Agent Outputs An agent function xagent Output indicates that the agent function will output an agent with a name equal to that specified by the non optional xagent Name element This differs slightly from the formal definition of an x machine which does not explicitly define a technique for the creation of new agents but adds functionality required for dynamically changing population sizes during simulation runtime The xagentName element belonging to an xagentOutput element must refer to an existing agent name defined within the XMML document It is not possible for an agent function script to output a agent without specifying that it is an xagntOutput within the XMML model file agent output functions are parameterised to prevent this In addition to the xagentName element a message output also requires a state The state represents the state from the list of state elements belonging to the specified agent name that the new agent should be in after it has been created Only continuous type agents are allowed to output new agents which must a
29. her than 0 indicates that the agent has dies and should be removed from the simulation unless the agent function definition had specifically set the reallocate element value to false in which case any agent deaths will be ignored FLAME GPU FUNC int functionl xmachine memory myAgent xmemory xmemory x xmemory gt x 0 01f xmemory no movements 1 return 0 13 FLAM E GPU Technical Report and User Guide 3 4 Useofthe Message Output Simulation API Within an agent function script message output is possible by using a message output function For each message type defined within the XM M L model definition the dynamically generated simulation API will create a message output function of the following form add message name message message name messages args Where message name refers to the value of the messages name element within the message specification and args isa list of named arguments which correspond to the message variables see section 2 4 1 Agent functions may only call a message output function for the message name defined within the function definitions output see 2 5 2 This restriction is enforced as message output functions require a pointer to a message list which is passed as an argument to the agent function xmachine message location list in the below example Agents are only permitted to output a single message per agent function and repeated calls to an add message function will result
30. hin this chapter describing each part in more detail gpu xmodel xmlns gpu http www dcs shef ac uk paul XMMLGPU xmlns http www dcs shef ac uk paul XMML gt lt name gt Model Name lt name gt optional lt gpu environment gt lt gpu environment gt lt xagents gt lt xagents gt lt messages gt lt messages gt lt layers gt lt layers gt lt gpu xmodel gt 2 2 The Environment The environment element is used to hold global information which relates to the simulation This information includes zero or more constant or global variables which are constant for all agents over the period of either the simulation or single simulation iteration a single non optional function file containing agent function script see Chapter 3 and an optional number of initialisation functions lt gpu environment gt lt gpu constants gt lt gpu constants gt optional lt gpu functionFiles gt lt gpu functionFiles gt not optional lt gpu initFunctions gt lt gpu initFunctions gt optional lt gpu environment gt 22 1 Simulation Constants Global Variables Simulation constants are defined as global variables and may be of type int float or double on GPU hardware with double support i e CUDA Compute capability 2 0 or beyond Constant variables must each have a unique name which is used to reference them within simulation code and can have an optional static array length of size greater than
31. ied to none of the agents As with an agent function condition a globalCondition consists of a left hand side statement 11s an operator and a right hand side statement rhs The syntax of the left hand side statement 1hs the operator and the right hand side statement rhs is the same as with an agent function condition and may use recursion to generate a complex conditional statement The maxItterations element is used to limit the number of times a function guarded by the global condition can be avoided or evaluated as the logical opposite of the value specified by the mustEvaluateTo element For example the definition at the end of this section resulting in the following pseudo code condition movement lt 0 25 true May be evaluated as false up to 200 times i e in 200 separate simulation iterations before the global condition will be ignored and the function is applied to every agent Following maximum number of iterations being reached the iteration count is reset once the agent function has been applied 10 FLAM E GPU Technical Report and User Guide lt gpu globalCondition gt lt lhs gt lt agentVariable gt movement lt agentVariable gt lt lhs gt operator amp lt operator lt rhs gt lt value gt 0 25 lt value gt lt rhs gt lt gpu maxItterations gt 200 lt gpu maxItterations gt lt gpu mustEvaluateTo gt true lt gpu mustEvaluateTo gt lt gpu globalCondition gt 2 6 Fun
32. in previous message information simply being overwritten The example below demonstrates an agent function output message belonging to an agent named myAgent which outputs a message with four variables For clarity the message output function prototype normally found in header n is also shown add location message xmachine message location list location messages int id float x float y float z FLAME GPU FUNC int output message xmachine memory myAgent xmemory xmachine message location list location messages int id float x y Z id xmemory gt id x xmemory gt x y xmemory gt y Zz xmemory gt z add location message location messages id x y z return 0 3 5 Use of the Message Input Simulation API As with message outputs iterating message lists message input within agent functions is made possible by the use of dynamically generated message API functions In general two functions are provided for each named message a get_first_message_name_message args and get_next_message_name_message args the second of which can be used within a while loop until it returns a NULL value indicating the end of the message list The arguments of these functions differ slightly depending on the partitioning scheme used by the message The following subsections describe these in more detail Regardless of the partitioning type a number of important rules must be observed when using the message functions Firs
33. ing and linking with non CUDA libraries is not supported e External Function Calls As above external function calls may only be made to CUDA device functions Many common math functions calls such as sin cos etc are supported via native GPU implementations and can be used in exactly the same way as standard C code Likewise additional helper functions can be defined and called from agent functions by prefixing the helper function using the _ FLAME GPU FUNC macro which signifies it can be run on the GPU device The following chapter describes the syntax and use of agent function scripts including any arguments which must be passed to the agent or simulation API functions As agent functions and simulation API functions are dynamic and based on the XM M L model definition it is often easier to first define a model and use the technique described within section 4 2 to automatically generate a functions file containing prototype agent function files and API system calls Alternatively section 3 8 describes fully the expected argument order for agent function arguments 3 2 Agentand Message Data Structures Access to agent and message data within the agent function scripts is provided through the use of agent and message data structures which contain variables matching those defined within the XMML definitions For each agent in the simulation a structure is defined within the dynamically generated header h with the name xmachine memory agent
34. ionals to change the simulations expected arguments see section 4 5 4 4 2 Visual Studio Project Virtual File Structure Within the FLAM E GPU examples and template projects code is organised into the following virtual folders e FLAME GPU Consisting of a folder containing the FLAME GPU XML schemas and Code generating templates These files are shared amongst all examples so editing them will change simulation code generated for other projects e FLAM EModel Contains the XM ML model file and the agent functions file usually called functions c Note that the functions c file is actually excluded from the build processes as it is built by the dynamically generated simulation cu source file which includes it 20 FLAM E GPU Technical Report and User Guide e Dynamic Code Contains the dynamically generated FLAME GPU simulation code This code will be overwritten each time the project is built so any changes to this files will be lost unless template transformation is turned off using the FLAME GPU build rule see section 4 4 4 e Additional Source Code This folder should contain any hard coded simulation specific source or header files By default the FLAME GPU project template defines a single visualisation h file in this folder which may be modified to set a number of variables such as viewing distance and clipping Within the FLAME GPU examples this folder is typically used to sore any model specific visualisation code
35. lements Q in the X Machine formal definition with a unique and non optional name As simulations within FLAM EGPU can continue indefinitely or for a fixed number of iterations terminal states T in the formal definition are not defined The initial state qo must however be defined within the init ialState element and must correspond with an existing and unique state name from the list of states above it states gpu state lt name gt statel lt name gt FLAM E GPU Technical Report and User Guide lt gpu state gt Qpu state gt lt name gt state2 lt name gt lt gpu state gt lt initialState gt statel lt initialState gt lt states gt 2 4 Defining Messages Messages represent the information which is communicated between agents An element messages Contains a list of at least one message which defines a non optional name an optional description of the message a list of variables a partitioning type and a bufferSize The bufferSize element is used in the same way that a buf ferSi ze is used to define an X M achine agent i e the maximum number of this message type which may exist within the simulation at one time The partitioning type may be one of three currently defined message partition schemes non partitioned partitioningNone discrete 2D space partitioning part itioningDiscrete or 2D 3D spatially partitioned space part itioningSpatial Message partition schemes are used to ensure that the most optimal c
36. lso be of type continuous The creation of new discrete agents is not permitted under any circumstance An xagent Output does not require a type asis the case with a message output and any agent function outputting an agent is assumed to be optional l e each agent performing the function may output either one or zero agents lt xagentOutputs gt lt gpu xagentOutput gt lt xagentName gt agent_name lt xagentName gt lt state gt statel lt state gt gpu xagentOutput lt xagentOutputs gt 2 5 4 Function Conditions An agent function condition indicates that the agent function should only be applied to agents which meet the defined condition and in the correct state specified by current State Each function condition consists of three parts a left hand side statement 1ns an operator anda right hand side statement rhs Both the ihs and rhs elements may contain either a agentVariable a value or a recursive condition element An agentVariable element 9 FLAM E GPU Technical Report and User Guide must refer to a agent variable defined within the agents list of variable names i e gpu xagent memory gpu variable name A value element may refer to any numeric value or constant definition defined within the agent function scripts The use of recursive conditions is demonstrated below by embedding a condition within the rhs element of the top level condition lt condition gt amp lnsos lt agentVariable gt variable_name
37. make use of template parameterisation to distinguish between the type of agent requesting message information The template parameters which may be used are either DISCRETE 2D as in the example below or CONTINUOUS This parameterisation is required as underlying implementation of the message API functions differs 16 FLAM E GPU Technical Report and User Guide between the two agent types The example below shows an agent function input messages of a discrete agent named ce11 which iterates a message list of state messages to count the number neighbours with a state value of 1 The differences between the function arguments in the section describing non partitioned message iteration are highlighted in red as is the function parameterisation FLAME GPU FUNC int input messages xmachine memory cell xmemory xmachine message state list state messages int neighbours 0 xmachine_message_state state_message message get_first_state_message lt DISCRETE_2D gt state_messages xmemory gt x xmemory gt y while message if message gt state 1 neighbours message get_next_state_message lt DISCRETE_2D gt message state_messages xmemory neighbours neighbours return 0 3 6 Use of the Agent Output Simulation API Within an agent function script agent output is possible by using a message output API function For each agent type defined within the XMML model definition the dynamically genera
38. may in fact be non spatial more abstract agents As all memory is pre allocated on the GPU a bufferSize is required to represent the largest possible size of the agent population That is the maximum number of x machine agent instances of the format described by the XMML model There is no performance disadvantage to using a large bufferSize however it is the user s responsibility to ensure that the GPU contains enough memory to support large populations of agents It is recommended that the bufferSize always be a power of two number i e 1024 2048 4096 16384 etc as it will most likely be rounded to one during simulation For discrete agents the bufferSize is currently limited to only power of 2 numbers which have squarely divisible dimensions i e the square of the bufferSize must be a whole number If at any point in the simulation exceeds the stated bufferSize then the user will be warned at the simulation will exit Each expandable aspect of an XMML agent FLAM E GPU Technical Report and User Guide representation in the below example is discussed within this section with the exception of agent functions which due to their dependence of the definition of messages are discussed later in section 2 5 lt xagents gt lt gpu xagent gt lt name gt Agent Name lt name gt lt description gt optional description of the agent lt description gt lt memory gt lt memory gt tuncblonss functions lt states gt lt states g
39. message is used to calculate an average position of all the locations specified in the message list The agent then updates three of its positional values to move towards the average location cohesion FLAME GPU FUNC int input messages xmachine memory myAgent xmemory xmachine message location list location messages int count float avg x avg y agv z Get the first location messages xmachine message location message message get first location message location messages Loop through the messages while message if message id xmemory id avg x message gt x avg y message gt y avg z message z count Move onto next location message message get_next_location_message message location_messages if count avg_x count avg_y count avg_z count xmemory gt x avg x SMALL NUMBER xmemory y avg y SMALL NUMBER xmemory gt z avg z SMALL NUMBER return 0 352 Spatially Partitioned Message Iteration For spatially partitioned messages the dynamically generated message API functions rely on the use of a Partition Boundary Matrix PBM The PBM holds important information which determines which agents are located within the spatially partitioned areas making up the simulation environment Wherever a spatially partitioned message is defined as a function input within the XMML model definition a PMB argument should directly
40. mpilation Using Visual Studio The FLAM E GPU SDK and examples are targeted at CUDA 3 1 for compilation under windows using Visual Studio 2008 The decision to target windows is influenced entirely by visual studios excellent IDE tools and debugging facilities for CUDA programming and not as a result of any windows specific functionality Porting to a Linux environment should be relatively simple In addition to this Visual Studios XML editor includes validation support and XML tag auto completion which makes defining an XMML model incredibly easy The following subsections describe the various aspects of a FLAME GPU project file and describe the build processes 4 4 1 Visual Studio Project Build Configurations The FLAME GPU examples and template project file contain build configurations for both 32 bit windows Win32 and 64 bit Windows x64 environments which can be changed using the Solutions Platforms drop down toolbar item For each platform the project also contains four configurations for debugging Debug and release versions Release of both console based simulation and visualisation simulation The two debug options disable all compiler optimisations and generate debug information for debugging host non GPU code and enables CUDA device emulation for GPU device debugging The visualisation configurations enable building of visualisation code and specify a pre processor macro VISUALISATION which is used by a number of pre processor condit
41. nt type variables of name x and y Spatial partitioning requires three float or double type variables named x y and z The example below shows an example of message memory containing two message variables named id and message variable variables lt gpu variable gt lt type gt int lt type gt lt name gt id lt name gt lt description gt variable description lt description gt lt gpu variable gt lt gpu variable gt lt type gt float lt type gt lt name gt message_variable lt name gt lt gpu variable gt lt variables gt FLAM E GPU Technical Report and User Guide 2 4 2 Non partitioned Messages None partitioned messages do not use any filtering mechanism to reduce the number of messages which will be iterated by agent functions which use the message as input None partitioned messages therefore require a brute force or O n message iteration loop wherever the message list is iterated As non partitioned messages do not require any message variables with location information the partition type is particularly suitable for communication between non spatial or more abstract agents Brute force iteration is obviously reasonably computationally expensive however non partitioned message iteration requires very little overhead or setup and as a result for small numbers of messages it can be more efficient than either limited range technique There is no strict rule governing performance and different GPU hardware will produce di
42. off These options are configuration specific and therefore console configurations by default do not processes the visualisation template XMLModelFile xml Property Pages Configuration Active Debug Console Platform Active Win32 xj Configuration Manager Configuration Properties ed Yes tools XSLTProcessor src model InputFile General vals xsit enat Yes tools XSLTProcessor src model InputFile FLAMEGPU Template Buil Yes tools XSLTProcessor src model InputFile XSLT Options ran nula slt enabled Yes tools XSLTProcessor src model InputFile Command Line Tran enabled Yes tools XSLTProcessor src model InputFile Ne Transform visualisation xsIt enabled Toggle XSLT Processing for the visualisation xslt FLAMEGPU Template File E D Figure 2 FLAME GPU Build Rule XSLT Options Tab 21 FLAM E GPU Technical Report and User Guide 4 4 5 Visual Studio Launch Configuration Command Arguments In order to set the execution arguments described in the next section for simulation executable in any one of one of the four launch configurations the Command Arguments property can be set form the Project Properties Page Select Project Menu followed by FLAMEGPU Project Properties The Command Arguments property is located under Configuration Properties Debug see Figure 3 Each configuration has its own set of Command Arguments so when moving be
43. on 4 6 Creating a Custom Visualisation Customised visualisation can easily be integrated to a FLAME GPU project by extending the automatically generated visualisation file the output of processing visualisation xslt Many of the FLAM E GPU SDK examples use customised visualisations in this way As with the default visualisations any custom visualisation must define the following function prototypes defined in the automatically generated simulation header extern C void initVisualisation extern C void runVisualisation The first of these can be used to initialisate any OpenGL memory and CUDA OpengGL bindings as well as displaying the user interface The second of these functions must take control of the simulation by repeatedly calling the draw and singleIteration which advances the simulation by a single iteration step functions in a recursive loop A more detailed description of the default rendering technique is provided within other FLAM E GPU documentation listed in Section 1 2 4 7 Performance Tips The GPU offers some enormous performance advantages for agent simulation over more traditional CPU based alternatives With this in mind it is possible to write extremely sub optimal code which When doing this within Visual Studio it is important to turn off the template processing of the visualisation xslt file in each of the launch configurations as processing them will overwrite any custom code 23 FLAM E GPU Techni
44. oningSpatial gt lt gpu radius gt 1 lt gpu radius gt lt gpu xmin gt 0 lt gpu xmin gt gpu xmax 10 gpu xmax gpu ymin 0 gpu ymin gpu ymax 10 gpu ymax gpu zmin 0 gpu zmin gpu zmax 10 gpu zmax lt gpu partitioningSpatial gt 2 5 Defining an Agent function An optional list of agent functions is described within an X M achine agent representation and must contain a list of at least a single agent function element In turn a function must contain a non optional name and optional description a current state next state an optional single message input and optional single message output an optional single agent output an optional global function condition an optional function condition a reallocation flag and a random number generator flag The current state is defined within the current State element and is used to filter the agent function by only applying it to agents in the specified state After completing the agent function agents then move into the state specified within the next State element Both the current and next State values are required to have values which exist as a state name within the state list st ates definition The reallocate element is used as an optional flag to indicate the possibility that an agent performing the agent function may die as a result and hence require removing from the agent population By default this value is assumed true however if a value of false is
45. s an agent function cannot iterate a list of messages without specifying that it is an input within the XMML model file message iteration functions are parameterised to prevent this inputs gpu input lt messageName gt message_name lt messageName gt lt gpu input gt FLAM E GPU Technical Report and User Guide lt inputs gt 252 Agent Function Message Outputs An agent function message output indicates that the agent function will output a message with a name equal to that specified by the non optional messageName element The messageName element must therefore refer to an existing message name defined within the XM M L document It is not possible for an agent function script to output a message without specifying that it is an output Within the XM M L model file message output functions are parameterised to prevent this In addition to the messageName element a message output also requires a type The type may be either single message Or optional message Where single message indicates that every agent performing the function outputs exactly one message and optional message indicates that agent s performing the function may either output a single message or no message The type of messages which can be output by discrete agents are not restricted however continuous type agents can only output messages which do not use discrete message partitioning e g no partitioning or spatial partitioning The example below shows a messa
46. s where possible if they are no longer needed and before they go out of scope Message Iteration e For small populations of agents generally less than 2000 but dependant on hardware and the model non partitioned messaging has less overhead and is similarly comparable to spatial partitioning e For large populations of distributed agents with limited communication spatially partitioned message communication will be much faster 24
47. simulation iteration The initialisation function declaration should be preceded with a FLAME GPU INIT FUNC macro definition should have no arguments and should return void The below example demonstrated an initialisation function named initConstants which uses the simulation APls dynamically created constants functions to set a constant named A_CONSTANT FLAME GPU INIT FUNC void initConstants float const_value 8 25f set_A_CONSTANT amp const_value 4 FLAME GPU Simulation and Visualisation 4 1 Introduction The processes of building and running a simulation is made easier described within this chapter as are a number of tools and procedures which simplify the simulation code generation and compilation of simulation executables In order to use the FLAME GPU SDK it should be placed in a directory which does not contain any spaces preferably directly within the C drive or root or root Operating system drive The host machine must also be running windows with a copy of the NET runtime used within the XSLT template processor and must contain NVIDIA GPU hardware with Compute level 1 0 4 2 Generating a Agent Functions Script Section 3 8 previously described the exact argument order for agent function declarations however in most cases it is sensible to use the provided XSLT template unctions xsit located in the FLAM EGPU templates folder within the FLAM E GPU SDK to generate a agent function source file with
48. specified then the processes for removing dead agents will not be executed even if an agent indicates it has died see agent function definitions in section 3 3 The RNG element represents a flag to indicate the requirement of random number generation within the agent function If this value is true then an additional parameter demonstrated in section 3 7 is passed to the agent function which holds a number of seeds used for parallel random number generation lt functions gt lt gpu function lt name gt func_name lt name gt lt description gt function description lt description gt lt currentState gt statel lt currentState gt lt nextState gt state2 lt nextState gt lt inputs lt inputs gt optional lt outputs gt lt outputs gt optional lt xagentOutputs gt lt xagentOutputs gt optional lt gpu globalCondition gt lt gpu globalCondition gt optional lt condition gt lt condition gt optional lt gpu reallocate gt true lt gpu reallocate gt optional lt gpu RNG gt t rue lt gpu RNG gt optional gpu function tunctions 25 1 Agent Function Message Inputs An agent function message input indicates that the agent function will iterate the list of messages with a name equal to that specified by the non optional messageName element It is therefore required that the messageName element refers to an existing message name defined within the XMML document In addition to thi
49. t lt gpu type gt continuous lt gpu type gt lt gpu bufferSize gt 1024 lt gpu bufferSize gt lt gpu xagent gt lt gpu xagent gt lt gpu xagent gt lt xagents gt 2 3 1 Agent Memory Agent memory consists of a number of variables at least one which are use to hold information An agent variable must have a unique name and may be of type int float or double CUDA compute capability 1 3 or beyond Currently agent memory only supports the use of single memory values i e no static or dynamic arrays and default values are always 0 unless a value is specified within the XML input states file There are no specified limits on the maximum number of agent variables however the performance tips noted in section 4 7 should be taken into account Below shows an example of agent memory containing four agent variables representing an agent identifier and three positional values lt memory gt lt gpu variable gt lt type gt int lt type gt lt name gt id lt name gt lt description gt variable description lt description gt lt gpu variable gt lt gpu variable gt lt type gt float lt type gt lt name gt x lt name gt lt gpu variable gt lt gpu variable gt lt type gt float lt type gt lt name gt y lt name gt lt gpu variable gt lt gpu variable gt lt type gt float lt type gt lt name gt z lt name gt lt gpu variable gt lt memory gt 2 3 2 Agent States Agent states are defined as a list of st ate e
50. ted simulation code will create an agent output function of the following form add_agent_name_agent agent_name_agent args Where agent_name refers to the value of the agents name element within the agent specification and args is a list of named arguments which correspond to the agents memory variables see section 2 5 3 Agent functions may only output a single type of agent and are only permitted to output a single agent per agent function As with message outputs repeated calls to an add agent function will result in previous agent information simply being overwritten The example below demonstrates an agent function create_agent which outputs a new agent by creating a clone of itself For clarity the agent output API function prototype normally found in header h is also shown add_myAgent_agent xmachine memory myAgent list myAgent agents int id float x float y float z FLAME GPU FUNC int output message xmachine memory myAgent xmemory xmachine memory myAgent list myAgent agents int id float x y Z id xmemory gt id x xmemory gt x y xmemory gt y z xmemory gt z add myAgent agent myAgent agents id x y z return 0 17 FLAM E GPU Technical Report and User Guide 3 7 Using Random Number Generation Random number generation is provided via the rnd API function which uses template parameterisation to distinguish between either discrete where a parameter value of DISCRETE_2
51. tly it is essential that message loop complete naturally l e the get_next_message_name_message function must be called without breaking from the while loop until the end of the message list is reached Secondly agent functions must not directly modify messages returned from the get message functions Changing message data directly will result in undefined behaviour and will most likely crash the simulation 3 5 1 Non Partitioned Message Iteration For non partitioned messages the dynamically generated message API functions are relatively simple and the arguments which are passed to the API functions are also required by all other message partitioning schemes The get first message API function i e get_first_message_name_message takes only a single argument which is a pointer to a 14 FLAM E GPU Technical Report and User Guide message list structure of the form xmachine_message_message_name_list which is passed as an argument to the agent function The get next message API function i e get next message name message takes two arguments the previously returned message and the message list The below example shows a complete agent function input messages demonstrating the iteration of a message list where the message name 1ocat ion is highlighted within the structure and API names for clarity The while loop continues until the get next message API function returns a NULL or false value In the below example the location
52. tween configurations these will need to be set Likewise the Configuration Properties are computer and user specific so these cannot be preset and must be specified the first time each example is compiled and run The Visual Studio macro rnputDir can be used to specify the working directory of the project file which makes locating initial agent data XML files for many of the examples much easier these are normally located in the iterations folders of each example Once a The Command Arguments have been set the simulation executable can be launched by selecting Start Debugging from the Debug menu or using the F5 hotkey this is the same in both release and debug launch configurations FLAMEGPU Project Property Pages Configuration Release Console Platform Active Win32 x Configuration Manager Common Properties Debugger to launch Configuration Properties Local Windows Debugger General Debugging Command S TargetPath get ELEN sonet teat Pow 4 Tool Working Directory im Attach No XML Document Generator Debugger Type Auto Environment Browse Information Build Events Custom Build Step Merge Environment Yes XML Data Generator Tool SQL Debugging No CUDA Build Rule FLAMEGPU Template Buil Command Arguments The command line arguments to pass to the application Gad Cancel Apply Figure 3 FLAME GPU Project Properties Page 4 5 Simulation Execution Modes
53. ulation layers which define the execution order of agent functions which constitutes a single simulation iteration Throughout a simulation agent data is persistent however message information and in particular message lists is persistent only over the lifecycle of a single iteration This allows a mechanism for agents to iteratively interact in a way which allows emergent global group behaviour The process of generating a FLAME GPU simulation is described by the Figure 1 The use of XML schemas forms a large part of the process where polymorphic like extension allows a base schema specification to be extended with a number of GPU specific elements Given an XMML model definition template driven code generation is achieved through Extensible Stylesheet Transformations XSLT XSLT is a flexible functional language based on XML validated itself using a W3C specified Schema and is suitable for the translation of XML documents into other document formats using a number of compliant processors although the FLAM E GPU SDK provides its own Through the specification of a number of XSLT Simulation Templates a Dynamic Simulation API is generated which links with the Agent Function Files to generate a simulation program FLAM E GPU Technical Report and User Guide XML Scripted Schemas Behaviour l 4 Simulation Code XML Model File XSLT Processor Simulation Program XSLT Simulation Templates Figure 1 FLAME
54. ycling of messages occurs within agent functions The use of the partitioning techniques is described within this section as are message variables lt messages gt lt gpu message gt lt name gt message_name lt name gt lt description gt optional message description lt description gt lt variables gt lt variables gt lt partitioningType gt replace with a partitioning type gpu bufferSize 1024 gpu bufferSize lt gpu message gt lt gpu message gt lt gpu message gt lt messages gt 2 4 1 Message Variables The message variables element consists of a number of variables at least one which are use to hold communication information A variable must have a unique name and may be of type int float or double CUDA Compute capability 2 0 or beyond As with agent variables message variables only supports the use of single memory values i e no static or dynamic arrays Likewise there are no specified limits on the maximum number of message variables however increased message size will have a negative effect on performance in all partitioning cases and in particular when non partitioned messages are used The format of message variable specification shown below is identical to that of agent memory The only exception is the requirement of certain variable names which are required by certain partitioning types Non partitioned messages have no requirement for specific variables Discrete partitioning requires two i
Download Pdf Manuals
Related Search