Main Content

sdo.GriddedSpace

Specify discrete grids of sample values for model parameters

Since R2023a

expand all in page

    Description

    Use sdo.GriddedSpace to generate samples of parameter values over a grid of values for sensitivity analysis. Where sdo.ParameterSpace allows you to draw random samples of parameter values from probability distributions, sdo.GriddedSpace allows you to generate uniform or nonuniform grids of parameter values at which to evaluate your cost function or design objectives. You can generate gridded samples of continuous or discrete parameters obtained from a Simulink® model using sdo.getParameterFromModel. You can also create composite spaces such that sdo.sample samples some parameters across a grid and generates random samples of other parameters.

    Use the sdo.GriddedSpace object as an input to the sdo.sample command to generate values of model parameters across the grid. Then, use sdo.evaluate to analyze how the model parameters influence the design objectives.

    Creation

    Syntax

    gs = sdo.GriddedSpace(p)
    gs = sdo.GriddedSpace(p,parameterValues)

    Description

    gs = sdo.GriddedSpace(p) creates a gridded parameter space based on the param.Continuous and param.Discrete parameters specified in p. The grid values for each parameter are set as follows:

    • Continuous parameter with nonzero nominal value — {nom-10%,nom,nom+10%}, where nom is the nominal value.

    • Continuous parameter with nom = 0 — {-1,0,1}.

    • Discrete parameter — The ValueSet property of the discrete parameter.

    This syntax is most useful when p contains discrete parameters. For continuous parameters, use the parameterValues input argument to specify the grid of values.

    example

    gs = sdo.GriddedSpace(p,parameterValues) specifies the grid of allowed values for each parameter, stored in the ParameterValues property. Use a cell array of cell arrays to specify the grid of values for each parameter in p.

    example

    Input Arguments

    expand all

    Model parameters to sample for sensitivity analysis, specified as a vector of param.Continuous objects, param.Discrete objects, or both. Use sdo.getParameterFromModel to obtain the array of parameters for p.

    Properties

    expand all

    This property is read-only.

    Names of parameters in the gridded parameter space, specified as a cell array of character vectors. For example, {'Kp','Ki'}. This property is set using the names of the parameters in the input array p.

    Model parameter values, specified as a cell array of cell arrays providing the allowed values for each parameter in p. For instance, if p contains two parameters, one that can take values (1, 2, 3) and another that can take values (10, 20, 30), then use values = {{1,2,3},{10,20,30}}.

    If you do not specify values when you create the gridded parameter space, then sdo.GriddedSpace uses the following default values:

    • Continuous parameter with nonzero nominal value — {nom-10%,nom,nom+10%}, where nom is the nominal value.

    • Continuous parameter with nom = 0 — {-1,0,1}.

    • Discrete parameter — The ValueSet property of the discrete parameter.

    When you create a composite parameter space that contains both a gridded subspace and a random subspace, the entries in ParameterValues that correspond to the random variables are prob.UnivariateDistribution objects. These objects represent the probability distributions assigned to the random variables (see sdo.ParameterSpace).

    Sampling method, specified as a sdo.GriddingOptions object. When you use sdo.sample to generate samples from the gridded space, this property determines whether those samples are exhaustive (all possible combinations of values across the grid) or sequential (pairwise combinations of values). Use dot notation to set this property, as follows.

    gs.Options.Method = 'exhaustive';
gs.Options.Method = 'sequential';

    By default, gs.Options.Method = 'exhaustive'. To set gs.Options.Method = 'sequential', all parameters must have the same number of possible values specified in ParameterValues.

    Parameter subspaces contained in the parameter space, specified as an empty cell array or a cell array of parameter spaces.

    When you construct a gridded parameter space using sdo.GriddedSpace, there are no subspaces, and the Spaces property is an empty cell array.

    When you create a composite parameter space by using the combine command with at least one sdo.GriddedSpace object, the Spaces property of the resulting sdo.GriddedSpace object is a cell array containing the two parameter spaces.

    Example: {[1×1 sdo.GriddedSpace] [1×1 sdo.ParameterSpace]}

    Text notes, specified as a character vector or cell array of character vectors. Use this property to store any text information you want to associate with the parameter space.

    Object Functions

    sdo.sampleGenerate parameter samples for sensitivity analysis
    combineCombine parameter spaces defined for sensitivity analysis
    addParameterAdd parameter to sdo.ParameterSpace or sdo.GriddedSpace object
    removeParameterRemove parameter from sdo.ParameterSpace or sdo.GriddedSpace object

    Examples

    collapse all

    Open Live Script

    This example uses the sdoCSTR model discussed in detail in Design Exploration Using Parameter Sampling (Code). Among the parameters in this model are the reactor cylinder area A and height h. Suppose that you want to test the sensitivity of your design objectives over a grid of values for these parameters. To start, open the model and create param.Continuous objects to represent the two parameters.

    mdl = "sdoCSTR";
open_system(mdl);
p = sdo.getParameterFromModel(mdl,{'A','h'});

    Specify the grid of values for each parameter by placing the values in a cell array. The grids in this example are uniformly spaced, but you can also use nonuniformly spaced values. 

    Avals = {0.2 0.6 1.0 1.4 1.8 2.2};
