diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
index da548f6b4e8c62bc68d9880c1ea6dcedf4c10693..39dcde9ea7c2a3670ecda3d18bba517f6ad17016 100644
--- a/docs/source/getting_started.rst
+++ b/docs/source/getting_started.rst
@@ -1,8 +1,19 @@
Getting Started
===============
-*Verse* is a Python library for modeling, simulation, and verification of multi-agent
-autonomous systems like cars, drones, and spacecraft, in structured environments like road networks, racetracks, and orbits.
+The package requires python 3.8+. The package can be installed using pip with all required dependencies::
+
+ python3 -m pip install -e .
+
+To update the dependencies in case anything is missing, ``requirements.txt`` can be used::
+
+ pip install -r requirements.txt
+
+An interactive tutorial can be found in ``tutorial/tutorial.ipynb``. The tutorial requires Jupyter notebook to run. A PDF version of the tutorial can be found in ``tutorial.pdf``.
+
+The package comes with several examples in the ``demo/`` folder. Run these as::
+
+ python3 demo/ball/ball_bounces.py
+
+Read the comments in demo/ball/ball_bounces.py to learn how to create new agents and scenarios. More detailed tutorials will be provided later.
-Installing
-__________
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ee054a894fb5e34cf38e77c294e003734e50549e..2a9b54ceb3fff423b99bd663ea45c510ed2a8de9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,6 +6,8 @@
Welcome to verse's documentation!
=================================
+Verse is a Python library for creating, simulating, and verifying scenarios with interacting, decision making agents. The decision logic can be written in an expressive subset of Python. The continuous evolution can be described as a black-box simulation function. The agent can be ported across different maps, which can be defined from scratch or imported from opendrive files. Verse scenarios can be simulated and verified using hybrid reachability analysis.
+
.. toctree::
:maxdepth: 2
:caption: Contents:
@@ -16,6 +18,7 @@ Welcome to verse's documentation!
sensor.rst
scenario.rst
parser.md
+ outputs.rst
plotting.rst
contributors.rst
diff --git a/docs/source/outputs.rst b/docs/source/outputs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bdafcd03684f7fac3e1e335e691398e2e7cfa893
--- /dev/null
+++ b/docs/source/outputs.rst
@@ -0,0 +1,34 @@
+Simulations
+~~~~~~~~~~~
+
+The ``simulate`` function generates simulation traces of scenarios which can be stored as a json file using ``dump()`` in the following format::
+
+ "ID": {
+ "agent": {<list of agents>},
+ "assert_hits": <result>,
+ "child": [<list of node IDs>],
+ "id": int,
+ "init": {<list of initial state>},
+ "mode": {<list of modes>},
+ "parent": <parent node id>,
+ "start_time": float,
+ "static": ,
+ "trace": {<list of traces for agents>},
+ "type": "simtrace"
+ },
+
+
+Each trace in the list of traces is of the form::
+
+ {
+ "<agent_name>": [
+ [time,
+ x1,
+ x2,
+ x3
+ ], ...
+ ]
+ }
+
+Reachtubes
+~~~~~~~~~~
diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst
index 7422430ef8fc420c70cc59852b47604d78cfcc14..b2bfbfaabe7b8000a8a9312a5eca018ad2b55825 100644
--- a/docs/source/plotting.rst
+++ b/docs/source/plotting.rst
@@ -1,26 +1,21 @@
-Visualization and plotting
-==========================
+Visualization
+=============
-plot3dReachtube
-~~~~~~~~~~~~~~~
-This function is used for plotting reachtubes.
-
-reachtube_anime
-~~~~~~~~~~~~~~~
-Shows an animation of a reachtube.
-
-Usage::
+simulation_tree
+~~~~~~~~~~~~~~~~
+Shows an animation of a simulation with or without trails.
-reachtube_anime(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, time_step=None, speed_rate=1, combine_rect=None)
+Usage::
-* ``root``: the root node of the simulation trace. Typically this would be a computed using ``Scenario.verify()`` or ``Scenario.simulate()``.
+ simulation_tree(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1)
-* ``map``: Plots the map of the scenario in the background. Can be optional.
+* ``root``: root node of a simulation trace. Typically, return value ``Scenario.simulate()``.
-* ``fig``: The figure object of type ``plotly.graph_objects.Figure()``.
+* ``map``: the map of the scenario plotted as a background.
-* ``x_dim``: The dimension to be used along the x-axis of the graph. The default value is **1** corresponding to time.
+* ``fig``: figure object of type ``plotly.graph_objects.Figure()``.
+- **x_dim:** the dimension of x coordinate in the trace list of every time step. The default value is **1**.
- **y_dim:** the dimension of y coordinate in the trace list of every time step. The default value is **2**.
- **print_dim_list** the list containing the dimensions of data which will be shown directly or indirectly when the mouse hovers on the point. The default value is **None**. And then all dimensions will be shown.
- **map_type** the way to draw the map. It should be **'lines'** or **'fill'** or **'detailed'**. The default value is **'lines'**.
@@ -32,26 +27,18 @@ reachtube_anime(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Fi
- For the **'map'** mode, the map will be in the center of the plot with an appropriate scale.
- **label_mode** the mode to display labels or not. if it is 'None', then labels will not be displayed. Otherwise, labels will be displayed. The default value is **'None'**.
- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
-- **time_step** it is used to determine the num of digits of time points. If it's None, then the num of digits is set as 3. Otherwise, the num of digits is set as the num of digits of the given time_step. Normally, it should be the time step of simulation/verification. The default value is **None**.
-- **speed_rate** it determines the speed od anime. Due to the performance, it maybe be limited when the response of the plot is slow. The default value is **1**.
-- **combine_rect** it determines the way of displaying reachtube. Specifically, it can combine specified number of reachtubes as a rectangle. The default value is **None** here, which means no combination.
-
-reachtube_tree
-~~~~~~~~~~~~~~
-Shows the reachtube, possibly with multiple brances.
simulation_anime
~~~~~~~~~~~~~~~~
-Shows an animation of a simulation with or without trails.
-
-simulation_tree
-~~~~~~~~~~~~~~~
Shows simulation traces possibly with multiple brances.
-#### reachtube_tree(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, combine_rect=1):
+
+
+
+#### simulation_anime(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, time_step=None, speed_rate=1, anime_mode='normal', full_trace=False):
- **root:** the root node of the trace, normally should be the return value of Scenario.verify() or Scenario.simulate().
- **map:** the map of the scenario, templates are in dryvr_plus_plus.example.example_map.simple_map2.py.
- **fig:** the object of the figure, its type should be plotly.graph_objects.Figure().
@@ -66,14 +53,32 @@ Shows simulation traces possibly with multiple brances.
- For the **'trace'** mode, the traces will be in the center of the plot with an appropriate scale.
- For the **'map'** mode, the map will be in the center of the plot with an appropriate scale.
- **label_mode** the mode to display labels or not. if it is 'None', then labels will not be displayed. Otherwise, labels will be displayed. The default value is **'None'**.
-- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
-- **combine_rect** it determines the way of displaying reachtube. Specifically, it can combine specified number of reachtubes as a rectangle. The default value is **1** here.
+- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
+- **time_step** it is used to determine the num of digits of time points. If it's None, then the num of digits is set as 3. Otherwise, the num of digits is set as the num of digits of the given time_step. Normally, it should be the time step of simulation/verification. The default value is **None**.
+- **speed_rate** it determines the speed od anime. Due to the performance, it maybe be limited when the response of the plot is slow. The default value is **1**.
+- **anime_mode** it determines if the trails are displayed or not. if it's 'normal', then the trails will not be displayed. Otherwise, displayed. The default value is **'normal'**.
+- **full_trace** it determines if the full trace is displayed or not. if it's False, then the full trace will not be displayed. Otherwise, displayed. The default value is **False**.
+
+plot3dReachtube
+~~~~~~~~~~~~~~~
+This function is used for plotting reachtubes.
+
+reachtube_anime
+~~~~~~~~~~~~~~~
+Shows an animation of a reachtube.
+
+Usage::
+
+ reachtube_anime(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, time_step=None, speed_rate=1, combine_rect=None)
+
+* ``root``: the root node of the simulation trace. Typically this would be a computed using ``Scenario.verify()`` or ``Scenario.simulate()``.
+
+* ``map``: Plots the map of the scenario in the background. Can be optional.
+
+* ``fig``: The figure object of type ``plotly.graph_objects.Figure()``.
+
+* ``x_dim``: The dimension to be used along the x-axis of the graph. The default value is **1** corresponding to time.
-#### simulation_tree(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1):
-- **root:** the root node of the trace, normally should be the return value of Scenario.verify() or Scenario.simulate().
-- **map:** the map of the scenario, templates are in dryvr_plus_plus.example.example_map.simple_map2.py.
-- **fig:** the object of the figure, its type should be plotly.graph_objects.Figure().
-- **x_dim:** the dimension of x coordinate in the trace list of every time step. The default value is **1**.
- **y_dim:** the dimension of y coordinate in the trace list of every time step. The default value is **2**.
- **print_dim_list** the list containing the dimensions of data which will be shown directly or indirectly when the mouse hovers on the point. The default value is **None**. And then all dimensions will be shown.
- **map_type** the way to draw the map. It should be **'lines'** or **'fill'** or **'detailed'**. The default value is **'lines'**.
@@ -85,9 +90,20 @@ Shows simulation traces possibly with multiple brances.
- For the **'map'** mode, the map will be in the center of the plot with an appropriate scale.
- **label_mode** the mode to display labels or not. if it is 'None', then labels will not be displayed. Otherwise, labels will be displayed. The default value is **'None'**.
- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
+- **time_step** it is used to determine the num of digits of time points. If it's None, then the num of digits is set as 3. Otherwise, the num of digits is set as the num of digits of the given time_step. Normally, it should be the time step of simulation/verification. The default value is **None**.
+- **speed_rate** it determines the speed od anime. Due to the performance, it maybe be limited when the response of the plot is slow. The default value is **1**.
+- **combine_rect** it determines the way of displaying reachtube. Specifically, it can combine specified number of reachtubes as a rectangle. The default value is **None** here, which means no combination.
+
+reachtube_tree
+~~~~~~~~~~~~~~
+Shows the reachtube, possibly with multiple brances.
+
+Usage::
+
+ reachtube_tree(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, combine_rect=1):
+
+* ``root``: the root node of the reachtube. Typically, the return value of ``Scenario.verify()`` or ``Scenario.simulate()``.
-#### simulation_anime(root: Union[AnalysisTree, AnalysisTreeNode], map=None, fig=go.Figure(), x_dim: int = 1, y_dim: int = 2, print_dim_list=None, map_type='lines', scale_type='trace', label_mode='None', sample_rate=1, time_step=None, speed_rate=1, anime_mode='normal', full_trace=False):
-- **root:** the root node of the trace, normally should be the return value of Scenario.verify() or Scenario.simulate().
- **map:** the map of the scenario, templates are in dryvr_plus_plus.example.example_map.simple_map2.py.
- **fig:** the object of the figure, its type should be plotly.graph_objects.Figure().
- **x_dim:** the dimension of x coordinate in the trace list of every time step. The default value is **1**.
@@ -101,8 +117,6 @@ Shows simulation traces possibly with multiple brances.
- For the **'trace'** mode, the traces will be in the center of the plot with an appropriate scale.
- For the **'map'** mode, the map will be in the center of the plot with an appropriate scale.
- **label_mode** the mode to display labels or not. if it is 'None', then labels will not be displayed. Otherwise, labels will be displayed. The default value is **'None'**.
-- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
-- **time_step** it is used to determine the num of digits of time points. If it's None, then the num of digits is set as 3. Otherwise, the num of digits is set as the num of digits of the given time_step. Normally, it should be the time step of simulation/verification. The default value is **None**.
-- **speed_rate** it determines the speed od anime. Due to the performance, it maybe be limited when the response of the plot is slow. The default value is **1**.
-- **anime_mode** it determines if the trails are displayed or not. if it's 'normal', then the trails will not be displayed. Otherwise, displayed. The default value is **'normal'**.
-- **full_trace** it determines if the full trace is displayed or not. if it's False, then the full trace will not be displayed. Otherwise, displayed. The default value is **False**.
\ No newline at end of file
+- **sample_rate** it determines the points used in the plot. if sample_rate = n which is a positive integer, it means that the plotter sample a point within n points. it is useful when the points are too much and the response of the plot is slow. The default value is **1**.
+- **combine_rect** it determines the way of displaying reachtube. Specifically, it can combine specified number of reachtubes as a rectangle. The default value is **1** here.
+