Update examples

.github/workflows/ci-base-tests-linux.yml

@@ -31,7 +31,8 @@ jobs:
           pip install --upgrade pip
           pip install wheel==0.38.4
           pip install -e .[camera_obs,opendrive,test,test_notebook,torch,train,gif_recorder,gymnasium,argoverse,envision,sumo]
-          if echo ${{matrix.tests}} | grep -q -e "test_rllib_hiway_env.py" -e "test_examples.py"; then pip install -e .[rllib]; fi
+          if echo ${{matrix.tests}} | grep -q -e "test_rllib_hiway_env.py"; then pip install -e .[rllib]; fi
+          if echo ${{matrix.tests}} | grep -q -e "test_examples.py"; then pip install -e .[examples,rllib]; fi
           if echo ${{matrix.tests}} | grep -q -e "/smarts/ray"; then pip install -e .[ray]; fi
       - name: Build scenarios
         run: |
@@ -71,23 +72,23 @@ jobs:
     strategy:
       matrix:
         tests:
-          - drive
-          - platoon
+          - e10_drive
+          - e11_platoon
     steps:
       - name: Checkout
         uses: actions/checkout@v2
       - name: Install dependencies
         run: |
-          cd ${GITHUB_WORKSPACE}/examples/rl/${{matrix.tests}}
+          cd ${GITHUB_WORKSPACE}/examples/${{matrix.tests}}
           python3.8 -m venv ${{env.venv_dir}}
           . ${{env.venv_dir}}/bin/activate
           pip install --upgrade pip
           pip install wheel==0.38.4
-          pip install -e ./../../../.[camera_obs,argoverse,sumo,test]
+          pip install -e ./../../.[camera_obs,argoverse,sumo,test]
           pip install -e ./inference/
       - name: Run smoke tests
         run: |
-          cd ${GITHUB_WORKSPACE}/examples/rl/${{matrix.tests}}
+          cd ${GITHUB_WORKSPACE}/examples/${{matrix.tests}}
           . ${{env.venv_dir}}/bin/activate
           PYTHONPATH=$PWD PYTHONHASHSEED=42 pytest -v \
             --doctest-modules \
@@ -103,8 +104,8 @@ jobs:
     strategy:
       matrix:
         tests:
-          - drive
-          - platoon
+          - e10_drive
+          - e11_platoon
     steps:
       - name: Checkout
         uses: actions/checkout@v2
@@ -116,7 +117,7 @@ jobs:
           pip install --upgrade pip
           pip install wheel==0.38.4
           pip install -e .[camera_obs,argoverse,test,ray,sumo]
-          scl zoo install examples/rl/${{matrix.tests}}/inference
+          scl zoo install examples/${{matrix.tests}}/inference
       - name: Run smoke tests
         run: |
           cd ${GITHUB_WORKSPACE}

.github/workflows/ci-base-tests-mac.yml

@@ -49,7 +49,8 @@ jobs:
           pip install wheel==0.38.4
           pip install -r utils/setup/mac_requirements.txt
           pip install -e .[camera_obs,opendrive,rllib,test,test_notebook,torch,train,argoverse,envision,sumo]
-          if echo ${{matrix.tests}} | grep -q -e "/env" -e "/examples"; then pip install -e .[rllib]; fi
+          if echo ${{matrix.tests}} | grep -q -e "/env"; then pip install -e .[rllib]; fi
+          if echo ${{matrix.tests}} | grep -q -e "/examples"; then pip install -e .[examples,rllib]; fi
           if echo ${{matrix.tests}} | grep -q "/ray"; then pip install -e .[ray]; fi
       - name: Run smoke tests
         run: |

.gitignore

@@ -73,7 +73,7 @@ target/
 celerybeat-schedule
 
 # Environments
-.venv
+.venv*
 venv
 .bugtest
 
@@ -150,4 +150,7 @@ collected_observations/
 .pytype
 
 # Benchmark
