Giter Club home page Giter Club logo

docs's Introduction

FLAME GPU

http://www.flamegpu.com

Current version: 1.5.0

FLAME GPU (Flexible Large-scale Agent Modelling Environment for Graphics Processing Units) is a high performance Graphics Processing Unit (GPU) extension to the FLAME framework.

It provides a mapping between a formal agent specifications with C based scripting and optimised CUDA code. This includes a number of key ABM building blocks such as multiple agent types, agent communication and birth and death allocation. The advantages of our contribution are three fold.

  1. Agent Based (AB) modellers are able to focus on specifying agent behaviour and run simulations without explicit understanding of CUDA programming or GPU optimisation strategies.
  2. Simulation performance is significantly increased in comparison with desktop CPU alternatives. This allows simulation of far larger model sizes with high performance at a fraction of the cost of grid based alternatives.
  3. Massive agent populations can be visualised in real time as agent data is already located on the GPU hardware.

Documentation

The FLAME GPU documentation and user guide can be found at http://docs.flamegpu.com, with source hosted on GitHub at FLAMEGPU/docs.

Getting FLAME GPU

Pre-compiled Windows binaries are available for the example projects in the FLAME-GPU-SDK, available as an archive for each release.

Source is available from GitHub, either as a zip download or via git:

git clone https://github.com/FLAMEGPU/FLAMEGPU.git

Or

git clone [email protected]:FLAMEGPU/FLAMEGPU.git

Building FLAME GPU

FLAME GPU can be built for Windows and Linux. MacOS should work, but is unsupported.

Dependencies

  • CUDA 8.0 or later
  • Compute Capability 2.0 or greater GPU (CUDA 8)
    • Compute Capability 3.0 or greater GPU (CUDA 9)
  • Windows
    • Microsoft Visual Studio 2015 or later
    • Visualisation:
      • freeglut and glew are included with FLAME GPU.
    • Optional: make
  • Linux
    • make
    • g++ (which supports the cuda version used)
    • xsltproc
    • Visualistion:
      • GL (deb: libgl1-mesa-dev, yum: mesa-libGL-devel)
      • GLU (deb: libglu1-mesa-dev, yum: mesa-libGLU-devel)
      • GLEW (deb: libglew-dev, yum: glew-devel)
      • GLUT (deb: freeglut3-dev, yum: freeglut-devel)
    • Optional: xmllint

Windows using Visual Studio

Visual Studio 2015 solutions are provided for the example FLAME GPU projects. Release and Debug build configurations are provided, for both console mode and (optionally) visualisation mode. Binary files are places in bin/x64/<OPT>_<MODE> where <OPT> is Release or Debug and <MODE> is Console or Visualisation.

An additional solution is provided in the examples directory, enabling batch building of all examples.

make for Linux and Windows

make can be used to build FLAME GPU simulations under linux and windows (via a windows implementation of make).

Makefiles are provided for each example project examples/project/Makefile), and for batch building all examples (examples/Makefile).

To build a console example in release mode:

cd examples/EmptyExample/
make console

Or for a visualisation example in release mode:

cd examples/EmptyExample/
make visualisation

Debug mode executables can be built by specifying debug=1 to make, i.e make console debug=1.

Binary files are places in bin/linux-x64/<OPT>_<MODE> where <OPT> is Release or Debug and <MODE> is Console or Visualisation.

For more information on building FLAME GPU via make, run make help in an example directory.

Note on Linux Dependencies

If you are using linux on a managed system (i.e you do not have root access to install packages) you can provide shared object files (.so) for the missing dependencies.

I.e. libglew and libglut.

Download the required shared object files specific to your system configuration, and place in the lib directory. This will be linked at compile time and the dynamic linker will check this directory at runtime.

Alternatively, to package FLAME GPU executables with a different file structure, the .so files can be placed adjacent to the executable file.

Usage

FLAME GPU can be executed as either a console application or as an interactive visualisation. Please see the documentation for further details.

# Console mode
usage: executable [-h] [--help] input_path num_iterations [cuda_device_id] [XML_output_override]

# Interactive visualisation
usage: executable [-h] [--help] input_path [cuda_device_id]

For further details, see the documentation or see executable --help.

Running a Simulation on Windows

Assuming the GameOfLife example has been compiled for visualisation, there are several options for running the example.

  1. Run the included batch script in bin/x64/: GameOfLife_visualisation.bat
  2. Run the executable directly with an initial states file
    1. Navigate to the examples/GameOfLife/ directory in a command prompt
    2. Run ..\..\bin\x64\Release_Visualisation\GameOfLife.exe iterations\0.xml

