18-649 Project 8

Smart Dispatcher, Fast Speed, and Correct Lanterns

Check the course webpage for due dates

Please submit all project-related correspondence to

Changelog:

For the midterm project, your group specified, designed and implemented a simple (but inefficient) elevator.  In this project, you will complete testing of your simple design.  You will also begin changes to the dispatcher that will improve the performance of your elevator.  In addition to more sophisticated dispatcher design, we will add some new high level requirements that require more sophisticated behaviors from other parts of the elevator. 

Assignment

1.  Complete testing of the simple design

Your simple design must continue to pass all unit and integration tests.  Since this was a requirement for project 7, this part should already be done.
Note: You are not permitted to use the -il flag
In project 7, you were only required to pass a simple acceptance test.  You must complete testing of your design to pass the following acceptance tests.

*Note:  The acceptance test your write must meet the following requirements:

Another change in the testing procedure is related to the random seeds used to execute the acceptance tests.  Because of the pseudorandom nature of the elevator simulation, if your elevator has subtle bugs, it may pass a test with one random seed and fail with another.  In project 7, the random seed used by the TAs for grading purposes was provided.  In this project 8, an arbitrary random seed will be used, and it will not be provided ahead of time.   In order to thoroughly test your elevator, it is a good idea to run each test multiple times with different random seeds, but how much testing you do is up to you. 

To meet the minimum requirements, you must execute (and pass) each test one time.  If your design fails to pass the test with the random seed chosen by the TAs, you will lose some points, even if the tests passed with the random seed you chose.

If you run the tests multiple times, you should create a separate entry in the Acceptance Test Log for each one.  You can differentiate these tests by putting the random seed used in the "Random Seed" column of the Acceptance Test Log.

For each bug that you find and fix during acceptance testing, you must add an entry to the issue log.

2. Runtime Requirements Monitoring

For the rest of the project you will introducing a new runitme monitor evey week until handin (except for project 9). If needed, review the Runtime Monitoring Overview from Project 7.

2.1  Write a Description of Your Runtime Monitor

To start out, you will provide a written description of your strategy for runtime monitoring.  Take a look at the inputs provided by the Runtime Monitor class.  For each high level requirement state one or more specific run-time checks you could perform to ensure that requirement is being met.  For example, if a high level requirement were "never stops at floor 6" you could write a monitor that threw a warning every time the motor was commanded to stop while the elevator was at floor 6.   You must also include an Event Triggered statechart for each requirment that your runtime monitor is checking. The Event Triggered statechart should mirror the actual state of the elevator and contain both valid and invalid states. An example Event Triggered statechart for the requirement "never stops on floor 6" might look something like this:

Sample statechart

If your elevator ever enters an invalid state, then you should throw a warning. Add your writeup to the High Level Requirements Verification page.  Your writeup must convince us that your verification system enforces all high-level requirements. Your writeup shall not exceed 700 words. For Project 8 you'll be desgining and implementing a monitor for RT 6 and RT 7.

2.2  Write a Runtime Monitor

Now you will implement the checks you described in part 2.1 above.  Add a new class to the simulator.elevatorcontrol package called RuntimeRequirementsMonitor.  Be sure you use the right name because the monitor may be graded by an automated script that relies on this name.  Make sure RuntimeRequirementsMonitor extends simulator.framework.RuntimeMonitor.

Your runtime monitor shall meet the following requirements:

If your monitor does more than monitor the system (i.e. outputs any framework or network messages), or affects the simulation state in any way, you will receive significant deductions on the final assignment.

It is acceptable for your monitor not to throw warnings during startup, but it must register any violations of the high level requirements that occur after the elevator has moved for the first time.

In order to verify that your design meets the requirements, we will run your elevator against our own runtime monitor.  Although the grading monitor is not provided, you will receive the output of our tests in your project feedback.

It might be that you receive a handful (4 to 6) warnings that are due to unusual passenger conditions that put your elevator into a gray area of the specifications (perhaps one you didn't realize you had). An example is if a passenger gets on and then gets off at the same floor/hall. Many teams execute all acceptance tests including the final project with no warnings. If you have a handful of warnings through the final project and they are a result of benign corner cases such as this then that will be OK. (You MUST receive TA approval for any warnings; don't use this as an excuse to blow off things that really do need to get fixed.) Many teams have projects with NO warnings, and we encourage you to get there if you can. In every case we have seen, any team with more than 10 warnings on a huge acceptance test we run for the final project has bugs in their elevator.

