Parallel Computing Toolbox 4.3
Perform parallel computations on multicore computers and computer clusters
Parallel Computing Toolbox lets you solve computationally and data-intensive problems using MATLAB and Simulink on multicore and multiprocessor computers. Parallel processing constructs such as parallel for-loops, distributed arrays, parallel numerical algorithms, and message-passing functions let you implement task- and data-parallel algorithms in MATLAB at a high level without programming for specific hardware and network architectures. As a result, converting serial MATLAB applications to parallel MATLAB applications requires few code modifications and no programming in a low-level language. You can run your applications interactively or offline, in batch environments.

Key Features

Support for data-parallel and task-parallel application development Ability to annotate code segments with parfor (parallel for-loops) and spmd (single program multiple data) for implementing task- and data-parallel algorithms High-level constructs such as distributed arrays, parallel algorithms, and message-passing functions for processing large data sets on multiple processors Ability to run eight workers locally on a multicore desktop Integration with MATLAB Distributed Computing Server for cluster- and grid-based applications that use any scheduler or any number of workers Interactive and batch execution modes
Developing parallel applications with Parallel Computing Toolbox. The toolbox enables application prototyping on the desktop with up to eight local workers (left), and, with MATLAB Distributed Computing Server (right), applications can be scaled to multiple computers on a cluster or a grid or cloud computing service.
You can use the toolbox to execute applications on a single multicore or multiprocessor desktop. Without changing the code, you can run the same application on a computer cluster or a grid or cloud computing service (using MATLAB Distributed Computing Server). Parallel MATLAB applications can be distributed as executables or shared libraries (built using MATLAB Compiler) that can access MATLAB Distributed Computing Server. Programming Parallel Applications in MATLAB Parallel Computing Toolbox provides several high-level programming constructs that let you convert your serial MATLAB code to run in parallel on several workers (MATLAB computational engines that run independently of MATLAB clients). Constructs such as parallel for-loops (parfor) and distributed arrays simplify parallel code development by abstracting away the complexity of managing coordination and distribution of computations and data between a MATLAB client and workers, as well as between workers. These constructs function even in the absence of workers, letting you maintain a single version of your code for both serial and parallel execution. You can run an application that uses up to eight workers on your multicore desktop. Using MATLAB Distributed Computing Server, you can run the same application without modification on large resources such as computer clusters or grid and cloud computing services. Taking Advantage of Built-in Parallel Computing Support in MathWorks Products Key functions in a growing number of products in the MATLAB and Simulink product families, such as Statistics Toolbox and Simulink Design Optimization, provide built-in support for parallel computing. In the presence of Parallel Computing Toolbox, these functions exploit parallel computing resources by distributing computations across available workers, enabling you to take advantage of parallel computing resources without additional programming effort. Implementing Task-Parallel Algorithms You can parallelize Monte Carlo simulations and other coarse-grained or embarrassingly parallel problems by organizing them into independent tasks (units of work). Parallel for-loops in the toolbox offer one way to distribute tasks across multiple MATLAB workers. Using these loops, you can automatically distribute independent loop iterations to multiple MATLAB workers. The parfor construct manages data and code transfer between the MATLAB client session and the workers. It automatically detects the presence of workers and reverts to serial behavior if none are present.

