runExperiment

R2026b

Run experiment from project

Since R2026b

collapse all in page

    Syntax

    result = runExperiment(projectFolder,experimentName)
    result = runExperiment(projectFolder,experimentName,UseParallel=parallelopt)

    Description

    result = runExperiment(projectFolder,experimentName) runs the specified experiment and returns the result in an ExperimentResult object. You must create and configure the experiment in the Experiment Manager app before you can run it programmatically.

    example

    result = runExperiment(projectFolder,experimentName,UseParallel=parallelopt) also specifies whether to run multiple trials simultaneously. Enabling this option reduces execution time for long-running experiments. This syntax requires Parallel Computing Toolbox™.

    example

    Examples

    collapse all

    Run an experiment. The function displays its progress using timestamped messages.

    result = runExperiment("MyProject","Experiment1")
    [09:57:55] [MyProject/Experiment1] Starting experiment.
[09:57:55] [MyProject/Experiment1] Initializing experiment and validating experiment details.
[09:57:56] [MyProject/Experiment1] Running 4 trials.
[09:57:56] [MyProject/Experiment1] Starting trial 1.
[09:57:57] [MyProject/Experiment1] Trial 1 Status : Complete.
[09:57:57] [MyProject/Experiment1] Starting trial 2.
[09:57:57] [MyProject/Experiment1] Trial 2 Status : Complete.
[09:57:57] [MyProject/Experiment1] Starting trial 3.
[09:57:58] [MyProject/Experiment1] Trial 3 Status : Complete.
[09:57:58] [MyProject/Experiment1] Starting trial 4.
[09:57:58] [MyProject/Experiment1] Trial 4 Status : Complete.
[09:57:58] [MyProject/Experiment1] Finishing experiment.
result = 

  ExperimentResult with properties:

     ProjectFolder: "C:\Projects\MyProject"
    ExperimentName: "Experiment1"
        ResultName: "Result1"
          Strategy: "exhaustive-sweep"
            Status: complete
             Error: [0x0 MException]
     ResultSummary: [4x3 table]
            Trials: [4x1 matlab.experiment.trial.ExperimentTrial]

    View the result summary table. Each row corresponds to one trial. Alternatively, you can view the result summary table in the Experiment Manager app.

    T = result.ResultSummary
    T =

  4×3 table

            Experiment Details             Parameters    Outputs
    ___________________________________    __________    _______

    Trial      Status      Elapsed Time      x    y         z   
    _____    __________    ____________      _    _         _   
                                                                
      1      "Complete"      00:00:04        1    4         5   
      2      "Complete"      00:00:05        2    4         6   
      3      "Complete"      00:00:05        1    5         6   
      4      "Complete"      00:00:04        2    5         7

    Run an experiment with trials executing simultaneously. This syntax requires Parallel Computing Toolbox.

    result = runExperiment("MyProject","Experiment1",UseParallel="on");

    Input Arguments

    collapse all

    Path to the project PRJ file or project root folder, specified as a string scalar or character vector. You can specify an absolute or relative path. The project must contain one or more Experiment Manager experiments.

    Example: "C:\Projects\MyProject\MyProject.prj"

    Example: "C:\Projects\MyProject"

    Example: "MyProject"

    Name of the experiment to run, specified as a string scalar or character vector. To query the names of experiments in a project, use the experimentNames function.

    Example: "Experiment1"

    Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

    • "off" — Run trials sequentially on the MATLAB® client.

    • "auto" — Run trials simultaneously using a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, run trials sequentially on the MATLAB client.

    • "on" — Run trials simultaneously using a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, throw an error.

    If you do not have a parallel pool open and automatic pool creation is enabled, MATLAB opens a pool using the default cluster profile. To use a parallel pool to run computations in MATLAB, you must have Parallel Computing Toolbox. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

    Example: UseParallel="on"

    Output Arguments

    collapse all

    Experiment result, returned as an ExperimentResult object that contains the configuration details and outcomes of a single execution of the specified experiment.

    Limitations

    • The runExperiment function does not support running an experiment on a cluster. Use the Experiment Manager app to run batch experiments.

    Version History

    Introduced in R2026b

    See Also

    Functions

    Objects

    Apps

    Topics