-**/diagnostic/reports/*
+**/diagnostic/reports/*
+
+# Experiments
+outputs/

CHANGELOG.md

@@ -10,12 +10,23 @@ Copy and pasting the git commit messages is __NOT__ enough.
 
 ## [Unreleased] - XXXX-XX-XX
 ### Added
+- SMARTS option `smarts[examples]` added for running SMARTS examples.
 ### Changed
 - The following dependencies have been loosened: `numpy`, `opencv`, `torch`.
+- Clarified engine configuration location under `logging.info` instead of `print`.
+- `ScenarioOrder` enumeration values are now lower-case (e.g. `scrambled` instead of `Scrambled`).
+- `EnvReturnMode`, `ScenarioOrder`, and `SumoOptions` have been moved to `smarts.env.configs.hiway_env_configs`.
+- `trimesh` version has been loosened to `trimesh>=3.9.29`.
 ### Deprecated
 ### Fixed
 - The `smarts` package now works with `python3.10` and `python3.11`.
+- Fixed an issue where default `AgentInterface.events` shared a reference.
+- Episode log now lists current value out of maximum rather than index.
+- Episode log now correctly shows all agent scores.
+- Added `scipy` back to dependencies to fix scenario building.
+- Fixed `gymnasium` floating type cast warnings in action conversion.
 ### Removed
+- Removed previously deprecated `SMARTS.timestep_sec` attribute.
 ### Security
 
 ## [1.3.0] - 2023-07-11

README.md

@@ -17,37 +17,38 @@ Check out the paper at [SMARTS: Scalable Multi-Agent Reinforcement Learning Trai
 :rotating_light: :bell: Read the docs :notebook_with_decorative_cover: at [smarts.readthedocs.io](https://smarts.readthedocs.io/) . :bell: :rotating_light:
 
 # Examples 
-### Egoless
-Simulate a SMARTS environment without any ego agents, but with only background traffic.
-1. [Egoless](examples/egoless.py) example.
+### 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.
 
-### Control Theory
-Several agent control policies and agent [action types](smarts/core/controllers/__init__.py) are demonstrated.
+### Integration examples
+A few more complex integrations are demonstrated.
 
-1. Chase Via Points
-   + script: [control/chase_via_points.py](examples/control/chase_via_points.py)
-   + Multi agent
-   + ActionSpaceType: LaneWithContinuousSpeed
-1. Trajectory Tracking
-   + script: [control/trajectory_tracking.py](examples/control/trajectory_tracking.py)
-   + ActionSpaceType: Trajectory
-1. OpEn Adaptive Control
-   + script: [control/ego_open_agent.py](examples/control/ego_open_agent.py)
-   + ActionSpaceType: MPC
-1. Laner
-   + script: [control/laner.py](examples/control/laner.py)
-   + Multi agent
-   + ActionSpaceType: Lane
+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: [control/parallel_environment.py](examples/control/parallel_environment.py)
+   + script: [examples/e8_parallel_environment.py](examples/e8_parallel_environment.py)
    + Multiple SMARTS environments in parallel
    + ActionSpaceType: LaneWithContinuousSpeed
 
-### RL Model
-1. [Drive](examples/rl/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/rl/platoon). See [Driving SMARTS 2023.3](https://smarts.readthedocs.io/en/latest/benchmarks/driving_smarts_2023_3.html) for more info.
-1. [PG](examples/rl/rllib/pg_example.py). See [RLlib](https://smarts.readthedocs.io/en/latest/ecosystem/rllib.html) for more info.
-1. [PG Population Based Training](examples/rl/rllib/pg_pbt_example.py). See [RLlib](https://smarts.readthedocs.io/en/latest/ecosystem/rllib.html) for more info.
+### 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.

docs/benchmarks/driving_smarts_2023_1.rst

@@ -178,7 +178,7 @@ the user.
                 agent_params=agent_params,
             )
 
-        register(locator="contrib-agent-v0", entry_point=entry_point)
+        register("contrib-agent-v0", entry_point=entry_point)
 
     + User may fill in the ``<...>`` spaces in the template.
     + User may specify the ego's interface by configuring any field of :class:`~smarts.core.agent_interface.AgentInterface`, except
@@ -239,7 +239,7 @@ Example
 -------
 
 An example training and inference code is provided for this benchmark. 
-See the :examples:`rl/drive` example. The example uses PPO algorithm from 
+See the :examples:`e10_drive` example. The example uses PPO algorithm from 
 `Stable Baselines3 <https://github.com/DLR-RM/stable-baselines3>`_ reinforcement learning library.
 It uses :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.RelativeTargetPose` action space.
 Instructions for training and evaluating the example is as follows.
@@ -251,12 +251,12 @@ Train
   .. code-block:: bash
 
     # In terminal-A
-    $ cd <path>/SMARTS/examples/rl/drive
+    $ cd <path>/SMARTS/examples/e10_drive
     $ python3.8 -m venv ./.venv
     $ source ./.venv/bin/activate
     $ pip install --upgrade pip
     $ pip install wheel==0.38.4
-    $ pip install -e ./../../../.[camera_obs,argoverse,envision,sumo]
+    $ pip install -e ./../../.[camera_obs,argoverse,envision,sumo]
     $ pip install -e ./inference/
 
 + Train locally without visualization
@@ -271,7 +271,7 @@ Train
   .. code-block:: bash
 
     # In a different terminal-B
-    $ cd <path>/SMARTS/examples/rl/drive
+    $ cd <path>/SMARTS/examples/e10_drive
     $ source ./.venv/bin/activate
     $ scl envision start
     # Open http://localhost:8081/
@@ -281,7 +281,7 @@ Train
     # In terminal-A
     $ python3.8 train/run.py --head
 
-+ Trained models are saved by default inside the ``<path>/SMARTS/examples/rl/drive/train/logs/`` folder.
++ Trained models are saved by default inside the ``<path>/SMARTS/examples/e10_drive/train/logs/`` folder.
 
 Docker
 ^^^^^^
@@ -290,14 +290,14 @@ Docker
   .. code-block:: bash
 
     $ cd <path>/SMARTS
-    $ docker build --file=./examples/rl/drive/train/Dockerfile --network=host --tag=drive .
+    $ docker build --file=./examples/e10_drive/train/Dockerfile --network=host --tag=drive .
     $ docker run --rm -it --network=host --gpus=all drive
-    (container) $ cd /SMARTS/examples/rl/drive
+    (container) $ cd /SMARTS/examples/e10_drive
     (container) $ python3.8 train/run.py
 
 Evaluate
 ^^^^^^^^
-+ Choose a desired saved model from the previous training step, rename it as ``saved_model.zip``, and move it to ``<path>/SMARTS/examples/rl/drive/inference/contrib_policy/saved_model.zip``.
++ Choose a desired saved model from the previous training step, rename it as ``saved_model.zip``, and move it to ``<path>/SMARTS/examples/e10_drive/inference/contrib_policy/saved_model.zip``.
 + Evaluate locally
 
   .. code-block:: bash
@@ -308,11 +308,11 @@ Evaluate
     $ pip install --upgrade pip
     $ pip install wheel==0.38.4
     $ pip install -e .[camera_obs,argoverse,envision,sumo]
-    $ scl zoo install examples/rl/drive/inference
+    $ scl zoo install examples/e10_drive/inference
     # For Driving SMARTS 2023.1
-    $ scl benchmark run driving_smarts_2023_1 examples.rl.drive.inference:contrib-agent-v0 --auto-install
+    $ scl benchmark run driving_smarts_2023_1 examples.e10_drive.inference:contrib-agent-v0 --auto-install
     # For Driving SMARTS 2023.2
-    $ scl benchmark run driving_smarts_2023_2 examples.rl.drive.inference:contrib-agent-v0 --auto-install
+    $ scl benchmark run driving_smarts_2023_2 examples.e10_drive.inference:contrib-agent-v0 --auto-install
 
 Zoo agents
 ----------

docs/benchmarks/driving_smarts_2023_3.rst

@@ -156,7 +156,7 @@ the user.
                 agent_params=agent_params,
             )
 
-        register(locator="contrib-agent-v0", entry_point=entry_point)
+        register("contrib-agent-v0", entry_point=entry_point)
 
     + User may fill in the ``<...>`` spaces in the template.
     + User may specify the ego's interface by configuring any field of :class:`~smarts.core.agent_interface.AgentInterface`, except
@@ -217,7 +217,7 @@ Example
 -------
 
 An example training and inference code is provided for this benchmark. 
-See the :examples:`rl/platoon` example. The example uses PPO algorithm from 
+See the :examples:`e11_platoon` example. The example uses PPO algorithm from 
 `Stable Baselines3 <https://github.com/DLR-RM/stable-baselines3>`_ reinforcement learning library. 
 It uses :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.Continuous` action space.
 Instructions for training and evaluating the example is as follows.
@@ -229,12 +229,12 @@ Train
   .. code-block:: bash
 
     # In terminal-A
-    $ cd <path>/SMARTS/examples/rl/platoon
+    $ cd <path>/SMARTS/examples/e11_platoon
     $ python3.8 -m venv ./.venv
     $ source ./.venv/bin/activate
     $ pip install --upgrade pip
     $ pip install wheel==0.38.4
-    $ pip install -e ./../../../.[camera_obs,argoverse,envision,sumo]
+    $ pip install -e ./../../.[camera_obs,argoverse,envision,sumo]
     $ pip install -e ./inference/
 
 + Train locally without visualization
@@ -249,7 +249,7 @@ Train
   .. code-block:: bash
 
     # In a different terminal-B
-    $ cd <path>/SMARTS/examples/rl/platoon
+    $ cd <path>/SMARTS/examples/e11_platoon
     $ source ./.venv/bin/activate
     $ scl envision start
     # Open http://localhost:8081/
@@ -259,7 +259,7 @@ Train
     # In terminal-A
     $ python3.8 train/run.py --head
 
-+ Trained models are saved by default inside the ``<path>/SMARTS/examples/rl/platoon/train/logs/`` folder.
++ Trained models are saved by default inside the ``<path>/SMARTS/examples/e11_platoon/train/logs/`` folder.
 
 Docker
 ^^^^^^
@@ -268,14 +268,14 @@ Docker
   .. code-block:: bash
 
     $ cd <path>/SMARTS
-    $ docker build --file=./examples/rl/platoon/train/Dockerfile --network=host --tag=platoon .
+    $ docker build --file=./examples/e11_platoon/train/Dockerfile --network=host --tag=platoon .
     $ docker run --rm -it --network=host --gpus=all platoon
-    (container) $ cd /SMARTS/examples/rl/platoon
+    (container) $ cd /SMARTS/examples/e11_platoon
     (container) $ python3.8 train/run.py
 
 Evaluate
 ^^^^^^^^
-+ Choose a desired saved model from the previous training step, rename it as ``saved_model.zip``, and move it to ``<path>/SMARTS/examples/rl/platoon/inference/contrib_policy/saved_model.zip``. 
++ Choose a desired saved model from the previous training step, rename it as ``saved_model.zip``, and move it to ``<path>/SMARTS/examples/e11_platoon/inference/contrib_policy/saved_model.zip``. 
 + Evaluate locally
 
   .. code-block:: bash
@@ -286,8 +286,8 @@ Evaluate
     $ pip install --upgrade pip
     $ pip install wheel==0.38.4
     $ pip install -e .[camera_obs,argoverse,envision,sumo]
-    $ scl zoo install examples/rl/platoon/inference
-    $ scl benchmark run driving_smarts_2023_3 examples.rl.platoon.inference:contrib-agent-v0 --auto-install
+    $ scl zoo install examples/e11_platoon/inference
+    $ scl benchmark run driving_smarts_2023_3 examples.e11_platoon.inference:contrib-agent-v0 --auto-install
 
 Zoo agents
 ----------

docs/conf.py

@@ -121,6 +121,7 @@
     ("py:class", "ActType"),
     ("py:class", "ObsType"),
     ("py:class", "smarts.env.gymnasium.wrappers.metric.utils.T"),
+    ("py:class", "enum.Enum"),
 }
 nitpick_ignore_regex = {
     (r"py:.*", r"av2\..*"),

docs/ecosystem/rllib.rst

@@ -10,9 +10,9 @@ deep learning frameworks.
 
 SMARTS contains two examples using `Policy Gradients (PG) <https://docs.ray.io/en/latest/rllib-algorithms.html#policy-gradients-pg>`_.
 
-1. ``rllib/pg_example.py``
+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. ``rllib/pg_pbt_example.py``
+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.
 
 Recommended reads

docs/quickstart.rst

@@ -16,25 +16,23 @@ A typical workflow would look like this.
 Example
 -------
 
-In this quickstart guide, we will run the `Chase Via Points` example. Here,
+In this quickstart guide, we will run the `multi-agent` example. Here,
 
 1. a pre-designed scenario :scenarios:`scenarios/sumo/loop <sumo/loop>` is used.
-2. a simple agent with `interface` == :attr:`~smarts.core.agent_interface.AgentType.LanerWithSpeed` and `policy` == `Chase Via Points` is demonstrated. The agent chases via points or follows nearby waypoints if a via point is unavailable.
+2. a simple agent with `interface` == :attr:`~smarts.core.agent_interface.AgentType.Laner` and `policy` == `Random Laner` is demonstrated. The agent chases via points or follows nearby waypoints if a via point is unavailable.
 
-File: :examples:`examples/control/chase_via_points.py <control/chase_via_points.py>`
+File: :examples:`examples/e3_multi_agent.py <e3_multi_agent.py>`
 
-.. literalinclude:: ../examples/control/chase_via_points.py
+.. literalinclude:: ../examples/e3_multi_agent.py
     :language: python
 
 Use the `scl` command to run SMARTS together with it's supporting processes. 
 
 .. code-block:: bash
 
     $ cd <path>/SMARTS
-    # Build the scenario `scenarios/sumo/loop`.
-    $ scl scenario build scenarios/sumo/loop
     # Run SMARTS simulation with Envision display and `loop` scenario.
-    $ scl run --envision examples/control/chase_via_points.py scenarios/sumo/loop 
+    $ scl run --envision examples/e3_multi_agent.py scenarios/sumo/loop 
 
 Visit `http://localhost:8081/ <http://localhost:8081/>`_ to view the experiment.