Apply Daniel's recommendations

docs/simulators.rst

@@ -16,7 +16,7 @@ See the individual entries for details on each interface's capabilities and how
 Currently Supported
 ===================
 
-MetaDrive (Optional)
+MetaDrive
 ----------------------------
 
 Scenic supports integration with the `MetaDrive <https://metadriverse.github.io/metadrive/>`_ simulator as an optional dependency,
@@ -25,7 +25,7 @@ If your system supports it, you can install it with:
 
 .. code-block:: console
 
-    pip install scenic[metadrive]
+    python -m pip install scenic[metadrive]
 
 Scenic supports both 2D and 3D rendering modes for MetaDrive simulations.
 2D rendering is available on all systems, providing a top-down view.
@@ -36,11 +36,7 @@ These issues are expected to be addressed in the next version of MetaDrive.
 Scenic uses OpenDRIVE maps, while MetaDrive relies on SUMO maps. Scenic provides corresponding SUMO maps for OpenDRIVE maps under the :file:`assets/maps/CARLA` directory.
 Additionally, you can convert your own OpenDRIVE maps to SUMO maps using the `netconvert <https://sumo.dlr.de/docs/Networks/Import/OpenDRIVE.html/>`_ tool.
 To avoid setting the SUMO map manually, name it the same as your OpenDRIVE file and place it in the same directory.
-Otherwise, specify it explicitly with:
-
-.. code-block:: console
-
-    --param sumo_map your_map.net.xml
+Otherwise, you can specify it explicitly using the ``sumo_map`` global parameter.
 
 The simulator is compatible with scenarios written using Scenic's :ref:`driving_domain`.
 For more information, refer to the documentation of the `scenic.simulators.metadrive` module.

docs/tutorials/dynamics.rst

@@ -396,14 +396,14 @@ You can see all of the above syntax in action by running some of our examples of
 scenarios. We have examples written for the CARLA and LGSVL driving simulators, and those
 in :file:`examples/driving` in particular are designed to use Scenic's abstract
 :ref:`driving domain <driving_domain>` and so work in either of these simulators, as well
-as Scenic's built-in Newtonian physics simulator and MetaDrive simulator. While the Newtonian simulator is convenient
+as Scenic's built-in Newtonian physics simulator and the MetaDrive simulator. While the Newtonian simulator is convenient
 for testing simple experiments, we recommend using MetaDrive for more realistic driving scenarios.
 
 MetaDrive support is **optional**. If your system supports MetaDrive, you can install it separately using:
 
 .. code-block:: console
 
-    pip install scenic[metadrive]
+    python -m pip install scenic[metadrive]
 
 If MetaDrive is **not available**, we recommend using the Newtonian simulator instead.
 
@@ -423,7 +423,7 @@ usual schematic diagram of the generated scenes:
 To run dynamic simulations, add the :option:`--simulate` option (:option:`-S` for short).
 Since this scenario is not written for a particular simulator, you'll need to specify
 which one you want by using the :option:`--model` option (:option:`-m` for short) to
-select the corresponding Scenic :term:`world model`: for example, to use the Metadrive simulator we could add
+select the corresponding Scenic :term:`world model`: for example, to use the MetaDrive simulator we could add
 ``--model scenic.simulators.metadrive.model``.
 It's also a good idea to put a time bound on the simulations, which we can do using the :option:`--time` option.
 

examples/driving/Carla_Challenge/carlaChallenge2.scenic

@@ -5,7 +5,7 @@ ego-vehicle must react, performing an emergency brake or an avoidance maneuver.
 Note: The scenario may fail if the leadCar or the ego get past the intersection while following the roadDirection
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
+    scenic examples/driving/Carla_Challenge/carlaChallenge2.scenic --2d --model scenic.simulators.metadrive.model --simulate
 
 To run this file using the Carla simulator:
     scenic examples/driving/Carla_Challenge/carlaChallenge2.scenic --2d --model scenic.simulators.carla.model --simulate

examples/driving/OAS_Scenarios/oas_scenario_03.scenic

@@ -3,7 +3,7 @@ Voyage OAS Scenario Unique ID: 2-2-XX-CF-STR-CAR
 The ego vehicle follows the lead car
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
+    scenic examples/driving/OAS_Scenarios/oas_scenario_03.scenic --2d --model scenic.simulators.metadrive.model --simulate
 
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_03.scenic --2d --model scenic.simulators.carla.model --simulate

examples/driving/OAS_Scenarios/oas_scenario_04.scenic

@@ -3,8 +3,8 @@ Voyage OAS Scenario Unique ID: 2-2-XX-CF-STR-CAR:01
 The ego vehicle follows the lead car which suddenly stops
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/OAS_Scenarios/oas_scenario_04.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_04.scenic --2d --model scenic.simulators.carla.model --simulate
 """

examples/driving/OAS_Scenarios/oas_scenario_28.scenic

@@ -5,8 +5,8 @@ The other car, on the other leg of the intersection, takes a left turn first
 because it is closer to the intersection.
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/OAS_Scenarios/oas_scenario_28.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_28.scenic --2d --model scenic.simulators.carla.model --simulate
 """

examples/driving/OAS_Scenarios/oas_scenario_29.scenic