hvals = {0.5 1.5 2.5 3.5};

    Define the gridded parameter space using this grid.

    gp = sdo.GriddedSpace(p,{Avals,hvals});

    Sample the parameter space to generate all the combinations to use for sensitivity analysis. By default, sdo.sample generates an exhaustive list of all possible combinations in the parameter space, (Avals,hvals) = (0.2,0.5), (0.6,0.5), (1.0,0.5), ..., (1.4,3.5), (1.8,3.5), (2.2,3.5). Thus, the sampled values make up a table of 24 rows. 

    values = sdo.sample(gp)
    values=24×2 table
     A      h 
    ___    ___

    0.2    0.5
    0.6    0.5
      1    0.5
    1.4    0.5
    1.8    0.5
    2.2    0.5
    0.2    1.5
    0.6    1.5
      1    1.5
    1.4    1.5
    1.8    1.5
    2.2    1.5
    0.2    2.5
    0.6    2.5
      1    2.5
    1.4    2.5
      ⋮

    You can visualize the sampled values for a view of the distribution of samples. 

     sdo.scatterPlot(values)

    MATLAB figure

    Use values with sdo.evaluate to evaluate your design objectives at the sampled parameter values. For instance, if you have defined a cost function design.m to capture your design objectives, you can use values in a call to sdo.evaluate as follows.

    [yR,infoR] = sdo.evaluate(@design,p,values);

    Open Live Script

    The example Exhaustive Sampling Across a Grid of Parameter Values shows how to create exhaustive grids of parameter values. Suppose instead that you want to create a set of specified pairs of parameter values (A1,h1), (A2,h2), and so on. To do so, use the sequential method of sampling the gridded parameter space. Open the model and create param.Continuous objects to represent the two parameters.

    mdl = "sdoCSTR";
open_system(mdl);
p = sdo.getParameterFromModel(mdl,{'A','h'});

    Specify the values (A1, A2, ...) and (h1, h2, ...). For sequential sampling, use the same number of values for each parameter. 

    Avals = {0.2 0.6 1.0 1.4 1.8};
hvals = {0.5 1.0 1.5 2.0 2.5};

    Define the gridded parameter space using this grid.

    gp = sdo.GriddedSpace(p,{Avals,hvals});

    Specify sequential sampling using the Method property of the Options property of gp.

    gp.Options.Method = 'sequential';

    Finally, sample the parameter space to generate the parameter samples (Avals,hvals) = (0.2,0.5), (0.6,1.0), ..., (1.8,2.5). 

    values = sdo.sample(gp)
    values=5×2 table
     A      h 
    ___    ___

    0.2    0.5
    0.6      1
      1    1.5
    1.4      2
    1.8    2.5

    You can visualize the sampled values for a view of the set of samples. 

    sdo.scatterPlot(values)

    MATLAB figure

    Use values with sdo.evaluate to evaluate your design objectives at the sampled parameter values. For instance, if you have defined a cost function design.m to capture your design objectives, you can use values in a call to sdo.evaluate as follows.

    [yR,infoR] = sdo.evaluate(@design,p,values);

    Open Live Script

    You can sample discrete parameters across their full gird of allowed values or across a subset of those values. As with continuous parameters, sampling can be exhaustive or sequential.

    The sdoMotorPosition model includes a resistor network containing resistors R1, R2, R3, and R4. Open the model, and create a vector of param.Discrete objects to represent the resistor values. 

    mdl = "sdoMotorPosition";
open_system(mdl)
params = sdo.getParameterFromModel(mdl,[],{'R1','R2','R3','R4'});

    Specify sets of allowed values and current values for these parameters,

    % R1 values
params(1).ValueSet = [39 43 47 51 56];
params(1).Value    = 47;
% R2 values
params(2).ValueSet = [150 160 180 200 220];
params(2).Value    = 180;
% R3 values
params(3).ValueSet = [8.2 9.1 10 11 12];
params(3).Value    = 10;
% R4 values
params(4).ValueSet = [8.2 9.1 10 11 12];
params(4).Value    = 10;

    To generate samples using the full set of allowed values, create the gridded parameter space without specifying any values. 

    gspace = sdo.GriddedSpace(params)
    gspace = 
  GriddedSpace with properties:

    ParameterValues: {{1x5 cell}  {1x5 cell}  {1x5 cell}  {1x5 cell}}
              Notes: []
             Spaces: {1x0 cell}
     ParameterNames: {'R1'  'R2'  'R3'  'R4'}
            Options: [1x1 sdo.GriddingOptions]

    Generate a sequential sample set, (R1_1, R2_1, R3_1, R4_1), ..., (R1_5, R2_5, R3_5, R4_5), by setting the sampling method of gspace. 

    gspace.Options.Method = 'sequential';
svalues = sdo.sample(gspace)
    svalues=5×4 table
    R1    R2     R3     R4 
    __    ___    ___    ___

    39    150    8.2    8.2
    43    160    9.1    9.1
    47    180     10     10
    51    200     11     11
    56    220     12     12

    To draw samples from a subset of the allowed parameter values, reset the values in gspace using setValues. Alternatively, specify the subsets when you create the gridded parameter space. The values you specify must be subsets of the ValueSet property of params and must include the current value of each parameter.

    gsubspace = sdo.GriddedSpace(params,...
            {{39 43 47},{150 160 180},{8.2 9.1 10},{8.2 9.1 10}});

    Suppose that you want an exhaustive of every possible combination of R1, R2, R3, and R4 values in these subsets. Use sdo.sample to obtain these samples. 

    gsubspace.Options.Method = 'exhaustive';
evalues = sdo.sample(gsubspace)
    evalues=81×4 table
    R1    R2     R3     R4 
    __    ___    ___    ___

    39    150    8.2    8.2
    43    150    8.2    8.2
    47    150    8.2    8.2
    39    160    8.2    8.2
    43    160    8.2    8.2
    47    160    8.2    8.2
    39    180    8.2    8.2
    43    180    8.2    8.2
    47    180    8.2    8.2
    39    150    9.1    8.2
    43    150    9.1    8.2
    47    150    9.1    8.2
    39    160    9.1    8.2
    43    160    9.1    8.2
    47    160    9.1    8.2
    39    180    9.1    8.2
      ⋮

    Version History

    Introduced in R2023a

    See Also

    | | | | | |