Improvements and hot fixes for version 3.0.0-alpha2

configuration/build_runshfile.py

@@ -0,0 +1,67 @@
+import yaml
+import os
+import sys
+
+# Constants
+DEFAULT_PORT = 5123
+RUN_PATH = './Desktop/illuminatorclient/configuration/runshfile/'
+RUN_MODEL = '/home/illuminator/Desktop/Final_illuminator'
+RUN_FILE = 'run.sh'
+
+def load_yaml(file_path):
+    """Loads a YAML file and returns its content."""
+    try:
+        with open(file_path, 'r') as file:
+            return yaml.safe_load(file)
+    except FileNotFoundError:
+        print(f"Error: The file {file_path} was not found.")
+        return None
+    except yaml.YAMLError as exc:
+        print(f"Error while parsing YAML: {exc}")
+        return None
+
+def build_run_command(model_type, connect_ip, connect_port):
+    """Builds the SSH run command for a given model."""
+    return f"lxterminal -e ssh illuminator@{connect_ip} '{RUN_PATH}run{model_type}.sh {connect_ip} {connect_port} {RUN_MODEL}'&"
+
+def process_models(data, output_file):
+    """Processes each model in the YAML data and writes the commands to a file."""
+    if 'models' not in data:
+        print("Error: No 'models' key found in the YAML data.")
+        return
+
+    with open(output_file, 'w') as file:
+
+        file.write('#! /bin/bash\n')
+
+        for model in data['models']:
+            model_type = model.get('type', 'unknown')
+
+            # Extract connection details
+            connect = model.get('connect', {})
+            connect_ip = connect.get('ip')
+            connect_port = connect.get('port', DEFAULT_PORT)
+
+            # Ensure both IP and port are available
+            if connect_ip:
+                run_command = build_run_command(model_type, connect_ip, connect_port)
+                file.write(run_command + '\n')
+            else:
+                print(f"Warning: Model '{model_type}' has no IP address specified.")
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python3 "+sys.argv[0]+" <path_to_yaml_file>")
+        sys.exit(1)
+
+    yaml_file = sys.argv[1]
+    output_file = RUN_FILE
+    data = load_yaml(yaml_file)
+
+    if data:
+        process_models(data, output_file)
+        print(f"Commands have been written to {output_file}")
+
+if __name__ == "__main__":
+    main()
+

configuration/modelling-example.yaml

@@ -22,11 +22,9 @@ models: # list of models for the energy network
     - capacity
     - soc_min
   scenario_data: 'path/to/file' #path to the scenario data file for the model. This should be optional
-  method: 
-    type: connect     # can be python for local or connect for remote
-    location: null
-    connect_ip: 192.168.0.1
-    connect_port: 5123
+  connect:
+    ip: 192.168.0.1
+    port: 5000
 - name: Battery2
   type: Battery # models can reuse the same type
   inputs: 
@@ -38,11 +36,47 @@ models: # list of models for the energy network
     charge_power_max: 100
   states: 
     soc: 0.5  # initial value for the state, optional
-  method: 
-    type: connect     # can be python for local or connect for remote
-    location: null
-    connect_ip: 192.168.0.2
-    connect_port: 5123
+  connect:
+    ip: 192.168.0.2
+    port: 5000
+- name: Battery3
+  type: Battery # models can reuse the same type
+  inputs: 
+    input1: 0  # input-name: initial value, default value will be used if not defined
+  outputs: 
+    output1: 0 
+    output2: null
+  parameters: 
+    charge_power_max: 100
+  states: 
+    soc: 0.5  # initial value for the state, optional
+  connect:
+    port: 5000
+- name: Battery4
+  type: Battery # models can reuse the same type
+  inputs: 
+    input1: 0  # input-name: initial value, default value will be used if not defined
+  outputs: 
+    output1: 0 
+    output2: null
+  parameters: 
+    charge_power_max: 100
+  states: 
+    soc: 0.5  # initial value for the state, optional
+  connect:
+    ip: 
+    port: 5000
+- name: Battery5
+  type: Battery # models can reuse the same type
+  inputs: 
+    input1: 0  # input-name: initial value, default value will be used if not defined
+  outputs: 
+    output1: 0 
+    output2: null
+  parameters: 
+    charge_power_max: 100
+  states: 
+    soc: 0.5  # initial value for the state, optional
 - name: PV1
   type: PV
   inputs: 
@@ -54,11 +88,8 @@ models: # list of models for the energy network
     power_max: 100
   states: 
     initial_soc: 0.5
