Mochy User Guide

LogoMochy

Mochy : Models for Concurrent Hybrid Systems

1. Presentation

The goal of the Mochy software is to simulate and analyze models composed of three parts : a physical model, an a priori schedule for a subset of events occurring during executions of the physical model, and a regulation scheme that updates the schedule and elements of the model in real time to adhere to the original schedule, or optimize performance indicators.

MOCHY was developped thanks to an ADT (Development project) of INRIA.

2. Functionnalities of MOCHY

Mochy provides several functionalities:

  • step by step simulation of a cyber-physical model

  • Random simulation of arbitrary length

  • Simulation campaigns and statisitical analysis

The physical model and the schedule can be simulated separately or jointly, considering that events listed in the schedule are prescription of dates for events appearing during executions of the physical Model.

MOCHY distribution is provided with one implementaiton of a physical model, schedule and regulation tailored for analysis of urban transport networks. The physical model (tracks + trains) is a variant of timed Petri Net, the schedule is a metro Timetable, and the regulation scheme implements a so-called hold-on policy, which propagates delays to reschedule events at their earliest possible realization date.

3. Inputs

MOCHY takes as inputs project descriptions that contain references to a physical model, to a schedule, and to a correspondance between scheduled and physical events.

4. Mochy API

Version 1.0.0 of MOCHY provides a specialization of the simulator for a simple model taylored for simulation and statisitcal analysis of metro networks. In the next coming versions, MOCHY will come with an API allowing you to use all its functionnalities with you own version of physical/schedule/regulation models.

The elements to provide to use the MOCHY simulator with your own models are:

  • Physical model : a model describing evolution of your cyber-physical systme. In particular, this implementation of your physical model needs to provide the following methods:

    • Discrete moves: a method listing the possible discrete events that can occur at a given instant

    • discrete state change : method(s) to describe what happens when a discrete event of your physical model occurs.

    • allowed time elapsing: a method describing the amount of time that can elapse without occurrence of a discrete move in your model

    • time elapsing: a method updating the state of your physical system when a given duration elapses.

  • Schedule : a model describing an a priori scheduled list of events and their planned occurrence dates. In particular, this implementation of your physical model needs to provide the following methods:

    • discrete events : a method listing evnets that can occur at a given instant

    • Realization of an event at a given date: update information in the current state of your schedule, and trigger corrective actions if needed.

    • time elapsing: a method updating the state of your physical system when a given duration elapses.

  • Regulation : the regulation part of MOCHY specializations describes how schedules are adapted upon occurrence of a discrete or timed move. Regulation can be seen as a specialized type of coontroller. This module is optional.

5. Quick Start

Download the latest vesion of MOHY here

Download running examples here

6. Specifying a Network

6.1. File

The Petri Net is loaded from the file menu. The default folder to load a net can be set on Edit/Preferences. The file can be created from the user interface in the menu Config/Config. It contains the places (headways for example), the transitions (the link between two places with a clock that is the delay between two headway), the inflows which are the link between a place and a transition, the outflows which are the link between a transition and a next place and the initial marking of the places (if a place is marked, it means that a train is at this headway for example).

* The places are defined by a line as :
place:number:label

* The transitions are defined by a line as :
transition:number:label:[clock_lowerbound,clock_upperbound]:Distribution
the Distribution field can be not fill for a uniform distribution, it can be filled by Gaussian to enable the gaussian distribution or by Weibull:coef to use the weibull distribution with the specified coefficient.

* The inflows are defined by a line as :
inflow:place_number:transition_number

* The outflows are defined by a line as :
outflow:transition_number:place_number

* The initial state is defined by a line which begin with initial: and then the numbers of the marked places separated by two dots. For example :
initial:1:2:6:8

At the end of the file, a random distribution can be set to sample random value of the clock. By default the uniform distribution is set to sample a value in the interval set for the transition. Gaussian can be written to sample a value following the gaussian distribution. Weibull:coef can be set to sample a value following the Weibull distribution with the coef set, 5 for example. More the coeff is high, more often the value sampled will be near the middle of the interval set for the transition.

