Send Polyspace Analysis from Desktop to Remote Servers Using Scripts

Instead of running a Polyspace^® analysis on your local desktop, you can send the analysis to a remote cluster. You can use a dedicated cluster for running Polyspace to free up memory on your local desktop.

This topic shows how to use Windows^® or Linux^® scripts to send the analysis to a remote cluster and download the results to your desktop after analysis.

To offload an analysis from the Polyspace user interface, see Send Polyspace Analysis from Desktop to Remote Servers.
For a simple tutorial that walks through all the steps for offloading a Polyspace analysis, see Send Bug Finder Analysis from Desktop to Locally Hosted Server. In the tutorial, the same computer acts as the client and the server.

Client-Server Workflow for Running Analysis

After the initial setup, you can submit a Polyspace analysis from a client desktop to a server. The client-server workflow happens in three steps. All three steps can be performed on the same computer or three different computers.

Client node: You specify Polyspace analysis options and start the analysis on the client desktop. The initial phase of analysis up to compilation runs on the desktop. After compilation, the analysis job is submitted to the server.
You require the Polyspace desktop product, Polyspace Bug Finder™ on the computer that acts as the client node.
Head node: The server consists of a head node and several worker nodes. The head node uses a job scheduler to manage submissions from multiple client desktops. The jobs are then distributed to the worker nodes as they become available.
You require the product MATLAB^® Parallel Server™ on the computer that acts as the head node.
Worker nodes: When a worker becomes available, the job scheduler assigns the analysis to the worker. The Polyspace analysis runs on the worker and the results are downloaded back to the client desktop for review.
You require the product MATLAB Parallel Server on the computers that act as worker nodes. You also require the Polyspace server products, Polyspace Bug Finder Server™ and/or Polyspace Code Prover™ Server to run the analysis.

Note

The versions of Polyspace on the client and worker nodes must match.

A flow diagram showing the client-server workflow for running a Polyspace analysis. On the client side, you can start an analysis in the graphical user interface or at the command line. After compilation, the analysis job is queued on a server. Once the server-side analysis completes, the analysis results are downloaded back to the client-side desktop for review.

Prerequisites

Before you run a remote analysis by using scripts, you must set up communication between a desktop and a remote server. See Install Products for Submitting Polyspace Analysis from Desktops to Remote Server.

Run Remote Analysis

To run a remote analysis, use the following command. Here, [] indicates optional flags.

polyspaceroot\polyspace\bin\polyspace-bug-finder -batch -scheduler NodeHost|MJSName@NodeHost [-wait -download] [options] [-mjs-username name]

where:

polyspaceroot is the installation folder of Polyspace desktop products, for instance, C:\Program Files\Polyspace\R2024b.
NodeHost is the name of the computer that hosts the head node of the MATLAB Parallel Server cluster.
MJSName is the name of the MATLAB Job Scheduler on the head node host.
If you set up communications with a cluster from the Polyspace user interface, you can determine NodeHost and MJSName from the user interface.
Select Tools > Preferences, and then click Settings on the Server Configuration tab to open the Cluster Profile Manager. Select the cluster profile in the left pane, and see the MJSName and Host fields on the Properties tab for MJSName and NodeHost.
If you use the startjobmanager command to start the MATLAB Job Scheduler, MJSName is the argument of the option -name. For details, see Configure Advanced Options for MATLAB Job Scheduler Integration (MATLAB Parallel Server).
options are the analysis options. These options are the same as that of a local analysis. For instance, you can use these options:
- -sources-list-file: Specify a text file with one source file name per line.
- -options-file: Specify a text file with one option per line.
- -results-dir: Specify a download folder for storing results after analysis.
For the full list of options, see Complete List of Polyspace Bug Finder Analysis Engine Options. Alternatively, you can:
- Start an analysis in the user interface and stop after compilation. You can obtain the text files and scripts for running the analysis at the command line. See Configure Polyspace Analysis Options in User Interface and Generate Scripts.
- Enter polyspace-bug-finder -h. The list of available options with a brief description are displayed.
- Place your cursor over each option on the Configuration pane in the Polyspace user interface. Click the More Help button for information on the option syntax and when the option is required.
name is the username required for job submissions using MATLAB Parallel Server. These credentials are required only if you use a security level of 1 or higher for MATLAB Parallel Server submissions. See Set MATLAB Job Scheduler Cluster Security (MATLAB Parallel Server).
For security levels 2 and higher, you have to provide a password in a graphical window at the time of job submission. To avoid this prompt in the future, you can specify that the password be remembered on the computer.

The analysis happens in two parts:

