CS4330/6310
  Heated Planet Design Study

Background

This project uses the same application domain as the Heated Plate and Heated Earth projects, but adds new functional and non-functional features. It asks you to prepare a simulation of the temperature of an arbitrary planet that includes a tilted axis and an elliptical orbit around the Sun. In addition, it includes the ability to persist simulation data.

Persistence

Simulation can be computationally costly. If a scientist needs to know a specific fact, such as the expected average temperature at the South Pole in the next century, and another scientist has already conducted a simulation study that answers the question, then it makes sense to use the existing result rather than to rerun the simulation. However, it must be the case that the existing simulation data satisfy all required scientific conditions.

Persistence is a property of an application in which some of its data outlive the execution of the program that computed them. Persistence is often achieved by storing the data in some form of repository such as a database management system (DBMS), formatted documents (XML) or so-called flat files. Clients of this data can be the original application, other similar applications, a query interface provided by the DBMS or a newly written query interface program. In each case, input requests are analyzed to determine whether the required data is available for retrieval or if a simulation must be run.

Simulators can run for long periods of time and generate large amounts of data. One of the design decisions that must be made in situations like this is how much data to save. In the case of the Heated Planet simulation, at one extreme is the saving of the temperature at every grid cell for every time period for all previously run simulations. At the other extreme is saving nothing and forcing a rerun for each request. The interesting situations are in between. That is, some values are saved, some are recomputed and others are computed by interpolating from saved values. For example, a geographically distributed sample of grid points might persist for all time periods, and requests for non-existent data would be satisfied by geographic interpolation. Alternatively, all grid points could be saved, but only for a sample of time periods. In this case, requests for missing data could be satisfied by temporal interpolation.

Using interpolation reduces output quality; that is, interpolated values may not provide as accurate or as precise a picture of the situation as would be obtained by redoing the simulation. Hence, one trade-off is between the amount of external storage used and the quality of the results obtained (accuracy and precision). Another trade-off is the classic time-space trade-off inherent when any data is stored rather than being recomputed.

Simulation

The Heated Planet simulation for this project adds the following functional requirements to those used in Project 2.
  1. Orbit: In Project 2, it was assumed that the Earth was always the same distance from the Sun; that is, that it traversed a circular orbit. Actually the orbit of our planet is not quite circular; it is an ellipse with two nearly equal axes. Other planets have more eccentric orbits. If the lengths of the two axes of an ellipse are 2a and 2b, then the eccentricity of an ellipse is a non-negative number equal to sqrt(abs(difference(square(a), square(b))))/max(a, b). This should be a number greater than or equal to zero and strictly less than one. Your simulation for Project 3 should allow the eccentricity to be set by the user, with a default value of .0167; that is, our Earth's eccentricity. Note that the one implication of an eccentric orbit is that the amount of heat arriving at the planet from the Sun depends on the distance between them according to the inverse-squares law. Another is that the planet travels at different speeds during different parts of its orbit, thereby altering the number of daylight and nighttime hours.
  2. Tilt: In Project 2, the axis of the Earth was perpendicular to its orbital plane. In reality, of course, the axis of rotation of the Earth is tilted with respect to its orbit around the Sun. This is what causes the seasons. For example, on March 21st, the tilt or obliquity is perpendicular to the line between the center of the Earth and the Sun (i. e. the Sun is directly overhead at noon on the Equator). During the next three months, it gradually moves so that on June 21st, the Northern Hemisphere is pointed toward the Sun at an angle of 23.44°. This orbital movement has the effect of adjusting the vertical angle of incidence of each cell. For example, for a point on the Equator at noon on June 21st, the sunlight received is reduced to the cosine of  23.44° or 91% of its nominal value. Your simulation for Project 3 should allow the user to set the tilt to any value between ±180°. The default should be +23.44°.

Assumptions

