CS211 Programming Exercise 1
Spring 2008 - 100 Points
Due: Lesson T12 at 1630 (11 Feb)

Objectives:

• Be able to create a MATLAB program to solve a problem
• Be able to appropriately document a program with comments
• Be able to create and use descriptive variable names
• Be able to perform basic mathematical operations
• Be able to use the fprintf function for formatted output
• Be able to select and use appropriate branch (selection) statements
• Be able to read in and validate user input
• Be able to select and use appropriate repetition (loop) statements

Due Date/Time: 

• This lab is due at 1630 on Lesson T12 (11 Feb).
   

• Please submit an electronic copy of your PEX1.m file to the course web site before the class starting time due date.
   

• Please bring a hardcopy printout of your PEX1.m file to class on the due date.
   

• A late penalty accrues at a rate of 25% for each 24-hour period (including weekends) past the on-time turn-in date and time.  The late penalty is a cap on the maximum grade that may be awarded for the late work.  Thus zero points will be awarded for a programming exercise submitted 72 hours or more late. There is no early turn-in bonus for this assignment.

Help Policy:

AUTHORIZED RESOURCES: 

      Any, except another cadet’s program.

NOTES: 

• Never copy another person’s work and submit it as your own.

• You must document all help received from sources other than your instructor.

• DFCS will recommend a grade of F for any cadet who egregiously violates this Help Policy or contributes to a violation by others.

Requirements For Documentation:

• You must document all help received from any source other than your instructor.

• The documentation statement must explicitly describe WHAT assistance was provided, WHERE on the assignment the assistance was provided, and WHO provided the assistance.

• If no help was received on this assignment, the documentation statement must state “NONE.”

• Vague documentation statements must be corrected before the assignment will be graded, and will result in a 5% deduction on the assignment.

Problem Overview:

This programming exercise requires you to create a MATLAB program that will calculate and display images of the Mandelbrot set, a fractal which is described below. Your program will read in four(4) inputs from the user, display a single image, and output some statistics about the image in the command window. Part of this assignment is to help you develop strong programming practices. Please note that 40% of the points for this assignment are based on good programming techniques, independent of the program's correctness.

The Mandelbrot Set

The Mandelbrot Set, shown in the image below, is a set of points in the complex plane that have some very interesting properties. For example, the shapes created by the set of points are self-similar -- that is, they create many copies of the same shape at different scales. In addition, the set of points has an infinite complexity -- regardless of how much you zoom into the set of points you see new and interesting shapes.

A point in the complex plane, c = (a + bi), is considered part of the Mandelbrot Set if repeated squaring and additions of the point using the equation z_n = z²_n-1 + c, do not result in an infinite value, where z₀ (the first value of z) is always 0. (Mathematicians call this a divergent function if it goes to infinity-- but this is not a math class, so we will skip most of the math details.) If you repeatedly perform this operation on a value c, and the result always stays below 2.0, then you can be fairly certain that the value will never grow to infinity. If you ever get a value greater than or equal to 2.0, you know immediately that the repeated calculation will produce an infinite result.

Technically, a complex number c is either in (or not in) the Mandelbrot Set, as described above. However, you can create some very nice images by assigning different colors to each complex number in a region based on how many iterations of the equation it takes to get a value greater than or equal to 2.0. This is what you will do for this assignment.

MATLAB Images

MATLAB has many built-in functions that produce graphical output. One such function is the image() function that will treat each value in a 2D array as a color index value and display a "picture" of the array data. For example, the two MATLAB commands below will produce a 300-by-300 pixel image of random colors. (We will cover more details about graphical output in future lessons and only introduce some basic concepts for this assignment.)

My_colors = floor(rand(300) * 64);
image(My_colors);

The color index values, by default, are indexes into a color map containing 64 colors, as shown in the figure below. You can see (and edit) the color values in the color map using the MATLAB command colormapeditor(). (We highly recommend that you do not edit the default color map for this assignment! If you do change the color map, it can be restored to its original values using the command colormap('default') )

Program Description:

Your MATLAB program should be a single function that implements the following steps. You should implement and test each step before going to the next step. Please read the Helpful Hints section below BEFORE you begin programming.

1. Clear the command window.
    

2. Display a useful introduction to the program's user in the command window.
    

3. Get the limits on the x (real) axis and the y (imaginary) axis that define a rectangular region in the complex plane.

   a. prompt for and get from the user the left limit of the x axis; the input can be any floating point number and does not need to be validated
   b. prompt for and get from the user the right limit of the x axis; the input must be validated to be greater then the left limit
   c. prompt for and get from the user the bottom limit of the y axis; the input can be any floating point number and does not need to be validated
   d. prompt for and get from the user the top limit of the y axis; the input must be validated to be greater then the bottom limit
    

4. Create an 2D array containing all ones. The size of the array should be defined by "constants" at the top of your program.
    

5. For every row and column position in the 2D array, do the following:

   a. Calculate (or set) a variable c equal to the complex number associated with this row/column position in the 2D array
   b. Initialize a variable  z to 0
   c. Repeatedly calculate the formula   z = z² + c   until the magnitude of  z gets greater than or equal to 2.0 or you have done the equation at least 64 times. In addition, count the number of times the equation is calculated.
   d. Set the value of your 2D array at this row/column position to the number of times you executed the equation.
    

