docs/tutorials sofa

docs/User_Guide/getting_started.md

@@ -4,9 +4,13 @@ pySimBlocks is a block-based simulation framework for control systems,
 supporting both programmatic and graphical modeling workflows.
 
 This guide walks you through the core concepts in a progressive manner.
+Recommended order: Tutorial 1 -> Tutorial 2 -> Tutorial 3.
 
 ## 1. First Simulation (Python)
 
+Prerequisites: Python environment configured for pySimBlocks.
+Level: Beginner.
+
 Build and simulate a closed-loop system directly in Python.
 
 You will learn:
@@ -16,9 +20,13 @@ You will learn:
 - How to log and visualize results
 
 → [Start Tutorial 1 — Python API](tutorial_1_python.md)
+After this tutorial: You can build and run a basic closed-loop model from code.
 
 ## 2. First Simulation (GUI)
 
+Prerequisites: Tutorial 1 completed, pySimBlocks GUI installed.
+Level: Beginner.
+
 Rebuild the same system using the graphical interface.
 
 You will learn:
@@ -27,4 +35,20 @@ You will learn:
 - How to save and export the project
 
 → [Start Tutorial 2 — GUI](tutorial_2_gui.md)
+After this tutorial: You can create and manage equivalent models in the GUI.
+
+## 3. SOFA Coupling
+
+Prerequisites: Tutorials 1 and 2 completed, SOFA installed and available.
+Level: Intermediate.
+
+Replace the plant with a SOFA model. 
+
+You will learn:
+- How to set up the environment for SOFA coupling
+- How to interface pySimBlocks with SOFA
+- How to run co-simulations
+- How to use SOFA's GUI for inspection and debugging
 
+→ [Start Tutorial 3 — SOFA Coupling](tutorial_3_sofa.md)
+After this tutorial: You can run a pySimBlocks + SOFA co-simulation workflow.

docs/User_Guide/tutorial_1_python.md

@@ -19,7 +19,7 @@ We build a simple closed-loop control system composed of three elements:
 - a PI controller, 
 - a first-order discrete-time linear plant.
 
-![Alt Text](./images/tutorial_1-block_diagram.png)
+![Block-Diagram](./images/tutorial_1-block_diagram.png)
 
 **Plant — Linear State-Space System**  
 The plant is a discrete-time first-order linear system defined by:
@@ -186,6 +186,6 @@ Observe how the closed-loop response changes.
 This simple example is the foundation for more advanced use cases,
 including:
 - [GUI modeling](./tutorial_2_gui.md), 
-- SOFA integration, 
+- [SOFA integration](./tutorial_3_sofa.md), 
 - Hardware implementation.
 

docs/User_Guide/tutorial_2_gui.md

@@ -22,7 +22,7 @@ We build a simple closed-loop control system composed of three elements:
 - a PI controller, 
 - a first-order discrete-time linear plant.
 
-![Alt Text](./images/tutorial_1-block_diagram.png)
+![Block Diagram](./images/tutorial_1-block_diagram.png)
 
 ## 2. Step-by-Step Construction
 
