Programming Assignment Checklist: LFSR

Frequently Asked Questions

What are the goals of this assignment? To introduce you to object-oriented programming and to reinforce the message of Lecture 1.

What preparations do I need to do before beginning this assignment? Review the Lecture 1 slides to reacquaint yourself with the basic ideas behind LFSRs. Also read Sections 3.1 and 3.2 of the textbook (to learn the basics of object-oriented programming).

Do I need to follow the prescribed API? Yes, we will be testing the methods in the API directly. If your method has a different signature or does not behave as specified, you will lose a substantial number of points.

How should I represent the LFSR? There are several possible approaches. We recommend that you use an int[] array of size N, each entry of which is either 0 or 1. If you follow this approach, the constructor amounts to creating the array and converting the char values in the string to int values for the array (and initializing your other instance variables).

How do I create an instance variable which is an array if I don't know its length at compile time? Declare it as an instance variable, but initialize it in constructor (where you will know its length). For example, see Program 3.2.3 in the textbook.

What extra comments should I include when writing object-oriented programs? You must comment the purpose of every method, using the names of the argument variables in your description, as below.

// simulate k steps of the LFSR and return corresponding k-bit integer
public int generate(int k)

Additionally, you must comment the purpose of each instance variable, as below.

private int N;          // number of registers in the LFSR
private int[] reg;      // reg[i] = ith least significant (rightmost) bit of the LFSR
private int tap;        // index of the tap bit

In the initial register, fill.charAt(0) is the leftmost bit. But in the Lecture 1 slides and the assignment page, bit 0 is the rightmost bit. Do I have to arrange the bits in my register array that way? Strings are always indexed from left to right (the way we read English). Traditionally, binary digits are indexed from right to left, with bit 0 as the lowest order or rightmost bit. You are welcome to use either approach here—just be careful to do it correctly and consistently.

How do I convert the char values in the string to int values for the array? The number zero is represented by the char value '0'. The char data type is a Java primitive type, so you can compare two of them with if (c == '0').

My step() method is producing 19 for the binary number 11001. What am I doing wrong? You are calculating the bits in reverse order. 19 is the decimal value of the binary number 10011.

My generate() works with the 11 bit fill and the tap at position 8, but when I try generate()with the 20 bit fill and the tap at position 16, I get a different answer from the one shown in the example. What am I doing wrong? Make sure you are not hardwiring 11 or 8 in your LFSR code. The LFSR constructor arguments should set the size of the register and the tap position.

The toString() is not explicitly called in the test client code, but it still gets called. How does this work?

      LFSR lfsr = new LFSR("01101000010", 8);
      StdOut.println(lfsr);

When a Java object is passed to any of the print methods, a call is automatically made to that object's toString() method.

I get an ArrayOutOfBounds or NullPointerException error. What could cause this? Do your constructors initialize all of the instance variables (e.g., N, reg, and tap)? Did you allocate memory for your array with new? Did you inadvertently redeclare int N or int[] reg in a method or constructor, thereby hiding the instance variable with the same name?

How do I do exclusive or (XOR) in Java? Use the ^ Java symbol. The operation a ^ b, where a and b are int values, does a bit-by-bit exclusive or of the values.

How do I read in the .png files? Use our Picture.java data type, described in Section 3.1 of the textbook. You will only need the constructors and methods of the Picture API summarized on page 330. To see it in action, look at the program Grayscale.java which takes the name of a picture file as a command line argument, converts all pixels to gray, and displays all those pixels. If you download Grayscale.java, you will also want to download Luminance.java. Look at Luminance.java to see how to retrieve the r, g, and b values for the Color.

Sometimes my encrypted picture looks like a shadowy version of the original. How do I pick a good tap number? Here are suggested tap numbers for maximizing the cycle of different size binary registers: 5 bits, tap 2; 6 bits, tap 4; 9 bits, tap 4; 10 bits, tap 6; 11 bits, tap 8; 20 bits, tap 16; 25 bits, 21; 36 bits, tap 24; 60 bits, tap 58; 100 bits, tap 62; 150 bits, tap 96.

Testing

Be sure to thoroughly test each piece of your code as you write it. We offer some suggestions in the assignment specification. You should also test your data type with other parameters.

Use the following code to test generate() with a 20-bit fill and a tap of 16.

LFSR lfsr3 = new LFSR("01101000010100010000", 16);
for (int i = 0; i < 10; i++) {
    int r = lfsr3.generate(8);
    StdOut.println(lfsr3 + " " + r);
}

It should output:

01010001000000101010 42
00000010101011011001 217
10101101100100010111 23
10010001011111000001 193
01111100000100011010 26
00010001101010011100 156
10101001110010011100 156
11001001110011100111 231
11001110011110000111 135
01111000011110111101 189

PhotoMagic. To test PhotoMagic.java use
```
    java PhotoMagic pipe.png 01101000010100010000 16
```
and compare with the pictures on the assignment page.
```
    java PhotoMagic Xpipe.png 01101000010100010000 16
```
should retrieve the original picture. We have also provided two encrypted pictures which when decrypted with
```
    java PhotoMagic Xbaboon-red.png 01101000010100010000 16
```
should retrieve the original picture which uses only variants of red, and
```
    java PhotoMagic Xscarpet-cookies.png 01101000010100010000 16
```
should retrieve a Sierpinski carpet design in vanilla and chocolate. ;)

Submission

Your programs must be named LFSR.java and PhotoMagic.java. Use the following readme file template. Don't forget to hit the "Run Script" button on the submission system to test that it compiles cleanly.

Possible Progress Steps

These are purely suggestions for how you might make progress. You do not have to follow these steps.

Download the directory lfsr to your system. It contains a template LFSR.java file to get you started. It also contains Picture.java, pipe.png, and the readme.txt template.
Reread the slides for Lecture 1 (to reacquaint yourself with the basic ideas behind LFSRs), the lecture slides for "Using Data Types" and "Creating Data Types", and pages 316-335 and 370-377 in the text (to learn the basics of object-oriented programming).
The design of your program should look like the template LFSR.java, except that you will need to fill in all of the constructors and methods.

We recommend defining the instance variables as follows:

public class LFSR {
    private int N;          // number of registers in the LFSR
    private int[] reg;      // reg[i] = ith least significant (rightmost) bit of the LFSR
    private int tap;        // index of the tap bit
}

Make the constructor. Your constructor for LFSR will initialize all the instance variables. Use new to allocate memory for the int[] array. Observe that you must do this in the constructor (and not when you declare the instance variables) since otherwise you wouldn't know how big to make the array.
Write the toString() method.
As you fill in the methods for LFSR, use the test code described in the assignment.
Write the step() method. Test.
Write the generate() method. Test.
PhotoMagic. Your PhotoMagic class is a client of the Picture, Color, and LFSR classes. By placing the line
```
 import java.awt.Color;
```
above the line where you declare public class PhotoMagic, the compiler will know that you are going to use the Color class. Place Picture.java and LFSR.java in the same directory with PhotoMagic.java, so the compiler will be able to find both of them.

Enrichment

Read more about Linear Feedback Shift Registers.

COS 126 Home Page