COS 126, Fall 2026

0. Hello, World

Mon, 01 Jan 0001 00:00:00 +0000

This assignment introduces Java programming and the workflow for preparing and submitting COS 126 assignments. You will use IntelliJ to write, compile, and run Java programs, and TigerFile to submit your work.

Getting Started

Before you begin, complete the following setup and policy steps:

Read Sections 1.1 and 1.2 of the course textbook.
Browse the course website and read the collaboration policies.
Take the Collaboration Policy Quiz - look under Quizzes.
Fill out the Course Entry Survey - look under Quizzes. Completing this will count towards your participation grade (equivalent to participation in one lecture).
Install the latest COS 126 Java programming environment on your laptop for macOS, Windows, or Linux. Reuse the hello project folder for this assignment.
Consult the Assignments FAQ for common questions and answers.

If you get stuck, post on Ed, attend office hours, or visit the COS Lab TAs. Don’t be afraid to ask for help!

Restrictions

Follow these rules to support the intended learning goals and preserve anonymous grading:

For each assignment, you may use only Java features introduced in COS 126 so far.
For example, on this assignment, you may call System.out.print(), Integer.parseInt(), Math.sqrt(), and StdAudio.play(), but you may not use loops or conditionals.
Do not include your name, NetID, or email in any submitted file except acknowledgments.txt.

Hello, World

Write a program HelloWorld.java that prints “Hello, World.” If you completed the IntelliJ setup, you have already done this step.

~/Desktop/hello> javac HelloWorld.java

~/Desktop/hello> java HelloWorld
Hello, World

Personalized Greeting

Write a program Greeting.java that takes three command-line arguments: a greeting and two names. It prints two lines. The first line uses the names in the given order; the second line in the reverse order.

Below are some sample executions. Match the output exactly, including punctuation.

~/Desktop/hello> javac Greeting.java
~/Desktop/hello> java Greeting Hi Sonia Samuel
Hi Sonia and Samuel.
Hi Samuel and Sonia.

~/Desktop/hello> java Greeting Ciao Kellia Yacoub
Ciao Kellia and Yacoub.
Ciao Yacoub and Kellia.

~/Desktop/hello> java Greeting γεια Alexandria Homer
γεια Alexandria and Homer.
γεια Homer and Alexandria.

~/Desktop/hello> java Greeting "Nǐ hǎo" Ahmed Hagop
Nǐ hǎo Ahmed and Hagop.
Nǐ hǎo Hagop and Ahmed.

Q.How do I pass a greeting or name that contains spaces as a single command-line argument?

Spaces normally separate command-line arguments. To include a space, wrap the entire argument in double quotes.

For more multilingual examples, see HelloWorldMultilingual.java.

Hello, World in Many Voices

Write a program SayHelloWorld.java that takes the name of a WAV file as a command-line argument and plays it using StdAudio.play().

Details:

StdAudio.play() takes a filename, such as "HelloWorld.wav", and plays the audio file.
The filename may include a directory path, such as people/KevinWayne.wav.
When using the command line, compile and run with javac-introcs and java-introcs. These commands tell Java where to find our course libraries, such as StdAudio.
The people, google and siri directories contain many WAV files of ‘Hello, World’ in different voices and languages, including recordings and synthetic audio (from Google Translate and Apple Siri).

Below are some sample executions:

~/Desktop/hello> javac-introcs SayHelloWorld.java

~/Desktop/hello> java-introcs SayHelloWorld people/KevinWayne.wav

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/hello> java-introcs SayHelloWorld people/AloeBlacc.wav

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/hello> java-introcs SayHelloWorld google/Spanish.wav

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/hello> java-introcs SayHelloWorld siri/Kyoko.wav

  
  
  
  
  Your browser does not support the audio element.

Record yourself saying “Hello, World” (any language) and save the audio file in your device’s native format:

Mac OS X: Voice Memos app → Record. Drag the recording to a folder to save the file.
iPhone: Voice Memo app → Record. Transfer the file to your laptop.
Windows: Sound Recorder → Record → Save.
Android: Use an app that allows you to record audio. Transfer the file to your laptop.

Then convert it to WAV format (e.g., using Zamzar) and name the file MyHelloWorld.wav.

Great Circle Distance

The great-circle distance is the length of the shortest path between two points $(x_1, y_1)$ and $(x_2, y_2)$ on the surface of a sphere, where the path is constrained to be along the surface.

Write a program GreatCircle.java that takes four double command-line arguments $x_1$, $y_1$, $x_2$, and $y_2$—the latitude and longitude (in degrees) of two points on the surface of the Earth—and prints the great-circle distance (in kilometers) between them.

Use the following spherical law of cosines formula:

\[ distance \; = \; r \cdot \arccos \left ( \sin x_1 \sin x_2 \, + \, \cos x_1 \cos x_2 \cos(y_1 - y_2) \right ) \]

where $r = \text{6,371.0}$ is the mean radius of the Earth (in kilometers).

Below are some sample executions. Your output should match exactly, except possibly in the last digit.

~/Desktop/hello> javac GreatCircle.java

~/Desktop/hello> java GreatCircle 40.35 74.65 48.87 -2.33   // Princeton to Paris
5902.927099258562 kilometers

~/Desktop/hello> java GreatCircle 30.0 15.0 30.0 75.0       // for debugging
5706.280401668459 kilometers

Q.The command-line arguments are given in degrees but Java’s trigonometric functions use radians. What can I do?

Use code like radians = Math.toRadians(degrees) to convert from degrees to radians.

Q.Which other math library functions will I need?

You will also need Math.sin(), Math.cos(), and Math.acos().`.

Q.I’m getting the wrong result. How can I check my formula?

Create a small example that you can work out by hand. Then verify that each intermediate term matches.

Q.Can I use a different formula to compute the great-circle distance?

No. Use the spherical law of cosines formula, as specified. Later in the course, we will use the Haversine formula, which is more accurate for nearby points with floating-point arithmetic.

Q.Is this formula exact, given that the Earth is not a perfect sphere?

No. However, this formula is a good approximation to the true distance.

RGB to CMYK Conversion

Colors are represented in different formats, including RGB and CMYK.

RGB format is used for screens and web graphics. It specifies each component (red, green, blue) on an integer scale from 0 to 255.
CMYK format is used for print publishing. It specifies each component (cyan, magenta, yellow, black) on a real scale from 0.0 to 1.0

Write a program RGBtoCMYK.java that converts from RGB format to CMYK format. The program takes three integer command-line arguments: red, green, and blue (each between 0 and 255). It prints the RGB components, followed by the corresponding CMYK components.

Use the following conversion formulas:

\[ \begin{aligned} white & \;\; = \; \max \left ( { \frac{red}{255}, \; \frac{\textit{green}}{255}, \; \frac{blue}{255}} \right ) \\[.2in] cyan & \;\; = \; \left ( white - \frac{red}{255} \right ) \;\;\;\, \div \; white \\[.2in] magenta & \;\; = \; \left ( white - \frac{green}{255} \right ) \; \div \; white\\[.2in] yellow & \;\; = \; \left ( white - \frac{blue}{255} \right ) \;\;\, \div \; white\\[.2in] black & \;\; = \; 1 - white \end{aligned} \]

Restriction: You may assume the three RGB arguments are not all zero (to ensure $white$ is nonzero).

Below are some sample executions. Your output format must match the examples exactly, including whitespace and punctuation.

~/Desktop/hello> javac RGBtoCMYK.java

~/Desktop/hello> java RGBtoCMYK 75 0 130   // indigo
red     = 75
green   = 0
blue    = 130
cyan    = 0.423076923076923
magenta = 1.0
yellow  = 0.0
black   = 0.4901960784313726

~/Desktop/hello> java RGBtoCMYK 255 143 0   // Princeton orange
red     = 255
green   = 143
blue    = 0
cyan    = 0.0
magenta = 0.4392156862745098
yellow  = 1.0
black   = 0.0

Q.How do I compute the maximum of three numbers?

Java does not include a built-in function for that. However, Math.max(x, y) returns the maximum of x and y.

Q.How do I align the equals signs in the output?

We will learn about formatted printing later in the course. For now, add the appropriate number of spaces in the string you print, before each equals sign.

Readme

Complete readme.txt to describe your work. Use the provided template and answer every question.

Acknowledgments

Complete acknowledgments.txt using the provided template. It contains two sections:

List the names and dates of anyone who helped you with this assignment. When you attend office hours or a Lab TA session, introduce yourself and write down the person’s name.
```
1/23/26 Alan Turing (lab TA)
Helped me cast the result of Math.round() to an int.

1/24/26 Grace Hopper (faculty)
Explained how to use the StdAudio library.
```
Include the Student Acknowledgment of Original Work from Rights, Rules, Responsibilities. Add your digital signature as /s/ followed by your full name.
```
This programming assignment represents my own work in
accordance with University regulations. /s/ Ada Lovelace
```

Submission

HelloWorld.java
Greeting.java
SayHelloWorld.java
GreatCircle.java
RGBtoCMYK.java
MyHelloWorld.wav
readme.txt
acknowledgments.txt

Then click Check Submitted Files to check your work. Fix every reported issue (including issues in readme.txt and acknowledgments.txt) and resubmit.

You may submit files individually or in a batch.
You may click Check Submitted Files at most 20 times per assignment.
We will not grade your submission until acknowledgments.txt is submitted. If you plan to submit late, do not submit that file until you are finished and ready for grading.
Read the output of Tigerfile carefully! You should address all failed test cases, warnings, and error messages in your solution. These indicate that there may be issues that need to be fixed. If you are unsure how to address a failed test, warning, or error, please ask for help!

Grading Breakdown

Item	Points
HelloWorld.java	4
Greeting.java	8
SayHelloWorld.java	8
GreatCircle.java	8
RGBtoCMYK.java	8
readme.txt	4
Total	40

You must complete the Collaboration Policy Quiz with a perfect score to receive credit for any programming assignment.

1. Conditionals and Loops

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will use conditionals and loops to write small programs involving sound and images. You will also diagnose and fix bugs in a provided program.

Getting Started

Read Section 1.3 of the textbook and review the corresponding lectures and precepts.
Download and unzip loops.zip , then open the loops project in IntelliJ.
Refer to the Programming Assignments FAQ as needed.
Reminder: You may use only Java features introduced so far.

Saying Military Time

Military time specifies the time of day in the form HHMM, where HH is the hour since midnight and MM is the minutes since the last full hour. For example, 1200 is noon; 2359 is one minute before midnight; and 0100 is one hour after midnight.

To parse and say military time, following these steps:

Extract the hours HH and minutes MM from the four-digit time HHMM.
Say the hours HH. If HH is between 1 and 9, precede it with the word “zero.”
Say the word “hundred.”
Say the minutes MM, unless MM is 00.
Say the word “hours.”

For example, 2359 is spoken as “twenty-three hundred fifty-nine hours” and 0100 as “zero one hundred hours.”

Write a program SayMilitaryTime.java to say a given military time using these rules. The program takes two command-line arguments:

Time: A 4-digit string in military time (e.g., 1200, 2359, or 0100).
Voice: The name of a voice subdirectory (e.g., Alex or Siri).

The subdirectories Alex, Siri, Amélie, Luca, Paulina, Samantha, and Veena contain voice recordings of people saying the numbers 0 through 59, along with the words for hundred and hours. For example, Alex/59.wav is Alex saying the number 59 and Siri/hundred.wav is Siri saying the word hundred.

Below are some sample executions:

~/Desktop/loops> java-introcs SayMilitaryTime 2359 Alex

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs SayMilitaryTime 1100 Siri

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs SayMilitaryTime 0609 Veena

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs SayMilitaryTime 0011 Paulina

  
  
  
  
  Your browser does not support the audio element.

Q.What happens if the argument to Integer.parseInt() has leading zeros, such as 0011?

Leading zeros are allowed and simply ignored. For example, Integer.parseInt("0011") returns the integer 11.

Q.What are the valid values for HHMM (24-hour time)?

Your program should correctly handle any HHMM time from 0000 to 2359.

Context: The 24-hour clock is used widely in Asia, Europe, Africa, and Latin America. In the United States, it is used in the military, aviation, navigation, computing, logistics, and hospitals.

Random Walkers

Fix the bugs in RandomWalkers.java. It must compile with no errors and no warnings, and it must pass all TigerFile checks, including style checks. The intended behavior is as follows:

The program takes two integer command-line arguments: $n$ (the number of steps) and $trials$ (the number of trials).
One trial simulates a random walk for $n$ steps, starting from the origin:
- maintain the current location $(x, y)$, initially $(0, 0)$
- repeat $n$ times: move one unit north, east, south, or west, each with probability $\tfrac14$
- after $n$ steps, compute the squared distance from the origin: $x^2 + y^2$
Print the mean squared distance (the average of the squared distances over all trials).

Here are sample executions of the corrected RandomWalkers. Because the walk is random, your output will vary. However, when $trials$ is large, your output should be close to the output below.

~/Desktop/loops> java-introcs RandomWalkers 100 10000
mean squared distance = 101.446

~/Desktop/loops> java-introcs RandomWalkers 100 10000
mean squared distance = 99.1674

~/Desktop/loops> java-introcs RandomWalkers 200 1000
mean squared distance = 195.75

~/Desktop/loops> java-introcs RandomWalkers 200 1000
mean squared distance = 198.21

~/Desktop/loops> java-introcs RandomWalkers 1600 100000
mean squared distance = 1600.13064

~/Desktop/loops> java-introcs RandomWalkers 1600 100000
mean squared distance = 1603.72

Context: Random walks model Brownian motion and diffusion, with applications ranging from ink dispersing in water to polymer formation and neural activity.

Duotone Filter

A duotone filter maps each pixel to a weighted average of two palette colors, using the pixel’s brightness as the weight.

To apply a duotone filter, process each pixel independently:

Let $(r, g, b)$ be the pixel’s red, green, and blue components. Each component is an integer between $0$ and $255$.
Compute the pixel brightness $\alpha$ using the NTSC luma coefficients:

$$\alpha = \tfrac{1}{255} (0.299r + 0.587g + 0.114b)$$
This guarantees that $0 \le \alpha \le 1$.
Let $(r_1, g_1, b_1)$ and $(r_2, g_2, b_2)$ be the RGB components of the two palette colors.
Compute the new color $(r^\prime, g^\prime, b^\prime)$ as follows: \begin{aligned} r' & = \alpha \, r_1 \; + \; (1 - \alpha) \, r_2 \\ g' & = \alpha \, g_1 \; + \; (1 - \alpha) \, g_2 \\ b' & = \alpha \, b_1 \; + \; (1 - \alpha) \, b_2 \end{aligned} Round each component to the nearest integer.

Write a program Duotone.java that takes seven command-line arguments: filename, r1, g1, b1, r2, g2, and b2. It should apply the duotone filter and display the result using StdPicture.

The sample execution below applies a duotone filter to a photo of Johnson Arch using Princeton orange $(245, 128, 37)$ for the first palette color and black $(0, 0, 0)$ for the second.

~/Desktop/loops> java-introcs StdPicture JohnsonArch.jpg



~/Desktop/loops> java-introcs Duotone JohnsonArch.jpg 245 128 37 0 0 0

Take a photo of a campus structure (building, archway, gate, etc.) and apply your duotone filter. Submit the original photo as MyPhoto.jpg, and record the two palette colors you used in your readme.txt.

Q.Which methods are available in StdPicture?

See the Java cheatsheet.

Q.Why does StdPicture use the conventions that the indices are $(col, row)$ and $(0, 0)$ is upper left?

These are common conventions in image processing. It’s a tradeoff between coordinate-system consistency and array-indexing consistency.

Using $(col, row)$ means that the first coordinate correspond to $x$ (horizontal) and the second corresponds to $y$ (vertical).
Using the upper-left as the origin reflects early display hardware, which scanned from top to bottom. As you move down the screen, the row index increases.

Q.What does java-introcs StdPicture filename do?

It runs main() in StdPicture, which takes an image filename as a command-line argument and displays that image in a window.

Q.How do I round a double to the nearest int?

Use (int) Math.round(x).

Q.Why use the NTSC luma coefficients instead of a simple average of the RGB components?

They better approximate perceived brightness, since the human eye is more sensitive to green than to red or blue.

Q.My photo appears to be rotated 90 degrees in StdPicture. Why?

It’s likely that your image is rotated 90 degrees but has an EXIF tag that tells certain apps to rotate it back 90 degrees. On macOS, open your image in Preview, rotate it 90 degrees clockwise, then Tools -> Rotate Left -> Rotate Right and Save. That should make it no longer depend on the EXIF tag.

Q.My photo is too large to display in StdPicture. How can I fix?

Create a smaller version of your photo.

Context: Duotone is a popular effect for photographers and digital artists. See this site for examples.

Musical Dice Game

A musical dice game (Musikalisches Würfelspiel) generates music by stitching together precomposed measures chosen at random. In this exercise, you will assemble a 32-measure Viennese waltz in the style of Mozart. The waltz has two parts: a minuet followed by a trio.

Minuet. The minuet consists of 16 measures (numbered 0 to 15).
- For measure $i$, roll two fair six-sided dice and let $s$ be the sum.
- Play minuet<i>-<s>.wav.
- For example, if you roll an 8 for measure 3, play minuet3-8.wav.
- Note: sums range from 2 to 12; 7 is most likely, and 2 and 12 are least likely.

Trio. The trio consists of 16 measures (numbered 0 to 15).
- For measure $i$, roll one fair six-sided die and let $r$ be the roll.
- Play trio<i>-<r>.wav.
- For example, if you roll a 6 for measure 15, play trio15-6.wav.

Instruments and files. The project folder includes several instrument subdirectories. For example, mozart-piano contains 272 WAV files named using the conventions above:
- Minuet: 16 measures × 11 possible sums = 176 files.
- Trio: 16 measures × 6 possible die outcomes = 96 files.
- The other subdirectories (mozart-clarinet, mozart-flute-harp, and mozart-mbira) provide the same measures for different instruments.
To play minuet3-8.wav using a clarinet, call StdAudio.play("mozart-clarinet/minuet3-8.wav").

Write a program MusicalDiceGame.java to play a waltz according to the rules above. The program takes one command-line argument: the instrument subdirectory name (e.g., mozart-piano). Here are some sample executions:

~/Desktop/loops> java-introcs MusicalDiceGame mozart-piano

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs MusicalDiceGame mozart-piano

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs MusicalDiceGame mozart-clarinet

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs MusicalDiceGame mozart-flute-harp

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/loops> java-introcs MusicalDiceGame mozart-mbira

  
  
  
  
  Your browser does not support the audio element.

Context: Each run generates a new waltz from precomposed measures that follow a rigid harmonic structure. It sounds convincingly Mozart-like, but it rarely produces anything truly extraordinary.

Submission

Upload all required files to TigerFile :

SayMilitaryTime.java
RandomWalkers.java
Duotone.java
MusicalDiceGame.java
MyPhoto.jpg
readme.txt
acknowledgments.txt

Grading Breakdown

File	Points
SayMilitaryTime.java	8
RandomWalkers.java	8
Duotone.java	9
MusicalDiceGame.java	9
MyPhoto.jpg	2
readme.txt	4
Total	40

2. Arrays and Input/Output

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will write array-based programs that read input with StdIn, print results with StdOut, draw graphics with StdDraw, play sound using StdAudio. You will also redirect standard input to read from a file.

Getting Started

Read Sections 1.4 and 1.5 of the textbook and review the corresponding lectures and precepts.
Download and unzip arrays.zip , then open the arrays project in IntelliJ.
Take the Getting Help in COS 126 Quiz.
Consult the Programming Assignments FAQ as needed.
Refer to the relevant textbook library APIs in the Java Cheatsheet.
Reminder: You may use only Java features introduced so far.

Dice and the Gaussian Distribution

Write a program DiceHistogram.java that takes two command-line arguments: $n$ (the number of fair six-sided dice) and $trials$ (the number of trials). Each trial consists of rolling all $n$ dice, summing the results, and recording the total. Use an integer array to tabulate how many times each possible total occurs (from $n$ to $6n$) over all trials. Then print a text histogram of the results.

Print one line per total. Each line contains:

the total, right justified in a field of width 3,
a colon,
one space,
a sequence of * characters whose length equals the number of times that total occurred.

Here are a few sample executions. Because the rolls are random, your output may vary. However, when the number of trials is large, the histogram should resemble the examples below.

~/Desktop/arrays> java-introcs DiceHistogram 2 500
  2: **************
  3: ***************************
  4: *********************************
  5: *************************************************************
  6: **********************************************************************
  7: ******************************************************************************
  8: ***********************************************************************
  9: **********************************************************
 10: **********************************************
 11: ****************************
 12: **************

~/Desktop/arrays> java-introcs DiceHistogram 10 1000
 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:

Context: The central limit theorem, a key result in probability and statistics, asserts that when the number of dice and trials is large, the histogram of the sums approaches the familiar bell curve (Gaussian distribution).

Q.What values should my program handle for n and trials?

Assume that $0 \leq n < 166$ (fits in a field of width 3) and $trials \geq 0$.

Q.How do I print an integer right-justified in a field of width 3?

Use formatted printing. For example,

StdOut.printf("%3d", value);

Q.I have the magic number 6 sprinkled through DiceHistogram.java. Is there a better way?

Yes. Define a named constant and use it throughout. For example:

int SIDES = 6;

Echo Filter

Consider what happens if you superpose a sound file with a delayed copy of itself. You will hear the same sound twice, with the second instance slightly delayed. If the $delay$ is relatively short (say, 15,000 samples or about 1/3 of a second) and you reduce the loudness of the delayed copy by scaling its samples by a $decay$ factor (e.g, multiply by 0.5), the result is an echo effect, similar to what you might hear in a tunnel or large empty room.

Example. Consider the following sound wave:

Here is the same sound wave with $delay = 3$ (shift 3 positions to the right) and $decay = 0.8$ (multiply by 0.8):

Superposing the two sound waves (adding them element-by-element) results in the following:

Task. Write a program EchoFilter.java that takes three command-line arguments: a string filename, an integer delay, and a real-valued decay factor. It applies an echo filter to the given sound file and plays the resulting sound.

The length of the resulting sound (in samples) is the original length plus the delay.

Here are some sample executions:

~/Desktop/arrays> java-introcs EchoFilter IHaveADream.wav 0 0.0

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter IHaveADream.wav 15000 0.5

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter PearlHarbor.wav 15000 0.5

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter TheHillWeClimb.wav 10000 0.5

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter Crow.wav 10000 0.5

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter HelloWorld.wav 5000 1.0

  
  
  
  
  Your browser does not support the audio element.


~/Desktop/arrays> java-introcs EchoFilter RowYourBoat.wav 117600 1.0

  
  
  
  
  Your browser does not support the audio element.

Context: An echo filter is a popular voice effect that you can apply on social media platforms such as TikTok.

Q.Is delay measured in samples?

Yes. The echo begins delay samples after the original sound.

Q.Can I assume that delay is a non-negative integer?

Yes. Negative delays correspond to reverse echo effects, but we will not test those cases.

Q.Can I assume that decay is between 0 and 1?

Yes. We will test your program only with decay values between 0 and 1.

Q.Is it possible for delay to be longer than the number of samples in the original array?

Yes. Think about an echo from a far-away mountain: the echo might not start until after the original sound has ended. If designed properly, your code will handle this case without extra conditional logic.

Q.How do I test my program?

Start with a small example. For example, use decay = 0.8, delay = 3, and

double[] original = { 1.0, 0.0, 0.5, 0.0, -1.0, -0.5, 1.0, 0.25 };

to match the daigram above (and the sound in tiny.wav). This example is too small to play, but you can print the resulting array to verify your calculations.

Q.How do I print the contents of an array for debugging?

If a[] is an array, System.out.println(a) prints a reference to the array (not its elements). To print the elements, use a for loop.

Q.How many times should my program call StdAudio.play()?

Only once. Call StdAudio.play() with a double[] array as argument.

Q.The echo filter repeats the sound only once. How could I get a repeating, decaying echo?

Superpose several delayed copies of the original sound, with each successive copy shifted by a larger delay and scaled by a smaller decay factor. Feel free to experiment with this idea.

World Maps

Write a program WorldMap.java that reads boundary data for a country (or other geographic entity) from standard input (using StdIn) and draws it to standard drawing (using StdDraw). A country consists of a set of regions (e.g., states or provinces). Each region is described by a polygon. Represent a polygon using two floating-point arrays: one containing the $x$-coordinates and the other containing the $y$-coordinates of the polygon’s vertices.

Input format. The first line contains two integers: width and height. The remainder of the input is divided into regions.

The first token in each region is the region name. For simplicity, names contain no spaces.
The next token is an integer specifying the number of vertices in the region’s polygon.
The remaining tokens in the region are the $x$- and $y$-coordinates of the vertices.

Output format. Draw the polygons to standard drawing, using the following guidelines:

Call StdDraw.setCanvasSize() to set the size of the canvas to width-by-height pixels.
Call StdDraw.setXscale() and StdDraw.setYscale() so that the $x$-coordinates range from 0 to width and the $y$-coordinates range from 0 to height.
Call StdDraw.polygon() to draw each polygon. This method takes two arrays as arguments: the array of $x$-coordinates and the array of $y$-coordinates. It draws the polygon whose vertices are given by those $x$- and $y$-coordinates.

Data files. The project folder includes the following data files:

Here are some sample executions:

~/Desktop/arrays> java-introcs WorldMap < shapes.txt



~/Desktop/arrays> java-introcs WorldMap < usa.txt



~/Desktop/arrays> java-introcs WorldMap < iceland.txt



~/Desktop/arrays> java-introcs WorldMap < world.txt

Q.Can I assume the input file is properly formatted?

Yes. You may assume it matches the specified format (the expected number, order, and types of tokens).

Q.What if a region has multiple boundary polygons?

In the input file, it appears as multiple regions, one polygon per region. So, you don’t need to handle multi-polygon regions.

Q.Can I draw the boundary of a region as a sequence of line segments instead of a polygon?

No. You must draw each region using StdDraw.polygon(), as specified.

Q.My program runs slowly for inputs with a large number of regions. Any way to speed it up?

Yes. By default, as soon as you call a drawing method such as StdDraw.polygon(), the result appears on screen. Updating the screen is relatively expensive (in terms of CPU time). If there are thousands of geometric objects to draw, this can slow down your program considerably. To avoid this slowdown, use the double-buffering feature of standard draw:

Call StdDraw.enableDoubleBuffering() once before any drawing code. Now all drawing is done on an offscreen canvas.
Call the drawing commands such as StdDraw.polygon(). Nothing will appear on screen yet.
Call StdDraw.show(). This transfers the offscreen canvas to the onscreen canvas.

You can think of double buffering as collecting all drawing commands and then displaying them all at once.

Q.My favorite country is not supplied as one of the data files. Why not?

Some of the source data files we used had technical discrepancies, which made converting them into our format more challenging. If you wish to add a country, please send us an input file in the specified format.

Q.The displayed map distorts the areas of regions. How can I fix this?

Every map projection that represents a sphere on a plane introduces some distortion. For example, with the Mercator projection, Greenland appears to be about the same size as Africa; in reality, Africa is 14 times larger by area. The Gall–Peters projection reduces area distortion but distorts shapes instead.

Submission

Upload all required files to TigerFile :

DiceHistogram.java
EchoFilter.java
WorldMap.java
readme.txt
acknowledgments.txt

Grading Breakdown

Files	Points
DiceHistogram.java	12
EchoFilter.java	12
WorldMap.java	12
readme.txt	2
Getting Help Quiz	2
Total	40

3. Conjunction Function

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will implement functions that manipulates digital audio, then use them to create an audio collage. You will learn how to develop reusable functions, pass and return arrays, and manipulate audio.

Getting Started

Read Sections 2.1 and 2.2 of the textbook and review the corresponding lectures and precepts.
Download and unzip functions.zip , then open the functions project in IntelliJ.
Refer to the Programming Assignments FAQ as needed.
Review the StdAudio API.

Part I: Audio Library

Write a program AudioCollage.java to manipulate digital audio. As in lecture, we represent sound as an array of real numbers between –1 and +1, with 44,100 samples per second. You will implement functions that produce audio effects by transforming these arrays.

Implement the following API:

public class AudioCollage {

    // Returns a new array that rescales a[] by a factor of alpha.
    public static double[] amplify(double[] a, double alpha)

    // Returns a new array that clamps each sample to  the range [-1, +1].
    public static double[] clamp(double[] a)

    // Returns a new array that contains the samples of a[] in reverse order.
    public static double[] reverse(double[] a)

    // Returns a new array that is the concatenation of a[] followed by b[].
    public static double[] merge(double[] a, double[] b)

    // Returns a new array that mixes a[] and b[] by adding corresponding
    // samples. If one array is shorter, treat missing samples as 0.
    public static double[] mix(double[] a, double[] b)

    // Returns a new array that changes the speed of a[] by a factor of alpha.
    public static double[] changeSpeed(double[] a, double alpha)

    // Creates an audio collage and plays it on standard audio.
    // See Part II of the assignment specification for requirements.
    public static void main(String[] args)

}

Here is additional documentation for the API:

Each function returns a new array and does not modify its argument array(s).
You may assume that all array arguments are non-null.
Do not add public methods; you may add private helper methods.
amplify(double[] a, alpha)

Returns a new array with the same length as a[], where each sample is multiplied by a constant $\alpha$. If $|\alpha| > 1$, the result is louder; if $|\alpha| < 1$, it is quieter. For example:

Note: amplify() may produce samples whose absolute value exceed 1, even if all input samples are between –1 and +1.
clamp(double[] a)

Returns a new array where each sample in a[] is “clamped” to the range [–1, +1]:
- values greater than +1 become +1
- values less than –1 become –1
- values between –1 and +1 are unchanged
For example:
reverse(double[] a)

Returns a new array with the same samples as a[], but in reverse order. This can lead to unexpected (and sometimes entertaining) results. For example:
merge(double[] a, double[] b)

Returns a new array that contains the samples of a[] followed by the samples of b[]. If the two sounds have lengths $m$ and $n$, the resulting array has length $m + n$. This enables you to play two sounds sequentially. For example:
mix(double[] a, double[] b)

Returns a new array that adds the corresponding samples of a[] and b[] (sample-by-sample). If one array is shorter, treat missing samples as 0. This enables you to play two sounds simultaneously. For example:

Note: mix() may produce samples whose absolute value exceed 1, even if all input samples are between –1 and +1.
changeSpeed(double[] a, double alpha)

Returns a new array that changes the duration of a[] by resampling, using speed factor $\alpha > 0$. The returned array has length $\lfloor n / \alpha \rfloor$, where $n$ is the length of a[]. Sample $i$ of the returned array has the same value as sample $\lfloor i \alpha \rfloor$ of a[]. Larger $\alpha$ plays the sound faster (shorter duration); smaller $\alpha$ plays it slower (longer duration). For example:

Q.Which does the notation $\lfloor x \rfloor$ mean?

A.
It is the floor function: the largest integer less than or equal to $x$.

Q.How can I compute $\lfloor x \rfloor$ in Java?

A.
Cast x to an int, which discards the fractional part (rounds toward 0). If x is nonnegative, this equals $\lfloor x \rfloor$.

Q.The changeSpeed() function changes not only the speed of the sound, but also its pitch. Why?

A.
Resampling changes the playback rate. Speeding up the sound raises the pitch, producing the “chipmunk” effect. More sophisticated time-stretching techniques can change speed without changing pitch. That’s the kind of technique used, for example, when you watch a lecture recording at 2× speed while keeping the speaker’s voice at a natural pitch.

Part II: Audio Collage

Now use your library methods to create an audio collage. In main(), build a single array of samples that represents your collage, then play it using StdAudio. Follow these requirements:

At least 5 WAV files. Use at least five different WAV files. Several are provided, and you may also supply your own.
Use all audio effects. The collage must use every function from the API: amplify, reverse, merge, mix, change speed, and clamp. You may also add additional effects (see ideas below).
Duration. The collage must be between 10 and 60 seconds (441,000 to 2,646,000 samples).
No command-line arguments. Do not use command-line arguments.
Valid samples. All samples passed to standard audio must be between –1 and +1.
Be creative. We plan to post your audio collages.

Q.How do I read a WAV file and extract its samples?

Call StdAudio.read(). It returns a double[] containing samples between –1 and +1.

double[] samples1 = StdAudio.read("cow.wav");

Q.How can I convert an audio file to WAV format?

Use an online conversion utility, such as Online-Convert.

Q.What is a WAV file?

A WAV file (Waveform Audio File Format) is a popular format for storing raw, typically uncompressed, audio data. For details, see the Wikipedia page.

Q.Can intermediate samples be outside the prescribed range?

Yes. Intermediate arrays may contain values outside –1 and +1, but the samples you pass to standard audio must be between –1 and +1. One way to ensure this is to call clamp() on final array.

Implementing Other Audio Effects

You may implement additional functions that produce other audio effects. Any such helper must be private. For example:

private static double[] mirror(double[] samples) {
   ...
}

Some ideas include:

normalize: rescale a sound so that all samples are between –1 and +1.
cut: extract a contiguous subarray from a sound.
trim: remove leading and trailing samples that are 0 (or nearly 0).
loop: repeat a sound a specified number of times.
mirror: concatenate a sound with its reverse.
hip–hop: speed up a sound, mirror it, then loop it.
echo / delay / reverb: add a time-delayed copy of a sound to itself, attenuated by a scale factor.
fade-in / fade-out: gradually increase or decrease the volume at the beginning or end of a sound.
crossfade: fade out the first sound while fading in the second, with an overlap.
tremolo: create a trembling effect by modulating the amplitude over time.

You may also synthesize your own sounds by generating a sine, square, triangle, or sawtooth wave with a given amplitude, frequency, and duration.

Submission

Upload all files to TigerFile :

AudioCollage.java
readme.txt
acknowledgments.txt
Any supplementary WAV files (do not submit the WAV files we provided).

If you submit supplementary WAV files, cite their source in readme.txt.

We may publish selected collages (anonymously) on the course website. Publishing is optional: if you do not wish your work to be published, indicate this in readme.txt.

Grading Breakdown

File	Points
AudioCollage.java	36
readme.txt	4
Total	40

Credits

This assignment was inspired by an audio effects programming assignment by Keith Vertanen.
The assignment name is a play on the https://en.wikipedia.org/wiki/Schoolhouse_Rock! title Conjunction Junction.

4. Recursion

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will compute Delannoy numbers using recursion and dynamic programming. You will plot a Sierpinski triangle using recursion, then create an original recursive pattern of your own design.

Getting Started

Read Sections 2.3 and 4.1 of the textbook and review the corresponding lectures and precepts.
Review the StdDraw API.
Download and unzip recursion.zip , then open the recursion project in IntelliJ.

Delannoy Numbers (brute force)

Write a program DelannoyBrute.java that takes two integer command-line arguments $m$ and $n$ and prints the Delannoy number $D(m, n)$. The Delannoy number $D(m, n)$ is the number of paths from $(0,0)$ to $(m, n)$ in an $m$-by-$n$ grid using only single steps north, east, and northeast.

For example, $D(2, 2) = 13$ because these are $13$ Delannoy paths in a 2-by-2 grid:

Use the following recurrence to compute $D(m,n)$:

$$ \displaystyle D(m, n) \; = \; \begin{cases} \;\; 1 & \text{if } m = 0 \\[.5em] \;\; 1 & \text{if } n = 0 \\[.5em] \;\; D(m-1, n) + D(m-1, n-1) + D(m, n-1) & \text{otherwise} \end{cases} $$

Organize your program according to the following public API:

public class DelannoyBrute {

    // Returns the Delannoy number D(m, n).
    public static long count(int m, int n)

    // Takes two integer command-line arguments m and n and prints D(m, n).
    public static void main(String[] args)
}

This brute-force approach is far too slow, even for moderately small $m$ and $n$.

~/Desktop/recursion> java-introcs DelannoyBrute 2 2
13

~/Desktop/recursion> java-introcs DelannoyBrute 3 2
25

~/Desktop/recursion> java-introcs DelannoyBrute 2 3
25

~/Desktop/recursion> java-introcs DelannoyBrute 3 3
63

~/Desktop/recursion> java-introcs DelannoyBrute 20 20
[takes too long]

Q.Can I assume $m \ge 0$ and $n \ge 0$?

Yes. Delannoy numbers are defined only for nonnegative integers $m$ and $n$.

Context: Delannoy numbers arise in combinatorics and computational biology. For example, $D(m,n)$ is the number of global alignments of two strings of lengths $m$ and $n$.

Delannoy Numbers (dynamic programming)

Now, write a program DelannoyMemo.java that takes two integer command-line arguments $m$ and $n$ and computes the Delannoy number $D(m, n)$ using dynamic programming (memoization). Model your solution after FibonacciMemo.java (lecture) and PalindromeMemo.java (precept). Use a private static two-dimensional array memo[][] such that memo[i][j] stores $D(i, j)$.

Organize your program according to the following API:

public class DelannoyMemo {

    // Returns the Delannoy number D(m, n).
    public static long count(int m, int n)

    // Takes two integer command-line arguments m and n and prints D(m, n).
    public static void main(String[] args)
}

Below are some sample executions. Unlike the brute-force version, the memoization version is fast enough to handle much larger values of $m$ and $n$.

~/Desktop/recursion> java-introcs DelannoyMemo 2 2
13

~/Desktop/recursion> java-introcs DelannoyMemo 3 2
25

~/Desktop/recursion> java-introcs DelannoyMemo 2 3
25

~/Desktop/recursion> java-introcs DelannoyMemo 3 3
63

~/Desktop/recursion> java-introcs DelannoyMemo 20 20
260543813797441

Analysis

Conduct the following computational experiments and measure the running time:

~/Desktop/recursion> java-introcs DelannoyBrute 2 2
~/Desktop/recursion> java-introcs DelannoyBrute 4 4
~/Desktop/recursion> java-introcs DelannoyBrute 8 8
~/Desktop/recursion> java-introcs DelannoyBrute 16 16

~/Desktop/recursion> java-introcs DelannoyMemo 2 2
~/Desktop/recursion> java-introcs DelannoyMemo 4 4
~/Desktop/recursion> java-introcs DelannoyMemo 8 8
~/Desktop/recursion> java-introcs DelannoyMemo 16 16

~/Desktop/recursion> java-introcs -Xss10m DelannoyMemo 3000 3000
~/Desktop/recursion> java-introcs -Xss10m DelannoyMemo 6000 6000
~/Desktop/recursion> java-introcs -Xss10m DelannoyMemo 12000 12000
~/Desktop/recursion> java-introcs -Xss10m DelannoyMemo 24000 24000

Based on the results, answer the following questions in readme.txt:

Which runs faster: DelannoyBrute.count() or DelannoyMemo.count() ?
Estimate the order of growth of the running time of DelannoyBrute.count(n, n) as a function of $n$?
Estimate the order of growth of the running time of DelannoyMemo.count(n, n) as a function of $n$.

Q.What does the command-line option -Xss10m do?

It increases the Java thread stack size to 10 MB (more room for deep recursion).

Q.I’m getting a java.lang.OutOfMemoryError?

Try allocating more heap memory with -Xmx. The heap is used for arrays and other objects.

`java-introcs -Xss50m -Xmx5g DelannoyMemo 24000 24000