The adjusted assumptions from Project 2 are listed here.
  1. The Sun is a point source with constant radiation output per unit of time.
  2. All grid cells cool in proportion to their current temperatures, irrespective of their latitudes.
  3. The orbital period is 366.24 planetary rotations (sidereal days).
  4. The orbital direction around the Sun is such that with the default values of tilt and eccentricity, Summer will occur in the Northern Hemisphere between June 21st and September 21st.
  5. The planet's atmosphere plays no role, either in attenuating solar radiation or insulating against cooling loss. In general, there is no convective heating, only radiant (from the Sun) and conductive (from neighboring cells).
  6. The planet is spherical; there is no flattening at the Equator.
  7. The axis of the planet does not wobble.
  8. The size of a grid cell is small enough that it is uniformly heated by the Sun. That is, all points in the cell can be treated as being the same distance from the Sun and receiving radiation at the same angle.
  9. Grid spacing in degrees is the same for both latitude and longitude. Longitude lines are parallel with the axis of rotation. Latitude lines are perpendicular to longitude lines. Consequently, each grid cell is a (possibly degenerate) trapezoid.
  10. Cooling of the planet is such that it exactly balances Solar heating for each time step.
  11. At any given time, each point on the surface of the planet is the same distance from the Sun.
  12. Cartesian geometric computation are sufficiently accurate for this project. That is, you do not have to worry about spherical coordinates. In particular, each grid cell can be considered to be planar.
  13. None of the radiation the planet receives from the Sun is reflected. Moreover, the heating effect of Solar radiation on the planet's surface is uniform. For example, there is no difference in the heating effect over desert, ice cap or water.
  14. The relative masses of the Sun and the planet are such that the focus of the planet's elliptical orbit can be approximated as the center of Sun.
  15. There are no perturbations to the planet's orbit arising from other planets in the Solar System or from any moons.

Initial Conditions

  1. The start date of each simulation is January 4th with the planet at its closest point of approach (perihelion) to the Sun.
  2. On each December 21st, the South Pole of the planet's axis is tilted directly at the Sun.
  3. At the beginning of the simulation, the planet's rotation is such that the Sun is directly overhead (noon) at the Prime Meridian (longitude 0°). That will make the time midnight, January 4th at any position on the International Date Line (longitude 180°).
  4. Initial temperature of all grid cells is 288° Kelvin.

User Interface

A primary goal of the system is, to the extent possible, to hide from the user whether the data is being computed or retrieved. That is, the user interface should be constructed in such a way that the user requests certain data and the system determines whether it needs to perform a computation or can retrieve previously computed data. This kind of abstraction is sometimes called transparency. That is, the system should be transparent to the user with respect to the source of the data it returns.

When the system is given a request, several issues arise. First, the simulation's Physical Factors (described below) may match those for a previously executed simulation. On the other hand, other details about the requested data (Simulation Settings, also described below) can be considered as approximations, allowing the system to interpolate from existing data. Another implication of data-source transparency is that the animated presentation of the data should work regardless of whether the data is computed or comes from stored data.

A more precise description of the user interface requirements are given below.

Deliverables

You are to prepare two deliverables--a software simulation system and a report. In addition, you are to prepare an in-class presentation of your design study and a demonstration of your software.

Program

Simulation Software

You should prepare software that provides the following features.
  1. Computation of the temperatures at locations on the surface of a planet as it rotates about its axis and orbits the Sun
  2. Graphical user interface for controlling the simulation and enabling the setting of initial conditions
  3. False-color animation of the temperatures displayed on the planet's surface as it rotates and orbits
  4. Query interface for retrieving computed values

Computation

Your system should be able to simulate the temperature of the planet as it rotates about its axis and orbits the Sun. The following Physical Factors affecting the computation should be included in the simulation model.
  1. Axial tilt: integer degrees between ±180°; default is +23.44° (toward the Sun) in the Northern Hemisphere
  2. Orbital eccentricity: non-negative real number less than one; default is .0167
In addition to the above, the simulation to be performed depends on the following Simulation Settings.
  1. Name: unique text string denoting the simulation
  2. Grid spacing: non-negative integer angle between 1° and 180°; default is 15° (one time zone). Only values that evenly divide 180 need to be considered
  3. Simulation time step: non-negative integer minutes between 1 and 525,960 (1 Solar year), logarithmically graduated; default once per Solar day (1440 minutes)
  4. Simulation length: non-negative integer (Solar) months between 1 and 120; default 12 (one Solar year)

Graphical User Interface

The user should be able to interactively use the following Controls.
  1. Set the Physical Factors
  2. Adjust the Simulation Settings
  3. Control the rate at which the presentation is displayed
  4. Start the simulation running
  5. Pause and restart the simulation
  6. Stop the simulation or retrieval
  7. Determine whether the animation is to be displayed

False-Color Animation

When requested, the system should provide a graphical animation that includes the following aspects.
  1. False-color representation of the temperature in each grid cell (of the whole planet, not just the side facing the Sun)
  2. Point on the planet's surface where the Sun is directly overhead (noon). Note that it is no longer sufficient to assume that this point is on the Equator
  3. Grid lines
I can think of several ways in which #1 can be satisfied: a rotating sphere with a movable view point, two circular hemispherical projections, an unrolled cylindrical projection, or a straightforward unprojected (rectangular) whole-world view. You can choose any of these or come up with your own. See http://www.colorado.edu/geography/gcraft/notes/mapproj/mapproj_f.html for a nice set of pages on map projections. Here is some Java code and documentation from a previous student that may help you.

In addition to the three aspects listed above, you should also dynamically update, either graphically or textually, the following information.
  1. Simulated date and time
  2. Orbital position
  3. Rotational position
Also, the Physical Factors, Simulation Settings, Invocation Parameters (described below) and Controls should be visible for review.

Query Interface

A user's primary interaction with the system takes the form of a query asking for the temperatures at certain specified locations (which might be the entire planet) during specified time periods. If the data is available to the system, that is, if it has been previously computed, it should be retrieved. If not, a simulation should be conducted to produce it.

A user query may include the following information; the syntax of a query and how the user enters it, is up to the designer, as is the formatting of the results.
  1. Name of the simulation (possibly selecting from those available)
  2. A specification of the Physical Factors used to compute the data. When searching for existing data, these factors must match exactly.
  3. Dates and times to be reported on expressed as a contiguous range. That is, the user can specify a single starting date and time and a single stopping date and time. If a query matches the Physical Factors and locations but describe a time range that extends later than the saved data, there is no requirement to extrapolate from the saved data. Instead a simulation should be run just as if no saved data existed. Otherwise, the system must interpolate temperature values for all times not stored from a previous simulation.
  4. Locations to be reported on in terms of contiguous latitude and longitude ranges. That is, the user can specify a single region bounded by two latitude lines and two longitude lines. If the stored data does not exactly match the query, the system must perform an interpolation. Because the planet is spherical, the value of temperature at any point can always be interpolated. The default geographical range is the whole planet.
  5. Note that there may be more than one saved simulation that matches the specified Physical Factors. In this case, the system must select the best matching simulation.
In addition to specifying these inputs, the user can request any combination of the following outputs.
  1. Minimum temperature in the region, when and where it occurred
  2. Maximum temperature in the region, when and where it occurred
  3. Mean temperature over the region for the requested times
  4. Mean temperature over the times for the requested region
  5. Actual values, whether recorded or interpolated, for the requested cells at the requested times. In this case, temperature values for all grid cells in the region should be reported. Moreover, values for all computed time steps should be reported.
Format of the resultant values is up to the designer, but should include qualifications concerning its accuracy, both geographic and temporal.

Invocation

The name of the simulation program should be PlanetSim.Demo. It should be invoked with the following Invocation Parameters to allow the designer to control the execution architecture.
  1. -p d: The precision of the data to be stored, in decimal digits after the decimal point. The default is to use the number of digits storable in a floating point variable.
  2. -g d: The geographic accuracy (sampling rate) of the temperature data to be stored, as an integer percentage of the number of grid cells saved versus the number simulated. The default is 100%; that is, a value is stored for each grid cell.
  3. -t d: The temporal accuracy of the temperature data to be stored, as an integer percentage of the number of time periods saved versus the number computed. The default is 100%; that is, all computed values should be stored.

Persistence

Results from all simulations should be persistently stored. In addition to the Physical Factors, Simulation Settings, and Invocation Parameters saved for each simulation, the following data should be stored for each grid cell.
  1. Latitude: degrees North or South of the Equator
  2. Longitude: degrees East or West of the Prime Meridian
  3. Temperature: degrees Kelvin
  4. Reading date: simulated date at which the temperature reading was taken in terms of years and days since the start of the simulation
  5. Reading time: hours and minutes since the start of the Reading Date
The storage media you use, that is, whether the data is stored in a database, formated document or flat files, is up to you. So also is the data format (XML, text, binary, NetCDF) in which the data is stored.

Report

Using the program you have built, perform a design study examining the trade-offs inherent in persistence. That is, for persistence, you should vary the sampling percentage and the precision and then measure accuracy, response time, and required storage. Provide explicit conclusions about the costs and benefits of persistence, including discussion of code complexity and maintainability.

The overall report should be no more than thirteen pages, not counting screen shots, diagrams, design-pattern descriptions and tables. The report should be structured as follows:

Design

Describe your logical design. What were the major classes used, and what were their roles in the architecture? Refer to the accompanying class model diagram. (Major classes are top-level, having their own Java files.) How did they depend on each other? (Dependency should be thought of in the sense of UML.) Prepare a table which, for each major non-API class, lists all major non-API classes it depends on and the nature of the dependencies. One way to check whether your table is complete is to make sure that for each non-API package you import there is at least one corresponding dependency listed. Dependency types are described in the following table:

