8.9  Real-time simulation of a pendulum

What is PyQt6 and pyqtgraph?

Before we dive into the code, let’s understand the tools we’re using:

PyQt6 is a Python binding for the Qt framework. Qt is a powerful toolkit for creating graphical user interfaces (GUIs). With PyQt6, you can create windows, buttons, sliders, and other interactive elements that users can click and interact with.

pyqtgraph is a library built on top of PyQt that specializes in creating fast, interactive plots and visualizations. It’s perfect for real-time data visualization, like our pendulum simulation where we need to update the display many times per second.

Think of it this way:

• PyQt6 provides the window, buttons, and sliders
• pyqtgraph provides the plotting capabilities to draw the pendulum and energy graphs
• Together, they create an interactive simulation

Step 1: Creating the Basic Pendulum Visualization

Every PyQt application needs these fundamental components:

1. An application object - This manages the overall program
2. A window - The main container for your interface
3. Widgets - The visual elements inside the window

Let’s see how this works:

# Create the application object
app = pg.mkQApp()

# Create the main window
win = QtWidgets.QMainWindow()
win.setWindowTitle('Pendulum Simulation')

# Create a central widget to hold everything
central_widget = QtWidgets.QWidget()
win.setCentralWidget(central_widget)

# Create a layout to organize widgets vertically
layout = QtWidgets.QVBoxLayout()
central_widget.setLayout(layout)

Understanding this code:

• pg.mkQApp() - Creates the application object. Think of this as starting your program.
• QtWidgets.QMainWindow() - Creates the main window that will appear on your screen.
• setWindowTitle() - Sets the text that appears in the window’s title bar.
• QWidget() - A generic container widget that will hold our other elements.
• setCentralWidget() - Every QMainWindow needs a central widget. This is where your content goes.
• QVBoxLayout() - A layout manager that arranges widgets vertically (one on top of another). The “V” stands for “Vertical”.

Now let’s create the plot where the pendulum will be displayed:

# Create a plot widget
plot_widget = pg.PlotWidget()
layout.addWidget(plot_widget)

# Configure the plot appearance
plot_widget.setBackground('w')  # 'w' = white background
plot_item = plot_widget.getPlotItem()
plot_item.setTitle("Pendulum Simulation")
plot_item.setLabel('bottom', 'X Position (m)')
plot_item.setLabel('left', 'Y Position (m)')
plot_item.setXRange(-2.2, 2.2)  # Set the x-axis range
plot_item.setYRange(-2.2, 2.2)  # Set the y-axis range
plot_item.setAspectLocked(True)  # Keep x and y scales equal (circle stays circular)
plot_item.showGrid(x=True, y=True)  # Show grid lines

Understanding PlotWidget:

• PlotWidget() - Creates a widget specifically for plotting data. This is from pyqtgraph.
• layout.addWidget() - Adds the plot widget to our vertical layout.
• getPlotItem() - Gets the actual plot object that we can configure.
• setAspectLocked(True) - Important! This ensures that 1 unit on the x-axis equals 1 unit on the y-axis. Without this, the pendulum’s circular motion would look stretched.

Now let’s draw the pendulum itself. A pendulum has two visual parts:

1. A line from the pivot point (0, 0) to the bob
2. A circle representing the bob (the mass at the end)

# Create the pendulum line
pendulum_line = plot_item.plot(pen=pg.mkPen('k', width=5))

# Create the pendulum bob (the circle at the end)
pendulum_bob = pg.ScatterPlotItem(
    size=20,                    # Size of the circle
    pen=pg.mkPen(None),        # No outline
    brush=pg.mkBrush(255, 0, 0) # Red fill (RGB: Red=255, Green=0, Blue=0)
)
plot_item.addItem(pendulum_bob)

Understanding the pendulum graphics:

• plot_item.plot() - Creates a line plot. The pen parameter controls how the line looks.
• pg.mkPen('k', width=5) - Makes a black pen (‘k’ = black) with width 5 pixels.
• ScatterPlotItem() - Creates scatter points (dots/circles) that can be positioned anywhere.
• pen=pg.mkPen(None) - No outline around the circle.
• brush=pg.mkBrush(255, 0, 0) - Fills the circle with red color using RGB values.
• addItem() - Adds the scatter plot item to our plot.

Step 2: Adding the Physics Simulation

To animate the pendulum, we need to:

