Merge branch 'simplify-readme' into zoo-8

.github/workflows/ci-format.yml

@@ -100,7 +100,7 @@ jobs:
           pip install wheel==0.38.4
           pip install .[camera_obs,doc,train,ray,envision,argoverse,opendrive,waymo,sumo]
           cd ${GITHUB_WORKSPACE}/docs
-          make html SPHINXOPTS="-W -T -E -n --keep-going -b spelling"
+          make html SPHINXOPTS="-W -T -E -n --keep-going -b spelling -b linkcheck"
       - name: Check build output
         run: |
           cd $GITHUB_WORKSPACE

CHANGELOG.md

@@ -11,14 +11,27 @@ Copy and pasting the git commit messages is __NOT__ enough.
 ## [Unreleased] - XXXX-XX-XX
 ### Added
 ### Changed
+- `VehicleIndex.build_agent_vehicle()` no longer has `filename` and `surface_patches` parameters.
+- The following modules have been renamed: `envision.types` -> `envision.etypes`, `smarts.core.utils.logging` -> `smarts.core.utils.core_logging`, `smarts.core.utils.math` -> `smarts.core.utils.core_math`, `smarts.sstudio.types` -> `smarts.sstudio.sstypes`. For compatibility reasons they can still be imported by their original module name.
+- Exposed `traffic:traci_retries`/`SMARTS_TRAFFIC_TRACI_RETRIES` to control how many times the `SumoTrafficSimulation` will try to restart when using default configuration.
+
 ### Deprecated
 ### Fixed
+- `SumoTrafficSimulation` gives clearer reasons as to why it failed to connect to the TraCI server.
+- Suppressed an issue where `pybullet_utils.pybullet.BulletClient` would cause an error because it was catching a non `BaseException` type.
+- Fixed an issue where `AgentInterface.vehicle_type` would not affect agent vehicles when attempting to take over an existing vehicle.
+- Fixed a case where newly created agent vehicles would have a constant `"sedan"` size instead of the size of `AgentInterface.vehicle_type`.
+- Fixed a case where if vehicles are replaced they would not respect controller and vehicle parameters.
+- Fixed an issue where `RandomRoute` would always give the same route across traffic groups in scenario studio.
 - Fixed an issue where `SMARTS` might not be explicitly destroyed in the `ros_driver`.
 - Fixed issue where `SumoTrafficSimulation` could get locked up on reset if a scenario had only 1 map but multiple scenario variations.
 - Fixed an issue where an out-of-scope method reference caused a pickling error.
 - Fixed an issue where the `EnvisionDataFormatterArgs` default would use a locally defined lambda and cause a serialization failure.
 - Fixed an issue where user configuration was being overridden.
 - Fixed a `pkg_resources` deprecation warning in `python3.10` and up.
+- Fixed the envision camera to center on the map which was broken due to a change in the `gltf` metadata hierarchy.
+- Fixed an issue where you would need to install `waymo` in order to use any kind of dataset histories.
+- Fixed an issue where Pycharm would load `smarts/sstudio/types` as the integrated `types` module. See #2125.
 ### Removed
 ### Security
 

Makefile

@@ -154,7 +154,7 @@ format: gen-header
 
 .PHONY: docs
 docs:
-	cd docs && make clean html SPHINXOPTS="-W -T -n --keep-going -b spelling"
+	cd docs && make clean html SPHINXOPTS="-W -T -n --keep-going -b spelling -b linkcheck"
 
 .PHONY: wheel
 wheel: docs

README.md

