Assignments | 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

	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

Assignments | 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