Request for more detailed step-by-step guide

[ThisIsIsaac]

I have read the Cityflow doc multiple times but it comes very short to providing enough guidance to get me started.

Here are just a few questions from a long list of questions that weren't answered by the guide:

1. What is "roadLinkIndices"?

2. What does it mean if "availableRoadLinks":[] for a lightphases?

3. Why must virtual intersections have "lightphases" when we don't care about the lights in the edges?

4. How do I change the number of vehicles (i.e. the rate of spawning new vehicles)?

5. How do you turn on yellow lights? And change the duration of yellow lights?

6. Where is the origin (the point where x and y are both 0)?

7. how is roadLinks different from laneLinks?

I see that CityFlow could be leaps better than SUMO, but there doesn't seem to be enough guide to getting started. And I am willing to read any extra material you can provide.

Since there is no guide, I am digging through roadnet.json and flow.json that others have made to deduce what these fields do, which is a painstaking process.

So a more detailed step-by-step guide that doesn't omit any necessary information would be great.

[Hzfengsy]

I apologize for our incomplete documents. I agree with you that we should provide some tutorials for users. We plan to do it recently, and I will keep this issue open until we provide additional tutorials.

For now, I can answer some of your questions. But I don't fully understand every detail in roadnet file, so I will figure out if I don't know or confident about the answer.

1. To be honest, I don't know about that. I guess it means the traffic light can control these roadLink. But I think it may be redundant.
2. In every lightphases, only the roadLinks in availableRoadLinks are passable. It figures out which lights are green in this phase.
3. I think it is unnecessary. Maybe it can be deleted (not sure). If not we can improve it later.
4. Every flow has an attribute called interval, which means every few seconds there is one vehicle appearing.
5. Since the yellow-light phase has no difference with an all-red phase, you can define 0 phase as an all-red phase. (you can also determine whether cars can turn right)
6. All positions are relative. So, the origin point has no meaning except it is the initial position in visual UI.
7. A roadLink contains several laneLinks(i.e. the source road and the destination road have both two lanes, there are 2 * 2 = 4 laneLinks in this roadLink) laneLinks are used for running vehicles while the roadLink will be directly controlled by traffic light.

[ThisIsIsaac]

@Hzfengsy

Thanks for your helpful answer :)

A follow up on your second answer:

2. In every lightphases, only the roadLinks in availableRoadLinks are passable. It figures out which lights are green in this phase.

So in examples/roadnet.json, there are lines like this:

"lightphases":[{"time":30,"availableRoadLinks":[]},

Where a lightphase does not have any link. Does this mean it is essentially a red light on all lanes?

---

A few extra questions:

1. how do you reset the simulation to scratch? Do you simply call eng = cityflow.Engine(config_path, thread_num=1) again?

2. How do you shut down the simulation? Or is there no need to do that?

[zhc134]

@ThisIsIsaac

You're right. And for virtual intersections, trafficLight is not required and has no effect.

[zhc134]

1. how do you reset the simulation to scratch? Do you simply call eng = cityflow.Engine(config_path, thread_num=1) again?

You can use eng.reset() (Notice this does not reset random state).

2. How do you shut down the simulation? Or is there no need to do that?

You can use del eng to trigger garbage collection.

[ThisIsIsaac]

@zhc134
what are some paramters to eng.reset()? I think it could be helpful if it is in the docs. I will make a push you are busy and can direct me to where I can see the explanations.

[ThisIsIsaac]

@Hzfengsy

5. Since the yellow-light phase has no difference with an all-red phase, you can define 0 phase as an all-red phase. (you can also determine whether cars can turn right)

I am not convinced that yellow light phases are not necessary. If a car was going at 50km/h and the light suddenly turns red without any buffer time -- i.e. the yellow light -- for the car to decelerate, then the car would either have to:

1. hit the breaks to stop immediately,

2. run the light and perform an "illegal" action.

So without yellow lights, how does a car know when to start decelerating properly?

[zhc134]

what are some paramters to eng.reset()? I think it could be helpful if it is in the docs. I will make a push you are busy and can direct me to where I can see the explanations.

There is no parameter in reset(). I've added reset() in docs in c99cee1. Thanks a lot!

So without yellow lights, how does a car know when to start decelerating properly?

In our system design, if a vehicle cannot perform a full stop before the end of the road, then it will just go through the intersection even if the light is red. On the other hand, if it can stop, it will. This is similar to the intention of yellow lights. So we think all red phase is sufficient. But I admit there is some difference, i.e. driver will go through the intersection even if he can stop given a yellow light. We consider adding a yellow light in future version.

[ThisIsIsaac]

@zhc134

Thanks for the detailed explanation.

In our system design, if a vehicle cannot perform a full stop before the end of the road, then it will just go through the intersection even if the light is red. On the other hand, if it can stop, it will.

What is the rate of deceleration? Can we control this? I assume the rate of deceleration is set to be close to the rate of deceleration of real drivers when they see a yellow light that they cannot make through.

[zhc134]

@ThisIsIsaac
each vehicle has a parameter maxNegAcc which is specified in flowFile.
please see https://cityflow.readthedocs.io/en/latest/flow.html for more detail

[ThisIsIsaac]

So if the distance from stopping line is too short s.t. the car won't come to stop while accelerating at maxNegAcc, then it just runs the light?

[zhc134]

Yes

[ThisIsIsaac]

Is there a way to set where to save replay files in Python, without editing config.json? When debugging an RL agent, I may want to save replays of multiple episodes. However, since the name of the replay file is hard-coded in config.json, older replay files get over-written whenever a new episode starts.

[zhc134]

Currently, we do not support changing replayFilePath on the fly. Please open a new issue, clarify your needs and we will add it to our develop plan.

BTW, eng.reset() won't clear old replay information, so you can visualize multiple episodes, they will appear in replay.txt in order.

[ThisIsIsaac]

BTW, eng.reset() won't clear old replay information, so you can visualize multiple episodes, they will appear in replay.txt in order

oh so if there already exists replay.txt, then instead of overwriting the old replay, it appends newer replay to the end?

[zhc134]

If you call eng.reset() then yes it appends newer replays to the end. However, if you create a new Engine object with same replayFilePath, it will clear the file first.

[ThisIsIsaac]

Thanks. I feel like this could be very important, but not obvious from the doc. Maybe we can add this to the doc under the replay section?

[zhc134]

Sure! Please check 7f2cc2e

[ThisIsIsaac]

Is "interval": defined in flow.json specific to each vehicle? So interval:5 means the specific vehicle is spawned every 5 seconds. Would that be a correct interpretation?

[zhc134]

Exactly

[eewangzx]

I have checked your doc, but I don't find a function to get the current signal phase?
How to obtain the current signal phase for a given intersection?