diff --git a/docs/ecosystem/argoverse.rst b/docs/ecosystem/argoverse.rst index ba776c21bd..91ebca404c 100644 --- a/docs/ecosystem/argoverse.rst +++ b/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 diff --git a/docs/ecosystem/rllib.rst b/docs/ecosystem/rllib.rst index 778eb26142..95440c2698 100644 --- a/docs/ecosystem/rllib.rst +++ b/docs/ecosystem/rllib.rst @@ -35,7 +35,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 `_. diff --git a/docs/ecosystem/waymo.rst b/docs/ecosystem/waymo.rst index 5ba540312e..b9da591937 100644 --- a/docs/ecosystem/waymo.rst +++ b/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 diff --git a/docs/examples/base_examples.rst b/docs/examples/base_examples.rst new file mode 100644 index 0000000000..f5f376740b --- /dev/null +++ b/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.py` + + A primitive use of SMARTS in a Jupyter Notebook. diff --git a/docs/examples/control.rst b/docs/examples/control.rst deleted file mode 100644 index 05249da4a2..0000000000 --- a/docs/examples/control.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _control: - -Control Theory -============== - -Several agent control policies and agent :class:`~smarts.core.controllers.action_space_type.ActionSpaceType` are demonstrated. Run these examples as follows. - -.. code-block:: bash - - $ cd /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/.py scenarios/sumo/loop - # Visit http://localhost:8081/ to view the experiment. - - -#. Chase Via Points - - + script: :examples:`control/chase_via_points.py` - + Multi agent - + ActionSpaceType: :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.LaneWithContinuousSpeed` - -#. Trajectory Tracking - - + script: :examples:`control/trajectory_tracking.py` - + ActionSpaceType: :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.Trajectory` - -#. OpEn Adaptive Control - - + script: :examples:`control/ego_open_agent.py` - + ActionSpaceType: :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.MPC` - -#. Laner - - + script: :examples:`control/laner.py` - + Multi agent - + ActionSpaceType: :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.Lane` - -#. Parallel Environments - - + script: :examples:`control/parallel_environment.py` - + Multiple SMARTS environments in parallel - + ActionSpaceType: :attr:`~smarts.core.controllers.action_space_type.ActionSpaceType.LaneWithContinuousSpeed` diff --git a/docs/examples/drive.rst b/docs/examples/drive.rst deleted file mode 100644 index 98f53b54c2..0000000000 --- a/docs/examples/drive.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _drive: - -Drive -===== - -This example was developed in conjunction with the :ref:`Driving SMARTS 2023.1 & 2023.2 ` benchmark, hence refer to it for details. diff --git a/docs/examples/egoless.rst b/docs/examples/egoless.rst deleted file mode 100644 index 51acf598bf..0000000000 --- a/docs/examples/egoless.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _egoless: - -Egoless -======= - -Simulate a SMARTS environment without any ego agents, but with only background traffic. Run these examples as follows. - -.. code-block:: bash - - $ cd /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/.py scenarios/sumo/loop - # Visit http://localhost:8081/ to view the experiment. - - -#. Egoless - - + script: :examples:`egoless.py` diff --git a/docs/examples/platoon.rst b/docs/examples/platoon.rst deleted file mode 100644 index ca3b216fad..0000000000 --- a/docs/examples/platoon.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _platoon: - -Platoon -======= - -This example was developed in conjunction with the :ref:`Driving SMARTS 2023.3 ` benchmark, hence refer to it for details. diff --git a/docs/examples/rl_model.rst b/docs/examples/rl_model.rst index a0c5646326..e0749d57eb 100644 --- a/docs/examples/rl_model.rst +++ b/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 \ No newline at end of file + +#. Driving SMARTS Drive + + + directory: :examples:`e10_drive` + + This example was developed in conjunction with the :ref:`Driving SMARTS 2023.1 & 2023.2 ` 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 ` benchmark, hence refer to it for details. + + +#. RLlib + + + directory: :examples:`e12_rllib` + + See the :ref:`RLlib integration ` for additional examples. diff --git a/docs/index.rst b/docs/index.rst index 40cc96b7d4..942675f284 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,8 +64,7 @@ If you use SMARTS in your research, please cite the `paper ` -(ii) :ref:`Control theory ` -(iii) :ref:`RL model ` +(i) :ref:`Base Examples ` +(ii) :ref:`RL model ` A handful of pre-built scenarios are available at :scenarios:`scenarios <>` folder. diff --git a/docs/resources/containers.rst b/docs/resources/containers.rst index 9126cfd8ad..44b8ef7c37 100644 --- a/docs/resources/containers.rst +++ b/docs/resources/containers.rst @@ -23,7 +23,7 @@ SMARTS docker images are hosted at `dockerhub `_ # 1. Run container in interactive mode. $ singularity shell --containall --bind ../SMARTS:/src ./utils/singularity/smarts.sif # Inside the container - Singularity> python3.8 /src/examples/control/chase_via_points.py /src/scenarios/sumo/loop/ --headless + Singularity> python3.8 /src/examples/e2_single_agent.py /src/scenarios/sumo/loop/ --headless # 2. Run commands within the container from the host system. - $ singularity exec --containall --bind ../SMARTS:/src ./utils/singularity/smarts.sif python3.8 /src/examples/control/chase_via_points.py /src/scenarios/sumo/loop/ --headless + $ singularity exec --containall --bind ../SMARTS:/src ./utils/singularity/smarts.sif python3.8 /src/examples/e2_single_agent.py /src/scenarios/sumo/loop/ --headless # 3. Run container instance in the background. - $ singularity instance start --containall --bind ../SMARTS:/src ./utils/singularity/smarts.sif smarts_train /src/examples/control/chase_via_points.py /src/scenarios/sumo/loop/ --headless + $ singularity instance start --containall --bind ../SMARTS:/src ./utils/singularity/smarts.sif smarts_train /src/examples/e2_single_agent.py /src/scenarios/sumo/loop/ --headless diff --git a/docs/resources/contributing.rst b/docs/resources/contributing.rst index 791d356132..e69c687bdb 100644 --- a/docs/resources/contributing.rst +++ b/docs/resources/contributing.rst @@ -145,4 +145,4 @@ Things inevitably become slow, when this happens, Flame Graph is a great tool to $ mkdir -p flamegraph_dir $ curl https://raw.githubusercontent.com/brendangregg/FlameGraph/master/flamegraph.pl > ./utils/third_party/tools/flamegraph.pl $ chmod 777 {$flamegraph_dir}/flamegraph.pl - $ make flamegraph scenario=./scenarios/sumo/loop script=./examples/control/chase_via_points.py \ No newline at end of file + $ make flamegraph scenario=./scenarios/sumo/loop script=./examples/e2_single_agent.py \ No newline at end of file diff --git a/docs/sim/visualization.rst b/docs/sim/visualization.rst index 1bc1cf28a7..9f2e18ff58 100644 --- a/docs/sim/visualization.rst +++ b/docs/sim/visualization.rst @@ -23,7 +23,7 @@ An example is shown below to run SMARTS with Envision. # Build scenarios/sumo/loop $ scl scenario build --clean scenarios/sumo/loop # Run the chase_via_points.py example with the loop scenario - $ scl run --envision examples/control/chase_via_points.py scenarios/sumo/loop + $ scl run --envision examples/e2_single_agent.py scenarios/sumo/loop ``--envision`` flag is added to ``scl run`` to enable the Envision server. Visit `http://localhost:8081/ `_ in your browser to see the environment visualization. Select the simulator instance in the top left drop-down. If you are using SMARTS on a remote machine you will need to forward port 8081. diff --git a/examples/replay/README.md b/examples/replay/README.md index 38944f4c86..886f0a9ca2 100644 --- a/examples/replay/README.md +++ b/examples/replay/README.md @@ -3,7 +3,7 @@ This module shows how you can write your own experiments that will allow you to ## Wrapping your Social Agent You need to wrap your social agent using the `ReplayAgent` wrapper to save agent observations and actions at each step. -Checkout `examples/replay/replay_klws_agent.py` on an example on how you can write your own experiment to replay your agent: +Look at `examples/replay/replay_klws_agent.py` as an example on how you can write your own experiment to replay your agent: ```python from smarts.zoo.registry import make as zoo_make from zoo import policies diff --git a/scenarios/INTERACTION/README.md b/scenarios/INTERACTION/README.md index e063953cff..f5e5aa632f 100644 --- a/scenarios/INTERACTION/README.md +++ b/scenarios/INTERACTION/README.md @@ -26,5 +26,5 @@ their level of exactness may not be enough for some model-training situations, so you may want or need to refine them with SUMO's [netedit tool](https://sumo.dlr.de/docs/Netedit/index.html). An example of how traffic history might be replayed in SMARTS can be found in the -[examples/smarts/traffic_histories_to_observations.py](../../examples/smarts/traffic_histories_to_observations.py) +[smarts/dataset/traffic_histories_to_observations.py](../../smarts/dataset/traffic_histories_to_observations.py) script. diff --git a/scenarios/NGSIM/README.md b/scenarios/NGSIM/README.md index f72713a568..e9b147509c 100644 --- a/scenarios/NGSIM/README.md +++ b/scenarios/NGSIM/README.md @@ -28,5 +28,5 @@ their level of exactness may not be enough for some model-training situations, so you may want or need to refine them with SUMO's [netedit tool](https://sumo.dlr.de/docs/Netedit/index.html). An example of how traffic history might be replayed in SMARTS can be found in the -[examples/smarts/traffic_histories_to_observations.py](../../examples/smarts/traffic_histories_to_observations.py) +[smarts/dataset/traffic_histories_to_observations.py](../../smarts/dataset/traffic_histories_to_observations.py) script.