Using parallel for-loops for a task-parallel application. You can use parallel for-loops in MATLAB scripts and functions and execute them both interactively and offline.
You can also explicitly program tasks either as MATLAB functions or as MATLAB scripts. You execute the tasks, when specified as functions, by manipulating task and job objects in the toolbox or, when specified as scripts, by using the batch function. Implementing Data-Parallel Algorithms For MATLAB algorithms that require large data set processing, Parallel Computing Toolbox provides distributed arrays and parallel functions that can operate on these arrays. Distributed arrays let you process significantly larger data sets than you could in a single MATLAB session by distributing data across multiple workers and using parallel functions to perform operations on the distributed data. The toolbox also provides functions for moving distributed data to and from MAT-files. You can work with distributed arrays interactively from your MATLAB session as you would with MATLAB arrays. Working with distributed arrays and their associated parallel functions does not require knowledge of low-level programming tools, such as MPI. The toolbox provides more than 150 parallel functions for operating on distributed arrays, including linear algebra routines based on ScaLAPACK. You can use the familiar operators for arrays in MATLAB to perform indexing, matrix multiplication, and transforms directly on distributed arrays.
Programming with distributed arrays. Distributed arrays and parallel algorithms let you create data-parallel MATLAB programs with minimal changes to your code and without programming in MPI.
The toolbox also provides the spmd (single program multiple data) construct, which you can use to designate sections of your code to run concurrently across workers participating in a parallel computation. During program execution, spmd automatically transfers data and code used within its body to the workers and, once the execution is complete, brings results back to the MATLAB client session. For explicit, fine-grained control over your parallelization scheme, which also requires explicitly managing interworker coordination, Parallel Computing Toolbox functions provide access to message-passing routines based on the MPI standard (MPICH2), including functions for send, receive, broadcast, barrier, and probe operations. Working in an Interactive Parallel Environment Parallel Computing Toolbox extends the MATLAB interactive environment, letting you prototype and develop task- and data- parallel applications in your familiar environment. The matlabpool command allocates a set of dedicated computational resources for you, connecting your MATLAB session to a pool of MATLAB workers that can run either locally on your desktop or on a computer cluster. The command sets up an interactive parallel execution environment in which you can execute your parallel MATLAB code from the command prompt and retrieve results immediately as computations finish. In this environment, parallel for-loops and distributed arrays automatically detect the presence of workers and distribute computations and data between your MATLAB session and the workers. Commands can be collected into MATLAB functions or scripts and submitted for offline execution. Working in Batch Environments Parallel Computing Toolbox lets you use batch environments for offline execution, enabling you to free your MATLAB client session for other activities while you execute large MATLAB and Simulink applications. You can also shut down your MATLAB client session while your application executes and retrieve results later. The batch function lets you execute MATLAB scripts offline. It provides a mechanism for data transfer between MATLAB client and worker workspaces, which frees you from explicitly managing data in multiple workspaces.

The toolbox also provides job and task objects. These objects provide a lower-level but more general mechanism to execute parallel MATLAB applications in batch environments. Both the batch function and the job and task objects can be used to offload the execution of serial MATLAB programs from a desktop MATLAB session to a worker.
Executing MATLAB scripts offline. With the Configurations Manager, you can direct program execution to your workstation using eight local workers or to a cluster using any scheduler and any number of workers.
Scaling Up to Clusters, Grids, and Clouds Using MATLAB Distributed Computing Server Parallel Computing Toolbox provides the ability to use up to eight local workers on a multicore or multiprocessor computer using a single toolbox license. When used with MATLAB Distributed Computing Server, you can run an application using any number of workers on large-scale resources such as computer clusters or grid and cloud computing services. The server also supports both interactive and batch workflows. Using MATLAB Compiler, you can build MATLAB applications that use toolbox functions into standalone executables or shared software components and distribute them royalty-free. These executables and libraries can connect to MATLAB Distributed Computing Server workers and perform MATLAB computations on large computing resources.
Running a gene regulation model on a cluster using MATLAB Distributed Computing Server. The server enables applications developed using Parallel Computing Toolbox to harness computer clusters for large problems. Compiled parallel MATLAB applications can also use the server.
Integrating Products into Your Computing Environment MATLAB Distributed Computing Server provides a job manager and directly supports several third-party schedulers such as Platform LSF, Microsoft Windows HPC Server, Altair PBS Pro, and TORQUE. Using the Configurations Manager in the toolbox, you can maintain named settings such as scheduler type, path settings, and cluster usage policies. Switching between clusters or schedulers typically requires changing the configuration name only. MATLAB Distributed Computing Server dynamically enables the required product licenses when an application runs on the cluster, based on the users profile. As a result, administrators need to manage only the server license on the cluster rather than separate toolbox and blockset licenses for every cluster user.

Resources

Product Details, Demos, and System Requirements www.mathworks.com/products/parallel-computing Trial Software www.mathworks.com/trialrequest Sales www.mathworks.com/contactsales Technical Support www.mathworks.com/support Online User Community www.mathworks.com/matlabcentral Training Services www.mathworks.com/training Third-Party Products and Services www.mathworks.com/connections Worldwide Contacts www.mathworks.com/contact
2010 The MathWorks, Inc. MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be trademarks or registered trademarks of their respective holders.

