CSC 101, Winter 2008

Project 3 (Lunar Lander)

Due Date

• Part 1 by Friday, February 8 at 11:59 P.M.

• Final handin by Friday, February 14 by 11:59 P.M.

Recent Changes

• None so far

Objectives

• More practice making decisions in C.

• To Practice writing loops in C.

• To experience some of the issues and subtleties involved with solving problems that include repetitive tasks.

• To practice writing and calling functions that you have written.

• To further appreciate the benefits of modular development.

Collaboration

Collaboration is mandatory on this project. You must select a partner in your section. You must only submit one complete program solution (for each part) for your team. It doesn't matter which partner does the submission. As long as you put the correct comment header, see below, you will both get credit.

Required File Header

All students are required to have the following header comment at the top of their source file. Note that the stuff to the right of the colon in red is information for an imaginary example student. (Your header comment is not expected to have red text.) All program files require this header.

   /* Project 3
    *
    * Name: Fleetybelle Screwdriverson
    * Instructor: Haungs
    * Section: 1
    *
    * Partner: John Codewell
    * Instructor: Haungs
    * Section: 1
    *
    */

Resources

• A sample program you can run to see the expected behavior in any situation you wish to test.  To run the program enter the following command on vogon:

• 12:01pm vogon ~> ~mhaungs/Public/moonlander

• Your text.

• Your instructor.

• For Part 1:

  • A header file moonlander.h

  • A function driver program driver.c.

  • Inputs for the driver driverInput.txt

  • Driver outputs driverOutput.txt

• Test runs for Part 2:

  • Test 1 and Test 1 output

  • Test 2 and Test 2 output

  • Test 3 and Test 3 output
    

Ground Rules

• Your program must not use any global data (that is, all data must be declared within some function).

• You may only use standard library functions printf and scanf found in stdio.h, and must implement all other functions yourself.

• Your program must implement the required functions as specified and no others.

• Your program must use the required functions appropriately. That is, it's not enough to create the functions, you must also use them.

• Your program must mimic the sample program's behavior exactly and in all cases. As an exception, some minor whitespace variation is allowed, but you should not rely on this.

Orientation

• You will be writing a program that simulates landing the Lunar Module (LM) from the Apollo space program on the moon.  The simulation picks up when the retrorockets cut off and the pilot/astronaut takes over control of the LM.  The user of the simulator specifies the initial amount of fuel and initial altitude.  The LM starts at a user-specified altitude with an initial velocity of zero meters per second and has a user-specified amount of fuel on board.  The manual thrusters are off and the LM is in free-fall -- meaning that lunar gravity is causing the LM to accelerate toward the surface according to the gravitational constant for the moon.  The pilot can control the rate of descent using the thrusters of the LM.  The thrusters are controlled by entering integer values from 0 to 9 which represent the rate of fuel flow.  A value of 5 maintains the current velocity, 0 means free-fall, 9 means maximum thrust -- all other values are a variation of those possibilities and can be calculated with an equation that is provided below.  To make things interesting (and to reflect reality) the LM has a limited amount of fuel -- if you run out of fuel before touching down you have lost control of the LM and it freefalls to the surface.  The goal is to land the LM on the surface with a velocity between 0 and -1 meters per second, inclusive, using the least amount of fuel possible.  A landing velocity between -1 meters per second and -10 meters per second (exclusive) means you survive but the LM is damaged and will not be able to leave the surface of the moon -- you will be able to enjoy the surface of the moon as long as your oxygen lasts but you will not leave the moon alive.  Velocities faster than (less than) or equal to -10 meters per second mean the LM sustains severe damage and you die immediately. 

• The initial conditions of 1300 meters altitude and 500 liters of fuel were used in the original, and were chosen so that an optimal landing should use approximately 300 liters of fuel. It's a considerable challenge at first, and you may enjoy trying it. Try to beat a 60-second flight duration ending with 202 liters of fuel and a landing velocity of -0.65 m/s.

