addParameter

Add parameter to sdo.ParameterSpace or sdo.GriddedSpace object

Syntax

ps = addParameter(ps0,p)

ps = addParameter(ps0,p,pdist)

ps = addParameter(ps0,p,values)

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.

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

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)

Examples

Add Parameters to Parameter Space Object

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);

Add Parameter with Specified Distribution to Parameter Space Object

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);

Add Parameters to Gridded Parameter Space

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: {{1×6 cell}  {1×4 cell}  {1×3 cell}  {1×3 cell}}
              Notes: []
             Spaces: {1×0 cell}
     ParameterNames: {'A'  'h'  'FeedCon0'  'FeedTemp0'}
            Options: [1×1 sdo.GriddingOptions]

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

Input Arguments

ps0 — Parameter space

sdo.ParameterSpace object | sdo.GriddedSpace object

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

p — Parameters to add

param.Continuous object | param.Discrete object | vector of parameter objects

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.

pdist — Probability distribution of parameter values

probability distribution object | vector of probability distribution objects

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').

values — Parameter values for gridded sampling

cell array of cell arrays

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

ps — Updated parameter space

sdo.ParameterSpace object | sdo.GriddedSpace object

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

R2023a: Add parameters to gridded parameter space

The new syntax ps = addParameter(ps0,p,values) lets you add parameters with the specified grid values to a gridded parameter space (sdo.GriddedSpace).