p71924506
/
carla
mirror of https://github.com/carla-simulator/carla.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

sergi-e/tm-determinism-and-updates-docs (#3453) 

* New methods of the TM module

* First iteration on determinism

* Warning on sync mode for both world and TM in adv_synchrony_timestep.md and PythonAPI ref

* Iteration on J review!

* fixed broken link
This commit is contained in:
sergi.e 2020-10-20 18:32:20 +02:00 committed by GitHub
parent 530f56e78b
commit a90956ad0c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 154 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Docs/adv_synchrony_timestep.md
View File

@ -98,6 +98,8 @@ settings = world.get_settings()
settings.synchronous_mode = True # Enables synchronous mode
world.apply_settings(settings)
```
!!! Warning
If synchronous mode is enabled, and there is a Traffic Manager running, this must be set to sync mode too. Read [this](adv_traffic_manager.md#synchronous-mode) to learn how to do it.
To disable synchronous mode just set the variable to false or use the script `PythonAPI/util/config.py`.
```sh

76
Docs/adv_traffic_manager.md
View File

@ -15,6 +15,7 @@
* [Creating a Traffic Manager](#creating-a-traffic-manager)
* [Setting a Traffic Manager](#setting-a-traffic-manager)
* [Stopping a Traffic Manager](#stopping-a-traffic-manager)
* [__Deterministic mode__](#deterministic-mode)
* [__Hybrid physics mode__](#hybrid-physics-mode)
* [__Running multiple Traffic Managers__](#running-multiple-traffic-managers)
* [Definitions](#definitions)
@ -22,7 +23,6 @@
* [MultiTM](#multitm)
* [Multisimulation](#multisimulation)
* [__Other considerations__](#other-considerations)
* [FPS limitations](#fps-limitations)
* [Synchronous mode](#synchronous-mode)
* [__Summary__](#summary)
@ -144,7 +144,7 @@ First stage in the [control loop](#control-loop). Defines a near-future path for
* Obtains the position and velocity of all the vehicles from [simulation state](#simulation-state).
* Using the [In-Memory Map](#in-memory-map), relates every vehicle with a list of waypoints that describes its current location and near-future path, according to its trajectory. The faster the vehicle goes, the larger said list will be.
* The path is updated according to planning decisions such as lan changes, speed limit, distance to leading vehicle parameterization, etc.
* The path is updated according to planning decisions such as lane changes, speed limit, distance to leading vehicle parameterization, etc.
* The [PBVT](#pbvt) module stores the path for all the vehicles.
* These paths are compared with each other, in order to estimate possible collision situations. Results are passed to the following stage: [Colllision stage](#stage-2-collision-stage).
@ -304,6 +304,32 @@ However, it is important that when shutting down a TM, the vehicles registered t
!!! Warning
Shutting down a __TM-Server__ will shut down the __TM-Clients__ connecting to it. To learn the difference between a __TM-Server__ and a __TM-Client__ read about [*Running multiple Traffic Managers*](#running-multiple-traffic-managers).
---
## Deterministic mode
In deterministic mode, the Traffic Manager will always produce the same results and behaviours under the same conditions. Do not mistake determinism with the recorder. While the recorder allows you to store the log of a simulation to play it back, determinism ensures that Traffic Manager will always have the same output over different executions of a script, if the same conditions are maintained.
Deterministic mode is meant to be used __in synchronous mode only__. In asynchronous mode, there is much less control over the simulation, and determinism cannot be achieved. Read the considerations to run [TM in synchronous mode](#synchronous-mode) before using it.
To enable deterministic mode, simply call the following method in your script.
```py
my_tm.set_random_device_seed(seed_value)
```
`seed_value` is an `int` number from which all the random numbers will be generated. The value is not relevant itself, but the same value will always result in the same output. Two simulations, with the same conditions, that use the same seed value, will be deterministic.
The deterministic mode can be tested when using the `spawn_npc.py` example script, using a simple argument. The following example sets the seed to `9` for no specific reason.
```sh
cd PythonAPI/examples
python3 spawn_npc.py -n 50 --sync --seed 9
```
!!! Warning
Make sure to set both the world and the TM to synchronous mode before enabling deterministic mode.
---
## Hybrid physics mode
@ -401,20 +427,46 @@ The only possible issue arising from this is a client trying to connect to an al
The TM is a module constantly evolving and trying to adapt the range of possibilities that it presents. For instance, in order to get more realistic behaviours we can have many clients with different TM in charge of sets of vehicles with specific and distinct behaviours. This range of possibilities also makes for a lot of different configurations that can get really complex and specific. For such reason, here are listed of considerations that should be taken into account when working with the TM as it is by the time of writing.
### FPS limitations
The TM stops working properly in asynchronous mode when the simulation is under 20fps. Below that rate, the server is going much faster than the client containing the TM and behaviours cannot be simulated properly. For said reason, under these circumstances it is recommended to work in __synchronous mode__.
!!! Important
The FPS limitations are specially relevant when working in the night mode.
### Synchronous mode
TM-Clients cannot tick the CARLA server in synchronous mode, __only a TM-Server can call for a tick__.
If more than one TM-Server ticks, the synchrony will fail, as the server will move forward on every tick. This is specially relevant when working with the __ScenarioRunner__, which runs a TM. In this case, the TM will be subordinated to the ScenarioRunner and wait for it.
If the CARLA server is set to synchronous mode, the Traffic Manager must be set to synchronous mode too. To do so, your script should be similar to the following:
```py
...
# Set the simulation to sync mode
init_settings = world.get_settings()
settings = world.get_settings()
settings.synchronous_mode = True
# Right after that, set the Traffic Manager to sync mode
my_tm.set_synchronous_mode(True)
...
# Tick the world in the same client
world.apply_settings(init_settings)
world.tick()
...
# Disable the sync mode always, before the script ends
settings.synchronous_mode = False
my_tm.set_synchronous_mode(False)
```
When using the `spawn_npc.py` example script, the TM can be set to synchronous mode just by passing an argument.
```sh
cd PythonAPI/examples
python3 spawn_npc.py -n 50 --sync
```
If more than one Traffic Manager is set to synchronous mode, the synchrony will fail. Follow these general guidelines to avoid issues.
* In a __[multiclient](#multiclient)__ situation, only the __TM-Server__ must be set to synchronous mode.
* In a __[multiTM](#multitm)__ situation, only __one of the TM-Server__ must be set to synchronous mode.
* The __[ScenarioRunner module](https://carla-scenariorunner.readthedocs.io/en/latest/)__, already runs a TM. In this case, the TM inside ScenarioRunner will be the one set to sync mode.
!!! Warning
Disable the synchronous mode in the script doing the ticks before it finishes. Otherwise, the server will be blocked, waiting forever for a tick.
Disable the synchronous mode (both, world and TM sync mode) in the script doing the ticks before it finishes. Otherwise, the server will be blocked, waiting forever for a tick.
---
## Summary

34
Docs/python_api.md
View File

@ -355,7 +355,7 @@ Parses the location and extent of the bounding box to string.
---
## carla.CityObjectLabel<a name="carla.CityObjectLabel"></a>
Enum declaration that contains the different tags available to filter the bounding boxes returned by [carla.World.get_level_bbs](#carla.World.get_level_bbs)(). These values correspond to the [semantic tag](../../ref_sensors/#semantic-segmentation-camera) that the elements in the scene have.
Enum declaration that contains the different tags available to filter the bounding boxes returned by [carla.World.get_level_bbs](#carla.World.get_level_bbs)(). These values correspond to the [semantic tag](https://[carla.readthedocs.io](#carla.readthedocs.io)/en/latest/ref_sensors/#semantic-segmentation-camera) that the elements in the scene have.
<h3>Instance Variables</h3>
- <a name="carla.CityObjectLabel.None"></a>**<font color="#f8805a">None</font>**
@ -2029,10 +2029,6 @@ Forces a vehicle to change either to the lane on its left or right, if existing,
- **Parameters:**
- `actor` (_[carla.Actor](#carla.Actor)_) – Vehicle being forced to change lanes.
- `direction` (_bool_) – Destination lane. __True__ is the one on the right and __False__ is the left one.
- <a name="carla.TrafficManager.global_distance_to_leading_vehicle"></a>**<font color="#7fb800">global_distance_to_leading_vehicle</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**distance**</font>)
Sets the minimum distance in meters that vehicles have to keep with the rest. The distance is in meters and will affect the minimum moving distance. It is computed from center to center of the vehicle objects.
- **Parameters:**
- `distance` (_float<small> – meters</small>_) – Meters between vehicles.
- <a name="carla.TrafficManager.global_percentage_speed_difference"></a>**<font color="#7fb800">global_percentage_speed_difference</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**percentage**</font>)
Sets the difference the vehicle's intended speed and its current speed limit. Speed limits can be exceeded by setting the `perc` to a negative value.
Default is 30. Exceeding a speed limit can be done using negative percentages.
@ -2043,6 +2039,11 @@ During the traffic light stage, which runs every frame, this method sets the per
- **Parameters:**
- `actor` (_[carla.Actor](#carla.Actor)_) – The actor that is going to ignore traffic lights.
- `perc` (_float_) – Between 0 and 100. Amount of times traffic lights will be ignored.
- <a name="carla.TrafficManager.ignore_signs_percentage"></a>**<font color="#7fb800">ignore_signs_percentage</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**actor**</font>, <font color="#00a6ed">**perc**</font>)
During the traffic light stage, which runs every frame, this method sets the percent chance that stop signs will be ignored for a vehicle.
- **Parameters:**
- `actor` (_[carla.Actor](#carla.Actor)_) – The actor that is going to ignore stop signs.
- `perc` (_float_) – Between 0 and 100. Amount of times stop signs will be ignored.
- <a name="carla.TrafficManager.ignore_vehicles_percentage"></a>**<font color="#7fb800">ignore_vehicles_percentage</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**actor**</font>, <font color="#00a6ed">**perc**</font>)
During the collision detection stage, which runs every frame, this method sets a percent chance that collisions with another vehicle will be ignored for a vehicle.
- **Parameters:**
@ -2068,7 +2069,11 @@ Returns the port where the Traffic Manager is connected. If the object is a TM-C
- **Return:** _uint16_
<h5 style="margin-top: -20px">Setters</h5>
<div style="padding-left:30px;margin-top:-25px"></div>- <a name="carla.TrafficManager.set_hybrid_mode_radius"></a>**<font color="#7fb800">set_hybrid_mode_radius</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**r**=70.0</font>)
<div style="padding-left:30px;margin-top:-25px"></div>- <a name="carla.TrafficManager.set_global_distance_to_leading_vehicle"></a>**<font color="#7fb800">set_global_distance_to_leading_vehicle</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**distance**</font>)
Sets the minimum distance in meters that vehicles have to keep with the rest. The distance is in meters and will affect the minimum moving distance. It is computed from center to center of the vehicle objects.
- **Parameters:**
- `distance` (_float<small> – meters</small>_) – Meters between vehicles.
- <a name="carla.TrafficManager.set_hybrid_mode_radius"></a>**<font color="#7fb800">set_hybrid_mode_radius</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**r**=70.0</font>)
With hybrid physics on, changes the radius of the area of influence where physics are enabled.
- **Parameters:**
- `r` (_float<small> – meters</small>_) – New radius where physics are enabled.
@ -2080,6 +2085,21 @@ Enables or disables the hybrid physics mode. In this mode, vehicle's farther tha
Enables or disables the OSM mode. This mode allows the user to run TM in a map created with the [OSM feature](tuto_G_openstreetmap.md). These maps allow having dead-end streets. Normally, if vehicles cannot find the next waypoint, TM crashes. If OSM mode is enabled, it will show a warning, and destroy vehicles when necessary.
- **Parameters:**
- `mode_switch` (_bool_) – If __True__, the OSM mode is enabled.
- <a name="carla.TrafficManager.set_percentage_keep_right_rule"></a>**<font color="#7fb800">set_percentage_keep_right_rule</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**actor**</font>, <font color="#00a6ed">**perc**</font>)
During the localization stage, this method sets a percent chance that vehicle will follow the *keep right* rule, and stay in the right lane.
- **Parameters:**
- `actor` (_[carla.Actor](#carla.Actor)_) – Vehicle whose behaviour is being changed.
- `perc` (_float_) – Between 0 and 100. Amount of times the vehicle will follow the keep right rule.
- <a name="carla.TrafficManager.set_random_device_seed"></a>**<font color="#7fb800">set_random_device_seed</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**value**</font>)
Sets a specific random seed for the Traffic Manager, thereby setting it to be deterministic.
- **Parameters:**
- `value` (_int_) – Seed value for the random number generation of the Traffic Manager.
- <a name="carla.TrafficManager.set_synchronous_mode"></a>**<font color="#7fb800">set_synchronous_mode</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**mode_switch**=True</font>)
Sets the Traffic Manager to [synchronous mode](adv_traffic_manager.md#synchronous-mode). In a [multiclient situation](adv_traffic_manager.md#multiclient), only the TM-Server can tick. Similarly, in a [multiTM situation](adv_traffic_manager.md#multitm), only one TM-Server must tick. Use this method in the client that does the world tick, and right after setting the world to synchronous mode, to set which TM will be the master while in sync.
- **Parameters:**
- `mode_switch` (_bool_) – If __True__, the TM synchronous mode is enabled.
- **Warning:** <font color="#ED2F2F">_If the server is set to synchronous mode, the TM <b>must</b> be set to synchronous mode too in the same client that does the tick.
_</font>
---
@ -2680,6 +2700,8 @@ This method applies settings contained in an object to the simulation running an
- **Parameters:**
- `world_settings` (_[carla.WorldSettings](#carla.WorldSettings)_)
- **Return:** _int_
- **Warning:** <font color="#ED2F2F">_If synchronous mode is enabled, and there is a Traffic Manager running, this must be set to sync mode too. Read [this](adv_traffic_manager.md#synchronous-mode) to learn how to do it.
_</font>
- <a name="carla.World.freeze_all_traffic_lights"></a>**<font color="#7fb800">freeze_all_traffic_lights</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**frozen**</font>)
Freezes or unfreezes all traffic lights in the scene. Frozen traffic lights can be modified by the user but the time will not update them until unfrozen.
- **Parameters:**

67
PythonAPI/docs/client.yml
View File

@ -337,16 +337,6 @@
doc: >
Forces a vehicle to change either to the lane on its left or right, if existing, as indicated in `direction`. This method applies the lane change no matter what, disregarding possible collisions.
# --------------------------------------
- def_name: global_distance_to_leading_vehicle
params:
- param_name: distance
type: float
param_units: meters
doc: >
Meters between vehicles.
doc: >
Sets the minimum distance in meters that vehicles have to keep with the rest. The distance is in meters and will affect the minimum moving distance. It is computed from center to center of the vehicle objects.
# --------------------------------------
- def_name: global_percentage_speed_difference
params:
- param_name: percentage
@ -371,6 +361,19 @@
doc: >
During the traffic light stage, which runs every frame, this method sets the percent chance that traffic lights will be ignored for a vehicle.
# --------------------------------------
- def_name: ignore_signs_percentage
params:
- param_name: actor
type: carla.Actor
doc: >
The actor that is going to ignore stop signs.
- param_name: perc
type: float
doc: >
Between 0 and 100. Amount of times stop signs will be ignored.
doc: >
During the traffic light stage, which runs every frame, this method sets the percent chance that stop signs will be ignored for a vehicle.
# --------------------------------------
- def_name: ignore_vehicles_percentage
params:
- param_name: actor
@ -422,6 +425,16 @@
doc: >
Returns the port where the Traffic Manager is connected. If the object is a TM-Client, it will return the port of its TM-Server. Read the [documentation](#adv_traffic_manager.md#multiclient-and-multitm-management) to learn the difference.
# --------------------------------------
- def_name: set_global_distance_to_leading_vehicle
params:
- param_name: distance
type: float
param_units: meters
doc: >
Meters between vehicles.
doc: >
Sets the minimum distance in meters that vehicles have to keep with the rest. The distance is in meters and will affect the minimum moving distance. It is computed from center to center of the vehicle objects.
# --------------------------------------
- def_name: set_hybrid_physics_mode
params:
- param_name: enabled
@ -453,6 +466,40 @@
doc: >
Enables or disables the OSM mode. This mode allows the user to run TM in a map created with the [OSM feature](tuto_G_openstreetmap.md). These maps allow having dead-end streets. Normally, if vehicles cannot find the next waypoint, TM crashes. If OSM mode is enabled, it will show a warning, and destroy vehicles when necessary.
# --------------------------------------
- def_name: set_percentage_keep_right_rule
params:
- param_name: actor
type: carla.Actor
doc: >
Vehicle whose behaviour is being changed.
- param_name: perc
type: float
doc: >
Between 0 and 100. Amount of times the vehicle will follow the keep right rule.
doc: >
During the localization stage, this method sets a percent chance that vehicle will follow the *keep right* rule, and stay in the right lane.
# --------------------------------------
- def_name: set_random_device_seed
params:
- param_name: value
type: int
doc: >
Seed value for the random number generation of the Traffic Manager.
doc: >
Sets a specific random seed for the Traffic Manager, thereby setting it to be deterministic.
# --------------------------------------
- def_name: set_synchronous_mode
params:
- param_name: mode_switch
type: bool
default: true
doc: >
If __True__, the TM synchronous mode is enabled.
doc: >
Sets the Traffic Manager to [synchronous mode](adv_traffic_manager.md#synchronous-mode). In a [multiclient situation](adv_traffic_manager.md#multiclient), only the TM-Server can tick. Similarly, in a [multiTM situation](adv_traffic_manager.md#multitm), only one TM-Server must tick. Use this method in the client that does the world tick, and right after setting the world to synchronous mode, to set which TM will be the master while in sync.
warning: >
If the server is set to synchronous mode, the TM <b>must</b> be set to synchronous mode too in the same client that does the tick.
# --------------------------------------
- class_name: OpendriveGenerationParameters
# - DESCRIPTION ------------------------

2
PythonAPI/docs/sensor_data.yml
View File

@ -55,7 +55,7 @@
- class_name: CityObjectLabel
# - DESCRIPTION ------------------------
doc: >
Enum declaration that contains the different tags available to filter the bounding boxes returned by carla.World.get_level_bbs(). These values correspond to the [semantic tag](../../ref_sensors/#semantic-segmentation-camera) that the elements in the scene have.
Enum declaration that contains the different tags available to filter the bounding boxes returned by carla.World.get_level_bbs(). These values correspond to the [semantic tag](https://carla.readthedocs.io/en/latest/ref_sensors/#semantic-segmentation-camera) that the elements in the scene have.
# - PROPERTIES -------------------------
instance_variables:

2
PythonAPI/docs/world.yml
View File

@ -209,6 +209,8 @@
type: carla.WorldSettings
doc: >
This method applies settings contained in an object to the simulation running and returns the ID of the frame they were implemented.
warning: >
If synchronous mode is enabled, and there is a Traffic Manager running, this must be set to sync mode too. Read [this](adv_traffic_manager.md#synchronous-mode) to learn how to do it.
# --------------------------------------
- def_name: on_tick
return: int