Merge branch 'dummy' into 'Tadej-Review'

Code review

See merge request sami.hatna/crowd-simulation!10

Author: Sami Hatna

.gitignore

@@ -0,0 +1,2 @@
+/.vscode
+/build

CMakeLists.txt

@@ -0,0 +1,49 @@
+# Copyright (C) 2022 Codeplay Software Ltd.
+cmake_minimum_required (VERSION 3.21.0)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
+
+project(crowd-simulation)
+
+OPTION(PROFILING_MODE "Enable profiling" off)
+if(PROFILING_MODE)
+    add_definitions(-DPROFILING_MODE)
+else()
+    find_package(SDL2 REQUIRED)
+    include_directories(${SDL2_INCLUDE_DIRS})
+endif()
+
+OPTION(STATS "Run in stats mode" off)
+if (STATS)
+    add_definitions(-DSTATS)
+endif()
+
+set(SYCL_BACKEND "SYCL_BACKEND" CACHE STRING "Backend chosen by the user at CMake configure time")
+set_property(CACHE SYCL_BACKEND PROPERTY STRINGS spir cuda hip)
+
+if(SYCL_BACKEND STREQUAL hip)
+    SET(CMAKE_CXX_FLAGS  "${CMAKE_CXX_FLAGS} -fsycl -fsycl-targets=amdgcn-amd-amdhsa")
+elseif(SYCL_BACKEND STREQUAL cuda)
+    SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsycl -fsycl-targets=nvptx64-nvidia-cuda")
+else()
+    SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsycl -fsycl-targets=spir64")
+endif()
+
+find_package(Python QUIET)
+if(Python_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/scripts/InputFileGenerator.py")
+    execute_process(COMMAND ${Python_EXECUTABLE} ../scripts/InputFileGenerator.py)
+else()
+    message(WARNING "Unable to generate input configuration files")
+endif()
+
+add_executable(crowdsim src/main.cpp)
+
+add_subdirectory(external)
+
+if (PROFILING_MODE)
+    target_link_libraries(crowdsim PUBLIC external) 
+else()
+    target_link_libraries(crowdsim PUBLIC ${SDL2_LIBRARIES} external)
+endif()
+target_include_directories(crowdsim PUBLIC "${PROJECT_BINARY_DIR}" "${PROJECT_SOURCE_DIR}/external")

LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2022 Codeplay Software Ltd.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use these files except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,126 @@
+# SYCL-Crowd-Simulation
+
+SYCL GPU-accelerated crowd simulation engine based on Helbing et. al.'s social force model.
+
+Dirk Helbing introduced the social force model in a paper in 1995, aimed at modelling the behaviour of crowds using Langevin equations. He proposed a refined model in a 2000 paper, "Simulating Dynamical Features of Escape Panic". Helbing posits that human behaviour in large crowds is determined by three component forces: A personal impulse towards one's destination, the cumulative force exerted by neighbouring people, and the repulsive force of any nearby walls. Together, these forces form the basis of a differential equation which can subsequently be integrated in order to calculate the actor's velocity.
+
+## Features
+
+- Performantly simulate tens of thousands of actors in real time
+- Define different crowds with different characteristics and different destinations 
+- Define rooms and obstacles
+- Fully configurable environments (see [Input Format](#input-format))
+- Record and graph simulation metrics
+- Target and build for multiple SYCL supported backends
+- Apply a force heatmap across actors
+- The simulation kernels may be used separately from the GUI
+
+## Dependencies
+
+- The [DPC++ compiler](https://intel.github.io/llvm-docs/GetStartedGuide.html) is required to compile SYCL code
+- If targeting the DPC++ CUDA backend, the [CUDA runtime](https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain-with-support-for-nvidia-cuda) is required
+- If targeting the DPC++ OpenCL backend, an [OpenCL runtime](https://intel.github.io/llvm-docs/GetStartedGuide.html#install-low-level-runtime) is required
+- Graphics are rendered with [SDL2](https://lazyfoo.net/tutorials/SDL/01_hello_SDL/linux/index.php), installed with apt: `$ apt install libsdl2-dev`
+- Input files are parsed using [RapidJSON](https://rapidjson.org/index.html)  
+RapidJSON is a header-only library, so can be installed by simply copying the directory `include/rapidjson` into your system include path
+- Python is needed to run scripts
+- Graphs are plotted using matplotlib, installed via pip: `$ pip install matplotlib`
+- To run simulations in headless mode and record video output, install [xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) and [ffmpeg](https://ffmpeg.org/download.html) using apt
+
+## Building
+
+Build configuration is carried out using CMake.
+
+The option `-DSYCL_BACKEND` allows you to select which backend to build for (spir, cuda or hip). By default, it builds for spir.
+
+When enabled, the `-DPROFILING_MODE` option builds a headless version which can be run without the SDL dependency.
+
+When enabled, the `-DSTATS` option will collect metrics whilst the simulation is running. Results are written to `output/outputStats`.txt. Graphs can be produced from these metrics by running the python script [PlotGraphs.py](scripts/PlotGraphs.py).
+
+By default, CMake should generate example input files by running [InputFileGenerator.py](scripts/InputFileGenerator.py) when generating the project makefiles.
+
+The `crowdsim` executable takes an input configuration JSON as a command line argument.
+
+```
+$ git clone https://[repo link]
+$ cd crowd-simulation
+$ mkdir build && cd build
+$ cmake -DCMAKE_CXX_COMPILER=path/to/llvm/build/bin/clang++ -DSYCL_BACKEND=spir -DPROFILING_MODE=off -DSTATS=on ..
+$ cmake --build .
+$ ./crowdsim ../input/evacuateRoom.json
+```
+
+## Input Format
+
+Below is an annotated example input file which creates a room containing two actors with two different destinations.
+
+```
+{
+  "config": {                                     <-- Configure environment
+    "width": 9,
+    "height": 9,
+    "scale": 100,                                 
+    "delay": 0,
+    "bgColor": [0, 0, 0],                         
+    "wallColor": [255, 255, 255],
+    "heatmapEnabled": true                        <-- Flag denoting whether 
+  },                                                  the heatmap should be 
+                                                      applied to actors
+  "room": {                                       
+    "walls": [
+      [0.5, 0.5, 8.5, 0.5],                       <-- Walls are defined via their
+      [8.5, 0.5, 8.5, 8.5],                           start and end points
+      [8.5, 8.5, 0.5, 8.5],
+      [0.5, 8.5, 0.5, 0.5]
+    ]                                             
+  },
+                                                  
+  "actors": [                                     <-- Populate environment with
+    {                                                 actors
+      "pos": [3.4, 5.6],
+      "velocity": [0.0123, 0.0567],               
+      "desiredSpeed": 0.6,
+      "pathId": 0,                                
+      "mass": 50,
+      "radius": 0.05,                             
+      "atDestination": false,
+      "color": [255, 0, 0],                       
+      "heatmapEnabled": true 
+    },
+    {
+      "pos": [0.7, 7.3],                          
+      "velocity": [0.0789, 0.0444],
+      "desiredSpeed": 0.6,                        
+      "pathId": 1,
+      "mass": 45,                                 
+      "radius": 0.06,
+      "atDestination": false,                     
+      "color": [0, 255, 0],
+      "heatmapEnabled": true                      
+    }
+  ],                                              
+
+  "paths": [                                      
+    {                                             
+      "id": 0,                                    <-- Each path has a unique id, 
+      "checkpoints": [[[7.9, 5.6], [8.1, 5.8]]]       referenced by any actor which
+    },                                                takes that path
+    {
+      "id": 1,
+      "checkpoints": [[[7.9, 5.6], [8.1, 5.8]],   <-- Paths consist of checkpoints
+                      [[1.5, 2], [1.7, 2.2]]]         Each checkpoint is a rectangular
+    }                                                 region defined as:
+  ]                                                   [[minX, minY], [maxX, maxY]]
+}
+```
+
+Larger input configurations can be generated with python scripts, as demonstrated in [InputFileGenerator.py](scripts/InputFileGenerator.py).
+
+The social force model itself can be tweaked by altering the constexprs defined in [DifferentialEq.hpp](external/DifferentialEq.hpp). For example, in simulations involving large numbers of actors (10,000+), the values `WALLAi` and `PEOPLEAi` will need to be increased to prevent any clipping issues.
+
+## Benchmarks
+
+## Citations
+
+- Helbing, D., Farkas, I. & Vicsek, T. Simulating dynamical features of escape panic. Nature 407, 487–490 (2000). https://doi.org/10.1038/35035023
+- Marsaglia, G. (2003). Xorshift RNGs. Journal of Statistical Software, 8(14), 1–6. https://doi.org/10.18637/jss.v008.i14

external/Actor.cpp

@@ -0,0 +1,101 @@
+/***************************************************************************
+ *
+ *  Copyright (C) 2022 Codeplay Software Ltd.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  Codeplay's crowd-simulation
+ *
+ *  Actor.cpp
+ *
+ *  Description:
+ *    Class denoting an actor in social force model
+ *
+ **************************************************************************/
+
+#include "Actor.hpp"
+
+Actor::Actor(sycl::float2 pPos, sycl::float2 pVelocity, float pDesiredSpeed,
+             int pPathId, float pMass, float pRadius, bool pAtDestination,
+             std::array<int, 3> pColor)
+    : pos(pPos), velocity(pVelocity), desiredSpeed(pDesiredSpeed),
+      pathId(pPathId), mass(pMass), radius(pRadius),
+      atDestination(pAtDestination), color(pColor), destinationIndex(0),
+      bBox({0, 0}) {}
+
+SYCL_EXTERNAL sycl::float2 Actor::getPos() const { return pos; }
+
+SYCL_EXTERNAL sycl::float2 Actor::getVelocity() const { return velocity; }
+
+SYCL_EXTERNAL float Actor::getDesiredSpeed() const { return desiredSpeed; }
+
+SYCL_EXTERNAL int Actor::getPathId() const { return pathId; }
+
+SYCL_EXTERNAL int Actor::getDestinationIndex() const {
+    return destinationIndex;
+}
+
+SYCL_EXTERNAL float Actor::getMass() const { return mass; }
+
+SYCL_EXTERNAL float Actor::getRadius() const { return radius; }
+
+SYCL_EXTERNAL bool Actor::getAtDestination() const { return atDestination; }
+
+SYCL_EXTERNAL std::array<int, 3> Actor::getColor() const { return color; }
+
+SYCL_EXTERNAL std::array<int, 2> Actor::getBBox() const { return bBox; }
+
+SYCL_EXTERNAL uint Actor::getSeed() const { return seed; }
+
+SYCL_EXTERNAL float Actor::getForce() const { return force; }
+
+SYCL_EXTERNAL void Actor::setPos(sycl::float2 newPos) { pos = newPos; }
+
+SYCL_EXTERNAL void Actor::setVelocity(sycl::float2 newVelocity) {
+    velocity = newVelocity;
+}
+
+SYCL_EXTERNAL void Actor::setDesiredSpeed(float newDesiredSpeed) {
+    desiredSpeed = newDesiredSpeed;
+}
+
+SYCL_EXTERNAL void Actor::setAtDestination(bool param) {
+    atDestination = param;
+}
+
+SYCL_EXTERNAL void Actor::setColor(std::array<int, 3> newColor) {
+    color = newColor;
+}
+
+SYCL_EXTERNAL void Actor::setBBox(std::array<int, 2> newBBox) {
+    bBox = newBBox;
+}
+
+SYCL_EXTERNAL void Actor::setSeed(uint newSeed) { seed = newSeed; }
+
+SYCL_EXTERNAL void Actor::setForce(float newForce) { force = newForce; }
+
+SYCL_EXTERNAL void
+Actor::checkAtDestination(std::array<sycl::float2, 2> destination,
+                          int pathSize) {
+    // Destinations are defined as rectangular regions
+    if (pos[0] >= destination[0][0] && pos[0] <= destination[1][0] &&
+        pos[1] >= destination[0][1] && pos[1] <= destination[1][1]) {
+        if (destinationIndex >= PATHALLOCATIONSIZE - 1 ||
+            destinationIndex >= pathSize - 1) {
+            this->setAtDestination(true);
+        } else {
+            destinationIndex++;
+        }
+    }
+}

external/Actor.hpp

@@ -0,0 +1,83 @@
+/***************************************************************************
+ *
+ *  Copyright (C) 2022 Codeplay Software Ltd.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  Codeplay's crowd-simulation
+ *
+ *  Actor.hpp
+ *
+ *  Description:
+ *    Class denoting an actor in social force model
+ *
+ **************************************************************************/
+
+#ifndef Actor_hpp
+#define Actor_hpp
+
+#include "Path.hpp"
+#include "RandomNumber.hpp"
+#include <array>
+#include <iostream>
+#include <random>
+#include <sycl/sycl.hpp>
+#include <vector>
+
+class Actor {
+  private:
+    std::array<int, 3> color;
+    sycl::float2 pos;
+    sycl::float2 velocity;
+    std::array<int, 2> bBox;
+    float desiredSpeed;
+    int pathId;
+    int destinationIndex;
+    float mass;
+    float radius;
+    uint seed;
+    float force;
+    bool atDestination;
+
+  public:
+    Actor(sycl::float2 pPos, sycl::float2 pVelocity, float pdesiredSpeed,
+          int pPathId, float pMass, float pRadius, bool pAtDestination,
+          std::array<int, 3> pColor);
+
+    SYCL_EXTERNAL sycl::float2 getPos() const;
+    SYCL_EXTERNAL sycl::float2 getVelocity() const;
+    SYCL_EXTERNAL float getDesiredSpeed() const;
+    SYCL_EXTERNAL int getPathId() const;
+    SYCL_EXTERNAL int getDestinationIndex() const;
+    SYCL_EXTERNAL float getMass() const;
+    SYCL_EXTERNAL float getRadius() const;
+    SYCL_EXTERNAL bool getAtDestination() const;
+    SYCL_EXTERNAL std::array<int, 3> getColor() const;
+    SYCL_EXTERNAL std::array<int, 2> getBBox() const;
+    SYCL_EXTERNAL uint getSeed() const;
+    SYCL_EXTERNAL float getForce() const;
+
+    SYCL_EXTERNAL void setPos(sycl::float2 newPos);
+    SYCL_EXTERNAL void setVelocity(sycl::float2 newVelocity);
+    SYCL_EXTERNAL void setDesiredSpeed(float newDesiredSpeed);
+    SYCL_EXTERNAL void setAtDestination(bool param);
+    SYCL_EXTERNAL void setColor(std::array<int, 3> newColor);
+    SYCL_EXTERNAL void setBBox(std::array<int, 2> newBBox);
+    SYCL_EXTERNAL void setSeed(uint newSeed);
+    SYCL_EXTERNAL void setForce(float newForce);
+
+    SYCL_EXTERNAL void
+    checkAtDestination(std::array<sycl::float2, 2> destination, int pathSize);
+};
+
+#endif

external/CMakeLists.txt

@@ -0,0 +1,12 @@
+# Copyright (C) 2022 Codeplay Software Ltd.
+
+add_library(external Actor.cpp 
+                     Room.cpp 
+                     Path.cpp 
+                     MathHelper.cpp 
+                     DifferentialEq.cpp 
+                     Heatmap.cpp 
+                     ParseInputFile.cpp 
+                     RandomNumber.cpp 
+                     Stats.cpp
+            )