The point of the grading monitor is so that students don't slack on their own monitor and then pass all test because their own monitor ignores problems. So if there is a conflict between your monitor and the grading monitor (i.e., your monitor says "OK" and TA monitor doesn't), then what you need to do is help the TAs understand that your monitor is doing a sufficient job in those cases. This should consist both of explaining why representative violations aren't a real problem, and also walking the TAs through the monitor design so they can see that you are monitoring the right stuff.

2.3  Run your monitor

You need to run your runtime monitor on proj7acceptance1.pass. You will, of course, generate an awful lot of warnings, since your code was not written with these requirements in mind. You will log the results of this test in the Verification Results log (verify/verfication.html). In the notes column you will list a time stamp at which you recieve a warning and briefly explain why the waring was issued. This explanation should be a technical description of the behavior of the elevator and the monitor at that moment, not just "The design isn't updated."

A Recommendation About Design Verification

Although you are not required to do so, we recommend that you get a head start on writing monitors for RT 8 - 10 as soon as you have a complete design.  Dispatcher algorithms are very complex and have many corner cases.  You probably won't find all the problems without runtime monitoring.  You should also consider generating additional acceptance tests to further exercise your design.  Again, these are not requirements, but remember that the sooner you identify problems in your design, the easier they are to fix!

3. Begin Fast Elevator Design

From this project forward, your elevator shall meet the following additional high level requirements. 

Add these new requirements to the existing high level requirements in the Requirements I document.

Note:  These high level requirements may conflict with some of the simple controller behaviors provided in the first half of the course.  If you have been using those behaviors up to this point, you will need to modify them in order to meet these new requirements.

Note 2:  If you need to, you can refer back to the  the drive acceleration profile from project 3.

Optional Modifications to Network Interfaces

In order to facilitate more sophisticated and optimized dispatcher behaviors, you may make the following changes for this project or in any future project (when you are ready to do more optimization).  Note that these changes are not required.  You should be able to fully meet all high level requirements with the existing interfaces.  

  1. Add mCarPositionIndicator to the input of the Dispatcher and DriveControl, OR
  2. Add mDriveSpeed and mCarLevelPosition to the input of the Dispatcher.

If you choose to change the make one of the above modifications, you must document the change in the following ways:

You should spend some time thinking about the implications of these changes and what optimized dispatcher behavior they might enable.    You are not required to make a change to the interfaces at all, and you may make a change at any time during the rest of the semester (as long as you fully document the change as described here).  Since you are already updating the design, you will likely save yourself some work by making the change sooner rather than later.

4. Sequence diagrams for Fast Elevator design

To meet the new high-level requirements, you will need to update your design, starting with your scenarios and sequence diagrams.  You will update the scenarios and sequence diagrams you have already written and add new ones as needed.  You should modify or add sequence diagrams to address all the new high-level requirements.  Each new behavior (high level requirement) must show up in at least one sequence diagram. 

Follow all the guidelines for scenarios and sequence diagrams from Project 2, including:

Some thoughts on adding scenarios
Each scenario must originate from a valid use case.  Note that the sections in the scenarios and sequence diagrams (2.  Passenger Makes a Car Call, 3. Passenger Enters Car, etc) correspond to use cases.  They are not just section headings.  Any scenario/sequence diagram you add must be added to the Scenarios and Sequence diagrams document in the the section corresponding to the appropriate use case.  This is a form of forward traceability.

It is likely that the existing use cases are adequate to cover the new behaviors., but you may create new use cases if you wish.  You should avoid creating use cases that duplicate the existing use cases.  For example, adding a use case for "Passenger rides in the elevator" would be redundant because that use case is covered by use cases 1-7.    If you choose to create new use cases, you will need to update the use case diagram (and log the change in your issue log) so that your design continues to be complete and consistent.

Sequence diagram numbering
Since you will be modifying your sequence diagrams, it is acceptable to add arcs that are not numbered contiguously with the arcs already in place and to remove an arc without renumbering the arcs.  This will simplify the task of updating traceability and reduce the chance of introducing traceability errors that might be caused by a complete renumbering of arcs. 

You must make sure your traceability is updated to reflect any arcs that are added or removed from sequence diagrams.

Note that the arc numbering must still correspond to the correct step in the scenario (e.g. if you add an arc that goes in the 4th step, it must still be numbered something like "4h").  You can see some examples of this in the sodamachine example portfolio.

