MATLAB

Note: Users must procure and maintain valid licenses to integrate this commercial DE tool with the Istari Digital platform. Please contact your local IT administrator for assistance.

Supported Functions:

extract

Getting Started

The Matlab integration provides support for MATLAB R2023b, allowing users to extract data and run MATLAB scripts.

Methods to Link to Istari Digital Platform

Upload: Yes

Link: No

Files Supported

The istari Digital Platform can extract from the following file types: .m

All other MATLAB file types not supported at this time. Please submit a feature request if an important file type is not supported.

Example Files

Download Example Script: example_script.m

Setup for Administrators

Ensure that MATLAB is installed on a machine with Istari Digital Agent and appropriate Istari Digital Software. Verify that the installation is up to date with the latest patches and updates from MATLAB.

Version Compatibility

This software was tested with MATLAB R2023b, and is intended to run in a Linux or Windows environment. It may work on similar Matlab versions near R2023. It was tested on a Linux Ubuntu 22.04 and a Windows 11 Virtual Machine (VM).

Function Coverage and Outputs

The MATLAB software can produce a number of artifacts extracted from the MATLAB script. The table below describes each output artifact and its type.

Route	Coverage	Artifact Content Example
Extract figures - PNG	Yes
Extract input variables - JSON	Yes
Extract output variables - JSON	Yes
Extract functions - JSON	Yes
Extract metadata - JSON	Yes
Extract errors and warnings - JSON	Yes
Extract workspace file - MAT	Yes
Update extracted inputs - JSON	Coming Soon	Coming Soon

Tips and tricks for model extraction and Reuse

To ensure the extract function from our module operates effectively with your MATLAB script, follow these guidelines when setting up your script.

1. Define Input Variables in a Dictionary

At the beginning of your MATLAB script, define all the input variables you intend to use in the script. These variables should be stored in a dictionary named istari_input. Assign each variable to the dictionary using @() function handles.

Here's how you can structure your input variables and the istari_input dictionary:

% Inputs
A = [1.0, 2.5, 3.7];
B = [4.1, 5.2, 6.3];  % Example additional variable
singleArray = [7.4, 8.5, 9.6];
complexNum = 2 + 3i;
structVar = struct('field1', 1, 'field2', 'text', 'field3', [1, 2, 3]);
cellArray = {'text', 123, true};
% Creating istari_input dictionary
istari_input = dictionary();
istari_input('A') = @() A;
istari_input('B') = @() B;
istari_input('singleArray') = @() singleArray;
istari_input('complexNum') = @() complexNum;
istari_input('structVar') = @() structVar;
istari_input('cellArray') = @() cellArray;

2. Define Output Variables in a Dictionary

After the script has run, capture all the output variables and store them in a dictionary named istari_output. This ensures that all relevant outputs are available for extraction.

Here's an example of how to structure your output variables and the istari_output dictionary:

% Outputs
resultArray = [10, 20, 30]; % Example output variable
calculatedSum = sum(resultArray); % Another example output
% Creating istari_output dictionary
istari_output = dictionary();
istari_output('resultArray') = @() resultArray;
istari_output('calculatedSum') = @() calculatedSum;

Make sure to assign the output variables to the istari_output dictionary using @() function handles at the point in your script where the variable results are desired and available. All defined functions shall be defined at the end of the script as per MATLAB syntax.

3. Specify the matlab script Start Line

Identify the line number in your script where the script starts. This line number is crucial as it should be passed as an argument to the extract function to ensure accurate extraction of script data.

For example, if your script starts at line 20, you will pass this line number when calling the extract function:

% The number of this line (e.g., 20) should be passed as an argument to the `extract` function

4. Example MATLAB Script

Below is an example of how your MATLAB script might look:

