/xdevs.py

Version of the xDEVS simulator for Python projects

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

xdevs.py

Version of the xDEVS simulator for Python projects

The aim of this repository is to be able to simulate DEVS systems in both virtual and real-time environments using python. However, additional features are being developed.

Sections

  1. Quick Start
  2. What to Expect
  3. DEVS in a Nutshell
  4. Deepening the repository

Quick Start

  1. Clone the repository:
git clone https://github.com/iscar-ucm/xdevs.py.git
  1. Navigate to the project directory
cd xdevs
  1. Install the package
pip install .

Now you're ready to start using xDEVS.py for your DEVS simulations!

In case additional dependencies (sql, elasticsearch or mqtt) are required, they can be installed. To add MQTT support with paho-mqtt:

pip install .[mqtt]

What to Expect

This section summarizes what you may find in the repository folder structure.

  • Folder abc:

    • The abstract classes folder contains the handler and transducer files. These folders contain the classes that define the general behavior and structure that each I/O handler or Transducer must follow.

  • Folder celldevs:

    • Contains the implementation of CellDEVS.

  • Folder examples

    • Inside this folder, you will find a collection of examples to try and execute in both virtual and wall-clock simulations. Each sub-folder represents an independent case study:
      • CellDevs
      • Devstone
      • Gpt
      • Json
      • Store

  • Folder plugins

    • This folder encapsulates a collection of folders. Each subfolder stores the implementations of each of the abstract classes. For example, in the input_handlers subfolder, you will find several implementations for the Input Handler.

  • Folder tests

    • This folder is dedicated to storing the tests for GitHub Actions.

  • Factory.py

    • This script is in charge of creating the different types of implementations of an abstract class based on a key that is linked to the desired implementation.

  • Models.py

    • It has the basic DEVS models such as Atomic, Coupled Component, or Port.

  • Rt.py

    • It has the adaptation of the sim.py components to the real-time simulation methodology developed.

  • Sim.py

    • It has the DEVS components to carry out a simulation based on the abstract simulator mechanism.

DEVS in a Nutshell

Discrete Event System Specification (DEVS) is a mathematical formalism with modular and hierarchical characteristics. DEVS is based on discrete event simulation where events occur chronologically in discrete instants of time and result in a change of the system.

DEVS is mainly based on atomic and coupled models.

Atomic Model

An atomic model is the smallest representation of a system. It may remain in a state (S) for a certain time (ta); once the time has passed, it executes the internal transition function (deltint). This function will define what to do next for each state. However, if during that time something external occurs, the model reacts with its external transition function (deltext) that describes what to do in this case. If the external event occurs at the same time the ta has elapsed, the confluent transition function (deltcon) defines what to do next. Finally, the output function (lambdaf) defines for each state what should be done when transitioning between states. It is only executed after the internal transition function.

Coupled Model

A coupled model defines the connections among atomic models and other coupled models.

Simulation Mechanism

To simulate a system composed of atomic and coupled models, the abstract simulator mechanism is used. This methodology defines the simulators and coordinators. A simulator is attached to an atomic model, while the coordinator is attached to a coupled model. The coordinator will be in charge of carrying out the simulation.

Refer to the xDEVS user’s manual for further and deeper understanding here.

xDEVS.py Wall-clock Simulation

A real-time simulation intends to match the virtual time into a wall-clock time. The methodology followed in this repository to achieve the real-time behaviour is based on the arrival of external events. The system will remain waiting for external events between states, when an external event occurs the system will react according to its particular behaviour.

In this repository, a RealTimeManager and a RealTimeCoordinator must be combined to achieve a wall-clock simulation. In addition, if the system requires the handling of input and output events, the input_handler and output_handler will be used.

System overview

The next picture shows the system overview and how the different components interact with each other

System Overview

  1. The input_handler acts are the interface for any incoming event to the system sending it to the RealTimeManager.
  2. The RealTimeCoordinator send the events collected from the RealTimeManager to the DEVS model.
  3. The DEVS model may eject events out of the system, so they are routed to the RealTimeManager.
  4. Finally, those outgoing events are forwarded to the output_handler which act as an interface to send the events.

In order to execute real-time simulations examples go to xdevs.examples.gpt.README

Deepening the repository

In order to deepen the repository and understand the different functionalities, the following sections should be checked:

  • What is a Factory? go to xdevs.abc.README

  • xDEVS.py simulations? go to xdevs.examples.gpt.README

  • JSON to xDEVS.py simulation? go to xdevs.examples.json.README

  • TCP examples? go to xdevs.examples.gps.README or xdevs.examples.store.README

  • MQTT examples? go to xdevs.examples.store.README

Feel free to contribute to the project by opening issues or submitting pull requests.