Install Products for Submitting Polyspace Analysis from Desktops to Remote Server

You can perform a Polyspace^® analysis locally on your desktop or offload the analysis to one or more dedicated remote servers. This topic shows how to set up the dispatch of Polyspace analysis from desktop clients to remote servers. Once configured, you can send the Polyspace analysis to a remote server and view the downloaded results on your desktop.

Choose Between Local and Remote Analysis

To determine when to use local or remote analysis, use the rules listed in this table.

Type	When to Use
Remote	Source files are large and execution time of analysis is lengthy. Typically, a Code Prover analysis takes significantly longer than a Bug Finder analysis and benefits from running on a dedicated server.
Local	Source files are small and execution time of analysis is short.

Requirements for Remote Analysis

A typical distributed network for running remote analysis consists of these parts:

Client nodes: On the client node, you configure your Polyspace project or scripts, and then submit a job that runs Polyspace.
Head node: The head node distributes the submitted jobs to worker nodes.
Worker node(s): The Polyspace analysis runs on a worker node.

In this workflow, you install the product MATLAB^® Parallel Server™ to manage submissions from multiple clients. An analysis job is created for each submission and placed in a queue. As soon as a worker node is available, the next analysis job from the queue is run on the worker.

This table lists the product requirements for remote analysis.

Location	Requirements	Installation
Client node	Polyspace Bug Finder™ A Polyspace Bug Finder license is sufficient to trigger a Bug Finder or Code Prover analysis on the server and review the downloaded analysis results.	Run the MathWorks installer on the client desktops. Choose a license for Polyspace desktop products. For detailed instructions, see Installation and Licensing.
Head node	MATLAB Parallel Server (earlier called MATLAB Distributed Computing Server)	Run the MathWorks installer on the server(s). Choose a license for MATLAB Parallel Server installation. For detailed instructions, see Install for MATLAB Job Scheduler with Network License Manager (MATLAB Parallel Server).
Worker nodes	MATLAB Parallel Server (earlier called MATLAB Distributed Computing Server) Polyspace Bug Finder Server™ Polyspace Code Prover™ Server (if you choose to run Code Prover)	To install: MATLAB Parallel Server, run the MathWorks installer on the server(s). Choose a license for MATLAB Parallel Server installation. Polyspace Bug Finder Server and/or Polyspace Code Prover Server, run the MathWorks installer. Choose a license for Polyspace server products.

Location

Requirements

Installation

Client node

Polyspace Bug Finder™

A Polyspace Bug Finder license is sufficient to trigger a Bug Finder or Code Prover analysis on the server and review the downloaded analysis results.

Run the MathWorks installer on the client desktops. Choose a license for Polyspace desktop products.

For detailed instructions, see Installation and Licensing.

Head node

MATLAB Parallel Server (earlier called MATLAB Distributed Computing Server)

Run the MathWorks installer on the server(s). Choose a license for MATLAB Parallel Server installation.

For detailed instructions, see Install for MATLAB Job Scheduler with Network License Manager (MATLAB Parallel Server).

Worker nodes

MATLAB Parallel Server (earlier called MATLAB Distributed Computing Server)
Polyspace Bug Finder Server™
Polyspace Code Prover™ Server (if you choose to run Code Prover)

To install:

MATLAB Parallel Server, run the MathWorks installer on the server(s). Choose a license for MATLAB Parallel Server installation.
Polyspace Bug Finder Server and/or Polyspace Code Prover Server, run the MathWorks installer. Choose a license for Polyspace server products.

In the simplest remote analysis configuration, the same computer can serve as the head node and worker node.

Selecting Number of Workers

To select the number of worker nodes to allocate, consider the following:

Polyspace does not distribute a single analysis over multiple workers and executes one analysis entirely on one worker node. Do not expect an individual analysis to speed up if you use multiple workers (unless you run a file by file verification in Code Prover).
Only if the head node processes more than one analysis job at the same time can you benefit from multiple workers. This scenario is likely if multiple clients submit analysis jobs within a short time window.
Each worker node must have a license available for executing the Polyspace analysis. Otherwise, a worker node might wait for a license to be released and you might not benefit from multiple workers.
Make sure that you do not allocate more workers than the number of licenses available.

Using MATLAB Parallel Server for distributing Polyspace jobs is different from other uses of MATLAB Parallel Server where a single job can be parallelized over multiple workers.

Configure and Start Server

On the computers that act as the worker nodes of the server, you install MATLAB Parallel Server and the Polyspace server products in two separate folders. The MATLAB Parallel Server installation must know where the Polyspace server products are located so that it can route the Polyspace analysis. To link the two installations, specify the paths to the root folder of the Polyspace server products in your MATLAB Parallel Server installations.

Then configure and start MATLAB Parallel Server (the mjs service) on all computers that act as the head node and worker nodes.

Configure `mjs` Service Settings

Before starting services, you must configure the mjs service settings.