Comments can be add as a line after a "%:" annotation.

6.2. Simulation

netsim

During the simulation a transition can have 3 types of distribution : enabled, firable or blocked. It is enabled if its previous place (pre) is marked, the clock is then set to a random value depending of the lowerbound and upperbound of the interval and the distribution set in the file. In the same configuration, the transition is firable if the time has advanced, the clock is set to 0 and the next place is not marked. So that when a transition is fired the previous place is not marked anymore and the next place is marked. Still in the same configuration a transition is blocked if the clock is set to 0 and the next place is marked.

* By clicking in the chart column for a specific transition, it is possible to see the distribution set to sample the values of the clock.
* By clicking on the one step button it will advance the time if there is no firable transitions. The time is the smaller time necessary for a transition to switch from enable to firable. If there is a firable transition it will be fired. If there is multiple firable transitions, the first one will be fired. A double click on a transition which the user prefers to fire can fire it.
* Multiple steps can be set on the right of Enter the number of steps and it can be run by clicking on launch.
* By clicking on the Discrete step it will fire the first of the firable transitions if there is at least one.
* By clicking on the Timed Move button it will advance the time indicated at its right. If the value is higher than the smaller time necessary for a transition to switch from enable to firable, the smaller time will be chosen.

6.3. TrajectoryNet

trajectories

A new model has been implemented with trajectories net. Multiple tokens can be set in one place as soon as a minimum headway is preserved between two tokens.
To load a Trajectory Net file, TrajectoryNet must be checked in Edit/Preferences.
Places are now represented by a diagram with the distance in the ordinate and the time in abscissa. The content of a place can be shown by clicking on the button in chart column of the places.
A token is fireable as the distance is to 0 for the time 0.
A place is defined by its headway and its distance.
The time of a token is defined by the lowerbound and upperbound of the next transition.
Then there is an adaptation of the trajectory of the token depending of the minimal headway of the place.
A place is defined in the file as : place:nb:name:distance:headway where nb, distance and headway are integer numbers.
A trajectory can be add as well linked to a place with specific points as : trajectory:placeNb:x0,y0,x1,y1:x1,y1,x2,y2:…​
At the first line of the file, TrajectoryNet can be written to load automatically the file with the good model.

6.4. Equalization Net

It is also a new model implemented which the goal is to equalize the time between the tokens.
It is more described in Development Notes/circleRegulation.pdf

7. Specifying a Timetable

7.1. File

The TimeTable is loaded from the file menu. The default folder to load a timetable can be set on Edit/Preferences. The file can be created from the user interface in the menu Config/Config.
It contains the events and the dependencies which make the link between two events and specify the minimum time that a second event must be realized after a first one has been realized.

* An event is defined by a line as :
event:number:tag={tags}:duration:label
The tags are separated by a comma.

* A dependency is defined by a line as :
dependency:start_event_number:end_event_number:duration

* Comments can be add as a line after a "%:" annotation.

7.2. Simulation

ttsim

During the simulation of the timetable, an event can have 5 types :
- blue if the event has been realized
- green if the event can be realized at the correct time
- red if the event can be realized but is late
- pink if the event is late but it can’t be realized because of the dependencies which are not satisfied
- none background if the event is not late, has not been and can’t be realized at the current time

  • in. date is the initial date of the event as set in the file

  • date is the date when the event can be realized or when it has been realized

  • label is the name of the event

  • transnames is the transitions of the net on which a link can be made

  • realized is true if the event has been realized, else it is false

  • tags are used for the statistics which can be done from the stats menu. Some statistics can be done on specific tags to get the average delay or the sum of the delays.

The simulation is done of alternative timed moves and the use of one step of timetable to realize events. Events can also be realized with a double click.
Of course to realize an event the current date of the timetable must be superior or equal to the date of the event and the dependencies must be satisfied. It means that the duration between two events as specified in the dependencies is satisfied.
A delay can be add to an event by specifying the event number the time to be add. Then Delay can be clicked.

