README.md
1SynChrono
2==============
3
4## Table of Contents
5
6- [Project Overview](#Project-Overview)
7- [General SynChrono Process](#General-SynChrono-Process)
8- [Building and Running](#Building-and-Running)
9- [Implementation Specific Details](#Implementation-Specific-Details)
10- [Other](#Other)
11
12## Project Overview
13
14SynChrono is an autonomous vehicle simulation project developed by the Simulation Based Engineering Lab ([SBEL](https://sbel.wisc.edu/)) at the University of Wisconsin-Madison.
15This simulation framework is based around the ability to simulation one or multiple robots, autonomous vehicles, or other autonomous agents together in a unified framework.
16Our current motivation comes from autonomous vehicle testing, so many of our demos and examples will draw on autonomous vehicles, but since the simulation is backed by Chrono, we can support any virtual environment.
17
18Our goal is to extend Project Chrono's physics simulation into the multi-agent realm, specifically the multi-agent realm where the dynamics of the agents are not strongly coupled.
19For a simulation of say two robots underwater, where the currents created by one robot will impact the dynamics of the other robot, you are better off in Chrono, where the robots and the fluid will be contained together in a single Chrono model and where the dynamics will be jointly simulated.
20SynChrono is suited for scenarios where the dynamics of each agent are important individually, but not in the way that they interact with each other.
21This is the case for autonomous vehicles where, barring a collision, the dynamics of one vehicle will not impact any other.
22SynChrono synchronizes the motion of all agents, but allows their dynamics to be distributed across computing nodes rather than including all dynamics in one monolithic simulation.
23
24## General SynChrono Process
25
261. Environment setup
27 - Find an environment mesh: e.g. surface data for the specific roads or terrain your agent will move on)
28 - Obtain agents: Chrono::Vehicle provides many vehicle models but you can of course create your own in Chrono
29 - Define environment parameters: How many agents? What types are they? Where will they be? How long will the simulation run for? Will they have sensors? etc...
302. Consult the agent's controller
31 - Each agent has a controller that tells it what to do, provided some inputs from the world around it.
32 - For a vehicle the outputs will be the thrust, braking and steering driving parameters, and the input can be anything accessible to simulation.
33 - There may be messages received from e.g. a stoplight.
34 - There may be data received from sensors e.g. GPS coordinates, lidar point clouds
35 - Controllers can be whatever the user would like and the goal of the SynChrono project is not to develop any particular controller, but rather to develop an environment where others can test their algorithms.
36 - SynChrono does currently provide some simple controllers such as a controller that will follow a path defined by GPS coordinates and maintain an appropriate following distance to any vehicles ahead of it based on lidar data.
373. Run Chrono simulation
38 - Each computing node starts up starts running a Chrono simulation for the agent(s) it is responsible for.
39 - It will run this simulation until it gets to the next "heartbeat" or synchronization timestep.
40 - This step 1 is the same as a normal Chrono simulation, iterating a particular system's dynamics for a particular number of timesteps
41 - For a vehicle this would be taking the thrust, braking, steering and computing how much the wheels will turn, how far the center of mass will travel, etc...
42 - Further Chrono specific details can be found on the Project Chrono [website](http://www.projectchrono.org/).
434. Send state data to controller
44 - Having computed its state at the particular heartbeat, each agent now communicates its state to the central controller so that the control can synchronize all agents
45 - For a vehicle the state is just the locations and rotation angle of each of the wheels, for a stoplight it may just be the current color of the light, for a complex robot the state may be a large collection of the positions and rotations of each component of the robot.
465. Synchronize all agents
47 - The central controller collects state data from every agent and sends it to every other agent in the simulation
48 - Each agent will create a "zombie" version of all other agents.
49 - The dynamics for this zombie agent will not be simulated, it will just be placed in the world as a visual mesh so that the real agent can compute accurate sensor data.
506. Rinse, wash, repeat
51 - Each Chrono simulation has a timestep and each heartbeat has a timestep, so repeatedly doing steps 1-4 advances the simulation through time
52
53## Implementation Specific Details
54
55### Multi-Agent
56
57SynChrono's main aim is to provide robust scalability for large numbers of vehicles. SynChrono has been benchmarked at faster than realtime performance for over 100 vehicles on rigid terrain. Currently, SynChrono supports multiple agents per Chrono system, with each Chrono system tied to a specific node. Multiple agents aids in resource-sharing for scenarios with large memory requirements.
58
59### Physics
60
61The physics for SynChrono is based on the physics of Chrono; for vehicles, this means Chrono::Vehicle's physics.
62
63### Sensing
64
65Sensing support in SynChrono comes through the [Chrono::Sensor module](../chrono_sensor/README.md). Chrono::Sensor is based around OptiX ray-tracing and currently includes support for camera, lidar, GPS and IMU.
66
67### V2X Communication
68
69SynChrono includes support for arbitrary communication between agents in the system, by using the same flatbuffer message mechanism that is used for synchronizing state data. Currently the main example of this communication is V2V communication of sensor data, and Traffic Light to Vehicle communication of SPAT and MAP messages.
70
71## Build Instructions
72
73Follow the standard [Chrono build process](http://api.projectchrono.org/tutorial_install_chrono.html) to build SynChrono. The Chrono::Vehicle module is required, and one of Chrono::Irrlicht or Chrono::Sensor is recommended for visualization. The only additional dependencies that SynChrono requires are Flatbuffers and MPI. FastDDS is an optional dependency.
74
75#### Flatbuffers
76
77Flatbuffers is included in chrono_thirdparty as a submodule but you can also use a local copy if it is already installed on your system. Follow the [build instructions](https://google.github.io/flatbuffers/flatbuffers_guide_building.html). The flatbuffer include directory within CMake is pointed directly to the submodule in chrono_thirdparty, so ensure the submodule is used and built.
78
79#### MPI
80For most systems (Linux, MacOS), you can use [OpenMPI](https://www.open-mpi.org/) or [MPICH](https://www.mpich.org/). For Windows there are two main options:
81- Intel MPI: [Intel MPI](https://software.intel.com/en-us/mpi-library/choose-download/windows)
82- MS-MPI: [MS-MPI](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi)
83
84One consideration is the version of MPI that is supported. Intel MPI is MPI 3.1 compliant whereas MS-MPI is only MPI 2.2 compliant. SynChrono is typically developed and tested with MPI 3.x, but there is no reason that older versions will not work.
85
86#### Windows
87On Windows specifically, you'll need some CMake variables to be set correctly. For all of these variables, set both the CXX and C variation of them (e.g. both MPI_CXX_LIB_NAMES and MPI_C_LIB_NAMES). Example values are included for each variable, but they may vary depending on your specific system setup
88- MPI_CXX_ADDITIONAL_INCLUDE_DIRS - `C:/Program Files (x86)/IntelSWTools/compilers_and_libraries_2019.5.281/windows/mpi/intel64/include`
89- MPI_CXX_COMPILER - `C:/Program Files (x86)/IntelSWTools/compilers_and_libraries_2019.5.281/windows/mpi/intel64/bin/mpicl.bat`
90- MPI_CXX_HEADER_DIR - `C:/Program Files (x86)/IntelSWTools/mpi/2019.5.281/intel64/include/`
91- MPI_CXX_LIB_NAMES - set to `impi` if using Intel MPI or `msmpi` if using MS-MPI
92
93Intel MPI specific:
94- MPI_impi_LIBRARY - `C:/Program Files (x86)/IntelSWTools/compilers_and_libraries_2019.5.281/windows/mpi/intel64/lib/release/impi.lib`
95- MPI_impicxx_LIBRARY - `C:/Program Files (x86)/IntelSWTools/compilers_and_libraries_2019.5.281/windows/mpi/intel64/lib/impicxx.lib`
96
97MS-MPI specific, most of these can be set automatically by running `set MSMPI` in `cmd`.
98- MPI_msmpi_LIBRARY - `C:/Program Files (x86)/Microsoft SDKs/MPI/Lib/x64/msmpi.lib`
99- MSMPI_BIN
100- MSMPI_INC
101- MSMPI_LIB32
102- MSMPI_LIB64
103
104#### FastDDS
105FastDDS is supported on most modern systems (Linux, MacOS, Windows). To install, please visit the [FastDDS website](https://fast-dds.docs.eprosima.com/en/latest/). To link to Chrono, either install globally or install in a single directory and point `FAST_DDS_INSTALL_DIR` to that location.
106