Design Study - 2
Heated Earth

Background

Software architecture issues come into play when non-functional requirements force design trade-offs. This project uses the same application domain as the Heated Plate project, but generalizes it to simulate the temperature of the planet Earth as it is heated by the Sun. The project also asks you to explore issues of software architecture. Specifically, it adds in considerations of initiative and concurrency.

Initiative

Consider two components A and B that must cooperate in order to satisfy a system's requirements. A produces data that B consumes. There are several ways that overall system initiative may be managed. In a push architecture, when A produces data, it invokes B to consume it, passing the data as a parameter of the invocation. In a pull architecture, when B is ready to consume more data, it invokes A, which returns the data as its result. Of course, a problem can arise when A's rate of production does not correspond to B's rate of consumption. In this case, one or the other of A and B must sit idle while the other catches up. To deal with this problem, a third scheme introduces a buffer component, Q, between A and B. A can then send data to Q, and B can fetch it from Q. If the capacity of Q is large enough and the difference in work rates between A and B is not too great, the composite system can work with improved efficiency.

For this project, you will explore all three options for connecting a producer of data to its consumer.

Concurrency

Simulations can be computationally costly and organizationally complex. A way to cope with these limitation is to make use of concurrency; that is, to partition a simulation into concurrently executing components. For example, many simulations ca be partitioned into computational and visualization components that can benefit from executing concurrently.

Concurrency can be achieved in a variety of ways. Java provides threads as an integral part of its virtual machine. It also provides an API for remote method invocation (RMI), in which a called method runs on another Java virtual machine (JVM). The remote JVM may be on the same physical hardware or across a network on another box.

Concurrent computation entails overhead. Data and requests must be communicated among the concurrent components. This overhead must be traded off against the overall responsiveness and increased throughput due to the concurrency. Concurrency has another cost--added complexity due to synchronization. That is, the components must agree to how and when they are going to coordinate their executions. The coordination adds additional moving parts to the overall architecture. This global complexity must be weighed against the improvement in modularity that arises from being able to treat different aspects of the overall computational task relatively independently.

For this project, you will explore different concurrency configurations available with threads.

Simulating the Heating of the Earth

Simulating the climate of the Earth is an enormous challenge. Factors such as solar radiation, ice caps, cloud cover, volcanic ash, and deforestation compound with better-understood factors such as axial tilt and orbital eccentricity. For the purposes of this project, the following enhancements should be made to the previous Heated Plate simulation.

Spherical surface: The plate upon which your computation is performed is altered in significant ways. The intent is to enable the modeling of the temperature distribution on the spherical surface of the Earth. That is, the east and west edges of the plate are joined so that heat can flow between them. Also, the north and south ends of the plate fold inward to meet at the poles. The grid is now defined by latitude and longitude lines. The latitude lines are equally spaced but of reduced length as they near the poles. Longitude lines are all the same length but get closer together as they near the poles. This means that the shape of a grid cell is no longer rectangular. You may still assume that each cell has four neighbors. But in calculating the new temperature for each cell, the contribution of a neighbor is prorated by the extent of the cell's common boundary with it.
External energy source: Because of the new topology, there are no longer any edges to supply heat. Because there are no such edges, instead grid cells receive externally supplied energy during each time period. This takes the form of an energy source (the Sun) at a given distance from Earth and with a given radiation output. That is, each grid cell receives heat from each of its neighbors in addition to the energy it obtains from the Sun. At a first approximation, the heat obtained from the Sun is proportional to the surface area of the cell. The effects of rotation and lattitude are described below.
Cooling: In the absence of cooling, the irradiated Earth would continue to increase in temperature indefinitely. We therefore assume that each cell loses a percentage of its heat to space during each time period in proportion to its surface area. This is a distinct effect from the diffusion of heat to its neighboring grid cells.
Incident angle for radiation: On an irradiated sphere, the angle at which the radiation arrives affects the amount of heat transferred. That is, at noon, when the Sun is directly overhead, the heating effect of radiation is greater than at sunrise or sunset when the angle of incidence is much greater. Also, radiation arriving at the poles for any given unit of area is reduced as compared with that arriving at the Equator. The attenuation is proportional to the cosine of the angle of incidence. In the east-west dimension, a cell on the side of the Earth facing the Sun has its radiation reduced proportionally to the cosine of the absolute difference between the cell's longitude and the longitude of the cell directly under the Sun. For example, at noon, the two cells are the same, the difference between their longitude's is zero, the cosine is one, and so there is no reduction. At 3:00 or 9:00, the difference in longitude's is 45°, the cosine is .707, and so only 71% as much energy is received per unit of cell area. In the north-south dimension, the same reduction takes place with respect to latitude--sites at 60° latitude receive only 50% of the heating effect of the Sun per unit of area as those on the Equator. In summary, there is attenuation due to the time of day and attenuation due to latitude. The overall reduction is the product of the two factors.
Rotation: The Earth turns around its axis once every 24 hours. Once a cell rotates so that it is on the side of the Earth away from the Sun, it receive no external energy at all and its temperature begins to drop significantly. After sunrise, however, when it begins to face the Sun again, its temperature starts to rise.

