Goals and Outcomes

In this project you will create a simulation for a Newton’s Cradle (see visualization below). A Newton’s cradle is a series of pendula that display a “chain reaction” when each pendulum knocks into the pendulum next to it. This project involves some super cool - and fundamental! - physics concepts like angular momentum and conservation of momentum, which you can see in the Physics appendix. If you want some intuition for what you’re building in this project, we recommend skimming through this section now if you want to understand what you’re dealing with!

In this project, you will create a Newton’s cradle based on information drawn from your own CSV file!

The project uses VPython and pandas to implement the visualization.

Setup

Go to project registration to register for the project. Make sure to sign up for cs1-25sp projects on the left! Once you do, restart vscode and a folder with the starter code should automatically show up in your file browser.

Project Grading

Grading guidelines are outlined here!

What is a CSV file

A CSV file, which is an example of a filename extension, refers to any file ending in .csv. Filename extensions tell us the type of content contained in a file. For example, a file ending in .png tells us that the file is likely going to be an image while a file ending in .mp4 tells us that the file is likely going to be a video.

CSV stands for comma-separated values. The most common use of CSV files is to store and move tabular data (often done in the field of machine learning!). So a file ending in .csv tells us that the file is going to contain data best visualized in a table. Each line in a CSV file represents a data point. Each value in the line describes an attribute of that data point. The very first line in a CSV file contains the names of each attribute.

It is helpful to understand the contents of a CSV file by looking at one. Below, is an image of what a CSV file containing the information of CS1-25sp TAs looks like.

In the later parts of this project, you can edit a CSV file called newton_cradle_pends.csv that contains information about the pendulums you will be simulating in your Newton’s Cradle.

What is pandas

pandas is a library that is designed for data analysis since it allows us to create and manipulate dataframes (you can think of these as tables containing data) by reading CSV files.

What is VPython

VPython is a library that is designed to help write physics simulations, since it allows us to build and visualize objects, and also has a built-in mathematical library (including trigonometry, vectors and math operations).

VPython Objects

You can think of VPython’s box, sphere, and cylinder as the shapes that we get to see in the final visualization. Specifically, the shapes we use to create the pendulum are:

• box for the axle (support)
• sphere for the bob (mass hanging in the pendulum)
• cylinder for the cord (string of the pendulum)

To customize the bobs, we use VPython’s textures and colors, which are initialized in constants.py. The TEXTURE_MAP dictionary contains the textures, and the COLOR_MAP dictionary contains the colors. These have been used in pendulum.py (which is provided to you), but you will end up working with these objects; so it is good to know where they came from!

When working with box, sphere, and cylinder, you can use their specific attributes to access information. For example, if we have ball = sphere(...), then we can use ball.radius to get ball’s radius and ball.pos to get ball’s position (as a vector).

We have provided additional documentation on the attributes of various VPython objects if you would like to read it.

VPython Math

VPython uses vectors to define the axes and positions. It uses something called “operator overloading” to allow us to add and multiply vectors exactly like we do with numbers! This is the same thing that allows us to use + with both strs and ints!

To find the magnitude of a given vector vec, you can use the function mag(vec). You can also directly use trigonometric functions like sin(theta) where theta is in radians.

Newton’s Cradle Simulation

Before you write any code, it is important to understand what a pendulum is.

What is a pendulum

A pendulum is defined by the following 7 attributes:

• mass - the mass of the pendulum
• restitution_coeff - the “level” of inelasticity of collision when another object collides with this pendulum
• color - color of the pendulum
• texture - texture of the pendulum
• objects - the Vpython objects (box, sphere, cylinder) that makes up the phyiscal representation of the pendulum
• theta - the current angle of the pendulum
• omega - the current velocity of the pendulum

Representations of Newton’s Cradle

In this project we are representing a Newton’s Cradle in 2 ways. First, using a CSV file. Second, using a list of dictionaries that we will refer to as pend_list.

Using a CSV file enables a user of our simulation program to easily create and modify pendulums in their Newton’s Cradle without worrying about how the code works. While on the other hand, using a list of dictionaries called pend_list enables the programmer to easily work with the pendulums’ data.

In the CSV representation, the information of a single pendulum is stored on a line. Take a look at newton_cradle_pends.csv in src/.

In the list of dictionaries representation, each pendulum is represented by a dictionary in a list called pend_list. Each key is the name of a pendulum attribute and the value of a key is the value associated with that attribute.

A CVS to pend_list converter (D Tests)

Once you have understood how each pendulum is represented, you are ready to begin implementing the extract_and_convert function that converts the information representing a Newton’s Cradle in a CVS file to a pend_list! For this part, you will be working in pds_helper.py in src/. Implement the following function.

extract_and_convert(relative_filepath) (partially provided)

Once the tests for extract_and_convert passed, feel free to press the “triangle icon” on the top right of vscode in the pds_tester.py file to see what a what the correct pend_list looks like!

We know this is only a brief introduction into pandas, if you want to learn more, here’s a short guide!

Pendulum Creation (D Tests)

