Skip to content

Commit dd78644

Browse files
author
Sami Hatna
committed
Merge branch 'readme+license' into 'main'
readme + license See merge request sami.hatna/crowd-simulation!7
2 parents 655c6be + abea209 commit dd78644

28 files changed

+742
-4
lines changed

‎CMakeLists.txt

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
1+
# Copyright (C) 2022 Codeplay Software Ltd.
12
cmake_minimum_required (VERSION 3.21.0)
23

34
set(CMAKE_CXX_STANDARD 17)
45
set(CMAKE_CXX_STANDARD_REQUIRED True)
56

67
project(crowd-simulation)
78

8-
set(CMAKE_C_COMPILER /home/sami/sycl_workspace/llvm/build/bin/clang)
9-
set(CMAKE_CXX_COMPILER /home/sami/sycl_workspace/llvm/build/bin/clang++)
10-
119
OPTION(PROFILING_MODE "Enable profiling" off)
1210
if(PROFILING_MODE)
1311
add_definitions(-DPROFILING_MODE)

‎LICENSE.txt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright 2022 Codeplay Software Ltd.
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use these files except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎README.md

Lines changed: 124 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,125 @@
1-
# Crowd-Simulation
1+
# SYCL-Crowd-Simulation
22

3+
SYCL GPU-accelerated crowd simulation engine based on Helbing et. al.'s social force model.
4+
5+
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.
6+
7+
## Features
8+
9+
- Performantly simulate tens of thousands of actors in real time
10+
- Define different crowds with different characteristics and different destinations
11+
- Define rooms and obstacles
12+
- Fully configurable environments (see [Input Format](#input-format))
13+
- Record and graph simulation metrics
14+
- Target and build for multiple SYCL supported backends
15+
- Apply a force heatmap across actors
16+
- The simulation kernels may be used separately from the GUI
17+
18+
## Dependencies
19+
20+
- The [DPC++ compiler](https://intel.github.io/llvm-docs/GetStartedGuide.html) is required to compile SYCL code
21+
- 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
22+
- If targeting the DPC++ OpenCL backend, an [OpenCL runtime](https://intel.github.io/llvm-docs/GetStartedGuide.html#install-low-level-runtime) is required
23+
- Graphics are rendered with [SDL2](https://lazyfoo.net/tutorials/SDL/01_hello_SDL/linux/index.php), installed with apt: `$ apt install libsdl2-dev`
24+
- Input files are parsed using [RapidJSON](https://rapidjson.org/index.html)
25+
RapidJSON is a header-only library, so can be installed by simply copying the directory `include/rapidjson` into your system include path
26+
- Python is needed to run scripts
27+
- Graphs are plotted using matplotlib, installed via pip: `$ pip install matplotlib`
28+
- 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
29+
30+
## Building
31+
32+
Build configuration is carried out using CMake.
33+
34+
The option `-DSYCL_BACKEND` allows you to select which backend to build for (spir, cuda or hip). By default, it builds for spir.
35+
36+
When enabled, the `-DPROFILING_MODE` option builds a headless version which can be run without the SDL dependency.
37+
38+
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).
39+
40+
By default, CMake should generate example input files by running [InputFileGenerator.py](scripts/InputFileGenerator.py) when generating the project makefiles.
41+
42+
The `crowdsim` executable takes an input configuration JSON as a command line argument.
43+
44+
```
45+
$ git clone https://[repo link]
46+
$ cd crowd-simulation
47+
$ mkdir build && cd build
48+
$ cmake -DCMAKE_CXX_COMPILER=path/to/llvm/build/bin/clang++ -DSYCL_BACKEND=spir -DPROFILING_MODE=off -DSTATS=on ..
49+
$ cmake --build .
50+
$ ./crowdsim ../input/evacuateRoom.json
51+
```
52+
53+
## Input Format
54+
55+
Below is an annotated example input file which creates a room containing two actors with two different destinations.
56+
57+
```
58+
{
59+
"config": { <-- Configure environment
60+
"width": 9,
61+
"height": 9,
62+
"scale": 100,
63+
"delay": 0,
64+
"bgColor": [0, 0, 0],
65+
"wallColor": [255, 255, 255]
66+
},
67+
68+
"room": {
69+
"walls": [
70+
[0.5, 0.5, 8.5, 0.5], <-- Walls are defined via their
71+
[8.5, 0.5, 8.5, 8.5], start and end points
72+
[8.5, 8.5, 0.5, 8.5],
73+
[0.5, 8.5, 0.5, 0.5]
74+
]
75+
},
76+
77+
"actors": [ <-- Populate environment with
78+
{ actors
79+
"pos": [3.4, 5.6],
80+
"velocity": [0.0123, 0.0567],
81+
"desiredSpeed": 0.6,
82+
"pathId": 0,
83+
"mass": 50,
84+
"radius": 0.05,
85+
"atDestination": false,
86+
"color": [255, 0, 0],
87+
"heatmapEnabled": true <-- Flag denoting whether the
88+
}, actor's colour should change
89+
{ with the heatmap
90+
"pos": [0.7, 7.3],
91+
"velocity": [0.0789, 0.0444],
92+
"desiredSpeed": 0.6,
93+
"pathId": 1,
94+
"mass": 45,
95+
"radius": 0.06,
96+
"atDestination": false,
97+
"color": [0, 255, 0],
98+
"heatmapEnabled": true
99+
}
100+
],
101+
102+
"paths": [
103+
{
104+
"id": 0, <-- Each path has a unique id,
105+
"checkpoints": [[[7.9, 5.6], [8.1, 5.8]]] referenced by any actor which
106+
}, takes that path
107+
{
108+
"id": 1,
109+
"checkpoints": [[[7.9, 5.6], [8.1, 5.8]], <-- Paths consist of checkpoints
110+
[[1.5, 2], [1.7, 2.2]]] Each checkpoint is a rectangular
111+
} region defined as:
112+
] [[minX, minY], [maxX, maxY]]
113+
}
114+
```
115+
116+
Larger input configurations can be generated with python scripts, as demonstrated in [InputFileGenerator.py](scripts/InputFileGenerator.py).
117+
118+
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.
119+
120+
## Benchmarks
121+
122+
## Citations
123+
124+
- Helbing, D., Farkas, I. & Vicsek, T. Simulating dynamical features of escape panic. Nature 407, 487–490 (2000). https://doi.org/10.1038/35035023
125+
- Marsaglia, G. (2003). Xorshift RNGs. Journal of Statistical Software, 8(14), 1–6. https://doi.org/10.18637/jss.v008.i14

‎external/Actor.cpp

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* Actor.cpp
20+
*
21+
* Description:
22+
* Class denoting an actor in social force model
23+
*
24+
**************************************************************************/
25+
126
#include "Actor.hpp"
227

328
Actor::Actor(vecType pPos, vecType pVelocity, float pDesiredSpeed, int pPathId,

‎external/Actor.hpp

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* Actor.hpp
20+
*
21+
* Description:
22+
* Class denoting an actor in social force model
23+
*
24+
**************************************************************************/
25+
126
#ifndef Actor_hpp
227
#define Actor_hpp
328

‎external/CMakeLists.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Copyright (C) 2022 Codeplay Software Ltd.
2+
13
add_library(external Actor.cpp
24
Room.cpp
35
Path.cpp

‎external/DifferentialEq.cpp

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* DifferentialEq.cpp
20+
*
21+
* Description:
22+
* Kernel for calculating social forces
23+
*
24+
**************************************************************************/
25+
126
#include "DifferentialEq.hpp"
227

328
SYCL_EXTERNAL void differentialEq(

‎external/DifferentialEq.hpp

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* DifferentialEq.hpp
20+
*
21+
* Description:
22+
* Kernel for calculating social forces
23+
*
24+
**************************************************************************/
25+
126
#ifndef DifferentialEqu_hpp
227
#define DifferentialEqu_hpp
328

‎external/Heatmap.cpp

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* Heatmap.cpp
20+
*
21+
* Description:
22+
* Applying heatmap across actors reflecting how much force they are
23+
* experiencing
24+
*
25+
**************************************************************************/
26+
127
#include "Heatmap.hpp"
228

329
// Required because SDL only takes RGB colors

‎external/Heatmap.hpp

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
1+
/***************************************************************************
2+
*
3+
* Copyright (C) 2022 Codeplay Software Ltd.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*
17+
* Codeplay's crowd-simulation
18+
*
19+
* Heatmap.hpp
20+
*
21+
* Description:
22+
* Applying heatmap across actors reflecting how much force they are
23+
* experiencing
24+
*
25+
**************************************************************************/
26+
127
#ifndef Heatmap_hpp
228
#define Heatmap_hpp
329

0 commit comments

Comments
 (0)