@@ -35,7 +35,7 @@ $ cd tutorial-gui
 $ pysimblocks
 ```
 The main window opens, with the `Toolbar` at the top, the `Blocks List` on the left, and the `Diagram View` on the right.
-![Alt Text](./images/tutorial_2-gui_main.png)
+![Gui](./images/tutorial_2-gui_main.png)
 
 ### 2.2 Add the Blocks 
 
@@ -44,11 +44,12 @@ Add the required blocks to the diagram.
 2. Drag the selected block into the `Diagram View` 
 3. Repeat this for all required blocks and arrange them in the `Diagram View`. 
 
-![Alt Text](./images/tutorial_2-drag_drop.gif)
+![Drag-Drop](./images/tutorial_2-drag_drop.gif)
 
-**Tips:** 
-- Once you have all your blocks, if you click anywhere in the `Diagram View`, you can use `space` to center the view on all blocks.
-- To rotate a block, select it and press `Ctrl+R`. 
+> **Notes:** 
+> - You can click anywhere in the `Diagram View`, and use `space` to center the view on 
+> all blocks.
+> - To rotate a block, select it and press `Ctrl+R`. 
 
 ### 2.3 Connect the Blocks
 
@@ -58,11 +59,12 @@ To connect two blocks: Select the first port (input or output) and drag the conn
 
 When dragging the cable, a dashed line appears between the starting port and the cursor. The line becomes solid once the connection is valid.
 
-![Alt Text](./images/tutorial_2-connections.gif)
+![Connection](./images/tutorial_2-connections.gif)
 
 ⚠️ The two ports must be of different types (input to output). 
 
-**Tips:** You can move a connection by selecting the line and moving your mouse. However, if a connected block moves, the connection is recomputed.
+>  **Notes:** You can move a connection by selecting the line and moving your mouse. 
+>  However, if a connected block moves, the connection is recomputed.
 
 ### 2.4 Configure the Parameters 
 
@@ -90,11 +92,12 @@ Renaming a block updates its label in the `Diagram View`. In [Tutorial 1](./tuto
 
 All required parameters must be defined before running the simulation.
 
-![Alt Text](./images/tutorial_2-block_dialog.gif)
+![Block-Dialog](./images/tutorial_2-block_dialog.gif)
 
-**Tips:** 
-- Scalars are represented as `(1,1)` arrays. But you can create matrix or vector by defining `[[0.5], [0.3]]`  which will be set to a `(2,1)` numpy array.
-- Use the Help button for a detailed description of the block.
+> **Notes:** 
+> - Scalars are represented as `(1,1)` arrays. But you can create matrix or vector by
+> defining `[[0.5], [0.3]]`  which will be set to a `(2,1)` numpy array.
+> - Use the Help button for a detailed description of the block.
 
 #### 2.4.b For the Simulation
 
@@ -108,7 +111,7 @@ Click the `Settings` button in the `Toolbar`. A dialog opens with multiple panel
 Custom plots can be defined in the `Plots` panel for quick access after the simulation You must define:
 - the title 
 - the signals 
-![Alt Text](./images/tutorial_2-setting.gif)
+![Setting](./images/tutorial_2-setting.gif)
 
 ⚠️ Click `Apply` before switching panels, otherwise the changes will not be saved.  
 Click on `ok` to close.
@@ -120,13 +123,13 @@ Once all parameters are configured, run the simulation using the `Run` button in
 Click the `Plot` button in the `Toolbar` to visualize the results. A dialog opens where you can either:
 - Plot selected logged signals in a single graph.
 - Open your predefined plots. 
-![Alt Text](./images/tutorial_2-plots.gif)
+![Plots](./images/tutorial_2-plots.gif)
 
 Under the hood, the GUI generates the same `Model` structure used in [Tutorial 1](./tutorial_1_python.md). The execution engine remains identical.
 
 ## 3. Generate Project Files 
 
-### Saving
+### 3.1 Saving
 
 Saving the project using the `Save` button in the `Toolbar` creates a unified `project.yaml` file in the current folder.
 
@@ -138,7 +141,7 @@ This file contains:
 
 This single file fully describes the model and can be reloaded in the GUI or executed programmatically in Python.
 
-### Exporting a Python Runner
+### 3.2 Exporting a Python Runner
 
 The `Export` button in the `Toolbar` generates a `run.py` file.
 
@@ -183,4 +186,4 @@ After modifying the model, save the project and export a new `run.py` file.
 Run it from the command line to verify that the exported script reproduces the same behavior.
 
 This tutorial demonstrates how to build and execute a model visually.  
-The next tutorials extend this approach to SOFA integration and real-time execution.
+The next tutorials extend this approach to [SOFA integration](./tutorial_3_sofa.md) and real-time execution.