README.md 6.63 KB
Newer Older
1
![VADERE](vadere.png "VADERE")
Felix Dietrich's avatar
Felix Dietrich committed
2
3
4

---

5
# VADERE
Felix Dietrich's avatar
Felix Dietrich committed
6

7
VADERE is an open source framework for the simulation of microscopic pedestrian dynamics. In addition to this core domain, other systems including cars and granular flow can be introduced into the framework. VADERE provides generic model classes and visualisation and data analysis tools for two-dimensional systems. A series of simulation models are already implemented in the framework that are also the basis for scientific publications. Namely the optimal steps model, the gradient navigation model, and the social force model are available for simulation studies.
Felix Dietrich's avatar
Felix Dietrich committed
8

9
This software runs on OS X, Windows, and Linux.
Felix Dietrich's avatar
Felix Dietrich committed
10

Jakob Schöttl's avatar
Jakob Schöttl committed
11
12
13
14
VADERE has been developed by [Prof. Dr. Gerta Köster's](http://www.cs.hm.edu/die_fakultaet/ansprechpartner/professoren/koester/index.de.html)
research group at the [Munich University of Applied Sciences](https://www.hm.edu/) at the
[department for Computer Science and Mathematics](http://cs.hm.edu/).
However, we welcome contributions from external sources.
Felix Dietrich's avatar
Felix Dietrich committed
15

16
17
## Pipeline Status

18
19
| Branch  | Pipeline Status  | Coverage |
|:--------|:----------------:|:--------:| 
Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
20
21
| master  | [![pipeline status (master)](https://gitlab.lrz.de/vadere/vadere/badges/master/pipeline.svg)](https://gitlab.lrz.de/vadere/vadere/commits/master) | [![coverage report (master)](https://gitlab.lrz.de/vadere/vadere/badges/master/coverage.svg)](https://gitlab.lrz.de/vadere/vadere/commits/master) |
| develop | [![pipeline status (develop)](https://gitlab.lrz.de/vadere/vadere/badges/develop/pipeline.svg)](https://gitlab.lrz.de/vadere/vadere/commits/develop) | [![coverage report (develop)](https://gitlab.lrz.de/vadere/vadere/badges/develop/coverage.svg)](https://gitlab.lrz.de/vadere/vadere/commits/develop) |
22

Felix Dietrich's avatar
Felix Dietrich committed
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
## Installation

### Dependencies

* Java 8
* Maven 3.0
* Git
* OpenCL

### Install OpenCL

For this project, GPGPU with OpenCL is used to speed up some computations. Therefore, the following requirements have to be met:

* the latest drivers for your OpenCL device(s)
* an OpenCL SDK

#### Operating Systems

* Windows: For further information using OpenCL on Windows [click here](https://streamcomputing.eu/blog/2015-03-16/how-to-install-opencl-on-windows/).
* OS X: OpenCL is pre-installed for OS X.
43
44
45
* Linux: Please refer to the installation manual of your Linux distribution. 
  * [Sources: OpenCL HowTo](https://wiki.tiker.net/OpenCLHowTo)
  * [Intel Driverpack (only driver needed)](https://software.intel.com/en-us/articles/opencl-drivers#latest_linux_driver)
Felix Dietrich's avatar
Felix Dietrich committed
46

47
### Run the Application
Felix Dietrich's avatar
Felix Dietrich committed
48

49
1. Get the Source: Run `git clone https://gitlab.lrz.de/vadere/vadere.git`.
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
50
51
52
2. Build the Application: Go to the project directory and run `mvn clean package` (or `mvn clean package -DskipTests` if you want to skip the unit tests). This will build `vadere.jar`and `postvis.jar`. 
3. Start the Application: After building the application, you can start Vadere by running `java -jar VadereGui/target/vadere.jar`.
4. (If you only want to use the Postvisualization-Tool you can do so by running `java -jar VadereGui/target/postvis.jar`).
Felix Dietrich's avatar
Felix Dietrich committed
53

54
## Usage Example
Felix Dietrich's avatar
Felix Dietrich committed
55

56
With the following steps, you can start a scenario of one of the model test projects in [VadereModelTests](VadereModelTests):
Felix Dietrich's avatar
Felix Dietrich committed
57
58
59

- start Vadere 
- *Project* > *Open* 
60
- choose `vadere.project` of one of the projects e.g. [TestOSM](VadereModelTests/TestOSM) and click *open*
Felix Dietrich's avatar
Felix Dietrich committed
61
62
63
64
65
- select the scenario on the left and press *run selected scenario*


## Development Setup

66
Follow the **installation instructions** above i.e. install all required software and get the source. Go to the project directory and run `mvn clean install`. The project can now be imported *As Maven Project* in your IDE.
Felix Dietrich's avatar
Felix Dietrich committed
67
68
69
70
71

### Eclipse

- *File* > *Import* > *Maven* > *Existing Maven Projects*
- choose `pom.xml` as *Root Directory* and click *Finish*
72
- open *Vaderegui (gui)* > *src* > *org.vadere.gui.projectview* > `Vadereapplication`
Felix Dietrich's avatar
Felix Dietrich committed
73
74
75

### IntelliJ IDEA

76
- on the welcome-screen select *Import Project*
Felix Dietrich's avatar
Felix Dietrich committed
77
- select `pom.xml` > *Next* > *Next* > *Next* > *Finish*
78
- open *VadereGui (gui)* > *src* > *org.vadere.gui.projectview* > `VadereApplication`
Felix Dietrich's avatar
Felix Dietrich committed
79
80
81
82
- click the *run*-icon next to the `main` method

Alternatively, run `mvn eclipse:eclipse` using the [Maven Eclipse Plugin](http://maven.apache.org/plugins/maven-eclipse-plugin/usage.html) or `mvn idea:idea` using the [Maven IntelliJ Plugin](http://maven.apache.org/plugins/maven-idea-plugin/).

83
84
### Git Hooks

85
86
87
88
89
90
91
92
93
94
95
96
Since it is important to reproduce simulation results, we have the guidline that each output file has to provide its commit-hash. This commit-hash identifies
the state the software was in when the output file was generated. Therefore, git hooks save the commit-hash in the **current_commit_hash.txt** which
will be created in the [VadereSimulator/resource](vadere/VadereSimulator/resource) directory whenever a commit is made or the developer
switches to another commit. If the file is missing or there is no commit-hash in it, you will be warned in the log. 
We strongly suggest that you install these git hooks on your local machine:

1. Copy files [post-checkout](Documentation/version-control/post-checkout), [post-merge](Documentation/version-control/post-merge), 
[post-applypatch](Documentation/version-control/post-applypatch) and [post-commit](Documentation/version-control/post-commit) 
from [version-control](Documentation/version-control) to your local **.git/hooks/** directory.
These files start the script [git-hook-vadere-software](Documentation/version-control/git-hook-vadere-software).
2. Make sure that [git-hook-vadere-software](Documentation/version-control/git-hook-vadere-software) is executable.

97
To create the **current_commit_hash.txt** without changes to the current commit, you can choose *Switch/Checkout...* on the Repository folder or you 
98
switch to another branch and switch back again using the command line or any other tool you prefer.
99

Felix Dietrich's avatar
Felix Dietrich committed
100
101
## Contribution

Jakob Schöttl's avatar
Jakob Schöttl committed
102
Please see [Contribution guidelines](CONTRIBUTING.md). The document defines guidelines for coding style and commit messages.
Felix Dietrich's avatar
Felix Dietrich committed
103
104
105

## Release History

106
107
- 0.1 initial release of the software as open source (2016-08-05)
- 0.2 stability and usability improved, additional pedestrian simulation models are supported (2016-12-22)
Marion Goedel's avatar
Marion Goedel committed
108
109
- 
- 0.6 [Description to be added... ] (2018-09-07)
Felix Dietrich's avatar
Felix Dietrich committed
110
111
112
113
114

## Contributors

People who have contributed code to the project at the Munich University of Applied Sciences (in alphabetical order):

115
Florian Albrecht, Benjamin Degenhart, Felix Dietrich, Benedikt Kleinmeier, Jakob Schöttl, Michael Seitz, Swen Stemmer, Isabella von Sivers, Mario Teixeira Parente, Peter Zarnitz, Benedikt Zönnchen
Felix Dietrich's avatar
Felix Dietrich committed
116
117
118
119
120

## License

This software is licensed under the GNU Lesser General Public License ([LGPL](LICENSE)).

121
For more information: http://www.gnu.org/licenses/lgpl.html