Running a Simulation on Linux

Assuming the GameOfLife example has been compiled for visualisation, there are several options for running the example.

  1. Run the included bash script in bin/linux-x64/: GameOfLife_visualisation.sh
  2. Run the executable directly with an initial states file
    1. Navigate to the examples/GameOfLife/ directory
    2. Run ../../bin/linux-x64/Release_Visualisation/GameOfLife iterations/0.xml

How to Contribute

To report FLAME GPU bugs or request features, please file an issue directly using Github. If you wish to make any contributions, please issue a Pull Request on Github.

Publications

Please cite FLAME GPU using

@article{richmond2010high,
  doi={10.1093/bib/bbp073},
  title={High performance cellular level agent-based simulation with FLAME for the GPU},
  author={Richmond, Paul and Walker, Dawn and Coakley, Simon and Romano, Daniela},
  journal={Briefings in bioinformatics},
  volume={11},
  number={3},
  pages={334--347},
  year={2010},
  publisher={Oxford Univ Press}
}

For an up to date list of publications related to FLAME GPU and it's use, visit the flamegpu.com website.

Authors

FLAME GPU is developed as an open-source project by the Visual Computing research group in the Department of Computer Science at the University of Sheffield. The primary author is Dr Paul Richmond.

Copyright and Software Licence

FLAME GPU is copyright the University of Sheffield 2009 - 2018. Version 1.5.X is released under the MIT open source licence. Previous versions were released under a University of Sheffield End User licence agreement.

Release Notes

1.5.0

  • Documentation now hosted on readthedocs, http://docs.flamegpu.com and https://github.com/flamegpu/docs
  • Supports CUDA 8 and CUDA 9
    • Removed SM20 and SM21 support from the default build settings (Deprecated / Removed by CUDA 8.0 / 9.0)
  • Graph communication for agents with new example
  • Updated Visual Studio version to 2015
  • Improved linux support by upgraded Makefiles
  • Additional example projects
  • Template example has been renamed EmptyExample
  • tools/new_example.py to quickly create a new example project.
  • Various bugfixes
  • Adds step-functions
  • Adds host-based agent creation for init and step functions
  • Adds parallel reductions for use in init, step and exit functions
  • Additional command line options
  • Environmental variables can now be loaded from 0.xml
  • Adds the use of colour agent variable to control agent colour in the default visualisation
  • Additional controls for the default visualisation
  • Macro definitions for default visualisation colours
  • Macro definitions for message partitioning strategy
  • Adds instrumentation for simple performance measurement via preprocessor macros
  • Improved functions.xslt output for generating template functions files.
  • Improved state model diagram generator

1.4.3

  • Updated Circles Example
  • Purged binaries form history, reducing repository size
  • Updated Visual Studio Project files to 2013
  • Improved Visual Studio build customisation
  • Fixed double precision support within spatial partitioning
  • Compile-time spatial partition configuration validation

1.4.2

  • Added support for continuous agents reading discrete messages.

1.4.1

  • Minor bug fixes and added missing media folder

1.4.0

  • FLAME GPU 1.4 for CUDA 7 and Visual Studio 2012

##Problem reports

To report a bug in this documentation or in the software or propose an improvement, please use the FLAMEGPU GitHub issue tracker.

docs's People

Contributors

cmoralesmx avatar coolmule0 avatar dentarthur avatar mileach avatar mondus avatar mozhgan-kch avatar ptheywood avatar robadob avatar willfurnass avatar

Stargazers

avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar

Forkers

willfurnass coolmule0 ptheywood cmoralesmx mileach thecapitalistcycle

docs's Issues

Describe host agent creation

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).

Quircks of Discrete Messaging with Different Radii

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.

Message Wrapping

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

Agent Type and Message Partitioning Table (or list)

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

I.e

Message Type Continuous Agents Discrete Agents
partitioningNone Yes No
partitioningDiscrete No Yes
partitioningSpatial Yes No

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

Document accessing agent array data.

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);

Graph based communication

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

Current RTD builds failing

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

Host access of agent variables (1.5)

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

Vector and Unsigned Types

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

Various Updates for 1.5

  • 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

RNG

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).

Document early_exit functions

Document get_exit_early() and set_exit_early()

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

min and max analytics functions

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.

Parameter Exploration Example

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)

Example Creation documentation

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)

RTD Badge

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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.