@@ -14,44 +14,9 @@ Check out the paper at [SMARTS: Scalable Multi-Agent Reinforcement Learning Trai
 ![](docs/_static/smarts_envision.gif)
 
 # Documentation
-:rotating_light: :bell: Read the docs :notebook_with_decorative_cover: at [smarts.readthedocs.io](https://smarts.readthedocs.io/) . :bell: :rotating_light:
-
-# Examples 
-### Primitive
-1. [Egoless](examples/e1_egoless.py) example.
-   + Run a SMARTS simulation without any ego agents, but with only background traffic.
-1. [Single-Agent](examples/e2_single_agent.py) example.
-   + Run a SMARTS simulation with a single ego agent.
-1. [Multi-Agent](examples/e3_multi_agent.py) example.
-   + Run a SMARTS simulation with multiple ego agents.
-1. [Environment Config](examples/e4_environment_config.py) example.
-   + Demonstrate the main observation/action configuration of the environment.
-1. [Agent Zoo](examples/e5_agent_zoo.py) example.
-   + Demonstrate how the agent zoo works.
-1. [Agent interface example](examples/6_agent_interface.py)
-   + TODO demonstrate how the agent interface works.
-
-### Integration examples
-A few more complex integrations are demonstrated.
-
-1. Configurable example
-   + script: [examples/e7_experiment_base.py](examples/e7_experiment_base.py)
-   + Configurable agent number.
-   + Configurable agent type.
-   + Configurable environment.
-1. Parallel environments
-   + script: [examples/e8_parallel_environment.py](examples/e8_parallel_environment.py)
-   + Multiple SMARTS environments in parallel
-   + ActionSpaceType: LaneWithContinuousSpeed
-
-### RL Examples
-1. [Drive](examples/e10_drive). See [Driving SMARTS 2023.1 & 2023.2](https://smarts.readthedocs.io/en/latest/benchmarks/driving_smarts_2023_1.html) for more info.
-1. [VehicleFollowing](examples/e11_platoon). See [Driving SMARTS 2023.3](https://smarts.readthedocs.io/en/latest/benchmarks/driving_smarts_2023_3.html) for more info.
-1. [PG](examples/e12_rllib/pg_example.py). See [RLlib](https://smarts.readthedocs.io/en/latest/ecosystem/rllib.html) for more info.
-1. [PG Population Based Training](examples/e12_rllib/pg_pbt_example.py). See [RLlib](https://smarts.readthedocs.io/en/latest/ecosystem/rllib.html) for more info.
-
-### RL Environment
-1. [ULTRA](https://github.com/smarts-project/smarts-project.rl/blob/master/ultra) provides a gym-based environment built upon SMARTS to tackle intersection navigation, specifically the unprotected left turn.
+1. Read the docs :notebook_with_decorative_cover: at [smarts.readthedocs.io](https://smarts.readthedocs.io/) :fire:
+1. [Base examples](https://smarts.readthedocs.io/en/latest/examples/base_examples.html)
+1. [RL models](https://smarts.readthedocs.io/en/latest/examples/rl_model.html)
 
 # Issues, Bugs, Feature Requests 
 1. First, read how to communicate issues, report bugs, and request features [here](./docs/resources/contributing.rst#communication).

docs/benchmarks/agent_zoo.rst

@@ -53,16 +53,16 @@ Available zoo agents
      - driving_smarts_2022==0.0
      - :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.TargetPose`
      - `code <https://github.com/smarts-project/smarts-project.rl/tree/master/interaction_aware_motion_prediction>`__
-     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/>`__ competition.
+     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/competition/>`__ competition.
    * - | zoo.policies:control-and-supervised-learning-agent-v0
        | zoo/policies/control_and_supervised_learning
      - driving_smarts_2022==0.0
      - :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.TargetPose`
      - `code <https://github.com/smarts-project/smarts-project.rl/tree/master/control_and_supervised_learning>`__
-     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/>`__ competition.
+     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/competition/>`__ competition.
    * - | zoo.policies:discrete-soft-actor-critic-agent-v0
        | zoo/policies/discrete_soft_actor_critic
      - driving_smarts_2022==0.0
      - :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.TargetPose`
      - `code <https://github.com/smarts-project/smarts-project.rl/tree/master/discrete_soft_actor_critic>`__
-     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/>`__ competition.
+     - Contributed as part of `NeurIPS 2022 Driving SMARTS <https://smarts-project.github.io/archive/2022_nips_driving_smarts/competition/>`__ competition.

docs/conf.py

@@ -148,6 +148,14 @@
     (r"py:class", r".*\.?S"),
 }
 
+# -- Options for broken link checks ------------------------------------------
+linkcheck_anchors = False
+linkcheck_ignore = [
+    r"https?://localhost:\d+/?",
+    r"https?://ops.fhwa.dot.gov.*",  # The ngsim domain (us government) appears to go down sometimes.
+]
+linkcheck_retries = 2
+
 # -- Options for spelling ----------------------------------------------------
 spelling_exclude_patterns = ["ignored_*", "**/*_pb2*"]
 spelling_ignore_pypi_package_names = True

docs/ecosystem/argoverse.rst

@@ -27,6 +27,6 @@ You can then run any of the examples with this scenario:
 
 .. code-block:: sh
 
-    $ scl run --envision examples/egoless.py scenarios/argoverse
+    $ scl run --envision examples/e1_egoless.py scenarios/argoverse
 
 .. image:: /_static/argoverse-replay.gif

docs/ecosystem/ngsim.rst

@@ -88,7 +88,7 @@ To consume the generated observations you could use the following approach:
             ...
 
 
-Alternatively, an approach like :examples:`traffic_histories_vehicle_replacement.py` can be used to operate directly with the scenarios.
+Alternatively, an approach like :examples:`direct/traffic_histories_vehicle_replacement.py` can be used to operate directly with the scenarios.
 
 
 Samples

docs/ecosystem/rllib.rst

@@ -4,16 +4,20 @@
 RLlib
 =====
 
-**RLlib** is an open-source library for reinforcement learning that offers both high scalability and a unified API for a variety
-of applications. ``RLlib`` natively supports ``TensorFlow``, ``TensorFlow Eager``, and ``PyTorch``. Most of its internals are agnostic to such
-deep learning frameworks.
+**RLlib** is an open-source library for reinforcement learning that offers both high scalability and a unified API for a variety of applications. ``RLlib`` natively supports ``TensorFlow``, ``TensorFlow Eager``, and ``PyTorch``. Most of its internals are agnostic to such deep learning frameworks.
 
 SMARTS contains two examples using `Policy Gradients (PG) <https://docs.ray.io/en/latest/rllib-algorithms.html#policy-gradients-pg>`_.
 
-1. ``e12_rllib/pg_example.py``
-This example shows the basics of using RLlib with SMARTS through :class:`~smarts.env.rllib_hiway_env.RLlibHiWayEnv`.
-1. ``e12_rllib/pg_pbt_example.py``
-This example combines Policy Gradients with `Population Based Training (PBT) <https://docs.ray.io/en/latest/tune/api/doc/ray.tune.schedulers.PopulationBasedTraining.html>`_ scheduling.
+#. Policy gradient
+
+    + script: :examples:`e12_rllib/pg_example.py`
+    + Shows the basics of using RLlib with SMARTS through :class:`~smarts.env.rllib_hiway_env.RLlibHiWayEnv`.
+
+#. Policy gradient with population based training
+
+    + script: :examples:`e12_rllib/pg_pbt_example.py`
+    + Combines Policy Gradients with `Population Based Training (PBT) <https://docs.ray.io/en/latest/tune/api/doc/ray.tune.schedulers.PopulationBasedTraining.html>`_ scheduling.
+
 
 Recommended reads
 -----------------
@@ -35,7 +39,7 @@ many docs about ``Ray`` and ``RLlib``. We recommend to read the following pages
 Resume training
 ---------------
 
-With respect to ``SMARTS/examples/rl/rllib`` examples, if you want to continue an aborted experiment, you can set ``resume_training=True``. But note that ``resume_training=True`` will continue to use the same configuration as was set in the original experiment.
+With respect to ``SMARTS/examples/e12_rllib`` examples, if you want to continue an aborted experiment, you can set ``resume_training=True``. But note that ``resume_training=True`` will continue to use the same configuration as was set in the original experiment.
 To make changes to a started experiment, you can edit the latest experiment file in ``./results``.
 
-Or if you want to start a new experiment but train from an existing checkpoint, you will need to look into `How to Save and Load Trial Checkpoints <https://docs.ray.io/en/latest/tune/tutorials/tune-trial-checkpoints>`_.
+Or if you want to start a new experiment but train from an existing checkpoint, you will need to look into `How to Save and Load Trial Checkpoints <https://docs.ray.io/en/latest/tune/tutorials/tune-trial-checkpoints.html#how-to-save-and-load-trial-checkpoints>`_.

docs/ecosystem/sumo.rst

@@ -24,6 +24,6 @@ Build from source
 If you wish to compile SUMO by yourself from source
 
 + Git repository can be found at `https://github.com/eclipse/sumo <https://github.com/eclipse/sumo>`_ .
-+ Use SUMO version `1.7.0 <https://github.com/eclipse/sumo/commits/v1_7_0>`_ or higher.
-+ Build instructions are available at `https://sumo.dlr.de/docs/Developer/Main.html#build_instructions <https://sumo.dlr.de/docs/Developer/Main.html#build_instructions>`_ . 
++ Use SUMO version `1.7.0 <https://github.com/eclipse-sumo/sumo/commits/v1_7_0>`_ or higher.
++ Build instructions are available at `https://sumo.dlr.de/docs/Developer/index.html#build_instructions <https://sumo.dlr.de/docs/Developer/index.html#build_instructions>`_ . 
 + Please note that building SUMO might not install all other vital dependencies that SUMO requires to run.

docs/ecosystem/waymo.rst

@@ -67,7 +67,7 @@ You can then run any of the examples with this scenario:
 
 .. code-block:: sh
 
-    $ scl run --envision examples/egoless.py scenarios/waymo
+    $ scl run --envision examples/e1_egoless.py scenarios/waymo
 
 .. image:: /_static/waymo-replay.gif
 

docs/examples/base_examples.rst

@@ -0,0 +1,55 @@
+.. _base_examples:
+
+Base Examples
+==============
+
+Several examples are made available to help you get started with SMARTS.
+
+
+#. Egoless
+
+    + script: :examples:`e1_egoless.py`
+    + No agent
+    + Using a SMARTS environment without an agent.
+
+#. Single-agent
+
+    + script: :examples:`e2_single_agent.py`
+    + Single-agent
+    + Using a SMARTS environment with a single agent.
+
+#. Multi-agent
+
+    + script: :examples:`e3_multi_agent.py`
+    + Multi-agent
+    + Using a SMARTS environment with multiple agents.
+
+#. Environment configuration
+
+    + script: :examples:`e4_environment_config.py`
+    + Demonstrates how to configure a SMARTS environment.
+
+#. Agent zoo
+
+    + script: :examples:`e5_agent_zoo.py`
+    + Demonstrates how to use the agent zoo to retrieve an agent.
+
+#. Agent configuration
+
+    + script: :examples:`e6_agent_action_space.py`
+    + Demonstrates how to configure the action space for an agent.
+
+#. Experiment base
+
+    + script: :examples:`e7_experiment_base.py`
+    + An example of how to put together a larger experiment with configuration files.
+
+#. Parallel Environments
+
+    + script: :examples:`e8_parallel_environment.py`
+    + A primitive use of SMARTS environments in parallel.
+
+#. Jupyter Notebook
+
+    + script: :examples:`e9_notebook.ipynb`
+    + A primitive use of SMARTS in a Jupyter Notebook.

docs/examples/rl_model.rst

@@ -1,10 +1,24 @@
 .. _rl_model:
 
-RL Model
-========
+RL Models
+=========
 
-.. toctree::
-   :maxdepth: 1
+These examples demonstrate some ways to use SMARTS to generate RL models.
 
-   drive.rst 
-   platoon.rst
+
+#. Driving SMARTS Drive
+
+    + directory: :examples:`e10_drive`
+    + This example was developed in conjunction with the :ref:`Driving SMARTS 2023.1 & 2023.2 <driving_smarts_2023_1>` benchmark, hence refer to it for details.
+
+
+#. Driving SMARTS Platoon
+
+    + directory: :examples:`e11_platoon`
+    + This example was developed in conjunction with the :ref:`Driving SMARTS 2023.3 <driving_smarts_2023_3>` benchmark, hence refer to it for details.
+
+
+#. RLlib
+
+    + directory: :examples:`e12_rllib`
+    + See the :ref:`RLlib integration <rllib>` for additional examples.

docs/index.rst

@@ -64,8 +64,7 @@ If you use SMARTS in your research, please cite the `paper <https://arxiv.org/ab
    :maxdepth: 3
    :caption: Examples
 
-   examples/egoless.rst
-   examples/control.rst
+   examples/base_examples.rst
    examples/rl_model.rst
 
 .. toctree::

docs/quickstart.rst

@@ -43,8 +43,7 @@ Explore
 
 Explore more examples.
 
-(i) :ref:`Egoless <egoless>`
-(ii) :ref:`Control theory <control>`
-(iii) :ref:`RL model <rl_model>`
+(i) :ref:`Base Examples <base_examples>`
+(ii) :ref:`RL model <rl_model>`
 
 A handful of pre-built scenarios are available at :scenarios:`scenarios <>` folder.