Adds new case study for MATLAB Agent (#16)

-  Adds new case study on
   Industrial Cooling Fan Anomaly Detection Algorithm which
   has been taken from Matlab website.
- Adds documentation and restructures existing examples.

---------
Co-authored-by: prasadtalasila <prasadtalasila@users.noreply.github.com>

Author: marcomelloni

.gitignore

@@ -179,10 +179,13 @@ cython_debug/
 agents/matlab/client
 agents/matlab/logs
 agents/matlab/performance_log
+agents/matlab/matlab_agent/docs/examples/industrial-cooling-fan-anomaly-detection/Data/
 # Interactive simulation in progress
 agents/matlab/matlab_agent/src/interactive/ 
 agents/matlab/matlab_agent/docs/examples/InteractiveSimulation.m
 agents/matlab/matlab_agent/docs/examples/InteractiveSimulationWrapper.m
+# Simulink
+slprj/
 # Distribution files
 agents/matlab/dist/
 # Config files
@@ -198,4 +201,5 @@ simulation*.yaml
 #SIMULATION BRIDGE 
 /logs
 
-
+.venv*
+certs

agents/matlab/README.md

@@ -349,17 +349,7 @@ Inside this folder, you'll find:
 - `simulation.yaml` — The simulation request payload that will be sent to the MATLAB Agent
 - `use_matlab_agent.py` — Python script to send the request and receive the results
 
-**Steps to Run**
-
-1. Open and configure `use.yaml` with the appropriate protocol settings.
-2. Open and configure `simulation.yaml` with the parameters of your simulation request.
-3. Run the script to send the request:
-
-```bash
-python use_matlab_agent.py
-```
-
-4. The script will send the simulation request to the MATLAB Agent and display the response received.
+For detailed instructions on how to configure and use the client, refer to the [Use Matlab Agent](./matlab_agent/resources/README.md) in the `agents/matlab/matlab_agent/resources/` folder.
 
 ## Workflow
 

agents/matlab/matlab_agent/docs/examples/SimulationBatch1.m

@@ -0,0 +1,56 @@
+# Batch Simulation
+
+This example showcases a basic "Hello world" batch simulation that computes the future position of a ball moving in three-dimensional space, given an initial position and constant velocity along each axis.
+
+The input parameters are:
+
+- the initial position of the ball (`x_i`, `y_i`, `z_i`)
+- the velocity components (`v_x`, `v_y`, `v_z`)
+- the time duration `t` for which the ball moves
+
+The simulation returns the final position (`x_f`, `y_f`, `z_f`) using basic equations of uniform linear motion.  
+This is a simple, deterministic model used to test the simulation system with customizable input parameters.
+
+## Table of Contents
+
+- [Batch Simulation](#batch-simulation)
+  - [Table of Contents](#table-of-contents)
+  - [Usage](#usage)
+
+## 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:
+
+```yaml
+simulation:
+  path: <path_to_simulation_folder>
+```
+
+This path should point to the directory `batch-simulation` containing the simulation files
+
+Once configured, you can initiate the simulation using the API as described below.
+
+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`
+
+```yaml
+simulation:
+  request_id: abcdef12345 # Unique identifier for the simulation request
+  client_id: dt # ID of the client making the request (e.g., Digital Twin)
+  simulator: matlab # Specifies MATLAB as the simulation engine
+  type: batch # Simulation type: 'batch' means a one-time execution, not continuous/streaming
+  file: SimulationBatch.m # Name of the MATLAB file to run for the simulation
+  inputs:
+    x_i: 10 # Initial x-coordinate of the ball
+    y_i: 9 # Initial y-coordinate of the ball
+    z_i: 0 # Initial z-coordinate of the ball
+    v_x: 1 # Velocity along the x-axis
+    v_y: 14 # Velocity along the y-axis
+    v_z: 3 # Velocity along the z-axis
+    t: 10 # Duration of motion (time)
+  outputs:
+    x_f: Final x position # Output field name for the final x-coordinate
+    y_f: Final y position # Output field name for the final y-coordinate
+    z_f: Final z position # Output field name for the final z-coordinate
+```
+
+Use the client `use_matlab_agent.py` with the CLI option `--api-payload` to specify the path to this YAML payload file and start the client.

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

@@ -0,0 +1,18 @@
+simulation:
+  request_id: abcdef12345              # Unique identifier for the simulation request
+  client_id: dt                        # ID of the client making the request (e.g., Digital Twin)
+  simulator: matlab                    # Specifies MATLAB as the simulation engine
+  type: batch                         # Simulation type: 'batch' means a one-time execution, not continuous/streaming
+  file: SimulationBatch.m              # Name of the MATLAB file to run for the simulation
+  inputs:
+    x_i: 10                          # Initial x-coordinate of the ball
+    y_i: 9                           # Initial y-coordinate of the ball
+    z_i: 0                           # Initial z-coordinate of the ball
+    v_x: 1                           # Velocity along the x-axis
+    v_y: 14                          # Velocity along the y-axis
+    v_z: 3                           # Velocity along the z-axis
+    t: 10                           # Duration of motion (time)
+  outputs:
+    x_f: Final x position             # Output field name for the final x-coordinate
+    y_f: Final y position             # Output field name for the final y-coordinate
+    z_f: Final z position             # Output field name for the final z-coordinate

agents/matlab/matlab_agent/docs/examples/SimulationBatch.m renamed to agents/matlab/matlab_agent/docs/examples/batch-simulation/SimulationBatch.m

@@ -0,0 +1,126 @@
+%% CoolingFanAnomalyDetectionExample
+% This is the original example simulation that has been copied and modified to
+% support batch constraints inside simulation.m. The current file serves as a reference
+% for the original implementation before the modifications were made to handle
+% batch processing constraints.
+
+addpath('Data_Generator/', 'Data_Generator/VaryingConvectionLib/');
+mdl = "CoolingFanWithFaults";
+open_system(mdl)
+
+generateFlag = false;
+if isfolder('./Data')
+    folderContent = dir('Data/CoolingFan*.mat');
+    if isempty(folderContent)
+        generateFlag = true;
+    else
+        numSim = numel(folderContent);
+    end
+else
+    generateFlag = true;
+end
+
+if generateFlag
+    numSim = 5;
+    rng("default");
+    generateData('training', numSim);
+end
+
+ensemble = simulationEnsembleDatastore(pwd,'simulation','Data');
+ensemble.SelectedVariables = ["Signals", "Anomalies"];
+
+trainEnsemble = subset(ensemble, 1:numSim-3);
+testEnsemble = subset(ensemble, numSim-2:numSim-1);
+validationEnsemble = subset(ensemble, numSim);
+
+tempData = trainEnsemble.read;
+signal_data = tempData.Signals{1};
+anomaly_data = tempData.Anomalies{1};
+
+h = figure;
+tiledlayout("vertical");
+ax1 = nexttile; plot(signal_data.Data(:,1));
+ax2 = nexttile; plot(signal_data.Data(:,2));
+ax3 = nexttile; plot(signal_data.Data(:,3));
+ax4 = nexttile; plot(anomaly_data.Data(:,1), 'bx', 'MarkerIndices',find(anomaly_data.Data(:,1)>0.1), 'MarkerSize', 5); hold on;
+plot(anomaly_data.Data(:,2), 'ro', 'MarkerIndices',find(anomaly_data.Data(:,2)>0.1), 'MarkerSize', 5);
+plot(anomaly_data.Data(:,3), 'square', 'Color', 'g', 'MarkerIndices',find(anomaly_data.Data(:,3)>0.1), 'MarkerSize', 5); 
+linkaxes([ax1 ax2 ax3 ax4],'x')
+ylim([0, 2]);
+legend("Load Anomaly", "Fan Anomaly", "Power Supply Anomaly", 'Location', 'bestoutside')
+set(h,'Units','normalized','Position',[0 0 1 .8]);
+
+trainingData = trainEnsemble.readall;
+anomaly_data = vertcat(trainingData.Anomalies{:});
+labelArray={'Normal','Anomaly1','Anomaly2', 'Anomaly3', 'Anomaly12','Anomaly13','Anomaly23','Anomaly123'}';
+yCategoricalTrain=labelArray(sum(anomaly_data.Data.*2.^(size(anomaly_data.Data,2)-1:-1:0),2)+1,1);
+yCategoricalTrain=categorical(yCategoricalTrain);
+summary(yCategoricalTrain);
+
+yTrainAnomaly1=logical(anomaly_data.Data(:,1));
+yTrainAnomaly2=logical(anomaly_data.Data(:,2));
+yTrainAnomaly3=logical(anomaly_data.Data(:,3));
+
+windowSize=2000;
+sensorDataTrain = vertcat(trainingData.Signals{:});
+ensembleTableTrain1 = generateEnsembleTable(sensorDataTrain.Data,yTrainAnomaly1,windowSize);
+ensembleTableTrain2 = generateEnsembleTable(sensorDataTrain.Data,yTrainAnomaly2,windowSize);
+ensembleTableTrain3 = generateEnsembleTable(sensorDataTrain.Data,yTrainAnomaly3,windowSize);
+
+ensembleTableTrain1_reduced = downsampleNormalData(ensembleTableTrain1);
+ensembleTableTrain2_reduced = downsampleNormalData(ensembleTableTrain2);
+ensembleTableTrain3_reduced = downsampleNormalData(ensembleTableTrain3);
+
+startApp = false;
+if startApp 
+    diagnosticFeatureDesigner; %#ok<UNRCH>
+end
+
+featureTableTrain1 = diagnosticFeatures(ensembleTableTrain1_reduced);
+featureTableTrain2 = diagnosticFeatures(ensembleTableTrain2_reduced);
+featureTableTrain3 = diagnosticFeatures(ensembleTableTrain3_reduced);
+
+head(featureTableTrain1);
+
+m.m1 = fitcsvm(featureTableTrain1, 'Anomaly', 'Standardize',true, 'KernelFunction','gaussian');
+m.m2 = fitcsvm(featureTableTrain2, 'Anomaly', 'Standardize',true, 'KernelFunction','gaussian');
+m.m3 = fitcsvm(featureTableTrain3, 'Anomaly', 'Standardize',true, 'KernelFunction','gaussian');
+
+save anomalyDetectionModelSVM m
+
+testData = testEnsemble.readall;
+anomaly_data_test = vertcat(testData.Anomalies{:});
+
+yTestAnomaly1=logical(anomaly_data_test.Data(:,1));
+yTestAnomaly2=logical(anomaly_data_test.Data(:,2));
+yTestAnomaly3=logical(anomaly_data_test.Data(:,3));
+
+sensorDataTest = vertcat(testData.Signals{:});
+ensembleTableTest1 = generateEnsembleTable(sensorDataTest.Data,yTestAnomaly1,windowSize);
+ensembleTableTest2 = generateEnsembleTable(sensorDataTest.Data,yTestAnomaly2,windowSize);
+ensembleTableTest3 = generateEnsembleTable(sensorDataTest.Data,yTestAnomaly3,windowSize);
+
+featureTableTest1 = diagnosticFeatures(ensembleTableTest1);
+featureTableTest2 = diagnosticFeatures(ensembleTableTest2);
+featureTableTest3 = diagnosticFeatures(ensembleTableTest3);
+
+results1 = m.m1.predict(featureTableTest1(:, 2:end));
+results2 = m.m2.predict(featureTableTest2(:, 2:end));
+results3 = m.m3.predict(featureTableTest3(:, 2:end));
+
+yT = [featureTableTest1.Anomaly, featureTableTest2.Anomaly, featureTableTest3.Anomaly];
+yCategoricalT = labelArray(sum(yT.*2.^(size(yT,2)-1:-1:0),2)+1,1);
+yCategoricalT = categorical(yCategoricalT);
+
+yHat = [results1, results2, results3];
+yCategoricalTestHat=labelArray(sum(yHat.*2.^(size(yHat,2)-1:-1:0),2)+1,1);
+yCategoricalTestHat=categorical(yCategoricalTestHat);
+
+figure
+confusionchart(yCategoricalT, yCategoricalTestHat)
+
+figure
+tiledlayout(1,3);
+nexttile; confusionchart(featureTableTest1.Anomaly, results1);
+nexttile; confusionchart(featureTableTest2.Anomaly, results2);
+nexttile; confusionchart(featureTableTest3.Anomaly, results3);