dload

Load distributed arrays and Composite objects

collapse all in page

    Syntax

    dload filename
    dload filename variables
    dload -scatter ___
    dload(filename)
    [out1,...,outN] = dload(filename,variables)

    Description

    dload filename loads all variables from the file with the name filename. If you do not specify an extension, the function assumes that the extension is .mat. The function loads the contents of distributed arrays and Composite objects onto parallel pool workers. The function loads other data types directly into the workspace of the MATLAB® client.

    • When you load distributed arrays, the function distributes the data over the current parallel pool workers using the default distribution scheme. You do not need to have the same size pool open when you load variables using this function.

    • When you load Composite objects, the function sends the data to the current parallel pool workers. If the Composite is too large to fit on the current parallel pool, the software does not load the data. If the Composite is smaller than the current parallel pool, the software returns a warning.

    If a parallel pool is not open, by default the dload function starts a parallel pool of workers using the default profile.

    example

    dload filename variables loads the specified variables from the file with the name filename.

    The function does not support wildcards, nor the -regexp option. If the file does not contain one or more of the specified variables, the software returns a warning.

    example

    dload -scatter ___ attempts to distribute nondistributed data. If dload cannot distribute the data, it returns a warning.

    example

    dload(filename) performs the same operation as dload filename.

    For example, these function calls are equivalent: 

     dload("test.mat")
    dload test.mat

    example

    [out1,...,outN] = dload(filename,variables) loads the specified variables and returns them as separate output arguments. If the file does not contain one or more of the specified variables, the function returns an error.

    example

    Examples

    collapse all

    Open Live Script

    Load all distributed arrays from the fname MAT file into the MATLAB workspace.

    First, list the variables in the workspace.

    whos

    List the variables in fname.

    whos("-file","fname.mat")
      Name                 Size             Bytes  Class     Attributes

  DMAT_MANIFEST        1x1               4171  struct              
  X                  100x100            80000  double              
  Y                   90x90             64800  double              
  Z                  110x110            96800  double

    Load fname, and then list the variables in the workspace again. By default, the dload function starts a parallel pool of workers to distribute the variables.

    dload fname.mat
    Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 6 workers.

    whos
      Name        Size             Bytes  Class          Attributes

  X         100x100            80000  distributed              
  Y          90x90             64800  distributed              
  Z         110x110            96800  distributed

    You can also use the function syntax to load the variables. Clear the variables and call the dload function.

    clear X Y Z
dload("fname.mat")
    Open Live Script

    Create Composite objects, save them to a file, and load the data back into a different sized parallel pool.

    Create a parallel pool with four workers and use spmd statements to create Composite objects on the client. Save the Composite objects to the mydata MAT file then clear the workspace.

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

    spmd
P = magic(1000);
Q = randn(2000);
end
dsave mydata P Q
clear P Q
delete(p);
    Parallel pool using the 'Processes' profile is shutting down.

    Load the Composite objects P and Q from the MAT file. The new parallel pool is larger than the pool you use to create the Composite objects, so the software returns a warning.

    [P,Q] = dload("mydata.mat","P","Q");
    Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 6 workers.

    Warning: The Composite "P" was created with a pool of size 4, and is being loaded into a Composite of size 6 (the current default Composite size).

    Warning: The Composite "Q" was created with a pool of size 4, and is being loaded into a Composite of size 6 (the current default Composite size).

    List the variables in the workspace.

    whos
      Name      Size            Bytes  Class                   Attributes

  P         1x6               505  Composite                         
  Q         1x6               505  Composite                         
  p         1x1                 8  parallel.ProcessPool
    Open Live Script

    Load and distribute a table variable from a file.

    View the contents of the student_scores MAT file.

    whos("-file","student_scores.mat")
      Name               Size            Bytes  Class    Attributes

  studentScores       -              13541  table

    Load and distribute the studentScores table from the student_scores MAT file. 

    scores = dload("-scatter","student_scores.mat");
    Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 4 workers.

    Check how much data is distributed to each worker.

    spmd
    scores
end
    Worker 1: 
  This worker stores scores(1:9,:).
          LocalPart: [9x26 table]
      Codistributor: [1x1 codistributor1d]
Worker 2: 
  This worker stores scores(10:18,:).
          LocalPart: [9x26 table]
      Codistributor: [1x1 codistributor1d]
Worker 3: 
  This worker stores scores(19:26,:).
          LocalPart: [8x26 table]
      Codistributor: [1x1 codistributor1d]
Worker 4: 
  This worker stores scores(27:34,:).
          LocalPart: [8x26 table]
      Codistributor: [1x1 codistributor1d]

    Input Arguments

    collapse all

    Name of the file to load, specified as a string scalar or character vector. If you do not specify filename, the dload function searches for a MAT file named matlab. If the function cannot find the file, it returns an error.

    If you do not specify an extension for filename, dload searches for a file with the name filename and the .mat extension.

    Depending on the location of your file, filename has one of these forms.

    • If the file is in the current folder or a folder on the MATLAB path, specify only the name of the file in filename.

    • If the file is not in the current folder or in a folder on the MATLAB path, specify the full or relative path in filename.

    Example: "myFile.mat" specifies the name of the file.

    Example: C:\myFolder\myFile.mat specifies the full path to the file.

    Data Types: char | string

    Names of variables to load, specified as one or more string scalars or character vectors.

    The dload function does not support wildcards, nor the -regexp option. If the function cannot find one or more of the specified variables, it returns a warning.

    Data Types: char | string

    Tips

    • The dload function loads a distributed array or Composite object on the workers of the existing parallel pool. If no pool exists, the dload function starts a new parallel pool, unless automatically starting pools is disabled in your parallel settings. If no parallel pool exists and dload cannot start one, dload loads distributed objects but cannot load Composite objects.

    Version History

    Introduced in R2010a

    See Also

    | | | |