-  method: 
-    type: connect     # can be python for local or connect for remote
-    location: null
-    connect_ip: 192.168.0.3
-    connect_port: 5123
+  connect:
+    ip: 192.168.0.3
 connections:
 - from: Battery1.output2 # start model, pattern: model_name.output_name/input_name
   to: PV1.input1 # end model

configuration/run.sh

@@ -1,5 +1,4 @@
 #! /bin/bash
-lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runWind.sh 192.168.0.1 5123 /home/illuminator/Desktop/Final_illuminator'&
-lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runPV.sh 192.168.0.2 5123 /home/illuminator/Desktop/Final_illuminator'&
-lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runLoad.sh 192.168.0.3 5123 /home/illuminator/Desktop/Final_illuminator'&
-lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runBattery.sh 192.168.0.4 5123 /home/illuminator/Desktop/Final_illuminator'&
+lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runBattery.sh 192.168.0.1 5000 /home/illuminator/Desktop/Final_illuminator'&
+lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runBattery.sh 192.168.0.2 5000 /home/illuminator/Desktop/Final_illuminator'&
+lxterminal -e ssh [email protected] './Desktop/illuminatorclient/configuration/runshfile/runPV.sh 192.168.0.3 5123 /home/illuminator/Desktop/Final_illuminator'&

docs/cluster-setup.md

@@ -1,70 +1,110 @@
-# Cluster Pi Set Up
+# Cluster Pi Setup
 
-
-## Raspberry Pi Setup
-
-The setup for the Illuminator requires one **master** Raspberry Pi and several **clients** Raspberry Pi's.
+The Illuminator can be deployed to a cluster of Raspberry Pi's.  It requires one Raspberry Pi acting as a **server** or 'master' and several **clients** Raspberry Pi's.
 Raspberry Pi's must be connected and configured as a local network, and the
-*master* must be configured to have permissions to access and control the *clients* through Secure Shell Protocol (SSH).
+*server* must be configured to have permissions to access and control the *clients* through the Secure Shell Protocol (SSH).
 
-During simulation, the *master* engage with the *clients* to run the simulations defined in the *simulation configuration*, and
+During simulation, the *server* engage with the *clients* to run the simulations defined in the [simulation configuration file](user/config-file.md), and
 information is exchanged between Rasberry Pi's using network sockets.
-The **master** provides a Dashboard to viazulize the results, and saves them to a `.csv` files for later analysis. 
+The **server** provides a Dashboard to visualize the results, and saves them to a `.csv` files for later analysis. 
 
 <div align="center">
-    <img align="center" src="docs/_static/img/Structure.jpg" width="500">
+	<img align="center" src="_static/img/Structure.jpg" width="500">
 </div>
 
 