% Inputs
A = [1.0, 2.5, 3.7];
B = [4.1, 5.2, 6.3];
singleArray = [7.4, 8.5, 9.6];
complexNum = 2 + 3i;
structVar = struct('field1', 1, 'field2', 'text', 'field3', [1, 2, 3]);
cellArray = {'text', 123, true};
% Creating istari_input dictionary
istari_input = dictionary();
istari_input('A') = @() A;
istari_input('B') = @() B;
istari_input('singleArray') = @() singleArray;
istari_input('complexNum') = @() complexNum;
istari_input('structVar') = @() structVar;
istari_input('cellArray') = @() cellArray;
% Script starts here
% (Replace the following line with your actual script code)
simulate_system();  % Example script function
% Outputs
resultArray = [10, 20, 30];
calculatedSum = sum(resultArray);
% Creating istari_output dictionary
istari_output = dictionary();
istari_output('resultArray') = @() resultArray;
istari_output('calculatedSum') = @() calculatedSum;
% The number of the line where 'simulate_system()' is called should be passed as an argument to the `extract` function

Notes

• Function Handles: Using @() function handles in the istari_input dictionary ensures that the variables are evaluated at the time of extraction, capturing their latest values after any prior modifications in the script.
• Line Number Accuracy: It's important to keep the line number accurate. If you add or remove lines in your script, update the line number accordingly when calling the extract function.

By following these steps, you can optimize your MATLAB script for seamless integration with our module's extraction functionality.

Detailed SDK Reference

Prerequisite: Install Istari Digital SDK and initialize Istari Digital Client per instructions here

Step 1: Upload and Extract the File(s)

Upload the file as a model

model = client.add_model(
    path="example_script.m",
    description="Matlab example script",
    display_name="Matlab Model Name",
)
print(f"Uploaded base model with ID {model.id}")

Extract once you have the model ID

extraction_job = client.add_job(
    model_id  = model.id,
    function  = "@istari:extract",
    tool_name = "matlab",
    tool_version = "R2023b",
    operating_system = "Ubuntu 22.04",
    parameters = {"checkpoint_line": 43},
)
print(f"Extraction started for model ID {model.id}, job ID: {extraction_job.id}")

Please choose appropriate tool_name, tool_version, and operating_system for your installation of this software.
Above is an example of how to call the function

Step 2: Check the Job Status

extraction_job.poll_job()

Step 3: Retrieve Results

Example

for artifact in model.artifacts:
    output_file_path = f"c:\\extracts\\{artifact.name}"

    if artifact.extension in ["txt", "csv", "md", "json", "html"]:
        with open(output_file_path, "w") as f:
            f.write(artifact.read_text())
    else:
        with open(output_file_path, "wb") as f:
            f.write(artifact.read_bytes())

Troubleshooting

1. For general Agent and Software Troubleshooting Click Here

2. Missing Artifacts: If certain artifacts or parts of an artifact are missing after extraction (e.g., inputs.json or outputs.json), this typically indicates that the MATLAB script is not fully configured according to the optimal standards.

   Suggested Action:

   • Review the Tips and tricks for model extraction and Reuse section for guidance on setting up the script correctly.
   • Verify that all input variables are defined in the istari_input dictionary and are assigned using @() function handles.
   • Ensure that the line number specified for the start of the script in the extract function is accurate.

3. Errors in the MATLAB Script: If there are syntax errors or runtime errors in the MATLAB script, the extraction process will fail.

   Suggested Action:

   • Review the error logs provided in the errors_and_warnings.json file to identify the source of the issue.
   • Run the MATLAB script independently to ensure there are no errors or undefined variables.
   • Correct any errors in the script before attempting extraction again.

4. Inconsistent Extraction Results: If the extracted results vary between runs, it might be due to changes in the script or model that are not reflected in the istari_input dictionary.

   Suggested Action:

   • Ensure that the istari_input dictionary is defined at the start of the script and contains all necessary input variables.
   • Verify that the values of the input variables are updated consistently before extraction.

By following these troubleshooting steps, you can resolve common issues that may arise during the MATLAB script extraction process.

FAQ