Composite - Create and access nondistributed variables on multiple workers from

  client - MATLAB ([original](https://in.mathworks.com/help/parallel-computing/composite.html)) ([raw](?raw))

Create and access nondistributed variables on multiple workers from client

Description

Composite objects contain references to variables stored on parallel workers running an spmd statement. A Composite object resembles a cell array with one element for each worker and can contain different values for each worker. You can retrieve values using cell-array indexing and define values for the entries using indexing or an spmd block. The actual data on the workers remains available for subsequent spmd execution, while theComposite exists on the client and the parallel pool remains open.

Creation

spmd statements automatically create composite variables on the client when the body of an spmd statement returns values. Therefore, you rarely need to create Composite objects directly.

You can also create Composite objects explicitly with theComposite function.

Syntax

Description

[c](#mw%5F8b911041-33cd-4d4c-91a0-f45cb00a3389) = Composite creates aComposite object on the client using workers from the current parallel pool.

The actual number of workers that the object references depends on the size of the pool and any existing Composite objects. If a parallel pool is not open, the Composite function starts a parallel pool of workers using the default profile.

To create a Composite object manually, you must do so outside anyspmd statements. Initially, each entry of the manually createdComposite object contains no data. Define values for the entries by using indexing or an spmd block.

example

[c](#mw%5F8b911041-33cd-4d4c-91a0-f45cb00a3389) = Composite([nworkers](#mw%5Fce3b703a-fc56-488b-998b-3b8898ad5255)) specifies the number of workers to use to create a Composite object. The actual number of workers is the maximum number of workers compatible with the size of the current parallel pool and with any other existing Composite objects. The software returns an error if it cannot meet the constraints on the number of workers.

example

[c](#mw%5F8b911041-33cd-4d4c-91a0-f45cb00a3389) = Composite([pool](#mw%5Fdf331f7d-e0f3-4a59-8302-8a2bc6cc3c7b),___) creates a Composite object using workers from the parallel pool specified by the parallel.Pool objectpool. Use this syntax when you want to createComposite objects on a pool other than the pool the gcp function returns. (since R2025a)

example

Input Arguments

expand all

Number of workers creating the Composite object, specified as a positive integer, Inf, or a two-element vector containing positive integers or Inf values. If nworkers is a scalar, it specifies the exact number of workers to use. If nworkers is a two-element vector, its first and second elements specify the minimum and maximum number of workers to use, respectively.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Since R2025a

Pool creating Composite object, specified as aparallel.Pool object.

• To create a parallel pool, use parpool.
• To use a subset of the current pool, usepartition.

Output Arguments

expand all

Composite array on the client using workers from the parallel pool, returned as aComposite object.

Object Functions

Other object functions of a Composite object behave similarly to these MATLAB® array functions:

Examples

collapse all

This example shows how to create a Composite object with no defined elements, and then assign values using a for-loop on the client.

Start a parallel pool with four workers and create a Composite object with an element for each worker.

p = parpool("Processes",4);

Starting parallel pool (parpool) using the 'Processes' profile ... Connected to parallel pool with 4 workers.

c =

Worker 1: No data Worker 2: No data Worker 3: No data Worker 4: No data

Use a for-loop on the client to define values for the elements of the Composite object. The value that you assign to each element is stored on the workers. Display the Composite object.

for w = 1:length(c) c{w} = rand; end c{:}

This example shows how to specify the number of workers and consequently the number of elements in a Composite object.

Start a parallel pool of 10 workers using a profile called my_Profile.

parpool("my_Profile",10);

Starting parallel pool (parpool) using the 'my_Profile' profile ... Connected to parallel pool with 10 workers.

Create a Composite object with only four workers from the current parallel pool and assign values to the Composite elements in an spmd block. Display the Composite object.

c = Composite(4); spmd c = spmdIndex; end c{:}

This example shows how to use an spmd block and a distributed array to create Composite objects on the client.

Start a parallel pool with four workers and distribute an array of four integers to the workers. Each worker gets one integer.

p = parpool("Processes",4); d = distributed([3 1 4 2]);

Use the parts of the distributed array on each worker to set the values of the Composite object c.

spmd c = getLocalPart(d); end

Display and view information about c.

Name Size Bytes Class Attributes

c 1x4 489 Composite

Start a parallel pool using the remote cluster profile myMJSCluster.

myClusterPool = parpool(myMJSCluster,15);

Starting parallel pool (parpool) using the 'myMJSCluster' profile ... Connected to parallel pool with 15 workers.

Partition the myClusterPool to prepare for running an spmd statement. Use the partition function to create a new pool, spmdPool, where each host is limited to a maximum of one worker. This setup helps distribute tasks evenly across hosts.

[spmdPool,otherPool] = partition(myClusterPool,"MaxNumWorkersPerHost",1);

Create a Composite object with an element for each worker in spmdPool.

Use a for-loop on the client to define values for the elements of the Composite object.

m = 1000000; for w = 1:length(j) j{w} = rand(m,2); end

Perform a Monte Carlo approximation of pi using the Composite object.

spmd for p = drange(1:spmdSize) z = j(:,1) + 1ij(:,2); c = sum(abs(z) < 1); end k = spmdPlus(c); p = 4k/(m*spmdSize); end approxPi = p{1}

Tips

• The Composite function creates a Composite object on the workers of the existing parallel pool. If no pool exists, theComposite function starts a new parallel pool unless automatically starting pools is disabled in your parallel settings. If no parallel pool exists andComposite cannot start one, the result is a 1-by-1Composite object in the client workspace.

Extended Capabilities

Version History

Introduced in R2008a

expand all

You can now specify a parallel pool to use to create Composite objects. Use this syntax to create Composite on a pool other than the pool thegcp function returns.