主要内容

本页采用了机器翻译。点击此处可查看最新英文版本。

distributed

从客户端创建并访问分布式数组的元素

    说明

    客户端上的分布式数组表示在并行池中的工作单元之间进行分区的数组。您可以将整个数组作为单个实体进行操作;但是,工作单元仅对其所在的数组部分进行操作,并在必要时自动在它们之间传输数据。分布式数组在索引和操作其元素的方式上类似于普通的 MATLAB® 数组,但其元素均不存在于客户端上。您在 spmd 语句内创建的共存分布式数组可作为分布式数组从客户端访问。

    创建对象

    使用 distributed 函数或使用数组创建函数(如 oneszeros)的 "distributed" 选项。有关直接在工作单元上创建分布式数组的数组创建函数的列表,请参阅 替代功能

    描述

    D = distributed(ds)datastore ds 创建一个分布式数组。D 是一个分部分存储在开放并行池的工作单元上的分布式数组。

    要将池中的分布式数组元素检索回 MATLAB 工作区中的数组,请使用 gather 函数。

    示例

    D = distributed(X) 从数组 X 创建一个分布式数组。

    仅当 MATLAB 客户端能够将所有 X 存储在内存中时,才使用此语法从本地数据创建分布式数组。要创建大型分布式数组,请使用前面的语法从数据存储创建分布式数组,或者使用数组创建函数(例如 oneszeros替代功能 中列出的任何其他创建函数)的 "distributed" 选项。

    如果输入参量已经是分布式数组,则结果与输入相同。

    示例

    D = distributed(C,dim)Composite 对象 C 创建分布式数组,其中 C 的条目连接并沿维度 dim 分布。如果省略 dim,则第一个维度是分布维度。

    Composite 对象的所有条目必须具有相同的类。除分布维度之外的其他维度必须相同。

    示例

    D = distributed(tX) 将 tall 数组 tX 转换为沿第一个维度分布的分布式数组。tX 必须在可以运行分布式数组的并行环境中定义。 (自 R2023b 起)

    示例

    输入参量

    全部展开

    数据存储,指定为以下对象之一。

    对象类型
    TabularTextDatastore 对象文本文件
    ImageDatastore 对象图像文件
    SpreadsheetDatastore 对象电子表格文件
    KeyValueDatastore 对象MAT 文件以及使用 mapreduce 生成的序列文件
    FileDatastore 对象自定义格式文件
    TallDatastore 对象tall 数据类型的 write 函数生成的 MAT 文件和序列文件
    ParquetDatastore 对象Parquet 文件
    DatabaseDatastore (Database Toolbox) 对象数据库

    要分发的数组,指定为数组。

    要分发的 Composite 对象,指定为 Composite 对象。

    分布维度,指定为标量整数。分布维度指定分布 Composite 对象的维度。

    自 R2023b 起

    要转换为分布式数组的 tall 数组,指定为 tall 数组。必须在支持分布式数组的并行环境中定义 tall 数组。

    输出参量

    全部展开

    分部分存储在开放并行池的工作单元上的分布式数组,以分布式数组的形式返回。

    对象函数

    gather将分布式数组、Composite 对象或 gpuArray 对象传输到本地工作区
    write将分布式数据写入输出位置

    几个 MATLAB 工具箱包含支持分布式数组的函数。有关所有支持分布式数组的 MathWorks® 产品中的函数列表,请参阅所有函数列表(分布式数组)

    多个对象函数可让您检查分布式数组的特征。大多数行为类似于同名的 MATLAB 函数。

    isdistributed对于分布式数组而言为 true
    isreal确定数组是否使用复数存储
    isUnderlyingType确定输入是否有指定的基础数据类型
    length最大数组维度的长度
    ndims数组维度数目
    size数组大小
    underlyingType确定数组行为的基础数据的类型

    示例

    全部折叠

    此示例显示如何使用 datastore 创建和加载分布式数组。

    首先,使用示例数据集创建数据存储。该数据集太小,无法显示对各个工作单元进行平等分区的情况。为了仿真大型数据集,可以使用 repmat 人为地增加数据存储的大小。

    files = repmat("airlinesmall.csv",10,1);
    ds = tabularTextDatastore(files);
    

    选择示例变量。

    ds.SelectedVariableNames = ["DepTime", "DepDelay"];
    ds.TreatAsMissing = "NA";
    

    通过并行读取数据存储来创建分布式表。对数据存储进行分区,每个工作单元一个分区。然后每个工作单元从相应的分区读取所有数据。这些文件必须位于工作单元可访问的共享位置。

    dt = distributed(ds);
    Starting parallel pool (parpool) using the 'Processes' profile ... connected to 4 workers.

    最后,显示有关分布式表的摘要信息。

    summary(dt) 
    Variables:
    
        DepTime: 1,235,230×1 double
            Values:
    
                min          1
                max       2505
                NaNs    23,510
    
        DepDelay: 1,235,230×1 double
            Values:
    
                min      -1036
                max       1438
                NaNs    23,510
    

    此示例显示如何创建和检索分布式数组。

    创建一个小数组并将其转换为分布式数组。

    Nsmall = 50;
    D1 = distributed(magic(Nsmall));
    Starting parallel pool (parpool) using the 'Processes' profile ...
    Connected to parallel pool with 4 workers.
    

    使用构建函数直接在工作单元上创建大型分布式数组。

    Nlarge = 1000;
    D2 = rand(Nlarge,"distributed");

    将分布式数组的元素检索回本地工作区。您可以使用 whos 通过检查 Class 变量来确定工作区中数据的位置。

    D3 = gather(D2);
    whos
      Name           Size                Bytes  Class          Attributes
    
      D1            50x50                20000  distributed              
      D2          1000x1000            8000000  distributed              
      D3          1000x1000            8000000  double                   
      Nlarge         1x1                     8  double                   
      Nsmall         1x1                     8  double                   
    

    启动并行工作单元池并使用 Composite 创建 spmd 对象。

    p = parpool("Processes",4);
    Starting parallel pool (parpool) using the 'Processes' profile ...
    Connected to parallel pool with 4 workers.
    
    spmd
        C = rand(3,spmdIndex-1);
    end
    C
     
    C =
     
       Worker 1: class = double, size = [3  0]
       Worker 2: class = double, size = [3  1]
       Worker 3: class = double, size = [3  2]
       Worker 4: class = double, size = [3  3]
     
    

    要从 Composite 对象创建分布式数组,请使用 distributed 函数。对于此示例,沿第二个维度分布条目。

    d = distributed(C,2)
    d =
    
        0.6383    0.9730    0.2934    0.3241    0.9401    0.1897
        0.5195    0.7104    0.1558    0.0078    0.3231    0.3685
        0.1398    0.3614    0.3421    0.9383    0.3569    0.5250
    

    检查数据在工作单元身上的分布情况。

    spmd
        d
    end
    Worker 1: 
      This worker does not store any elements of d.
    Worker 2: 
      This worker stores d(:,1).
              LocalPart: [3x1 double]
          Codistributor: [1x1 codistributor1d]
    Worker 3: 
      This worker stores d(:,2:3).
              LocalPart: [3x2 double]
          Codistributor: [1x1 codistributor1d]
    Worker 4: 
      This worker stores d(:,4:6).
              LocalPart: [3x3 double]
          Codistributor: [1x1 codistributor1d]
    

    完成计算后,删除并行池。

    delete(p);
    Parallel pool using the 'Processes' profile is shutting down.
    

    自 R2023b 起

    此示例显示如何将 tall 数组转换为分布式数组。

    使用示例数据集创建一个 tall 表。如果您安装了 Parallel Computing Toolbox™,当您使用 tall函数时,MATLAB 会自动启动并行工作单元池,除非您关闭默认并行池首选项。默认集群使用您计算机本地的进程工作单元。

    size = 2000000;
    tt = tall(table((1:size)',randn(size,1),randn(size,1),randn(size,1), ...
        'VariableNames',["Exp","Rep1","Rep2","Rep3"]))
    Starting parallel pool (parpool) using the 'Processes' profile ...
    Connected to parallel pool with 4 workers.
    
    tt =
    
      2,000,000×4 tall table
    
        Exp      Rep1        Rep2         Rep3  
        ___    ________    _________    ________
    
         1      -1.6003      -1.2403     -1.6124
         2      0.76827      0.33907     0.77811
         3       1.4637      0.74255    -0.91635
         4      -1.2478      0.10478    -0.10097
         5        0.619      -1.2974     0.93445
         6       1.8375       0.2142     -1.1036
         7     -0.44354      -1.1438    -0.89011
         8      -1.3351    -0.036768     0.65196
         :        :            :           :
         :        :            :           :
    

    将 tall 表转换成分布式表。MATLAB 沿第一个维度对 tall 表中的数据进行分区,并将其分发给工作单元。

    dt = distributed(tt);

    显示有关分布式表的摘要信息。

    summary(dt)
    Variables:
    
        Exp: 2,000,000×1 double
            Values:
    
                Min         1  
                Max     2e+06  
    
        Rep1: 2,000,000×1 double
            Values:
    
                Min    -5.1402 
                Max     4.8763 
    
        Rep2: 2,000,000×1 double
            Values:
    
                Min    -4.7961 
                Max     4.9875 
    
        Rep3: 2,000,000×1 double
            Values:
    
                Min    -4.8369 
                Max     5.1454 
    

    最后,检查每个工作单元上存储了多少数据。数据被均匀地分区给各个工作单元。

    spmd
        dt
    end
    Worker 1: 
      
      This worker stores dt(1:500000,:).
      
              LocalPart: [500000x4 table]
          Codistributor: [1x1 codistributor1d]
      
    Worker 2: 
      
      This worker stores dt(500001:1000000,:).
      
              LocalPart: [500000x4 table]
          Codistributor: [1x1 codistributor1d]
      
    Worker 3: 
      
      This worker stores dt(1000001:1500000,:).
      
              LocalPart: [500000x4 table]
          Codistributor: [1x1 codistributor1d]
      
    Worker 4: 
      
      This worker stores dt(1500001:2000000,:).
      
              LocalPart: [500000x4 table]
          Codistributor: [1x1 codistributor1d]
      
    

    提示

    • 在现有并行池的工作单元上创建一个分布式数组。如果不存在池,distributed 将启动一个新的并行池,除非在并行设置中禁用了池的自动启动。如果没有并行池并且 distributed 无法启动并行池,则 MATLAB 会将结果作为客户端工作区中的非分布式数组返回。

    替代功能

    下表列出了可用的在工作单元上直接创建 distributed 数组的 MATLAB 函数。有关更多信息,请参阅函数参考页的扩展功能部分。

    版本历史记录

    在 R2008a 中推出

    全部展开