Navigate to matlabroot\toolbox\parallel\bin, where matlabroot is the MATLAB Parallel Server installation folder, for instance, C:\Program Files\MATLAB\R2024b.
Modify the file mjs_def.bat (Windows^®) or mjs_def.sh (Linux^®). To edit and save the file, you have to open your editor in administrator mode.
Read the instructions in the file and uncomment the lines as needed. At a minimum, you might have to uncomment these lines:
- Hostname:
```
REM set HOSTNAME=%strHostname%.%strDomain%
```
  in Windows or
```
#HOSTNAME=`hostname -f`
```
  in Linux. Explicitly specify your computer host name.
- Security level:
```
REM set SECURITY_LEVEL=
```
  in Windows or
```
#SECURITY_LEVEL=""
```
  in Linux. Explicitly specify a security level.
  If you do this step later, make sure to first stop the mjs services with:
```
mjs stop -clean
```
  Then make the modifications and later restart the services with:
```
mjs restart -clean
```
Otherwise, you might see an error later when starting the job scheduler.

Specify Polyspace Installation Paths

When you offload an analysis using a Polyspace desktop product installation, the server must run the analysis using a Polyspace server product installation from the same release. For instance, if you offload an analysis from an R2024b desktop product, the analysis must run using the R2024b server product. To ensure that the correct Polyspace server product is used, you must specify the installation paths of the Polyspace server products in your MATLAB Parallel Server installations.

To specify the Polyspace installation paths:

Navigate to matlabroot\toolbox\parallel\bin\. Here, matlabroot is the MATLAB installation folder, for instance, C:\Program Files\MATLAB\R2024b.
Uncomment and modify the following line in the file mjs_polyspace.conf. To edit and save the file, you have to open your editor in administrator mode.
```
POLYSPACE_SERVER_ROOT=polyspaceserverroot
```
Here, polyspaceserverroot is the installation path of the server products, for instance:
```
C:\Program Files\Polyspace Server\R2024b
```

If you use multiple releases of Polyspace desktop and server products, the MATLAB Parallel Server release must be the later one. For instance, if you offload analysis jobs using both R2019a and R2019b Polyspace desktop and server products, the MATLAB Parallel Server installation must be an R2019b one. See also Submit Analysis Jobs from Multiple Releases of Polyspace.

Start `mjs` Service and Assign as Head Node or Worker Node

To configure a server with multiple workers, start the service that runs a job scheduler (the mjs service) on the computer that acts as the head node and all computers that act as worker nodes. In the simplest configuration, the same computer can act as the head node and a worker node.

To set up a cluster with one head node and several workers, on the computer that acts as the head node:

Open the Admin Center window. Navigate to matlabroot\toolbox\parallel\bin\ and execute the file admincenter.bat (Windows) or admincenter.sh (Linux). Here, matlabroot is the MATLAB installation folder, for instance, C:\Program Files\MATLAB\R2024b.
In the Hosts section, add the host names of all computers that you want to use as head and worker nodes of the cluster. Start the mjs service.
The service uses the settings specified in the file mjs_def.bat (Windows) or mjs_def.sh (Linux).
Right-click each host. Select either Start MJS (head node) or Start Workers (worker nodes).
The hosts appear in the MATLAB Job Scheduler or Workers section. In each section, select the host and click Start to start the MATLAB Job Scheduler or the workers.

Selecting a computer as host starts the mjs service on that computer. You must have permission to start services on other computers in the network. For instance, on Windows, you must be in the Administrators group for other computers where you want to start the mjs service. Otherwise, you have to start the mjs services individually on each computer that acts as a worker.

For more details and command-line workflows, see:

Install for MATLAB Job Scheduler with Network License Manager (MATLAB Parallel Server)
mjs (MATLAB Parallel Server) command for starting services, and nodestatus (MATLAB Parallel Server) command for checking status of nodes (for instance, to check if the node can handle submissions from multiple releases).

For an example of command-line workflows to start the mjs services, see Send Code Prover Analysis from Desktop to Locally Hosted Server.

Configure Client

Configure the client node so that it can communicate with the computer that serves as the head node of the MATLAB Parallel Server cluster. For scheduling jobs, you can use the job scheduler that comes with MATLAB Parallel Server (MATLAB Job Scheduler). If you were already using a third-party scheduler such as HPC Server or PBS Professional, you can continue to use that scheduler.

Use MATLAB Job Scheduler

Configure the client node in the user interface of the Polyspace desktop products:

Select Tools > Preferences.
Click the Server Configuration tab. Under MATLAB Parallel Server cluster configuration:
1. In the Job scheduler host name field, specify the computer for the head node of the cluster. This computer hosts the MATLAB job scheduler.
  If the port used on the computer hosting the MATLAB job scheduler is different from 27350, enter the port name explicitly with the notation hostName:portNumber.
2. In the Parallel computing username field, define a default user name for job submissions. The user name is useful if you specify a security level of 1 or higher for job submissions using MATLAB Parallel Server.
3. Due to the network setting, the job scheduler may be unable to connect back to your local computer. If so, enter the IP address of the client computer in the Localhost IP address field.

