Assignment 2: Simulating a Traffic Light

Duration: 2 weeks

Total Points: 100

Prerequisites: Classes and Objects, Functions, Lists/Dictionaries, Timing, Asymptotic Analysis, Python Standard Libraries

Changelog

● Tue, Jul 22, 2025

○ Updated the specification of unit tests in the Goals section

○ To simplify the specification and make it more consistent with the class discussion, we have increased the maximum through lanes to 4.

● Sat, Jul 19, 2025

○ You do not need to output every simulated second; instead, you can output when the scenario state changes, as shown in the output sample. The document has been updated accordingly.

Overview

In this assignment, you will simulate a four-way traffic intersection. Each direction (North, South, East, West) may have:

● One or more through lanes.

● Zero or one dedicated left-turn lanes.

● A traffic signal cycle consisting of green, yellow, and red lights.

● A delay interval called "all-red clearance time", when all directions are red before switching to a different direction.

You will write a program that models the lanes, traffic light timing, and light transitions over time, allowing simulation of traffic signal cycles in real-time or fast-forwarded time.

Use of gen AI: You may use generative AI (gen AI) to help you (e.g., ChatGPT or Copilot), but you must include (1) all prompts and outputs provided by the gen AI and (2) any modifications you made to the resulting outputs provided and why you modified the outputs as such. This policy allows us to understand (1) how you are using gen AI and (2) help you use it more effectively, so as to demonstrate to others (e.g., future or possible employers) that you are adding value beyond the gen AI itself (e.g., you are worth hiring as a junior developer rather than having a senior developer just use the gen AI and not hire a junior developer). To encourage the submission of such gen AI-oriented materials, submitting this information in a file called genai_io.pdf will earn you up to 5 points of extra credit. We will grade that file on the quality of your prompts, the sensibility of the modifications to outputs, and the reasoning behind those modifications. Note that code generated using the current state-of-the-art generative AI has a strong tendency to be overly verbose and hallucinate, so we will be checking for such properties and others when evaluating quality and sensibility. Avoid just prompting and re-prompting generative AI without understanding the output. We will discuss strategies to assist you with this as we progress through the lectures.

We will also be using tools to detect your use of generative AI, so if we have strong suspicions that you have used generative AI without following the policy specified above, you may face a severe penalty, including failing the assignment or having your incident reported to the UCI Office of Academic Integrity & Student Conduct (OAISC), which may lead to suspension or dismissal/expulsion.

Goals

● Design object-oriented models for traffic signals, lanes, and the intersection.

● Implement a time-based simulation of light phases.

○ Time need not be in real-time, i.e., you do not actually have to run a 60-second simulation for 60 seconds, but instead, create a loop that iterates from integer 1 to integer 60, i.e., each iteration is a time step, and then, based on varying conditions and input events, different output events occur at each iteration.

● Provide console-based output of the current traffic signal status.

● Visualize or log the state at each time step.

○ By logging, we mean logging the output to a file, which can also ease debugging.

● Analyze the runtime complexity of your simulation step function, i.e., the function that conducts your main simulation.

● Design and submit unit tests to demonstrate your traffic light simulation works correctly.

○ For each class, design and implement at least one unit test that assesses the correctness of at least one function that is not a constructor.

Specification

Intersection Geometry and Traffic Rules

1. There are 4 directions: North, South, East, West.

2. Each direction may have the following lanes:

○ 1–4 through lanes

○ 0–1 left-turn lane

3. Traffic may flow in only one direction pair at a time:

○ North-South (NS) and South-North

○ East-West (EW) and West-East

4. Left-turns occur separately if protected (i.e., with a dedicated green-red-yellow arrow).

Traffic Light Configuration

Each direction's signal follows a cycle:

● Green: 20–45 seconds

● Yellow: 3–5 seconds

● Red: Variable depending on what phase the intersection is in

● All-red interval (clearance time between green in one direction and green in the next): 4 seconds

○ For many traffic light-controlled intersections, there are a few seconds during which all lights in all directions are red to ensure safety and minimize the possibility of collisions at the intersection when lights change and the direction of oncoming traffic changes.

Each light phase must be configurable per direction or per lane. In other words, the length of time each light may last can vary (e.g., the green light can be configured to any second value between 20-45 seconds).

Simulation Requirements

You must:

1. Define a Lane class with:

○ direction (N, S, E, W)

○ type (through or left-turn)

2. Define a SignalPhase class with:

○ green_time

○ yellow_time

○ red_time (auto-determined)

3. Define a TrafficLight class that:

○ Keeps current phase: GREEN, YELLOW, RED

○ Counts the time remaining in the current phase

○ Transitions to the next phase when time runs out

4. Define an IntersectionController class that:

○ Manages which direction is active

○ Enforces all-red clearance time

○ Runs the full simulation

Deliverables and Recommended Schedule

Week 1: Modeling and Setup (50 points)

Tasks:

● Design and implement Lane, SignalPhase, TrafficLight, and IntersectionController classes.

● Set up a sample intersection with:

○ North/South: 2 through lanes, 1 left-turn lane

○ East/West: 1 through lane, 0 left-turn lanes

● Initialize traffic lights with proper cycle timings.

● Implement phase transitions and print updates every simulated second (as previously described, every simulated second can simply be one iteration through a loop) or when the state of the scenario changes (e.g., one of the traffic lights changes as shown in the example below).

Output Sample:

None

[00:00] NS through lanes: GREEN (20s), Left-turn: RED

[00:20] NS through lanes: YELLOW (4s), Left-turn: RED

[00:24] All lanes: RED (clearance time)

[00:28] EW through lanes: GREEN (30s)

...

Week 2: Simulation, Reporting, and Analysis (50 points)

Tasks:

● Print or log the full state of the intersection at each time step.

● Analyze and comment on the time complexity of your update functions.

○ Analyze each sub-function first, determining the Big O complexity of each sub-function, and then use those sub-complexities to determine the overall complexity of the main function of your IntersectionController

Tips

● Consider using Enum for signal states or create a class to represent signal states

● Document your classes with __str__ or __repr__ to make debugging easier.

Example Usage

Python

intersection = IntersectionController()

intersection.simulate(120) # Run the simulation for 2 minutes,

i.e., 120 seconds

Submission

● traffic.py (your implementation) (80 points)

○ Submit unit tests demonstrating your assignment works correctly. We’ll discuss this aspect of the assignment more in class.

● README.md (explain your classes, how to run the simulation) (5 points)

● analysis.pdf (describe runtime behavior, design choices) (15 points)

● gen-ai.pdf (gen-ai extra credit as described above) (5 points of extra credit)