From 7be80fde1b4a82bb57421c203731128952b4efa6 Mon Sep 17 00:00:00 2001
From: OscarFdezS <oscar.fernandez.sebastian@alumnos.upm.es>
Date: Thu, 27 Jun 2024 18:01:50 +0200
Subject: [PATCH] README for abc and json

---
 xdevs/abc/README.md           | 24 +++++++++
 xdevs/examples/json/README.md | 91 +++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+)
 create mode 100644 xdevs/abc/README.md
 create mode 100644 xdevs/examples/json/README.md

diff --git a/xdevs/abc/README.md b/xdevs/abc/README.md
new file mode 100644
index 0000000..42cd9cc
--- /dev/null
+++ b/xdevs/abc/README.md
@@ -0,0 +1,24 @@
+# What is a Factory
+
+A factory is a software methodology for designing and implementing objects that have a common behavior but several possible implementations. This type of methodology is widely used in this repository for creating different components in the simulations such as transducers, handlers, models, etc.
+
+## Example 1 
+_(Focused on handlers, transducer and celldevs)_
+
+1. Firstly, a father abstract class is defined, which states the common behavior of the component under developing. (The class `InputHandler` may be found in `xdevs.abc.handler`)
+2. A child class that inherits the behavior of its father defines the particular implementation. (The folder `xdevs.plugins.input_handlers.` stores several implementations for this class)
+3. An entry point is defined. This name will play the role of a key that links the name to the desired implementation. (In the script `xdevs.pyproject`, the keys for Input Handlers are found after the `[project.entry-points."xdevs.input_handlers"]` statement)
+4. Creating an instance of each implementation is as easy as passing to a method of the factory class the desired key and the required parameters (if any) for that specific implementation (Using the class `InputHandlers` in `xdevs.factory` and calling the method `create_input_handler`).
+
+## Example 2 
+
+_(Focused on `JSON` to `DEVS` components)_
+
+In case of the `JSON` to `DEVS` model conversion, the factory methodology is used to create the components defined in the `JSON` file. The `Factory` class 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.
+
+1. The `DEVS` model must be defined (i.e. `EFP` in `xdevs.examples.gpt.models`).
+2. The entry point must be created in pyproject.toml after `[project.entry-points."xdevs.components"]`
+
+With this methodology, adding several instances of a component for a range of simulations is easier.
+Defining a key that links to the desired implementation allows for a more straightforward way to create the components
+and avoids having to create and define each component for each simulation.
\ No newline at end of file
diff --git a/xdevs/examples/json/README.md b/xdevs/examples/json/README.md
new file mode 100644
index 0000000..815b9ae
--- /dev/null
+++ b/xdevs/examples/json/README.md
@@ -0,0 +1,91 @@
+# JSON to `xDEVS` Simulations
+
+The `json` folder contains two examples of how to generate a `DEVS` model using a `JSON` file, these examples are the `efp.json` and `gpt.json`.
+
+Next, a concise guide on using the `from_json` method from `xdevs.factory` to parse a `JSON` file into a `DEVS` model is presented. 
+For detailed information, please refer to the method's documentation.
+
+## Overview
+
+The `from_json` method allows you to parse a `JSON` file into a `DEVS` model. The `JSON` file must follow specific rules to correctly define components and their couplings.
+
+**ATTENTION PLEASE**  ❗❗
+
+ Take into account that the `component_id` inside the `JSON` file must be identified as an `entry-point` of `Components`  in `xdevs.factory `. (See the `Factory` section in `xdevs.abc` for more information).
+
+
+## JSON Structure
+
+### Master Component
+
+The top-level JSON object represents the master component.
+
+```json
+{
+    "MasterComponentName": {
+        "components": {
+            // Nested components
+        },
+        "couplings": [
+            // List of couplings
+        ]
+    }
+}
+```
+
+### Components
+
+Components can be either already registered in the `entry-points` or couple:
+
+* Coupled: Contains `components` and `couplings` keys. 
+* Component: Identified by the `component_id` key. It must be already defined in the `entry-points`.
+
+
+```json
+"components": {
+    "CoupledModel1": {
+        "components": {
+            // Nested components
+        },
+        "couplings": [
+            // List of connection dictionaries
+        ]
+    },
+    "Component2": {
+        "component_id": "ID_from_factory",
+        "args": [/* positional arguments */],
+        "kwargs": {
+            "a_parameter": "value",
+            // Other keyword arguments
+        }
+    }
+    // Additional components
+}
+
+```
+
+### Couplings
+Couplings define connections between components:
+
+* IC (Internal Coupling): Both componentFrom and componentTo are specified.
+* EIC (External Input Coupling): componentFrom is missing. (A new input port is created)
+* EOC (External Output Coupling): componentTo is missing. (A new output port is created)
+
+```json
+"couplings": [
+    {
+        "componentFrom": "Model1",
+        "portFrom": "PortA", // Port name defined in Model1
+        "componentTo": "Model2",
+        "portTo": "PortB"
+    }
+    // Additional couplings
+]
+```  
+
+## Example
+
+```bash
+$ cd xdevs/examples/json
+$ python3 main.py
+```