CSCI 1300
Introduction to Computer Science
Homework 3: Four Functions

Due Date

All work must be submitted by 7:50am on Tuesday, Feb 2. Submit the programming work online to http://culearn.colorado.edu. No late work is accepted, so submit what you have before the due date!

Working Alone

You may talk with other students and instructors about the assignments, but you may not look at or copy code written by others. The penalty for violating this code is an F for the entire semester.

Programming Style

Starting with this homework, all your work must follow these ten style items. Thank you! (See snowmen.cxx for examples of this style.)

1. A comment at the top of the program lists the file name, your name, your e-mail address, and a short description of the purpose of the program.
2. Constants are declared with ALL CAPITAL LETTERS. Variables, parameters and function names are declared with all lower-case letters.
3. No global variables. Instead, every variable is declared AT THE TOP of the function it is used in (right after the open curly bracket). Each variable has a short, but meaningful name and a short comment indicating its purpose.
4. Each curly bracket is on a line by itself (or with a comment).
5. Function prototypes appear before the main program in alphabetical order with a comment that indicates how to use each function. The comment must mention the purpose of every parameter.
6. Function definitions (the "implementations") must appear after the main function in alphabetical order. Every function must have a a blank line and a line of dashes immediately before its defintion; immediately after the definition is another line of dashes and then another blank line.
7. No line exceeds 80 characters.
8. Each level of indentation (such as the body of a function or the body of a loop) is indented 4 extra spaces.
9. Blank lines are used in a meaningful way. For example, if there are six lines of code that perform some job, then put a comment before the six lines, and one blank line afterward.
10. Formulas are nicely spaced with a space around every operator (except *, / and %), and a space after every comma in an argument list.

The Assignment

This week, we will learn about writing your own non-void functions to compute numerical value that is sent back to the main program (or elsewhere). We've already used several of these functions (such as sin and cos), but now you'll write four of your own. These particular four functions will later be used in HW 4 that simulates the orbit of a planet.

The Four Functions

Your functions must have these exact prototypes. You may copy and paste these descriptions into your program, which must be called functions.cxx:

//-----------------------------------------------------------------------------
// Function Prototypes

// A function to calculate the solution to Kepler's equation. The equation is
// x = ma + ecc*sin(x), and the answer returned is x, within EPSILON.
double kepler_solution(double ma, double ecc);

// orbit_angle(ecc, period, t) computes the angle of a planet's position
// in polar coordinates at time t.  ecc is the ecentricity of the orbit,
// and period is the time for one full orbit.  period and t must be in the
// same units.
double orbit_angle(double ecc, double period, double t);

// orbit_dist(a, ecc, theta) computes the distance of a planet
// from the sun when it is at angle theta in polar coordinates.
// a is the semi-major axis; ecc is the orbit's eccentricity.  The units
// of the answer are the same as the units of a.
double orbit_dist(double a, double ecc, double theta);

// pixel(v, v0, v1, pmax) converts v from an interval that ranges from v0 to v1
// into an integer interval that ranges from 0 to pmax. Note that when v = v0,
// the answer is always 0, and when v = v1, the answer is always pmax.
// Example 1: Suppose an x-coordinate called x ranges from -2 (on the left
// side of the screen) to +3 (on the right side of the screen), and
// we want to figure out the corresponding pixel x coordinate for a screen
// that is 400 pixel wide. Then call pixel(x, -2, 3, 400).
// Example 2: Suppose a y-coordinate called y ranges from +4 (on the top
// of the screen) to -2 (on the bottom of the screen), and
// we want to figure out the corresponding pixel y coordinate for a screen
// that is 300 pixels tall. Then call pixel(y, 4, -2, 300). Note that in this
// case v0 > v1 since we want bigger coordinates at the top of the screen.
int pixel(double v, double v0, double v1, int pmax);
//-----------------------------------------------------------------------------

Algorithm for kepler_solution

Mathematicians and astronomers (beginning with Kepler) have spent much effort trying to find a technique that solves for the unknown value x in this equation. Here is the technique that we will use:

Declare a global named constant, EPSILON to be 0.001.

Then start with a guess of x = 0. Then calculate how much of an error this guess has. The error amount is just the absolute value of the left side of the equation (x) minus the right side of the equation (ma + ecc*sin(x)). You can use the function abs from <cmath> to compute an absolute value. If this error is less than EPSILON, then you are done (return this value of x as your answer). But if the error is greater than or equal to epsilon, then change your new guess to be the right side of the equation (ma + ecc*sin(x)), and then check the error again. Keep going until you get an error that's below EPSILON.

Algorithm for orbit_angle

Calculating the orbit angle requires three steps:

1. Compute an angle: ma =2πt/period. This is the angle that the planet would be at if it were traveling in an exact circle.

2. Solve for x in the equation x = ma + ecc*sin(x).

3. Your answer (as Kepler discovered) is then: 2*atan(sqrt((1 + ecc)/(1 - ecc))*tan(x/2)). The atan function is the inverse tangent, and its also part of <cmath>.

Algorithm for orbit_dist

The orbit distance is computed as: a*(1 - ecc*ecc)/(1 + ecc*cos(theta))

Algorithm for pixel

You'll need to figure out this algorithm yourself. Draw some pictures! You'll probably figure out how to compute the answer as a double number first, but then convert it to int before returning it (without any warnings from the compiler!)

The Main Program

You must write a short interactive main program that lets the user test each of the functions once. Here is a sample dialog with the program. You must match this exactly (otherwise, the TA's grading program will fail your work!) (Note: If your answers are only slightly different, that's usually okay. It's caused by doing arithmetic operations in slightly different orders.) Note the message at the end, too! (The numbers in boldface are the ones typed by the example user.)

Please type ma and ecc for testing kepler_solution: 2.2 0.2
kepler_solution is 2.3436
Please type ecc, period and t for testing orbit_angle: 0.2 60 9.1
orbit_angle is 1.32472
Please type a, ecc and theta for testing orbit_dist: 0.34 0.2 2.34
orbit_dist is 0.379144
Please type v, v0, v1 and pmax for testing pixel: 0.38 -0.68 0.68 400
pixel is 311
Thank you, Mr. Kepler.

Grading Criteria

1. Your program must be called functions.cxx. You must submit this file and no other.
2. You must meet all the style requirements listed above.
3. Your code compiles correctly with no warnings.
4. Each of your four functions (with the exact prototypes specified) must always produce right answers.
5. Additional requirement #1: The orbit_angle must call your own kepler_solution function to do Step 2.
6. Additional requirement #2: The dialog with the main program must exactly match the example shown above.