Currently job artifacts in CI/CD pipelines on LRZ GitLab never expire. Starting from Wed 26.1.2022 the default expiration time will be 30 days (GitLab default). Currently existing artifacts in already completed jobs will not be affected by the change. The latest artifacts for all jobs in the latest successful pipelines will be kept. More information: https://gitlab.lrz.de/help/user/admin_area/settings/continuous_integration.html#default-artifacts-expiration

README.md 5.45 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. VADERE provides generic model classes and visualisation and data analysis tools for two-dimensional systems. A series of pedestrian locomotion 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. In addition to pedestrians, other systems including cars and granular flow can be introduced into the framework.
Felix Dietrich's avatar
Felix Dietrich committed
8

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

Jakob Schöttl's avatar
Jakob Schöttl committed
11
12
13
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/).
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
14
15
However, we welcome contributions from external sources. 

16
The VADERE framework includes a mesh generator for unstructured high-quality 2D meshes called **EikMesh** which is described [here](https://gitlab.lrz.de/vadere/vadere/blob/master/VadereMeshing/README.md). 
Felix Dietrich's avatar
Felix Dietrich committed
17

18
19
## Pipeline Status

20
21
| Branch  | Pipeline Status  | Coverage |
|:--------|:----------------:|:--------:| 
Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
22
| 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) |
23
| stable | [![pipeline status (stable)](https://gitlab.lrz.de/vadere/vadere/badges/stable/pipeline.svg)](https://gitlab.lrz.de/vadere/vadere/commits/stable) | [![coverage report (stable)](https://gitlab.lrz.de/vadere/vadere/badges/stable/coverage.svg)](https://gitlab.lrz.de/vadere/vadere/commits/stable) |
24

Felix Dietrich's avatar
Felix Dietrich committed
25
26
27
28
29
30
31
32
33
34
35
## Installation

### Dependencies

* Java 8
* Maven 3.0
* Git
* OpenCL

### Install OpenCL

36
VADERE uses computer's video card to speed up some computations. Therefore, following OpenCL components must be installed:
Felix Dietrich's avatar
Felix Dietrich committed
37
38
39
40

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

41
Please, use following instructions to set up the OpenCL components for your operating system:
Felix Dietrich's avatar
Felix Dietrich committed
42
43
44

* 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.
45
46
47
* 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
48

49
## Run the Application
Felix Dietrich's avatar
Felix Dietrich committed
50

51
1. Get the Source: Run `git clone https://gitlab.lrz.de/vadere/vadere.git`.
Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
52
2. Build the Application: Go to the project directory and run `mvn clean package` (or `mvn clean package -Dmaven.test.skip` if you want to skip the unit tests). This will build `vadere.jar`and `postvis.jar`. 
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
53
54
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
55

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
56
### Run Built-In Examples
Felix Dietrich's avatar
Felix Dietrich committed
57

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
58
With the following steps, you can run a simulation with one of the built-in examples from [VadereModelTests](VadereModelTests):
Felix Dietrich's avatar
Felix Dietrich committed
59
60
61

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

65
### Use Git Hooks
66

67
68
69
70
71
72
73
74
75
76
77
78
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.

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

82
83
84
## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
Felix Dietrich's avatar
Felix Dietrich committed
85

86
87
88
89
## Contribution

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the development environment and the coding guidelines.

Felix Dietrich's avatar
Felix Dietrich committed
90
91
92
93
## License

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

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