You use the function matlabpool to reserve a number of MATLAB labs (workers) for executing a subsequent spmd statement or parfor-loop. Depending on your scheduler, the labs might be running remotely on a cluster, or they might run locally on your MATLAB client machine. You identify a scheduler and cluster by selecting a parallel configuration. For a description of how to manage and use configurations, see Programming with User Configurations on page 6-16. To begin the examples of this section, allocate local MATLAB labs for the evaluation of your spmd statement:
This command starts the number of MATLAB worker sessions defined by the default parallel configuration. If the local configuration is your default and does not specify the number of workers, this starts one worker per core (maximum of eight) on your local MATLAB client machine. If you do not want to use default settings, you can specify in the matlabpool statement which configuration or how many labs to use. For example, to use only three labs with your default configuration, type:

matlabpool 3

To use a different configuration, type:

matlabpool MyConfigName

To inquire whether you currently have a MATLAB pool open, type:

matlabpool size

This command returns a value indicating the number of labs in the current pool. If the command returns 0, there is currently no pool open.
Note If there is no MATLAB pool open, an spmd statement runs locally in the MATLAB client without any parallel execution, provided you have Parallel Computing Toolbox software installed. In other words, it runs in your client session as though it were a single lab. When you are finished using a MATLAB pool, close it with the command:
Defining an spmd Statement
The general form of an spmd statement is:
spmd <statements> end
The block of code represented by <statements> executes in parallel simultaneously on all labs in the MATLAB pool. If you want to limit the execution to only a portion of these labs, specify exactly how many labs to run on:
spmd (n) <statements> end
This statement requires that n labs run the spmd code. n must be less than or equal to the number of labs in the open MATLAB pool. If the pool is large enough, but n labs are not available, the statement waits until enough labs are available. If n is 0, the spmd statement uses no labs, and runs locally on the client, the same as if there were not a pool currently open. You can specify a range for the number of labs:
spmd (m, n) <statements> end
In this case, the spmd statement requires a minimum of m labs, and it uses a maximum of n labs.
If it is important to control the number of labs that execute your spmd statement, set the exact number in the configuration or with the spmd statement, rather than using a range. For example, create a random matrix on three labs:

MATLAB Worker

MATLAB Distributed Computing Server

MATLAB Client

Parallel Computing Toolbox

Scheduler or Job Manager

Basic Parallel Computing Configuration
Toolbox and Server Components
Job Managers, Workers, and Clients on page 6-3 Local Scheduler on page 6-5 Third-Party Schedulers on page 6-5 Components on Mixed Platforms or Heterogeneous Clusters on page 6-7 mdce Service on page 6-7 Components Represented in the Client on page 6-7
Job Managers, Workers, and Clients
The job manager can be run on any machine on the network. The job manager runs jobs in the order in which they are submitted, unless any jobs in its queue are promoted, demoted, canceled, or destroyed. Each worker is given a task from the running job by the job manager, executes the task, returns the result to the job manager, and then is given another task. When all tasks for a running job have been assigned to workers, the job manager starts running the next job with the next available worker.
A MATLAB Distributed Computing Server software setup usually includes many workers that can all execute tasks simultaneously, speeding up execution of large MATLAB jobs. It is generally not important which worker executes a specific task. The workers evaluate tasks one at a time, returning the results to the job manager. The job manager then returns the results of all the tasks in the job to the client session. Note For testing your application locally or other purposes, you can configure a single computer as client, worker, and job manager. You can also have more than one worker session or more than one job manager session on a machine.

Task Job Results

Worker

Client

All Results
Task Results Task Results
Interactions of Parallel Computing Sessions
A large network might include several job managers as well as several client sessions. Any client session can create, run, and access jobs on any job manager, but a worker session is registered with and dedicated to only one job manager at a time. The following figure shows a configuration with multiple job managers.
Client Client Scheduler or Job Manager
Configuration with Multiple Clients and Job Managers

