flamegpu / docs Goto Github PK

It may be worthwhile documenting the preferred approach to parameter exploration for FLAME GPU models.

I.e. as of 1.5 this is:

1. Use Environment constants for parameters
2. Load these values from the XML Model file (or a custom init function)
3. Initialise population via Init function
4. Use 1 folder per init file to avoid overwriting
5. Jobs can then be ran sequentially on a single device (or multiple concurrent runs for very small models) or batched across multiple devices (i.e high throughput on clusters)

Document new Agent ID generation functionality when merged.

• generate_<AgentName>_id()
• set_initial_<AgentName>_id()
• Starts at 0 or max(id)+1
• Agents must have a variable id of an integer type.

See FLAMEGPU/FLAMEGPU#250

Document the newly created min and max analytics functions, available for non-vector, non-array agent variables.

Should be possible for vectors but would require a custom comparison object.

From http://readthedocs.org/projects/flamegpu/builds/6522833/:

python2.7 -mvirtualenv --no-site-packages --no-download /home/docs/checkouts/readthedocs.org/user_builds/flamegpu/envs/latest
python /home/docs/checkouts/readthedocs.org/user_builds/flamegpu/envs/latest/bin/pip install --use-wheel --upgrade --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/flamegpu/.cache/pip Pygments==2.2.0 setuptools==37.0.0 docutils==0.13.1 mock==1.0.1 pillow==2.6.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.5.4 recommonmark==0.4.0 sphinx<2 sphinx-rtd-theme<0.3 readthedocs-sphinx-ext<0.6
python /home/docs/checkouts/readthedocs.org/user_builds/flamegpu/envs/latest/bin/pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/flamegpu/.cache/pip -rrequirements.txt
python setup.py install --force
python: can't open file 'setup.py': [Errno 2] No such file or directory 

Document accessing agent data on the host in init/exit/step functions.

Do this VERY clearly, as there may be significant performance implications.

Possibly also include an example / details of how to implement a custom output function.

FLAMEGPU/FLAMEGPU#178

Document get_exit_early() and set_exit_early()

Also document exit functions executing on window close via freeglut (if merged)

Spatially partitioned messaging (and discrete messaging) both wrap in the X and Y dimensions. This should be clearly stated in the documentation.

From 1.5 it will be possible to create agents from the host, in init functions, step functions, or any host code which is executed between calls to single_iteration().

This needs adding to the documentation.

• Mention this in section 2.7, indicating that initial XML data could instead be generated by an init function.
• a new section in chapter 3, detailing the process and functions available (with an example).

To add clarity to the documentation about which types of agents can output which types of message would be useful.

I.e

It could just be an explicit statement rather than a table, but a table would add clarity if we have additional messaging types

The docs don't appear to mention accessing agent array data on the device at all.

This is a massive oversight which should be resolved.

I.e from the stable marriage example:

woman = get_Man_agent_array_value<int>(agent->preferred_woman, round);

New macros in 1.5 for the type of message partitioning used for a given message type should be docuumented with an example.

I.e. xmachine_message_location_partitioningSpatial is defined for a message of name location using spatial parititioning. See FLAMEGPU/FLAMEGPU#121

We need to add details about the use of vector and unsigned types for 1.5.X

• Agent Variables
• Environmental Variables
• Message Variables
  • Importantly this does not support vector types, but might support unsigned? @mondus

Need to document new communication strategy.

• Section describing it and its purpose
• How to define a staticGraph (and the limitations)
• Format for reading graph from disk, with examples
  • XML
  • JSON
  • Including the use of agent arrays, vector types and arrays of vector types.
• How to define graph based communication

The linked RTD badge in the readme refers to latest which we have disabled in favour of master / certain branches / tags. This should be updated

• Instrumentation constants
• Limitations of statically allocated memory (2GB limit on windows) which effects agent populations, message list size and the number of bins available for spatially partitioned messaging.
• The current Linux build process
• Step Functions
• Analytics functions such as reductions
  • Including that these are not available for agent variable arrays
• Upcoming host-based agent creation (init and step functions)
• PAUSE_ON_START in visualisation.h

We may wish to:

• Remove the technical report from the repository? OR Replace the technical report with a pdf of the new documentatiojn
• Update the README to point to the documentation.

From FLAMEGPU/FLAMEGPU#66

The Makefiles have been updated in flamegpu/rc1.5/alternate-makefiles (FLAMEGPU/FLAMEGPU#112) and the documentation should reflect the changes.

Provide details of:

• How to manually create a new visual studio project
• How to manually create a new makefile based project
• How to create a new example based off an existing example (tools/new_example.py)

Discrete Partitioned Messaging with radius 0 returns the value from the individual cell (i.e PedestrianNavigation).

Discrete Partitioned Messaging with radius > 0, i.e. 1 returns the neighbouring 8 cells and not the cell at the centre.

This means that using the same message list for discrete->discrete communication and discrete -> continuous communication doesn't work, and 2 message lists must be used.

This is a limitation in FLAME GPU 1, but will be avoided in FLAME GPU 2, with baked-in self-message ignoring.

I.e. in flamegpu/modelspec.rst

Both the mintinline[fontsize=small]{text}{lhs} and mintinline[fontsize=small]{text}{rhs} elements may

• Launching without an initial states file (subject to twin's merge)
• Overriding OUTPUT_TO_XML via additional optional argument in console mode.

docs/flamegpu/api.rst:467

Nowhere in the docs does it state what range the RNG returns (presumably 0<=x<1. but it's not clear from the code either).