1. Store the pendulum’s state (angle, angular velocity)
2. Update the physics each frame
3. Redraw the pendulum at its new position

First, let’s set up the initial state:

# Physics constants (you'll learn these in your mechanics course!)
g = 9.82  # Gravity acceleration (m/s^2)
m = 1.0   # Mass of pendulum bob (kg)

# Initial state
theta = 45 * np.pi / 180  # Starting angle: 45 degrees converted to radians
omega = 0.0                # Angular velocity: starts from rest
L = 1.0                    # Length of pendulum (meters)
c = 0.5                    # Damping coefficient (resistance)
t = 0.0                    # Current time (seconds)
dt = 1/60                  # Time step: 60 frames per second

Important notes about angles:

• In Python’s numpy library, trigonometric functions use radians, not degrees
• To convert: radians = degrees * π / 180
• That’s why we multiply 45 by np.pi / 180

Now let’s create a function to update the pendulum’s position on screen:

def update_visuals():
    """Update the pendulum graphics"""
    # Calculate the bob's position from the angle
    # Note: theta is measured from the positive x-axis, clockwise
    P = L * np.array([np.cos(theta), -np.sin(theta)])
    
    # Update the line: from origin (0,0) to bob position (P[0], P[1])
    pendulum_line.setData([0, P[0]], [0, P[1]])
    
    # Update the bob position
    pendulum_bob.setData([P[0]], [P[1]])

Understanding setData():

• setData([0, P[0]], [0, P[1]]) - This takes two lists: x-coordinates and y-coordinates
• The line goes from point (0, 0) to point (P[0], P[1])
• For the bob, we pass single-element lists because it’s just one point

Now the physics update function:

The physics of a simple pendulum with friction is a topic for the mechanics course. Just know that we are using a Euler-Cromer method to update the angle and angular velocity based on the equations of motion. Which basically is a second order differential equation with respect to time. See Time Integration Methods for more details.

\[ \frac{d^2\theta}{dt^2} = \frac{g}{L} \cos(\theta) - \frac{c}{mL^2} \frac{d\theta}{dt} \]

where \(\alpha = \frac{d^2\theta}{dt^2}\) and \(\omega = \frac{d\theta}{dt}\), \(g\) is the gravitational constant, \(m\) is the mass, \(c\) is the damping coefficient and \(L\) is the pendulum length.

def pendulum_step():
    """Update the physics simulation by one time step"""
    global theta, omega, t  # We need to modify these global variables
    
    # Update time
    t += dt
    
    # Update angular velocity (this equation comes from physics)
    # Don't worry about the details - you'll learn this in mechanics!
    omega += (g / L) * np.cos(theta) * dt + c/(m*L**2) * (-omega) * dt
    
    # Update angle
    theta += omega * dt
    
    # Redraw the pendulum at its new position
    update_visuals()

The global keyword:

• Functions normally can’t modify variables defined outside of them
• The global keyword tells Python: “I want to modify the outer variable, not create a new local one”

Now we need to make this function run repeatedly to create animation. In PyQt, we use a timer:

# Create a timer
timer = QtCore.QTimer()

# Connect the timer to our physics function
# Every time the timer "times out", it will call pendulum_step()
timer.timeout.connect(pendulum_step)

# Start the timer: call pendulum_step every dt seconds
# Note: timer interval is in milliseconds, so we multiply by 1000
timer.start(int(dt * 1000))  # 1/60 second = ~16.7 milliseconds

Understanding Signals and Slots:

PyQt uses a concept called signals and slots to handle events. This is Qt-specific terminology, but the concept is common in programming:

• A signal is an event (like “timer timed out” or “button clicked”)
• A slot is a function that responds to that signal (also called an “event handler” or “callback function”)
• connect() links a signal to a slot

In other frameworks, you might see this same pattern called:

