Project README + additional doc

README.md

@@ -1,3 +1,145 @@
 # `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](#quick-start)
+2. [What to Expect](#what-to-expect)
+3. [DEVS in a Nutshell](#devs-in-a-nutshell)
+4. [Deepening the repository](#deepening-the-repository)
+
+
+## Quick Start
+
+1. Clone the repository:
+````text
+git clone https://github.com/iscar-ucm/xdevs.py.git
+````
+2. Navigate to the project directory
+```text
+cd xdevs
+```
+3. Install the package
+```text
+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: 
+```text
+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](https://iscar-ucm.github.io/xdevs/).
+
+
+## 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](xdevs/images/sysoverview_small.png
+)
+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.
+
+

xdevs/examples/gpt/README.md

@@ -6,6 +6,7 @@ This folder stores several examples in order to illustrate some of the possibili
 ## `xDEVS.py` Virtual Simulation
 
 A virtual simulation is carried out only taking into account the virtual environment. 
+In the context of this repository, a DEVS virtual simulation will be achieved by a Coordinator. Two possible options are provided based on two methods: `simulate` and `simulate_time`. The first one is based on the number of iterations and the second one on the desired virtual time to simulate. 
 
 ### Example:
 
@@ -27,7 +28,7 @@ This section aims to show a collection of examples based on the methodology foll
 $ cd xdevs/examples/gpt
 $ python3 gpt_rt_sim.py
 ```
-2. #### Input handler real-time simulation
+2. #### (TCP) Input handler real-time simulation
 
 ```bash
 $ cd xdevs/examples/gpt
@@ -49,7 +50,7 @@ c.connect((HOST,PORT))
 c.sendall('ih_in,TCP'.encode()) # The data is 'port_name,msg'
 ```
 
-3. #### Output handler real-time simulation
+3. #### (TCP) Output handler real-time simulation
 
 ```bash
 $ cd xdevs/examples/gpt
@@ -83,7 +84,7 @@ while True:
         break
 ````
 
-4. #### Input and Output handlers real-time simulation
+4. #### (TCP) Input and Output handlers real-time simulation
 
 ````bash
 $ cd xdevs/examples/gpt

xdevs/examples/store/README.md

@@ -43,4 +43,21 @@ The client can send messages to the server in the following format:
 <input_port>,<client_id>?<t_entered>
 ```
 
-The model only has one input port, called `IP_NewClient`.
+The model only has one input port, called `IP_NewClient`.
+
+## MQTT Example
+
+An MQTT example is provided, in which the connection between two `DEVS` models is created.
+The execution of both models should be carried out in parallel.
+
+_First model_
+```bash
+$ cd xdevs/examples/store
+$ python3 4_1_rt_simulation_mqtt_input_handler.py
+```
+
+_Second model_
+```bash
+$ cd xdevs/examples/store
+$ python3 4_2_rt_simulation_mqtt_output_handler.py
+```

xdevs/rt.py

@@ -130,6 +130,12 @@ def propagate_output(self, port: Port):
 
 
 class RealTimeCoordinator(Coordinator):
+    """
+    The RealTimeCoordinator is the adaptation of the already existing class Coordinator to the real-time simulations.
+
+    :param Coupled model: A DEVS model to simulate in real-time.
+    :param RealTimeManager manager: A RealTimeManager to handle the external events.
+    """
     def __init__(self, model: Coupled, manager: RealTimeManager):
         super().__init__(model)
         self.manager: RealTimeManager = manager
@@ -147,10 +153,10 @@ def simulate_rt(self, time_interv: float = float("inf")):
         while self.clock.time < time_interv:
             if self.time_next == float("inf") and not self.manager.input_handlers:
                 break
-            # SLEEP UNTIL NEXT STATE TRANSITION
-            t, msgs = self.manager.wait_until(min(time_interv, self.time_next))
+            # WAIT UNTIL NEXT STATE TRANSITION
+            t, events = self.manager.wait_until(min(time_interv, self.time_next))
             # INJECT EXTERNAL EVENTS (if any)
-            for port_id, msg in msgs:
+            for port_id, msg in events:
                 port = self.model.get_in_port(port_id)
                 if port is not None:
                     try: