In January 2021 we will introduce a 10 GB quota for project repositories. Higher limits for individual projects will be available on request. Please see https://doku.lrz.de/display/PUBLIC/GitLab for more information.

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

---

Daniel Lehmberg's avatar
Daniel Lehmberg committed
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

11
Vadere has been developed by [Prof. Dr. Gerta Köster's](http://www.cs.hm.edu/die_fakultaet/ansprechpartner/professoren/koester/index.de.html)
Jakob Schöttl's avatar
Jakob Schöttl committed
12 13
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. 

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
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/wikis/eikmesh/Overview). 
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
## Installation

27
### Download Releases
Daniel Lehmberg's avatar
Daniel Lehmberg committed
28

Daniel Lehmberg's avatar
Daniel Lehmberg committed
29 30 31 32 33
Latest build of master:
* [Windows](http://www.vadere.org/builds/master/vadere.master.windows.zip)
* [Linux](http://www.vadere.org/builds/master/vadere.master.linux.zip)

Stable releases and selected branch-builds are located on [www.vadere.org/releases/](http://www.vadere.org/releases/)
Daniel Lehmberg's avatar
Daniel Lehmberg committed
34

35 36
The ZIP file contains:
* **README.md** - this README file. 
37 38
* **vadere-gui.jar** - provides the GUI version of Vadere.
* **vadere-console.jar** - provides the command line version of Vadere and allows easy integration into other applications.
Daniel Lehmberg's avatar
Daniel Lehmberg committed
39 40
* **VadereModelTests** - contains test scenarios for pedestrian locomotion models. Note: The tests are also useful for a "getting started" (see below "Run Built-In Examples" for details).

Daniel Lehmberg's avatar
Daniel Lehmberg committed
41
To execute the `.jar` files it is highly recommended to use Java 11 (OpenJDK).  
Daniel Lehmberg's avatar
Daniel Lehmberg committed
42

43
### Build from Source
Daniel Lehmberg's avatar
Daniel Lehmberg committed
44 45

#### Dependencies
Felix Dietrich's avatar
Felix Dietrich committed
46

Daniel Lehmberg's avatar
Daniel Lehmberg committed
47
* Java 11 (OpenJDK recommended)
Felix Dietrich's avatar
Felix Dietrich committed
48 49
* Maven 3.0
* Git
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
50
* OpenCL (optional but recommended)
Felix Dietrich's avatar
Felix Dietrich committed
51

52 53
**Note:** Please, ensure that the Git executable can be found in the `PATH` variable of your operating system.

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
54
#### Install OpenCL (optional but recommended)
Felix Dietrich's avatar
Felix Dietrich committed
55

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
56
Vadere uses computer's video card to speed up some computations. Therefore, following OpenCL components should be installed:
Felix Dietrich's avatar
Felix Dietrich committed
57

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
58
* the OpenCL Installable Client Driver loader also called ICD loader (Opencl.dll for Windows and libOpenCL.so for Linux)
59 60 61 62
* drivers for your device(s) 

Both should be offered by the vendor of your device (often there are also open-source solutions). The device can be a CPU as well as a GPU (recommanded). For example, if you have a NVIDIA GPU instaling your drivers should be enough to install both components. 
Vadere will search for the best suiable device which is supported. On a desktop workstation this should be your video card (GPU). If there is no device supporting OpenCL Vadere will use a plain and slower Java-implementation instead. 
Felix Dietrich's avatar
Felix Dietrich committed
63

64
Please, use following instructions to set up the OpenCL components for your operating system:
Felix Dietrich's avatar
Felix Dietrich committed
65

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
66
* Windows: For further information using OpenCL on Windows read the paragraph Running an OpenCL application [click here](https://streamcomputing.eu/blog/2015-03-16/how-to-install-opencl-on-windows/).
Felix Dietrich's avatar
Felix Dietrich committed
67
* OS X: OpenCL is pre-installed for OS X.
68 69
* Linux: Please refer to the installation manual of your Linux distribution. 
  * [Sources: OpenCL HowTo](https://wiki.tiker.net/OpenCLHowTo)
Daniel Lehmberg's avatar
Daniel Lehmberg committed
70 71 72 73 74 75 76 77 78 79 80 81 82
  * Tips and official packages (Ubuntu): 
    
    <details>

    * Use the console tool `clinfo` (`sudo apt-get install clinfo`) to see the current status in terminal
    * Drivers commonly have the prefix `opencl-icd` (to look at most opencl related packages run `apt search opencl`). Some that may be helpful:
         * `beignet-opencl-icd` (OpenCL library for Intel GPUs)
         * `mesa-opencl-icd` (free and open source implementation of the OpenCL API)
         * `nvidia-opencl-icd`
         * `ocl-icd-opencl-dev` (installs opencl development files and can be required for compiling)
         * `ocl-icd-libopencl1` (Generic OpenCL ICD Loader)
    
    </details>
83
  * [Intel Driverpack (only driver needed)](https://software.intel.com/en-us/articles/opencl-drivers#latest_linux_driver)
Felix Dietrich's avatar
Felix Dietrich committed
84

Daniel Lehmberg's avatar
Daniel Lehmberg committed
85
#### Run the Application
Felix Dietrich's avatar
Felix Dietrich committed
86

87
1. Get the Source: Run `git clone https://gitlab.lrz.de/vadere/vadere.git`.
Daniel Lehmberg's avatar
Daniel Lehmberg committed
88
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`, `vadere-console.jar` and `postvis.jar`.
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
89 90
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
91

Daniel Lehmberg's avatar
Daniel Lehmberg committed
92
## Run Built-In Examples
Felix Dietrich's avatar
Felix Dietrich committed
93

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
94
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
95 96 97

- start Vadere 
- *Project* > *Open* 
98
- choose `vadere.project` of one of the projects e.g. [TestOSM](https://gitlab.lrz.de/vadere/vadere/tree/master/VadereModelTests/TestOSM) and click *open*
Felix Dietrich's avatar
Felix Dietrich committed
99 100
- select the scenario on the left and press *run selected scenario*

101 102
## Changelog

103
See [CHANGELOG.md](https://gitlab.lrz.de/vadere/vadere/blob/master/CHANGELOG.md) for a list of changes.
Felix Dietrich's avatar
Felix Dietrich committed
104

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
105 106
## JavaDoc

Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
107
- [state](http://www.vadere.org/javadoc/state/index.html)
Benedikt Zoennchen's avatar
Benedikt Zoennchen committed
108

109 110
## Contribution

111
See [CONTRIBUTING.md](https://gitlab.lrz.de/vadere/vadere/blob/master/CONTRIBUTING.md) for how to set up the development environment and the coding guidelines.
112

Felix Dietrich's avatar
Felix Dietrich committed
113 114
## License

115
This software is licensed under the GNU Lesser General Public License ([LGPL](https://gitlab.lrz.de/vadere/vadere/blob/master/LICENSE)).
Felix Dietrich's avatar
Felix Dietrich committed
116

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