Q.Should I worry if count() overflows a long?

No. For the analysis, you can ignore the return value ofcount() since it does not impact the running time.

Q.How should I measure the running time of count()?

Instrument your program as in precept using System.currentTimeMillis(). But be sure to remove this code before submitting.

Sierpinski Triangle

The Sierpinski triangle is a classic fractal pattern, like the H-tree from Section 2.3 of the textbook.

Order 1

Order 2

Order 3

Order 4

Order 5

Order 6

Despite its complexity, the Sierpinski triangle can be generated with a short recursive function. Your primary task is to write sierpinski(), which draws a Sierpinski triangle of order $n$ at a specified location and size. It should draw one filled, downward-pointing equilateral triangle, then call itself three times (with an appropriate base case).

Organize your program into four functions, as specified in the following API:

public class Sierpinski {

    // Height of an equilateral triangle with the given side length.
    public static double height(double length)

    // Draws a filled equilateral triangle with the given side length
    // whose bottom vertex is at (x, y).
    public static void filledTriangle(double x, double y, double length)

    // Draws a Sierpinski triangle of order n in which the largest filled
    // triangle has the given side length and bottom vertex at (x, y).
    public static void sierpinski(int n, double x, double y, double length)

    // Takes an integer command-line argument n; draws the outline of an
    // upward-pointing equilateral triangle of side length 1 with vertices
    // (0, 0), (1, 0), and (1/2, sqrt(3) / 2); and draws a Sierpinski
    // triangle of order n that fits inside the outline.
    public static void main(String[] args)

}

Geometry

The diagram below shows the outline triangle and an order-2 Sierpinski triangle inside it.

The outline triangle has vertices $(0, 0)$, $(1, 0)$, and $( 1 / 2, \sqrt{3} / 2)$.
The order-2 Sierpinski triangle has side length $1 / 2$ and bottom vertex is $(1 / 2 , 0)$.

The diagram below shows a downward-pointing equilateral triangle of side length $s$ whose bottom vertex is $(x, y)$.

The height is $h = s \sqrt{3} \; / \; 2$.
The vertices are $(x, y)$, $(x - s/2, y + h)$, and $(x + s/2, y + h)$.

Requirements

When implementing Sierpinski.java, follow these requirements:

Draw filled triangles using StdDraw.filledPolygon().
Draw the outline triangle using StdDraw.polygon().
Do not call any method in StdDraw besides polygon() and filledPolygon(). These restrictions ensure consistent grading output.
Do not add any public methods. You may add private helper methods.

Here are some sample executions. Your output should match exactly.

~/Desktop/recursion> java-introcs Sierpinski 1 



~/Desktop/recursion> java-introcs Sierpinski 2



~/Desktop/recursion> java-introcs Sierpinski 3

Q.I’m stuck. Can you suggest some steps for making steady, incremental progress?

These steps are optional. Use them as needed.

Review Htree.java from the textbook, lecture, and precept.
Create Sierpinski.java. Copy the provided API into the file, then make the minimal changes needed for it to compile.
Write the function height(). The body of this method should be a one-liner (no recursion).
Test: In main(), call height() a few times with different arguments and verify the results.
In main(), draw the outline of the initial equilateral triangle. Use height() to compute the top vertex.
Write filledTriangle(x, y, length). Again, no recursion.
Test: In main(), call filledTriangle() a few times with different arguments and verify the results.

Now implement the recursive function sierpinski(). Use an incremental approach:

Write a recursive function sierpinski() that takes one argument n, prints the value n, and then calls itself three times with the value n-1. The recursion should stop when n becomes 0.

Test: in main(), read n from the command line and call sierpinski(n). Ignoring whitespace, your output should match the output below. Make sure you understand why the values are printed in that order.

~/Desktop/recursion> java-introcs Sierpinski 0
[no output]

~/Desktop/recursion> java-introcs Sierpinski 1
1

~/Desktop/recursion> java-introcs Sierpinski 2
2
1
1
1

~/Desktop/recursion> java-introcs Sierpinski 3
3
2 1 1 1
2 1 1 1
2 1 1 1

~/Desktop/recursion> java-introcs Sierpinski 4
4
3 2 1 1 1 2 1 1 1 2 1 1 1
3 2 1 1 1 2 1 1 1 2 1 1 1
3 2 1 1 1 2 1 1 1 2 1 1 1

Modify sierpinski() so that it prints both n and the triangle side length. The method should now take two arguments: n and length.
In main(), call sierpinski(n, 0.5), since the largest filled triangle has side length 0.5.
At each recursive level, halve length.

Test: Ignoring whitespace, your program should produce the output below:

~/Desktop/recursion> java-introcs Sierpinski 0
[no output]

~/Desktop/recursion> java-introcs Sierpinski 1
1 0.5

~/Desktop/recursion> java-introcs Sierpinski 2
2 0.5
1 0.25
1 0.25
1 0.25

~/Desktop/recursion> java-introcs Sierpinski 3
3 0.5
2 0.25  1 0.125  1 0.125  1 0.125
2 0.25  1 0.125  1 0.125  1 0.125
2 0.25  1 0.125  1 0.125  1 0.125

~/Desktop/recursion> java-introcs Sierpinski 4
4 0.5
3 0.25  2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625
3 0.25  2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625
3 0.25  2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625
2 0.125  1 0.0625  1 0.0625  1 0.0625

Modify sierpinski() so that it takes four arguments: n, x, y, and length. The method should draw a Sierpinski triangle of order n with side length length and bottom vertex $(x, y)$. This is one of the more challenging steps, so sketch a few levels on paper first. Which arguments change between the three recursive calls?
Test: Your program should draw the Sierpinski triangles that match the sample executions above the Possible Progress Steps.
Remove all print statements before submitting to TigerFile.

Context: The Polish mathematician Wacław Sierpiński described this pattern in 1915, but similar motifs appear in Italian art dating back to the 13th century.

Create Your Recursive Art

In this part, you will writeArt.java, a program that produces a recursive drawing of your own design. This part is meant to be fun, but the guidelines below may help if you are not sure where to start.

A good approach is to choose a self-referential pattern as your target output. For inspiration, see this Wikipedia list of fractals. Some patterns are harder to generate than others, and some require trigonometry.

Design your drawing before you code it. Sketch your idea on paper and plan your approach. As usual, comment your code as you go.

Requirements

Art.java must take one integer command-line argument n that controls the recursion depth.
Your drawing must stay within the drawing window for all n between 1 and 6 (inclusive). The autograder will not test values of n outside this range.
You may not change the canvas size. You may change the scale.
Do not play sound.
Your drawing may be a geometric pattern, a randomized construction, or anything else that takes advantage of recursion.
Optional: You may use the Transform2D library from precept. You may also define additional transforms in Art.java (e.g., shear, reflection across the $x$- or $y$-axis, or rotation about an arbitrary point). You may copy Transform2D.java into your local project for reference, but do not submit it. We will use the Ed Lessons implementation when grading.
Organize your program into at least three functions, including main(). All functions except main() must be private.
Your artwork must genuinely rely on recursion and must be substantially different from the in-class examples (HTree, Sierpinski, NestedCircles).
To earn full credit, do at least two of the following:
- Use mutually recursive methods.
- Use multiple recursive methods.
- Use recursion that does not always recurse from level n to level n-1.
- Draw between recursive calls, not only before or after all recursive calls.
- Use the recursion level for a secondary purpose (e.g., to control the color).
- Call one or more Transform2D methods (or implement additional transforms)
- Use different StdDraw primitives than the examples (e.g., ellipses, arcs, or text).
- Use a non-constant number of recursive calls per level (e.g., conditional recursion).
- Use additional parameters that affect the recursion or drawing, such as an angle, aspect ratio, color/opacity, branching factor, or a random seed.
You may use GIF, JPG, or PNG files in your artwork. If you do, submit them with your other files. In readme.txt, clearly indicate which parts of the design are yours and which parts come from the image files.

Q.What will cause me to lose points on the artistic part?

See the rubric in the bulleted list above. In particular, you may lose points for either of the following:

Recursion is not essential. You will lose points if the same artwork can be created just as easily without recursion (for example, with a simple loop). As a rule of thumb, if your recursive call tree is essentially straight line (one recursive call per level), it is probably too simple.
Too similar to in-class examples. Even if the picture looks different, you will lose points if the code and recursion structure are essentially the same as HTree, Sierpinski, or NestedCircles. For example, the Quadricross looks different, but the code to generate it is very similar to HTree.

Student Art

Here is an animation we produced using student art:

Submission

Upload all files to TigerFile :

DelannoyBrute.java
DelannoyMemo.java
Sierpinski.java
Art.java (and optional image files)
readme.txt
acknowledgments.txt

Note: We may anonymously publish your art. If you object, please indicate so in your readme.txt when asked. We also reserve the right to pull any art, at any time, for whatever reason; by submitting your assignment, you implicitly agree with this policy.

Grading Breakdown

File	Points
DelannoyBrute.java	6
DelannoyMemo.java	6
Sierpinski.java	16
Art.java	6
readme.txt	6
Total	40

5. Object Oriented Programming

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will write programs that use and create data types. You will use Picture and Color to process images and In to read input from files.

Getting Started

Read Sections 3.1 and 3.2 of the textbook and review the corresponding lectures and precepts.
Download and unzip oop.zip , then open the oop project in IntelliJ.
Consult the Picture, Color, and In APIs as needed.

Partnering

This is a partner assignment. Partnering is optional, but we strongly recommend doing at least one partnered assignment. Pair programming improves how you communicate about code and is often faster, less error-prone, and less frustrating than working alone.

See Ed for instructions on finding a partner and creating a TigerFile group.
Follow these partnering rules.

Rectangular Tile of an Image

A rectangular tile repeats an image in a grid with a specified number of columns and rows. For example, consider the following image:

Here is a 6-by-3 rectangular tile:

Write a program Tile.java that takes three command-line arguments (the image filename, the number of columns, and the number of rows) and displays the corresponding rectangular tile.

Organize your program according to the following API:

public class Tile {

    // Returns a cols-by-rows tiling of the given image.
    public static Picture tile(Picture picture, int cols, int rows)

    // Takes three command-line arguments (the image filename, the number
    // of columns, and the number of rows), and displays a rectangular
    // tiling of the image with the given number of columns and rows.
    public static void main(String[] args)
}

Here are some sample executions:

~/Desktop/oop> java-introcs Tile heart.png 1 1


~/Desktop/oop> java-introcs Tile heart.png 6 3


~/Desktop/oop> java-introcs Tile princeton.png 1 1


~/Desktop/oop> java-introcs Tile princeton.png 5 2


~/Desktop/oop> java-introcs Tile bricks.png 1 1


~/Desktop/oop> java-introcs Tile bricks.png 9 4

Tracker

In this part, you will create a data type for a tracking device, such as an AirTag or Tile Pro. Each tracking device has a name and a location. A device may also be in lost mode, which conserves power and limits access to personal information.

Implement Tracker.java as specified by the following API:

public class Tracker {

    // Creates a tracker with the given name and initial location.
    // Lost mode is initially disabled.
    public Tracker(String name, double initialLatitude, double initialLongitude)

    // Is this tracker in lost mode?
    public boolean isInLostMode()

    // Enables lost mode on this tracker.
    public void enableLostMode()

    // Disables lost mode on this tracker.
    public void disableLostMode()

    // Moves this tracker to the given location.
    public void move(double newLatitude, double newLongitude)

    // Returns the great-circle distance between the two trackers.
    public double distanceTo(Tracker other)

    // Returns a string representation of this tracker.
    public String toString()

    // Unit tests the Tracker data type.
    public static void main(String[] args)

}

Here is some more information about the required behavior:

Test client. The main() method must call every public instance method.
String representation. Return a string consisting of the tracker name and its current location (latitude, longitude) in the following format:

"backpack (40.34386, -74.6593)"
Corner cases. You may assume that all arguments are meaningful values (e.g., not null, NaN, Double.POSITIVE_INFINITY, or Double.NEGATIVE_INFINITY).
Locations. Locations are specified using latitude and longitude in degrees. For example, Nassau Hall is located at $40.34386^\circ$ latitude and $-74.6593^\circ$ longitude.
Distance. Let $(x_1, y_1)$ and $(x_2, y_2)$ be the latitude and longitude of two points on the surface of a sphere of radius $r$. The great-circle distance between them is the length of the shortest path along the surface.

The Haversine formula gives the great-circle distance:

$$ distance \; = \; 2r \arcsin \left ( \sqrt{ \sin^2 \left ( \frac{x_2 - x_1}{2} \right ) + \cos x_1 \cos x_2 \sin^2 \left ( \frac{y_2 - y_1}{2} \right ) } \right ) $$

Use the mean Earth radius $r = \text{6,371.0}$ kilometers, which gives a good approximation.

Q.The arguments are given in degrees but Java’s trig functions use radians. What can I do?

Use code like radians = Math.toRadians(degrees) to convert from degrees to radians.

Q.Which Math library functions should I use?

Use whichever functions from Java’s Math library that you need.

Q.I’m getting the wrong result. How can I check my formula?

Create a small example that you can work out by hand. Then verify that each intermediate term matches.

Q.Can I use a different formula to compute the great-circle distance?

No. Use the formula provided. Different formulas can produce slightly different results due to floating-point rounding, especially for nearly antipodal points.

Musical Notes

Musical notes are the building blocks of music. In this assignment, each note is specified by its MIDI number and an instrument.

Implement Note.java as specified by the following API:

public class Note {

    // Creates a note with the given MIDI number and instrument name.
    public Note(int midiNumber, String instrumentName)

    // Returns this note's MIDI number.
    public int midi()

    // Returns this note's frequency.
    public double frequency()

    // Plays this note to standard audio using the associated WAV file.
    public void play()

    // Returns this note's name (e.g., C or A#).
    public String name()

    // Returns this note's octave.
    public int octave()

    // Returns a new Note transposed by delta semitones.
    public Note transpose(int delta)

    // Returns a string representation of this note.
    public String toString()

    // Unit tests the Note data type.
    public static void main(String[] args)

}

Here is additional information about the required behavior:

