Main Content

addParameter

Add parameter to sdo.ParameterSpace or sdo.GriddedSpace object

    Description

    ps = addParameter(ps0,p) adds the model parameters specified in p to an sdo.ParameterSpace or sdo.GriddedSpace parameter space and returns the updated parameter space.

    example

    ps = addParameter(ps0,p,pdist) specifies the probability distributions of parameters in p. Use this syntax when adding parameters to an sdo.ParameterSpace object.

    example

    ps = addParameter(ps0,p,values) specifies allowed values for the parameters in p. Use this syntax when adding parameters to an sdo.GriddedSpace object. (since R2023a)

    example

    Examples

    collapse all

    Create an sdo.ParameterSpace object, ps, for the Ac parameter of the sdoHydraulicCylinder model.

    load_system('sdoHydraulicCylinder');
    pAc = sdo.getParameterFromModel('sdoHydraulicCylinder','Ac');
    ps = sdo.ParameterSpace(pAc);

    Add the K parameter to ps.

    pK = sdo.getParameterFromModel('sdoHydraulicCylinder','K');
    ps = addParameter(ps,pK);

    Create an sdo.ParameterSpace object for the Ac and C1 parameters of the sdoHydraulicCylinder model.

    load_system('sdoHydraulicCylinder');
    p = sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','C1'});
    ps = sdo.ParameterSpace(p);

    Add the K parameter to ps. Specify a normal distribution for K.

    pK = sdo.getParameterFromModel('sdoHydraulicCylinder','K');
    pKdist = makedist('Normal','mu',pK.Value,'sigma',2);
    ps = addParameter(ps,pK,pKdist);

    Since R2023a

    Open the sdoCSTR model and extract continuous parameters A and h. Assign values to these parameters for gridded sampling and define the parameter space.

    mdl = "sdoCSTR";
    open_system(mdl);
    p1 = sdo.getParameterFromModel(mdl,{'A','h'});
    Avals = {0.2 0.6 1.0 1.4 1.8 2.2};
    hvals = {0.5 1.5 2.5 3.5};
    ps0 = sdo.GriddedSpace(p1,{Avals,hvals});

    The sdoCSTR model also contains parameters FeedCon0 and FeedTemp0. Extract these parameters and define grid values for them.

    p2 = sdo.getParameterFromModel(mdl,{'FeedCon0','FeedTemp0'});
    Convals = {9.5 10.0 10.5};
    Tempvals = {250,275,300};

    Add these parameters to the gridded parameter space.

    ps = addParameter(ps0,p2,{Convals,Tempvals})
    ps = 
      GriddedSpace with properties:
    
        ParameterValues: {{1x4 cell}  {1x4 cell}  {1x4 cell}  {1x4 cell}}
                  Notes: []
                 Spaces: {1x0 cell}
         ParameterNames: {'A'  'h'  'FeedCon0'  'FeedTemp0'}
                Options: [1x1 sdo.GriddingOptions]
    
    

    addParameter updates the ParameterNames and ParameterValues properties to reflect the new parameters.

    Input Arguments

    collapse all

    Parameter space to add parameters to, specified as an sdo.ParameterSpace or sdo.GriddedSpace object.

    Parameters to add to the parameter space, specified as a param.Continuous object, a param.Discrete object, or a vector of parameter objects.

    • If ps0 is a sdo.ParameterSpace object, then p must contain only continuous parameters (param.Continuous).

    • If ps0 is a sdo.GriddedSpace object, then p can contain continuous parameters (param.Continuous) or discrete parameters (param.Discrete).

    Usually, you obtain ps0 using sdo.getParameterFromModel or sdo.getStateFromModel.

    Probability distribution of parameter values, specified as a univariate probability distribution object or a vector of univariate probability distribution objects. Use this argument when adding parameters for random sampling to an sdo.ParameterSpace object.

    • If pdist is a vector of the same length as p, the software uses each entry of pdist as the probability distribution of the corresponding parameter in p.

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

    Use makedist to create a univariate probability distribution object. For example, makedist('Normal','mu',10,'sigma',3).

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

    Since R2023a

    Parameter values for gridded sampling, 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}}. Use this argument when adding parameters for gridded sampling to an sdo.GriddedSpace object.

    Output Arguments

    collapse all

    Updated parameter space, returned as an sdo.ParameterSpace or sdo.GriddedSpace object. addParameter adds the parameter or parameters specified in p, setting ps.ParameterNames to reflect the names of the added parameters. The function also updates the possible values for the new parameters depending on the type of parameter space.

    If ps0 is an sdo.ParameterSpace object:

    • If you specify the pdist input argument, then addParameter sets ps.ParameterDistributions to reflect the specified distributions for the new parameters.

    • If you do not specify parameter distributions, then addParameter sets ps.ParameterDistributions with the default uniform distributions for the new parameters, setting the properties of the uniform distributions as follows for each parameter in p:

      • Lower — Set to p.Minimum. If p.Minimum is equal to -Inf, then the software sets Lower to 0.9*p.Value. If p.Value is equal to 0, then the software sets Lower to -1.

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

    If ps0 is an sdo.GriddedSpace object:

    • If you specify the values input argument, then addParameter sets ps.ParameterValues to reflect the specified grid values for the new parameters.

    • If you do not specify values, then addParameter sets ps.ParameterValues to default values for each parameter in p as follows:

      • For each param.Continuous parameter in p, the corresponding entry in ps.ParameterValues is set to {nom-10%,nom,nom+10%}, where nom is the nonzero nominal value. If the nominal value is zero, then the default values are {-1,0,1}.

      • For each param.Discrete parameter in p, the corresponding entry in ps.ParameterValues is set to the ValueSet property of the discrete parameter.

    Tips

    • Use addParameter to add random parameters to randomly sampled parameter spaces or to add gridded parameters to gridded parameter spaces. To combine gridded parameters with random parameters, use combine.

    Version History

    Introduced in R2014a

    expand all