• FYI: This program is modeled after a version that was popular on HP-28S programmable calculators in the 1970s.  It is interesting to note that the desktop computers you are working on cost about the same amount (unadjusted for inflation) as the calculators did but are quite a bit more powerful (more memory, storage, computational power, not to mention more sophisticated display, keyboard, mouse, et cetera).  This program took approximately 90 seconds to load on the calculator – virtually instantaneous on the machines you are running on today.  Credits to Dick Nungester of HP for the provided equations.

• Before you begin, take a look at sample program by logging on to your vogon account and typing the following command:

        12:01pm vogon ~> ~mhaungs/Public/moonlander

• Start at 1300 meters with 500 liters of fuel, and see how you do.

• The project has two parts:

  1. In the first week, write the functions specified to work with the supplied driver. Submit a working copy as landerFuncs.c by Friday, February 8. Note that input (scanf) and output (printf) occur only in the functions which specifically have that job. The functions that calculate do no I/O, and vice versa. Note also that the file you submit must NOT contain a main function. This part is worth 10% of the overall project, even though it is most of the work. This allows you to fix problems with only a small penalty. NOTE: this driver does not do moon landings – all it does is to test that your functions exist and they can be called without crashing the program. Moon landings have to wait for the next part:

  2. Write the moonlander.c file, which contains the main function. When compiled with your landerFuncs.c and the given header file, this should form a working Lunar Lander simulator, and should be able to duplicate the given sample runs (see Resources above). You may also submit a revised landerFuncs.c, if necessary. NOTE: do not attempt to include the driver from the first part; you cannot have both the moonlander.c and the driver.c because they both have main() functions, and only one is allowed.

• You are given access to a working copy of moonlander. Your goal is to write a program that mimics this program’s behavior exactly, value for value, line for line, letter for letter, while meeting the Ground Rules specified above. As an exception, some minor whitespace variation is allowed, but you should not rely on this.

Part 1: Functions

• You must implement the following functions in a file named landerFuncs.c. Your file must compile correctly with the supplied driver and header files using the command

        gcc -ansi -pedantic -Wall driver.c landerFuncs.c -o driver

• The supplied header file (moonlander.h) will need to be present for this to work. It is a very good idea to #include the header in the same way that the driver does. This will allow the compiler to catch some errors that you might otherwise miss. The function signatures are as specified in that file, and together with the formulas below indicate what parameters must be provided.

• References to tp0 indicate the immediately previous time period (1 second ago) and references to tp1 indicate the current time period.

• The simulation assumes a time interval of one second between each display of the LM’s status and request for throttle input from the user.  To calculate new values for a new time period you need to use the old values from the old time period with the exception of acceleration.  Be sure you examine the following equations carefully and notice that you must calculate the acceleration before you calculate altitude and velocity.

• CAUTION: Pay attention to the data types involved in these equations and be sure you are not losing any necessary precision due to C’s rules for dealing with mixed-type expressions.