• Event and event handler (JavaScript, C#)
• Callback function (JavaScript, Node.js, Python)
• Observer / Listener (Java, Android)

So timer.timeout.connect(pendulum_step) means: “When the timer times out, call the pendulum_step function”

This is the same idea as addEventListener in JavaScript or callback functions in other Python libraries - just with Qt’s terminology!

Finally, to show the window and run the application:

# Show the window
win.show()

# Run the application (this starts the event loop)
app.exec()

The event loop:

• app.exec() starts the event loop - this keeps your program running and responsive
• Without it, the window would appear and immediately close
• The event loop continuously checks for events (mouse clicks, key presses, timer timeouts) and responds to them

At this point, you have a working animated pendulum! Now let’s add user interaction.

Step 3: Adding Keyboard Controls

Let’s add keyboard controls to make the simulation interactive:

• SPACE - Pause/resume the simulation
• ENTER - Reset to starting position

First, we need functions for these actions:

def reset_simulation():
    """Reset the pendulum to its starting position"""
    global theta, omega, t
    
    theta = 45 * np.pi / 180  # Back to 45 degrees
    omega = 0.0                # At rest
    t = 0.0                    # Time resets
    
    update_visuals()
    print("Simulation reset!")


def pause_simulation():
    """Pause or resume the simulation"""
    if timer.isActive():
        timer.stop()
        print("Simulation paused.")
    else:
        timer.start(int(dt * 1000))
        print("Simulation resumed.")

Understanding timer.isActive():

• timer.isActive() returns True if the timer is running, False if it’s stopped
• This lets us toggle between pause and resume with a single function

Now we need to connect keyboard presses to these functions:

def handle_key_press(event):
    """Handle keyboard input"""
    if event.key() == QtCore.Qt.Key.Key_Return:
        reset_simulation()
    elif event.key() == QtCore.Qt.Key.Key_Space:
        pause_simulation()

# Connect the keyboard handler to the window
win.keyPressEvent = handle_key_press

Understanding event handlers:

• event.key() tells us which key was pressed
• QtCore.Qt.Key.Key_Return is the constant for the Enter key
• QtCore.Qt.Key.Key_Space is the constant for the Space bar
• We assign our function to win.keyPressEvent to override the window’s default keyboard behavior

Now you can pause/resume with SPACE and reset with ENTER!

Step 4: Adding Mouse Interaction

Wouldn’t it be cool to drag the pendulum to any position by clicking? Let’s add that!

The challenge: when you click on the plot, you get pixel coordinates, but we need to:

1. Convert pixels to plot coordinates
2. Calculate the angle from the click position

def handle_mouse_click(event):
    """Handle mouse clicks to set pendulum position"""
    global theta, omega, t
    
    # Only respond to left clicks
    if event.button() == QtCore.Qt.MouseButton.LeftButton:
        # Convert pixel coordinates to plot coordinates
        mouse_point = plot_item.vb.mapSceneToView(event.scenePos())
        x_mouse = mouse_point.x()
        y_mouse = mouse_point.y()
        
        # Avoid division by zero
        if x_mouse == 0 and y_mouse == 0:
            return
        
        # Calculate angle from mouse position
        # arctan2(y, x) gives the angle of a point (x, y)
        theta = np.arctan2(-y_mouse, x_mouse)
        omega = 0.0  # Start from rest
        t = 0.0      # Reset time
        
        update_visuals()
        event.accept()  # Tell Qt we handled this event
    else:
        event.ignore()  # Let other handlers deal with it

# Connect the mouse handler to the plot
plot_item.scene().sigMouseClicked.connect(handle_mouse_click)

Understanding coordinate conversion:

• event.scenePos() gives the position in “scene coordinates” (pixels)
• plot_item.vb.mapSceneToView() converts to “view coordinates” (our plot’s x,y values)
• np.arctan2(-y_mouse, x_mouse) calculates the angle
  • We use -y_mouse because our y-axis points down, but angles are measured from the horizontal

Understanding signal connection:

• plot_item.scene().sigMouseClicked is a signal emitted when you click on the plot
• We connect it to our handler function using .connect()

Now you can click anywhere to position the pendulum!

Step 5: Adding Sliders for Parameters

Sliders let users interactively change values. We’ll create sliders to adjust:

• Length (L) - How long the pendulum is
• Damping (c) - How much air resistance slows it down

A slider needs:

1. The slider widget itself
2. A label showing the current value
3. A function that updates when the slider moves

# Create a container for the length slider
length_container = QtWidgets.QWidget()
length_layout = QtWidgets.QHBoxLayout(length_container)  # Horizontal layout

# Add a label
length_label_prefix = QtWidgets.QLabel("Length (L):")
length_layout.addWidget(length_label_prefix)

# Create the slider
length_slider = QtWidgets.QSlider(QtCore.Qt.Orientation.Horizontal)
length_slider.setRange(10, 200)        # Range: 0.1m to 2.0m (stored as 10-200)
length_slider.setValue(int(L * 100))   # Initial value: 1.0m = 100
length_slider.setTickPosition(QtWidgets.QSlider.TickPosition.TicksBelow)
length_slider.setTickInterval(25)
length_layout.addWidget(length_slider)

# Add a label to show the current value
length_value_label = QtWidgets.QLabel(f"{L:.1f} m")
length_layout.addWidget(length_value_label)

# Add the container to the main layout
layout.addWidget(length_container)

Understanding sliders:

• QSlider only works with integers, not floats
• So we store length × 100 (1.0 m becomes 100, 1.5 m becomes 150, etc.)
• setRange(10, 200) means slider values go from 10 to 200 (representing 0.1 m to 2.0 m)
• QHBoxLayout arranges widgets horizontally in a row
• f"{L:.1f} m" is an f-string that formats L with 1 decimal place

Now we need a function that updates L when the slider moves:

def update_length(slider_value):
    """Update pendulum length from slider"""
    global L
    L = slider_value / 100.0  # Convert slider value to meters
    length_value_label.setText(f"{L:.1f} m")  # Update the label
    update_visuals()  # Redraw the pendulum

# Connect the slider to the update function
length_slider.valueChanged.connect(update_length)

The valueChanged signal:

• Every time you move the slider, it emits a valueChanged signal
• This signal includes the new value
• Our function receives that value and updates L

The damping slider works the same way:

# Create damping slider (same pattern as length slider)
damping_container = QtWidgets.QWidget()
damping_layout = QtWidgets.QHBoxLayout(damping_container)

damping_label_prefix = QtWidgets.QLabel("Damping (c):")
damping_layout.addWidget(damping_label_prefix)

damping_slider = QtWidgets.QSlider(QtCore.Qt.Orientation.Horizontal)
damping_slider.setRange(0, 100)  # 0.0 to 1.0
damping_slider.setValue(int(c * 100))
damping_slider.setTickPosition(QtWidgets.QSlider.TickPosition.TicksBelow)
damping_slider.setTickInterval(10)
damping_layout.addWidget(damping_slider)

damping_value_label = QtWidgets.QLabel(f"{c:.2f}")
damping_layout.addWidget(damping_value_label)

layout.addWidget(damping_container)

# Update function
def update_damping(slider_value):
    """Update damping coefficient from slider"""
    global c
    c = slider_value / 100.0
    damping_value_label.setText(f"{c:.2f}")
    update_visuals()

damping_slider.valueChanged.connect(update_damping)

Step 6: Adding Energy Graphs

The final feature is plotting kinetic and potential energy over time. This requires:

1. Storing energy data in arrays
2. Creating a second plot widget
3. Updating the plots each frame

First, let’s create arrays to store the data:

# Create arrays to store energy data
BUFFER_SIZE = 1000  # Keep the last 1000 data points
time_data = np.full(BUFFER_SIZE, np.nan)  # Fill with NaN initially
ke_data = np.full(BUFFER_SIZE, np.nan)    # Kinetic energy
pe_data = np.full(BUFFER_SIZE, np.nan)    # Potential energy
data_index = 0  # Track where to write next

Understanding circular buffers:

• We use fixed-size arrays to avoid unlimited memory growth
• np.nan (Not a Number) indicates “no data yet”
• data_index wraps around when it reaches BUFFER_SIZE (using % modulo operator)
• This creates a circular buffer that always shows the most recent 1000 points

Now create the energy plot:

# Create energy plot widget
energy_plot_widget = pg.PlotWidget()
layout.addWidget(energy_plot_widget)

energy_plot_item = energy_plot_widget.getPlotItem()
energy_plot_item.setTitle("Kinetic and Potential Energy")
energy_plot_item.setLabel('bottom', 'Time (s)')
energy_plot_item.setLabel('left', 'Energy (J)')
energy_plot_item.addLegend()  # Show a legend

# Create two plot lines: one for KE, one for PE
ke_plot = energy_plot_item.plot(
    pen=pg.mkPen('b', width=2),  # Blue line
    name='Kinetic Energy'         # Label for legend
)
pe_plot = energy_plot_item.plot(
    pen=pg.mkPen('r', width=2),  # Red line
    name='Potential Energy'       # Label for legend
)

Creating multiple plots:

• addLegend() creates a legend box that shows which color corresponds to which data
• The name parameter in plot() sets the label that appears in the legend
• 'b' and 'r' are color codes for blue and red

Now we need to update our pendulum_step() function to calculate and store energy:

def pendulum_step():
    """Update physics simulation one time step"""
    global theta, omega, t, data_index
    
    # Update time
    t += dt
    
    # Update physics (as before)
    omega += (g / L) * np.cos(theta) * dt + c/(m*L**2) * (-omega) * dt
    theta += omega * dt
    
    # Calculate energies (formulas from physics - you'll learn these!)
    v = L * omega                      # Linear velocity
    KE = 0.5 * m * v**2                # Kinetic energy
    PE = m * g * L * (1 - np.sin(theta))  # Potential energy
    
    # Store data in circular buffer
    time_data[data_index] = t
    ke_data[data_index] = KE
    pe_data[data_index] = PE
    data_index = (data_index + 1) % BUFFER_SIZE  # Wrap around at end
    
    # Update energy plots
    if np.isnan(time_data[0]):  # Buffer not full yet
        plot_time = time_data[:data_index]
        plot_ke = ke_data[:data_index]
        plot_pe = pe_data[:data_index]
    else:  # Buffer is full, handle wrap-around
        plot_time = np.concatenate((time_data[data_index:], time_data[:data_index]))
        plot_ke = np.concatenate((ke_data[data_index:], ke_data[:data_index]))
        plot_pe = np.concatenate((pe_data[data_index:], pe_data[:data_index]))
    
    ke_plot.setData(plot_time, plot_ke)
    pe_plot.setData(plot_time, plot_pe)
    
    update_visuals()

Understanding the circular buffer logic:

• data_index = (data_index + 1) % BUFFER_SIZE - The % operator wraps the index back to 0
• When the buffer isn’t full yet, time_data[0] is still np.nan
• When not full: we slice from start to current index
• When full: we concatenate the “newer” part (from data_index to end) with the “older” part (from start to data_index)
• This keeps the time axis correctly ordered for plotting

Important: You’ll also need to clear the energy data when resetting the simulation. Update your reset_simulation() function to include:

time_data.fill(np.nan)
ke_data.fill(np.nan)
pe_data.fill(np.nan)
data_index = 0
ke_plot.setData([], [])
pe_plot.setData([], [])

Key PyQt Concepts You’ve Learned:

1. Application Structure

   • QApplication - The main application object
   • QMainWindow - The window container
   • Widgets - UI elements (plots, sliders, labels)
   • Layouts - Organizing widgets (QVBoxLayout, QHBoxLayout)

2. Signals and Slots

   • Signals are events (timer timeout, slider moved, mouse clicked)
   • Slots are functions that respond to signals
   • connect() links signals to slots

3. Event Handling

   • Timer events for animation (QTimer)
   • Keyboard events (keyPressEvent)
   • Mouse events (sigMouseClicked)

Key pyqtgraph Concepts:

1. PlotWidget - Container for plots
2. PlotItem - The actual plotting area
3. plot() - Creates line plots
4. ScatterPlotItem - Creates scatter points
5. setData() - Updates plot data efficiently

Program Flow:

Start app → Create window and widgets → Set up initial state
     ↓
Start timer (60 fps)
     ↓
Every frame:
  1. Update physics (angle, velocity)
  2. Calculate energies
  3. Store data in circular buffer
  4. Update all plots
     ↓
Respond to user input:
  - Mouse clicks → Set angle
  - Keyboard → Pause/reset
  - Sliders → Change parameters

Tips for Your Own Implementation:

1. Start Simple - Get a basic pendulum working first, then add features one at a time
2. Test Incrementally - Run your code after adding each feature to catch errors early
3. Use Print Statements - Add print() statements to debug and understand the flow
4. Experiment - Try different colors, sizes, ranges. Break things and fix them!
5. Read Error Messages - PyQt error messages often tell you exactly what’s wrong

Common Pitfalls to Avoid:

• Forgetting global when modifying variables in functions
• Using degrees instead of radians with numpy trig functions
• Forgetting to call update_visuals() after changing state
• Not connecting signals to slots (your functions won’t be called!)
• Putting app.exec() too early (window will show before everything is set up)

Good luck with your implementation! Remember, the physics equations aren’t important for this programming exercise - you’ll learn those in your mechanics course. Focus on understanding the PyQt and pyqtgraph code structure.