Assumptions

The factors mentioned above should be taken into account when constructing your simulation. In addition, you should make the following simplifying assumptions.

The Sun is a point source with constant radiation output per unit of time.
The Sun is directly over the Equator; that is, the Earth is not tilted with respect to the Sun.
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.
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 considerd to be planar.
Grid spacing in degrees is the same for both latitude and longitude. Longitude lines are aligned with the axis of rotation. Latitude lines are perpendicular to longitude lines. Consequently, each grid cell is a trapezoid. Moreover, the angular spacing of grid cells divides evenly into 180°.
All grid cells cool in proportion to their current temperature, irrespective of their latitude.
Across the entire surface of the Earth, total cooling exactly balances solar heating.
The Earth is spherical; there is no flattening at the Equator.
The axis of the Earth does not wobble.
None of the radiation the Earth receives from the Sun is reflected.
The Earth'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).
The heating effect of solar radiation on the Earth's surface is uniform. For example, there is no difference in the heating effect over desert, ice cap or water.

Initial Conditions

At the beginning of the simulation the Earth's rotation is such that the Sun is directly over the Equator (noon) at the Prime Meridian (longitude 0°) on December 31, 1999. That is, it is the start of a new day, January 1st, 2000 at the International Data Line.
The temperature of all grid cells is 15° Centigrade.

Program

You should prepare software organized to have at least the following three components.

Simulation engine: Computation of the temperature at locations on the surface of the Earth as it rotates about its axis
Presentation: False-color animation of the temperatures displayed on the Earth's surface as it rotates, along with various associated data, described below
User Controls: Graphical user interface allowing the user to control the simulation and its presentation

Simulation Engine

Your system should be able to simulate the temperature of the Earth as it rotates about its axis. The simulation to be performed depends on the following Simulation Settings.

Grid spacing: positive integer angular degrees between 1° and 180°; default is 15° (one time zone). If the input values does not evenly divide into 180°, you should reduce it to the next lowest number that does so.
Simulation time step: positive integer number of minutes between 1 and 1440 (1 day); default once per minute. This value is not the length of the simulation nor the rate of presentation refresh; rather it controls the mapping from simulation steps to physical time units. That is, how much simulated time passes between temperature recalculations.

Presentation Output

While the simulation is running, the system shall provide a graphical animation that includes the following aspects.

False-color representation of temperature in each grid cell (of the whole Earth, not just the side facing the Sun)
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 two aspects listed above, you should also dynamically update a display of the following information.

Rotational position: that is, some indication of which spot on the Equator is currently directly under the Sun
Time: the number of simulated time since the start of execution
Simulation settings: the current values of the Simulation Settings

User Controls

A mechanism should be provided that allows the user to interactively accomplish the following.

Initialize or change the values of the Simulation Settings
Control the rate at which the presentation is displayed (which is different from the simulation time step described above). This rate can be understand by using an anology with time-lapse photography (TLP). In TLP pictures of a flower are taken every five minutes and shown one per second. The first number (five minutes) corresponds to the simulation time step; the second (one per second) corresponds to the presentation display rate
Start a simulation running
Pause the simulation
Restart a paused simulation
Stop the simulation

Invocation

The name of the simulation program should be EarthSim.Demo. Note that the Java Virtual Machine (JVM) starts each program in a main thread. If in addition, Swing is used, there is a second, event-dispatch thread. The following parameters control what additional threads your program should use.

-s: Indicates that the Simulation should run in its own thread
-p: Indicates that the Presentation should run in its own thread
-t: Indicates that the Simulation should transmit (push) data to the Presentation
-r: Indicates that the Presentation should receive (pull) data from the Simulation
-b: indicates that a buffer component should serve as an intermediary between the Presentation and the Simulation

All four subsets of {-s, -p} are allowed. For example, in the absence of both -s and -p, all three components should run in the same thread. Exactly one of {-t, -r, -b} must be used.

Report

Prepare a report describing your design and the results of your experimentation. The overall report should be no more than twelve pages, not counting screen shots, diagrams, and tables. The report should be structured as follows.

Design

