Merge branch 'master' into tucker/feature-gpu-images

.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

@@ -10,10 +10,54 @@ Copy and pasting the git commit messages is __NOT__ enough.
 
 ## [Unreleased] - XXXX-XX-XX
 ### Added
+- Added a utility method `SMARTS.prepare_observe_from()` which allows safely adding sensors to vehicles.
+- The following methods now exist explicitly `Vehicle.{add_sensor|detach_sensor|subscribed_to|sensor_property|}`.
+- Resources loaded with `load_yaml_config_with_substitution()` now substitute in SMARTS configuration with single squiggle bracket `${}` syntax. This is currently restricted to environment variable names prefixed with `"SMARTS_"`. This extends to benchmark configuration and vehicle configuration.
+- Default vehicle definitions can be now modified using `assets:default_vehicle_definitions_list`/`SMARTS_ASSSETS_DEFAULT_VEHICLE_DEFINITIONS_LIST` or by providing a `vehicle_definitions_list.yaml` in the scenario. These vehicle types are related to the `AgentInterface.vehicle_type` attribute.
 ### 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.
+- `rllib` is now constrained as `<=2.9,>2.4`.
+- The `examples/e12_rllib` training examples `{pg_example|pg_pbt_example}.py` have been changed to `{ppo_example|ppo_pbt_example}.py`. `Policy Gradients (PG)` has been dropped in favor of the more well documented `Proximal Policy Optimization (PPO)`.
+- Vehicles can now have sensors added to, overwritten, or replaced outright.
+- Logging is now improved to give information about sensor changes in the sensor manager.
+- - Renamed `vehicle.urdf` to `sedan.urdf`.
+- Environment prefix is now configurable for custom `smarts.core.config()` calls.
+- `Vehicle.build_agent_vehicle()` argument `vehicle_filepath` now renamed to `vehicle_dynamics_filepath`.
+- Renamed `MACOS` `pybullet` gui utility from `smarts.core.utils.bullet.BulletClient` to `smarts.core.utils.pybullet.BulletClientMACOS`.
+- `Vehicle.build_agent_vehicle()` and `Vehicle.build_social_vehicle()` moved to `VehicleIndex`.
+- `smarts.core.configuration.Configuration.get_settings()` now uses the `PyYAML` default instead of forcefully casting to `str`.
+- Added `AgentInterface.vehicle_class` which allows selection of a dynamics vehicle from the vehicle definitions list file.
 - Waypoints now have a `position` property (which will eventually replace `pos`).
+- You must now implement `act()` for any agent inheriting from `smarts.core.agent.Agent`.
+- `FunctionAgent` is now no longer dynamically defined.
 ### Deprecated
+- Module `smarts.core.models` is now deprecated in favour of `smarts.assets`.
+- Deprecated a few things related to vehicles in the `Scenario` class, including the `vehicle_filepath`, `tire_parameters_filepath`, and `controller_parameters_filepath`. The functionality is now handled through the vehicle definitions.
+- `AgentInterface.vehicle_type` is now deprecated with potential to be restored.
 ### 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 a bug where `smarts.core.vehicle_index.VehicleIndex.attach_sensors_to_vehicle()` would pass a method instead of a `PlanFrame` to the generated vehicle `SensorState`.
+- 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.
+- Fixed an issue where the `e12_rllib` examples would use the wrong path for the default loop scenario.
+- Fixed an issue where the sensor state could be `None` when calling `SMARTS.observe_from()` on a non-ego vehicle. See #2133.
+- The via sensor and trip meter sensor now work without a mission.
+- Fixed a bug with `VehicleIndex.attach_sensors_to_vehicle()` that would generate an invalid plan.
+- Fixed a bug where vehicle sensor meta attributes would reference the wrong vehicle.
 - Resolved issue with road waypoints not showing waypoints if the horizon was larger than the start of the lane.
 ### Removed
 ### Security

MANIFEST.in

@@ -1,8 +1,7 @@
 include smarts/core/glsl/*.vert smarts/core/glsl/*.frag
-include smarts/core/models/*.glb smarts/core/models/*.urdf
-include smarts/core/models/controller_parameters.yaml
 include envision/web/dist/*
 include smarts/*.ini
+recursive-include smarts/assets *.glb *.urdf *.yaml *.yml
 recursive-include smarts/benchmark *.yaml *.yml
 recursive-include smarts/ros/src *.launch *.msg *.srv package.xml CMakeLists.txt *.py
 recursive-include smarts/scenarios *.xml *.py

Makefile

@@ -36,7 +36,7 @@ sanity-test: build-sanity-scenarios
 		./smarts/core/tests/test_dynamics_backend.py::test_set_pose \
 		./smarts/core/tests/test_sensors.py::test_waypoints_sensor \
 		./smarts/core/tests/test_smarts.py::test_smarts_doesnt_leak_tasks_after_reset \
-		./examples/tests/test_examples.py::test_examples \
+		./examples/tests/test_examples.py::test_examples[e2_single_agent] \
 		./smarts/env/tests/test_social_agent.py::test_social_agents_not_in_env_obs_keys
 
 .PHONY: test-learning
@@ -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/benchmarks/benchmark.rst

@@ -108,18 +108,5 @@ The benchmark listing file is organized as below.
            params: # Additional values to pass into the entrypoint as named keyword arguments.
              benchmark_config: ${{smarts.benchmark.driving_smarts.v2022}}/config.yaml
 
-.. note:: 
-
-    Resolving module directories.
 
-    The benchmark configuration directory can be dynamically found through
-    python using an evaluation syntax ``${{}}``. This is experimental and
-    open to change but the following resolves the python module location in
-    loaded configuration files:
-
-    .. code:: yaml
-
-        somewhere_path: ${{module.to.resolve}}/file.txt # resolves to <path>/module/to/resolve/file.txt
-
-    This avoids loading the module into python but resolves to the first
-    path that matches the module.
+See :ref:`engine_configuration` for more details.

docs/conf.py

@@ -47,12 +47,16 @@
 ]
 
 extlinks = {
+    "assets": (
+        "https://github.com/huawei-noah/SMARTS/tree/master/smarts/assets/%s",
+        "%s",
+    ),
     "examples": (
-        "https://github.com/huawei-noah/SMARTS/blob/master/examples/%s",
+        "https://github.com/huawei-noah/SMARTS/tree/master/examples/%s",
         "%s",
     ),
     "scenarios": (
-        "https://github.com/huawei-noah/SMARTS/blob/master/scenarios/%s",
+        "https://github.com/huawei-noah/SMARTS/tree/master/scenarios/%s",
         "%s",
     ),
 }
@@ -148,6 +152,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