The first part of the analysis up to the end of the compilation phase executes locally on your desktop. After compilation, the software submits the analysis job to the cluster and provides a job ID. You can also read the ID from the file ID.txt, which is stored in the .status subfolder of the results folder. To monitor your analysis, use the polyspace-jobs-manager command with the job ID.
The remaining part of the analysis continues on the cluster. The command waits till the analysis is completed and the results automatically downloaded back to the desktop. If you want to free up the console and download results later using the polyspace-jobs-manager command, omit the options -wait -download.

If the analysis stops after compilation and you have to restart the analysis, to avoid rerunning the compilation phase, use the option -submit-job-from-previous-compilation-results.

Manage Remote Analysis

To manage multiple remote analyses, use the option -batch. For instance:

polyspaceroot\polyspace\bin\polyspace-jobs-manager action -scheduler schedulerName

See also

Run Bug Finder or
                    Code Prover analysis on a remote cluster (-batch)

. Here:

polyspaceroot is your MATLAB installation folder.
schedulerName is one of the following:
- Name of the computer that hosts the head node of your MATLAB Parallel Server cluster (NodeHost).
- Name of the MATLAB Job Scheduler on the head node host (MJSName@NodeHost).
- Name of a MATLAB cluster profile (ClusterProfile).
  For more information about clusters, see Discover Clusters and Use Cluster Profiles (Parallel Computing Toolbox)
If you do not specify a job scheduler, polyspace-job-manager uses the scheduler specified in the Polyspace preferences. To see the scheduler name, select Tools > Preferences. On the Server Configuration tab, see the Job scheduler host name.
action refers to the possible action commands to manage jobs on the scheduler:
- listjobs:
  Generate a list of Polyspace jobs on the scheduler. For each job, the software produces this information:
  - ID — Verification or analysis identifier.
  - AUTHOR — Name of user that submitted job.
  - APPLICATION — Name of Polyspace product, for example, Polyspace Code Prover or Polyspace Bug Finder.
  - LOCAL_RESULTS_DIR — Results folder on local computer, specified through the Tools > Preferences > Server Configuration tab.
  - WORKER — Local computer from which job was submitted.
  - STATUS — Status of job, for example, running and completed.
  - DATE — Date on which job was submitted.
  - LANG — Language of submitted source code.
- download -job ID -results-folder FolderPath:
  Download results of analysis with specified ID to folder specified by FolderPath. If you use the option -wait -download when sending the analysis job to a server, the results are automatically downloaded after analysis. Only when you want to explicitly download results do you need to use the polyspace-jobs-manager command with the download action.
  When the analysis job is queued on the server, the command polyspace-bug-finder returns a job id. In addition, a file ID.txt that is stored in the .status subfolder of the results folder contains the job ID in this format:
```
job_id;server_name:project_name version_number
```
  For instance, 92;localhost:Demo 1.0.
  If you do not use the -results-folder option, the software downloads the result to the folder that you specified when starting analysis, using the -results-dir option.
  After downloading results, use the Polyspace user interface to view the results.
- getlog -job ID:
  Open log for job with specified ID.
- remove -job ID:
  Remove job with specified ID.
- promote -job ID:
  Promote job with specified ID in the queue.
- demote -job ID
  Demote job with specified ID in the queue.

Sample Scripts for Remote Analysis

In Windows, to avoid typing the commands each time, you can save the commands in a batch file. In Linux, you can relaunch the analysis by using a shell script. To create a batch file for running analysis:

Save your analysis options in a file listofoptions.txt. See -options-file.
Create a file launcher.bat in a text editor like Notepad.
In the file, enter these commands:
```
echo off
set POLYSPACE_PATH=polyspaceroot\polyspace\bin
set RESULTS_PATH=C:\Results
set OPTIONS_FILE=C:\Options\listofoptions.txt
"%POLYSPACE_PATH%\polyspace-bug-finder.exe" -batch -scheduler hostname -results-dir "%RESULTS_PATH%" -options-file "%OPTIONS_FILE%"
pause
```
polyspaceroot is the Polyspace installation folder. hostname is the name of the computer that hosts the head node of your MATLAB Parallel Server cluster.
Replace the definitions of these variables in the file:
- POLYSPACE_PATH: Enter the actual location of the .exe file.
- RESULTS_PATH: Enter the path to a folder. The files generated during compilation are saved in the folder.
- OPTIONS_FILE: Enter the path to the file listofoptions.txt.
Double-click launcher.bat to run the analysis.

Tip

If you run a Polyspace analysis, a Windows .bat or Linux .sh file is generated. The file is in the .settings subfolder in your results folder. Instead of writing a script from scratch, you can relaunch the analysis using this file.