Create a Cluster Profile for Job Scheduling

Cluster profiles let you define certain properties for your cluster, such as number of threads per worker, timeouts, callbacks, and so on. For more information on cluster profiles, see Discover Clusters and Use Cluster Profiles (Parallel Computing Toolbox).

For instance, instead of the job scheduler provided with MATLAB Parallel Server, you can use a third party scheduler such as HPC Server or PBS Professional. You can create a cluster profile to use the third-party scheduler. You can also create a cluster profile that uses the MATLAB job scheduler but with nondefault properties. For instance, if you start the job manager with a certificate using the -certificate flag, you can create a cluster profile that uses this job manager.

To create and use a cluster profile:

In the Polyspace user interface, select Tools > Preferences.
In the Polyspace Preferences window, click the Settings button beside Cluster Profile Manager.
In the Cluster Profile Manager window, click Add Cluster Profile. Select a third-party scheduler. You see a default cluster profile using this scheduler.
Specify the properties of the cluster profile.
1. Click Edit. Modify the default properties as needed.
2. Click Validate. At a minimum, the cluster connection test and the job test must complete.
In the Polyspace Preferences window, for Job scheduler host name, specify the cluster profile name that you just created (for instance, HPCServerProfile1 in the example above).

Offload Polyspace Analysis from Desktop to Server

Once the configuration is over, you can offload an analysis from a Polyspace desktop product installation to a remote server. You can do one of the following:

Start a remote analysis from the user interface of the Polyspace desktop products.
See Send Polyspace Analysis from Desktop to Remote Servers.
Start a remote analysis with Windows or Linux scripts.
See Send Polyspace Analysis from Desktop to Remote Servers Using Scripts. In the simplest configuration, the same computer can be used as a client and server. For a simple tutorial that uses this configuration and walks through all the steps for offloading a Polyspace analysis, see Send Code Prover Analysis from Desktop to Locally Hosted Server.
Start a remote analysis with MATLAB scripts.
See Run Analysis on Server.

Submit Analysis Jobs from Multiple Releases of Polyspace

If you upgrade to a newer release of Polyspace products, you can continue to submit jobs from both the older and the new releases. For instance, suppose that you were using the R2019a release of Polyspace products and MATLAB Parallel Server. When you upgrade to the R2019b releases of the two sets of products, you can continue to submit jobs from the older releases.

The setup for handling multiple releases of Polyspace, for instance, R2019a and R2019b, looks like this:

To support submissions from multiple releases with a single MATLAB Parallel Server cluster, you have to link the various installations of Polyspace products and MATLAB Parallel Server. Of the links shown in the preceding figure, the links numbered 1, 2 and 5 are part of a regular server-client installation using all products from the same release. To create all the links, do these steps:

In the R2019b installation of the Polyspace desktop products, open the user interface and select Tools > Preferences. Specify the computer that acts as the head node of the R2019b MATLAB Parallel Server cluster, as described earlier.
If you are able to submit jobs from R2019b Polyspace desktop products, you have already done this step.
In the R2019b installation of the MATLAB Parallel Server products, edit the mjs_polyspace.conf file to point to the R2019b installation of the Polyspace Server products, as described earlier.
If your R2019b installation of MATLAB Parallel Server can run an analysis using R2019b Polyspace Server products, you have already done this step.
In the R2019a installation of the Polyspace desktop products, open the user interface and select Tools > Preferences. Specify the computer that acts as the head node of the R2019b MATLAB Parallel Server cluster.
If you install the R2019b version of MATLAB Parallel Server on the same computer as the R2019a version, you have already done this step. Otherwise, this step might be new in the multi-release workflow.
In the R2019b installation of the MATLAB Parallel Server products, edit the file mjs_def.bat or mjs_def.sh (located in matlabroot\toolbox\parallel\bin\) to refer to the earlier release. Find the line with MJS_ADDITIONAL_MATLABROOTS and edit it as follows. To edit and save the file, you have to open your editor in administrator mode.
```
set MJS_ADDITIONAL_MATLABROOTS=othermatlabroot
```
Here, othermatlabroot is the installation path of the MATLAB Parallel Server installation from the earlier release, for instance:
```
C:\Program Files\MATLAB\R2019a
```
This step is new in the multi-release workflow.
In the R2019a installation of the MATLAB Parallel Server products, edit the mjs_polyspace.conf file to point to the R2019a installation of the Polyspace Server products, as described earlier.
If your R2019a installation of MATLAB Parallel Server can run an analysis using R2019a Polyspace Server products, you have already done this step.

Note

The lowest release of MATLAB Parallel Server that can be mixed with the current release using this workflow is R2016a.
For releases from R2016a to R2018b,.the server side configuration is different from releases R2019a and later. Consult the documentation for older releases for step 5 above. However, if you are already submitting jobs from a pre-R2019a Polyspace installation using a pre-R2019a MATLAB Parallel Server installation, you have presumably done this step.