@@ -5,8 +5,8 @@ The other car, on a different leg of the intersection,
 has the right of the way and makes a left turn first because it is closer to the intersection.
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/OAS_Scenarios/oas_scenario_29.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_29.scenic --2d --model scenic.simulators.carla.model --simulate
 """

examples/driving/OAS_Scenarios/oas_scenario_30.scenic

@@ -5,8 +5,8 @@ The other car approaches from a different leg of the intersection to make a left
 ego has the right of the way because it is closer to the intersection.
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/OAS_Scenarios/oas_scenario_30.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_30.scenic --2d --model scenic.simulators.carla.model --simulate
 """

examples/driving/OAS_Scenarios/oas_scenario_32.scenic

@@ -4,8 +4,8 @@ At 3-way intersection, ego turns left and the other car on a different leg of th
 intersection goes straight. There is no requirement on which vehicle has the right of the way.
 
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/OAS_Scenarios/oas_scenario_32.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/OAS_Scenarios/oas_scenario_32.scenic --2d --model scenic.simulators.carla.model --simulate
 """

examples/driving/badlyParkedCarPullingIn.scenic

@@ -1,7 +1,7 @@
 '''
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/badlyParkedCarPullingIn.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/badlyParkedCarPullingIn.scenic --2d --model scenic.simulators.carla.model --simulate
 '''

examples/driving/car.scenic

@@ -1,7 +1,7 @@
 '''
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/car.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/car.scenic --2d --model scenic.simulators.carla.model --simulate
 '''

examples/driving/pedestrian.scenic

@@ -1,7 +1,7 @@
 '''
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/pedestrian.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/pedestrian.scenic --2d --model scenic.simulators.carla.model --simulate
 '''

examples/driving/pedestrianAcrossRoad.scenic

@@ -1,7 +1,7 @@
 '''
 To run this file using the MetaDrive simulator:
-    scenic examples/driving/Carla_Challenge/carlaChallenge3.scenic --2d --model scenic.simulators.metadrive.model --simulate
-    
+    scenic examples/driving/pedestrianAcrossRoad.scenic --2d --model scenic.simulators.metadrive.model --simulate
+
 To run this file using the Carla simulator:
     scenic examples/driving/pedestrianAcrossRoad.scenic --2d --model scenic.simulators.carla.model --simulate
 '''

src/scenic/simulators/metadrive/model.scenic

@@ -10,8 +10,8 @@ in scenarios using the ``param`` statement or on the command line using the
 
 Global Parameters:
     sumo_map (str or Path): Path to the SUMO map (``.net.xml`` file) to use in the simulation.
-        This map should correspond to the **map** file used in the scenario, which must be in the OpenDrive
-        format (``.xodr`` file).
+        This map should correspond to the **map** file used in the scenario. See the documentation in
+        :doc:`scenic.domains.driving.model` for details.
     timestep (float): The interval (in seconds) between each simulation step. This determines how often Scenic
         interrupts MetaDrive to run behaviors, check requirements, and update the simulation state.
         The default value is 0.1 seconds.
@@ -20,8 +20,7 @@ Global Parameters:
     render3D (bool): Whether to render the simulation in 3D. If True, it will render the simulation in 3D.
         If False (default), it will render in 2D.
     real_time (bool): If True (default), the simulation will run in real time, ensuring each step takes at least
-        as long as the specified timestep. If False, the simulation may run faster, based on the time it takes
-        to process each step.
+        as long as the specified timestep. If False, the simulation runs as fast as possible.
 """
 import pathlib
 
@@ -38,19 +37,19 @@ except ModuleNotFoundError:
     # for convenience when testing without the metadrive package
     from scenic.core.simulators import SimulatorInterfaceWarning
     import warnings
-    warnings.warn('The "metadrive" package is not installed; '
+    warnings.warn('The "metadrive-simulator" package is not installed; '
                   'will not be able to run dynamic simulations',
                   SimulatorInterfaceWarning)
 
     def MetaDriveSimulator(*args, **kwargs):
-        """Dummy simulator to allow compilation without the 'metadrive' package.
+        """Dummy simulator to allow compilation without the 'metadrive-simulator' package.
 
         :meta private:
         """
-        raise RuntimeError('the "metadrive" package is required to run simulations '
+        raise RuntimeError('the "metadrive-simulator" package is required to run simulations '
                            'from this scenario')
 
-if globalParameters.get("sumo_map") is None:
+if "sumo_map" not in globalParameters:
     sumo_map_path = str(pathlib.Path(globalParameters.map).with_suffix(".net.xml"))
 
     if not pathlib.Path(sumo_map_path).exists():

src/scenic/simulators/metadrive/simulator.py

@@ -5,7 +5,7 @@
     from metadrive.component.vehicle.vehicle_type import DefaultVehicle
 except ImportError as e:
     raise ModuleNotFoundError(
-        "Metadrive is required. Please install the 'metadrive' package (and sumolib) or use scenic[metadrive]."
+        "Metadrive is required. Please install the 'metadrive-simulator' package (and sumolib) or use scenic[metadrive]."
     ) from e
 
 import logging

src/scenic/simulators/metadrive/utils.py

@@ -9,7 +9,7 @@
     from metadrive.obs.observation_base import DummyObservation
 except ImportError as e:
     raise ModuleNotFoundError(
-        'Metadrive scenarios require the "metadrive" package'
+        'Metadrive scenarios require the "metadrive-simulator" package'
     ) from e
 
 import math