• Due Date: 22 December 2022, before 23:59.
• Team Size: 2 (pair design/programming)!
  Note that as of the 2017-2018 Academic Year, each International student should team up with "local" (i.e., whose Bachelor degree was obtained at the University of Antwerp).
• Submission Information: Only one member of each team submits a full solution. This must be a compressed archive (ZIP, RAR, TAR.GZ...) that includes your report and all models, images, code and other sources that you have used to crate your solution. Do not submit any executables. The report may be either HTML or PDF and must be accompagnied by all images. When an image is unreadable in your report and missing from your submission archive, you will not receive any points for that task. Make sure to mention the names and student IDs of both team members. The other team member must submit a single HTML file containing only the coordinates of both team members. You may use this template. This will allow us to put in grades for both team members in BlackBoard.
• Submission Medium: BlackBoard. Beware that BlackBoard's clock may differ slightly from yours. If BlackBoard is not reachable due to an (unpredicted) maintenance, you submit your solution via e-mail to the TA. Make sure all group members are in CC!
• Contact / TA: Randy Paredis.

This assignment will make you familiar with modelling, simulation and performance analysis in DEVS. You will learn to use modelling patterns to construct a discrete-event simulation from which specific statistics can be obtained and analyzed. This assignment is to be completed with PythonPDEVS. A detailed documentation is available. Take a look at the "Application to Queueing Systems" example to get started with PythonPDEVS. This assignment completes the Nautical Engineering/Port example that was introduced in the previous assignments.

EDIT: the highlighted text has been altered, as opposed to the original assignment.
In this assignment, you will use the DEVS formalism to model a highly simplified version of the movement of ships through the Port of Antwerp. This simplification is shown in the figure/map below. On this map, multiple nodes are used to identify important locations in the port. The bold lines show the connections between these nodes and are labeled with the corresponding distances. These connections can be sailed on in both directions (unless they have an arrow) and are separated in Canals (full lines) and Waterways (dotted lines). For the sake of simplicity, we shall ignore tides and any differences due to upstream/downstream travel (i.e., ships will sail as fast in one direction as in the other). Squares identify Locks, and the numbered diamonds indicate Docks.
Note: The figure is an SVG map, so you can open it in an external tab and look at it in much more detail!
Note: Distances are rough approximations. Additionally, some bridges may not exist in reality.

Vessels arrive at the first Anchorpoint, called "loodskotter" (marked with "K"). Here they wait until they have received their target dock number. This dock is guaranteed to be free upon arrival of the ship. Next, the vessel sails a large stretch of the river Scheldt before actually arriving in the port, marked as "CP". From "CP", it is possible to reach 3 different Locks. Behind each Lock, there is a number of Docks. After at least 24 hours 6 hours (simulated time, not the time it takes to run the simulation), a docked vessel is allowed to depart and make the journey back out to sea (marked with "S"). See also the Dock description for more info.

Note how this port description greatly simplifies the port's geography, as well as ignores the need for pilots, boatswains, tugboats, traffic control, ...

We wish to study the performance of the traffic in this port. Therefore, the following performance metrics/statistics must be observed (or computed, through simulation).

1. Average travel time for a vessel (from entering the port until leaving it again).
2. Average waiting time for a vessel in the Anchorpoint.
3. Average number of vessels in the port.
4. Total number of vessels in the port at every hour in the simulation (create a plot for this statistic).
5. Average idle time for each Lock (i.e., the time that there are no vessels inside).
6. How often a Lock changed state without it actually containing ships.
7. Remaining capacity (surface area) for each Lock at every hour in the simulation (create a plot for this statistic).

The following is a detailed description of the important components for this system, as well as the corresponding messages that are sent. Feel free to create additional components/events to simplify your models and/or to break up the system logic. Make sure not to hard-code any numbers. This will help your analysis later on. You are allowed to group multiple components together in Coupled DEVS models. Try to optimize your model such that there is a minimum of duplication.

Note that in this assignment, resources such as Waterways, Canals, Locks, etc. will be modeled as "active" entities (i.e., Atomic DEVS). The Vessels however will be modeled as DEVS events. The opposite may seem more natural and is the way this problem would be modeled using an "individual" or "agent"-based formalism. As the number of vessels can be large and as inter-vessel interaction is mostly, if not entirely, through competition for shared resources, the "active resource" style of modelling and the use of DEVS as modelling formalism is more appropriate here (mostly thanks to much higher simulation efficiency).

Vessel (message/event):

Identifies a vessel/ship travelling through the system. For the sake of simplicity, we will assume there are only four possible vessels that can travel through the port:

Image:
Vessel Type:	Crude Oil Tanker	Bulk Carrier	Tug Boat	Small Cargo Freighter
Surface Area:	11,007 m2	5,399 m2	348 m2	1,265 m2
Avg Velocity:	10.7 knots	12 knots	7.8 knots	6.4 knots
Max Velocity:	15.4 knots	15.6 knots	10.6 knots	9.8 knots
Probability:	28%	22%	33%	17%

For each of these vessels, you are also given a few immutable properties that should be stored in the Vessels. On top of that, you may need to store additional state variables that help you in the simulation (e.g., unique identifiers, vessel destination, ...) and when gathering statistics. The probability property identifies the probability for a ship of this type to arrive at the port and should not be kept for simulation purposes.
Each ship should also have a name. In this file, you are given a list of randomly generated ship names that you can use to assign names to your Vessels.
Note: 1 knot (1 nautical mile per hour) is 1.852 km/h.

PortEntryRequest (message/event):

Indicates a message sent from the Anchorpoint to the ControlTower, informing the latter that a ship with a certain identification number would like to enter the port.

PortEntryPermission (message/event):

Dual of the PortEntryRequest. This is a message sent from the ControlTower to the Anchorpoint, informing the latter that a ship with a certain identification number is allowed to enter the port and can dock at a specified quay.

PortDepartureRequest (message/event):

Sent by a Dock to the ControlTower, identifying that a certain Vessel has left a specific Dock, making room for another ship to arrive.

Generator (Atomic DEVS):

Generates Vessels that arrive at the port, taking the probabilities from the Vessel description into account. We know, on an hourly basis, that the average number of Vessels arriving at the port follows the plot below. For the sake of simplicity, no interpolation needs to be done between two sequential hours. Each hour, the inter-arrival times of the Vessels are sampled from an exponential distribution, where the scale for each hour can be found in the plot below. This implies: the waiting time until the next arrival of a Vessel is sampled from Exp(λ), with 1/λ the current average for that hour.
For instance, between 10 a.m. and 11 a.m., the inter-arrival time is sampled from Exp(1/250).
Note: "scale" is not the same as the "rate"!
Note: Do not forget to rescale the averages below to match your time-unit!
For your convenience, the list of values is: [100, 120, 150, 175, 125, 50, 42, 68, 200, 220, 250, 245, 253, 236, 227, 246, 203, 43, 51, 33, 143, 187, 164, 123].

Anchorpoint (Atomic DEVS):

Location at which an unlimited number of Vessels can remain until access is granted to the port. This point is marked with a "K" (from loodskotter) in the diagram.
The Anchorpoint has an input on which the Vessels, generated by the Generator arrive. When a Vessel arrives, the Anchorpoint sends a PortEntryRequest to the ControlTower. As soon as the Anchorpoint receives a PortEntryPermission on another input, the ship that is described in that message gets its destination set and will be output towards the port. There are no additional delays in this system.

Sea (Atomic DEVS):

When exiting the port, Vessels do not return to the Anchorpoint, but instead immediately go out to Sea. This component acts like a collector of all departing Vessels. In the diagram, you can find this point marked with "S".

Waterway (Atomic or Coupled DEVS):

Identifies a section of the river over which Vessels sail in both directions. There is no maximal speed limit on this segment and vessels are allowed to pass each other. Waterways have a distance (see the map above), which, when combined with a Vessel's velocity, allows identification of the time spent on this Waterway. For simplicity reasons, there is no capacity on a Waterway.

Canal (Atomic or Coupled DEVS):

Special kind of Waterway. Identifies a section of the port over which Vessels sail in both directions. Vessels are limited to their average velocity and they are not allowed to pass each other. This implies: if there is a Vessel A at velocity v in front of another Vessel B, with desired velocity w, B's velocity becomes min(w, v). Just like Waterways, Canals also have a distance, which can be used to obtain the time spent on this Canal. For simplicity reasons, there is also no capacity on a Canal.

Confluence (Atomic DEVS):

A split/merge of multiple two-way Waterways and/or Canals. A parameter allows you to define how many Waterways and/or Canals converge at this Confluence. Sailing through a Confluence happens instantaneously. Arriving Vessels are handled in a FIFO (first-in-first-out) way. The Confluence uses the Vessel's destination to determine the desired output: when a Vessel arrives, it will be output on the Waterway or Canal that is closest to the destination Dock. When distances are approximately the same, the closest Lock is to be preferred on the trajectory. Furthermore, a Confluence can handle multiple Vessels at once.
Hint: You may give the Anchorpoint a unique quay_id (see Dock) as well to simplify this logic.

Lock (Atomic DEVS):

Separates the Canals and Docks from the river. Each Lock can be in state LOW or HIGH. The level of the river can be seen as the HIGH water level and the water level of the Docks corresponds to the LOW value. The changing of this state is known as "washing" ("versassen" in Dutch).
Additionally, the gates of the Lock can be OPEN or CLOSED (on either side).
There are three Locks in the system, with the following properties:

Identifier:	Lock A (Zandvliet/Berendrecht)	Lock B (Kieldrecht)	Lock C (Boudewijn/Van Cauwelaert)
Washing Duration:	20 minutes	12 minutes	8 minutes
Lock Shift Interval:	Every hour	Every 45 minutes	Every 30 minutes
Gate Opening/Closing Duration:	7 minutes	5 minutes	5 minutes
Surface Area:	62,500 m2	34,000 m2	25,650 m2

The figure below explains some of the timing information:


A Vessel is allowed to enter the Lock if the water level corresponds to the level at the Vessel's current position and if the gates are opened on that side. Additionally, there should be enough surface area left in the Lock to house the Vessel. Ignore the fact that ships have a fixed beam (width) and length and that fenders (used to prevent ships from crashing into each other) also take up space. It is allowed for Vessels to skit the line if they can fit in the Lock, but none of the Vessels waiting in front can fit.
Vessels that cannot enter the Lock will wait in a FIFO queue. When washing has completed and the gates have opened, all Vessels inside the Lock must exit first. The time in-between departure of each of the Vessels is 30 seconds. Next, all Vessels in the queue are granted access to the Lock. For the sake of simplicity, this happens instantaneously. Finally, if there is no queue, but a Vessel wants to enter on the side of the open gates, it can immediately sail into the Lock.
Hint: You can use a state machine to model this behaviour.

Dock (Atomic DEVS):

Identifies a quay or wharf with multiple mooring possibilities. Each Dock is able to hold 50 Vessels and is identified by a unique quay number (see map), such that Vessels know which way to go in Confluences.
When a Vessel arrives, the Dock samples from a normal distribution with average 36 hours and standard deviation 12 hours. This sample identifies how long a Vessel needs to stay at a Dock. A Vessel remains at least 6 hours at the port Dock. After this sampled time period has ended, the Dock sends a PortDepartureRequest to the ControlTower, releasing its position at the Dock before sailing to the Sea.

Control Tower (Atomic DEVS):

Communication point for accessing the port. It can communicate with the Anchorpoint to identify which ships are allowed to enter and to which quay/Dock they must sail. It therefore keeps track of all the available Docks and their capacities. For the sake of simplicity, a Dock is reserved by a Vessel, as soon as the ControlTower sends the PortEntryPermission message.

You will need to perform the following tasks step by step. Store (and submit) a copy of your model after each finished (sub-)task. Provide an answer to all the questions asked.

1. Create all individual components for the port system, as described above. Try to use the patterns that were discussed in the theory lectures to solve this task. Minimize magic numbers and maximize the usage of OO-programming.
   • Hint: Incrementally build all your components and test their behaviour. Do not try to create a system that fully encompasses everything from scratch. This will minimize the amount of time required to complete this assignment.
2. Make a (nested boxes with ports, and lines connecting ports) drawing (or a collection of such drawings) of your model. Use an appropriate diagramming tool such as draw.io. If you like, you may generate the Python code for your Coupled DEVS model from your visual representation, but this is optional.
3. Create a Coupled DEVS model of the port network and the various interactions.
4. Write your simulation experiment code as well as processing and presenting statistics in a separate experiments.py file.
5. Generate 100 Vessels that you assign to certain Docks as initial condition of your system. Ensure there is some variation in departure time of these Vessels.
6. Simulate your port for 1 week (i.e., 168 hours). Compare two different seeds and discuss the statistics.
7. Use the same seeds, but alter any of the given constant values to find a better performing port system.
8. Remove the randomness from your model by changing the distribution parameters. Use this new, deterministic model to argue the correctness of your model. Make sure to discuss all the components of the system. This may be a by simulation trace analysis or by logical reasoning.
9. Write a report that explains your solution for this assigment. Include all figures and plots; and discuss them. Also clearly indicate which models can be found in which files. Make sure to mention all your hypotheses, assumptions and conclusions. See also the "submission information" at the top of this page.

Notice the inconsitencies used in units (15 minutes, 1 hour, 1 week, 15.6 knots, ...). It is up to you to do a conversion to a corresponding set of units and to document your choice of "base units" explicitly.

It can be useful to create constructs that allow you to look up any quay-confluence combination. Additionally, you should use a predefined seed for random number generation. This allows a consistent result when testing and debugging your model. Note that random number generators also do change state and should therefore only be used where state changes are allowed!

While all components of the model are defined above, you are free to choose how these are implemented. As long as the behaviour is equivalent to how it is described here. Sometimes, there are multiple solutions to the same problem, but there are also ambiguities to allow you to make choices in the implementation. Don't choose for the most impressive solution, but rather the easiest and fastest to implement. Don't forget to discuss where and why you made certain choices!

Where possible, use different experiment files to setup your tasks. This allows you to return to previous tasks without issues, as well as referring to specific modules in your report. Also ensure your model is flexible enough to allow all the tasks by simply changing model parameters. If a task requires a (slight) change in the components used, make sure to include all versions of the components.

You must use Classic (not Parallel) DEVS. To simulate using Classic DEVS:

                    sim = Simulator(model)
                    sim.setClassicDEVS()
                    sim.simulate()
                    

Take pride in your work. Make sure your report and all models and images are clearly readable. If a figure is difficult to read, also include the corresponding source files (*.gv, *.py...). You will not lose points for doing too much, but you will lose points if you do too little.

• This assignment is to be created with PythonPDEVS. Installing this on your system/virual environment can be done by executing python setup.py install --user from the source directory. Alternatively, placing the source directory on the PYTHONPATH environment variable, or marking it as a "sources root" in an IDE will work as well. Note PythonPDEVS works on both Python 2.7 as well as Python >=3.6.
• The statistics can be printed after the simulate() call and printed to the console, to be plotted at the end (e.g., using gnuplot/matplotlib/bokeh). You are strongly advised to first study the "Application to Queueing Systems" example.
• Do not use real-time simulation.
• The theory slides describe a set of design patterns to use. Your model will be better if you do. This will be reflected in your grade.
• Useful links:
  • PythonPDEVS documentation: https://msdl.uantwerpen.be/documentation/PythonPDEVS/.
  • PythonPDEVS starting examples:
    • Example Store from the Practical Session
    • Classic Example
    • Application to Queueing Systems