in the listing and select Export.)
3 In the Export Configuration dialog box, specify a location and name for the
file. The default file name is the same as the name of the configuration it contains, with a.mat extension appended; these do not need to be the same, so you can alter the names if you want to.
Configurations saved in this way can then be imported by other MATLAB software users:
1 In the Configuration Manager, click File > Import. 2 In the Import Configuration dialog box, browse to find the.mat file for the
configuration you want to import. Select the file and click Import. The imported configuration appears in your Configurations Manager list. Note that the list contains the configuration name, which is not necessarily the file name. If you already have a configuration with the same name as the one you are importing, the imported configuration gets an extension added to its name so you can distinguish it. You can also import configurations programmatically with the
importParallelConfig function. For details and examples, see the importParallelConfig reference page.
Exporting Configurations for MATLAB Compiler
You can use an exported configuration with MATLAB Compiler to identify cluster setup information for running compiled applications on a cluster. For example, the setmcruserdata function can use the exported configuration file name to set the value for the key ParallelConfigurationFile. For more information and examples of deploying parallel applications, see Deploying Applications Created Using Parallel Computing Toolbox in the MATLAB Compiler documentation. A compiled application has the same default configuration and the same list of alternative configurations that the compiling user had when the application was compiled. This means that in many cases the configuration file is not needed, as might be the case when using the local configuration for local workers. If an exported file is used, the configuration in the file becomes the default, and overwrites any existing configuration with the same name. The other alternative configurations are still available.
Validating Configurations
The Configurations Manager includes a tool for validating configurations.
To validate a configuration, follow these steps:
1 Open the Configurations Manager by selecting on the desktop
Parallel > Manage Configurations.
2 In the Configurations Manager, click the name of the configuration you
want to test in the list of those available. Note that you can highlight a configuration this way without changing the selected default configuration. So a configuration selected for validation does not need to be your default configuration.
3 Click Start Validation.

If using mpiexec

No Results or Failed Job

Task Errors

If your job returned no results (i.e., getAllOutputArguments(job) returns an empty cell array), it is probable that the job failed and some of its tasks have their ErrorMessage and ErrorIdentifier properties set. You can use the following code to identify tasks with error messages:
errmsgs = get(yourjob.Tasks, {'ErrorMessage'}); nonempty = ~cellfun(@isempty, errmsgs); celldisp(errmsgs(nonempty));
This code displays the nonempty error messages of the tasks found in the job object yourjob.

Debug Logs

If you are using a supported third-party scheduler, you can use the getDebugLog function to read the debug log from the scheduler for a particular job or task. For example, find the failed job on your LSF scheduler, and read its debug log.
sched = findResource('scheduler', 'type', 'lsf') failedjob = findJob(sched, 'State', 'failed'); message = getDebugLog(sched, failedjob(1))
Connection Problems Between the Client and Job Manager
For testing connectivity between the client machine and the machines of your compute cluster, you can use Admin Center. For more information about Admin Center, including how to start it and how to test connectivity, see Admin Center in the MATLAB Distributed Computing Server documentation. Detailed instructions for other methods of diagnosing connection problems between the client and job manager can be found in some of the Bug Reports listed on the MathWorks Web site. The following sections can help you identify the general nature of some connection problems.
Client Cannot See the Job Manager
If you cannot locate your job manager with
findResource('scheduler','type','jobmanager')
the most likely reasons for this failure are The client cannot contact the job manager host via multicast. Try to fully specify where to look for the job manager by using the LookupURL property in your call to findResource:
findResource('scheduler','type','jobmanager',. 'LookupURL','JobMgrHostName')
The job manager is currently not running. Firewalls do not allow traffic from the client to the job manager. The client and the job manager are not running the same version of the software. The client and the job manager cannot resolve each others short hostnames.

Recovering Objects

A client session of Parallel Computing Toolbox software can access any of the objects in MATLAB Distributed Computing Server software, whether the current client session or another client session created these objects. You create job manager and worker objects in the client session by using the findResource function. These client objects refer to sessions running in the engine.
jm = findResource('scheduler','type','jobmanager',. 'Name','Job_Mgr_123','LookupURL','JobMgrHost')
If your network supports multicast, you can find all available job managers by omitting any specific property information.
jm_set = findResource('scheduler','type','jobmanager')
The array jm_set contains all the job managers accessible from the client session. You can index through this array to determine which job manager is of interest to you.

jm = jm_set(2)

When you have access to the job manager by the object jm, you can create objects that reference all those objects contained in that job manager. All the jobs contained in the job manager are accessible in its Jobs property, which is an array of job objects.
all_jobs = get(jm,'Jobs')
You can index through the array all_jobs to locate a specific job. Alternatively, you can use the findJob function to search in a job manager for particular job identified by any of its properties, such as its State.
finished_jobs = findJob(jm,'State','finished')
This command returns an array of job objects that reference all finished jobs on the job manager jm.
Resetting Callback Properties
When restarting a client session, you lose the settings of any callback properties (for example, the FinishedFcn property) on jobs or tasks. These properties are commonly used to get notifications in the client session of state changes in their objects. When you create objects in a new client session that reference existing jobs or tasks, you must reset these callback properties if you intend to use them.
Permanently Removing Objects
Jobs in the job manager continue to exist even after they are finished, and after the job manager is stopped and restarted. The ways to permanently remove jobs from the job manager are explained in the following sections: Destroying Selected Objects on page 8-19 Starting a Job Manager from a Clean State on page 8-20 Destroying Selected Objects. From the command line in the MATLAB client session, you can call the destroy function for any job or task object. If you destroy a job, you destroy all tasks contained in that job. For example, find and destroy all finished jobs in your job manager that belong to the user joep.

