File size: 7,479 Bytes
3d2dbcf | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 | .. _start:
Quick Start
===========
Installation
------------
If you have not installed CityFlow yet, :ref:`install` is a simple guide for installation.
Create Engine
-------------
.. code-block:: python
import cityflow
eng = cityflow.Engine(config_path, thread_num=1)
- ``config_path``: path for config file.
- ``thread_num``: number of threads.
Arguments In Config File
^^^^^^^^^^^^^^^^^^^^^^^^
- ``interval``: time of each simulation step (in seconds). An ``interval`` of 0.5 means for each simulation step, the system will move 0.5 seconds forward. For example, if a car is at location 0 with speed 10m/s, after one simulation step, it will move to location 10*0.5=5.
- ``seed``: random seed.
- ``dir``: root directory, all file path will be relative to this directory.
- ``roadnetFile``: path for roadnet file.
- ``flowFile``: path for flow file.
- ``rlTrafficLight``: whether to enable traffic light control through python API. If set to ``false``, default traffic light plan defined in ``roadnetFile`` will be used.
- ``saveReplay``: whether to save simulation for replay. If set to ``true``, ``roadnetLogFile`` and ``replayLogFile`` are required.
- ``roadnetLogFile``: path for roadnet replay file. This is a special roadnet file for replay, not the same as ``roadnetFile``.
- ``replayLogFile``: path for replay. This file contains vehicle positions and traffic light situation of each simulation step.
- ``laneChange``: whether to enable lane changing. The default value is 'false'.
For format of ``roadnetFile`` and ``flowFile``, please see :ref:`roadnet`, :ref:`flow`
.. note::
Runnable sample roadnet and flow files can be found in ``examples`` folder.
You can generate grid roadnet and flow files using `tools/generate_grid_scenario.py`
For example, you can generate a 2x3 roadnet with predefined traffic light plan and a corresponding flow file with
.. code-block:: shell
python generate_grid_scenario.py 2 3 --roadnetFile roadnet.json --flowFile flow.json --dir . --tlPlan
Sample Config File
^^^^^^^^^^^^^^^^^^^
.. note::
Runnable sample config files can be found in ``examples`` folder.
.. code-block:: json
{
"interval": 1.0,
"seed": 0,
"dir": "data/",
"roadnetFile": "roadnet/testcase_roadnet_3x3.json",
"flowFile": "flow/testcase_flow_3x3.json",
"rlTrafficLight": false,
"saveReplay": true,
"roadnetLogFile": "frontend/web/testcase_roadnet_3x3.json",
"replayLogFile": "frontend/web/testcase_replay_3x3.txt"
}
Simulation
----------
To simulate one step, simply call ``eng.next_step()``
.. code-block:: python
eng.next_step()
Data Access API
---------------
``get_vehicle_count()``:
- Get number of total running vehicles.
- Return an ``int``
``get_vehicles(include_waiting=False)``:
- Get all vehicle ids
- Include vehicles in lane's waiting buffer if ``include_waiting=True``
- Return an ``list`` of vehicle ids
``get_lane_vehicle_count()``:
- Get number of running vehicles on each lane.
- Return a ``dict`` with lane id as key and corresponding number as value.
``get_lane_waiting_vehicle_count()``:
- Get number of waiting vehicles on each lane. Currently, vehicles with speed less than 0.1m/s is considered as waiting.
- Return a ``dict`` with lane id as key and corresponding number as value.
``get_lane_vehicles()``:
- Get vehicle ids on each lane.
- Return a ``dict`` with lane id as key and list of vehicle id as value.
``get_vehicle_info(vehicle_id)``:
- Return a ``dict`` which contains information of the given vehicle.
- The items include:
+ ``running``: whether the vehicle is running.
+ If the vehicle is running:
* ``speed``: The speed of the vehicle.
* ``distance``: The distance the vehicle has travelled on the current lane or lanelink.
* ``drivable``: The id of the current drivable(lane or lanelink)
* ``road``: The id of the current road if the vehicle is running on a lane.
* ``intersection``: The next intersection if the vehicle is running on a lane.
* ``route``: A string contains ids of following roads in the vehicle's route which are separated by ``' '``.
- Note that all items are stored as ``str``.
``get_vehicle_speed()``:
- Get speed of each vehicle
- Return a ``dict`` with vehicle id as key and corresponding speed as value.
``get_vehicle_distance()``:
- Get distance travelled on current lane of each vehicle.
- Return a ``dict`` with vehicle id as key and corresponding distance as value.
``get_leader(vehicle_id)``
- Return the id of the vehicle in front of ``vehicle_id``.
- Return an empty string ``""`` when ``vehicle_id`` does not have a leader
``get_current_time()``:
- Get simulation time (in seconds)
- Return a ``double``
``get_average_travel_time()``:
- Get average travel time (in seconds)
- Return a ``double``
Control API
-----------
``set_tl_phase(intersection_id, phase_id)``:
- Set the phase of traffic light of ``intersection_id`` to ``phase_id``. Only works when ``rlTrafficLight`` is set to ``true``.
- The ``intersection_id`` should be defined in ``roadnetFile``
- ``phase_id`` is the index of phase in array ``"lightphases"``, defined in ``roadnetFile``.
``set_vehicle_speed(vehicle_id, speed)``:
- Set the speed of ``vehicle_id`` to ``speed``.
- The vehicles have to obey fundamental rules to avoid collisions so the real speed might be different from ``speed``.
``reset(seed=False)``:
- Reset the simulation (clear all vehicles and set simulation time back to zero)
- Reset random seed if ``seed`` is set to ``True``
- This does not clear old replays, instead, it appends new replays to ``replayLogFile``.
``snapshot()``:
- Take a snapshot of current simulation state
- This will generate an ``Archive`` object which can be loaded later
- You can save an ``Archive`` object to a file using its ``dump`` method.
``load(archive)``:
- Load an ``Archive`` object and restore simulation state
``load_from_file(path)``
- Load a snapshot file created by ``dump`` method and restore simulation state.
- The whole process of saving and loading file is like:
.. code-block:: python
archive = eng.snapshot() # create an archive object
archive.dump("save.json") # if you want to save the snapshot to a file
# do something
eng.load(archive)
# load 'archive' and the simulation will start from the status when 'archive'is created
# or if you want to load from 'save.json'
eng.load_from_file("save.json")
``set_random_seed(seed)``:
- Set seed of random generator to ``seed``
.. _set-replay-file:
``set_vehicle_route(vehicle_id, route)``:
- To change the route of a vehicle during its travelling.
- `route` is a list of road ids (doesn't include the current road)
- Return true if the route is available and can be connected.
Other API
---------
``set_replay_file(replay_file)``:
- ``replay_file`` should be a path related to ``dir`` in config file
- Set ``replayLogFile`` to ``replay_file``, newly generated replays will be output into ``replay_file``
- This is useful when you want to look at a specific episode for debugging purposes
- This API works only when ``saveReplay`` is ``true`` in config json
``set_save_replay(open)``:
- Open or close replay saving
- Set ``open`` to False to stop replay saving
- Set ``open`` to True to start replay saving
- This API works only when ``saveReplay`` is ``true`` in config json |