Harvey Mudd College
Computer Science 42
Assignment 7, Due Monday, March. 26, by 11:59pm

Unicalc Part 1

Unicalc is a calculator program that handles numerical quantities including physical and other units, e.g.,

Units are important to computation because they eliminate an element sometimes left to human interpretation. In the area of engineering, failure to interpret numbers without their units specified has been known to lead to failure of space missions. In the Wikipedia article about NASA's Mars Climate Orbiter, it is stated:

“Twenty-four hours prior to orbital insertion, calculations placed the orbiter at an altitude of 110 kilometers; 80 kilometers is the minimum altitude that Mars Climate Orbiter was thought to be capable of surviving during this maneuver. Final calculations placed the spacecraft in a trajectory that would have taken the orbiter within 57 kilometers of the surface where the spacecraft likely disintegrated because of atmospheric stresses. The primary cause of this discrepancy was human error. Specifically, the flight system software on the Mars Climate Orbiter was written to calculate thruster performance using the metric unit Newtons (N), while the ground crew was entering course correction and thruster data using the Imperial measure Pound-force (lbf).”

A little closer to home, you will have to do many unit conversions and operations in your other classes here at HMC. It is our hope that this calculator will prove useful in those classes.

This week you will begin by implementing the back-end functionality for simple unit calculations with error propagation. In doing so, you will be implementing an API (Application Programming Interface), which is simply a library of visible functions that others can use. In this case, you will be using those functions next week when implementing the Unicalc calculator.

Error Propagation

Part 1: Quantity.java Basics (75 points) — Individual or Pair

Start out by creating a file Quantity.java that contains a definition of a class Quantity. The Quantity class must contain at least the following fields:

• The numerical value itself (as a double)
  
  
• The numerical uncertainty in that value (as a double)
  
  
• The attached units (as a Map<String,Integer>).
  
  This last field requires a bit more explanation: the map gives us the (non-zero) exponent for each attached unit. For example, a quantity measured in “meter per second squared” would have a map that associates the key "meter" with the exponent 1 and the key "second" associated with the exponent -2. Similarly, a quantity measured in \(\mathrm{kg}\ \mathrm{m}^2\ /\ \mathrm{s}^3\) would have "kg" mapping to 1, and "m" mapping to 2, and "s" mapping to -3. Try to make sure this map never gives any unit name an exponent of 0. (Take that unit name out of the map, instead).

• A constructor Quantity() of no arguments that creates a default quantity of value 1, uncertainty 0, and no units. (Note that even when there are no units; the object should still contain a map object; it will just be a map with no entries.)
  
  
• A constructor that takes a single Quantity argument, and creates a copy (i.e., copying the numeric parts and creating a new map with the same units and exponents).
  
  
• A constructor taking 4 arguments: a double (the numeric value), a double (the uncertainty), a List<String> of the units in the numerator (i.e., with positive exponents), and a List<String> of the units in the denominator (i.e., the units with positive exponents). For example, we can use this constructor to represent the quantity \(9.8 \pm 0.1 m/s^2\)

           new Quantity(9.8, 0.0, Arrays.asList("m"), Arrays.asList("s", "s"))
  

  You may assume that neither list argument will be null (lack of a list object), but either list might have size 0.
  
  
• A method multiply that takes a single Quantity argument, multiplies this by it, and returns the result.
  The result should be a brand new Quantity object; neither this quantity nor the argument quantity should change!
  
  
• A method divide that takes a single Quantity argument, divides this by it, and returns the result.
  The result should be a brand new Quantity object; neither this quantity nor the argument quantity should change!
  
  
• A method pow that takes a single int argument (positive, negative, or zero!), raises this to the given power, and returns the result.
  The result should be a brand new Quantity object; neither this quantity nor the argument quantity should change!
  
  
• A method add that takes a single Quantity argument, adds this to it, and returns the result.
  The result should be a brand new Quantity object; neither this quantity nor the argument quantity should change!
  If the two quantities involved do not have the same units, your method should abort with an exception:

     throw new IllegalArgumentException("...informative message goes here...");
  

  When checking whether the quantities have the same units: the .equals(...) method for two maps should do what you want, as long as the maps don't associate any unit with the zero exponent.
  
  
• A method sub that takes a single Quantity argument, subtracts it from this, and returns the result.
  The result should be a brand new Quantity object; neither this quantity nor the argument quantity should change!
  

  As with add, you should throw an error if the two quantities involved do not have identical units.
  
  

