Configuring Execution Options

You can control execution options, such as determining if MATLAB® runs in the background and controlling how MATLAB responds to errors.

  1. From the Applications section of the action bar, click MATLAB and drop it on the process diagram.
  2. Double-click MATLAB .
    The MATLAB Editor appears.
  3. From the MATLAB Editor, click the Options tab.
  4. Set the following options, as desired:

    • Capture MATLAB console output in. Select this option if you want to capture the text generated by running Commands from the MATLAB console log and bring the text into Optimization Process Composer.

      When a MATLAB command ends with a semicolon, MATLAB does not echo the command to the console; therefore, there is nothing to capture. You need to remove semicolons from your commands to capture the MATLAB console output.

      Console output is captured by calling the MATLAB diary command to tell MATLAB to write its console output to a file. For the adapter code to find this file, it must be written into the current working directory, which is defined only when the adapter runs the Execute action sequence. Therefore, console output cannot be captured when running the Initialize or Finalize action sequences. If you need to debug these action sequences, you must (temporarily) move them into the Execute action sequence.

      1. Choose where to store the text as follows:
        • On error runs only. Select this option to ignore the contents of the MATLAB console unless running a Command generates a MATLAB error. If an error occurs, the contents that contain the text of the MATLAB error message are captured and written to the job log as an error message. This is the default option. This option is useful when you cannot easily diagnose the cause of the error from the Optimization Process Composer error message.
        • On every run. Select this option to write the contents of the MATLAB console log to the job log in the current working directory. This option is useful when you need to diagnose a problem with your Command that does not generate a MATLAB error.
      2. Determine if you want to generate an error if a particular text string is found.

        In the Raise an error if output contains string text box, enter one or more strings separated by semicolons. At run time if no MATLAB error occurs, the MATLAB adapter checks the captured console log text for any of the strings. If one of the strings is found, the MATLAB adapter stops processing Mappings and Commands and flags this run as failed.

    • Show MATLAB during execution. Select this option if you do not want to have MATLAB running in the background. By default, this option is selected. When selected, MATLAB is launched and is viewable during the execution of your model.

      If you do not select this option but you have instructed MATLAB to produce a plot, the plot appears during execution.

      Warning: If you run MATLAB in the background on Windows, a MATLAB icon appears on the Windows task bar for each MATLAB adapter currently active in your model. These icons remain visible throughout the execution. If you attempt to close the icons during execution, your job will fail.

    • When to close MATLAB. Select when you want the MATLAB session to close:

      NeverIf you do not want the MATLAB adapter to close the MATLAB session. You must close the session manually.

      If you choose this option, it is recommended that you select Show MATLAB during execution.

      When job completesKeep the MATLAB session open and re-use it during the entire duration of the job. The session closes after the job completes.
      After each executionOpen, use, and close a new MATLAB session every time the MATLAB adapter runs.
      Note: When a MATLAB adapter is configured to close the workbook when the job completes (or never), Optimization Process Composer launches a single MATLAB process and reuses it to evaluate each run of the adapter. This ensures that the MATLAB startup delay is incurred only once. However, if the adapter’s parent adapter is launching subflow runs in parallel, these runs will be forced to use this single process and will be serialized, reducing the potential performance gains from parallel execution. Because MATLAB command evaluations are often very rapid, this serialization process is not likely to cause problems. In a 3DOrchestrate environment, the serialization process can be partially overcome because different subflow runs may be dispatched to different stations.

    • M-Script Error Response. Select how the MATLAB adapter responds to MATLAB errors that occur when Commands run:

      Fail execution on all errors Force the MATLAB adapter to stop processing Mappings and Commands if any MATLAB error occurs while running a Command and to flag this adapter run as failed.
      Ignore errors containing this text Force the MATLAB adapter to check if any MATLAB errors occur while running a Command and, if so, to retrieve the MATLAB error message.

      A text box appears below the list in which you can enter one or more strings separated by semicolons. If the error message contains any one of the entered strings as a substring, the error message is written to the log file, and execution proceeds to the next Mapping or Command. Otherwise, the MATLAB adapter stops processing mappings and commands and flags this run as failed.
      Ignore all errors Force the MATLAB adapter to disregard the MATLAB error report and to assume the Command ran correctly. Execution proceeds to the next Mapping or Command.

    • MATLAB Command. Type the command in the text box if you want newly created instances of the MATLAB adapter to run a version of MATLAB different from the one configured on the 3DOrchestrate Station.

      If you leave the MATLAB Command text box empty, newly created instances of the MATLAB adapter will run the instance of MATLAB specified in the application configured on the 3DOrchestrate Station.

      Note: If you are working in a Windows environment and MATLAB is installed on a network drive, you need to enter the path to the MATLAB executable file in UNC format (for example, \\testmachine\MATLAB\R2007b\bin\matlab.exe).

  5. Click Ok to save your changes and to close the MATLAB Editor.