Corner cases. You may assume that all arguments are meaningful values (e.g., MIDI numbers are between 0 and 127).
Note names and octaves. Musicians often use scientific pitch notation, such as A4 for concert A (MIDI number 69) and C4 for middle C (MIDI number 60). Scientific pitch notation consists of a note name (C, C#, D, D#, E, F, F#, G, G#, A, A#, or B) followed by an octave number. Each octave contains 12 notes. The following (partial) table shows the mapping between the two notations:

	MIDI	pitch	MIDI	pitch	MIDI	pitch	MIDI	pitch
	48	C3	60	C4	72	C5	84	C6
	49	C#3	61	C#4	73	C#5	85	C#6
	50	D3	62	D4	74	D5	86	D6
	51	D#3	63	D#4	75	D#5	87	D#6
	52	E3	64	E4	76	E5	88	E6
…	53	F3	65	F4	77	F5	89	F6	…
	54	F#3	66	F#4	78	F#5	90	F#6
	55	G3	67	G4	79	G5	91	G6
	56	G#3	68	G#4	80	G#5	92	G#6
	57	A3	69	A4	81	A5	93	A6
	58	A#3	70	A#4	82	A#5	94	A#6
	59	B3	71	B4	83	B5	95	B6

For the sake of brevity, we use only sharp accidentals (such as A#) for the note names, and not the equivalent flat accidentals such as (B♭).

String representation. Return a string consisting of the MIDI number, the note name, the octave, and the instrument in the following format: "69 A4 (piano)".
Play. Play the WAV file whose filename is the instrument name followed by the MIDI number, with extension .wav. For example, for instrument piano and MIDI number 69, call StdAudio.play("piano/piano69.wav").
Frequency. The frequency $f$ corresponding to MIDI number $m$ is

$$ f \; = \; 440 \; \times \; 2^{\, (m - 69) \, / \, 12} $$

Transpose. Transposing a note with MIDI number $m$ by $\Delta$ semitones yields a note with MIDI number $m + \Delta$. This method must return a new Note object; it must not modify the invoking Note.
Test client. The main() method must call every public method.

Q.How can I define constants that are global to a class?

Recall from the Creating Data Types lecture that you can declare a constant using the private static final modifiers. For example: private static final int MINUTES_PER_HOUR = 60;

Q.Which Math library functions should I use?

Use whichever functions from Java’s Math library that you need. The function ``Math.pow()` is particularly useful for computing frequency.

Q.MIDI values go from 0 to 127, however the table provided only shows the relationship between MIDI and octaves from 36 to 95. Should we only focus on those MIDI values? Or are we expected to generalize the relationship for the other values as well?

You need to generalize. See the Table of note frequencies in Scientific pitch notation.

Q.There are only instrument audio files for MIDI numbers 12 through 116. Are our programs purposefully not intended to play MIDI numbers 0 through 11 and 117 through 127?

While MIDI is defined for values 0 to 127, most instruments do not support that full range. For example, a typical piano has only 88 keys, not 128. You need not worry about that. The autograder won’t call play() on a MIDI note for which there is no accompanying WAV file.

Q.Do I need conditionals to determine a note name or octave?

You can implement name() and octave() without any if statements. If you a have large multiway if statement ladder, you are probably not finding the most elegant way to implement these methods. Consider using integer division/remainder and an array.

Play These Notes

Your final task is to write a client program PlayTheseNotes.java that reads a sequence of notes from a file, transposes them by a given $\Delta$, plays them on standard audio, and prints the transposed notes to standard output.

The program takes three command-line arguments:

the name of the input file
the instrument name: piano, guitar, clarinet, or mbira
the transposed amount $\Delta$ (in semitones)

Organize your client according to the following API:

public class PlayTheseNotes {

    // Reads a sequence of notes from filename and returns them 
    // as an array, using the given instrument.
    public static Note[] read(String filename, String instrument)

    // Takes three command-line arguments (a filename, an instrument name,
    // and a transposition amount delta), reads the notes; transposes them;
    // plays them on standard audio; and prints the transposed notes.
    public static void main(String[] args)
}

Here are some details about the API:

Approach. In main(), first call read() to obtain an array of Note objects for the specified instrument. Then, in order, transpose each note by $\Delta$, play it, and print it.
Input file format. A notes file consists of a sequence of lines:
- The first line contains the number of notes.
- Each remaining line contains a MIDI number followed by a floating-point duration (in seconds), separated by whitespace.
Input files. We provide several files containing simple songs in this format. You may also create and submit your own song in a file named music.txt. It may be original or by another artist; include credits at the end of the file.
Reading from a file. Use In in to read data from a file. The In data type (Section 3.1) is an object-oriented version of StdIn.
Duration. Duration is typically used to represent note lengths (eighth notes, quarter notes, half notes, and whole notes). In this assignment, we provide only quarter notes. You must read the duration, but you will not use it when creating or playing notes.
Output. Print the transposed pitch (note name and octave) for each note as it plays. Print all pitches on one line, separated by single spaces, and end the line with a newline.

Here are some sample executions:

~/Desktop/oop> java-introcs PlayTheseNotes C4-major-scale.txt piano 0
C4 D4 E4 F4 G4 A4 B4 C5

~/Desktop/oop> java-introcs PlayTheseNotes C4-major-scale.txt guitar 0
C4 D4 E4 F4 G4 A4 B4 C5

~/Desktop/oop> java-introcs PlayTheseNotes C4-major-scale.txt piano 8
G#4 A#4 C5 C#5 D#5 F5 G5 G#5

Submission

Upload all files to TigerFile :

Tile.java
Tracker.java
Note.java
PlayTheseNotes.java
readme.txt
acknowledgments.txt
music.txt (if you created your own composition)

Grading Breakdown

File	Points
Tile.java	10
Tracker.java	10
Note.java	10
PlayTheseNotes.java	6
readme.txt	4
Total	40

6. Guitar Hero

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will simulate plucking a guitar string with the Karplus–Strong algorithm, turning your computer into a musical instrument. You will implement a ring buffer to support efficient simulation.

Getting Started

Read Section 3.3 of the textbook.
Review the partnering rules.
Download and unzip guitar.zip , then open the guitar project in IntelliJ.

Background and Approach

We model a vibrating guitar string as a discrete sequence of audio samples in a fixed-size buffer. The Karplus–Strong algorithm generates a plucked-string sound by repeatedly updating this buffer and playing the resulting samples as audio.

When a guitar string is plucked, it vibrates and produces sound. The string length determines its fundamental frequency $f$. We represent the string’s displacement using $n$ real-valued samples, where

\[ n = \left\lceil \frac{44100}{f} \right\rceil . \]

Plucking the string. To simulate the initial excitation, fill the $n$ samples with white noise: set each displacement to a random real number between $-0.5$ and $0.5$.

Simulating vibration (Karplus–String). Maintain a ring buffer of the $n$ samples. Repeatedly remove the first sample and append a new sample equal to the average of the removed sample and the new first sample, multiplied by an energy-decay factor (0.996). For example:

Q.Why does it work?

The Karplus–Strong algorithm works because of two features: feedback (via a ring buffer) and averaging.

Feedback (ring buffer). The ring buffer models a wave traveling back and forth along a string fixed at both ends. Its length sets the fundamental frequency, and the feedback reinforces that frequency and its harmonics. The energy-decay factor (0.996) models gradual energy loss.
Averaging. Each update averages adjacent samples, which acts as a gentle low-pass filter. Over time, this attenuates higher frequencies faster than lower ones, producing a realistic “plucked string” timbre.

From a mathematical-physics viewpoint, Karplus–Strong can be seen as a crude numerical approximation to the 1D wave equation.

Q.Why is the Karplus–Strong algorithm historically important?

It played a seminal role in the emergence of physically modeled sound synthesis, where a physical description of a musical instrument is used to synthesize sound electronically.

Ring Buffer

Your first task is to implement a data type that models a ring buffer. Write a class RingBuffer that implements the following API:

public class RingBuffer {

     // Creates an empty ring buffer with the given capacity.
     public RingBuffer(int capacity)

     // Returns the capacity of this ring buffer.
     public int capacity()

     // Returns the number of items currently in this ring buffer.
     public int size()

     // Is this ring buffer empty (size equals zero)?
     public boolean isEmpty()

     // Is this ring buffer full (size equals capacity)?
     public boolean isFull()

     // Adds x to the end of this ring buffer.
     public void enqueue(double x)

     // Removes and returns the item at the front of this ring buffer.
     public double dequeue()

     // Returns (but does not remove) the item at the front of this ring buffer.
     public double peek()

     // Tests this class by directly calling all instance methods.
     public static void main(String[] args)
}

Implementation strategy

Since the ring buffer has a fixed maximum capacity, you can implement it with a double[] array of that length. For efficiency, use cyclic wrap-around and maintain the following integer instance variables:

first: the index of the least recently inserted item (the front of the buffer)
last: the index one past the most recently inserted item (the end of the buffer)
size: the current number of items in the buffer

For example, here a ring buffer of size 4 with capacity 10:

Insert. Store the new item at index last, then increment last.
Remove. Take the item at index first, then increment first.
Cyclic wrap-around. If first or last reaches capacity, wrap it to 0.

Requirements

Performance. The constructor must run in time proportional to the capacity. Every other method must run in constant time.
Data structure. You must use an array as the underlying data structure. You may not use ArrayList, LinkedList, or Queue.
Corner cases. RingBuffer must throw an IllegalStateException (with a custom message) if the client calls
- dequeue() when the ring buffer is empty,
- peek() when the ring buffer is empty, or
- enqueue() when the ring buffer is full.
API. You must not add public methods.

Click here for possible progress steps.

Implementing `RingBuffer.java`

Implement RingBuffer in an incremental and iterative manner. Edit your initial RingBuffer.java so that it can compile (recall the Data.java exercise from precept). Then, implement one constructor/method at a time, together with at least one corresponding test in main(). We provide some test cases below. You should also include your own test cases in main(), such as the ones from the precept worksheet.
Define the instance variables you will need to represent a RingBuffer. Hint: review the worksheet from precept.
Implement the constructor for RingBuffer. You will need to allocate and initialize an array of doubles using the new operator. Observe that you have to do this in the constructor (and not when you declare the instance variables) because you do not know the length of the array until the constructor is called.
Test the constructor in main(). You can run this test by trying various RingBuffer sizes specified on the command line.

   // test for the constructor, based on command-line argument
   int n = Integer.parseInt(args[0]); // get the size of n from the command-line
   StdOut.printf("Test #0 - create a RingBuffer object with %d\n", n);
   RingBuffer buffer = new RingBuffer(n);

Implement capacity() and then test it:

   // test for capacity()
   StdOut.printf("Test #1 - check capacity - should be %d\n", n);
   StdOut.printf("**** Capacity is %d\n", buffer.capacity());

Implement size() and then test it:

   // test for size()
   StdOut.printf("Test #2 - check size - should be %d\n", 0);
   StdOut.printf("**** Size is %d\n", buffer.size());

Implement isFull() and enqueue() and then test them:

   // test for isFull() and enqueue()
   StdOut.printf("Test #3 - perform %d enqueues: 1.0, 2.0, ...\n", n);
   StdOut.printf("**** isFull() should be false- is %b\n", buffer.isFull());
   for (int i = 1; i <= n; i++) { // enqueue n values:  1.0, 2.0, ...
       buffer.enqueue(i);
       StdOut.printf("Test #3.%d - check size after %d enqueues- should be %d\n",
                        i, i, i);
       StdOut.printf("**** Size is %d\n", buffer.size());
   }
   StdOut.printf("**** isFull() should be true- is %b\n", buffer.isFull());

Implement isEmpty() and peek()` and then test them:

   // test for isEmpty() and peek()
   StdOut.printf("Test #4 - check peek value == %.1f\n", 1.0);
   StdOut.printf("**** isEmpty() should be false- is %b\n", buffer.isEmpty());
   double val1 = buffer.peek();
   StdOut.printf("**** Value is %.1f\n", val1);

Implement dequeue() and then test it:

   // test for dequeue()
   double val2 = buffer.dequeue();
   StdOut.printf("Test #5 - dequeue a value, then check value == %.1f and "
                      + "size == %d after a dequeue\n", 1.0, n - 1);
   StdOut.printf("**** Value is %.1f\n", val2);
   StdOut.printf("**** Size is %d\n", buffer.size());
   for (int i = 0; i < n - 1; i++) buffer.dequeue(); // dequeue everything left
   StdOut.printf("**** remove %d items and isEmpty() should be true- is %b\n",
                      n - 1, buffer.isEmpty());

Is the size of a RingBuffer equal to its capacity? The size is the number of elements currently in it; the capacity is its maximum possible size.

Is the size of a RingBuffer equal to the number of its non-zero elements? No. Some of the elements in the RingBuffer can be zero.

How do I throw a IllegalStateException with a custom message? Read the Exceptions paragraph on pages 465–466 of the textbook. Also, see the precept exercises for examples.

I get an ArrayIndexOutOfBoundsException or NullPointerException. What could cause this? Does your constructor correctly initialize all of the instance variables? Did you allocate memory for your array? Did you inadvertently re-declare an instance variable in a method or constructor, thereby shadowing the instance variable with the same name?

Guitar String

Create a data type to model a vibrating guitar string. Write a class GuitarString that implements the following API:

public class GuitarString {


    // Creates a guitar string of the given frequency, using a sampling
    // rate of 44,100. Initializes the ring buffer with ceil(44100 / frequency)
    // samples, all set to 0.0.
    public GuitarString(double frequency)

    // Creates a guitar string whose initial ring buffer values
    // are given by init[].
    public GuitarString(double[] init)

    // Returns the number of samples in the ring buffer.
    public int length()

    // Returns the current sample (the value at the front of the ring buffer)..
    public double sample()

    // Plucks this guitar string by replacing the ring buffer contents
    // with white noise (random values between -0.5 and +0.5).
    public void pluck()

    // Advances the Karplus-Strong simulation one time step.
    public void tic()

    // Tests this class by directly calling both constructors
    // and all instance methods.
    public static void main(String[] args)
}

Requirements

Data structure. Implement GuitarString using the RingBuffer data type. Do not use Stack, Queue, ArrayList, or other data types to represent a guitar string.
Karplus–Strong update. The tic() method method removes the sample at the front of the ring buffer, then adds to the end of the ring buffer the average of the removed sample and the new first sample, multiplied by the energy-decay factor (0.996).
API: you must not add public methods to the API.

Click here to show possible progress steps.

Implementing `GuitarString.java`

Again, employ an incremental/iterative implementation/testing/debugging approach. Edit your initial GuitarString.java so that it can compile (recall the Data.java exercise from precept). Then, implement one constructor/method at a time, together with at least one corresponding test in main().
Implement and test the GuitarString(double frequency) constructor, which creates a RingBuffer of the desired capacity n (the sampling rate 44,100 divided by the frequency, rounded up to the nearest integer), and initializes it to represent a guitar string at rest by enqueueing n zeros. (Use Math.ceil and cast the result to an integer.)
Implement the length() method, which returns the number of samples in the ring buffer.
Implement the sample() method, which returns the value of the item at the front of the ring buffer. Use peek().

How can I test the GuitarString(double frequency) constructor and these methods?

In main(), instantiate a few different GuitarString objects using the GuitarString(double frequency) constructor.
Invoke length() on each GuitarString object. Is the value returned by length() what you expect?
Invoke sample() on each GuitarString object. Is the value returned by sample() what you expect?

Implement and test the GuitarString(double[]) constructor, which creates a RingBuffer of capacity equal to the length n of the array, and initializes the contents of the ring buffer to the corresponding values in the array. In this assignment, this constructor’s primary purpose is to facilitate testing and debugging.

How can I test the GuitarString(double[]) constructor and these methods?

Instantiate a few different GuitarString objects using the GuitarString(double frequency) constructor.
Invoke length() on each GuitarString object. Is the value returned by length() what you expect?
Invoke sample() on each GuitarString object. Is the value returned by sample() what you expect?

Implement pluck(), which replaces the n items in the ring buffer with n random values between −0.5 and +0.5. Use a combination of RingBuffer methods including dequeue() and enqueue() to replace the buffer with values between −0.5 and 0.5. Hint: StdRandom

When generating random values between −0.5 and +0.5, should I include the two endpoints? The assignment specification does not specify, so you are free to choose whichever convention you find most convenient. In Java, we typically include the left endpoint of an interval and exclude the right endpoint. For example, StdRandom.uniformDouble(-0.5, 0.5) generates a uniformly random value in the interval $[−0.5, 0.5)$ and s.substring(i, j) returns the substring of the String s beginning at index i and ending at index j - 1.

How can I test the constructor and these methods?

Instantiate a GuitarString object.
Invoke length() and sample() on this object.
Next invoke pluck() on this object.
Next invoke length() and sample() again on each object. Are the values returned what you expect?
Try this with a few GuitarString objects.

Implement tic(). Use the enqueue(), dequeue(), and peek() methods. This method applies the Karplus–Strong update: delete the first sample from the ring buffer and adds to the end of the ring buffer the average of the deleted sample and the first sample, scaled by an energy decay factor.

How can I test the constructor and these methods?

Instantiate a GuitarString object.
Invoke length() and sample() on this object.
Next invoke tic() on this object.
Next invoke length() and sample() again on each object. Are the values returned what you expect?
Try this with a few GuitarString objects.

After you have implemented and tested each of the methods for GuitarString, run GuitarString using the test client in the Testing section.

Testing Your `GuitarString.java` Implementation

You can test your GuitarString data type using the following main(). Note - this test is not exhaustive, but it should help you debug.

// get frequency from command-line
double freq = Double.parseDouble(args[0]);


// create a GuitarString object with given frequency
StdOut.printf("Test #0 - create GuitarString obj with frequency %f\n", freq);
GuitarString gs1 = new GuitarString(freq);

// check length (sampling rate/frequency)
StdOut.printf("Test #1 - check length based on frequency %f\n", freq);
StdOut.printf("**** Length is %d\n", gs1.length());

// get one sample
StdOut.printf("Test #2 - check sample is %.1f\n", 0.0);
StdOut.printf("**** Sample is %.1f\n", gs1.sample());

// create a simple GuitarString with 4 samples
double[] samples = { -0.7, +0.8, -0.9, +0.6 };
GuitarString gs2 = new GuitarString(samples);
int len = samples.length;
StdOut.printf("Test #3 - check length based on given samples == %d\n",
              len);
StdOut.printf("**** Length is %d\n", gs2.length());

// get a sample
StdOut.printf("Test #4 - check sample is %.2f\n", samples[0]);
StdOut.printf("**** Sample is %.2f\n", gs2.sample());

// now pluck and check length
gs2.pluck();
StdOut.printf("Test #5 - check length after pluck is still == %d\n",
              len);
StdOut.printf("**** Length is %d\n", gs2.length());

// check that a random sample is  [-0.5, +0.5)
StdOut.printf("Test #6 - check sample is range [-0.5, +0.5)\n");
StdOut.printf("**** Sample is %.2f\n", gs2.sample());

// test tic and sample
GuitarString gs3 = new GuitarString(samples);
StdOut.printf("Test #7 - check sample is %.2f\n", samples[0]);
StdOut.printf("**** Sample is %.1f\n", gs3.sample());
gs3.tic();
StdOut.printf("Test #8 - check sample is %.2f\n", samples[1]);
StdOut.printf("**** Sample is %.2f\n", gs3.sample());

// test 25 tics
int m = 25; // number of tics
double[] moreSamples =
        { 0.2, 0.4, 0.5, 0.3, -0.2, 0.4, 0.3, 0.0, -0.1, -0.3 };
StdOut.printf("Test #9 - test %d tics\n", m);
GuitarString gs4 = new GuitarString(moreSamples);
for (int i = 0; i < m; i++) {
    double sample = gs4.sample();
    StdOut.printf("%6d %8.4f\n", i, sample);
    gs4.tic();
}

Run this test from the command line with some input n:

java-introcs GuitarString 440
(Test #1 - Test #8 not shown)...

Test #9 - test 25 tics
     0   0.2000
     1   0.4000
     2   0.5000
     3   0.3000
     4  -0.2000
     5   0.4000
     6   0.3000
     7   0.0000
     8  -0.1000
     9  -0.3000
    10   0.2988
    11   0.4482
    12   0.3984
    13   0.0498
    14   0.0996
    15   0.3486
    16   0.1494
    17  -0.0498
    18  -0.1992
    19  -0.0006
    20   0.3720
    21   0.4216
    22   0.2232
    23   0.0744
    24   0.2232

`Guitar Hero Client

Implement an interactive guitar player. GuitarHeroLite.java is a GuitarString client that plays guitar sounds in real time. It relies on Keyboard.java, which provides a simple GUI for reading keystrokes. When the user types p or v, the program plucks the guitar string corresponding to middle C or concert A, respectively. Since multiple sound waves add by superposition, the program plays the sum of the active string samples.

Requirements

Write a program GuitarHero that is similar to GuitarHeroLite. It must support 37 notes on the chromatic scale from 110 Hz to 880 Hz.
On each time step, sum the samples of all strings and play the result.

Use the following 37 keys (from lowest to highest note):

String keyboardString = "q2we4r5ty7u8i9op-[=zxdcfvgbnjmk,.;/' ";

This keyboard arrangement imitates a piano keyboard: the white keys are on the qwerty and zxcv rows, and the black keys are on the 12345 and asdf rows. For brevity, we name notes using sharps (e.g., A#) rather than the equivalent flats (e.g., B♭).
Character index i in keyboardString corresponds to the frequency $$ 440 \times 2^{(i − 24) / 12}\text{ } \text{ Hz} $$ Thus, 'q' is 110 Hz, 'i' is 220 Hz, and 'v' is 440 Hz.
Do not declare 37 individual GuitarString variables or write a 37-way if statement. Instead, create an array of 37 GuitarString objects and use keyboardString.indexOf(key) to determine which string to pluck.

Click here to show possible progress steps.

Implementing `GuitarHero.java`

Test GuitarString and RingBuffer using GuitarHeroLite. Which additional constructor and method does GuitarHeroLite test?
To implement GuitarHero.java, use the code in GuitarHeroLite.java as a starting point.
Create an array of GuitarString objects. Remember: to create an array of objects, you need to create the array, then you need to create each individual object.
Can you play individual notes? Do the notes have the correct frequencies? Can you play a chord?

Where do I play notes in GuitarHeroLite and GuitarHero? Be sure that the interactive Keyboard window has focus by clicking it. Then, either click the piano keys or type the keystrokes.

What happens if I call StdAudio.play(x) where x is greater than 1 or less than −1? The value is clipped – it is replaced by the value +1.0 or −1.0, respectively. This is fine and can happen when you play chords.

Why do I get a RuntimeException or an ArrayIndexOutOfBoundsException in GuitarHeroLite before I type any keystrokes? Did you forget to initialize the ring buffer to contain n zeros in your GuitarString constructor?

When I run GuitarHeroLite for the first time, I hear no sound. What am I doing wrong? Make sure you have tested with the main() provided for GuitarString. If that works, there is likely something wrong with pluck() since the main() provided for GuitarString does not test that method. To diagnose the problem, print the values of sample() and check that they become nonzero after you type the keystrokes p and v.

When I run GuitarHeroLite, I hear static (either just one click and then silence, or continual static). What am I doing wrong? It’s likely that pluck() is working, but tic() is not. The best test is to run the main() provided for GuitarString.

How do I use keyboardString.indexOf(key)? If keyboardString is a String and key is a character, then keyboardString.indexOf(key) returns the integer index of the first occurrence of the character key in the String keyboardString, or –1 if it does not occur. You can read about it in the String Javadoc page.

Can I hardwire the constants 44,100, 0.996, 440.0, and 37 in my program? As usual, we may deduct style points for using an unnamed constant, especially if you use it more than once. We recommend using SAMPLING_RATE for 44100, DECAY_FACTOR for 0.996, CONCERT_A for 440.0, and the expression keyboardString.length() for 37. You do not need to name all of the constants in the formula: \[ 440 \times 2^{(i − 24)/12} \]

Rock on! Play your GuitarHero

Here are some example tunes you can play on your GuitarHero. Try these below, and then compose some of your own:

An A major chord.
```
 i - z    i
          -
          z
```

Your browser does not support the audio element.

An A major scale.
```
i o - [ z d f v   v f d z [ - o i
```

Your browser does not support the audio element.

Type the following into your guitar to get the beginning of Led Zeppelin’s Stairway to Heaven. Multiple notes in a column are dyads and chords.

                                              w q q
        8       u       7       y             o p p
i p z v b z p b n z p n d [ i d z p i p z p i u i i

Your browser does not support the audio element.

What is this familiar melody? (S == space)

nn//SS/ ..,,mmn //..,,m //..,,m nn//SS/ ..,,mmn

Submission

Upload all required files to TigerFile :

RingBuffer.java
GuitarString.java
GuitarHero.java
readme.txt
acknowledgments.txt

Grading Breakdown

Files	Points
RingBuffer.java	12
GuitarString.java	12
GuitarHero.java	12
readme.txt	4
Total	40

Challenge

Write a program AutoGuitar.java that will automatically play music using GuitarString objects.

Requirements

You may use a .txt file and read it using the In data type.
The duration of your composition must be between 10 and 120 seconds. Since the sampling rate is 44,100 Hz, this translates to between 441,000 and 5,292,000 calls to StdAudio.play().
You may create chords, repetition, and phrase structure using loops, conditionals, arrays, and functions. Also, feel free to incorporate randomness.
You may also create a new music instrument by modifying the Karplus–Strong algorithm; consider changing the excitation of the string (from white noise to something more structured) or changing the averaging formula (from the average of the first two samples to a more complicated rule) or anything else you might imagine. See below for some ideas.

Enrichment

Click each item to expand.

Click again to collapse the answer.

Synthesizing Additional Instruments

Here are some approaches for synthesizing additional instruments. Some come from the paper of Karplus and Strong.

Harp strings: Flipping the sign of the new value before enqueueing it in tic() will change the sound from guitar-like to harp-like. You may want to play with the decay factors to improve the realism, and adjust the buffer sizes by a factor of two since the natural resonance frequency is cut in half by the tic() change.
Drums: Flipping the sign of a new value with probability 0.5 before enqueueing it in tic() will produce a drum sound. A decay factor of 1.0 (no decay) will yield a better sound, and you will need to adjust the set of frequencies used.
Guitars play each note on one of six physical strings. To simulate this you can divide your GuitarString instances into six groups, and when a string is plucked, zero out all other strings in that group.
Pianos come with a damper pedal which can be used to make the strings stationary. You can implement this by changing the decay factor on iterations where a certain key (such as Shift) is held down.
While we have used equal temperament, the ear finds it more pleasing when musical intervals follow the small fractions in the just intonation system. For example, when a musician uses a brass instrument to play a perfect fifth harmonically, the ratio of frequencies is $ 3/2 = 1.5$ rather than $2^{7/12} ∼ 1.49$). Write a program where each successive pair of notes has just intonation.

Related Work

ChucK. ChucK is a specialized programming language for real-time synthesis, composition, and performance originated by Ge Wang and Perry Cook at Princeton University. Here’s the Karplus–Strong algorithm in ChucK.
Slide flute. Here’s a description of a physically modeled slide flute by Perry Cook.
Electric guitar synthesis. In COS 325/MUS 315 Transforming Reality by Computer, Charlie Sullivan ‘87 extended the Karplus–Strong algorithm to synthesize electric guitar timbres with distortion and feedback. Here’s his Jimi Hendrix-ified version of The Star Spangled Banner.

This assignment was developed by Andrew Appel, Jeff Bernstein, Alan Kaplan, Maia Ginsburg, Ken Steiglitz, Ge Wang, and Kevin Wayne.

7. Chat126

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will build a Markov model from an English text, then simulate it to generate stylized pseudorandom text. You will use symbol tables to store and look up $k$-grams efficiently.

Getting Started

Review the textbook material on parameterized data type and generics (pages 566–570).
Read the beginning of Section 4.4 (pages 582–586) on using symbol tables in client code.
Consult the ST API API as needed.
Review the precept exercises, especially FrequencyTable.java.
Download and unzip chat126.zip , then open the chat126 project in IntelliJ.
Review the partner collaboration policy.

Background

Modern generative AI systems like ChatGPT produce text by modeling language and predicting what comes next.
In this assignment, you will build a much simpler model—an order-k Markov model—that can still generate stylized text.
Markov models are lightweight and fast to train and simulate.
Claude Shannon proposed using Markov chains to model English text in 1948; here you’ll implement a playful variant to generating stylized pseudorandom text.

Markov model of natural language

A Markov model generates text one character at a time by sampling from probability distributions estimated from an input text.

Order 0. An order-0 Markov model chooses each character independently from a fixed distribution. We fit an order-0 model by counting character frequencies in the input text. For example, if the input text is
```
g a g g g a g a g g c g a g a a a
```
then the model predicts a with probability 7/17, c with probability 1/17, and g with probability 9/17. A typical generated sequence looks like:
```
g a g g c g a g a a g a g a a g a a a g a g a g a g a a a g a g a a g ...
```
Order $k$. Independence is a poor approximation for English: characters are strongly correlated (e.g., q is usually followed by u). An order-$k$ Markov model lets the next character depend on the previous $k$ characters, called a $k$-gram. For example, if th is followed by e, i, a, and o with frequencies 60, 25, 10, and 5 (out of 100), then an order-2 model predicts that after th the next letter is e with probability 3/5, i with probability 1/4, a with probability 1/10, and o with probability 1/20.
Generating text. To generate text from an order-$k$ model, start with an initial $k$-gram from the input. Repeatedly sample the next character according to the distribution for the current $k$-gram, append it to the output, and update the $k$-gram by dropping its first character and adding the sampled character.
Efficiency. A brute-force implementation that repeatedly searches the input text to find what follows the current $k$-gram is too slow for large inputs. Instead, we will preprocess the text and store the necessary counts so that we can sample the next character efficiently.

Q.What did Shannon propose?

in his landmark paper A Mathematical Theory of Communication. That idea helped launch information theory and remains influential today. Shannon described a manual method for generating text from a Markov model: repeatedly find an occurrence of the current $k$-gram in a book and record the character that follows it. Your task is to automate this process in an efficient manner. A direct brute-force implementation becomes too slow on large input texts.

Markov Language Model

Write a data type MarkovLM to represent a Markov model of order $k$ based on a given input text. Implement the following API:

public class MarkovLM {

    // Creates a Markov language  model of order k from the given text.
    public MarkovLM(String text, int k)

    // Returns the order k of the model.
    public int order()

    // Returns a string representation of the model (see below).
    public String toString()

    // Returns the number of times the k-gram occurs in the input text.
    public int freq(String kgram)

    // Returns the number of times character c follows the k-gram
    // in the input text.
    public int freq(String kgram, char c)

    // Returns a character chosen at random, with probability proportional
    // to the number of times each character follows the k-gram in
    // the input text.
    public char predictNext(String kgram)

   // Tests this class by directing calling all instance methods.
    public static void main(String[] args)
}

API. You must follow the prescribed API, with the given signatures. Do not add public methods.
Constructor. You may assume that the input text contains only ASCII characters (char values between 0 and 127).
String representation. Return a string representation of the model as illustrated below:
```
aa: a 1 g 1
ag: a 3 g 2
cg: a 1
ga: a 1 g 4
gc: g 1
gg: a 1 c 1 g 1
```
Include one line for each $k$-gram that appears in the text. Each line contains the $k$-gram, followed by a colon; followed by each character that appears in the text immediately after that $k$-gram and the number of times it appears, with a space between each component. The $k$-grams must appear in lexicographic order, and the characters for each $k$-gram must appear in ASCII order.
Predict next character. The predictNext() method must return a character that follows the given $k$-gram in the text, chosen at random with probability proportional to the number of times that character follows the $k$-gram. For example if "ga" appears 5 times—once followed by a and four times followed by g—then predictNext("ga") returns a with probability 1/5 and g with probability 4/5, independently on each call.
Circular string. To avoid dead ends, treat the input text as a circular string: the first character succeeds the the last character. For example, if $k = 2$ and the input text is "gagggagaggcgagaaa", then the model counts wrap-around $k$-grams as well. In particular, the frequency of "ag" is 5 (not 4) because one occurrence crosses the end of the string.

Corner cases. Throw appropriate exceptions for invalid arguments.
- In freq() and predictNext(), throw an IllegalArgumentException if kgram is not of length $k$.
- In predictNext(), throw an IllegalArgumentException if kgram does not appear in the input text.
- We will not test your data type with null arguments.
Performance requirements. Assume $k$ is a fixed constant. Let $n$ be the number of characters in the input text.
- The constructor must run in time proportional to $n \log n$ (or better)
- order() must run in constant time
- predictNext() and the two freq() methods must run in time proportional to $\log n$ (or better)
To meet these requirements, use one or more symbol tables with $k$-grams as keys. and values that support efficient implementation of the two freq() methods.

Q.What is the worst-case running time for common symbol-table operations?

For the ST and java.util.TreeMap classes, the worst-case running time of put(), get() and contains()/containsKey() is $\Theta(log n)$.

Q.How do I extract a substring of a given string?

Use substring(). For example, s.substring(i, i + k) returns the k-character substring of the string s, starting at i. Note that it includes the left endpoint but excludes the right endpoint.

Q.How do I generate a random index with probability proportional to its weight?

Review StdRandom.discrete(), which is overloaded:

One takes a floating-point array probabilities[] and returns index i with probability equal to probabilities[i]. The array entries must be nonnegative and sum to 1.
The other takes an integer array frequencies[] and returns index i with probability proportional to frequencies[i]. The array entries must be nonnegative and not all zero.

Text Generator

A Markov chain is a stochastic process in which the next state depends only on the current state. For text generation, the state is a $k$-gram. At each step, choose the next character at random using the probabilities from the Markov model, then form the next state by appending that character and dropping the first character of the $k$-gram.

For example, if the current state is "ga" in the order-2 model above, then the next character is a with probability $1/5$ and g with probability $4/5$. One possible trajectory (nine transitions) is:

$$ ga \rightarrow ag \rightarrow gg \rightarrow gc \rightarrow cg \rightarrow ga \rightarrow ag \rightarrow ga \rightarrow aa \rightarrow ag $$

Treating the input text as a circular string ensures that the Markov chain never gets stuck in a state with no possible next character.

To generate text from an order-$k$ model, start in the initial state given by the first $k$ characters of the input text. Then perform $T - k$ transitions, printing the sampled character at each step. For example, if $k = 2$ and $T = 11$, the following trajectory could produce the output gaggcgagaag:

trajectory:  ga --> ag --> gg --> gc --> cg --> ga --> ag --> ga --> aa --> ag
output:      ga      g      g      c      g      a      g      a      a      g

Write a client program Chat126 that:

takes two integer command-line arguments $k$ and $T$;
reads the input text from standard input;
builds an order-$k$ Markov model from the input text; and
prints $T$ characters generated by simulating a trajectory through the corresponding Markov chain, starting from the first $k$ characters of the input text..

~/Desktop/chat126> more input17.txt
gagggagaggcgagaaa

~/Desktop/chat126> java-introcs Chat126 2 11 < input17.txt
gaggcgagaag

~/Desktop/chat126> java-introcs Chat126 2 11 < input17.txt
gaaaaaaagag

~/Desktop/chat126> java-introcs Chat126 0 50 < input17.txt
gaaagaacagcagacgacggaagaaggaggaaaaggaggggaggggggag

Corner cases. You may assume that the length of the text is at least $k$ and $T \geq k$.
Performance requirement. If $k$ is a fixed constant, then the running time of Chat126 must be proportional to $n \log n + T \log n$ (or better), where $(n$ is the number of characters in the input text and $(T$ is the number of characters in the output.

Click here to show possible progress steps for MarkovLM.

Implementing `MarkovLM.java`

Review precept exercises, especially FrequencyTable, as well as IntegerSort.java.
Create one or more instance variables to support the two freq() methods. One strategy is to maintain two symbol tables—one for the one-argument freq() method and one for the two-argument freq() method.

For each $k$-gram (a string), the first symbol table tells you how many times it appears in the text (an integer).
For each $k$-gram (a string), the second symbol table tells you how many times each ASCII character succeeds the $k$-gram in the text (an array of 128 integers).
Character (i.e., char values) can be used as an index into an array. In Java, characters are 16-bit (unsigned) integers; they are promoted to int values in any context that expects one. For example, array['c'] is equivalent to array[99] because the ASCII code for 'c' is 99.
You can avoid hardwiring the constant 128 by using a static instance variable: private static final int ASCII = 128;
This code should appear inside the class block, but before any instance variables or methods. By convention, constant variable names should be ALL_UPPERCASE. The static modifier means that every instance method will refer to the same variable (as opposed to instance variables, for which there is one variable per object); the final modifier means that you can’t change its value, once initialized.

Write the constructor to create the circular version of the input text. Then initialize and populate your symbol tables, using the symbol table methods contains(), get(), and put(). This will be a substantial amount of code, relative to the other methods in this class.

Do not save the original text (or the circular text) as an instance variable because no instance method will need this information after the symbol table is initialized.
There are a number of approaches for emulating the circular text. One way is to append the first $k$ characters of the input text to the input text.

Test: In the main(), try creating some MarkovLM objects. For example:

String text1 = "banana";
MarkovLM model1 = new MarkovLM(text1, 2);
...
String text2 = "gagggagaggcgagaaa";
MarkovLM model2 = new MarkovLM(text2, 2);

Write the toString() method. Use an enhanced for loop to access each key–value pair in your symbol table and a StringBuilder to generate the required String value. See the FrequencyTable.java from precept for an example.

Test the constructor and toString() method: This can help you debug small test cases. In the main(), print some MarkovLM objects. For example:

String text1 = "banana";
MarkovLM model1 = new MarkovLM(text1, 2);
StdOut.println(model1);
...
String text2 = "gagggagaggcgagaaa";
MarkovLM model2 = new MarkovLM(text2, 2);
StdOut.println(model2);

Sample output from the code snippet above:

ab: a 1
an: a 2
ba: n 1
na: b 1 n 1

aa: a 1 g 1
ag: a 3 g 2
cg: a 1
ga: a 1 g 4
gc: g 1
gg: a 1 c 1 g 1

You can insert a line break in a String by using the characters \n. For example, if you print "ab\ncd", ab and cd will appear on separate lines.

Write the order() method. This should be a one-liner.
Using the symbol table instance variables, write the two freq() methods.
Use the main() provided above to test your code before continuing. In the main method, you should add more tests of the constructor, order(), and freq() methods.
Write the predictNext() method. To generate a random character with probability proportional to its frequency you may call either of the two StdRandom.discrete() methods.
It may not be obvious from your final results whether predictNext() is working as intended, so be sure to test it thoroughly. Next, test your complete MarkovLM data type before continuing. (See Testing Your MarkovLM.java Implementation below.)

Click here to show possible progress steps for Chat126.

Implementing `Chat126.java`

Read in k and T from the command line; read the input text from standard input.
Create a MarkovLM object of order k using the input text.
To generate a trajectory of length T, use the first k characters in the input text as the initial $k$-gram and print the initial $k$-gram. Then, repeatedly generate and print a new random character according to the Markov model and update the $k$-gram to store the last k characters printed.
Make sure to test your program on large inputs (we provide several), large outputs, and different values of k.
Some FAQs:

Should my program generate a different output each time I run it? Yes.
How can I read in the input text from standard input? Use StdIn.readAll(). Do not remove whitespace.
My random text ends in the middle of a sentence. Is that OK? Yes, that’s to be expected.
After executing the program, the command prompt appears on the same line as the random text. Is that OK? Yes. It’s because the random text does not end with a newline character. If you want to add a call to StdOut.println() at the end of your program, that’s fine—we promise not to deduct.
What does this message mean: The local variable ‘T’ must start with a lowercase letter and use camelCase? Since T is a constant, you should declare it as final, e.g., final int T = .... Alternatively, you can rename the constant using a variable name that is more than one character.
For which values of $k$ should my program work? It should work for all well defined values of $k$, from 0 up to, and including, the length of the input text. As $k$ gets larger, your program will use more memory and take longer.
My program is slow when $T$ is large because I am concatenating the $T$ characters, one at a time, to form string of length $T$). What else can I do? Do you need to form the entire string? Why not print the characters, one at a time, as you generate them?
I get an OutOfMemoryException. How do I tell Java to use more of my computer’s memory? Depending on your operating system, you may have to ask the Java Virtual Machine for more main memory beyond the default. The 500m means 500MB, and you should adjust this number depending on the size of the input text.
```
java-introcs -Xmx500m Chat126 7 1000 < input.txt
```

Testing

Testing Your `MarkovLM.java` Implementation

We provide a main() as a start to your testing. You will need to provide more tests.

public static void main(String[] args) {
   String text1 = "banana";
   MarkovLM model1 = new MarkovLM(text1, 2);
   StdOut.println("freq(\"an\", 'a')    = " + model1.freq("an", 'a'));
   StdOut.println("freq(\"na\", 'b')    = " + model1.freq("na", 'b'));
   StdOut.println("freq(\"na\", 'a')    = " + model1.freq("na", 'a'));
   StdOut.println("freq(\"na\")         = " + model1.freq("na"));
   StdOut.println();

   String text3 = "one fish two fish red fish blue fish";
   MarkovLM model3 = new MarkovLM(text3, 4);
   StdOut.println("freq(\"ish \", 'r') = " + model3.freq("ish ", 'r'));
   StdOut.println("freq(\"ish \", 'x') = " + model3.freq("ish ", 'x'));
   StdOut.println("freq(\"ish \")      = " + model3.freq("ish "));
   StdOut.println("freq(\"tuna\")      = " + model3.freq("tuna"));
}

If your method is working properly, you will get the following output:

java-introcs MarkovLM
freq("an", 'a')    = 2
freq("na", 'b')    = 1
freq("na", 'a')    = 0
freq("na")         = 2

freq("ish ", 'r') = 1
freq("ish ", 'x') = 0
freq("ish ")      = 3
freq("tuna")      = 0

To test predictNext(), write a loop that calls predictNext() repeatedly, and count how many times a particular character is returned. For example, with model1 above, predictNext("na") should return b about one-half of the time; with model3 above, predictNext("fish") should return o about one-quarter of the time.

Of course, you should try to define and test other models.

Generating Text Using Different Inputs and Orders

Once you get the program working, test it on different inputs of different sizes and different orders. Does increasing the order have the effect you expect? Try your model on something that you have written or some other text you know well. Make sure to test both long inputs (we provide several) and long outputs. Here are a couple of examples (click on the ► icon to expand to expand/collapse):

Example 1 Input: Speech to the Class of 2018

Good afternoon and welcome to Opening Exercises. What a special pleasure it is to greet Princetons Great Class of 2018! I also offer a warm welcome to our new graduate students, faculty and staff members, and all of you who are returning to campus after the summer.

Today we carry on a tradition that dates back at least to 1802, when Nassau Hall was the site of an opening exercise for Princeton students. The event switched to other sites before moving in 1929 to the University Chapel, where we gather today. Todays interfaith ceremony is far different from the Christian services that greeted students in 1929, but the chapels soaring architecture and inspirational spaces continue to invite all of us, whatever our religious or ethical traditions might be, to reflect on the larger purposes that should guide our community as we begin another year on this glorious campus.

Today you join the ranks of students who have left their marks on the Princeton campus and the world for generations through their intellect, creativity and passion. You, the 1,312 members of the Class of 2018, are an extraordinarily accomplished, inspiring and diverse group. You hail from 46 states, as well as the District of Columbia. You come from 50 countries outside of the United States from Chile to the Czech Republic, from Iceland to India, from Nigeria to New Zealand. You grew to become upstanding, compassionate citizens in Happy Valley, Oregon, and Niceville, Florida. You weathered the ups and downs of life in Boiling Springs, Pennsylvania, and Frostburg, Maryland. And you learned to appreciate the lyrical majesty of language in Ho Ho Kus, New Jersey, and Oologah, Oklahoma.

Example 1 output: random Eisgruber, using order 7 model

java-introcs Chat126 7 798 < opening-exercises.txt

Good afternoon and welcome to a universities around you here.

I often ask Princeton is a truly global institution. As scholars who matter most to you. And you here.

I often ask Princeton you have come to our social natures, and, more specifically, with drums and choirs and distinguished teachers, whose contributions will become upstanding.

This Universitys GREAT CLASS OF 2018! Welcome new members play indispensable roles in helping our Universitys GREAT CLASS OF 2018! I also offer insignificant, or puzzling, or uninteresting, or unsympathetic may turn out to be discourse in all disciplines here as rich with meaningful, not just of any story, can make it easy to feel without knowing exactly what he was destined to appreciate the lyrical majesty of language in Ho Ho Kus, New Jersey, and

Example 2 Input: As you Like It, Act 2

[Enter DUKE SENIOR, AMIENS, and two or three Lords, like foresters]

DUKE SENIOR Now, my co-mates and brothers in exile, Hath not old custom made this life more sweet Than that of painted pomp? Are not these woods More free from peril than the envious court? Here feel we but the penalty of Adam, The seasons’ difference, as the icy fang And churlish chiding of the winter’s wind, Which, when it bites and blows upon my body, Even till I shrink with cold, I smile and say ‘This is no flattery: these are counsellors That feelingly persuade me what I am.’ Sweet are the uses of adversity, Which, like the toad, ugly and venomous, Wears yet a precious jewel in his head; And this our life exempt from public haunt Finds tongues in trees, books in the running brooks, Sermons in stones and good in every thing. I would not change it.

AMIENS Happy is your grace, That can translate the stubbornness of fortune Into so quiet and so sweet a style.

DUKE SENIOR Come, shall we go and kill us venison? And yet it irks me the poor dappled fools, Being native burghers of this desert city, Should in their own confines with forked heads Have their round haunches gored.

Example 2 output: random Shakespeare, using order 6 model

java-introcs Chat126 7 1135 < as-you-like-it.txt

DUKE SENIOR Now, my co-mates and thus bolden’d, man, how now, monsieur Jaques, Unclaim’d of his absence, as the holly! Though in the slightest for the fashion of his absence, as the only wear.

TOUCHSTONE I care not for meed! This I must woo yours: your request than your father: the time, That ever love I broke my sword upon some kind of men Then, heigh-ho! sing, heigh-ho! sing, heigh-ho! sing, heigh-ho! unto the needless stream; ‘Poor deer,’ quoth he, ‘Call me not so keen, Because thou the creeping hours of the sun, As man’s feasts and women merely players: Thus we may rest ourselves and neglect the cottage, pasture? Enter DUKE FREDERICK Can in his time in my heartily, And have me go with your fortune In all this fruit Till than bear the arm’s end: I will through Cleanse the uses of the way to look you. Know you not, master, Sighing like upon a stone another down his bravery is not so with his effigies with my food: To speak my mind, and inquisition And unregarded age in corners throat, He will come hither: He dies that hath engender’d: And you to the bed untreasured of the brutish sting it.

Submission

Upload all required files to TigerFile :

MarkovLM.java
Chat126.java
readme.txt
acknowledgments.txt

Include in your readme.txt two of the most entertaining language-modeling fragments that you discover.

Grading breakdown

Files	Points
MarkovLM.java	26
Chat126.java	10
readme.txt	4
Total	40

Challenges

Challenge for the bored 1.

The current assignment only handles ASCII characters. However, many text collections use Unicode characters, such as those with diacritic marks (e.g.: ā ă ą ç é ē î ï ĩ í ĝ ġ ń ñ ö š ŝ ś û ů ŷ Á Ç) and other characters (e.g., 😀 ł đ ħ œ ⺆).

Extend your solution so that it replaces and/or removes such Unicode characters in your text. Hint - use the API provided in the ToASCII.java class. Try your solution on a text that contains Unicode.

Challenge for the bored 2.

Extend your solution to handle Unicode text, not just ASCII.

Challenge for the bored 3.

Imagine you receive a message where some of the characters have been corrupted by noise. We represent unknown characters by the ~ symbol (and assume the character ~ does not appear in the original text). Devise a scheme based on the Markov model to determine the most likely value for each corrupted character. Assume unknown characters are at least $k$ characters apart (and appear at least $k$ characters away from the start and end of the message). Test your new method by writing a client program FixCorrupted.java that takes as arguments the model order and the noisy string. The program prints the most likely original string:

Original:  it was the best of times, it was the worst of times.
Noisy:     it w~s th~ bes~ of tim~s, i~ was ~he wo~st of~times.

java-introcs FixCorrupted 4 "it w~s th~ bes~ of tim~s, i~ was ~he wo~st of~times." < wiki_100k.txt 
it was the best of times, it was the worst of times.

Enrichment

Click each item to expand.

Click again to collapse the answer.

What is the relationship between Markov models and LLMs for generating text?

We actually asked ChatGPT this question, and here’s its response (slightly edited):
Markov models and Large Language Models (LLMs) are both used for generating text but operate on different principles.
- Markov Models: These are based on the Markov property, which states that the future state of a system depends only on its present state, not on the sequence of events that preceded it. In the context of text generation, a Markov model predicts the next word in a sequence based current k-gram.
- Large Language Models (LLMs): These are more sophisticated models based on neural networks, particularly variants like GPT (Generative Pre-trained Transformer) models. LLMs leverage deep learning techniques to capture complex patterns and dependencies in text data. They are trained on large corpora of text and can generate coherent and contextually relevant sequences of text. Unlike Markov models, LLMs do not rely solely on fixed-length context windows but instead learn contextual representations of words and phrases based on their entire input sequence.
While both Markov models and LLMs can generate text, LLMs generally produce more fluent and contextually appropriate text due to their ability to capture long-range dependencies and contextual nuances. However, Markov models are simpler and more interpretable, making them suitable for certain text generation tasks, especially when computational resources are limited.

What is the origin of the Markov text generator?

It was first described by Claude Shannon in 1948. The first computer version was apparently written by Don P. Mitchell, adapted by Bruce Ellis, and popularized by A. K. Dewdney in the Computing Recreations section of Scientific American. Brian Kernighan and Rob Pike revived the program in a University setting and described it as an example of design in The Practice of Programming. The program is also described in Jon Bentley’s Programming Pearls.

What else can I do with a random text generator?

One former COS 126 student recited its output during the Frist filibuster.

Some other interesting topics.

We are implementing the model Shannon described in his landmark paper. But the one reads until this letter is encountered method in his quote on the assignment page is, ironically, not a statistically accurate example of his model. If we run your program with input wawawaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaawy then w should be followed by a 75% of the time, while the read until model will follow w with a only 15% of the time. What would be involved in simulating this other model? Which one do you think gives more realistic text?
Here’s a website that generates pseudo-random computer science papers. It uses something called a context-free grammar instead of a Markov chain, but otherwise is similar in spirit to what you are doing on this assignment.
Here are Garfield comics generated by a Markov chain.

8. Image Classifier

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will implement the perceptron algorithm and use it to classify images, then evaluate its accuracy.

Getting Started

Review the partnering rules.
Read/scan this entire project description before starting to code. This will provide a big picture before diving into the assignment!
Review the ML lectures and precept exercises.
Download and unzip classifier.zip , then open the classifier project in IntelliJ.
Consult the Picture and Color APIs as needed.

Context

Classification is a core task in machine learning (ML): given an input (such as an image), predict which category it belongs to. For a familiar example of digit classification, try this web app:

Derived from https://github.com/DenseInL2/webcnn

Training and testing. In this assignment, you will implement the perceptron algorithm for handwritten digit classification using supervised learning. Supervised learning as two phases:

Training: learn a function that maps inputs to labels from labeled examples. For digit recognition, the training set contains 60,000 grayscale images (inputs) and their corresponding digits (labels). Here is a small subset:
Testing: evaluate the learned function by predicting labels for unseen inputs (not used for training).

Binary vs. multiclass classification. In binary classification, we assign each image to one of two classes (e.g., “6” vs. “not 6”). By convention, we use labels $+1$ (positive) and $-1$ (negative). In multiclass classification, we assign each image to one of $m$ classes, labeled $0, 1, …, m-1$. For handwritten digits, $m = 10$ and class $i$ corresponding to digit $i$.

Test error rate. Typically, the algorithm makes some prediction errors (e.g., predicting 9 when the handwritten digit is 6). An important quality metric is the test error rate: the fraction of test inputs that are misclassified. It measures how well the learned classifier generalizes from the training data to new inputs.

Perceptrons. A perceptron is a simplified model of a biological neuron. It takes an input vector vector $x = x_0, x_1, \ldots, x_{n-1}$ of $n$ real numbers and outputs a binary label $+1$ or $-1$. A perceptron is defined by a weight vector $w = w_0, w_1, \ldots, w_{n-1}$. It computes the weighted sum

$$ S = (w_0 \cdot x_0) + (w_1 \cdot x_1) + \cdots + (w_{n-1} \cdot x_{n-1}) $$

and outputs $+1$ if the sum is positive, and $-1$ otherwise.

For the handwritten-digit task, we train a perceptron to output $+1$ for images of a chosen target digit and $-1$ for all other digits. The input vector $x$ contains the grayscale values of each pixel in the image, and the weight vector $w$ is computed during training, as described in the next paragraph.

Perceptron algorithm. How do we choose the weight vector $w$ so that the perceptron makes accurate predictions? The key idea is to use labeled training data to refine the weights incrementally. Initialize all weights to 0, then process the training examples one at a time. For each labeled input vector $x$, there are three cases:

Correct prediction: The perceptron predicts the correct label $+1$ or $-1$. Leave $w$ unchanged.
False positive: The true label is $-1$ but the perceptron predicts $+1$. Update $w$ by subtracting $x$: $$ \text{for each } j, \text{ } w^\prime_j=w_j - x_j $$
False negative: The true label is $+1$ but the perceptron predicts $-1$. Update $w$ by adding $x$: $$ \text{for each } j, \text{ } w^\prime_j=w_j + x_j $$

Intuitively, we push $w$ away from false positives and toward false negatives.

Example. Here is an example trace of the perceptron algorithm using four labeled inputs, each of length $n = 3$. In this example, an input $x$ has a label $+1$ if and only if $x_0 \le x_1 \le x_2$; otherwise it has a label $-1$.

Perceptron Data Type

Create a data type that represents a perceptron by implementing the following API:

public class Perceptron {

    // Creates a perceptron with n input and all weights initialized to 0.
    public Perceptron(int n)

    // Returns the number of inputs n.
    public int numberOfInputs()

    // Returns the weighted sum (dot product) of the weight vector and x. 
    public double weightedSum(double[] x)

    // Predicts the binary label for the input vector x.
    // Returns +1 if the weighted sum is positive; otherwise returns -1.
    public int predict(double[] x)

    // Trains this perceptron on the input vector x with the given
    // binary label (+1 or -1). Updates the weight vector according
    // to the perceptron training rule.
     public void train(double[] x, int binaryLabel)

    // Returns a string representation of the weight vector, with the
    // individual weights separated by commas and enclosed in parentheses.
    // Example: (2.0, 1.0, -1.0, 5.0, 3.0)
    public String toString()

    // Tests this class by directly calling all instance methods.   
    public static void main(String[] args)
}

Corner cases. You may assume that all arguments to the constructor and instance methods are valid. For example, you may assume that every binary label is either $+1$ or $-1$, every input vector $x$ has length $n$, and $n \ge 1$.

Q.I’m stuck on Perceptron.java. Can you suggest some steps for making steady, incremental progress?

These steps are optional. Use them as needed.

Implementing `Perceptron.java`

Implement the Perceptron() constructor and the method numberOfInputs().
- Define two instance variables: an integer n and real-valued array weights[].
- Initialize the instance variables.
- Test: In main(), create a few Perceptron objects and print the number of inputs for each one.
Implement the toString() method.
- Use a loop to concatenate the individual weights.
- Test: In main(), print the Perceptron objects you created in Step 1.
Implement the weightedSum() method.
- Use a loop to compute the weighted sum.
- Test: In main(), call weightedSum() with different arguments and print the results.
Implement the predict() method by calling weightedSum().
Implement the train() method. The train() method should call predict().
Test: Use the code in the Testing section below to test predict() and train().
Submit to TigerFile for additional testing.

Testing `Perceptron.java`

The Java code below trains a Perceptron on four input vectors (each of length three), following the example in the assignment specification. After Tests 1–3 pass, implement Tests 4–6.

// Create a Perceptron with n inputs.
int n = 3;
Perceptron perceptron = new Perceptron(n);
StdOut.printf("Test 1: Perceptron(%d)\n", n);
StdOut.println("  expect: " + "(0.0, 0.0, 0.0)");
StdOut.println("  result: " + perceptron);

StdOut.println("Test 2: numberOfInputs()");
StdOut.println("  expect: " + n);
StdOut.println("  result: " + perceptron.numberOfInputs());

double[] training1 = {  3.0, 4.0,  5.0 };  // +1 (yes)
double[] training2 = {  2.0, 0.0, -2.0 };  // -1 (no)
double[] training3 = { -2.0, 0.0,  2.0 };  // +1 (yes)
double[] training4 = {  5.0, 4.0,  3.0 };  // -1 (no)

StdOut.println("Test 3a: weightedSum(3.0, 4.0, 5.0)");
StdOut.println("  expect: " + 0.0);
StdOut.println("  result: " + perceptron.weightedSum(training1));

StdOut.println("Test 3b: predict(3.0, 4.0, 5.0)");
StdOut.println("  expect: " + -1);
StdOut.println("  result: " + perceptron.predict(training1));

StdOut.println("Test 3c: train(3.0, 4.0, 5.0, +1)");
perceptron.train(training1, +1);
StdOut.println("  expect: " + "(3.0, 4.0, 5.0)");
StdOut.println("  result: " + perceptron);

// TODO: Implement Tests 4–6, following the pattern in Test 3.
// Test 4: weightedSum(training2), predict(training2), train(training2, -1)
// Test 5: weightedSum(training3), predict(training3), train(training3, +1)
// Test 6: weightedSum(training4), predict(training4), train(training4, -1)

Do not move onto MultiPerceptron until Perceptron is working properly.

Multiclass Classification

In the previous section, we used a single perceptron for a binary classification task. For a multiclass problem with $m$ classes, we use an array of $m$ perceptrons, one per class. Perceptron $i$ is trained to answer the binary question: is this image the digit $i$?

We train each perceptron independently and combine their outputs to make a multiclass prediction.

Multiclass training. Initialize all $m$ perceptrons with weight vectors of $0$. Then process the labeled training inputs one at a time. For an input vector $x$ with class label $i$
- Train perceptron $i$ on $x$ with binary label $+1$
- Train each of the other $m-1$ perceptrons on $x$ with binary label $-1$
In other words, for perceptron $k$, examples of class $k$ are positive and all other examples are negative.
Multiclass prediction. To classify an input vector $x$, compute the weighted sum for each of the $m$ perceptrons. Predict the class label of the perceptron with the largest weighted sum. We choose exactly one class, even if all weighted sums are negative.

This one-vs-all strategy decomposes a multiclass classification task into $m$ binary classification tasks. In computer science, this kind of decomposition is called a reduction; reductions like this are used throughout machine learning.

Example. Here is an example of a multi-perceptron with $m = 2$ classes and $n = 3$ inputs.

MultiPerceptron Data Type

Create a data type that represents a multi-perceptron by implementing the following API:

public class MultiPerceptron {

    // Creates a multi-perceptron with m classes and n inputs.
    public MultiPerceptron(int m, int n) 

    // Returns the number of classes m.
    public int numberOfClasses() 

    // Returns the number of inputs n (length of the feature vector).
    public int numberOfInputs() 

    // Predicts the class label for input vector x.
    public int predictMulti(double[] x)

    // Trains this multi-perceptron on input vector x
    // with the given class label (between 0 and m-1).
    public void trainMulti(double[] x, int classLabel) 

    // Returns a string representation of this multi-perceptron, with
    // the string representations of the perceptrons separated by commas
    // and enclosed in parentheses.
    // Example with m = 2 and n = 3: ((2.0, 0.0, -2.0), (3.0, 4.0, 5.0))
    public String toString() 

    // Tests this class by directly calling all instance methods.
    public static void main(String[] args) 
}

Here are some additional details about the API:

Ties. If two (or more) perceptrons tie for the largest weighted sum in predictMulti(), return the index of one of them.
Corner cases. You may assume that the arguments to the constructor and instance methods are valid. For example, you may assume that every class label is an integer between $0$ and $m-1$, every input vector $x$ has length $n$, and $m \ge 1$ and $n \ge 1$.

Q.I’m stuck on MultiPerceptron. Can you suggest some steps for making steady, incremental progress?

Implementing `MultiPerceptron.java`

Implement the MultiPerceptron() constructor and the methods numberOfClasses() and numberOfInputs().
- Define three instance variables:
  - an integer m (number of classes)
  - an integer n (length of the input feature vector)
  - an array of Perceptron objects perceptrons[]
- Initialize the instance variables.
- Test: In main(), create a few MultiPerceptron objects and print the number of classes and inputs for each object.
Implement the toString() method.
- Use a loop to concatenate the Perceptron objects.
- Test: In main(), print the MultiPerceptron objects from Step 1.
Implement the predictMulti() method.
Implement the trainMulti() method.
Test: Test predictMulti() and trainMulti() with the code in the Testing section (below).
Submit to TigerFile for additional testing.

Testing `MultiPerceptron.java`

The Java code below creates a MultiPerceptron object, trains the MultiPerceptron on four input vectors (each of length three) and then tests the MultiPerceptron on two input vectors (of length three) following the examples in the assignment specification.

// Create a MultiPerceptron with m classes and n inputs.
int m = 2;
int n = 3;
MultiPerceptron mp1 = new MultiPerceptron(m, n);

// Constructor Test 1: create a MultiPerceptron and print it.
StdOut.printf("Constructor Test 1: MultiPerceptron(%d, %d)%n", m, n);
StdOut.println("  expect: ((0.0, 0.0, 0.0), (0.0, 0.0, 0.0))");
StdOut.println("  result: " + mp1);

// Constructor Test 2: check the number of classes.
StdOut.println("Constructor Test 2: numberOfClasses()");
StdOut.println("  expect: " + m);
StdOut.println("  result: " + mp1.numberOfClasses());

// Constructor Test 3: check the number of inputs.
StdOut.println("Constructor Test 3: numberOfInputs()");
StdOut.println("  expect: " + n);
StdOut.println("  result: " + mp1.numberOfInputs());

// Training data.
double[] training1 = {  3.0, 4.0,  5.0 };  // class 1
double[] training2 = {  2.0, 0.0, -2.0 };  // class 0
double[] training3 = { -2.0, 0.0,  2.0 };  // class 1
double[] training4 = {  5.0, 4.0,  3.0 };  // class 0

// Training Test 1 (class 1).
StdOut.println("Training Test 1: trainMulti((3, 4, 5), 1)");
mp1.trainMulti(training1, 1);
StdOut.println("  expect: ((0.0, 0.0, 0.0), (3.0, 4.0, 5.0))");
StdOut.println("  result: " + mp1);

// Training Test 2 (class 0).
StdOut.println("Training Test 2: trainMulti((2, 0, -2), 0)");
mp1.trainMulti(training2, 0);
StdOut.println("  expect: ((2.0, 0.0, -2.0), (3.0, 4.0, 5.0))");
StdOut.println("  result: " + mp1);

// Training Test 3 (class 1).
StdOut.println("Training Test 3: trainMulti((-2, 0, 2), 1)");
mp1.trainMulti(training3, 1);
StdOut.println("  expect: ((2.0, 0.0, -2.0), (3.0, 4.0, 5.0))");
StdOut.println("  result: " + mp1);

// Training Test 4 (class 0).
StdOut.println("Training Test 4: trainMulti((5, 4, 3), 0)");
mp1.trainMulti(training4, 0);
StdOut.println("  expect: ((2.0, 0.0, -2.0), (-2.0, 0.0, 2.0))");
StdOut.println("  result: " + mp1);

// Testing data.
double[] testing1 = { -1.0, -2.0, 3.0 };
double[] testing2 = {  2.0, -5.0, 1.0 };

// Testing Test 1 (expect class 1).
StdOut.println("Testing Test 1: predictMulti((-1, -2, 3))");
StdOut.println("  expect: 1");
StdOut.println("  result: " + mp1.predictMulti(testing1));

// Testing Test 2 (expect class 0).
StdOut.println("Testing Test 2: predictMulti((2, -5, 1))");
StdOut.println("  expect: 0");
StdOut.println("  result: " + mp1.predictMulti(testing2));

Image Classifier Data Type

Your final task is to implement ImageClassifier.java, which uses MultiPerceptron to classify images. It must:

Train on the labeled examples in a training data file.
Test on the labeled examples in a testing data file.
Print the misclassified images and the test error rate.

Organize your client according to the following API:

public class ImageClassifier {
    // Creates an ImageClassifier from the given configuration file.
    public ImageClassifier(String configFile) 

    // Returns the name of the class corresponding to the given class label.
    public String classNameOf(int classLabel) 

    // Returns the feature vector (1D array) extracted from the given picture.
    public double[] extractFeatures(Picture picture) 

    // Trains the classifier using the given training data file.
    public void trainClassifier(String trainFile) 

    // Predicts the class label for the given picture.
    public int classifyImage(Picture picture) 

    // Returns the test error rate on the given testing data file.
    // Also prints the misclassified examples (see the specification).
    public double testClassifier(String testFile) 

    // Tests this class using a configuration file, training file,
    // and testing file.
    public static void main(String[] args) {
        ImageClassifier classifier = new ImageClassifier(args[0]);
        classifier.trainClassifier(args[1]);
        double testErrorRate = classifier.testClassifier(args[2]);
        System.out.println("test error rate = " + testErrorRate);
    }
}

Here are some details about the API:

Configuration file format. The configuration file consists of the following lines:
1. The image width and height (in pixels), used by the training and testing data files.
2. The number of classes $m$.
3. The names of the $m$ classes, one per line.
Training and testing file format. Training and testing data files consists of a sequence of lines. Each line contains:
- the name of an image file, and
- an integer class label (between $0$ and $m-1$), separated by whitespace.
For testing data files, you will use the integer labels only to evaluate the accuracy of your predictions.

Input files. We provide a variety of datasets in the specified format, including handwritten digits, fashion articles from Zalando, Hiragana characters, and doodles of fruit, animals, and musical instruments. The handwritten digits and fashion articles are included in your project folder. You can download the other datasets here.

Data files	Description	Source



digits.jar	handwritten digits	MNIST



fashion.jar	fashion articles	Fashion MNIST



Kuzushiji.jar	Hirigana characters	Kuzushiji MNIST



fruit.jar	fruit doodles	Quick, Draw!



animals.jar	animal doodles	Quick, Draw!



music.jar	musical instrument doodles	Quick, Draw!

Constructor. The ImageClassifier constructor takes one argument: the name of a configuration file. It reads the configuration data and creates a MultiPerceptron with $m$ classes and $n = width \times height$ inputs. It also stores the class names from the configuration file.
Feature extraction. The extractFeatures() method converts a grayscale image into a one-dimensional feature vector for use with MultiPerceptron. It must:
1. iterate over the pixels in row-major order;
2. extract the grayscale value of each pixel (for a shade of gray, the red, green, and blue components are equal); and
3. store the values in a 1D array of length $width$-by-$height$.
It must throw an IllegalArgumentException if the image dimensions are not equal to the dimensions specified in the configuration file.
Training. The trainClassifier() method takes the name of a training data file and trains the classifier using the images and labels in that file.
Class name. The classNameOf() method must throw an IllegalArgumentException if its argument is not between $0$ and $m-1$, where $m$ is the number of classes.
Classification. The classifyImage() predicts and returns a class label $i$, where $$0 \leq i \leq m - 1$.
Testing. The testClassifier() method takes the name of a testing data file and tests the classifier using the images and labels in that file. For each misclassified image, it must print:
- the image filename,
- the correct class name, and
- the predicted class name.
in the format shown below:
```
jar:file:digits.jar!/testing/6/4814.png, label = seven, predict = nine
jar:file:digits.jar!/testing/6/66.png, label = seven, predict = eight
jar:file:digits.jar!/testing/5/9982.png, label = six, predict = seven
jar:file:digits.jar!/testing/7/6561.png, label = eight, predict = ten
```
The testClassifier() method also returns the test error rate (the fraction of test images that are misclassified).
Main. The main() method takes three command-line arguments:
1. the name of a configuration data file;.
2. the name of training data file;
3. The name of testing data file.
It then creates an ImageClassifier, trains it on the training data, tests it on the testing data, and prints the test error rate.

Here is a sample execution:

~/Desktop/classifier> java-introcs ImageClassifier digits.txt digits-training20.txt digits-testing10.txt
digits/testing/1/46.png, label = one, predict = three
digits/testing/7/36.png, label = seven, predict = two
digits/testing/7/80.png, label = seven, predict = two
digits/testing/1/40.png, label = one, predict = two
digits/testing/1/39.png, label = one, predict = three
digits/testing/7/79.png, label = seven, predict = two
digits/testing/9/20.png, label = nine, predict = two
digits/testing/9/58.png, label = nine, predict = four
test error rate = 0.8

Q.I’m stuck on ImageClassifier. Can you suggest some steps for making steady, incremental progress?

These steps are optional. Use them as needed.

Constructor and Instance Variables

Implement the ImageClassifier() constructor.
Read the configuration file data, and store the configuration data in your instance variables.

Review the In data type from Section 3.1, which is an object-oriented version of StdIn.
Define these instance variables:
- an integerwidth (picture width)
- an integer height(picture height)
- an array of strings classNames[] (the $m$ class names)
- a MultiPerceptron with $m$ classes and $n = width \times height$ inputs

Print the instances variables to standard output.
Test: In main(), create various ImageClassifier objects using different configuration files (image3x3.txt, digits.txt, fashion.txt, etc.)
Implement classNameOf(). For the given class label, return the class name associated with it. Test: call ``classNameOf()` with different arguments and print the results.
Printing is solely for checking progress; remove the print statements once you have confidence your constructor is working properly.

Feature Extraction

Review Section 3.1 of the textbook, especially Program 3.1.4 (Grayscale.java) for using the Picture and Color data types. Note that the images are already grayscale, so you don’t need to use Luminance.java. In particular, the red, green, and blue components are equal, so you can use any of getRed(), getGreen(), or getBlue() to get the grayscale value.
Comment out the test client code provided in ImageClassifier.main().
Create a Picture object for the image 49785.png (in the project folder) and display it in a window. (Remove this code after you have successfully displayed the image.)
Create a Picture object for the image image3x3.png (in the project folder) corresponding to the 3-by-3 example given below.
- Extract its width and height and print the values to standard output.
- Extract the grayscale values of the pixels and print. If it’s not already in row-major order, adjust your code so that it prints the values in the specified order.
- If you are using IntelliJ, do not type the import java.awt.Color; statement that is normally needed to access Java’s Color data type. IntelliJ is pre-configured to automatically add import statements when needed (and remove them when not needed).
Create a one-dimensional array of length width x height and copy the grayscale values to the array. Print the values of this array to confirm you can create a vector (row-major order) of values from a Picture object.
Using the code from steps (4) and (5) as a guide, implement the method extractFeatures() that takes a Picture as an argument and returns the grayscale values as a double[] in row-major order.

Write a main() method that tests extractFeatures(). Using image3-by-3.png, your main() method should print the values returned by extractFeatures() as shown in the above figure:

ImageClassifier test = new ImageClassifier("image3x3.txt"); // create a small test
Picture image3x3 = new Picture("image3x3.png");             
double[] values = test.extractFeatures(image3x3);
// print the array values

Once you are confident that extractFeatures() works, remove your testing code before submitting the assignment to TigerFile.

Classifying Images

Implement the classifyImage() method. For the given image, extract its features and use the multi-perceptron to predict its class label.
Implement the trainClassifier() method. Read the training file data just as you read the configuration file. For each training image, extract its corresponding features and train the classifier using the corresponding label.
Implement the testClassifier() method. Read the testing file data just as you read the configuration file. For each testing image, predict its class. Print each misclassified image to standard output and compute the error rate on these images.

Training and Testing using Large Datasets

Now for the fun part. Try the large training and testing files. Processing 60,000 images may take noticeable time.

Now, the fun part. Use large training and testing input files. Be prepared to wait for one (1) minute (or more) while your program processes 60,000 images.

~/Desktop/classifier> java-introcs ImageClassifier digits.txt digits-training60K.txt digits-testing10K.txt
jar:file:digits.jar!/testing/6/4814.png, label = six, predict = zero
jar:file:digits.jar!/testing/5/4915.png, label = five, predict = eight
jar:file:digits.jar!/testing/6/2754.png, label = six, predict = zero
...
jar:file:digits.jar!/testing/4/1751.png, label = four, predict = three
jar:file:digits.jar!/testing/3/9614.png, label = three, predict = five
jar:file:digits.jar!/testing/5/6043.png, label = five, predict = three
test error rate = 0.1318

Don’t worry about the odd-looking filenames. They specify the location of an image stored inside a JAR file (Java Archive). Storing the images in a JAR is more efficient than working with hundreds of thousands of separate files.

For example, in jar:file:digits.jar!/training/7/4545.png, digits.jar is the JAR file, and /training/7/4545.png is the path to the image within that JAR.

Try experimenting with the other datasets:

~/Desktop/classifier> java-introcs ImageClassifier fashion.txt fashion-training60K.txt fashion-testing10K.txt
...

~/Desktop/classifier> java-introcs ImageClassifier Kuzushiji.txt Kuzushiji-training60K.txt Kuzushiji-testing10K.txt
...

~/Desktop/classifier> java-introcs ImageClassifier music.txt  music-training50K.txt music-testing10K.txt
...

~/Desktop/classifier> java-introcs ImageClassifier fruit.txt fruit-training30K.txt fruit-testing6K.txt
...

~/Desktop/classifier> java-introcs ImageClassifier animals.txt animals-training60K.txt animals-testing12K.txt
...

Analysis

Answer Parts 1, 2 and 3 in readme.txt.

Part 1: Run the following experiment (you may want to redirect standard output to a file):

~/Desktop/classifier> java-introcs ImageClassifier digits.txt digits-training60K.txt digits-testing1K.txt

Which digit is misclassified the most frequently?
For that digit, what are the two most common incorrect predictions (i.e., which two digits does your classifier confuse it with most often)?
Inspect several of these misclassified images. Explain what visual features might be causing the misclassifications.

Part 2. Use experiments to answer the following:

What is the error rate on digits-testing1K.txt before training? To measure this, run your program without training (e.g., temporarily comment out the call to trainClassifier() in main()).
What is the error rate on digits-testing1K.txt after training?
Based on these results, can you conclude that the classifier is learning? Explain briefly.

Part 3. People write the digit 7 in different ways. For example, some writers (common in parts of Europe and Latin America) draw a 7 with a horizontal bar through the middle, while others (common in Japan and Korea) draw a 7 with a slanted or “crooked” top stroke.

Our data set	7 with a middle bar	7 with a crooked top

Suppose the training data contains no examples of either convention. How do you expect the classifier to perform on test data from populations that commonly use these styles? What are possible consequences?
Now consider a supervised learning system for diagnosing cancer. Suppose the training data contains examples only from population X, but you deploy the system on population Y. What are possible consequences?

Submission

Submit all files to TigerFile :

Perceptron.java
MultiPerceptron.java
ImageClassifier.java
readme.txt
acknowledgments.txt

Grading Breakdown

Files	Points
Perceptron.java	12
MultiPerceptron.java	12
Classifier.java	12
readme.txt	4
Total	40

Enrichment FAQ

Q.When was the perceptron algorithm first discovered?

It was proposed in 1958 by Frank Rosenblatt, an American psychologist. It is one of the earliest machine-learning algorithms. At the time, researchers were overly optimistic about its short-term potential and grossly underestimated the formidable challenge of building intelligent machines.

Q.What is the significance of the perceptron algorithm?

It is a really simple, beautiful algorithm that, nevertheless, can do something interesting.

The perceptron algorithm is one of the most fundamental algorithms in an area of ML called online learning (learning from samples one at a time).
The perceptron algorithm is closely related to the support-vector machine algorithm, another fundamental ML algorithm.
The perceptron algorithm has some beautiful theoretical properties. For example, if the training data set is linearly separable (i.e., there exists some weight vector that correctly classifies all of the training examples), and if we cycle through the training data repeatedly, the perceptron algorithm will eventually (and provably) find such a weight vector.
Perceptrons are a building block in neural networks. In neural networks, many perceptrons (or other artificial neurons) are connected in a network architecture, in which the outputs of some neurons are used as the inputs to other neurons. Training multi-layer neural networks requires a more sophisticated algorithm to adjust the weights, such as gradient descent and backpropagation.

Q.Does the perceptron algorithm produce a different weight vector depending on the order in which it processes the training examples?

Yes. We’ve randomized the training data. It would be a bad idea, for example, to process all of the handwritten 0s before all of the handwritten 6s.

Q.Any intuition for why the perceptron algorithm works?

Geometrically, you can view each input vector $x$ as a point in $R^n$ and the weight vector $w$ as a hyperplane through the origin. The goal of the perceptron algorithm is to find a hyperplane that separates the positive examples from the negative examples. Using vector terminology, the weighted sum is known as the dot product; its sign determines on which side of the hyperplane the point lies.

During training, when we encounter a point $x$ that is on the wrong side of the hyperplane (i.e., a false positive or negative), we update the weight vector, thereby rotating the hyperplane slightly. After the rotation, x is either on the correct side of the hyperplane or, if not, at least a bit closer to the hyperplane (in terms of Euclidean distance).

Q.How can I improve accuracy of the perceptron algorithm?

Here are three simple ideas:

Multiclass perceptron. Instead of training all m perceptrons on each input vector, when there is a prediction error (multiclass perceptron predicts $i$ but correct label is $k$, train only two perceptrons: train perceptron $i$ (with label $-1$) and perceptron $k$ (with label $+1$).
Adjust the weights with a fraction of $+1$ or $-1$ for correct or incorrect predictions (this helps with a smoother convergence) and iterate over the training step multiple times, each time training the perceptron with the same set of training data (randomized in order).
Normalize the features array data to have values between 0 and 1 (divide the values with 255) and initialize the perceptron weights to random values (with uniform random or Gaussian random to be less than 1 and on average 0).
Averaged perceptron. Instead of using the last weight vector, take the average of the weight vectors that are computed along the way.
Incorporate more features. Instead of using the feature vector $x_0, x_1,\ldots, x_{n-1}$, create additional features. In particular, for each pair of features $x_i$ and $x_k$, create a new feature $x_{ik} = x_i * x_k$. You could also keep going, adding not just pairs of features, but also triples, etc. This can significantly improve accuracy, but it becomes prohibitively expensive in terms of computation.

See this paper for additional ideas, including the kernel trick and the voted-perceptron algorithm.

Q.I noticed that the weights are always integral throughout the perceptron algorithm. Why is this?

Adding or subtracting an integer to an integer yields an integer. The weights are always adjusted by either adding or subtracting the input vector; for the image classification problems we consider in this assignment, the input vector elements are integers between 0 and 255 (grayscale values).

Q.As a perceptron is trained with more and more data, the weights increase in absolute value. Is this to be expected?

Yes. This implies that the algorithm makes smaller and smaller relative changes to the weights as it learns from more and more input–output pairs.

Q.Why not use the testing data for training?

We seek a model that can make good predictions for unseen input–output pairs. If we use the testing data when training, the algorithm could “memorize” the input–output pairs. While this might achieve higher accuracy on those inputs, the results may not generalize to unseen inputs.

Q.What is the difference between supervised and unsupervised learning?

In supervised learning, the algorithm has access to training data for which we know the correct labels. These labels act as a teacher supervising the learning process. In unsupervised learning, the training data is unlabeled, so there are no correct answers; instead, the goal may be to cluster similar inputs together.

Q.How can I make it recognize my own handwritten digits?

Use the same technique, but you must be careful to size-normalize and center the images, as is done in the MNIST training data.

Q.Can ML algorithms be trained to classify alphabetic and mathematical symbols?

Yes. Here are web apps that let you draw and find the most similar Unicode characters or LaTeX symbols.

Q.Any games based on classifying hand-drawn images?

Yes. Try Quick, Draw!, which uses neural networks and the world’s largest doodling data set.

Q.What is the best performing algorithm for classifying handwritten digits using the MNIST dataset?

The current champion uses convolution neural networks and achieves a 99.79% accuracy rate on the MNIST testing database consisting of 10,000 images. Here are the 21 incorrect predictions:

There is not much room for improvement; indeed, some of the errors appear to be due to incorrectly labeled (or ambiguous) inputs.

This assignment was developed by Sebastian Caldas, Robert DeLuca, Ruth Fong, Maia Ginsburg, Alan Kaplan, Kevin Jeon, and Kevin Wayne.

9. Hamming Codes in TOY

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

In this assignment, you will write TOY programs to encode and decode messages using Hamming codes. You will learn about machine-language programming and error-correcting codes.

Getting Started

Read Chapter 6 of the textbook and review the corresponding lectures and precepts.
Download and unzip hamming.zip , then open the hamming project in IntelliJ.
Review HammingEncoder.java and HammingDecoder.java in the project folder; they illustrate the encoding and decoding procedures in Java.
Refer to the TOY reference card, as needed.
Follow these partnering rules.

Background

Error-correcting codes enable reliable communication over noisy channels. The sender appends redundant information so the receiver can recover the original message even if some bits are corrupted during transmission. Errors can arise from static on a cell phone or atmospheric interference. In noisy settings, error-correcting codes can increase throughput by reducing (or eliminating) retransmissions. They are used in many systems, including memory storage systems (e.g., DRAM and SSDs), mobile and wireless communications, and digital television.

A Hamming code is an error-correcting code that detects and corrects single-bit errors. It is used in settings where such errors are common, including DRAM chips and satellite communications. A Hamming code takes four message bits and adds three parity bits to form a 7-bit codeword. If at most one of these seven bits is corrupted, the receiver can detect the error and recover the original four message bits. This single-bit error correction increases bandwidth by 75% (three extra parity bits for every four message bits). By comparison, sending three copies of each bit and taking the majority value increases bandwidth by 200%.

Approach

Before describing the algebra of Hamming codes, we first visualize how the parity bits are computed using Venn diagrams. As an example, suppose we want to send the 4-bit message 1101. Label the message bits $m_1, m_2, m_3, m_4$, as in the diagram below:

Then add three parity bits $p_1, p_2, p_3$ so that each circle has even parity:

That is, the sum of the four bits inside each circle is even:

In this example, the parity bits are 1 (top), 0 (left), and 0 (right). So, instead of sending 1101, we send the 7-bit codeword 1101100.

Now suppose one bit is corrupted during transmission, so the receiver gets the codeword 1001100:

The receiver detects an error by checking the parity of the three circles. Moreover, the pattern of failed parity checks pinpoints which bit flipped, so the receiver can correct the error and recover the original four message bits:

Here, the parity checks for the top and right circles fail, while the left circle passes. The only bit that lies in exactly those two circles is $m_2$, so the receiver flips $m_2$ to obtain 1101100. This corresponds to message bits 1101 plus parity bits 100, as intended.

The pattern of failed parity checks identifies which bit (if any) was flipped:

If no bit is corrupted, then all three parity checks pass.
If one of $m_1$, $m_2$, or $m_3$ is corrupted, then exactly two checks fail.
If $m_4$ is corrupted, then all three checks fail.
If one of $p_1$, $p_2$, $p_3$, or $p_4$ is corrupted, then exactly one check fails (the check for that circle).

This scheme corrects only single-bit errors; more sophisticated error-correcting codes handle multiple-bit errors.

Hamming Encoder

Write a TOY program encode.toy that encodes a binary message using the scheme described above.

Repeatedly read four bits $m_1, m_2, m_3, m_4$ from TOY standard input.
Compute the parity bits:
- $p_1 = m_1 \oplus m_2 \oplus m_4$
- $p_2 = m_1 \oplus m_3 \oplus m_4$
- $p_3 = m_2 \oplus m_3 \oplus m_4$
Write the seven bits $m_1, m_2, m_3, m_4, p_1, p_2, p_3$ to TOY standard output.
Stop when you read FFFF, then output FFFF.

Q.What is the meaning of the $\oplus$ operator?

It is the standard symbol in math and CS for exclusive or (xor), which is useful for comptuting parity. Xor takes two input bits and outputs 1 they are different and 0 if they are the same. Equivalently, it outputs 1 if the sum of the bits is odd, and 0 if is even. In Java and TOY, it corresponds to the ^ operator.

Hamming Decoder

Write a TOY program decode.toy that decodes (and corrects) a Hamming-encoded message.

Repeatedly read seven bits $m_1, m_2, m_3, m_4, p_1, p_2, p_3$ from standard input.
Recomptue the parity bits from the message bits:
- $q_1 = m_1 \oplus m_2 \oplus m_4$
- $q_2 = m_1 \oplus m_3 \oplus m_4$
- $q_3 = m_2 \oplus m_3 \oplus m_4$
Compare $q_1, q_2, q_3$ with the received parity bits $p_1, p_2, p_3$.
If necessary, flip the corrupted message bit, then write $m_1, m_2, m_3, m_4$ to standard output.
Stop when you read FFFF, then output FFFF.

To determine which message bit (if any) is corrupted, use the result of the three parity checks:

If zero or one check fails, then all four message bits are correct.
If checks 1 and 2 fail (but not check 3), then $m_1$ is incorrect.
If checks 1 and 3 fail (but not check 2), then $m_2$ is incorrect.
If checks 2 and 3 fail (but not check 1), then $m_3$ is incorrect.
If all three checks fail, then $m_4$ is incorrect.

Input Format

The input to encode.toy is a text file containing the bits to transmit.

Each line contains four bits, $m_1, m_2, m_3, m_4$.
Each bit is written as a 4-digit hexadecimal integer: 0000 (0) or 0001 (1), separated by whitespace.
The final line is the single integer FFFF, which marks the end of the file.

The file encode3.txt contains three 4-bit messages:

~/Desktop/hamming> more encode3.txt
0001 0001 0000 0001
0001 0001 0001 0000
0001 0001 0001 0001
FFFF

The corresponding 4-bit messages are 1101, 1110, and 1111.

The input format for decode.toy is similar, except that each line contains seven bits (a 7-bit codeword), again written as 0000 or 0001:

~/Desktop/hamming> more decode4.txt
0001 0001 0000 0001 0001 0000 0000
0001 0000 0000 0001 0001 0000 0000
0001 0001 0000 0000 0001 0000 0000
0001 0001 0000 0001 0001 0000 0001
FFFF

The corresponding 7-bit codewords are 1101100, 1001100, 1100100, and 1101101.

Formatting and Commenting Requirements

To make your TOY code readable and easy to debug, follow these formatting and commenting guidelines:

Each TOY instruction must have corresponding pseudocode. (If you use Visual X-Toy, the pseudocode is generated automatically.)
Add blank lines between logically related sections of TOY code.
Write a comment above each section explaining what that code does.
Use the third column for your own comments. Hint: use the Java code from HammingEncoder.java and HammingDecoder.java as a starting point for your comments.

FAQ

Q.Can I assume the input files are in the prescribed format?

Yes. The input files will contain only a sequence of 0000’s and 0001’s, followed by FFFF. If there are no bits to be decoded, the file contains only the single integer FFFF.

Q.How to use the Visual X-TOY Simulator?

Use the Visual X-TOY simulator by executing the following command in the IntelliJ terminal:

~/Desktop/hamming> java -jar toy.jar

The Visual X-TOY simulator provides lots of useful development features. There are two major modes: edit and debug. Use Mode > Edit Mode to edit .toy programs and Mode > Debug Mode to debug or run .toy programs. In Debug Mode, use the Reference, Stdin, Stdout and Core tabs on the right to help debug your program.

To open a TOY program from a file, use Select File > Open, then browse to find the program, e.g., multiply.toy.
To edit a TOY program, use Select Mode > Edit Mode. You can type your program directly in the edit window. Use multiply.toy as a reference for formatting and commenting.
To redirect standard input from a file, in Edit Mode, select Mode > Load File to Stdin.
To execute a TOY program, use Select Mode > Debug Mode. Then click the Run button at the bottom. You can enter data on standard input by typing the value in the Stdin tab and clicking the Add button. You will have to click the Run button to resume execution. You can see the results on standard output in the Stdout tab.

Q.What are common TOY programming issues?

The program counter starts at 10 so make sure that you place your code starting at memory address 10.
Be sure that each line follows the required format XX: XXXX.
Check for duplicated line numbers or out-of-order line numbers.
Check for using a letter like O or I instead of the number 0 or 1.
Remember that all values, memory addresses, and arithmetic are in hex. For example, memory address 1A follows 19. If you don’t specify the value for a memory address, that memory address will have the default value of 0000, which is a HALT instruction.
Watch out for jump statements — if you insert a new line of code between existing lines, you will have to renumber all the following lines. Also, be sure to update any jump statements that have hardwired line numbers.
Be very careful to update both your comments and your actual code at the same time! It is very common to update only the pseudocode and not the machine instruction.
All registers are global variables. One way to be sure that a register is not used for two different purposes is to fill in the question in the readme.txt about registers before or during debugging.

Q.I’m stuck. How do I make progress?

These are purely suggestions for how you might make progress. You do not have to follow these steps. If you get stumped or frustrated on some portion of the assignment, you should not hesitate to consult a preceptor.

Open the Visual X-Toy Simulator and experiment with some of the example programs.
1. Try the sample programs Add, Echo, and Sum by going to File > Open Example Programs.
2. Open and experiment with multiply.toy, which is included in the project folder.
3. Try executing some of the programs from precept.
Read, compile, and run the reference solutions HammingEncoder.java and HammingDecoder.java. Use these reference solutions as a design for your TOY programs.
The readme.txt provides tables to help your design/implementation/debugging of encode.toy and decode.toy. This will help you think about how you plan to use and/or re-use the Toy registers as you implement these Toy programs. Before you start coding, complete these tables, and update as needed. They will be very helpful for you as well as those helping you during office hours and/or Lab TA debugging sessions.
As you write your TOY programs, remember:
- The first column contains the TOY instruction in hex.
- The second column contains the TOY pseudo-code.
- The third column is used for your own comments. Write comments as you write your code. This will help you understand your design as well as help during office hours, grading, etc.
In X-Toy, create a new file (File > New).
Save the file (File > Save) as encode.toy in your Hamming assignment project folder.
Incrementally implement and test encode.toy, using HammingEncoder.java as a guide. Remember that as you revise your program, you will need to edit your TOY statement numbers accordingly.
- Write TOY code that reads a number from standard input. If the number is negative, the program shall halt. (Note, the only valid negative input is FFFF.) Otherwise, it prints the number and inputs the next number.
- Edit your TOY program from step (a) so that it now reads in sequences of four numbers, halting if the first number is negative. Otherwise, it writes the four numbers and inputs the next sequence of numbers.
- Edit your TOY program from step (b) so that it now computes the parity bits, and writes the parity bits.
Incrementally implement and test decode.toy, using HammingDecoder.java as a guide.

Q.How do I test my TOY programs?

We provide several input files for both encode.toy and decode.toy, along with the corresopnding answer files. For convenience, each answer file shows the input and an abbreviated version of the output. corresponding outputs.

Encoding

input file	output file
`encode0.txt`	`encode0-answer.txt`
`encode1.txt`	`encode1-answer.txt`
`encode3.txt`	`encode3-answer.txt`
`encode16.txt`	`encode16-answer.txt`

Decoding

input file	output file
`decode0.txt`	`decode0-answer.txt`
`decode1.txt`	`decode1-answer.txt`
`decode3.txt`	`decode3-answer.txt`
`decode4.txt`	`decode4-answer.txt`
`decode6.txt`	`decode6-answer.txt`
`decode16.txt`	`decode16-answer.txt`
`decode128.txt`	`decode128-answer.txt`

To test your TOY program with the command-line TOY.java simulator, type the commands below in the IntelliJ terrminal. You should see one bit (a TOY hex word) per line:

~/Desktop/hamming> java-introcs TOY encode.toy < encode3.txt
0001
0001
0000
0001
0001
0000
0000
0001
0001
0001
0000
0000
0000
0000
0001
0001
0001
0001
0001
0001
0001
FFFF

~/Desktop/hamming> java-introcs TOY decode.toy < decode4.txt
0001
0001
0000
0001
0001
0001
0000
0001
0001
0001
0000
0001
0001
0001
0000
0001
FFFF

You can then compare your output with the corresponding answer file.

The most thorough test is to encode and decode all possible inputs. The input files encode16.txt and decode128.txt do exactly that.

Submission

Upload all required files to TigerFile :

encode.toy
decode.toy
readme.txt
acknowledgments.txt

Be sure to answer all questions in readme.txt.

Grading Breakdown

Files	Points
encode.toy	16
decode.toy	22
readme.txt	2
Total	40

Leaderboard (optional)

Submit an optimized decode.toy to the Hamming Leaderboard for class fame and glory. You may work alone or with your partner. Your goal is to use the fewest nonzero words of TOY main memory.

Under 40 (decimal) is very good.
Under 35 is great.
The all-time record is 27.

To submit to the leaderboard and see results:

Upload nickname.txt containing your group name. Please keep it respectful.
Upload leaderboard.txt, describing your approach.
Submit to Leaderboard
View Current Leaderboard

People

Mon, 19 Jan 2026 00:00:00 +0000

Contact

Mon, 24 Oct 2022 00:00:00 +0000

COS 126 Programming Assignments FAQ

Mon, 01 Jan 0001 00:00:00 +0000

This page answers common questions about coding, testing, and submitting COS 126 assignments. If you do not find an answer here, ask on Ed or attend office hours.

Click a question to reveal the answer.

Getting started

Q.Which Java programming environment (IDE) should I use for COS 126?

We strongly recommend our custom version of IntelliJ. It is the only IDE we support.

Q.I already have IntelliJ. Do I still need to install the COS 126 version?

Yes. Install (or update to) the COS 126 version, which we refresh every summer.

Q.How do I unzip the assignment ZIP file?

macOS: Double-click the .zip file in Finder to extract it (if it wasn’t automatically extracted when you downloaded it).
Windows: Right-click the ZIP file and choose Extract All….

Q.How do I open an assignment project in IntelliJ?

Download the assignment ZIP file, unzip it, then open the project folder in IntelliJ. Do not open a file or subfolder inside the project folder.

Q.Where should I store assignment projects?

Create one folder for all COS 126 assignments, and keep each assignment in its own subfolder.

Store projects on a local disk (not a network drive, cloud-synced folder, or SMB share).
On macOS, if you store projects in Desktop, Documents, or Downloads, you may need to grant IntelliJ and Terminal file access via System Settings → Privacy & Security → Files and Folders.

Q.What is in the assignment project folder?

It typically includes data files and course configuration files.

Q.How do I create a new Java class in IntelliJ?

Select LIFT → New Java Class from the menu.

Q.How do I create a new IntelliJ project?

IntelliJ projects can be tricky to configure. We recommend using only the provided project folders (one for each assignment and precept). To create a new project, download any provided folder, rename it, and delete any unneeded files.

Course policies

Q.What Java features are allowed on assignments?

Use only Java features that have been covered in lecture, precept, or the assigned readings for this point in the course. If you are unsure whether something is in scope, ask on Ed before using it. For reference, the Java Programming Cheatsheet lists the Java features we use during the semester.

Q.Can I copy or adapt code from the course materials?

Yes. You may copy or adapt code from course materials, including the textbook, lecture slides, precepts, and assignment specifications. If you copy substantial code, include a brief comment citing the source. Do not copy solutions or code from outside course materials.

Q.Can I use generative AI tools in programming assignments?

No. You may not use generative AI for any part of a programming assignment, including writing code, debugging, explaining errors, generating comments, summarizing, or reformatting). These assignments are designed to help you build your own ability to reason about code. Submitting AI-generated work defeats that purpose and violates the course collaboration policy.

Q.Should I include my name and NetID in every file I submit?

No. We grade anonymously. Do not put any personally identifiable information in .java files or readme.txt.

Style and readability

Q.How should I format my code?

Use 4 spaces per indentation level.
Keep lines to 87 characters or fewer in .java, readme.txt, and acknowledgments.txt file.
Use whitespace for readability: blank lines between logical sections and spaces around operators.

Q.How should I write clear code?

Use meaningful variable names (for example, isOrdered, not o or ordered). Loop indices like i and j are fine.
Prefer simple conditionals: write if (isBlue) { ... }, not if (isBlue == true) {...}.
Match the require types: if an input is specified as an integer, store it in an int.
Match the required control flow: if the specification requires a while loop, use a while loop.
Match the output format exactly, including punctuation, spacing, and number of lines. Remove debugging prints before submitting.
Avoid magic numbers. Give important constants a named variable (e.g., int DAYS_PER_WEEK = 7).
Minimize scope: declare variables in the smallest block where they are used.
In OOP assignments, use instance variables only when they represent per-object state. Make all instance variables private.

Q.How should I comment my code?

Add a brief comment above each logical section of code.
Comment every method, documenting its purpose, inputs, and outputs.
Comment any local variable whose purpose is not obvious from its name.
In OOP assignments, comment every instance variable.
Write comments as you code so your intent stays clear.

Q.Is there another useful resource on writing clear programs?

Yes. Our style guide is a useful additional resource. Some guidelines may not make sense yet, but they will as the semester unfolds.

Required text files

Q.How should I edit readme.txt and acknowledgments.txt?

Use IntelliJ (recommended). Save them as plain text files. Do not change their names or file extensions.

Q.What is a readme.txt file?

It is a short narrative description of your work. Use the provided template and answer every question. Do not include your name, NetID, or email address in readme.txt.

Q.What is an acknowledgments.txt file?

It lists who helped you (with dates) and includes the required academic integrity statement with your digital signature. We grade an assignment only after acknowledgments.txt has been submitted.

Assignment submissions

Q.How do I submit an assignment?

Submit assignments on TigerFile. Each assignment has its own submission link.

Q.How do I log in to TigerFile?

Q.I cannot log in to TigerFile. What should I do?

To access TigerFile, you must be officially enrolled in the course. Make sure you are using the submission link for the current semester. If you still cannot log in, post on Ed.

Q.Can I submit via Canvas or email instead of TigerFile?

No. All programming assignments must be submitted via TigerFile.

Q.How do I correctly submit an assignment?

Remove debugging output.
Upload all required files (your latest versions).
Match the required output format exactly (spelling, spacing, punctuation, and number of lines).
After testing locally, click Check Submitted Files and fix any reported issues.
When you are ready for grading, upload acknowledgments.txt.

Q.Can I resubmit after uploading?

Absolutely. You may resubmit as often as you like before the deadline.

Q.How do I fix Filename is not in list?

Your filename must match the required name exactly, including capitalization and the .java extension. For example, HelloWorld.java is not the same as helloworld.java. We recommend enabling “show file extensions” in your operating system settings (Mac and Windows).

Late submissions

Q.How do I submit an assignment after the deadline?

Submit as usual in TigerFile. Upload acknowledgments.txt only when you are ready for your work to be graded.

Q.How do I use late days for an assignment?

They are applied automatically.

Partnered submissions

Q.On assignments that allow partners, how do we upload files?

Create a TigerFile group for the assignment and add your partner. Either partner may upload files.

Q.I am working alone, but TigerFile requires a group to submit. What should I do?

Create a group with one member (just you).

Q.Can either partner upload files?

Yes.

Check Submitted Files

Q.What does Check Submitted Files do?

It compiles your code and runs automated checks against the assignment specification. These include correctness tests and, on some assignments, performance and memory checks. It also runs static analysis (SpotBugs and Checkstyle) to flag likely bugs and style issues.

Q.Where is the Check Submitted Files button?

In TigerFile, open the assignment submission page. The Check Submitted Files button appears below your uploaded files.

Q.How many checks do I get per assignment?

You may run Check Submitted Files up to 20 times per assignment. For partnered assignments, this limit applies to the group.

Q.Do I need to upload all required files to get feedback?

No. The autograder checks whichever files you submit, as long as they compile.

Q.What do compiler errors or warnings mean?

Your code did not compile cleanly. Fix all compiler errors and resolve all warnings before your final submission. If you are stuck, ask on Ed or bring the error message to office hours or Lab TA hours.

Q.What do SpotBugs and Checkstyle warnings mean?

SpotBugs: likely bug patterns (occasionally false positives)
Checkstyle: formatting and style rules, including course-specific checks. Treat warnings seriously and fix them when possible. If you do not understand a message, ask on Ed or bring it to office hours or Lab TA hours.

Q.What does a FAILED message mean in the autograder output?

Your program does not meet the specification on the tested inputs. A FAILED result will likely reduce your score. Passing all tests is a good sign, but it does not guarantee full credit because we run additional tests when grading.

Q.What causes Process took too long and was killed?

The autograder did not finish within the time limit. Common causes are an infinite loop or printing far more output than the specification requires (often due to leftover debugging output).

Q.How do I fix failed to fetch NetworkError?

This typically indicates a network problem. Confirm you are online and reload the page.

Testing, input, and debugging

Q.Does my program need to handle every possible input?

No. Your program must handle all inputs in the domain specified by the assignment. For example, when grading RGBtoCMYK.java, we will always provide three integers between 0 and 255.

Q.Do I have to test my code?

Yes. Some assignments provide a test client; others require you to write one. At minimum, your test client should exercise every public method at least once with meaningful inputs and print the results. For thorough testing, try additional edge cases beyond the minimum.

Q.Should my program use command-line arguments, standard input, or file input?

Follow the assignment specification. If it requires command-line arguments, read args[]. If it requires standard input, read from standard input. If it requires file input, read from a file. Using the wrong input method will not match our tests.

Grading and feedback

Q.Does Check Submitted Files determine my grade?

No. Check Submitted Files provides automated feedback. Course staff assign the final grade, and we may run additional tests when grading.

Q.Where can I view grading feedback?

View grading feedback in Gradescope. We will email sign-up instructions after Assignment 0 is graded.

Q.How are deductions computed?

There are three components (1) The total number of tests passed / total number of tests. (2) .4 points deducted for each warning message. (3) 3.0 points deducted for each error message. However, we sometimes deduct points manually for certain violations.

Q.How do I know if my files have been successfully submitted?

You know your file has been successfully uploaded to TigerFile when the gray bar beneath the file name turns green and shows the label “Uploaded” in the middle. There will also be a file size shown immediately to the right of the file name and a timestamp at the far right of the row.

Q.Is coding style important?

Adhering to coding style conventions is important because it makes code easier to read, understand, and maintain. You should fix all Checkstyle errors and warnings, such as line length, comments, and variable names, and ask for help (office hours, Lab TAs, Ed) if you’re unsure how to resolve them.

Q.May I use coding patterns or Java features that have not yet been taught in COS 126?

No. You are expected to use only the programming concepts, coding patterns, and Java language features that have been covered in COS 126 up to that point of the assignment. Assignments are designed to assess your understanding of the material that has been taught. You should use only the programming techniques and language features covered in the course or introduced specifically for the assignment. Using more advanced techniques or features, even if they produce the correct output, is not permitted and may result in a deduction of points.

Q.If my program passes all the test cases and has no warnings or error messages, does that guarantee a score of 100%, or are there additional grading criteria that could affect my grade?

It does not guarantee a score of 100%. On some assignments, we may not provide all the test cases to the autograder due to resource constraints. Examples of such test cases involve memory and timing tests. In addition, we reserve the right to grade manually when we believe our automated test cases are not robust enough.

Q.I believe my assignment was graded incorrectly. How do I request a regrade?

If you think there is an error in your feedback, please submit a regrade request via GradeScope within three days of release of your graded work.

Q.Can the same bug produce multiple warning/error messages?

Yes, absolutely. You should fix all reported errors and warnings. Ask for help (office hours, Lab TAs, Ed) if you’re unsure how to resolve them.

Q.Will all the test cases always be provided?

Most of the time, yes. However, due to the load on our server, we often will not provide memory and timing tests. We also retain the right to add additional tests if needed. That said, passing all the published test cases without any errors/warnings generally means you understood how to develop a solution to the assignment specification. Read all feedback carefully and ask questions if you need clarifications.

Exam Archive

Mon, 01 Jan 0001 00:00:00 +0000

Programming Exams on TigerFile.

Here are a few programming exams that are hosted on TigerFile. This will give you practice with downloading the exam/project folder from TigerFile in the same manner that you will do on real programming exam.

Some Past Exams and Solutions

Note - some older exams include topics we no longer cover. You are responsible only for this semester’s lectures, precepts, and programming assignments.

Semester	Written Exam 1	Programming Exam	Written Exam 2/Final Exam
Spring 2026	Exam Solution	Exam Project Solution	Exam Solution
Fall 2025	Exam Solution	Exam Project Solution	Exam Solution
Spring 2025	Exam Solution	Exam Project Solution	Exam Solution
Fall 2024	Exam Solution	Exam Project Solution	Exam Solution
Spring 2024	Exam Solution	Exam Project Solution	Exam Solution
Fall 2023	Exam Solution	Exam Project Solution	Exam Solution

Help

Mon, 01 Jan 0001 00:00:00 +0000

COS 126 is a challenging course, and getting help early makes a big difference. If you’re falling behind, be proactive: start by contacting your preceptor. If you’d rather not start there, contact the course instructors. We will be happy to meet with you.

Course Discussion Forum. Use Ed Discussion for quick questions. Staff monitor Ed regularly. Please do not post your assignment code on Ed, even in private posts.

Office Hours. For more substantial questions, come to office hours. You may attend any staff member’s office hours; see the calendar below. Office hours are appropriate for help with assignments, course concepts, or broader CS questions. Please review the relevant lecture and attempt the corresponding precept exercises before coming to office hours.

Intro COS Lab. The Intro COS Lab, located in Computer Science Building 105 is staffed by undergraduate TAs and can help you debug your code. Before coming, make a reasonable effort to identify the bug and isolate the problem. Please also attend the relevant lecture and attempt the corresponding precept exercises first.

Tutoring and additional academic support. The McGraw Center for Teaching & Learning offers additional academic support, including:

Not Available

Mon, 01 Jan 0001 00:00:00 +0000

The content you want to access is not available yet. If you believe this is an error, please post on Ed.

Resources

Mon, 01 Jan 0001 00:00:00 +0000

Course communications. We use Ed Discussion for course communications, including announcements and questions.

Programming environment. We use a customized version of IntelliJ, which provides a complete Java programming environment. Install it on your computer by following the instructions for your operating system: Mac OS X, Windows, or Linux. For troubleshooting, go to the Intro COS Lab.

Textbook. The course textbook is Computer Science: An Interdisciplinary Approach, by Robert Sedgewick and Kevin Wayne. Addison–Wesley Professional, 2016. ISBN 978-0134076423.

You can purchase it through Princeton’s eCampus bookstore.
The textbook is on reserve at the Engineering Library.
The companion booksite includes the book’s code and solutions to selected exercises.
Use the textbook to learn new material and to review for exams. Use the booksite while you are online.

Lecture participation. We use iClicker to make lectures more interactive. To earn participation credit, you must attend lecture and respond to iClicker polls. You must also register your mobile/web app:

If needed, create an iClicker account.
- Select Princeton University as the institution.
- Use your name, Princeton email address (as listed on Canvas), and NetID.
Select COS 126, Fall 2026 for the course.

Lecture recordings. We post lecture recordings in Canvas.

Precept exercises. Posted on Ed Lessons, along with solutions and additional practice exercises.

Java documentation. The following references summarize the Java constructs and APIs you will use throughout the course:

Java cheatsheet. Summarizes Java constructs and selected APIs used in this course.
Textbook libraries Javadoc. Provides detailed documentation for the textbook libraries.

Java visualizer. Visualize your code with the Java Visualizer.

Computers. If your laptop fails during the semester, there are a few options:

OIT can troubleshoot laptop issues.
McGraw Digital Learning Lab has computers setup with our programming environment.
Your residential college may offer loaner laptops.

Submitting assignments. We use the platform TigerFile for submitting programming assignments and programming exams. Each assignment will have its own TigerFile submission link.

Feedback and grading. Grades and feedback are distributed across several systems:

We post grades on Canvas.
We use Gradescope for feedback on programming assignments and written exams.
You will receive an invitation to join Gradescope.

Zoom. We may use Zoom for certain office hours.

Schedule

Mon, 01 Jan 0001 00:00:00 +0000

Click here for the precept schedule, including rooms and instructor

Note - this is subject to change.

Section	Days/Time	Room	Instructor
Lecture	Mon/Wed, 1:20pm–2:40pm	McCosh 50	Yuri Pritykin
Precept P10	Mon/Wed, 2:55pm-4:15pm	McDonnell 105	Max Gonzalez Saez-Diez
Precept P10A	Mon/Wed, 2:55pm-4:15pm	McDonnell 103A	Daniel Williams
Precept P10B	Mon/Wed, 2:55pm-4:15pm	Friend 009	Donna Gabai
Precept P01	Mon/Wed, 3:30pm-4:20pm	Friend 112	Sowmya Thanvantri
Precept P01A	Mon/Wed, 3:30pm-4:20pm	Friend 111	Kylie Zhang
Precept P02	Tue/Thu, 8:30am–9:20am	Andlinger 017	Abhishek Joshi
Precept P11 RPi	Tue/Thu, 9:00am-10:20am	Friend 007	Alan Kaplan
Precept P11A	Tue/Thu, 9:00am-10:20am	Friend 112	Nobline Yoo
Precept P03	Tue/Thu, 9:35am-10:25am	Andlinger 017	Ryan Oet
Precept P03A	Tue/Thu, 9:35am-10:25am	Bendheim House 103	Tim Kosfeld
Precept P04	Tue/Thu, 10:40am-11:30am	Andlinger 017	Kara Schechtman
Precept P04A	Tue/Thu, 10:40am-11:30am	Friend 007	Matthew Munoz
Precept P12	Tue/Thu, 10:40am-12:00pm	Friend 111	Reva Hirave
Precept P05	Tue/Thu, 12:15pm-1:05pm	Friend 112	Alan Zhang
Precept P05A	Tue/Thu, 12:15pm-1:05pm	Friend 111	David Shustin
Precept P06	Tue/Thu, 1:20pm-2:10pm	Friend 112	Donna Gabai

Course Schedule

Week	Date	Topic	Handouts \| Demos \| Assignments
0	Mon, Sep 1	Labor Day: No lecture
	Mon, Sep 1 Tue, Sep 2	No precepts
	Wed, Sep 3	Lecture: Introduction to COS 126 Lecture: Introduction to Java Reading: 1.1-1.2
	Wed, Sep 3 Thu, Sep 4	Precept: Hello World
	Sun, Sep 7		Assignment: Hello due
1	Mon, Sep 8	Lecture: Conditionals Reading: 1.2-1.3
	Mon, Sep 8 Tue, Sep 9	Precept: Conditionals

	Wed, Sep 10	Lecture: Loops Reading: 1.3
	Wed, Sep 10 Thu, Sep 11	Precept: Loops
	Sun, Sep 14		Assignment: Conditionals & Loops due
2	Mon, Sep 15	Lecture: Arrays Reading: 1.4	Demo: Shuffle Demo
	Mon, Sep 15 Tue, Sep 16	Precept: Arrays
	Wed, Sep 17	Lecture: Input & Output Reading: 1.5
	Wed, Sep 17 Thu, Sep 18	Precept: Input & Output
	Sun, Sep 21		Assignment: Arrays & IO due
3	Mon, Sep 22	Lecture: Functions Reading: 2.1	Demo: Function-Call Demo
	Mon, Sep 22 Tue, Sep 23	Precept: Functions
	Wed, Sep 24	Lecture: Libraries & Clients Reading: 2.2
	Wed, Sep 24 Thu, Sep 25	Precept: Libraries & Clients
	Sun, Sep 28		Assignment: Functions due
4	Mon, Sep 29	Lecture: Recursion Reading: 2.3	Demo: Factorial Demo
	Mon, Sep 29 Tue, Sep 30	Precept: Recursion
	Wed, Oct 1	Lecture: Performance Reading: 4.1
	Wed, Oct 1 Thu, Oct 2	Precept: Performance
	Sun, Oct 5		Assignment: Recursive Graphics due
5	Mon, Oct 6	Lecture: Introduction to Networking
	Mon, Oct 6 Tue, Oct 7	Precept: Written Exam 1 Review
	Wed, Oct 8	Written Exam 1
	Wed, Oct 8 Thu, Oct 9	Precept: None

	Mon, Oct 13 - Fri, Oct 17	BREAK

6	Mon, Oct 20	Lecture: Using Data Types Reading: 3.1
	Mon, Oct 20 Tue, Oct 21	Precept: Using Data Types
	Wed, Oct 22	Lecture: Creating Data Types Reading: 3.2
	Wed, Oct 22 Thu, Oct 23	Precept: Creating Data Types
	Sun, Oct 26		Assignment: Object-Oriented Programming due
7	Mon, Oct 27	Lecture: Designing Data Types Reading: 3.3
	Mon, Oct 27 Tue, Oct 28	Precept: Designing Data Types
	Wed, Oct 29	Lecture: Intro to Machine Learning Reading: 2 \| Machine Learning Paradigms
	Wed, Oct 29 Thu, Oct 30	Precept: Intro to Machine Learning
	Sun, Nov 2		Assignment: Image Classifier due
8	Mon, Nov 3	Lecture: Algorithms Reading: 4.2	Demo: Binary Search Demo Demo: Insertion Sort Demo Demo: Mergesort Demo
	Mon, Nov 3 Tue, Nov 4	Precept: Algorithms
	Wed, Nov 5	Lecture: Data Structures Reading: 4.3	Demo: Dijkstra Two Stack
	Wed, Nov 5 Thu, Nov 6	Precept: Data Structures
	Sun, Nov 9		Assignment: Guitar Hero due
9	Mon, Nov 10	Lecture: Theory of Computing Reading: 5.3-5.4
	Mon, Nov 10 Tue, Nov 11	Precept: Theory of Computing
	Wed, Nov 12	Lecture: Toy I Reading: 6.1-6.2
	Wed, Nov 12 Thu, Nov 13	Precept Toy I
	Sun, Nov 16		Assignment: Chat126 due
10	Mon, Nov 17	Lecture: Toy II Reading: 6.3-6.4
	Mon, Nov 17 Tue, Nov 18	Precept: Toy II
	Wed, Nov 19	Lecture: Circuits Reading: 7.1, 7.3
	Wed, Nov 19 Thu, Nov 20	Precept Circuits
	Sun, Nov 23		Assignment: Hamming due
11	Mon, Nov 24	Programming Exam
	Mon, Nov 24 Tue, Nov 25	No precept
	Wed, Nov 26 Thu, Nov 27	THANKSGIVING BREAK
12	Mon, Dec 1	Lecture: Introduction to Computational Biology
	Mon, Dec 1 Tue, Dec 2	Precept Java Jeopardy
	Wed, Dec 3	Written Exam 2
	Wed, Dec 3 Thu, Dec 4	No precept
13+	Mon, Dec 8	Lecture: Optional class session for Final Project	2:00-4:00pm in CS 105
	Sun, Dec 14		Final Project: Atomic due, 11:30am

Schedule

Mon, 01 Jan 0001 00:00:00 +0000

Click here for the precept schedule, including rooms and instructor

Section	Days/Time	Room	Instructor
Lecture	Mon/Wed, 1:20pm–2:40pm	McCosh 50	Kevin Wayne
Precept P01	Mon/Wed, 3:30pm-4:20pm
Precept P01A	Mon/Wed, 3:30pm-4:20pm
Precept P02	Tue/Thu, 8:30am–9:20am
Precept P03	Tue/Thu, 9:35am-10:25am
Precept P04	Tue/Thu, 10:40am-11:30am
Precept P04A	Tue/Thu, 10:40am-11:30am
Precept P05	Tue/Thu, 12:15pm-1:05pm
Precept P05A	Tue/Thu, 12:15pm-1:05pm
Precept P06	Tue/Thu, 1:20pm-2:10pm
Precept P10	Mon/Wed, 2:55pm-4:15pm
Precept P10A	Mon/Wed, 2:55pm-4:15pm
Precept P10B	Mon/Wed, 2:55pm-4:15pm
Precept P11	Tue/Thu, 9:00am-10:20am
Precept P12	Tue/Thu, 10:40am-12:00pm

Course Schedule

Week	Date	Topic	Handouts \| Demos \| Assignments
0	Mon, Jan 26	Lecture: Introduction to COS 126 Lecture: Hello, World Reading: 1.1
	Mon, Jan 26 Tue, Jan 27	Precept: Hello World
	Wed, Jan 28	Lecture: Data Types Reading: 1.2
	Wed, Jan 28 Thu, Jan 28	Precept: Data Types
	Sun, Feb 1		Assignment: Hello due
1	Mon, Feb 2	Lecture: Conditionals Reading: 1.3
	Mon, Feb 2 Tue, Feb 3	Precept: Conditionals

	Wed, Feb 4	Lecture: Loops Reading: 1.3
	Wed, Feb 4 Thu, Feb 5	Precept: Loops
	Sun, Feb 8		Assignment: Conditionals & Loops due
2	Mon, Feb 9	Lecture: Arrays Reading: 1.4	Demo: Shuffle Demo
	Mon, Feb 9 Tue, Feb 10	Precept: Arrays
	Wed, Feb 11	Lecture: Input & Output Reading: 1.5
	Wed, Feb 11 Thu, Feb 12	Precept: Input & Output
	Sun, Feb 15		Assignment: Arrays & IO due
3	Mon, Feb 16	Lecture: Functions Reading: 2.1	Demo: Function-Call Demo
	Mon, Feb 16 Tue, Feb 17	Precept: Functions
	Wed, Feb 18	Lecture: Libraries & Clients Reading: 2.2
	Wed, Feb 18 Thu, Feb 19	Precept: Libraries & Clients
	Sun, Feb 22		Assignment: Functions due
4	Mon, Feb 23	Lecture: Recursion Reading: 2.3	Demo: Factorial Demo
	Mon, Feb 23 Tue, Feb 24	Precept: Recursion
	Wed, Feb 25	Lecture: Performance Reading: 4.1
	Wed, Feb 25 Thu, Feb 26	Precept: Performance
	Sun, Mar 1		Assignment: Recursive Graphics due
5	Mon, Mar 2	Lecture: Midterm Review
	Mon, Mar 2 Tue, Mar 3	Precept: Midterm Review
	Wed, Mar 4	Midterm
	Wed, Mar 5 Thu, Mar 6	Precept: None

	Mon, Mar 9 - Fri, Mar 13	BREAK

6	Mon, Mar 16	Lecture: Using Data Types Reading: 3.1
	Mon, Mar 16 Tue, Mar 17	Precept: Using Data Types
	Wed, Mar 18	Lecture: Creating Data Types Reading: 3.2
	Wed, Mar 18 Thu, Mar 19	Precept: Creating Data Types
	Sun, Mar 22		Assignment: Object-Oriented Programming due
7	Mon, Mar 23	Lecture: Designing Data Types Reading: 3.3
	Mon, Mar 23 Tue, Mar 24	Precept: Designing Data Types
	Wed, Mar 25	Lecture: Intro to Machine Learning Reading: 2 \| Machine Learning Paradigms
	Wed, Mar 25 Thu, Mar 26	Precept: Intro to Machine Learning
	Sun, Mar 29		Assignment: Image Classifier due
8	Mon, Mar 30	Lecture: Algorithms Reading: 4.2	Demo: Binary Search Demo Demo: Insertion Sort Demo Demo: Mergesort Demo
	Mon, Mar 30 Tue, Mar 31	Precept: Algorithms
	Wed, Apr 1	Lecture: Data Structures Reading: 4.3	Demo: Dijkstra Two Stack
	Wed, Apr 1 Thu, Apr 2	Precept: Data Structures
	Sun, Apr 5		Assignment: Guitar Hero due
9	Mon, Apr 6	Lecture: Theory of Computing Reading: 5.3-5.4
	Mon, Apr 6 Tue, Apr 7	Precept: Theory of Computing
	Wed, Apr 8	Lecture: Toy I Reading: 6.1-6.2
	Wed, Apr 8 Thu, Apr 9	Precept Toy I
	Sun, Apr 12		Assignment: Chat126 due
10	Mon, Apr 13	Lecture: Toy II Reading: 6.3-6.4
	Mon, Apr 13 Tue, Apr 14	Precept: Toy II
	Wed, Apr 15	Programming Exam
	Wed, Apr 15 Thu, Apr 16	Precept Java Jeopardy
	Sun, Apr 19		Assignment: Hamming due
11	Mon, Apr 20	Lecture: Circuits Reading: 7.1, 7.3
	Mon, Apr 20 Tue, Apr 21	Precept Circuits
	Wed, Apr 22	Written Exam 2
	Wed, Apr 22 Thu, Apr 23	No precept
12			READING WEEK
13	Wed, May 5		Project: Atomic due 5:00pm
14	Wed, May		Final Exam: TBD

Schedule

Mon, 01 Jan 0001 00:00:00 +0000

Click here for the precept schedule, including rooms and instructor.

Note - this is subject to change.

Section	Meetings	Room	Instructor
Lecture L01	Mon/Wed, 1:20–2:40pm	McCosh 50	Adam Finkelstein/Maryam Hedayati
Precept P01	Mon/Wed, 3:30–4:20pm	Friend 112	Matthew Munoz
Precept P01A	Mon/Wed, 3:30–4:20pm	Friend 007	Reva Hirave
Precept P02	Tue/Thu, 8:30–9:20am	Friend 007	James Zhang
Precept P03	Tue/Thu, 9:35–10:25am	Friend 007	Alan Kaplan
Precept P03A	Tue/Thu, 9:35–10:25am	Friend 112	Donna Gabai
Precept P04	Tue/Thu, 10:40–11:30am	Friend 007	John Luo
Precept P04A	Tue/Thu, 10:40–11:30am	Friend 112	Michelle Le
Precept P05	Tue/Thu, 12:15–1:05pm	Friend 110	Slater Fisch
Precept P05A	Tue/Thu, 12:15–1:05pm	Friend 007	Liz Austell
Precept P06	Tue/Thu, 1:20–2:10pm	Bend House 103	Donna Gabai
Precept P10	Mon/Wed, 2:55–4:15pm	Friend 111	Maryam Hedayati
Precept P11	Tue/Thu, 9:00–10:20am	Friend 111	Arnold Caleb Asiimwe
Precept P13 (RPi)	Tue/Thu, 1:20-2:40pm	Friend 005	Brian Phillips

Course Schedule

Week	Date	Topic	Handouts \| Demos \| Assignments
0	Wed, Sep 2	Lecture: Introduction to COS 126 Lecture: Hello, World Reading: 1.1
	Wed, Sep 2 Thu, Sep 3	Precept: Hello World
	Wed, Sep 9	Lecture: Data Types Reading: 1.2
	Wed, Sep 9 Thu, Sep 10	Precept: Data Types
	Sun, Sep 13		Assignment due: Hello
1	Mon, Sep 14	Lecture: Conditionals Reading: 1.3
	Mon, Sep 14 Tue, Sep 15	Precept: Conditionals

	Wed, Sep 16	Lecture: Loops Reading: 1.3
	Wed, Sep 16 Thu, Sep 17	Precept: Loops
	Sun, Sep 20		Assignment due: Conditionals and Loops
2	Mon, Sep 21	Lecture: Arrays Reading: 1.4	Demo: Shuffle
	Mon, Sep 21 Tue, Sep 22	Precept: Arrays
	Wed, Sep 23	Lecture: Input and Output Reading: 1.5
	Wed, Sep 23 Thu, Sep 24	Precept: Input and Output
	Sun, Sep 27		Assignment due: Arrays and IO
3	Mon, Sep 28	Lecture: Functions Reading: 2.1	Demo: Function Call
	Mon, Sep 28 Tue, Sep 29	Precept: Functions
	Wed, Sep 30	Lecture: Libraries and Clients Reading: 2.2
	Wed, Sep 30 Thu, Oct 1	Precept: Libraries and Clients
	Sun, Oct 4		Assignment due: Functions
4	Mon, Oct 5	Lecture: Recursion Reading: 2.3	Demo: Factorial
	Mon, Oct 5 Tue, Oct 6	Precept: Recursion
	Wed, Oct 7	Lecture: Performance Reading: 4.1
	Wed, Oct 7 Thu, Oct 8	Precept: Performance
	Sun, Oct 11		Assignment due: Recursive Graphics
5	Mon, Oct 12	Lecture: Midterm Review
	Mon, Oct 12 Tue, Oct 13	Precept: Midterm Review
	Wed, Oct 14	Midterm
	Wed, Oct 14 Thu, Oct 15	Precept: None

	Mon, Oct 19 - Fri, Oct 23	FALL BREAK

6	Mon, Oct 26	Lecture: Using Data Types Reading: 3.1
	Mon, Oct 26 Tue, Oct 27	Precept: Using Data Types
	Wed, Oct 28	Lecture: Creating Data Types Reading: 3.2
	Wed, Oct 28 Thu, Oct 29	Precept: Creating Data Types
	Sun, Nov 1		Assignment due: OOP
7	Mon, Nov 2	Lecture: Designing Data Types Reading: 3.3
	Mon, Nov 2 Tue, Nov 3	Precept: Designing Data Types
	Wed, Nov 4	Lecture: Algorithms Reading: 4.2	Demo: Binary Search Demo: Insertion Sort Demo: Mergesort
	Wed, Nov 4 Tue, Nov 5	Precept: Algorithms
	Sun, Nov 8		Assignment due: Guitar Hero
8	Mon, Nov 9	Lecture: Data Structures Reading: 4.3	Demo: Dijkstra Two Stack
	Mon, Nov 9 Tue, Nov 10	Precept: Data Structures
	Wed, Nov 11	Lecture: Theory of Computing Reading: 5.3-5.4
	Wed, Nov 11 Thurs, Nov 12	Precept: Theory of Computing
	Sun, Nov 15		Assignment due: Chat126
9	Mon, Nov 16	Lecture: Intro to Machine Learning Reading: Machine Learning Paradigms
	Mon, Nov 16 Tue, Nov 17	Precept: Intro to Machine Learning
	Wed, Nov 18	Lecture: Intro to Deep Learning
	Wed, Nov 18 Thu, Nov 19	Precept: ML-2
	Sun, Nov 22		Assignment due: Image Classifier
	Mon, Nov 23	Lecture: Networking
	Wed, Nov 18 Thu, Nov 19	Precept: Networking

	Wed, Nov 25 - Fri, Nov 27	THANKSGIVING BREAK

10	Mon, Nov 30	Lecture: Toy I Reading: 6.1-6.2	Demo: TOY Machine
	Mon, Nov 30 Tues, Dec 1	Precept: Toy I
	Wed, Dec 2	Lecture: Toy II Reading: 6.3-6.4
	Wed, Dec 2 Thu, Dec 3	Precept: Toy II
	Sun, Dec 6		Assignment due: Hamming
11	Mon, Dec 7	Lecture: Circuits Reading: 7.1, 7.3
	Mon, Dec 7 Tue, Dec 8	Precept: Circuits
12		READING PERIOD
13	Tue, Dec 15	Dean’s Date	Project due 5pm: Atomic
14	Sun, Dec 20	Final Exam	4:00pm - 07:00 pm

Syllabus

Mon, 01 Jan 0001 00:00:00 +0000

Course Description

COS 126 introduces computer science through scientific, engineering, and commercial applications. You will learn fundamental principles and practical programming skills that prepare you to use computers effectively in fields such as computer science, physics, biology, chemistry, and engineering. The course uses Java to introduce fundamental programming concepts, including conditionals, loops, arrays, functions, and object-oriented programming. Additional topics include algorithms and data structures; principles of computation; hardware and software systems; and machine learning.

Course Communications

We use Ed Discussion for course announcements and the course discussion forum. Start there if you have a question; post publicly when possible and privately for personal matters. For office hours, Lab TAs, and other support options, see the Help page.

Textbook

Computer Science: An Interdisciplinary Approach, by Robert Sedgewick and Kevin Wayne. Addison–Wesley Professional, 2016. ISBN 978-0134076423.

We use this text throughout the semester; lectures and precepts follow it closely.

Course Organization

This course includes lectures, precepts, programming assignments, code reviews, a programming project, a midterm exam, and a final exam.

Lectures. Class meets twice per week. Lectures introduce new content and motivate the week’s topics.

iClickers. We use iClicker to make lectures more interactive. To earn participation credit, you must attend lecture and submit responses to at least 50% of the iClicker poll questions. You may not use a classmate’s iClicker or allow someone else to use yours.
Lecture recordings. We record lectures and post in Canvas. The system is set up not to capture student voices, but if you speak loudly it might be audible.
Lecture absences. The first four lecture absences are automatically waived. This accounts for illnesses, religious observances, varsity athletic competitions, late course enrollment, and technical issues with the iClicker app.
Waivers beyond the four waived absences. To request a participation waiver beyond the four waived absences, post privately on Ed with a brief explanation.

Precepts. Precepts meet twice per week. In a small group, your preceptor will review key learning objectives from the week’s lectures and lead interactive exercises and discussion, often in pairs.

Precept absences. The first four absences are automatically waived. This accounts for illnesses, religious observances, varsity athletic competitions, and late course enrollment.
Waivers beyond the four waived absences. To request a participation waiver beyond the four waived absences, post privately on Ed with a brief explanation.
Attending another precept. If you cannot attend your assigned precept, you may occasionally attend another precept. Notify both your regular preceptor and the preceptor you plan to visit.
Reviewing precept. If you miss a precept, see the materials on Ed Lessons.

Programming Assignments. There are ten programming assignments, equally weighted.

Late work. Assignments are due Sundays at 11:59pm ET. If any part of an assignment is submitted late, the entire assignment is late.
Late penalties. Late work receives a penalty of 10% of the assignment’s total points per day (or partial day).
Free late days. Your first four late days are automatically waived. This accounts for illnesses, religious observances, travel, and late course enrollment.
Extensions beyond the four free late days. Extensions beyond the four free late days require a documented medical or personal emergency and a recommendation from your Residential College Dean. To request one, post privately on Ed.
Late days and partners. If you work with a partner, late penalties apply to the group. The number of waived late days available to the group is the minimum number remaining among the partners.
Submission signal. We will not grade your submission until acknowledgments.txt is submitted. If you plan to submit late, do not submit that file until you are finished and ready for grading.

Code Reviews. You must attend four code review sessions (20 minutes each) to review your graded programming assignments, clarify feedback (grader comments, warnings, error messages, and deductions), and discuss style and design. You will be asked to explain your code.

Credit: credit is based on attendance, participation, and understanding of your code. UCAs will grade only on participation; grad TAs and faculty members will grade both on attendance and understanding. There will be a grade penalty for no-shows and rescheduling past the scheduling deadline.
Sign-up: details forthcoming.
Partners: for partner submissions, partners will complete code reviews separately. Both partners should understand and be able to explain all of their submitted code.

Programming Project. The project is a capstone that integrates topics from across the course. It is about the size of two programming assignments.

Partner: you are encouraged to work with a partner.
Late policy: late days may not be used on the project.

Exams. There is one in-class midterm exam and one final exam.

Midterm exam: in class on Wednesday, October 14.
Final exam: Sunday, December 20 4pm-7pm, room TBD.
Rescheduling: Exams are rescheduled only in the event of a personal emergency. In-class exams requires a recommendation from a Residential College Dean and approval from the instructor. Final exam postponements require approval from the Registrar.

Regrades. If you believe your work was graded incorrectly (or your participation was recorded incorrectly), submit a regrade request within three days of the grade being posted:

Written exams: submit via Gradescope.
Programming assignments/project: submit via Gradescope.
Lecture and precept participation: post privately on Ed.

Course Grades

Your course grade will be calculated based on a weighted sum of the programming assignments, code reviews, programming project, exams, and participation.

Component	Weight
Programming Assignments (Code testing)	18%
Programming Assignments (Code reviews)	12%
Project	5%
Midterm Exam	25%
Final Exam	35%
Participation	5%
Total	100%

Letter grades. Cutoffs are set at semester end and are not curved to a fixed distribution. The following thresholds guarantee at least the listed grade: A (93.0), A– (90.0), B+ (87.0), B (83.0), B– (80.0), C+ (77.0), C (73.0), C– (70.0), D (60.0). Grades are not rounded.

Course Collaboration Policy

This collaboration policy applies to all programming assignments and the project (both are referred to as “assignments” below). We encourage collaboration with course staff, classmates, and lab TAs, but only as permitted below. Here is an executive summary:

	your partner	course staff	COS 126 alums	COS 126 students	generative AI	other
discuss concepts with …	yes	yes	yes	yes	yes	yes
acknowledge collaboration with …	yes	yes	yes	yes	yes	yes
show your code/solutions to …	yes	yes	yes	no	no	no
view any code/solutions from …	yes	no	no	no	no	no
copy any code/solutions from …	yes	no	no	no	no	no

Concepts vs. assignment-specific code. You may discuss general concepts with classmates, but you may not discuss assignment-specific code. For example, you may discuss the syntax of a for loop or how to read a sequence of numbers, but you may not show, share, or review solution code with another student currently enrolled in COS 126.

Course materials. The course materials are sufficient to succeed in COS 126. They include the textbook and companion booksite, the course website, lecture slides, and precepts.

Using outside resources. You may use outside resources to clarify lecture, reading, precept, and past-exam material. If you learn a technique from an external source and apply it on an assignment, it must be within the scope of the course, and you must cite the source in acknowledgments.txt. Be cautious with AI-integrated tools: they may produce inaccurate, incomplete, or out-of-scope guidance.

Permitted resources for assignments. Once you start a programming assignment, you may use only course-approved resources. “Starting” includes reading the specification; downloading the project files; and any design, coding, debugging, or testing.

Collaboration with generative AI (GAI). You may not use generative AI for any part of a graded assessment in this course (programming assignments, the project, or exams). This includes using GAI to summarize specifications, generate solution ideas, write code, debug, add comments, or format work. This prohibition applies to general-purpose AI systems (e.g., ChatGPT, Gemini, and Claude), AI coding assistants (e.g., Copilot, Cursor, and JetBrains Assistant), and AI-assisted web search.

Rationale: A core learning outcome of COS 126 is developing your own problem-solving and programming skills. GAI can be helpful in many settings, but you must be able to reason about code and evaluate correctness independently. These skills are essential regardless of your major and will prepare you to use AI tools responsibly in later coursework and beyond.

If you are unsure whether a tool or use case is permitted, ask the course staff before using it.

Your solutions. You must compose your solutions independently. “Solutions” includes everything you create for a graded assessment, including source code (and comments) and readme.txt. It includes both draft and final work, whether correct or complete.

You may not share, expose, or make your solutions accessible to anyone who is taking COS 126 now or might take it in the future. Do not post solutions publicly (e.g., on a website or public repository), and do not leave printouts or files in shared locations. If you step away from your computer, lock it.
You may not access any solutions other than your own. This includes other students’ work, solutions found online, and code produced by Generative AI tools.

These rules remain in effect after the semester ends.

Collaboration with course staff. You may discuss your solutions with course staff (instructors and preceptors) during office hours or via private Ed posts. Do not post code on Ed or email us code. If we need to review your program, submit it on TigerFile.

Collaboration with COS 126 classmates. You are encouraged to discuss general concepts with classmates, either privately or on Ed. Keep these discussions at a general level and do not share, view, or review assignment solutions. If a classmate helps you, they must not look at their own solution while doing so.

For example, you may discuss:	But, you may not:
How to interpret an error message. For example, “What does `StackOverflowError` mean?”	Access a classmate’s solutions (or allow a classmate to access your solutions).
The meaning of a piece of Java syntax. For example, “What is the purpose of the clause `Queue<String>`”?	Lead a classmate step-by-step through any part of the assignment (or allow a classmate to do the same for you).
How to use a feature in IntelliJ or bash. For example, “How do I start the embedded terminal?”	Refer to your solutions while helping a classmate (or receive help from a classmate while they are referring to their solutions).
Clarifications for the lectures, textbook, or assignment specifications.
Solutions to book/booksite/precept exercises or old exam questions.

Collaboration with students who have already taken COS 126. Anyone who successfully completed COS 126 in a prior term, including lab TAs and peer tutors, may assist you under the following rules:

They must not look at any other solutions, including their own, while helping you.
They may look at your code.
They must not write, type, or dictate code.
They may help you debug, but they must not provide step-by-step directions for completing the assignment.
They should offer high-level, thought-provoking suggestions rather than telling you exactly what to change.

Collaboration acknowledgment. You must acknowledge all collaboration in acknowledgments.txt. Include the names and dates of any lab TAs, instructors, preceptors, and/or students who provided assistance. Also cite any outside resources you used.

Collaboration with a partner

Some assignments permit partnering. You are not required to partner, but we strongly recommend partnering on at least one partnered assignment. Pair programming helps you communicate about code, catch mistakes earlier, and often makes the work more efficient and less frustrating.

Group size. At most two partners per group.
Eligibility. Your partner must be a current COS 126 student (not necessarily in your precept).
Choosing a partner. The best experience is usually with a similarly skilled partner.
Switching partners. You may change partners between assignments.
Work together. Complete all work together while sharing one screen, including design, coding, debugging, testing, commenting, writing readme.txt and acknowledgments.txt, and submitting files.
No splitting. You may not divide tasks or work separately.
Help sessions. Attend office hours or the COS Lab together.
Pair-programming protocol. Use driver/navigator roles: the driver types; the navigator reviews, asks questions, and spots bugs. Swap roles about every 30 minutes.
Protect your work. Do not store or share code in a way that is accessible to anyone other than you and your partner. Shared private storage (e.g., Google Drive or Dropbox) is allowed.
Late days. Late penalties apply to the group. The number of waived late days available to the group is the minimum remaining among the partners.
Acknowledgment. In acknowledgments.txt, both partners must state that they followed the partnering rules.
Ending a partnership. To dissolve a partnership, contact the course administrator.

Plagiarism

Plagiarism and abetting plagiarism are serious academic violations. Programming is a creative work, and the standards that apply to plagiarized prose also apply to plagiarized code. Princeton’s Rights, Rules, Responsibilities defines plagiarism as using “the use of any outside source without proper acknowledgment.” This includes verbatim copying (e.g., copy-and-paste) and thorough paraphrasing (e.g., renaming variables or rearranging code).

Citations. If you copy or adapt any code, you must cite the source in acknowledgments.txt. A citation is not required for code taken directly from the assignment specification.

Plagiarism detection. We use software tools to flag submissions for review for potential plagiarism, including paraphrased code. We compare each submission (including interim submissions) against a database that includes submissions from this offering, prior offerings, and other sources. These checks may occur during the semester or after it ends.

Penalties. We refer alleged academic violations (e.g., plagiarism, abetting plagiarism, and failure to disclose the use of generative AI) to the Faculty–Student Committee on Discipline (CoD). We do not bring cases lightly, but we must keep the playing field fair for students who follow the rules.

If you are found responsible, you will receive a zero on the assignment, along with any additional penalties imposed by the CoD. Findings involving multiple assignments may result in more serious course penalties, including a failing course grade.

Regret clause. If you neglected to cite a source (or disclose the use of generative AI), you may update acknowledgments.txt at any time before Dean’s Date and notify the course staff. If you used an unauthorized source, you will likely receive a zero on the assignment for violating course policy. However, with proper acknowledgments, it is not plagiarism (or failure to disclose the use of generative AI), and we will not refer the case to the CoD. Once a CoD case has been submitted, the regret clause no longer applies.

The Atomic Nature of Matter

Mon, 01 Jan 0001 00:00:00 +0000

Download project ZIP | Submit to TigerFile

Getting Started

Review Section 2.4 in the textbook, especially the part on depth-first search.
Download and unzip atomic.zip , then open the atomic project in IntelliJ.
You make work with a partner on this project subject to these partnering rules.

Historical Perspective

Atoms played a central role in 20th-century physics and chemistry, but before 1908 the reality of atoms and molecules was not universally accepted. In 1827, the botanist Robert Brown observed the random, erratic motion of microscopic particles suspended in fluid. This phenomenon later became known as Brownian motion. Einstein hypothesized that the motion arises from countless collisions with much smaller particles, namely atoms and molecules.

In one of his 1905 “miracle year” papers, Einstein developed a quantitative theory of Brownian motion to help justify the existence of atoms as real, finite entities. His theory gave experimentalists a way to estimate molecular quantities using an ordinary microscope by observing the collective effect of many molecular collisions on a larger immersed particle. In 1908, Jean-Baptiste Perrin validated Einstein’s kinetic theory experimentally, providing direct evidence for the atomic nature of matter. Perrin’s experiments also yielded one of the earliest estimates of Avogadro’s number. For this work, he won the 1926 Nobel Prize in Physics.

The Problem

In this project, you will reproduce a modern version of Perrin’s experiment. Your job is greatly simplified because modern video and computer technology, combined with your programming skills, makes it possible to measure and track the motion of an immersed particle undergoing Brownian motion accurately. We provide video microscopy data of polystyrene spheres (beads) suspended in water.

The project has three pats:

identify beads in each frame,
track beads between consecutive frames to measure their displacements, and
analyze the displacement data by fitting Einstein’s model and estimating Avogadro’s number.

The Data

We provide 10 datasets, collected by William Ryu using fluorescent imaging. Each dataset is stored in a subdirectory named run_1 through run_10 and contains a sequence of 200 640-by-480 color images named frame00000.jpg through frame00199.jpg.

Here is a movie of several beads undergoing Brownian motion.

There should have been a video here but your browser does not seem to support it.

Below is a typical raw image (left) and a cleaned up version (right) produced by thresholding, as described below.

Each image shows a two-dimensional cross section of a microscope slide. The beads move within the the microscope’s field of view (the $x$- and $y$-directions). They also move in the $z$-direction, entering and leaving the microscope’s depth of focus. As a result, beads may appear with halos or disappear from the image entirely.

I. Particle Identification

Your first task is to identify beads in noisy images. Each image is 640-by-480 pixels. Each pixel is a Color object; convert it to a luminance (intensity) value between 0.0 (black) and 255.0 (white).

Whiter pixels correspond to beads (foreground) and darker pixels to water (background). The task has three steps:

Reading the image. Use the Picture data type to read the image.
Classifying the pixels as foreground or background. Use thresholding to separate foreground from background: pixels with luminance strictly below a threshold $\tau$ are background; all others are foreground. The example images above use $\tau = 180.0$. Use the intensity() method from Luminance.java.
Finding the beads. A bead appears as a roughly disc-shaped region of at least $min$ connected foreground pixels (typically 25). A blob (connected component) is a maximal set of connected foreground pixels, regardless of shape. We call any blob with at least $min$ pixels a bead. The center of mass of a blob is the average of the $x$- and $y$-coordinates of its pixels.

Create a helper data type Blob that has the following API.

       public class Blob {
            //  Creates an empty blob.
            public Blob()                          

            //  Adds pixel (x, y) to this blob.
            public void add(int x, int y)          

            //  Returns the number of pixels in this blob.
            public int mass()                      

            //  Euclidean distance between the centers of mass of the two blobs.
            public double distanceTo(Blob that)    

            //  Returns a string representation of this blob (see below).
            public String toString()               

            //  Tests this class by calling all instance methods directly.
            public static void main(String[] args) 
	}

Here are some details about the required behavior:

Coordinates. In this API, $x$ is the column index and $y$ is the row index.
Center of mass. The center of mass is the average of the pixels’ $x$- and $y$-coordinates.
String representation. The toString() method returns a string that contains, in order:
- the blob’s mass,
- one space character,
- the center of mass in the form $(x, y)$
- $x$ and $y$ formatted with four digits after the decimal point.
Performance requirement. The constructor and each instance method must run in constant time.

Next, implement a data type BeadFinder with the following API. Use depth-first search to find connected components (blobs) in the thresholded image efficiently.

        public class BeadFinder {
            //  Finds all blobs in the given picture using luminance threshold tau.
            public BeadFinder(Picture picture, double tau)

            //  Returns all beads (blobs with >= min pixels).
            public Blob[] getBeads(int min)

            //  Test client (see below).
            public static void main(String[] args)
        }

The main() method takes three command-line arguments: an integer min, a floating-point number tau, and an image filename. It constructs a BeadFinder with threshold tau and print all beads (blobs with at least min pixels), as shown here:

~/Desktop/atomic> java-introcs BeadFinder 0 180.0 run_1/frame00001.jpg
29 (214.7241,  82.8276)
36 (223.6111, 116.6667)
 1 (254.0000, 223.0000)
42 (260.2381, 234.8571)
35 (266.0286, 315.7143)
31 (286.5806, 355.4516)
37 (299.0541, 399.1351)
35 (310.5143, 214.6000)
31 (370.9355, 365.4194)
28 (393.5000, 144.2143)
27 (431.2593, 380.4074)
36 (477.8611,  49.3889)
38 (521.7105, 445.8421)
35 (588.5714, 402.1143)
13 (638.1538, 155.0000)

~/Desktop/atomic> java-introcs BeadFinder 25 180.0 run_1/frame00001.jpg
29 (214.7241,  82.8276)
36 (223.6111, 116.6667)
42 (260.2381, 234.8571)
35 (266.0286, 315.7143)
31 (286.5806, 355.4516)
37 (299.0541, 399.1351)
35 (310.5143, 214.6000)
31 (370.9355, 365.4194)
28 (393.5000, 144.2143)
27 (431.2593, 380.4074)
36 (477.8611,  49.3889)
38 (521.7105, 445.8421)
35 (588.5714, 402.1143)

In the sample frame, there are 15 blobs, 13 of which are beads.

Q.Can I assume the image dimensions are all 640-by-480?

No, your solution should handle images of any dimension.

Q.My program prints the same beads, but in a different order. Is that okay?

Yes. The output order depends on how you store blobs and how you traverse the image (row-major vs. column-major).

Q.What are the conventions for pixels in a Picture?

By convention, pixels are indexed by $(col, row)$. The first argument to get() is the column (increasing left-to-right) and the second is the row (increasing top-to-bottom).

II. Particle Tracking

The next step is to determine how far a bead moves time $t$ to time $t + \Delta t$. For our data, $\Delta t = 0.5$ seconds between frames. Assume each bead moves only a small amount between frames and that beads never collide. Beads may disappear between frames by leaving the field of view ($x$ or $y$) or by moving out of focus ($z$).

To track beads between consecutive frames, do the following: for each bead at time $t + \Delta t$, find the closest bead at time $t$ (Euclidean distance) and treat the pair as the same bead. If the distance exceeds $\Delta$ pixels, assume that one of the beads has either just appeared or just disappeared.

Next, write BeadTracker.java with a main() method:

Read min, tau, delta, and the image filenames from the command line.
For each pair of consecutive frames, identify beads in both images using BeadFinder.
Print each displacement (distance moved) that is at most delta, formatted with four digits after the decimal point, one per line, in the order discovered.

~/Desktop/atomic> java-introcs BeadTracker 25 180.0 25.0 run_1/*.jpg
7.1833
4.7932
2.1693
5.5287
5.4292
4.3962
...

Q.Do I need to track individual beads across multiple frames?

No. Although tracking beads across many frames can be more accurate, this assignment only requires comparing beads in two consecutive frames.

III. Data Analysis

Einstein’s theory of Brownian motion links microscopic bead properties (such as radius and diffusivity) to macroscopic fluid properties (such as temperature and viscosity). Using video microscopy, we can estimate Avogadro’s number by observing the collective effect of many water molecules on a bead.

Estimating the self-diffusion constant. The self-diffusion constant $D$ describes the random motion of a bead in water due to thermal collisions.

Model. In one dimension, the Einstein–Smoluchowski equation implies that a bead’s displacement over time $\Delta t$ has mean $0$ and variance $\sigma^2 = 2 D \Delta t$.

Estimation. Estimate $\sigma^2$ by averaging the squared displacements in the $x$- and $y$-directions.
- Let $(\Delta x_1, \Delta y_1), \ldots, (\Delta x_n, \Delta y_n)$ be the $n$ observed displacements (in pixels).
- Convert pixels to meters: BeadTracker reports pixels, but the formula uses meters. To convert pixels to meters, multiply by $0.175 \times 10^{-6}$ (meters per pixel).
- Let $r_1, \ldots, r_n$ denote the radial displacements.
- $ \sigma^2 \; = \; \dfrac{(\Delta x^2_1+ \cdots + \Delta x^2_n) + (\Delta y^2_1+\cdots+\Delta y^2_n)}{2n} \; = \; \dfrac{r^2_1+\cdots+r^2_n}{2n} $
- For our data, $\Delta t = 0.5$, so $D \approx \sigma^2$.

Estimating the Boltzmann constant. The Boltzmann constant $k$ is a fundamental physical constant that relates a molecule’s average kinetic energy to its temperature. The Stokes–Einstein relation $$D = \dfrac{k\, T}{6 \, \pi \, \eta \, \rho}.$$ expresses the self-diffusion constant $D$ of a spherical bead in terms of $k$, the temperature $T$, the viscosity $\eta$, and the bead radius $\rho$. For our data:

$T = 297 \text{K}$,
$\eta = 9.135 \times 10^{-4} \; \text{N} \cdot \text{s} \cdot \text{m}^{-2}$, and
$\rho = 0.5 \times 10^{-6} \text{m}$.

Solve the Stokes–Einstein equation for $k$ using your estimate of $D$.

Estimating Avogadro’s number. Avogadro’s number $N_A$ is the number of particles in one mole.

Since $k = R / N_A$, we have $N_A = R / k$, where $R \approx 8.31446 J \cdot \text{mol}^{-1} \cdot \text{K}^{-1}$ is the universal gas constant.
Use $R / k$ as your estimate of Avogadro’s number $N_A$.

Write Avogadro.java. For the final part, write Avogadro.java with a main() method that:

reads the radial displacements $r_1, r_2, r_3, \ldots$ from standard input;
estimates Boltzmann’s constant $k$ and Avogadro’s number $N_A$ using the formulas above; and
prints $k$ and $N_A$ in scientific notation with four digits after the decimal point.

Here are a few sample executions. Your output should match exactly, including formatting:

~/Desktop/atomic> more displacements-run_1.txt
 7.1833
 4.7932
 2.1693
 5.5287
 5.4292
 4.3962
...

~/Desktop/atomic> java-introcs Avogadro < displacements-run_1.txt
Boltzmann = 1.2535e-23
Avogadro  = 6.6329e+23

~/Desktop/atomic> java-introcs BeadTracker 25 180.0 25.0 run_1/*.jpg | java-introcs Avogadro
Boltzmann = 1.2535e-23
Avogadro  = 6.6329e+23

Q.Do I need to worry about converting units?

All parameters are given in SI units. The only conversion you need to do is from pixels to meters, as described above.

Q.My output matches the reference output, except sometimes they are off by 0.0001. Why could cause this?

It is likely a combination of floating-point roundoff error and printing only 4 digits after the decimal point. For example, this discrepancy can arise if one solution computes the value 0.12345 (which gets rounded up to 0.1235) and another computes the value 0.1234499999999 (which gets rounded down to 0.1234). You need not worry about such discrepancies on this assignment.

Q.Can I use Java’s built-in libraries?

You are free to use and of the libraries introduced in the course, including java.util.ArrayList.

Possible Progress Steps

Click here to show possible progress steps for Blob

Observe that each directory run_1, run_2, …, run_9 contains a sequence of 200 JPEG images. In total, these data files consume 70MB of space. The file beads-run_1.txt lists the beads found in each frame of run_1 (using tau = 180.0 and min = 25). The files displacements-run_1.txt and displacements-run_2.txt are the output of BeadTracker for those runs.
Implement the Blob data type. Do not store all of the individual pixels that comprise a blob; instead, store three values. Two alternatives are:
- number of pixels, $x$-coordinate center of mass, and $y$-coordinate center of mass or
- number of pixels, sum of $x$-coordinates, and sum of $y$-coordinates needed to compute the center of mass.
Recall the main() method is used to write your test client. This is where you should thoroughly test your Blob implementation. For example, create various Blob objects and call the various Blob methods on these objects.
Some FAQs:

How can I implement the toString() method to format the numbers? Use String.format(). It works like StdOut.printf(), but returns the resulting string instead of printing it. See pp. 130–132 of the textbook to learn more about formatted printing.
Which value should distanceTo() return if the mass of one or both blobs is zero? We recommend Double.NaN. Since this corner case is not specified in the API, we will not test it.
What should toString() return if the mass is zero? We recommend returning the value "0 (NaN, NaN)". Since this corner case is not specified in the API, we will not test it.

Click here to show possible progress steps for BeadFinder

This is the most challenging code to implement.
Review Section 2.4 in the textbook, especially the part on depth-first search. Finding all the pixels in a blob is similar to finding a percolating path.
Write the constructor to find all of the blobs and initialize the instance variables. Most of the work for the BeadFinder data type will be here.
The crux of this part is to write a private recursive method dfs() that locates all of the foreground pixels in the same blob as the foreground pixel (x, y). To do this, use depth-first search:

Mark pixel (x, y) as in the current blob.
Then recursively mark all of its foreground neighbors as in the current blob (but do not recur if the pixel has previously been marked or the pixel indices are out-of-bounds).
It is up to you to decide which arguments would be useful for the dfs() method.
The constructor should call dfs() from each unmarked pixel (x, y). All of the pixels encountered during a single call to dfs() comprise one blob.
Next, implement the method getBeads(int min) that searches through the blobs and stores all of the beads (blobs that contain at least the specified number of pixels) in a Blob array. The length of the array should be equal to the number of beads. To determine the number of beads, you may find it helpful to implement a private method countBeads(int min) that counts and returns the number of beads.
Implement a main() method that takes as command-line arguments min, tau, and the name of a JPEG file. The main() method prints the list of beads.

Some FAQs:

Can I assume that the dimensions of all of the images are 640-by-480 pixels? No, do not hardwire these constants into your program. Use picture.width() and picture.height() for the width and height, respectively.
To compute the luminance of a pixel: First, get the Color value of that pixel. Then, use the appropriate method in Luminance.java (Program 3.1.3) to get the luminance value for that color. There is no need to copy this code.
Are diagonal pixels not considered adjacent? Use only the four ordinal neighbors (north, east, south, and west).
Must I print the beads and displacements in the same order as shown in the assignment specification? No, the order is not specified.

Testing: The initial description of BeadFinder shows the output from running BeadFinder with run_1/frame00001.jpg. Note that the order in which you print the beads is not important. Here are the results for run_1/frame00000.jpg:

   java-introcs BeadFinder 0 180.0 run_1/frame00000.jpg

   37 (220.0270, 122.8919)
   1 (254.0000, 223.0000)
   17 (255.4118, 233.8824)
   23 (265.8261, 316.4348)
   36 (297.8333, 394.5000)
   39 (312.3077, 215.8205)
   23 (373.0000, 357.1739)
   19 (390.8421, 144.8421)
   31 (433.7742, 375.4839)
   32 (475.5000,  44.5000)
   31 (525.2903, 443.2903)
   24 (591.0000, 399.5000)
   35 (632.7714, 154.5714)

   java-introcs BeadFinder 25 180.0 run_1/frame00000.jpg

   37 (220.0270, 122.8919)
   36 (297.8333, 394.5000)
   39 (312.3077, 215.8205)
   31 (433.7742, 375.4839)
   32 (475.5000,  44.5000)
   31 (525.2903, 443.2903)
   35 (632.7714, 154.5714)

java-introcs BeadFinder 0 180.0 run_6/frame00010.jpg

    1 ( 25.0000, 373.0000)
    1 ( 26.0000, 372.0000)
    1 ( 27.0000, 373.0000)
    1 ( 29.0000, 369.0000)
   63 ( 34.2063,  32.3175)
    9 ( 97.0000, 341.0000)
   65 (141.4615,  54.0615)
   70 (165.8571, 165.2857)
   60 (173.5667, 200.5333)
   50 (198.7000, 113.0200)
    1 (254.0000, 223.0000)
   89 (276.9101, 306.6629)
   24 (296.3750,  82.9583)
   62 (306.6774, 474.6774)
   59 (339.1356,  81.5932)
   68 (358.9706, 159.0588)
   40 (397.0750,  39.2000)
   86 (573.3488, 427.0581)
   51 (611.7451, 143.8235)
   53 (636.1132, 230.6038)
   14 (634.5000, 421.7143)
   26 (636.5000,  35.0000)

   java-introcs BeadFinder 25 180.0 run_6/frame00010.jpg

   63 ( 34.2063,  32.3175)
   65 (141.4615,  54.0615)
   70 (165.8571, 165.2857)
   60 (173.5667, 200.5333)
   50 (198.7000, 113.0200)
   89 (276.9101, 306.6629)
   62 (306.6774, 474.6774)
   59 (339.1356,  81.5932)
   68 (358.9706, 159.0588)
   40 (397.0750,  39.2000)
   86 (573.3488, 427.0581)
   51 (611.7451, 143.8235)
   53 (636.1132, 230.6038)
   26 (636.5000,  35.0000)

Click here to show possible progress steps for BeadTracker

The main() method in BeadTracker takes an arbitrary number of command-line arguments, args[0], args[1], and so forth.
You need to consider only two frames at a time, so do not store all of the frames at the same time.
Use the Picture data type to read a JPEG file.
Some FAQs

What should I do if several of the beads in frame t+1 have the same bead in frame t as their closest bead? That happens only rarely, so you should not worry about it—just let the bead in frame t get paired a second time.
I am able to find beads and blobs correctly, but my BeadTracker gives a few errors, despite that it is mostly working. Why could this be?
- Check that, for each bead in frame t + 1, you are finding the closest bead in frame t, and not vice versa.
- Be sure to discard distances greater than delta, not greater than or equal to delta.
Why do I have to compare each bead in frame t + 1 to each bead in frame t? Why can’t I do it the other way around? It is an arbitrary choice, but one that you must follow because it is prescribed in the assignment specification.
Can I assume that all of the runs consist of 200 frames? No, do not hardwire 200 into your program. Use args.length for the number of command-line arguments.
How can I specify 200 image names on the command line? Use the wildcard capability of the terminal. For example, the following specifies (in alphabetical order) all .jpg files in the run_1 directory.

   java-introcs BeadTracker 25 180.0 25.0 run_1/*.jpg

Testing: For reference, displacements-run_1.txt, displacements-run_2.txt, and displacements-run_6.txt contain a list of all of the displacements (using tau = 180.0 and min = 25) for run_1, run_2, and run_6, respectively. They were obtained by running

   java-introcs BeadTracker 25 180.0 25.0 run_1/*.jpg

   java-introcs BeadTracker 25 180.0 25.0 run_2/*.jpg

   java-introcs BeadTracker 25 180.0 25.0 run_6/*.jpg

Click here to show possible progress steps for Avogadro

The main() method in Avogadro reads a sequence of floating-point numbers from standard input and prints the estimate of Avogadro’s number using the formulas provided in the assignment.
To calculate $σ^2$, use the second formula listed with radial displacements; these are the results from BeadTracker.
Some FAQs:

How accurate of an estimate should I get? You should get within 10% or so of the exact value for Avogadro’s number $6.022142 × 10^{23}$. The standard deviation of the radius of the beads is about 10%, so you should not expect results more accurate than this. Your output, however, should agree exactly with ours.
My physics is a bit rusty. Do I need to worry about converting units? Not much, since all of the constants are in SI units. The only conversion you should need to do is to convert from distances measured in pixels (the radial displacements) to distances measured in meters, by using the conversion factor of $0.175 × 10^{−6}$ meters per pixel.
Checkstyle complains about the variables I named T and R. Which names should I use instead? A constant variable (a variable whose value does not change during the execution of a program, or from one execution of the program to the next) should begin with an uppercase letter and use underscores to separate any word boundaries, such as GRAVITATIONAL_CONSTANT. Constant variables should have more meaningful names, such as TEMPERATURE or GAS_CONSTANT.

Testing - below are the output for displacements-run_1.txt, displacements-run_2.txt, and displacements-run_6.txt.

java-introcs Avogadro < displacements-run_1.txt

Boltzmann = 1.2535e-23
Avogadro  = 6.6329e+23

java-introcs Avogadro < displacements-run_2.txt

Boltzmann = 1.4200e-23
Avogadro  = 5.8551e+23

java-introcs Avogadro < displacements-run_6.txt

Boltzmann = 1.3482e-23
Avogadro  = 6.1670e+23

Click here to show possible progress steps for system testing

As a final test, combine the data collection (BeadTracker) for run_1, run_2, and run_6 with the data analysis (Avogadro). The data for run_2 contains light boundary pixels and run_6 contains pixels whose luminance is exactly 180.0.

   java-introcs BeadTracker 25 180.0 25.0 run_1/*.jpg | java-introcs Avogadro

   Boltzmann = 1.2535e-23
   Avogadro  = 6.6329e+23

   java-introcs BeadTracker 25 180.0 25.0 run_2/*.jpg | java-introcs Avogadro

   Boltzmann = 1.4200e-23
   Avogadro  = 5.8551e+23

java-introcs BeadTracker 25 180.0 25.0 run_6/*.jpg | java-introcs Avogadro

   Boltzmann = 1.3482e-23
   Avogadro  = 6.1670e+23

Performance Analysis

Formulate a hypothesis for the running time (in seconds) of BeadTracker as a function of the input size $n$, where $n$ is the total number of pixels read across all processed frames. Use a power-law model: $$ T(n) = a \, n^b.$$

Use the doubling hypothesis and justify your results with empirical data. Provide data from at least three experiments.
Report only numeric values for $a$ and $b$.

Answer all questions in readme.txt.

Q.How can I estimate the running time of BeadTracker?

Use the Stopwatch data type from Section 4.1. Remember to remove it and any additional print statements from your submitted version of BeadTracker.java. When you execute BeadTracker, redirect the output to a file to avoid measuring the time to print the output to the terminal. Run BeadTracker with a variety of input sizes which allow you to get good timing data and form a doubling hypothesis.

Q.How can I run BeadTracker with a variety of input sizes?

All of the runs have 200 frames. However, when you are performing timing experiments, you can simply use a subset of them. Use use the wildcard capability of the terminal to run 10 frames, 20 frames, 40 frames, 80 frames, and 160 frames, as follows:

~/Desktop/atomic> java-introcs -Xint BeadTracker 25 180.0 25.0 run_1/frame000[0]*.jpg    > temp.txt

~/Desktop/atomic> java-introcs -Xint BeadTracker 25 180.0 25.0 run_1/frame000[0-1]*.jpg  > temp.txt

~/Desktop/atomic> java-introcs -Xint BeadTracker 25 180.0 25.0 run_1/frame000[0-3]*.jpg  > temp.txt

~/Desktop/atomic> java-introcs -Xint BeadTracker 25 180.0 25.0 run_1/frame000[0-7]*.jpg  > temp.txt

~/Desktop/atomic> java-introcs -Xint BeadTracker 25 180.0 25.0 run_1/frame000*.jpg run_1/frame001[0-5]*.jpg > temp.txt

Q.Do I need to use the -Xint option?

You can try your experiments with or without the -Xint option. Recall, that -Xint turns off Java optimization, so you may get clearer results when you use the doubling method.

Q.How long should BeadTracker take?

It depends on the speed of your computer, but processing 200 frames should take about 10 seconds or less without the -Xint option and about two minutes with the -Xint option.

Q.How much memory should my program use?

The reference solution uses less than 10 MB. You will receive a deduction if you use substantially more. The most common way to waste memory is to hold references to an array of Picture objects in BeadTracker instead of only two at a time. You can use the -Xmx option to limit how much memory Java uses: for example, the following command limits the memory available to Java to 10 MB.

   java-introcs -Xint -Xmx10m BeadTracker 25 180.0 25.0 run_1/*.jpg

Q.When I test with a very small luminance threshold, I get a StackOverflowError, but my code works for larger luminance thresholds. What does this mean?

Since DFS is recursive, it consumes memory proportional to the height of the function-call tree. If the luminance threshold is small, the blobs can be very big, and the height of the function-call tree may be very large. We will not test your program on inputs with such big blobs. If, however, you are determined to get it to work on such cases, use the command-line option -Xss20m to increase the stack space.

   java-introcs -Xint -Xss20m BeadTracker 25 18.0 25.0 run_1/*.jpg

Submission.

Upload all required files to TigerFile :

Blob.java
BeadFinder.java
BeadTracker.java
Avogadro.java
readme.txt
acknowledgments.txt

Do not submit stdlib.jar, Luminance.java, Stack.java, Queue.java, or ST.java.

Grading Breakdown

Files	Points
Blob.java	10
BeadFinder.java	30
BeadTracker.java	20
Avogadro.java	10
Analysis and readme.txt	10
Total	80

Enrichment.

Q.What is polystyrene?

It is an inexpensive plastic that is used in many everyday things including plastic forks, drinking cups, and the case of your desktop computer. Styrofoam is a popular brand of polystyrene foam. Computational biologists use micron size polystyrene beads (also known as microspheres and latex beads) to capture a single DNA molecule, e.g., for a DNA test.

Q.What is the history of measuring Avogadro’s number?

In 1811, Avogadro hypothesized that the number of molecules in a liter of gas at a given temperature and pressure is the same for all gases. Unfortunately, he was never able to determine this number that would later be named after him. Johann Josef Loschmidt, an Austrian physicist, gave the first estimate for this number using the kinetic gas theory. In 1873 Maxwell estimated the number of be around $4.3 × 10^{23}$; later Kelvin estimated it to be around $5 × 10^{23}$. Perrin gave the first “accurate” estimate ($6.5–6.8 × 10^{23}$) of, what he coined, Avogadro’s number. The most accurate estimates for Avogadro’s number and Boltzmann’s constant are computed using x-ray crystallography: Avogadro’s number is approximately $6.022142 × 10^{23}$; Boltzmann’s constant is approximately $1.3806503 × 10^{−23}$.

Q.Where can I learn more about Brownian motion?

Here’s the Wikipedia entry. You can learn about the theory in ORF 309. It may be the first subject you will be asked about if you interview on Wall Street.

This assignment was created by David Botstein, Tamara Broderick, Ed Davisson, Daniel Marlow, William Ryu, and Kevin Wayne.

	MIDI	pitch	MIDI	pitch	MIDI	pitch	MIDI	pitch
	48	C3	60	C4	72	C5	84	C6
	49	C#3	61	C#4	73	C#5	85	C#6
	50	D3	62	D4	74	D5	86	D6
	51	D#3	63	D#4	75	D#5	87	D#6
	52	E3	64	E4	76	E5	88	E6
…	53	F3	65	F4	77	F5	89	F6	…
	54	F#3	66	F#4	78	F#5	90	F#6
	55	G3	67	G4	79	G5	91	G6
	56	G#3	68	G#4	80	G#5	92	G#6
	57	A3	69	A4	81	A5	93	A6
	58	A#3	70	A#4	82	A#5	94	A#6
	59	B3	71	B4	83	B5	95	B6

	MIDI	pitch	MIDI	pitch	MIDI	pitch	MIDI	pitch
	48	C3	60	C4	72	C5	84	C6
	49	C#3	61	C#4	73	C#5	85	C#6
	50	D3	62	D4	74	D5	86	D6
	51	D#3	63	D#4	75	D#5	87	D#6
	52	E3	64	E4	76	E5	88	E6
…	53	F3	65	F4	77	F5	89	F6	…
	54	F#3	66	F#4	78	F#5	90	F#6
	55	G3	67	G4	79	G5	91	G6
	56	G#3	68	G#4	80	G#5	92	G#6
	57	A3	69	A4	81	A5	93	A6
	58	A#3	70	A#4	82	A#5	94	A#6
	59	B3	71	B4	83	B5	95	B6

COS 126, Fall 2026

0. Hello, World

Getting Started

Restrictions

Hello, World

Personalized Greeting

Hello, World in Many Voices

Great Circle Distance

RGB to CMYK Conversion

Readme

Acknowledgments

Submission

Grading Breakdown

1. Conditionals and Loops

Getting Started

Saying Military Time

Random Walkers

Duotone Filter

Musical Dice Game

Submission

Grading Breakdown

2. Arrays and Input/Output

Getting Started

Dice and the Gaussian Distribution

Echo Filter

World Maps

Submission

Grading Breakdown

3. Conjunction Function

Getting Started

Part I: Audio Library

amplify(double[] a, alpha)

clamp(double[] a)

reverse(double[] a)

merge(double[] a, double[] b)

mix(double[] a, double[] b)

changeSpeed(double[] a, double alpha)

Part II: Audio Collage

Implementing Other Audio Effects

Submission

Grading Breakdown

Credits

4. Recursion

Getting Started

Delannoy Numbers (brute force)

Delannoy Numbers (dynamic programming)

Analysis

Sierpinski Triangle

Geometry

Requirements

Create Your Recursive Art

Requirements

Student Art

Submission

Grading Breakdown

5. Object Oriented Programming

Getting Started

Partnering

Rectangular Tile of an Image

Tracker

Musical Notes

Play These Notes

Submission

Grading Breakdown

6. Guitar Hero

Getting Started

Background and Approach

Ring Buffer

Implementation strategy

Requirements

Implementing RingBuffer.java

Guitar String

Requirements

Implementing GuitarString.java

Testing Your GuitarString.java Implementation

`Guitar Hero Client

Requirements

Implementing GuitarHero.java

Rock on! Play your GuitarHero

Submission

`amplify(double[] a, alpha)`

`clamp(double[] a)`

`reverse(double[] a)`

`merge(double[] a, double[] b)`

`mix(double[] a, double[] b)`

`changeSpeed(double[] a, double alpha)`

Implementing `RingBuffer.java`

Implementing `GuitarString.java`

Testing Your `GuitarString.java` Implementation

Implementing `GuitarHero.java`

Implementing `MarkovLM.java`

Implementing `Chat126.java`

Testing Your `MarkovLM.java` Implementation

Implementing `Perceptron.java`

Testing `Perceptron.java`

Implementing `MultiPerceptron.java`

Testing `MultiPerceptron.java`

	MIDI	pitch	MIDI	pitch	MIDI	pitch	MIDI	pitch
	48	C3	60	C4	72	C5	84	C6
	49	C#3	61	C#4	73	C#5	85	C#6
	50	D3	62	D4	74	D5	86	D6
	51	D#3	63	D#4	75	D#5	87	D#6
	52	E3	64	E4	76	E5	88	E6
…	53	F3	65	F4	77	F5	89	F6	…
	54	F#3	66	F#4	78	F#5	90	F#6
	55	G3	67	G4	79	G5	91	G6
	56	G#3	68	G#4	80	G#5	92	G#6
	57	A3	69	A4	81	A5	93	A6
	58	A#3	70	A#4	82	A#5	94	A#6
	59	B3	71	B4	83	B5	95	B6