• NOTE: The "tp" (time period) subscripts are intended to show how the state at each new second of time (tp1) depends on the state at the current second (tp0) plus the newly entered rate of fuel consumption (marked as tp1). These formulas must be re-evaluated for every second of the simulation.
  
  

  showWelcome()

  display the welcome message. See the sample program for the exact text.

  getFuel()

  This function has no parameters and a return type of int. This function must prompt a user for positive integer value and return it.  It must display an error message if the user enters a negative or zero value and re-prompt for a valid value.  It is not expected to (but may at your option) handle non-integer input (possibly by printing an error message and quitting the program.) You will be tested only with "clean" input, so having this capability will neither help nor hurt your grade.  See the sample program for the exact text of the prompt and any error message(s).

  getAltitude()

  This function must prompt a user for a real value between 1 and 9999, inclusive.  It must display an error message if the user enters a value outside this range and re-prompt for a valid value.  It is not expected to (but may at your option) handle non-numeric input.  See the sample program for the exact text of the prompt and any error message(s).

  displayLMState()

  This function must display the state of the LM as indicated by the parameters. The parameters are: 1) an int representing the elapsed time the LM has been flown; 2) a double representing the LM’s altitude; 3) a double representing the LM’s velocity; 4) an int representing the amount of fuel on the LM; 5) an int representing the current rate of fuel usage.  See the sample program for the exact text and format of the display.

  getFuelRate()

  The parameter is an int representing the current amount of fuel in the LM.  The function prompts the user for an integer value and makes sure it is between 0 and 9, inclusive.   It must display an error message if the user enters a value outside this range and re-prompt for a valid value.  It is not expected to (but may at your option) handle non-numeric input.  The function must return the lesser of the user-entered value or the amount of fuel remaining on the LM (value passed in as a parameter).  See the sample program for the exact text and formatting of the prompt and any error message(s).

  updateAcceleration()

  The parameters are: 1) a double representing the gravitational constant for the moon (given in the driver program); 2) an int representing the current rate of fuel usage using the formula

  acceleration_tp1   =   gravitational constant * ((rate of fuel consumption_tp1 / 5) – 1)

  updateAltitude()

  The parameters are: 1) a double representing the current altitude; 2) a double representing the current velocity; 3) a double representing the current acceleration.  The function calculates and returns the new altitude based on the provided inputs and the formula

  altitude_tp1   =   altitude_tp0 + velocity_tp0 + (acceleration_tp1 / 2)

  Remember, however, that the surface of the moon stubbornly limits the altitude to non-negative values, and your code must do the same.

  updateVelocity()

  The parameters are: 1) a double representing the current velocity; 2) a double representing the current acceleration.  The function calculates and returns the new velocity based on the provided inputs and the formula

  velocity_tp1   =   velocity_tp0 + acceleration_tp1

  updateFuel()

  The parameters are: 1) an int representing the current amount of fuel on the LM; 2) an int representing the current rate of fuel usage.  The function calculates the remaining fuel.  Note: This is a trivial function as long as your getFuelRate function behaves correctly.

  fuel_tp1   =   fuel_tp0 - rate of fuel consumption_tp1

  displayLMLandingStatus()

  This function, as its name implies, displays the status of the LM upon landing.  There are three possible outputs depending of the velocity of the LM at landing, they are:

           Status at landing – The eagle has landed!
           Status at landing – Enjoy your oxygen while it lasts!
           Status at landing – Ouch – that hurt!

  1. Print the first message if the final velocity is between 0 and -1 meters per second, inclusive.

  2. Print the second message if the final velocity is between -1 and -10 meters per second, exclusive

  3. Print the third message if the final velocity is <= -10 meters per second

  See the sample program for the exact text and formatting.

Part 2: Moonlander simulation

• Before you attempt this part, you should complete Part 1 and ensure that it duplicates the output given with the driver.

• Now you must write a moonlander.c that can be compiled against the header and your Part 1 code. From now on the driver will not be used. Compile the moonlander with this command:

        gcc -ansi -pedantic -Wall moonlander.c landerFuncs.c -o moonlander

• You should start with a copy of the driver, however. Its variable declarations will be a good start. You should remove all the code after the declarations, however, because they are wrong in a number of respects.

• For one thing, you must code a simulator-loop that advances the LM from time period zero to landing, and calls to the functions of Part 1 along with minimal code to “glue” it together.  One of the challenges in this project will be understanding the overall structure that has been provided to you.  Don’t hesitate to ask your instructor questions early in the process to help make sure you understand what you are supposed to be doing.  You will probably go down some dead ends and need to remove and/or rewrite code.  This is part of the process so enjoy the ride!

• Use the three sample runs in the Resources section above to check that your code is doing the right things.

Grading

Part 1 is worth 10%; Part 2 (including any reworking of Part 1) is worth 90%.

Handin

1. You can do handin from vogon, or from any Linux lab machine.

2. You must run handin from the directory where your files are located.

3. You will be doing two handins with two different deadlines.

   1. Part 1: February 8

   2. Part 2: February 14
4. Remember, only one submission per team.

5. Execute the following command – be sure to replace -xx with your section:

           handin mhaungs Program3Part1-xx landerFuncs.c
   	handin mhaungs Program3Part2-xx moonlander.c landerFuncs.c