1%feature("docstring") OT::LHSExperiment
2"LHS experiment.
3
4Available constructors:
5    LHSExperiment(*size, alwaysShuffle, randomShift*)
6
7    LHSExperiment(*distribution, size, alwaysShuffle, randomShift*)
8
9Parameters
10----------
11distribution : :class:`~openturns.Distribution`
12    Distribution :math:`\mu` with an independent copula used to generate the
13    set of input data.
14size : positive int
15    Number :math:`\mathrm{card}\,I` of points that will be generated in the experiment.
16alwaysShuffle : bool
17    Flag to tell if the shuffle must be regenerated at each call to generate
18    or not.
19    Default is *False*: the shuffle is generated once and for all.
20
21randomShift : bool
22    Flag to tell if the point selected in each cell of the shuffle is the center
23    of the cell (*randomshift* is *False*) or if it is drawn wrt the restriction
24    of the distribution to the cell.
25    Default is *True*.
26
27Notes
28-----
29LHSExperiment is a random weighted design of experiments.
30The method generates a sample of points :math:`\Xi_i` according to the
31distribution :math:`\mu` with the LHS technique: some cells are determined,
32with the same probabilistic content according to the distribution, each line
33and each column contains exactly one cell, then points are selected among these
34selected cells. The weights associated to the points are all equal to
35:math:`1/\mathrm{card}\,I`. When recalled, the :meth:`generate` method generates a new
36sample: the point selection within the cells changes but not the cells
37selection. To change the cell selection, it is necessary to create a new LHS
38Experiment.
39
40See also
41--------
42WeightedExperiment
43
44Examples
45--------
46Create an *LHSExperiment*:
47
48>>> import openturns as ot
49
50Generate the sample reusing the initial shuffle and using a random shift:
51
52>>> ot.RandomGenerator.SetSeed(0)
53>>> experiment = ot.LHSExperiment(ot.Normal(2), 5, False, True)
54>>> print(experiment.generate())
55    [ X0        X1        ]
560 : [  0.887671 -0.647818 ]
571 : [  0.107683  1.15851  ]
582 : [  0.453077 -1.04742  ]
593 : [ -0.928012  0.409732 ]
604 : [ -0.290539  0.16153  ]
61>>> print(experiment.generate())
62    [ X0         X1         ]
630 : [  1.52938   -0.343515  ]
641 : [ -0.0703427  2.36353   ]
652 : [  0.576091  -1.79398   ]
663 : [ -2.11636    0.619315  ]
674 : [ -0.699601  -0.0570674 ]
68
69Generate the sample using a new shuffle and a random shift:
70
71>>> ot.RandomGenerator.SetSeed(0)
72>>> experiment = ot.LHSExperiment(ot.Normal(2), 5, True, True)
73>>> print(experiment.generate())
74    [ X0        X1        ]
750 : [  0.887671 -0.647818 ]
761 : [  0.107683  1.15851  ]
772 : [  0.453077 -1.04742  ]
783 : [ -0.928012  0.409732 ]
794 : [ -0.290539  0.16153  ]
80>>> print(experiment.generate())
81    [ X0         X1         ]
820 : [ -1.72695   -0.591043  ]
831 : [ -0.240653  -0.0406593 ]
842 : [  0.828719   2.12547   ]
853 : [  2.37061    0.508903  ]
864 : [ -0.668296  -1.11573   ]
87
88Generate the sample reusing the initial shuffle and using a constant shift:
89
90>>> ot.RandomGenerator.SetSeed(0)
91>>> experiment = ot.LHSExperiment(ot.Normal(2), 5, False, False)
92>>> print(experiment.generate())
93    [ X0        X1        ]
940 : [  1.28155  -0.524401 ]
951 : [  0         1.28155  ]
962 : [  0.524401 -1.28155  ]
973 : [ -1.28155   0.524401 ]
984 : [ -0.524401  0        ]
99>>> print(experiment.generate())
100    [ X0        X1        ]
1010 : [  1.28155  -0.524401 ]
1021 : [  0         1.28155  ]
1032 : [  0.524401 -1.28155  ]
1043 : [ -1.28155   0.524401 ]
1054 : [ -0.524401  0        ]
106
107Generate the sample using a new shuffle and using a constant shift:
108
109>>> ot.RandomGenerator.SetSeed(0)
110>>> experiment = ot.LHSExperiment(ot.Normal(2), 5, True, False)
111>>> print(experiment.generate())
112    [ X0        X1        ]
1130 : [  1.28155  -0.524401 ]
1141 : [  0         1.28155  ]
1152 : [  0.524401 -1.28155  ]
1163 : [ -1.28155   0.524401 ]
1174 : [ -0.524401  0        ]
118>>> print(experiment.generate())
119    [ X0        X1        ]
1200 : [  0.524401 -0.524401 ]
1211 : [  0         1.28155  ]
1222 : [ -1.28155   0        ]
1233 : [ -0.524401  0.524401 ]
1244 : [  1.28155  -1.28155  ]
125"
126// ---------------------------------------------------------------------
127
128%feature("docstring") OT::LHSExperiment::getShuffle
129"Return the cell randomization.
130
131Returns
132-------
133shuffle : :class:`~openturns.Matrix`
134    For each point, the indices of the shuffled components."
135
136// ---------------------------------------------------------------------
137
138%feature("docstring") OT::LHSExperiment::ComputeShuffle
139"Generate a new cell randomization for external use.
140
141Parameters
142----------
143dimension : positive int
144    Number of input dimension.
145totalSize : positive int
146    Number :math:`\mathrm{card}\,I` of points that need to be shuffled.
147
148Returns
149-------
150shuffle : :class:`~openturns.Matrix`
151    For each point, the indices of the shuffled components."
152
153// ---------------------------------------------------------------------
154
155%feature("docstring") OT::LHSExperiment::getAlwaysShuffle
156"Cell randomization flag accessor.
157
158Returns
159-------
160alwaysShuffle : bool
161    Flag to tell if the shuffle must be regenerated at each call to generate
162    or not.
163    Default is *False*: the shuffle is generated once and for all."
164
165// ---------------------------------------------------------------------
166
167%feature("docstring") OT::LHSExperiment::setAlwaysShuffle
168"Cell randomization flag accessor.
169
170Parameters
171----------
172alwaysShuffle : bool
173    Flag to tell if the shuffle must be regenerated at each call to generate
174    or not.
175    Default is *False*: the shuffle is generated once and for all."
176
177// ---------------------------------------------------------------------
178
179%feature("docstring") OT::LHSExperiment::setRandomShift
180"Randomization flag accessor.
181
182Parameters
183----------
184randomShift : bool
185    Flag to tell if the point selected in each cell of the shuffle is the center
186    of the cell (*randomshift* is *False*) or if it is drawn wrt the restriction
187    of the distribution to the cell.
188    Default is *True*."
189
190// ---------------------------------------------------------------------
191
192%feature("docstring") OT::LHSExperiment::getRandomShift
193"Randomization flag accessor.
194
195Returns
196-------
197randomShift : bool
198    Flag to tell if the point selected in each cell of the shuffle is the center
199    of the cell (*randomshift* is *False*) or if it is drawn wrt the restriction
200    of the distribution to the cell.
201    Default is *True*."
202