Main Content

sdo.ParameterSpace

Specify probability distributions for model parameters

    Description

    Use sdo.ParameterSpace to specify the probability distributions for model parameters that define a parameter space for sensitivity analysis. You use the sdo.ParameterSpace object as an input to the sdo.sample command and generate samples of the model parameters. The software generates these samples using the distributions specified for each parameter. You evaluate the cost function for each of these samples using the sdo.evaluate command and analyze how the model parameters influence the cost function.

    The parameters in the space defined by a sdo.ParameterSpace object are all randomly sampled. To define a gridded parameter space for sampling parameters at specified values, use sdo.GriddedSpace.

    Creation

    Description

    example

    ps = sdo.ParameterSpace(p) creates an sdo.ParameterSpace object for the specified model parameters. The software assigns the parameter names to the ParameterNames property and default values to the remaining properties, including ParameterDistributions. The software specifies the uniform distribution for each parameter in p and sets the values of the Lower and Upper parameters of the uniform distribution as follows:

    • Lower — Set to p.Minimum. If p.Minimum is equal to -Inf, then the software sets Lower to either 0.9*p.Value if p.Value is nonzero, or to –1.

    • Upper — Set to p.Maximum. If p.Maximum is equal to Inf, then the software sets Upper to either 1.1*p.Value if p.Value is nonzero, or to 1.

    example

    ps = sdo.ParameterSpace(p,pdist) specifies the distribution of each parameter.

    Input Arguments

    expand all

    Model parameters and states, specified as a vector of param.Continuous objects.

    For example, sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','K'}).

    Probability distribution of model parameters, specified as a vector of univariate probability distribution objects.

    • If pdist is the same size as p, the software specifies each entry of pdist as the probability distribution of the corresponding parameter in p.

    • If pdist contains only one object, the software specifies this object as the probability distribution for all the parameters in p.

    Use the makedist command to create a univariate probability distribution object, for example, makedist('Normal','mu',100,'sigma',10).

    To check if pdist is a univariate distribution object, run isa(pdist,'prob.UnivariateDistribution').

    Properties

    expand all

    This property is read-only.

    Model parameter names, specified as cell arrays of character vectors. For example, {'Kp','Ki'}.

    Model parameter distributions that sdo.sample uses to draw random samples, specified as a vector of probability distribution objects.

    By default, the software specifies a uniform distribution for the model parameters specified by p. For each parameter, the software sets the values of the Lower and Upper parameters of the uniform distribution:

    • Lower — Set to p.Minimum. If p.Minimum is equal to -Inf, then the software sets Lower to either 0.9*p.Value if p.Value is nonzero, or to –1.

    • Upper — Set to p.Maximum. If p.Maximum is equal to Inf, then the software sets Upper to either 1.1*p.Value if p.Value is nonzero, or to 1.

    Use the pdist input argument when constructing ps to set the value of this property. Alternatively, use the setDistribution method after you have constructed ps.

    Correlation between parameters, specified as a matrix.

    When you call sdo.sample, the software generates samples that are correlated as specified by this matrix (where the correlation refers to ranked correlation). You can specify the sampling method using the Method property of an sdo.SampleOptions.

    • If you specify Method as 'random', 'lhs', 'sobol', or 'halton', then the software uses the Iman-Conover algorithm to impose the correlation specified by RankCorrelation.

    • If you specify Method as 'copula', then the software uses a copula to impose the correlation specified by RankCorrelation. Use the MethodOptions property of the sdo.SampleOptions object to specify the copula family and to specify the degrees of freedom if using the t copula family.

    The default value [] imposes no correlation on the parameters. When you want to specify uncorrelated parameters, use RankCorrelation = eye(Np), where Np is the number of parameters.

    Sampling method options, specified as an sdo.SampleOptions object.

    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

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

    Examples

    collapse all

    Obtain the model parameters of interest.

    load_system('sdoHydraulicCylinder');
    p  = sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','K'});

    Construct an sdo.ParameterSpace object for Ac and K.

    ps = sdo.ParameterSpace(p);

    You can use ps as an input to sdo.sample and generate samples. By default, the software specifies a uniform distribution for both parameters.

    Suppose you want to specify the normal distribution for Ac and the uniform distribution for K, with K in the [30000 70000] range. Create an sdo.ParameterSpace object specifying these distributions for Ac and K.

    pdistAc = makedist('Normal','mu',p(1).Value,'sigma',2);
    pdistK = makedist('Uniform','lower',30000,'upper',70000);
    ps1 = sdo.ParameterSpace(p,[pdistAc;pdistK]);

    Version History

    Introduced in R2014a