for ii = 1:props.NumberOfTasks submit task to scheduler %Per-task settings: data_array(1,ii) =. parse string returned from scheduler data_array(2,ii) =. save ID returned from scheduler etc end setJobSchedulerData(scheduler, job, data_array)
Defining Scheduler Commands in User Functions
With the scheduler data (such as the schedulers ID for the job or task) now stored on disk along with the rest of the job data, you can write code to control what the scheduler should do when that particular job or task is canceled or destroyed. For example, you might create these four functions: myCancelJob.m myDestroyJob.m myCancelTask.m myDestroyTask.m Your myCancelJob.m function defines what you want to communicate to your scheduler in the event that you use the cancel function on your job from the MATLAB client. The toolbox takes care of the job state and any data management with the job data on disk, so your myCancelJob.m function needs to deal only with the part of the job currently running or queued with the scheduler. The toolbox function that retrieves scheduler data from the job is getJobSchedulerData. Your cancel function might be structured something like this:
function myCancelTask(sched, job) array_data = getJobSchedulerData(sched, job)
job_id = array_data(.) % Extract the ID from the data, depending on how % it was stored in the submit function above. command to scheduler canceling job job_id
In a similar way, you can define what do to for destroying a job, and what to do for canceling and destroying tasks.
Destroying or Canceling a Running Job
After your functions are written, you set the appropriate properties of the scheduler object with handles to your functions. The corresponding scheduler properties are: CancelJobFcn DestroyJobFcn CancelTaskFcn DestroyTaskFcn You can set the properties in the Configurations Manager for your scheduler, or on the command line:
schdlr = findResource(scheduler, 'type', 'generic'); % set required properties set(schdlr, 'CancelJobFcn', @myCancelJob) set(schdlr, 'DestroyJobFcn', @myDestroyJob) set(schdlr, 'CancelTaskFcn', @myCancelTask) set(schdlr, 'DestroyTaskFcn', @myDestroyTask)
Continue with job creation and submission as usual.

Description

behavior of the connection. The accepted parameters are: 'IdentityFilename' A string containing the full path to the identity file to use when connecting to a remote host. If 'IdentityFilename' is not specified, you are prompted for a password when establishing the connection. 'IdentityFileHasPassphrase' A boolean indicating whether or not the identity file requires a passphrase. If true, you are prompted for a password when establishing a connection. If an identity file is not supplied, this property is ignored. This value is false by default. For more information and detailed examples, see the integration scripts provided in matlabroot/toolbox/distcomp/examples/integration. For example, the scripts for PBS in a nonshared file system are in
matlabroot/toolbox/distcomp/examples/integration/pbs/nonshared

Method Name

connect
RemoteClusterAccess.connect(clusterHost)
establishes a connection to the specified host using the user credential options supplied in the constructor. File mirroring is not supported.
RemoteClusterAccess.connect(clusterHost, remoteDataLocation) establishes a connection to the
specified host using the user credential options supplied in the constructor. remoteDataLocation identifies a folder on the clusterHost that is used for file mirroring. The user credentials supplied in the constructor must have write access to this folder.
disconnect RemoteClusterAccess.disconnect() disconnects the existing remote connection. The connect method must
have already been called.
doLastMirrorForJob RemoteClusterAccess.doLastMirrorForJob(job)
performs a final copy of changed files from the remote DataLocation to the local DataLocation for the supplied job. Any running mirrors for the job also stop and the job files are removed from the remote DataLocation. The startMirrorForJob or resumeMirrorForJob method must have already been called.
getRemoteJobLocation RemoteClusterAccess.getRemoteJobLocation(jobID, remoteOS) returns the full path to the remote job location for the supplied jobID. Valid values for remoteOS are 'pc' and 'unix'. RemoteClusterAccess.isJobUsingConnection(jobID)

isJobUsingConnection

returns true if the job is currently being mirrored.

r = getAllOutputArguments(j) % Get results into a cell array r{1} % Display result
diary | findJob | load | wait

cancel

Cancel job or task

cancel(t) cancel(j)

