add stop logic interactive simulation, removed commands (NEXT PR), improved SimulationWrapperInteractive to send complete simulation status

Author: marcomelloni

agents/matlab/matlab_agent/docs/examples/interactive-simulation/InteractiveSimulation.m

@@ -1,11 +1,12 @@
 function InteractiveSimulation()
     % INTERACTIVESIMULATION  Interactive demo with frame validation.
     %   It processes valid telemetry (t, x, y, vx, vy) and sends an error packet
-    %   if the frame is missing required fields.
+    %   if the frame is missing required fields. Terminates after 100 steps.
 
     %% ───── configuration
     REQUIRED = ["t", "x", "y", "vx", "vy"];  % required fields
     PAUSE_IO = 0.01;                         % pause to avoid spin-lock (s)
+    MAX_STEPS = 100;                         % number of iterations before termination
 
     %% ───── initialization
 
@@ -15,8 +16,10 @@ function InteractiveSimulation()
     last_input = struct();  % cache of the last valid frame
     last_time  = [];        % timestamp of the last valid frame
 
+    step = 0;               % iteration counter
+
     %% ───── main loop
-    while true
+    while step < MAX_STEPS
         data_in = wrapper.get_input();  % receive data from the Python client
 
         % 1️⃣ Frame validation
@@ -25,42 +28,38 @@ function InteractiveSimulation()
 
         invalid_reason = "";
         if isempty(data_in)
-            invalid_reason = "empty frame";  % empty frame
+            invalid_reason = "empty frame";
         elseif ~isstruct(data_in)
-            invalid_reason = "not a struct";  % not a struct
+            invalid_reason = "not a struct";
         elseif ~all(isfield(data_in, REQUIRED))
             missing = REQUIRED(~isfield(data_in, REQUIRED));
             invalid_reason = "missing fields: " + strjoin(missing, ",");
         end
 
-        % 2️⃣ Always generate an output, regardless of frame validity
+        % 2️⃣ Always generate an output
         if invalid_reason ~= ""
-            disp(['❌ Invalid frame: ', invalid_reason]);  % log error
+            disp(['❌ Invalid frame: ', invalid_reason]);
             err_out = struct( ...
                 "status", "invalid", ...
                 "reason", invalid_reason, ...
                 "timestamp", posixtime(datetime("now")) ...
             );
-            wrapper.send_output(err_out);  % send error packet
+            wrapper.send_output(err_out);
         else
             % 3️⃣ If the frame is valid and new, process it
             if isempty(last_input) || ~isequal(data_in, last_input)
-                % Extract variables
                 t  = data_in.t;   x  = data_in.x;   y  = data_in.y;
                 vx = data_in.vx;  vy = data_in.vy;
 
-                % Δt (Euler)
                 if isempty(last_time)
-                    dt = 0;  % if there's no last time, set dt to 0
+                    dt = 0;
                 else
-                    dt = t - last_time;  % calculate the time difference
+                    dt = t - last_time;
                 end
 
-                % Prediction
                 x_next = x + vx * dt;
                 y_next = y + vy * dt;
 
-                % Build output
                 ok_out = struct( ...
                     "status", "ok", ...
                     "predicted", struct("x_next", x_next, "y_next", y_next), ...
@@ -71,17 +70,17 @@ function InteractiveSimulation()
                 );
 
                 disp('📤 Output sent:');
-                disp(ok_out);  % log the output sent
-
-                % Send the valid output packet
+                disp(ok_out);
                 wrapper.send_output(ok_out);
 
-                % Cache the last frame and time
                 last_input = data_in;
                 last_time  = t;
             end
         end
 
-        pause(PAUSE_IO);  % pause to avoid continuous loop consumption
+        step = step + 1;
+        pause(PAUSE_IO);
     end
+
+    wrapper.send_completed();
 end

agents/matlab/matlab_agent/docs/examples/interactive-simulation/README.md

@@ -1,46 +1,93 @@
 # Interactive Simulation
 
-This example showcases a basic "Hello world" interactive simulation.
+The `InteractiveSimulation` is a 'Hello world' MATLAB-based simulation that interacts with external clients, processes telemetry data, and returns predicted positions for a moving object. Both input and output are in streaming.
+The simulation operates in steps: it receives input, validates it, computes the next position using velocity and time, and sends the result back. This process repeats for up to 100 steps.
 