Overview: Overall structure, metaphor, or architecture. Also, describe what you feel is the single most troubling / interesting / complex aspect of the design. State this in the form of a question. Also state possible answers to the question, your choice of approach, and why you chose it
Program characteristics: For your programs, provide its total lines of code, the total size of its class files, the number of classes, the number of operations per class, the number of attributes per class, and the number of inter-class dependencies (see next bullet)
Static description: 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

Class-model design diagram: Major classes, including their non-private operations and attributes, subclass derivations and dependencies. This should not be an analysis diagram; it should not contain any associations (other than aggregations and compositions); and it decidedly should not be a diagram automatically generated from a case tool examining the source code
Interaction Diagrams: Sequence or collaboration diagrams describing the behavior of your system. At least one should describe the interaction required to coordinate the three components during a typical simulation run. Include a textual descriptive of the diagram
Architecture

Components: for each, its name, a paragraph description, and a statement about the nature of any data or controlling information it requires of other components or that it provides to other components
Connectors: for each connection between components, give the nature of the data it communicates and a description of the protocol it implements
Configuration: A "Box and Arrow Diagram" depicting the architecture (the components and connectors)
Architecture style: A short discussion of which style your architecture most closely resembles

Deployment diagrams: Depicting concurrency and initiative options
Low-level design considerations: Describe your choices for algorithms and data structure representations
Non-functional requirements: With which non-functional requirements did your design have to deal? For each, indicate how your design dealt with it. That is, explicitly state the design decisions that you had to make and your reasons for making them
GUI design: Describe how you selected the user controls and how you chose the particular visualization you ended up using. Also, describe the interface between the computational and user-interface pieces of the program and why you chose to do it the way that you did
Statechart diagram: Provide a statechart describing user-controllable/visible behavior
Code reuse: Include a description of the extent to which you were able to borrow code from the first design study (or the code provided above) and what you had to do to it to adapt it to this project. In particular, for each instance of reuse, describe its source and its contribution to Project 2
Reflection: Provide a post-mortem evaluation of your design and the resulting implementation, specifically, what worked, what didn't and why?

Limit the textual part of this section to six pages.

Design Study

Your program is capable of being run in multiple configurations. You should experiment with your program comprehensively and prepare an analysis of the issues involved in choosing a configuration. In particular, you should conduct a design study similar to what you did for Project One. Your design study should investigate the following issues.

Initiative: What are the effects of initiative on the structure and elegance of an architecture? On system performance? On memory use?
Concurrency: What are costs and benefits of using threads to provide concurrent computation?
Recommendation: What specific configuration would you recommend?
Initial conditions: How long did it take for your simulation to stabilize? How did this depend on the initial conditions?
Coarseness of the lattice: What effect did cell size have on the other factors?
Usability: How you would determine the usability of your presentation and controls? Note, you are not actually required to perform a usability study, only indicate how you would perform such a study
Adaptability: Subsequent projects may make use of the code that you built for this exercise. One way that this can be anticipated is to produce change scenarios. A change scenario is a description of a likely future change and an estimation of the effect that it will have on a design. Prepare at least six change scenarios for the heated-plate simulation. Four of them should anticipate functional changes, and two should discuss quality changes (changes to non-functional requirements). For each you should describe the enhancement and provide an assessment as to the resilience of your design to this change and why

Limit the textual portion of this section to six pages.

Presentation

You should expect to give a project overview and demo of your program in class. Plan for the presentation to last no more than ten minutes. The presentation should include the following information. A single speaker, who has not previously presented, should make your presentation although another team member can help with the demo

Team name, members, and roles
Description of the software architecture you employed including a "box and arrows" diagram
Summary of your study results
Demonstration of program execution

Mechanics

You should work on teams for this project. Atlanta team membership can be found here. Korean team membership can be found here. French team membership can be found here.
Create a team Swiki page and place a link to it from the class Heated Earth Project page. On your team page, include links to the class Swiki pages for each team member.
Place a link to your report on your team Swiki page. The report itself should be directly printable as a single PDF file.
You are free to use any drawing or CASE tool, including Visio, to draw your diagrams. Please export the resulting diagrams so that they can be printed from a browser.
Zip up your Java files, along with any installation/configuration instructions. Link your zip file to the Swiki page. Do not include class files.
You are free to use whatever machines you wish to build and test your programs. You are free to run your design studies on whatever machines you wish. However, your program must successfully build and execute on the the machine used by your grader without intervention by you. You should arrange for this with the TA in advance
You are encouraged to make use of code from the Heated Plate project, properly cited, and the code supplied above.
Your programs should be entirely buildable from your sources and the SUN JDK APIs. That is, no third party source code should be used.
An experimental description of the Heated Earth domain can be found here.

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 Design Description is given here
Grading criteria for the Design Study is given here

Design Study - 2 Heated Earth