Pending or running task to cancel. Pending, running, or queued job to cancel.
cancel(t) stops the task object, t, that is currently in the pending or running state. The tasks State property is set to finished, and no output arguments are returned. An error message stating that the task was canceled is placed in the task objects ErrorMessage property, and the worker session running the task is restarted. cancel(j) stops the job object, j, that is pending, queued, or running. The jobs State property is set to finished, and a cancel is executed on all tasks in the job that are not in the finished state. A job object that has been canceled cannot be started again.
If the job is running in a job manager, any worker sessions that are evaluating tasks belonging to the job object will be restarted.
Cancel a task. Note afterward the tasks State, ErrorMessage, and OutputArguments properties.
job1 = createJob(jm); t = createTask(job1, @rand, 1, {3,3}); cancel(t) get(t) ID: 1 Function: @rand NumberOfOutputArguments: 1 InputArguments: {[3] CaptureCommandWindowOutput: 0 CommandWindowOutput: '' [3]} OutputArguments: {1x0 cell}
State: 'finished' ErrorMessage: 'Task cancelled by user' ErrorIdentifier: 'distcomp:task:Cancelled' Timeout: Inf CreateTime: 'Fri Oct 22 11:38:39 EDT 2004' StartTime: 'Fri Oct 22 11:38:46 EDT 2004' FinishTime: 'Fri Oct 22 11:38:46 EDT 2004' Worker: [] Parent: [1x1 distcomp.job] UserData: [] RunningFcn: [] FinishedFcn: []

destroy | submit

changePassword
Prompt user to change job manager password
changePassword(jm) changePassword(jm, username)

jm username

Job manager object on which password is changing User whose password is changed
changePassword(jm) prompts the user to change the password for the current user. The users current password must be entered as well as the new password. changePassword(jm, username) prompts the job managers admin user to change the password for the specified user. The admin users password must be entered as well as the users new password. This enables the admin user to reset a password if the user has forgotten it.
For more information on job manager security, see Setting Job Manager Security.

clearLocalPassword

Purpose Syntax Arguments Description Tips
Remove objects from MATLAB workspace

clear obj

An object or an array of objects.
clear obj removes obj from the MATLAB workspace.
If obj references an object in the job manager, it is cleared from the workspace, but it remains in the job manager. You can restore obj to the workspace with the findResource, findJob, or findTask function; or with the Jobs or Tasks property. This example creates two job objects on the job manager jm. The variables for these job objects in the MATLAB workspace are job1 and job2. job1 is copied to a new variable, job1copy; then job1 and job2 are cleared from the MATLAB workspace. The job objects are then restored to the workspace from the job objects Jobs property as j1 and j2, and the first job in the job manager is shown to be identical to job1copy, while the second job is not.

y = dfeval(., 'P1',V1,'P2',V2,.) accepts additional
arguments for configuring different properties associated with the job. Valid properties and property values are Job object property value pairs, specified as name/value pairs or structures. (Properties of other object types, such as scheduler, task, or worker objects are not permitted. Use a configuration to set scheduler and task properties.) 'JobManager','JobManagerName'. This specifies the job manager on which to run the job. If you do not use this property to specify a job manager, the default is to run the job on the first job manager returned by findResource. 'LookupURL','host:port'. This makes a unicast call to the job manager lookup service at the specified host and port. The job managers available for this job are those accessible from this lookup service. For more detail, see the description of this option on the findResource reference page. 'StopOnError',true|{false}. You may also set the value to logical 1 (true) or 0 (false). If true (1), any error that occurs during execution in the cluster will cause the job to stop executing. The default value is 0 (false), which means that any errors that occur will produce a warning but will not stop function execution.
[y1,.,ym] = dfeval(F, x1,.,xn,. 'configuration', 'ConfigurationName',.) evaluates the function F in a
cluster by using all the properties defined in the configuration
ConfigurationName. The configuration settings are used to find and
initialize a scheduler, create a job, and create tasks. For details about defining and applying configurations, see Programming with User Configurations on page 6-16. Note that configurations enable you to use dfeval with any type of scheduler.
Note that dfeval runs synchronously (sync); that is, it does not return the MATLAB prompt until the job is completed. For further discussion of the usage of dfeval, see Evaluating Functions Synchronously on page 7-2.
Create three tasks that return a 1-by-1, a 2-by-2, and a 3-by-3 random matrix.
y = dfeval(@rand,{3}) y = [ 0.9501] [2x2 double] [3x3 double]
Create two tasks that return random matrices of size 2-by-3 and 1-by-4.
y = dfeval(@rand,{2 1},{3 4}); y{1} ans = 0.8132 0.1389 0.1987 0.0099 0.2028 0.6038 y{2} ans = 0.6154 0.9218 0.1763