-The simulation relies on `SimulationWrapperInteractive.m` to manage TCP/IP communication with the MATLAB agent, allowing real-time data exchange between the simulation and the client.
+Telemetry data must include time (`t`), position (`x`, `y`), and velocity (`vx`, `vy`). The simulation uses the Euler method to predict the next position (`x_next`, `y_next`). If required data is missing or invalid, an error message is returned. After 100 steps, the simulation terminates.
+
+Communication with the MATLAB agent is handled via TCP, using the `SimulationWrapperInteractive` object to manage data exchange.
 
 ## Table of Contents
 
 - [Interactive Simulation](#interactive-simulation)
   - [Table of Contents](#table-of-contents)
   - [Usage](#usage)
+  - [Simulation Steps and Flow](#simulation-steps-and-flow)
 
 ## Usage
 
-Before running the simulation, you need to configure the Matlab agent by setting the simulation folder path in the `config.yaml` file under the simulation section:
+Run this simulation interactively with a Python client using the specified API payload.
 
 ```yaml
 simulation:
-  path: <path_to_simulation_folder>
-```
+  # Unique identifier for this simulation request. This ID is used to track and reference the simulation request.
+  request_id: abcdef12345
 
-This path should point to the directory `interactive-simulation` containing the simulation files
+  # Identifier for the client that is sending the simulation request.
+  client_id: dt
 
-Once configured, you can initiate the simulation using the API as described below.
+  # Specifies the simulator type. In this case, it indicates that the simulation is running in MATLAB.
+  simulator: matlab
 
-The simulation can be initiated via the API by submitting a YAML payload, a template of which is available in the file `api/simulation.yaml`
+  # Type of simulation. Here, it indicates that the simulation is "interactive", meaning it involves continuous interaction.
+  type: interactive
 
-```yaml
-simulation:
-  request_id: abcdef12345 # Unique identifier for this simulation request
-  client_id: dt # Client identifier for tracking purposes
-  simulator: matlab # Specifies MATLAB as the simulation engine
-  type: interactive # Indicates this is an interactive simulation type
-  file: InteractiveSimulation.m # Main MATLAB file to execute
+  # Name of the MATLAB script that will handle the simulation. This script will process the input data and return the output.
+  file: InteractiveSimulation.m
+
+  # The inputs section defines the data that the simulation will receive to process.
   inputs:
-    stream_source: "rabbitmq://streaming.inputs.sim123" # RabbitMQ stream for input data
+    # Specifies the RabbitMQ stream URL from which the simulation will receive telemetry data.
+    # This is the source for continuous stream data to be processed in the simulation.
+    stream_source: "rabbitmq://streaming.inputs.sim123"
+
+  # The outputs section defines the structure of the results that will be returned after processing the inputs.
   outputs:
+    # Predicted values after the simulation process. These values represent the predicted next positions of the object.
     predicted:
-      x_next: float # Next predicted X coordinate value
-      y_next: float # Next predicted Y coordinate value
+      # Predicted x-coordinate of the object in the next time step.
+      x_next: float
+
+      # Predicted y-coordinate of the object in the next time step.
+      y_next: float
+
+    # Miscellaneous data that could provide additional context or information about the simulation.
     misc:
-      distance_from_origin: float # Calculated distance from origin point
-      timestamp: float # Simulation timestamp in epoch seconds
+      # The Euclidean distance from the origin (0, 0) to the current position of the object.
+      # This can be used to measure how far the object has moved from its starting point.
+      distance_from_origin: float
+
+      # The timestamp of the output data in epoch seconds. This helps to track when the output was generated.
+      timestamp: float # epoch seconds
 ```
 
-Use the client `use_matlab_agent_interactive.py` with the CLI option `--api-payload` to specify the path to this YAML payload file and start the client.
+> **Note:** The stream_source field in the inputs section is mandatory for interactive simulations. This parameter specifies the RabbitMQ stream from which the simulation will receive real-time input data, and it must be included for the simulation to function correctly.
+
+## Simulation Steps and Flow
+
+1. **Initialization**
+
+   - Initialize `SimulationWrapperInteractive` for TCP communication.
+   - Prepare to receive telemetry input.
+
+2. **Main Loop (100 Steps)**
+
+   - Process telemetry frames from the Python client.
+   - Each frame must include: `t`, `x`, `y`, `vx`, `vy`.
+
+3. **Frame Validation**
+
+   - Check for all required fields.
+   - If valid, compute next position using Euler method:
+     - `x_next = x + vx * dt`
+     - `y_next = y + vy * dt`
+     - `dt` is the time difference between current and previous `t`.
+   - If invalid, send error message.
+
+4. **Output**
+
+   - Send predicted position and additional info (distance from origin, timestamp) to the client.
+   - On error, send error packet.
+
+5. **Completion**
+   - After 100 steps, send a "completed" message.

agents/matlab/matlab_agent/docs/examples/interactive-simulation/SimulationWrapperInteractive.m

@@ -1,103 +1,114 @@
-
 classdef SimulationWrapperInteractive < handle
+    % SIMULATIONWRAPPERINTERACTIVE
+    % Wrapper for interactive communication with a Python-based simulation client
+    % via TCP. Handles input reception, output transmission, and finalization.
+
     properties (Access = private)
-        out_client  % TCP client object for outgoing data
-        in_client   % TCP client object for incoming data
-        last_inputs % Store the last inputs received from Python
+        out_client   % TCP client for sending data to Python
+        in_client    % TCP client for receiving data from Python
+        last_inputs  % Cache of the most recent valid input frame
     end
-    
+
     methods
-        % Constructor for the SimulationWrapperInteractive class
+        % Constructor: Establishes TCP connections to the Python client
         function obj = SimulationWrapperInteractive()
-            % Default host and ports (modifiable)
+            % Default connection settings
             out_host = 'localhost';
             out_port = 5678;
             in_host = 'localhost';
             in_port = 5679;
-            % Max retries for connecting to the server
+
+            % Retry logic configuration
             max_retries = 5;
-            retry_delay = 1;  % Delay between retries in seconds
+            retry_delay = 1;  % in seconds
 
-            % Try to connect to the server up to 'max_retries' times
+            % Attempt to connect to input and output ports with retry
             for retry = 1:max_retries
                 try
-                    % Create a TCP client object to connect to Python server
                     obj.out_client = tcpclient(out_host, out_port);
-                    obj.in_client = tcpclient(in_host, in_port);
+                    obj.in_client  = tcpclient(in_host, in_port);
+
                     configureTerminator(obj.out_client, "LF");
                     configureTerminator(obj.in_client, "LF");
-                    break; % Exit the loop if the connection is successful
+
+                    break;  % Exit loop upon successful connection
                 catch ME
-                    % If connection fails, retry up to 'max_retries' times
                     if retry == max_retries
-                        % If max retries reached, rethrow the exception
-                        rethrow(ME);
+                        rethrow(ME);  % Rethrow error if max retries reached
                     end
-                    % Wait before retrying
-                    pause(retry_delay);
+                    pause(retry_delay);  % Wait before next retry
                 end
             end
 
-            % Receive the initial parameters in JSON format from Python
+            % Read initial configuration/handshake data from Python (JSON format)
             data = readline(obj.out_client);
-            % Decode the received JSON data and store it as 'last_inputs'
-            obj.last_inputs = jsondecode(data);
+            obj.last_inputs = jsondecode(data);  % Store parsed input
         end
 
-        % Method to retrieve input parameters from the Python server
+        % Retrieve the latest input data frame (non-blocking with timeout)
         function inputs = get_input(obj)
-            % Single method to get input data
-            % Reads new streaming data if available, otherwise returns last input
-
-            % Timeout or no data received for a while
-            timeout_limit = 2;  % Set a timeout limit (in seconds)
+            timeout_limit = 2;  % Timeout threshold in seconds
             time_start = tic;
 
             new_data = obj.try_receive();
+
+            % Retry receiving until timeout is reached
             while isempty(new_data)
-                % No new data, check if the timeout limit is reached
                 if toc(time_start) > timeout_limit
                     disp('⏳ Timeout: No new input data received for a while.');
-                    break;  % Exit the loop if timeout
+                    break;
                 end
-                % Retry reading if no new data
                 new_data = obj.try_receive();
             end
 
+            % Update internal cache if new data was received
             if ~isempty(new_data)
                 obj.last_inputs = new_data;
             end
-            inputs = obj.last_inputs;  % Return the stored inputs
+
+            % Return the most recent available inputs
+            inputs = obj.last_inputs;
         end
 
+        % Try to receive a new input frame (non-blocking)
         function data_struct = try_receive(obj)
-            % Non-blocking receive function to get data if available
             data_struct = [];
+
+            % Read available data lines from the input stream
             while obj.in_client.NumBytesAvailable > 0
                 line = readline(obj.in_client);
                 disp("📩 Received:");
                 disp(line)
                 try
-                    data_struct = jsondecode(line);
+                    data_struct = jsondecode(line);  % Attempt to parse JSON
                 catch
-                    warning("JSON decode failed");
+                    warning("JSON decode failed");  % Log failure but continue
                 end
             end
         end
 
-        % Method to send output data to the Python server
+        % Send a "simulation completed" packet to Python
+        function send_completed(obj)
+            completed_packet = struct( ...
+                "status", "completed", ...
+                "timestamp", posixtime(datetime("now")) ...
+            );
+            disp("✅ Simulation completed. Sending final packet:");
+            disp(completed_packet);
+
+            obj.send_output(completed_packet);
+        end
+
+        % Send an output frame to the Python client (encoded as JSON)
         function send_output(obj, output_data)
-            % Convert the output data to JSON format
-            json_data = jsonencode(output_data);
-            % Send the JSON-encoded data to Python server
-            writeline(obj.out_client, json_data);
+            json_data = jsonencode(output_data);       % Convert to JSON string
+            writeline(obj.out_client, json_data);      % Send via TCP
         end
 
-        % Destructor to clean up the TCP client object when the wrapper is deleted
+        % Destructor: Gracefully close the TCP connections
         function delete(obj)
-            % Close the TCP connection by deleting the client object
             delete(obj.out_client);
             delete(obj.in_client);
         end
     end
-end
+end

agents/matlab/matlab_agent/resources/README.md

@@ -118,7 +118,7 @@ Each example folder contains an `api/` subfolder with example simulation payload
 To run the batch simulation example, specify the full absolute path to the payload file when invoking the Python client:
 
 ```bash
-python use_matlab_agent.py --api-payload "/Users/foo/simulation-bridge/agents/matlab/matlab_agent/docs/examples/batch-simulation/api/simulation_batch.yaml.example"
+python use_matlab_agent_batch.py --api-payload "/Users/foo/simulation-bridge/agents/matlab/matlab_agent/docs/examples/batch-simulation/api/simulation_batch.yaml.example"
 ```
 
 ## Control Commands