Quick Start
===========

Using METS-R in Docker (Recommended)
-------------------------------------

The recommended way to run METS-R is through the Docker-based HPC module,
which packages the simulator and all its dependencies into a self-contained
container and requires no Java or Eclipse setup.

**Prerequisites:** Install `Docker <https://www.docker.com/products/docker-desktop/>`__
and Python ≥ 3.10.

1. Clone the METS-R HPC repository:

   ::

      git clone https://github.com/umnilab/METS-R_HPC.git
      cd METS-R_HPC

2. Create a Python environment and install all requirements:

   ::

      pip install -r requirements.txt

3. Build the PostgreSQL Docker image (used for logging simulation outputs):

   ::

      cd docker
      docker build -t postgres postgres
      cd ..

4. Open ``interactive_example.ipynb`` in VS Code or any Jupyter-compatible IDE
   and run each cell in order. The notebook walks through starting the Docker
   containers, connecting to the simulator, and exercising the step, query,
   and control APIs end-to-end.

.. note::

   On Windows, ensure that the *Host Networking* feature is enabled in Docker
   Desktop settings (Settings → Resources → Network → Enable host networking).

Several APIs are developed to query and control the simulation. See :ref:`Interactive APIs` for more details.

Standalone mode
---------------

1.  Download and install Eclipse IDE with *Repast Simphony* 2.7 from
    `here <https://github.com/Repast/repast.simphony/releases>`__.

2.  Clone the *METS-R* repository using git to a target folder.

    ::

       git clone https://github.com/umnilab/METS-R_SIM.git

3.  Open Eclipse and go to File -> *Open Projects from File System…*

4.  In the *Import Projects from File System or Archive* window click on
    *Directory* and open the *METS_R* directory you cloned in Step 2.

5.  Check *METS_R* and click *Finish*. This should open the METS-R SIM
    project in Eclipse as shown in the following figure.

    .. figure:: res/load_sim_in_eclipse.png
       :alt: Load the METS_R SIM project in Eclipse

       Load the METS_R SIM project in Eclipse

6.  Go to the *laucher* folder in the project explorer, then right click
    ``METS_R Model.launch`` and select Run as -> *METS-R Model* to start
    the simulation.

7.  You should see the below *Repast Symphony* simulation window (After
    specifying the first time, you can also use the *Run* button in the
    Eclipse toolbar).

8.  Click on the *Start Run* button in the pop-up window to begin the
    simulation.

9.  The simulation outputs can be found in the agg_output folder, and
    the vehicle trajectories is in the trajectory_output folder.

10. You can check the configuration file
    (``METS_R/data/Data.properties``) for options available in the
    simulation.

Synchronized mode
-----------------

You can run the synchronized mode in the following ways:

Interactive mode
~~~~~~~~~~~~~~~~

1. Complete the Docker setup steps 1–3 in the *Using METS-R in Docker*
   section above.
2. Open ``interactive_example.ipynb`` in VS Code or another Jupyter-compatible IDE.
3. Run each cell one by one.

Co-simulation mode with CARLA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Complete the Docker setup steps 1–3 in the *Using METS-R in Docker*
   section above.
2. Update ``carla_dir`` in ``configs/run_cosim_CARLAT5.json`` to point
   to your local CARLA installation. The ``carla`` Python package version
   must match your CARLA build (tested with CARLA 0.9.15).
3. Run ``python cosim_example.py -r configs/run_cosim_CARLAT5.json``

More demand scenarios
---------------------

More demand scenarios for the NYC network can be downloaded from
`here <https://drive.google.com/drive/folders/1r6bsCjGYrg4ckLQeud4yMWfQ8qy85zJS?usp=drive_link>`__.
You just need to copy this to ``data\`` under the METS-R SIM folder.