0.9355

Create two tasks, where the first task creates a 1-by-2 random array and the second task creates a 3-by-4 array of zeros.

Xs = gcat(labindex)

returns Xs = [3 4] on all four labs.
cat | gop | labindex | numlabs

14-116

Object properties
get(obj) out = get(obj) out = get(obj,'PropertyName')

obj 'PropertyName' out

An object or an array of objects. A property name or a cell array of property names. A single property value, a structure of property values, or a cell array of property values.
get(obj) returns all property names and their current values to the command line for obj. out = get(obj) returns the structure out where each field name is the name of a property of obj, and each field contains the value of that
out = get(obj,'PropertyName') returns the value out of the property specified by PropertyName for obj. If PropertyName is replaced by a 1-by-n or n-by-1 cell array of strings containing property names, then get returns a 1-by-n cell array of values to out. If obj is an array of objects, then out will be an m-by-n cell array of property values where m is equal to the length of obj and n is equal to the number of properties specified.
When specifying a property name, you can do so without regard to case, and you can make use of property name completion. For example, if jm is a job manager object, then these commands are all valid and return the same result.
out = get(jm,'HostAddress'); out = get(jm,'hostaddress'); out = get(jm,'HostAddr');

14-117

This example illustrates some of the ways you can use get to return property values for the job object j1.
get(j1,'State') ans = pending get(j1,'Name') ans = MyJobManager_job out = get(j1); out.State ans = pending out.Name ans = MyJobManager_job two_props = {'State' 'Name'}; get(j1, two_props) ans = 'pending' 'MyJobManager_job'

inspect | set

14-118
Output arguments from evaluation of all tasks in job object
data = getAllOutputArguments(obj)

obj data

Job object whose tasks generate output arguments.
M-by-N cell array of job results.
data = getAllOutputArguments(obj) returns data, the output data contained in the tasks of a finished job. If the job has M tasks, each row of the M-by-N cell array data contains the output arguments for the corresponding task in the job. Each row has N columns, where N is the
greatest number of output arguments from any one task in the job. The N elements of a row are arrays containing the output arguments from that task. If a task has less than N output arguments, the excess arrays in the row for that task are empty. The order of the rows in data will be the same as the order of the tasks contained in the job.

If you are using a job manager, getAllOutputArguments results in a call to a remote service, which could take a long time to complete, depending on the amount of data being retrieved and the network speed. Also, if the remote service is no longer available, an error will be thrown. Note that issuing a call to getAllOutputArguments will not remove the output data from the location where it is stored. To remove the output data, use the destroy function to remove the individual task or their parent job object. The same information returned by getAllOutputArguments can be obtained by accessing the OutputArguments property of each task in the job.
Create a job to generate a random matrix.
jm = findResource('scheduler','type','jobmanager',. 'name','MyJobManager','LookupURL','JobMgrHost');

14-119

j = createJob(jm, 'Name', 'myjob'); t = createTask(j, @rand, 1, {10}); submit(j); data = getAllOutputArguments(j);
Display the 10-by-10 random matrix.
disp(data{1}); destroy(j);

14-120

getCodistributor
Codistributor object for existing codistributed array
codist = getCodistributor(D) codist = getCodistributor(D) returns the codistributor object of codistributed array D. Properties of the object are Dimension and Partition for 1-D distribution; and BlockSize, LabGrid, and Orientation for 2-D block cyclic distribution. For any one codistributed array, getCodistributor returns the same values on all labs. The returned codistributor object is complete, and therefore suitable as an input argument for codistributed.build.
Get the codistributor object for a 1-D codistributed array that uses default distribution on 4 labs:
spmd (4) I1 = codistributed.eye(64, codistributor1d()); codist1 = getCodistributor(I1) dim = codist1.Dimension partn = codist1.Partition end
Get the codistributor object for a 2-D block cyclic codistributed array that uses default distribution on 4 labs:
spmd (4) I2 = codistributed.eye(128, codistributor2dbc()); codist2 = getCodistributor(I2) blocksz = codist2.BlockSize partn = codist2.LabGrid ornt = codist2.Orientation end
Demonstrate that these codistributor objects are complete:
spmd (4) isComplete(codist1)

14-121