The Connect/Disconnect the timetable checkbox is used for the stats which can be done on the timetable only or in the net linked to the timetable.

The save new state of the timetable button allows to set the recorded dates of the events as initial dates of a new timetable file.

8. Joint Simulation

The Joint Simulation is the simulation of the timetable linked to the net. A correspondancies file is need to fill the transnames column of the timetable with the transitions numbers.
The correspondancies file is load from the file menu/load correspondance.
It must be loaded after that the net and the timetable are loaded.

It is made of lines like :
transition t implements event e
where t is the number of the transition
and e is the number of the event

Comments can be add as a line after a "%:" annotation.
The joint simulation is done with Global move to advance the time and to realize an event and fire a transition linked to this event.
Multiple steps is used to perform multiple Global move.
The save state button allows to save the state of the simulation at a specific time in a .state file. The load state button allows to load a .state file to get a state of a simulation at a specific time. == Statistics

The first step for the statistics is to choose or not to connect / disconnect the timetable from the network with the checkbox under the timetable.

We will first explain how to made statistics with the timetable only, which means that the checkbox is unchecked.
The menu stats/stats allow to specify which data we want to take into account in the statistics.
We can escape some delays, have more details with some tags, restrain the stats for a specific duration (if none is indicated, all the events will be taken into account), and precise the calculations to be done : sum of the delays and/or the average of the delays.
We can also calculate the time between two places, the checkbox near to the places must be checked to display the results in the log pane.
Then to have results, Multiple Runs must be start from the Stats menu. As indicated, the results will be shown in the Logs pane at the bottom of the window.
The checkbox connect/disconnect the timetable allows, when it is checked, to perform a joint simulation with the timetable and the net.
If it is not checked, only the timetable will be simulate.

9. Scenario

This tool is loaded from the menu Stats/Scenario.
It allows to add a delay at specific transitions and specific time.
The add delay text field must be filled under the form : placeName:[startTime,endTime]:delay
Multiple delays can be filled separated by ";".
The placeName field can be replaced by "all" to add a delay to all the transitions.

Then save can be clicked to add the delay for specific transitions and time.

Scenario can also be added at the end of a project file.
For example scenario:t2:[0,100]:10 at the end means we add a delay of 10 on transition t2 during the time interval [0,100]. == Display the models with Graphviz

To use the graphviz tool it first must be installed and the Graphviz/bin path must be added to the path environment variable. Once a net is loaded it can be display as a scheme from the Display/Net menu.
Once a timetable is loaded it can be display as a scheme also from the Display/TimeTable menu.
Once a net, a timetable and a correspondancies files are loaded, the full scheme can be display from the Display/Net+TimeTable menu.

10. Create/Edit nets or timetables files

A tool to create/edit nets or timetables files is available in the Config/create or edit net/tt menu. To edit files they can be loaded from the file menu. Then the + button allow to add lines for a specific table and the - menu delete the selected line. In the end the tables can be saved through the save button. The transitions and places tables are saved in a common file. The events and dependencies tables are saved in another common file.

For the transitions table, the distribution of the sampling of the clock can be chosen by setting the Gaussian column checked or the Weibull column checked with the coefficient of the Weibull distribution.
If Gaussian or Weibull:coeficient is written at the end of the file, all the transitions will be Gaussian or Weibull respectively.

11. Generate timetables and correspondancies files from a net

This tool is available from Config/generate tt/core from net. It allows to generate the timetable and correspondancies file for a line. Once the net file is loaded from the file menu and the parameters are filled, the generate button creates a tt and a cor file with the name specified in output. They are saved in the net folder as specified in the edit/preferences pane of the start window.

12. Get specific logs

The logs must be set in the edit/preferences pane. Some specific logs can be retrieved from an in.txt file in the logs folder to a out.txt file in the same folder. The in.txt file describe the values which must be retrieved. Each value is described as v1=package.class.getMethod;v2=…​;v3=…​ Arguments like an Integer or a String can be added as v1=package.class.getMethod=type.argValue. The out.txt contains a line for each step. Each line begins with the time elapsed and the values follow separated by a ";" .