Home   :   Matrix Language   :   Model Examples   :   Petrol Station

Petrol Station Model




The Petrol Station model documents an experiment to convert an existing MASL model to the Matrix language .


MASL is a relatively new textual modelling language, having made its first public appearance in 2016 . The language employs vocabulary from Shlaer-Mellor rather than the more established Executable UML terminology. For example, it uses the term "objects" to describe modern classes (entities) and the term "instances" to describe objects.


The language clearly builds on older action languages originating from the 1980's such as ASL and OAL. MASL is similar to Matrix in that it is not limited to the state action level but is capable of describing an entire model including projects, domains, objects and state transitions. The language has a C like syntax but also has a strong Ada influence.


Unlike Matrix, MASL allows a great deal of flexibility where the various model components can be defined. This would imply that modellers will be required to adhere to a style guide to ensure consistency of format between models.


MASL retains the programming approach to action description found in ASL and OAL. Unlike Matrix where navigation is a central feature and always operates on "live" objects, MASL "pulls out" collections of objects (or instances) which are later cycled through and processed.


Also, MASL navigation is used to jump from one entity to another in order to obtain, say an object's attribute's value. Whereas in Matrix, the main context changes to that entity.


Note: All Petrol Station MASL model code is UK Crown Copyright.



UML Diagram Notation Conversion


Unfortunately, the existing de facto UML notation is sub-optimal for Matrix analysis. Instead, the notation used in the Shlaer-Mellor method has been enhanced for use with the Matrix language. For completeness, the names of the Shlaer-Mellor diagrams have also been included in the table below:



Matrix Notation Executable UML Notation Shlaer-Mellor Notation
Domain Bridge Diagram (DBD) Package Diagram Domain Chart
Entity Relationship Diagram (ERD) Class Diagram Information Model
State Transition Diagram (STD) Statechart State Transition Diagram
Process Flow Diagram (PFD) Activity Diagram Action Data Flow Diagram





The model describes the operation of a normal petrol station (filling station) that can be found on most main roads and contains the expected entities.


Pumps make deliveries to customers which should not be confused with petrol tankers making deliveries to a station's storage tanks. At the end of a delivery, a transaction is created that enables the customer to pay for the petrol.



Model Walkthrough


A model walkthrough can be found in the PSC.mod file in the original MASL repository .


The Domain Bridge Diagram (DBD) below shows the top level application Petrol Station Control domain and sets the system boundary for the model.


Realm:Analysis_Of_Application (Domain)


In an actual project the application domain would be shown with all the other domains in the application as shown in the diagram below. Bridges to other domains are effectively "channels" that a domain sends events to and receives event from.


Realm:Analysis_Of_Application (Bridges)


It is often useful to name the major entities comprising a domain and to have them visible on the DBD. These are the usually the most central active entities and are displayed on each domain as shown below.


Realm:Analysis_Of_Application (Annotated)


The Entity Relationship Diagram (ERD) below shows the relationships between the various entities in the Petrol Station Control domain.


The entities have been taken directly from the MASL model except for the Transaction Policy entity which has been added to hold the next transaction number to be used. As required by Matrix, the ERD only shows relationships that are actually necessary for the model to operate.


The notation used by the diagrams below is based on Shlaer-Mellor Method notation (similar to UML) . To see the full size ERD, click on the diagram. Click again to see an annotated version.




The diagram below shows all the STDs from the Petrol Station Control domain without showing how they interact. Click on the picture to get an expanded view of the diagram.


Domain State Transition Diagrams (Separate)


Click on the picture below to get an expanded view of the diagram showing the source of actual events and their destination among the collaborating entity STDs. An event based notation is used .


Domain State Transition Diagrams (Annotated)


The Original MASL Model


During conversion to Matrix several observations were noted:



  • Some state names are in sentence case others are in capped case.
  • State at the end of a state name is unnecessary.
  • Creating junk instances in for loops is generally not very useful because of how the method works (true for Matrix) with the exception for performance load testing.
  • Tank and Pump numbers are set differently.
  • Tank level flag and tank level may be incompatible when defined.
  • One .tr has the keyword Begin repeated. This is a syntax error.
  • Inconsistent spelling of Attendant.
  • The Attendant Transaction_Pending service is defined but not used.
  • In the "supplied" scenario the Transaction:Customer_absconds and Transaction:Payment_received event generation have been swapped to fix wrong state error.


Delivery Entity

  • The event Delete_Delivery is redundant. Although Matrix needs it!
  • In the Creating_Delivery state, the event Delivery_Complete goes to the Delivery_Cancelled state and not to the Delivery_Complete state.
  • The magic number petrol unit price (0.1) has been placed with the Fuel_Grade entity in the Matrix model.
  • In simple assignments such as x:=x+1 a redundant intermediate variable is made used of (a:=x+1, x:=a).


Pump Entity

  • In the Fuel_Delivery_Complete state, the Fuel_Level_Ok event has "=> Ignore,Pumping". This is a syntax error. Assumed this to be "ignore" because to move from Fuel_Delivery_Complete to Pumping makes no sense. Unfortunately, this makes the Fuel_Level_Ok event redundant.
  • Pump:Pumping_fuel_from:Tank is a MANY and miss named.


Tank Entity

  • In state Checking_Levels_After_Tanker_Delivery, the begin and end around this.Check_Level(below_threshold); seem to be redundant.
  • Magic number Full_Percent: 100. This is unnecessary.
  • Tank_empty_flag may be redundant.
  • The attribute: Transaction_Process_Time does appear to be used anywhere.


Fuel Grade Entity

  • A fuel grade should be able to be stored in more than one tank so Fuel_Grade to Tank is UNCONDITIONAL MANY not UNCONDITIONAL ONE.
  • No relationships to Tank junk instances are established at initialisation.

Redundant Relationships









: Delivered_fuel_for

: Delivered_fuel_for

: Stored_in

: Records_fuel_delivery_for

: Specialisation

: Specialisation

: Specialisation


: Pending_Transaction

: Transaction

: Tank

: Pump

: Transaction

: Transaction

: Transaction


Matrix Model


The Matrix (Professional Edition) of the Petrol Station model is available . The model is contained in a standard main file, System.matix, plus four other files which describe the main active entities, and lastly a file describing the models configuration at initialisation.



Expected Output


The output log from the Matrix version of the Petrol Station model executing a short scenario is available  and another log is also available of the same scenario with an increased level of tracing .


No output logs from the original MASL model were found in the GitHub repository.

Copyright 2017 Dark Matter Systems Ltd. All Rights Reserved.