Software Specification (2IX20)

2023–2024
Assignment 1: Requirements and UML

The purpose of this assignment is to prepare a first model of a software system. This
includes both a (non-formal) requirements specification, as well as UML models for
several aspects of the system.

1 Introduction
Because this assignment concentrates on the specification and documentation of re-
quirements, and developing UML models, instead of eliciting requirements from clients
or stakeholders, the problem domain is one that you should already be (somewhat)
familiar with.
We describe the assignment fairly precisely, but frame it also from a challenge-based
point of view. That means you will inevitably also need to do some research yourself
to find out details about the system you are modelling. You can also take into account
your own knowledge of the problem domain in completing this work.
You are to complete this exercise in teams of 2, as registered in the assignment 1
groups on this course’s Canvas page.
When working in teams, your colleagues may have differing views about the require-
ments and models. You should reach some kind of consensus about the requirements
and modelling choices, and document your design decisions as good as you can. There
is more than one possible “right answer” for this project.

2 System description
The Panama Canal is a man-made canal with locks connecting the Atlantic and Pacific
oceans. The canal is roughly 26 meters above sea-level. To allow ships to move through
the canal, it has three flights of locks. On the Atlantic side, the Gatun locks are a
flight of locks consisting of three chambers, see Figure 1. On the Pacific side of the
channel, the Pedro Miguel locks consist of a single chamber, moving ships between the
Miraflores lake and the canal, and the Miraflores locks, consisting of two chambers,

1
Figure 1: Panama Canal Gatun Locks. By Stan Shebs, CC BY-SA 3.0. Via Wikimedia
Commons.

moving ships between the Pacific Ocean and Miraflores lake. In reality, each set of
locks is paired, meaning that there are two parallel flights of locks for each of the sets
of locks. For the sake of this assignment, we simplify the problem somewhat, and only
consider a single flight of locks for each of the sets of locks, instead of the paired setup.
A sketch of the Panama canal and its locks is given in Figure 2.
In 2016, additional locks with larger capacity were added, the Agua Clara Locks
and the Cocoli Locks. We will ignore these new locks in this assignment. So, you
only have to focus on the Gatun, Pedro Miguel and Miraflores locks. See https:
//en.wikipedia.org/wiki/Template:Panama_Canal_map for a schematic overview
of the Panama Canal and its locks.

2.1 Flight of locks

A flight of locks consists of n lock chambers, with n + 1 doors controlling access to
these chambers. An example of a lock with three chambers is shown in Figure 3.

2.2 Lock chamber

A lock chamber has two doors. Because of the different water levels on either side
of the lock chamber, during normal operation the two doors cannot be opened at the
same time. Ships can either be moved up or down. To change the water levels, the
lock chamber has sets of culverts. One set allows water to flow from the high side (or
a water basin) into the chamber in order to raise the water level. The other set of
culverts allows water to flow from the chamber to the low side to lower the water level.

2
 Figure 2: A schematic overview of the Panama canal

Water flow through the culverts is controlled by a valve that can be opened (to allow
water to flow) and closed (to stop the flow).
The doors of the locks and the control mechanism of the doors and the valves of
the culverts are supplied by the manufacturer. The internal mechanisms of these are
assumed (given). In Figure 4 we show the details of a single lock chamber that is part
of a flight of locks.
Each chamber has two pairs of doors. On one side of the lock, the water level is low,
and on the other side of the lock, the water level is high. Note that pairs of doors may
be shared with adjacent lock chambers. The chamber contains two culverts, that have
a valve to open and close the culvert. One culvert is used to raise the water level in
the chamber, the other is used to lower the water level in the chamber. A door can
only be opened if the water level on both sides of the door is equal. Both doors cannot
be open at the same time.
A control system operates the system of locks in the Panama canal. Every set of
doors can be opened or closed. Every door has a sensor indicating whether it is closed
or open. Each lock chamber has a water level sensor indicating the water level inside
the lock.

3 Assignment
You need to design and model a control system that allows ships to pass through the
Panama canal. The system should at least adhere to the following description.
When a ship makes passage through the canal, it can request to pass a specific flight
of locks in a specific direction. The control system receives such requests. Based on
the current status of the flight of locks (e.g. is there oncoming traffic that needs to
be handled first, are there other ships waiting that are allowed to pass first, etc.) the
control system takes action. It, for instance, controls the lock such that the water level

3
 Chamber 1 Chamber 2 Chamber 3

Figure 3: A flight of locks

is set to the appropriate level and the doors are opened. Subsequently it notifies the
ship that it is cleared to enter the lock chamber. Once the water level raised/lowered
and the doors are opened, the ship is again notified that it can move to the next lock
chamber, or that it can leave the lock. In other words, the control system communicates
with ships, and it receives inputs from the sensors and controls the actuators from the
different locks/lock chambers.
A very high-level interface of the control software is given in Figure 5. The control
software in the figure is very simple, since it is connected to only one lock chamber.
Your objective is to model a control system for controlling the three flights of locks in
the Panama canal (Gatun, Pedro Miguel and Miraflores).

3.1 Robustness and unexpected actions

The description given above focuses on the normal behavior of the control system.
When designing your system, you should keep in mind the safety of the system. Once
you have a model that describes the normal behavior, you should extend the model
with exceptional behavior. For this, think about what can go wrong, and how you
could model this.1
We next give some ideas of exceptional situations that you can consider, but you
may of course use your imagination to add more or to model others.

1 Thiswill surely give you extra fun (and of course, depending on how well you execute it, extra
points).

4
 Culvert

Valve

Door sensor Door sensor

Low doors Water level sensor High doors

Valve
Culvert

Figure 4: A lock chamber

For instance, you may wonder what should happen if an emergency happens while
opening or closing the door. Can the door be stopped while it is opening or closing?
You may also consider what happens, e.g., if a door does not close, or a valve does not
open.

4 Assignment
The description in the previous section gives a general idea of how the control software
works. Although fairly precise, once you start working on the requirements and the
models, you will observe that a lot of things are unclear. When developing software as
a software engineer, you will discover that this is a fact of life. Things that are unclear
are typically resolved by talking to the stakeholders in the requirements elicitation
process.
You may be familiar with the functioning of locks. You can use your own experience
to help you understand the details of the system for which you are trying to specify the
requirements. Also, use online resources to get a better understanding of the Panama
canal and its lock systems.
Since the assignment is fairly open-ended, the tutor in the tutorial sessions will
probably not be able to answer detailed questions about the system that you are mod-

5
 request passage up/down grant access to chamber

open/close low door low door opened

open/close drain valve low door closed
open/close high door Control software high door opened
open/close fill valve high door closed
water level

Figure 5: Control software interface

elling. However, the tutors should be able to help you think about the problem, and
discuss design decisions and modelling alternatives. You are definitely allowed to use
the information you find to make such design decisions, and you can make additional
assumptions in order to clarify and/or interpret the description in the previous sec-
tion. You are also allowed to deviate from the interface of the control system described
above. In all situations where you make assumptions or design decisions, or
where you deviate from the description in this assignment, motivate your
assumptions and document your design decisions in the report.
In this assignment, you will create a report that covers the following topics:
1. Requirements of the control software
2. A use case diagram and detailed use case descriptions for the control software
3. A class diagram for the control software
4. State machine diagrams for the control software
5. A sequence diagram for the control software
6. An activity diagram for the control software
Each of these will be specified in more detail below.

4.1 Deliverables
The deliverable for this assignment is a report that contains the requirements and
all the models, as a single PDF file. The assignment is to be handed in using the
submission page in Canvas. UML models should be drawn using a software tool (e.g.
UMLet or its online version UMLetino), and should adhere to the UML standard as
used in this course. Each of the models in the report should have textual explanation.
Design decisions and assumptions should be documented.

6
4.2 Tasks
Since modelling the full control system for locks in the Panama Canal will take more
time than is available in this course, you are required to model parts of the system.
To restrict the amount of work, you should complete each of the following tasks, and
include the result of the task in your report (1 section for each of the tasks).

1. Describe the requirements of the control software. Make sure to take into
account the guidelines described in the reader. Make sure you first identify
the system. You should identify at least 4 actors. You shall include at least 7
requirements. To define actors and inputs and outputs, you probably need to
extend the interface to deal with exceptional behaviors.

2. Define use cases and organize them in a use case diagram. You should follow
the methods described in this course. Make sure you extract the use cases from
the requirements (and possibly the informal description). Organize the use cases
in a (single) use case diagram, and write a detailed description for all the use
cases defined in the use case diagram. Your use case diagram shall contain at
least 4 actors and at least 4 use cases. The number of use cases you describe
should not exceed 8. Furthermore, it shall contain at least one “include” or
“extend” relationship. To keep the use case diagram simple, you can focus on
the ones that you consider most important.
3. Model a class diagram for the control software with at least 5 classes. Make
sure you also include an informal description of the class diagram that motivates
the most import design choices.
4. Give state machine diagrams that capture (the most important parts of)
the behavior of the control software. Your report shall contain at least 2 state
machine diagrams describing different aspects of the control software.

5. Give a sequence diagram describing the sequence of the interactions needed to

allow a ship to make passage from the Pacific through the Miraflores and Pedro
Miguel locks, under the assumption that no exception occurs, and that there is
no other traffic in the canal. Also describe how this sequence diagram relates to
other diagrams in your report.

6. Give an activity diagram for the use case where a ship arrives at the high side
of the Miraflores locks, and it must be allowed to move to the Pacific Ocean.

4.3 Reflection
At the end of your report, include a section in which you reflect on the assignment.
This should consist of the following:
1. Description of difficulties you encountered, or any questions you still have.

7
2. Brief description of the contributions of both team members. Should it turn out
that there are large differences between the contributions of the team members,
this may affect the individual grades.