We will now focus on actually building different types of pendulums from CSV files.

You will start by implementing four short functions in the file special_cradles.py:

uniform_mass_newton_cradle(relative_filepath, mass)

uniform_e_newton_cradle(relative_filepath, e_val)

elastic_newton_cradle(relative_filepath)

inelastic_newton_cradle(relative_filepath)

make_newton_cradle(relative_filepath, r_param, theta_init)

Swing Implementation (C Tests)

In the second part of the project, you will focus on the functionality of each individual pendulum; specifically, how each pendulum swings. You will implement that functionality for the entire cradle. The following three functions are all located in the file swinging.py.

angle_update(omega, theta, r_param, dt, g)

Next, you will write the function to update the each pendulum. We’ve provided a helpful function swing_update, which essentially performs a ‘swing’ of the pendulum. It takes in the pendulum’s dictionary pend_dict, the length of the cord r_param, the time step dt, and the gravitational acceleration g and updates the angle and position of the pendulum components, using the helper function angle_update. The pend_dict is updated and nothing is returned.

full_swing_update(pend_list, r_param, dt, g)

Handling Collisions (B Tests)

In this part of the project, you will focus on what happens to the pendula when they knock into each other, which lies at the heart of the Newton’s cradle demonstration. Everything from now on will need to be written in visualize_cradle_run.py. Specifically, you will implement the handle_collision function to the following specification:

handle_collision(e, omega1, omega2, m1, m2, r_param)

Now we get to the longest function you will have to write, but we can break it down.

handle_two_bobs(pend1, pend2, r_param)

Running the Simulation (A Tests)

This is where you put everything you have written so far to use. Finally, in this part of the project, you will put everything together and get to see your simulation!

newton_cradle_tick(pend_list, r_param, dt, g)

if __name__ == "main" (partially provided)

You can customise your simulation by modifying the values in the CSV file called newton_cradle_pends.csv located in src/. Before making the Newton’s Cradle, you can use any of the helper functions uniform_mass_newton_cradle, inelastic_newton_cradle, and elastic_newton_cradle to see the effects of uniform coefficients of restitution and masses on the system. We have provided you with a function called write_to_csv that takes in a pend_list and writes it to the CSV file called newton_cradle_pends.csv. You can also directly modify the CSV file and see the changes translate into your Newton’s cradle - so feel free to play around with the values and the number of pendulums! Make sure the values you pick for color and texture are in constants.py. Changing the values of theta and omega will not affect the simulation, think about why this is the case.

Appendix: Physics Derivations!

The following physics is based on a pendulum that looks like this [2]:

Angular Momentum and Velocity

For a swinging pendulum, we care more about the angular physical attributes than the linear ones. Thus, we have to work with:

Angular Acceleration

\(\dot{\omega} = \frac{-g \sin \theta}{R}\) where $g$ is the gravitational acceleration and $\theta$ is the angle formed by the cord normal to the axle.

Discrete Updates of the angular velocity with the angular acceleration

\(\omega_{new} = \omega + \dot{\omega} \Delta t\)

Updating the angle using the new angular velocity

\(\theta_{new} = \theta + \omega_{new} \Delta t\)

Conservation Laws

The Newton’s cradle is defined by the collisions between its pendula. The entire system should conserve kinetic energy in an elastic collision and conserve linear momentum (during a collision, we can approximate the momentum to be linear). We can approach the entire sequence of pendula in a pairwise manner, so we only consider the collision of two pendula. The two equations we have to take care of are:

Conservation of Linear Momentum

\(m_1 v_1 + m_2 v_2 = m_1 v_1^{new} + m_2 v_2^{new}\)

Conservation of Kinetic Energy

Kinetic energy is a little tricky to conserve when there is an elastic collision. We ask you to take in a quantity called coefficient of restitution $e$ which determines the “level” of inelasticity of a collision. If $e = 0$, it is a perfectly inelastic collision (kinetic energy not conserved), and if $e = 1$, it is a perfectly elastic collision (kinetic energy is conserved). We define:

Then, combining these equations, we can update the velocities of the objects post-collision as follows:

If we start off using angular velocities $\omega$, we need to convert them to linear velocities $v = R \times \omega$ for this equation, and the new calculated velocities can be converted back to angular velocities with the same equation.

Honor Roll Challenge

If you would like to challenge yourself even further, we have designed problems that that go beyond the course’s typical level of complexity. While these problems are entirely optional, we think some of you might enjoy pushing your limits. We will offer several of these challenges throughout the course assignments but you are in no way expected to complete them. You should expect much less guidance for those problems and cannot utilize TA Office Hours as our priority is to support students working on the main project. For general guidance or additional questions, please attend Professor Blank’s Office Hours.

References:

1. https://sites.ualberta.ca/~dnobes/Teaching_Section/Simulations/Newtons_Cradle/Simulation/Cradle.pdf
2. Image credit: Khan Academy, “Trig and forces: the pendulum”. https://www.khanacademy.org/computing/computer-programming/programming-natural-simulations/programming-oscillations/a/trig-and-forces-the-pendulum