Dependency Type
 UML Stereotype
 Description
calls
 <<call>>
 Source invokes target
creates
 <<create>>
 Source class creates an instance of target
instantiates
 <<instantiate>>
 Source operations creates an instance of target
uses as parameter
Source class contains operation with parameter of target class
returns as result
Source class contains operation that returns result of target class
sends a message to
 <<send>>
 Source sends message of type target
refers to globally
Source class refers to target class, for example, to obtain static final values

Describe your design choices. That is, discuss the alternatives, the choices made and the rationale for the choices. Include answers to at least the following questions:
  1. What medium did you choose to provide persistence, and why did you choose it? Note that for this project, you do not have to implement and compare different persistence mechanisms. But I would like you to make an informed decision. Therefore, I am asking that your decisions concerning persistence medium and format should be documented in tabular format where columns correspond to choices and rows correspond to factors. Each factor is a selection criterion. For example, your amount of experience with a particular medium is a relevant criterion. You should consider a variety of criteria for both (medium and format) decisions.
  2. What format was the data stored in, and why did you choose that format?
  3. The project specification does not constrain your use of concurrency. Describe your choice in this regard and why you made it.
  4. How much code were you able to reuse? How much adaptation was required? What factors affected your decisions?
  5. Any other key decisions you made
  6. In the case where more than one stored simulation matches a query, your program should choose the best. The meaning of the term best is up to you, but you should document it in your report.
Include the following diagrams in this section along with textual descriptions.
  1. One or more class diagrams describing your design
  2. A Deployment Diagram describing your physical architecture
  3. A description of the logical data model for your persistent data. You should augment this with either an ER diagram or a class diagram
Include a description of your code (files, lines, classes, byte code size).

Limit the textual part of this section to six pages.

Design Study

First, describe a set of tests you ran to validate the functioning of the simulation. That is, vary the Physical Factors and note the effect on the heating of the Earth. Note that persistence is of value to the extent that recomputation is expensive. Hence, actual repositories tend to be quite large. At least part of your design study should examine what happens as the amount of stored data grows.

Then present the results of exercising the non-functional aspects of your program. This should include a variety of grid sizes, initial conditions, and command-line options. Present and compare the results of your measurements and draw conclusions about the approaches taken. Include specific measurements of memory use, disc space, response time, and precision.

Note that in simulations such as described here, it may take a while for the system to stabilize. That is, effects due to tilt and eccentricity may not show up until sufficient heating has taken place to overcome the initial conditions. You can measure this effect by computing some measure of variance which will initially decrease until it reaches a steady state. You should only begin making any measurements after this has happened.

A general description of factors to consider in design studies is given here.

Limit this section to six pages.

Post Mortem

Provide a one-page post-mortem of what you think worked well and did not work well with your design. You may comment on process issues, but I am more interested in your thoughts on your design solution.

Extra Credit: Design Patterns

Your grade on the project can include up to three bonus points for each non-gratuitous design pattern used in the program and described in this section. Design patterns built into the Java API, such as Observer or Enumeration, may not be counted as extra credit. There is a limit of five different patterns you may receive points for. Descriptions should include the following aspects.
  1. Name of the pattern
  2. A citation of the source of the pattern, for example, the Gang of Four book
  3. The pattern's use within your program
  4. Implementation issues you had to consider and the choices you made. This discussion should be similar to the Implementation Issues subsection of each pattern description in the Gang of Four book.
  5. A class model diagram showing the generic pattern, similar to what is found in the Gang of Four book. Indicate textually how the classes in the generic pattern map to the classes in your class-model diagram.
  6. A sequence diagram showing how the relevant classes interact, similar to what is found in the Gang of Four book
Limit yourself to no more than one page per pattern described.

Presentation

You should expect to give a project overview and demo of your program in class on the day it is due. Plan for the presentation to last eight minutes. Include the following information.
  1. Team name, members, and roles
  2. Overall design approach, including persistence choice made
  3. Study results
  4. Design patterns used
  5. Demo of program in action

Mechanics

Grading

The primary concern of this project is design and not coding. You should spend considerable time actually designing the programs, planning and executing the design study and preparing your reports. I would rather see a functionally incomplete (but executable program) than a slipshod report. The approximate evaluation weights are 25% to the coding and 75% to the report
Grading criteria for the project are given here.