isComplete(codist2) end
codistributed | codistributed.build | getLocalPart | redistribute

14-122

getCurrentJob
Job object whose task is currently being evaluated

job = getCurrentJob

The job object that contains the task currently being evaluated by the worker session.
Description Tips See Also
job = getCurrentJob returns the job object that is the Parent of the
task currently being evaluated by the worker session. If the function is executed in a MATLAB session that is not a worker, you get an empty result.

LabGrid, Orientation

BusyWorkers

Workers currently running tasks The BusyWorkers property value indicates which workers are currently running tasks for the job manager.
Job manager object Always Array of worker objects
As workers complete tasks and assume new ones, the lists of workers in BusyWorkers and IdleWorkers can change rapidly. If you examine these two properties at different times, you might see the same worker on both lists if that worker has changed its status between those times. If a worker stops unexpectedly, the job managers knowledge of that as a busy or idle worker does not get updated until the job manager runs the next job and tries to send a task to that worker.
Examine the workers currently running tasks for a particular job manager.
jm = findResource('scheduler','type','jobmanager',. 'name','MyJobManager','LookupURL','JobMgrHost'); workers_running_tasks = get(jm, 'BusyWorkers')
ClusterSize, IdleWorkers, MaximumNumberOfWorkers, MinimumNumberOfWorkers, NumberOfBusyWorkers, NumberOfIdleWorkers

CancelJobFcn

Specify function to run when canceling job on generic scheduler
CancelJobFcn specifies a function to run when you call cancel for a job running on a generic scheduler. This function lets you communicate with the scheduler, to provide any instructions beyond the normal toolbox action of changing the state of the job. To identify the job for the scheduler, the function should include a call to getJobSchedulerData.
For more information and examples on using these functions and properties, see Managing Jobs on page 8-50.
Generic scheduler object Never Function handle
You can set CancelJobFcn to any valid function handle or a cell array whose first element is a function handle.
cancel, getJobSchedulerData, setJobSchedulerData
CancelTaskFcn, DestroyJobFcn, DestroyTaskFcn

CancelTaskFcn

Specify function to run when canceling task on generic scheduler
CancelTaskFcn specifies a function to run when you call cancel
for a task running on a generic scheduler. This function lets you communicate with the scheduler, to provide any instructions beyond the normal toolbox action of changing the state of the task. To identify the task for the scheduler, the function should include a call to getJobSchedulerData. For more information and examples on using these functions and properties, see Managing Jobs on page 8-50.
You can set CancelTaskFcn to any valid function handle or a cell array whose first element is a function handle.
CancelJobFcn, DestroyJobFcn, DestroyTaskFcn
CaptureCommandWindowOutput
Specify whether to return Command Window output

Job object Never String

The default value is an empty string. Suppose you create a job object in the job manager jm.

job1 = createJob(jm);

You can assign job1 a unique label using Tag.
set(job1,'Tag','MyFirstJob')
You can identify and access job1 using the findJob function and the Tag property value.
job_one = findJob(jm,'Tag','MyFirstJob');

16-104

First task contained in MATLAB pool job object The Task property contains the task object for the MATLAB pool job, which has only this one task. This is the same as the first task contained in the Tasks property.
MATLAB pool job object Always Task object
createMatlabPoolJob, createTask

16-105

Tasks contained in job object The Tasks property contains an array of all the task objects in a job, whether the tasks are pending, running, or finished. Tasks are always returned in the order in which they were created.
Job object Always Array of task objects
Examine the Tasks property for a job object, and use the resulting array of objects to set property values.
jm = findResource('scheduler','type','jobmanager',. 'name','MyJobManager','LookupURL','JobMgrHost'); j = createJob(jm); createTask(j,.). createTask(j,.) alltasks = get(j, 'Tasks') alltasks = distcomp.task: 10-by-1 set(alltasks, 'Timeout', 20);
The last line of code sets the Timeout property value to 20 seconds for each task in the job.

16-106

createTask, destroy, findTask

16-107

Timeout
Specify time limit to complete task or job Timeout holds a double value specifying the number of seconds to wait before giving up on a task or job. The time for timeout begins counting when the task State property value changes from the Pending to Running, or when the job object State property value changes from Queued to Running. When a task times out, the behavior of the task is the same as if the task were stopped with the cancel function, except a different message is placed in the task objects ErrorMessage property. When a job times out, the behavior of the job is the same as if the job were stopped using the cancel function, except all pending and running tasks are treated as having timed out.