6. Display the image represented by your 2D array using the image() command.
    

7. Display text to the command window that contains the following information. Make sure your output is nicely formatted. Only values that never exceeded 2.0 in your calculation loop after 64 tried are considered part of the Mandelbrot Set. All other points are definitely not a part of the set.

   For this image:
     There are ??? points probably in the Mandelbrot Set
     There are ??? points definitely NOT in the Mandelbrot Set
    

8. If all of the points represented in the image are part of the Mandelbrot set, display the message:

   All of the points are probably in the Mandelbrot set - not very interesting!

9. If all of the points represented in the image generated a value greater than 2.0 on their first calculation, display the message:

   Your image is totally blue -- not very interesting!.
   Please select a region of the complex plane closer to the origin.

Helpful Hints:

• Make sure you are perfectly clear on the help policy and do not use another cadet's code as a source of help.
   
• Run the pcode file Pex1p.p (right-click and select "Save Target As..."; save to your CS211 MATLAB folder; type pex1p in the command window) to see an example of how your program should behave (including output formatting).
   
• Make sure you understand the problem before you attempt to solve it -- read the above requirements several times and ask your instructor questions!
   
• Work out the required calculations by hand and test equations out in MATLAB's command interpreter before writing any program code.
   
• Define all program constants at the beginning of your program.  Refer to the sample code from lesson 9 for examples. Your code should have at least three(3) constants: the number of rows of the image, the number of columns of the image, and the number of colors in the color map. Use the declared constants consistently throughout your program.
   
• To minimize the time you spend in debugging the logic errors in your code, please do the following:
  • Initially use small values for the image size (e.g., 10x10 or 100x100). After you program appears to work correctly, increase the image size to a minimum of 300x300. (Changing the image size should require the modification of only 2 assignment statements -- assuming you have created appropriate "constants" that define the image size.)
  • After you have implemented and tested step 3 (the data input step), comment these lines of code out, and replace them with the following "hard coded" statements, changing the variable names to match your code:

    X_left   = -2.0;
    X_right  =  0.5;
    Y_bottom = -1.0;
    Y_top    =  1.0;
    
    This eliminates the need to enter data every time you test your program. When you believe your code is correct, delete these lines and uncomment your data input statements.

• Each row/column position in your 2D array will be associated with a complex number of the form (a + bi), where a is the real axis (x axis) value and b is the imaginary (y axis) value. You should set/calculate the correct complex number for each array position using the convention shown in the diagram below. That is, the first row will be at the top of the image, the last row will be at the bottom of the image, the first column will be on the left of the image and the last column will be on the right of the image. Some example values are filled into the array, assuming that the real limits are [-2.0, 0.5] and the imaginary limits are [-1.0, 1.0]. The example values would be different if the limits changed.
   

  	Column 1 (x  = left limit)									Column 10 (x = right limit)
  row 1 (y = top limit)	-2.0+1i									0.5+1i
  row 10 (y = bottom limit)	-2.0-1i	-1.72-1i	-1.44-1i	-1.16-1i	-0.88-1i	-0.61-1i	-0.33-1i	-0.06-1i	0.22-1i	0.5-1i

   

• The difference between each complex value in your array can be calculated with a simple formula. For example, if your x axis in defined on the interval [0.3, 0.4] and you have 100 columns in your array, the difference between each complex number along the real (x) axis is:

  (0.4 - 0.3) / (100 - 1)
  
  If you use this equation, modify it to use appropriate variables from your program.

• Given an x and y axis value, you can create a complex number using the MATLAB complex() function. For example:

  c = complex(x, y);

• MATLAB does calculations with complex numbers as easily as it does calculations with real numbers. Use the normal math operators (+  -  *  /  ^) on complex numbers and MATLAB will perform the correct calculations.
   
• To calculate the magnitude of a complex number, use the MATLAB abs() function.
   
• Do not test your code using a single set of inputs -- test it using a variety of inputs and make sure it works for all cases. Some good tests cases to try include
    real [-2.0, 0.5], imaginary [-1.0, 1.0]    (produces a "full" image of the Mandelbrot Set)
    real [0.35. 0.36], imaginary [0.35, 0.36]   
    real [0.357, 0.358], imaginary [0.356, 0.357]   
   

• Thoroughly document your code with comments including a standard program header comment block and appropriate comments in your code.  Make sure the References: section of your program header includes a description of any help you received on the assignment in accordance with the assignment Help Policy.
   

• Use white space (space characters and blank lines) to make your code easier to read.  Ensure that your code is appropriately indented.  You can select all of your code and then press Ctrl-I for smart indent.  Avoid excessively long lines that wrap around to multiple lines in the editor.  You can use ... to continue a single statement across two lines in your m-file (as long as the break is not in a string constant).
   

• Select descriptive names for all of your variables and constants and ensure your are consistent in the format of your constant and variable names (e.g., first letter capitalized, underscores between words).

Grading Information:

Proper Documentation Statement (-5 pts)?