18-649 Project 8

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.

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. 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.

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.

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.

A Recommendation About Design Verification

Runtime monitoring was introduces in Project 7. In Project 11, you will use runtime monitoring to verify that your design meets the new high-level requirements. Although you are not required to do so, you should look ahead at the monitoring requirements and think about how you can use monitoring to verify your improved design. We strongly recommend that you start using a monitor for verification 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. 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:

Scenario 8A - R-T9
Scenario 8B - R-T9

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.

4. 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.

5. 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.

6. 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:

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.
Project 8 is worth 125 points:

In addition to points explicitly allocated to traceability and portfolio formatting, we may also make random checks and deduct points if we find that you do not submit a complete and consistent design package.

If you choose to work ahead and go beyond the requirements for this project, that is fine. As with previous project phases, you must meet all the stated project requirements for this phase regardless of how much extra work you do.