StoryEvent

A StoryEvent represents an occurrence during the model run that we wish to log and save for later. StoryEvent is an abstract class that contains some of the main logic for displaying events and writing them to output files. It also includes data common to all subclasses, such as the event's time and its severity. Subclasses of StoryEvent represent specific types of events, and must implement two methods:

• getEventCsvHeaders: Return a String[] containing the names of the different variables that this type of event saves (i.e. the names of the column headers in the .csv file).
  • If it was possible to make a static abstract method, I would have done that. Unfortunately, this needs to be implemented as a regular abstract method, but should have identical behaviour for all objects.
• getEventCsvRowData: Return a String[] containing the values of the variables to save for this specific StoryEvent object (i.e. the values in a single row of the .csv file).

These methods are public, but you normally want to use getCsvHeaders and getCsvRowData which also include the "time" column and any other columns that are common to all StoryEvent types (none, currently).

StoryEvent subclasses

To find more information about a StoryEvent subclass, look at its corresponding class definition in the .alp file.

The following StoryEvent subclasses are used:

• ArriveAtHomeEvent: A Trucker returns to their home city at the end of a driving period. This type of event should never be triggered with the simulation configured such that trucks don't return home.
• DeniedParkingEvent: A Trucker attempts to stop at a StoppableLocation but is denied due to lack of available parking.
• HoursViolationEvent: A Trucker commits an hours violation.
• NoStopsFoundEvent: A Trucker wasn't able to find any truck stops at all. See the Truck Stop Selection Logic flowchart for more details.
• ParkingViolationEvent: A Trucker commits a parking violation.
• StartDrivingEvent: A Trucker starts driving in any circumstance.
• StartDrivingHomeEvent: A Trucker starts a trip home to end their driving period. This type of event should never be triggered with the simulation configured such that trucks don't return home.
• StartNewDayEvent: The clock hits midnight and a new day starts. All Trucker agents log their number of hours on duty in the last day.
• StartNewTripEvent: A Trucker starts a new trip either to a shipper, receiver, or home.
• StartSimulationEvent: The simulation starts. All Trucker agents log the time and their home city. This output file should only have a single row.
• StopDrivingEvent: A Trucker stops driving in any circumstance.

Storyteller

The Storyteller class exists to collect Event instances from a particular Trucker, keep track of them, and display them nicely when needed. Each Trucker is assigned a Storyteller at model initialization. This is essentially just a wrapper around a list of StoryEvents (see Possible Improvements).

Model Outputs

At the end of the model, each Trucker asks their Storyteller to write their events to disk. These will be saved in a directory called ModelRun-<id>, which contains a subdirectory for each trucker labelled 1 to N (N for # truckers). Inside each directory, the Storyteller will save a separate .csv file for each event type containing a row for each event. If no events of a given type occurred, no file is created. These model outputs can be analyzed after the model run, including by using the visualizer tool included in this repository.

Possible Improvements

The Storyteller agent was inspired by one of Wade McDonald's models where he was consulting about water issues with a First Nation in Saskatchewan. In that context, there was somewhat of a premium placed on having this logging behaviour represented as an agent. For the Trucker.alp use case, I'm not so sure that this is really necessary. The storyteller never interacts with the environment nor does it interact with any agents other than to receive story events. It should really be a regular class rather than an agent.