Issue log entries
For each externally observable change in the elevator behavior, include an issue log entry describing the modification to the elevator's behaviors and listing the sequence diagrams that are affected by the change, including sequence diagrams that you added to address the new behavior.

Annotate sequence diagram table of contents  
After you have completed your sequence diagrams, make sure the table of contents in the Scenarios and Sequence Diagrams document is complete and up-to-date (with working hyperlinks).  Then add an annotation describing which of the new high-level behaviors (if any) is addressed in that sequence diagram.  For example, if sequence diagrams 8A and 8B include elevator motion where the elevator reaches fast speed, then the table of contents entry for the sequence diagram would be similar to:
Note:  If the above items were really in your Scenarios and Sequence Diagrams document table of contents, the text "Scenario 8A" and "Scenario 8B" would contain a link that points to an anchor tag at the start of each Scenario.

This is a lightweight traceability task designed to help the graders more easily determine whether you have included all the new behaviors in your sequence diagrams.  You only need to trace the new behaviors R-T6 through R-T10, but you should separately trace the subnumbered requirements R-T8.1 through R-T8.3.  Each new high level requirement must be traced to to at least one sequence diagram.

5.  Time-Triggered Requirements for Fast Elevator Design

After you update your sequence diagrams, you will also update your time-triggered requirements to encompass the new behaviors described in your updated sequence diagrams.  Look back at Project 4 and review the guidelines for time-triggered requirements.  You must continue to follow all of those guidelines as you update your design.  You may not modify the constraints listed in the Requirements II document.

Since you will not be updating your event-triggered requirements, if they are still listed in your Requirements II portfolio document, you should remove them now to avoid confusion and ambiguity.

6.  Traceability

Since you have updated your sequence diagrams and requirements, you should also update the Requirements-to-Sequence-Diagrams and Requirements-to-Constraints traceability tables.

Since you have not updated the statecharts to conform to the new behaviors, it is acceptable for the Requirements-to-Statecharts tables to be inaccurate for this project handin only.  You will have to update them next week when you update your state charts.

If you find and fix bugs related to the acceptance testing in step 1, you should continue to log these bugs and update the design and traceability related to those problems.  For example, an acceptance test bug requires you to change a the guard condition on statechart and the related code.  There should be an issue log entry for this bug.   You should also update the statechart-to-requirements and statechart-to-code to be consistent with the changes. 

It is possible (but not likely if you have a clean design) that bug fixes related to acceptance testing will interact with the fast elevator design changes.  In that case, you should think carefully about how this bug might manifest in the new design and what changes you might make to the design accordingly.  If the changes to the design related to the fast elevator behaviors are in direct conflict with the bug fix changes from acceptance testing (e.g. the fast elevator requires one behavior and the bug fix for the old design requires a completely different, incompatible behavior), then you will need to make the bug fix changes in order to pass acceptance tests.  Document the conflicting fast elevator design changes as an unresolved issue in the issue and add them next week.

Keeping track of changes from two sources (new high level requirements and acceptance testing) can be challenging, so you will need to make a special effort to coordinate with your teammates when executing the various parts of this project.

7.  Peer Reviews

Pick the 4 scenarios and corresponding sequence diagrams that have changed the most for your fast elevator, and perform peer reviews on them. (Teams of 3 can pick only 3 if desired.) We suggest you peer review more items, but this is the minimum.

Pick the 4 sets of time triggered requirements that changed the most for your fast elevator, and perform peer reviews on them. (Teams of 3 can pick only 3 if desired.)

Any reasonable interpretation of "changed the most" is fine, but we're willing to bet the dispatcher is going to be one of them. Entirely new items have also "changed" for our purposes, so most gropus will end up picking the most complex four new scenarios and sequence diagrams to review, as well has new behaviors for the dispatcher and some other components.

Team Design Portfolio

The portfolio you submit should contain the most up-to-date design package for your elevator system organized and formatted according to the portfolio guidelines.  You are going to update your portfolio every week, so be sure to keep an up to date working copy. 

Ensure your design portfolio is complete and consistent.

The following is a partial list of the characteristics your portfolio should exhibit:

Handing In Results

Grading Criteria:

The Minimum Requirements spreadsheet is located HERE
This assignment counts as one team grade. If you choose to divide the work, remember that you will be graded on the whole assignment. A detailed grading rubric is available here (PDF).
Project 8 is worth 145 points: