Main Content

このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

runperf

一連のパフォーマンス測定テストを実行

説明

results = runperf は、パフォーマンス測定の目的で現在のフォルダー内にあるすべてのテストを実行し、matlab.perftest.TimeResult オブジェクトの配列を返します。results の各要素はテスト スイートの要素に対応します。

パフォーマンス テスト フレームワークは、可変の測定回数を使用してテストを実行し、信頼度 0.95 (95%) で相対許容誤差 0.05 (5%) のサンプル平均を求めます。テストを 5 回実行してコードをウォームアップし、次に 4 ~ 256 回実行して統計目標値を満たす測定値を収集します。256 回のテスト実行後にサンプル平均が信頼度 0.95 で相対許容誤差 0.05 を満たさない場合、フレームワークはテストの実行を停止して警告を表示します。この場合、TimeResult オブジェクトには 5 回のウォームアップ実行と 256 回の測定実行の情報が含まれます。

関数 runperf は、パフォーマンス実験として一連のテストを実行する簡単な方法を提供します。

results = runperf(tests) は、指定された一連のテストを実行します。

results = runperf(___,Name,Value) は、1 つ以上の名前と値の引数で指定された追加オプションを使用して一連のテストを実行します。

すべて折りたたむ

現在のフォルダー内にスクリプト ベースのテスト onesTest.m を作成します。このテストは 3 つの異なるメソッドを使用して、3000 行 1000 列の 1 の行列を初期化します。

rows = 3000;
cols = 1000;

%% Ones Function
X = ones(rows,cols);

%% Loop Assignment Without Preallocation
for r = 1:rows
    for c = 1:cols
        X(r,c) = 1;
    end
end

%% Loop Assignment With Preallocation
X = zeros(rows,cols);
for r = 1:rows
    for c = 1:cols
        X(r,c) = 1;
    end
end

スクリプトをパフォーマンス テストとして実行します。返される results 変数は 1 行 3 列の TimeResult 配列です。配列の各要素は、onesTest.m に定義されているテストの 1 つに対応しています。

results = runperf("onesTest")
Running onesTest
.......... .......... .......
Done onesTest
__________


results = 

  1×3 TimeResult array with properties:

    Name
    Valid
    Samples
    TestActivity

Totals:
   3 Valid, 0 Invalid.
   23.1678 seconds testing time.

2 番目のテストの測定結果を表示します。これは事前割り当てを行わずに代入をループしたものです。

results(2)
ans = 

  TimeResult with properties:

            Name: 'onesTest/LoopAssignmentWithoutPreallocation'
           Valid: 1
         Samples: [4×7 table]
    TestActivity: [9×12 table]

Totals:
   1 Valid, 0 Invalid.
   22.8078 seconds testing time.

テスト測定値のテーブル全体を表示します。パフォーマンス テスト フレームワークはウォームアップ実行を 5 回実行し、次に測定実行 (Objective 列に sample として表示) を 4 回実行します。結果は異なる場合があります。

results(2).TestActivity
ans =

  9×12 table

                       Name                        Passed    Failed    Incomplete    MeasuredTime    Objective         Timestamp             Host        Platform                 Version                            TestResult                         RunIdentifier            
    ___________________________________________    ______    ______    __________    ____________    _________    ____________________    ___________    ________    __________________________________    ______________________________    ____________________________________

    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5463        warmup      14-Oct-2022 13:51:36    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5294        warmup      14-Oct-2022 13:51:38    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.4956        warmup      14-Oct-2022 13:51:41    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5369        warmup      14-Oct-2022 13:51:43    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false           2.535        warmup      14-Oct-2022 13:51:46    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5856        sample      14-Oct-2022 13:51:49    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5344        sample      14-Oct-2022 13:51:51    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false           2.542        sample      14-Oct-2022 13:51:54    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.4653        sample      14-Oct-2022 13:51:56    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b

2 番目のテストの平均測定時間を表示します。ウォームアップ実行で収集されたデータを除外するには、Samples プロパティの値を使用します。

mean(results(2).Samples.MeasuredTime)
ans =

    2.5318

スクリプトの各種初期化メソッドを比較するために、results から要約統計量の table を作成します。この例では、関数 ones が行列を 1 に初期化する最も速い方法でした。パフォーマンス テスト フレームワークはこのテストの測定実行を 4 回行いました。

T = sampleSummary(results)
T =

  3×7 table

                       Name                        SampleSize      Mean       StandardDeviation      Min        Median         Max   
    ___________________________________________    __________    _________    _________________    ________    _________    _________

    onesTest/OnesFunction                              4         0.0052392       8.9302e-05        0.005171    0.0052078    0.0053703
    onesTest/LoopAssignmentWithoutPreallocation        4            2.5318         0.049764          2.4653       2.5382       2.5856
    onesTest/LoopAssignmentWithPreallocation           4          0.023947       0.00046027        0.023532     0.023921     0.024415

現在の作業フォルダーに、さまざまな事前割り当てメソッドを比較するクラスベースのテスト preallocationTest.m を作成します。

classdef preallocationTest < matlab.perftest.TestCase
    methods(Test)
        function testOnes(testCase)
            x = ones(1,1e7);
        end
        
        function testIndexingWithVariable(testCase)
            id = 1:1e7;
            x(id) = 1;
        end
        
        function testIndexingOnLHS(testCase)
            x(1:1e7) = 1;
        end
        
        function testForLoop(testCase)
            for i=1:1e7
                x(i) = 1;
            end
        end
        
    end
end

preallocationTest クラスの測定境界はテスト メソッドです。各テスト メソッドの時間測定には、メソッド内のすべてのコードが含まれます。測定境界の指定の詳細については、matlab.perftest.TestCasestartMeasuring メソッドおよび stopMeasuring メソッドを参照してください。

名前に 'Indexing' を含むすべての要素のパフォーマンス テストを実行します。結果は異なる可能性があり、runperf が統計目標値を満たさない場合は警告が表示されることもあります。

results = runperf('preallocationTest','Name','*Indexing*')
Running preallocationTest
.......... .......... .......
Done preallocationTest
__________


results = 

  1×2 TimeResult array with properties:

    Name
    Valid
    Samples
    TestActivity

Totals:
   2 Valid, 0 Invalid.
   2.4858 seconds testing time.

各テストの平均測定時間を表示します。results 配列の 2 要素にわたって Samples フィールドの値を連結します。次に、varfun を使用して table エントリを名前でグループ化し、平均を計算します。

fullTable = vertcat(results.Samples);
varfun(@mean,fullTable,'InputVariables','MeasuredTime','GroupingVariables','Name')
ans =

  2×3 table

                       Name                       GroupCount    mean_MeasuredTime
    __________________________________________    __________    _________________

    preallocationTest/testIndexingWithVariable         6             0.16337     
    preallocationTest/testIndexingOnLHS               13            0.049936     

入力引数

すべて折りたたむ

テスト。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数を使用してテスト内容を指定します。たとえば、テスト ファイル、テスト クラス、テスト ファイルを含むフォルダー、テスト クラスを含むパッケージ、テスト ファイルを含むプロジェクト フォルダーを指定できます。

例: runperf("myTestFile.m")

例: runperf(["myTestFile/test1" "myTestFile/test3"])

例: runperf("mypackage.MyTestClass")

例: runperf(pwd)

例: runperf({'mypackage.MyTestClass','myTestFile.m',pwd,'mypackage.subpackage'})

例: runperf("C:\projects\project1")

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

例: runperf(tests,Name="productA_*") は、"productA_" で始まる名前のテスト要素を実行します。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: runperf(tests,"Name","productA_*") は、"productA_" で始まる名前のテスト要素を実行します。

テストの識別

すべて折りたたむ

サブフォルダー内のテストを実行するかどうかを示すインジケーター。false または true (0 または 1) として指定します。既定では、フレームワークは指定されたフォルダー内のテストを実行しますが、そのサブフォルダー内のテストは実行しません。

サブパッケージ内のテストを実行するかどうかを示すインジケーター。false または true (0 または 1) として指定します。既定では、フレームワークは指定されたパッケージ内のテストを実行しますが、そのサブパッケージ内のテストは実行しません。

参照プロジェクトのテストを含めるかどうか。数値または logical 0 (false) または 1 (true) として指定します。参照プロジェクトの詳細については、大規模なプロジェクトのコンポーネント化を参照してください。

関数で処理するフォルダーまたはパッケージ内の無効なテスト ファイルに対して実行するアクション。"warn" または "error" として指定します。

  • "warn" — 関数はフォルダーまたはパッケージ内の無効なテスト ファイルのそれぞれについて警告を発行し、有効なファイルのテストを実行します。

  • "error" — 関数はフォルダーまたはパッケージ内で無効なテスト ファイルを見つけるとエラーをスローします。

無効なテスト ファイルは、フレームワークで実行できないテスト ファイルです。たとえば、構文エラーを含むテスト ファイル、ローカル関数が欠落した関数ベースのテスト ファイル、未定義のパラメーター化プロパティが渡された Test メソッドを含むファイルなどが含まれます。

テストのフィルター処理

すべて折りたたむ

テスト ファイルを含むベース フォルダーの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素が BaseFolder によって指定されたベース フォルダーの 1 つに含まれていなければなりません。Test 要素がいずれもベース フォルダーと一致しない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

パッケージで定義したテスト ファイルでは、ベース フォルダーは最上位パッケージ フォルダーの親です。

ソース コードが含まれているファイルおよびフォルダーの名前。string ベクトル、文字ベクトル、または文字ベクトルの cell ベクトルとして指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理したスイートにテストを含めるには、テストを定義しているファイルが、指定したソース コードに依存している必要があります。テスト ファイルのいずれもソース コードに依存していない場合は、空のテスト スイートが返されます。

指定する値は、拡張子が .m.p.mlx.mlapp.mat、または .slx である 1 つ以上の既存のファイルを表している必要があります。サポートされていない拡張子をもつファイル名を明示的に指定することはできません。フォルダー名を指定した場合、フレームワークは、そのフォルダー内のサポートされるファイルのパスを抽出します。

DependsOn を使用するには、MATLAB® Test™ のライセンスが必要です。ソース コードの依存関係によるテストの選択の詳細については、matlabtest.selectors.DependsOn (MATLAB Test) を参照してください。

例: DependsOn=["myFile.m" "myFolder"]

例: DependsOn=["folderA" "C:\work\folderB"]

テストの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の Name プロパティが Name によって指定された名前の 1 つと一致しなければなりません。Test 要素がいずれも一致する名前をもたない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

特定のテスト ファイルにおいて、テストの名前はテスト内容のうち実行可能な最小部分を一意に識別します。テストの名前には、パッケージ名、ファイル名 (拡張子は除く)、プロシージャ名、およびパラメーター化に関する情報が含まれます。

テストで使用されるパラメーターを定義するテスト クラス プロパティの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の Parameterization プロパティに ParameterProperty で指定されたプロパティ名が少なくとも 1 つ含まれていなければなりません。Test 要素がいずれも一致するプロパティ名をもたない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

テストで使用されるパラメーターの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。MATLAB は、パラメーターを定義するテスト クラス プロパティに基づいてパラメーター名を生成します。

  • プロパティ値が cell 配列である場合、MATLAB は、cell 配列の要素の値、型、および次元を考慮して、それらの要素からパラメーター名を生成します。

  • プロパティ値が構造体である場合、MATLAB はパラメーター名を構造体フィールドから生成します。

引数 ParameterName はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の Parameterization プロパティに ParameterName によって指定されたパラメーター名が少なくとも 1 つ含まれていなければなりません。Test 要素がいずれも一致するパラメーター名をもたない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

テスト プロシージャの名前。string 配列、文字ベクトルまたは文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の ProcedureName プロパティが ProcedureName によって指定されたプロシージャ名の 1 つと一致しなければなりません。Test 要素がいずれも一致するプロシージャ名をもたない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

クラスベースのテストでは、テスト プロシージャの名前はテストを含む Test メソッドの名前です。関数ベースのテストでは、テストを含むローカル関数の名前です。スクリプトベースのテストでは、テスト セクション タイトルから生成された名前です。テスト スイート要素の名前とは異なり、テスト プロシージャの名前にパッケージ名、ファイル名、パラメーター化に関する情報は含まれません。

テスト クラスの派生元であるクラスの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の TestClass プロパティが Superclass によって指定されたクラスの 1 つから派生するテスト クラスを指していなければなりません。Test 要素がいずれもクラスに一致しない場合、空のテスト スイートが返されます。

テストで使用されるタグの名前。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。この引数はテスト スイートをフィルター処理します。テスト フレームワークがフィルター処理されたスイートにテストを含めるためには、Test 要素の Tags プロパティに Tag によって指定されたタグ名が少なくとも 1 つ含まれていなければなりません。Test 要素がいずれも一致するタグ名をもたない場合、空のテスト スイートが返されます。ワイルドカード文字 (*) を使用すると任意の数の文字と一致します。疑問符 (?) を使用すると単一の文字と一致します。

ヒント

  • パフォーマンス テストの統計目標値をカスタマイズするには、TimeExperiment クラスを使用してパフォーマンス テストを構成し実行します。

  • 共有テスト フィクスチャをテストで使用し、関数 runperf への入力を string 配列または文字ベクトルの cell 配列で指定する場合、テスト フレームワークは、共有フィクスチャのセットアップと破棄の操作を減らすために配列を並べ替えます。結果として、テストは入力配列内の要素の順序とは異なる順序で実行される可能性があります。詳細については、sortByFixtures を参照してください。

  • クラス ベースのテストを記述する場合、テストをスタンドアロン アプリケーションとして実行できます (MATLAB Compiler™ が必要です)。パフォーマンス テストのコンパイルは現在サポートされていません。詳細については、MATLAB ユニット テストのコンパイルを参照してください。

代替方法

テスト スイートを明示的に作成するには、スイートを作成する関数 testsuite または matlab.unittest.TestSuite メソッドを使用します。次に、指定した TimeExperimentrun メソッドを使用してパフォーマンス テストを実行できます。

バージョン履歴

R2016a で導入

すべて展開する