• A method toString() that returns the quantity as a string. So that we can test your code, please put

  import java.text.DecimalFormat;
  

  at the top of your file, and paste the following code into your Quantity class, and update the first few lines to match the names of the fields in a Quantity:
  

    public String toString()
    {
      // XXX You will need to fix these lines to match your fields!
      double valueOfTheQuantity = this.NAME_OF_RELEVANT_FIELD;
      double uncertaintyOfTheQuantity = this.NAME_OF_RELEVANT_FIELD;
      Map<String,Integer> mapOfTheQuantity = this.NAME_OF_RELEVANT_FIELD;
   
      // Ensure we get the units in order
      TreeSet<String> orderedUnits = 
        new TreeSet<String>(mapOfTheQuantity.keySet());
      
      StringBuffer unitsString = new StringBuffer();
      
      for (String key : orderedUnits) {
        int expt = mapOfTheQuantity.get(key);
        unitsString.append(" " + key);
        if (expt != 1)
           unitsString.append("^" + expt);
      }
      
      // Used to convert doubles to a string with a 
      //   fixed maximum number of decimal places.
      DecimalFormat df = new DecimalFormat("0.0####");
  
      // Put it all together and return.
      return df.format(valueOfTheQuantity) 
             + " ~ " 
             + df.format(uncertaintyOfTheQuantity) 
             + unitsString.toString();
      
    }
  

• A boolean method equals that takes any single Object, and returns true if that object is a Quantity (you can test that with “if (... instanceof Quantity) ...”) and its toString() returns the same string as this.toString(). (Hint: don't forget to use .equals(...) instead of the =; they need to be strings with the same contents, not literally the same String object in memory.)
  
  
• A method hashCode() that returns an integer, such that equal Quantities always return the same integer. (Hint: this.toString().hashCode())
  
  
• A public static void main(String[] args) method that includes at least 2 tests for each method, e.g., creating quantities, printing them, doing arithematic and printing the results, etc. Just remember to use add and sub only when quantities have exactly identical units.

Part 2: Extending Quantity.java (25 points) — Individual or Pair

    Map<String,Quantity> db = new HashMap<String,Quantity>();
    List<String> emp = new ArrayList<String>();  
                          // Sadly, Arrays.asList() gives an empty list of Objects
                          //   instead of an empty list of Strings.
    
    db.put("km", new Quantity(1000, 0, Arrays.asList("meter"), emp));
    db.put("day", new Quantity(24, 0, Arrays.asList("hour"), emp));
    db.put("hour", new Quantity(60, 0, Arrays.asList("minute"), emp));
    db.put("minute", new Quantity(60, 0, Arrays.asList("second"), emp));
    db.put("hertz", new Quantity(1, 0, emp, Arrays.asList("second")));
    db.put("kph", new Quantity(1, 0, Arrays.asList("km"), Arrays.asList("hour")));

• A static method normalizedUnit that takes a String (the name of a unit) and a Map<String,Quantity> (a units database). It should create a brand-new normalized Quantity equivalent to 1 of the given unit. For example, if db is the database defined above, then Quantity.normalizedUnit("km", db) should return the quantity 1000 meter; Quantity.normalizedUnit("hour", db) should return the quantity 3600 second; and Quantity.normalizedUnit("kph",db) would return the quantity 0.27777... meters per second.
  
  
• A method normalize() that (takes in the database and) returns a copy of this but in normalized form (with all defined units expanded out into primitive units). For example, normalizing the quantity 60 kph, given the above database, should produce the quantity 16.6666... meters per second.
  
  
• Extend your main method with at least 3 tests for each of these methods.

For normalizedUnit, either the given unit is primitive (in which case the answer is easy to construct), or it has a definition in the database that could be normalized.

Similarly, to normalize a quantity like 30 km^2 / hour, it suffices to observe that

1. The products, quotients, and power of normalized quantities are normalized, and
2. \[ \begin{array}{r@{\qquad}c@{\qquad}l} 30\ \mathrm{km}^2/\ \mathrm{hour} & = & \displaystyle 30\ \mathrm{km}^2/\ \mathrm{hour}\quad \times \quad \left(\frac{\mbox{1000 meter}}{\mathrm{km}}\right)^2 \quad \times \quad \frac{\mathrm{hour}}{\mbox{3600 second}}\\ \ \\ &=& \displaystyle \displaystyle 30\ \mathrm{km}^2\ \mathrm{hour}^{-1}\quad \times \quad \left(\frac{\mbox{1000 meter}}{\mathrm{km}}\right)^2 \quad \times \quad \left(\frac{\mbox{3600 second}}{\mathrm{hour}}\right)^{-1}\\ \end{array} \]
3. The quantities “1000 meter” and “3600 meter” should look familiar from the discussion of normalizeUnit.

Totally Optional Extra Credit (up to 10 points) — Pair or Individual

Add a method convert to your Quantity class, that returns the result of transforming the specified quantity into specified units. For example, if we have a Quantity q representing 100 km/hour, then q.convert(...) with the right arguments should create a brand-new Quantity representing 1666.66667 meters/minute, and with other arguments should create a brand-new Quantity representing 27.77778 meter-hertz.

If the given quantity would not make sense in the requested units, throw IllegalArgumentException (including a helpful string describing the specific error).

In main, add several tests demonstrating your convert method in action.