-### Set up a Raspberry Pi cluster
+## Hardware Requirements
+- A Raspberry Pi to use as a *server*.
+- One or more Raspebrry Pi's to use as *clients*.
+- A networkw switch to connect all Rasberry Pi's as a local network.
+
+## Set up
+
+Conduct the following steps on each Raspberry Pi to deploy the illuminator in the cluster.
 
 1. [Install Raspberry pi OS using Raspberry Pi imager.](https://www.raspberrypi.com/software/)
-2. Set an static IP addresse for each Raspberry Pi. Use the following command on the terminal to open the `dhcpcd.conf` file:
-   ```
+2. Set an static IP address for the Raspberry Pi. Use the following command on the terminal to open the `dhcpcd.conf` file:
+
+   ```shell
    sudo nano /etc/dhcpcd.conf
    ```
 
-   In the `dhcpcd.conf` file, find the information to change the IP address as static as following:
+   In the `dhcpcd.conf` file, find the information to change the IP address to static as following:
 
-   ```
+   ```shell
    interface etho
    static ip_address=192.168.0.1/24 # change the IP address as you want
    ```
-   Finally, reboot the Raspberry Pi suing `sudo reboot` on the terminal.
-3. [Configure SSH connections so that the *master* can connect to the *clients* without a password.](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-2)
-4. Install the following Python packages.
+
+   Give all users execute permission to all the documents in `runshfile/` in order to make sure the *server* can access the *client* model.
+
+   ```shell
+   chmod -R a+X *dir*
    ```
-   pandas
-   tk
-   python-csv
-   datetime
-   python-math
-   numpy
-   scipy
-   arrow
-   mosaik
-   mosaik_api
-   mosaik.util
-   wandb
-   matplotlib
-   itertools
+
+   Finally, reboot the Raspberry Pi using `sudo reboot` on the terminal.
+3. [Configure SSH connections so that the *server* can connect to the *clients* without a password.](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-2)
+
+4. Install the Illuminator Python package, and the addional dependencies:
+
+   ```shell
+   # if connected to the internet
+   pip install illuminator
+
+   # or, if from source code
+   pip install Illuminator/
    ```
-5. Send the Illuminator package [TODO: What is the illuminator package?] to all *clients*. Use the following command on the *master's* terminal to check the connection  between *master* and the *clients*
 
    ```shell
-   ssh illuminator@ip #ip represent your follower IP address
+   # aditional dependencies
+   pip install tk python-csv python-math scipy wandb itertools
    ```
-   [TODO: This suggest that all Pi's need a user with the name 'illuminator']
+5. Use the following command on the *server's* terminal to check the connections for each of the *clients:*
 
-6. Run the `buildcilentremoterun.py` file on each *client* and give all users execute permission to all the documents in `runshfile/` in order 
-to make sure the leader can access the *client* model.
+   ```shell
+   # notice that the followng assumes that each client has a 
+   # user named 'illuminator'
+   ssh illuminator@ip #ip represent your follower IP address set in step 2
+   ```
+6. Run the `build_runshfile.py` file in the configuration directory on the *server*, this will generate a `run.sh` script. Give the appropiate `config.yaml` file containing the simulation scenario definition:
 
    ```shell
-   chmod -R a+X *dir*
+   python3 build_runshfile.py <config.yaml>
    ```
 
-More detialed instructions are given in the [user guide document](docs/user/user-guide.md) and the [model build up document](Models.md).
-
+The  `runs.sh` file contains a list of commands that will start the models required by a simulation defined in the `config.yaml`, such as:
+
+```shell
+# add example
+```
+
+TODO: integrate this:
+
+   The lx terminal command does the following:
+
+Lxterminal itself starts a terminal on a remote machine.
+
+So ‘lxterminal -e ssh [email protected]’  would use SSH to login to machine 192.168.0.1 with the user illuminator which has no password (room for improvement 😉 ).
+
+The second part:
+
+'./Desktop/illuminatorclient/configuration/runshfile/runWind.sh 192.168.0.1 5123 /home/illuminator/Desktop/Final_illuminator'&
+
+Is starting the script ./Desktop/illuminatorclient/configuration/runshfile/runWind.sh on the remote machine with the following parameters:
+
+IP address                          192.168.0.1
+Port                                       5123
+Path of mosaik                 /home/illuminator/Desktop/Final_illuminator
+
+The & at the end starts the process in the background, so that the run.sh script does not wait for the command to finish but executes the next command immediately.
+
+For example runWind.sh looks like this:
+
+#! /bin/bash
+cd $3/Wind
+python wind_mosaik.py $1:$2 –remote
+
+There you see the three parameters in action.
 
 
 ## Contact and Support

docs/conf.py

@@ -38,7 +38,7 @@
               ]
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'user/depricated-user-guide.md']
 
 
 

docs/developer/start.md → docs/developer/set-up.md

@@ -1,12 +1,10 @@
 # Set Up Environment
+Follow these steps to set up a development environment.
 
 **Requirements**
 * Python >= 3.11
 * Recent version of PIP
 
-
-To set up a development environment:
-
 1. Clone the repository:
 
 ```shell
@@ -22,14 +20,14 @@ cd Illuminator/
 3. install the development dependencies in editable mode:
 
 ```shell 
-pip install -e .e
+pip install -e .
 ```
 
 ## Running Unit Tests
 
 We use `Pytest` to write and test the source code. To run all unit-tests, run the following command at the root of the repository:
 
-```
+```shell
 pytest tests/
 ```
 

docs/index.rst

@@ -25,9 +25,9 @@ and the simulation engine is based on `Mosaik. <https://mosaik.offis.de/>`_
    :maxdepth: 2
    :caption: User's Documentation
 
-   user/start
-   user/user-guide
    user/models
+   user/config-file.md
+   user/simulations.md
 
 .. toctree::
    :maxdepth: 2
@@ -39,6 +39,7 @@ and the simulation engine is based on `Mosaik. <https://mosaik.offis.de/>`_
    :maxdepth: 2
    :caption: Developer's Documentation
 
+   developer/set-up.md
    developer/developer-docstrings.md
    developer/testing-explained.md
    developer/writing-tests.md