sdo.sample
Generate parameter samples for sensitivity analysis
Description
generates samples using the specified parameter space definition,
x
= sdo.sample(ps
)ps
.
If
ps
is ansdo.ParameterSpace
object, thensdo.sample
returns a table of samples drawn from the probability distributions specified in theParameterDistributions
,RankCorrelation
, andOptions
properties ofps
.If
ps
is ansdo.GriddedSpace
containing only gridded parameters, thensdo.sample
generates samples across the specified grid.If
ps
is ansdo.GriddedSpace
containing a random-parameter subspace, thensdo.sample
generates a mixture of gridded and random samples.
specifies the number of random samples to generate.x
= sdo.sample(ps
,N
)
If
ps
is ansdo.ParameterSpace
object, thenx
is a table withN
rows andNp
columns, whereNp
is the number of parameters inps
.If
ps
is ansdo.GriddedSpace
containing only gridded parameters, thensdo.sample
ignoresN
and returns samples across the grid as specified in the gridding options ofps
.If
ps
is ansdo.GriddedSpace
containing a random-parameter subspace, thensdo.sample
generatesN
samples for each random parameter and combines them with the gridded parameters, as specified in the gridding options.
Examples
Generate Parameter Samples
Open the model.
open_system('sdoHydraulicCylinder');
Obtain the parameters from the model.
p = sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','K'});
Create an sdo.ParameterSpace
object to specify the sample distributions.
ps = sdo.ParameterSpace(p);
Generate samples for the parameters.
x = sdo.sample(ps);
Specify Number of Samples
Open the model.
open_system('sdoHydraulicCylinder');
Obtain the parameters from the model.
p = sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','K'});
Create an sdo.ParameterSpace
object to specify the sample distributions.
ps = sdo.ParameterSpace(p);
Generate 50 samples for the parameters.
x = sdo.sample(ps,50);
Exhaustive Sampling Across a Grid of Parameter Values
Since R2023a
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)
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);
Generate Samples with Both Gridded and Random Parameters
Since R2023a
If your model contains some parameters you want to sample across a grid and others from which you want to draw random samples, you can combine gridded and random parameter spaces.
This example uses the sdoCSTR
model discussed in detail in Design Exploration Using Parameter Sampling (Code). Open the model.
mdl = "sdoCSTR";
open_system(mdl)
Among the parameters in this model are the reactor cylinder area A
, height h
, and the feed temperature and concentration, FeedCon0
and FeedTemp0
. Suppose that you want to explore the sensitivity of your design constraint to these four parameters, sampling across a grid of A
and h
values while drawing FeedCon0
and FeedTemp0
from random distributions.
First, define a gridded parameter space for A
and h
. Use sdo.getParameterFromModel
to create an array of param.Continuous
objects representing A
and h
. Then, specify values for the grid, and create the parameter space.
pg = sdo.getParameterFromModel(mdl,{'A','h'}); Avals = {0.2 0.6 1.0 1.4 1.8}; hvals = {0.5 1.5 2.5}; gspace = sdo.GriddedSpace(pg,{Avals,hvals});
Next, define a random parameter space for FeedCon0
and FeedTemp0
. Create an array of param.Continuous
objects and specify the probability distributions for each parameter. For this example, assign both variables a normal distribution where the mean is the current parameter value in the model and the variance is 5% of the mean. Then, create the parameter space.
pr = sdo.getParameterFromModel(mdl,{'FeedCon0','FeedTemp0'}); distCon = makedist('normal',pr(1).Value,0.05*pr(1).Value); distTemp = makedist('normal',pr(2).Value,0.05*pr(2).Value); rspace = sdo.ParameterSpace(pr); rspace = setDistribution(rspace,'FeedCon0',distCon); rspace = setDistribution(rspace,'FeedTemp0',distTemp);
Finally, combine the two parameter spaces into a new parameter space.
cspace = combine(gspace,rspace)
cspace = GriddedSpace with properties: ParameterValues: {{1x4 cell} {1x4 cell} [1x1 prob.NormalDistribution] [1x1 prob.NormalDistribution]} Notes: [] Spaces: {[1x1 sdo.GriddedSpace] [1x1 sdo.ParameterSpace]} ParameterNames: {'A' 'h' 'FeedCon0' 'FeedTemp0'} Options: [1x1 sdo.GriddingOptions]
The combined space is represented by a sdo.GriddedSpace
object. The property cspace.Spaces
shows that cspace
contains the two subspaces, one gridded space and one random parameter space. The property cspace.ParameterValues
shows that the space includes the finite grid for A
and H
, and the probability distributions for the random variables FeedCon0
and FeedTemp0
.
You can now use sdo.sample
to draw sets of sampled values from the combined space. By default, the samples are exhaustive over the grid, meaning every possible combination of grid values is included in the sampled set. Suppose that for each combination, you want to sample the random parameters ten times. Provide that value to sdo.sample
in the NumSample
argument.
cspace.Options.Method = 'exhaustive';
NumSample = 10;
evalues = sdo.sample(cspace,NumSample)
evalues=150×4 table
A h FeedCon0 FeedTemp0
___ ___ ________ _________
0.2 0.5 10.269 275.09
0.6 0.5 10.269 275.09
1 0.5 10.269 275.09
1.4 0.5 10.269 275.09
1.8 0.5 10.269 275.09
0.2 1.5 10.269 275.09
0.6 1.5 10.269 275.09
1 1.5 10.269 275.09
1.4 1.5 10.269 275.09
1.8 1.5 10.269 275.09
0.2 2.5 10.269 275.09
0.6 2.5 10.269 275.09
1 2.5 10.269 275.09
1.4 2.5 10.269 275.09
1.8 2.5 10.269 275.09
0.2 0.5 10.917 339.77
⋮
Here, for each of the fifteen combinations of (A
, h
) values, sdo.sample
assigns ten random values for (Feedcon0
, FeedTemp0
), resulting in 150 sets of (A
, h
, FeedCon0
, FeedTemp0
) samples.
You can also have sdo.sample
choose only one random (FeedCon0
,FeedTemp0
) value for each (A
,h
) pair. To do so, set the sampling method of cspace
to sequential. Note that in this case, you created cspace
using a gridded space gspace
that had gspace.Options.Method = 'exhaustive'
. Thus, when you sample cspace
, the (A
,h
) pairs are still exhaustive.
cspace.Options.Method = 'sequential';
svalues = sdo.sample(cspace)
svalues=15×4 table
A h FeedCon0 FeedTemp0
___ ___ ________ _________
0.2 0.5 9.5682 296.27
0.6 0.5 10.039 273
1 0.5 9.3929 284.05
1.4 0.5 9.4432 279.34
1.8 0.5 9.9966 329.67
0.2 1.5 10.766 285.92
0.6 1.5 9.6152 306.03
1 1.5 10.186 292.16
1.4 1.5 9.8872 308.11
1.8 1.5 10.559 283.72
0.2 2.5 9.4555 274.32
0.6 2.5 10.016 274.02
1 2.5 10.276 302.2
1.4 2.5 10.55 292.38
1.8 2.5 10.772 292.11
Use values
with sdo.evalute
to evaluate your design objectives at each of the sampled parameter values. For instance, if you have defined a cost function design
, you can use values
in a call to sdo.evluate
as follows.
[yR,infoR] = sdo.evaluate(@design,p,values);
Specify Sampling Method
Open the model.
open_system('sdoHydraulicCylinder');
Obtain the parameters from the model.
p = sdo.getParameterFromModel('sdoHydraulicCylinder',{'Ac','K'});
Create an sdo.ParameterSpace
object to specify the sample distributions.
ps = sdo.ParameterSpace(p);
Specify the sampling method as Latin hypercube.
opt = sdo.SampleOptions;
opt.Method = 'lhs';
Generate 50 samples for the parameters using Latin hypercube sampling.
x = sdo.sample(ps,50,opt);
Input Arguments
ps
— Parameter space
sdo.ParameterSpace
object | sdo.GriddedSpace
Parameter space to sample, specified as an sdo.ParameterSpace
object
(for random sampling) or an sdo.GriddedSpace
object (for gridded sampling or a mixture of
random and gridded sampling).
N
— Number of random samples
positive integer
Number of random samples to generate, specified as a positive integer.
Ideally, use the smallest number of samples that yield useful results,
because each sample requires a model evaluation. As the number of parameters
increases, the number of samples needed to explore the design space
generally increases. For correlation or regression analysis, consider using
10*Np
samples, where Np
is the
number of sampled parameters.
N
applies only to randomly sampled parameters, that
is, parameters specified in an sdo.ParameterSpace
object
or an sdo.ParameterSpace
subspace of a composite sdo.GriddedSpace
object. sdo.sample
ignores N
for parameters configured for gridded
sampling and instead returns samples over the specified grid values.
Example: 100
opt
— Sampling options
sdo.SampleOptions
object | sdo.GriddingOptions
object
Sampling options, specified as an sdo.SampleOptions
or
sdo.GriddingOptions
object.
sdo.SampleOptions
— Specify the method for drawing samples from probability distributions defined in ansdo.ParameterSpace
object.sdo.GriddingOptions
— Specify the method for drawing samples from the grid of parameter values defined in ansdo.GriddedSpace
object.
Output Arguments
x
— Parameter samples
table
Parameter samples, returned as a table.
If
ps
is ansdo.ParameterSpace
object, thenx
is a table withN
rows andNp
columns, whereNp
is the number of parameters inps
. Each column corresponds to a parameter and each row corresponds to a sample of the parameters. IfN
is omitted,sdo.sample
usesN
= 2*Np + 1
.If
ps
is ansdo.GriddedSpace
containing only gridded parameters, thensdo.sample
ignoresN
and returns samples across the grid, as specified in the gridding options ofps
.If
ps
is ansdo.GriddedSpace
containing a random-parameter subspace, thensdo.sample
generatesN
samples for each random parameter and combines them with the gridded parameters, as specified in the gridding options.
Version History
Introduced in R2014aR2023a: Sample Gridded Parameter Spaces
sdo.sample
can now generate parameter samples across a grid
of values. Define the grid using sdo.GriddedSpace
. You can also use the new combine
command to combine a gridded parameter space with a random parameter space (sdo.ParameterSpace
). Such composite
parameter spaces allow sdo.sample
to draw gridded samples of
some parameters and random samples of other parameters.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)