1%define OT_WeightedExperiment_doc
2"Weighted experiment.
3
4Available constructor:
5    WeightedExperiment(*distribution=ot.Uniform(), size=100*)
6
7Parameters
8----------
9distribution : :class:`~openturns.Distribution`
10    Distribution :math:`\mu` used to generate the set of input data.
11size : positive int
12    Number :math:`cardI` of points that will be generated in the experiment.
13
14Notes
15-----
16WeightedExperiment is used to generate the points :math:`\Xi_i` so that the
17mean :math:`E_{\mu}` is approximated as follows:
18
19.. math::
20
21    \Expect{ f(\vect{Z})}_{\mu} \simeq \sum_{i \in I} \omega_i f(\Xi_i)
22
23where :math:`\mu` is a distribution, :math:`f` is a function :math:`L_1(\mu)`
24and :math:`\omega_i` are the weights associated with the points. By default,
25all the weights are equal to :math:`1/cardI`.
26
27A WeightedExperiment object can be created only through its derived classes
28which are distributed in three groups:
29
301. The first category is made up of the random patterns, where the set of input
31   data is generated from the joint distribution of the input random vector,
32   according to these sampling techniques:
33
34   - :class:`Monte Carlo <openturns.MonteCarloExperiment>`
35
36   - :class:`LHS <openturns.LHSExperiment>`
37
38   - :class:`Bootstrap <openturns.BootstrapExperiment>`
39
40   - :class:`Importance Sampling <openturns.ImportanceSamplingExperiment>`
41
422. The second category contains the :class:`low discrepancy sequences
43   <openturns.LowDiscrepancySequence>`. OpenTURNS proposes the Faure, Halton,
44   Haselgrove, Reverse Halton and Sobol sequences.
45
463. The third category consists of deterministic patterns:
47
48   - :class:`Gauss product <openturns.GaussProductExperiment>`
49
50   - :class:`~openturns.FixedExperiment`
51
52   - :class:`~openturns.LowDiscrepancyExperiment`"
53%enddef
54%feature("docstring") OT::WeightedExperimentImplementation
55OT_WeightedExperiment_doc
56
57// ---------------------------------------------------------------------
58
59%define OT_WeightedExperiment_generate_doc
60"Generate points according to the type of the experiment.
61
62Returns
63-------
64sample : :class:`~openturns.Sample`
65    Points :math:`(\Xi_i)_{i \in I}` which constitute the design of experiments
66    with :math:`card I = size`. The sampling method is defined by the nature of
67    the weighted experiment.
68
69Examples
70--------
71>>> import openturns as ot
72>>> ot.RandomGenerator.SetSeed(0)
73>>> myExperiment = ot.MonteCarloExperiment(ot.Normal(2), 5)
74>>> sample = myExperiment.generate()
75>>> print(sample)
76    [ X0        X1        ]
770 : [  0.608202 -1.26617  ]
781 : [ -0.438266  1.20548  ]
792 : [ -2.18139   0.350042 ]
803 : [ -0.355007  1.43725  ]
814 : [  0.810668  0.793156 ]"
82%enddef
83%feature("docstring") OT::WeightedExperimentImplementation::generate
84OT_WeightedExperiment_generate_doc
85
86// ---------------------------------------------------------------------
87
88%define OT_WeightedExperiment_generateWithWeights_doc
89"Generate points and their associated weight according to the type of the experiment.
90
91Returns
92-------
93sample : :class:`~openturns.Sample`
94    The points which constitute the design of experiments. The sampling method
95    is defined by the nature of the experiment.
96weights : :class:`~openturns.Point` of size :math:`cardI`
97    Weights :math:`(\omega_i)_{i \in I}` associated with the points. By default,
98    all the weights are equal to :math:`1/cardI`.
99
100Examples
101--------
102>>> import openturns as ot
103>>> ot.RandomGenerator.SetSeed(0)
104>>> myExperiment = ot.MonteCarloExperiment(ot.Normal(2), 5)
105>>> sample, weights = myExperiment.generateWithWeights()
106>>> print(sample)
107    [ X0        X1        ]
1080 : [  0.608202 -1.26617  ]
1091 : [ -0.438266  1.20548  ]
1102 : [ -2.18139   0.350042 ]
1113 : [ -0.355007  1.43725  ]
1124 : [  0.810668  0.793156 ]
113>>> print(weights)
114[0.2,0.2,0.2,0.2,0.2]"
115%enddef
116%feature("docstring") OT::WeightedExperimentImplementation::generateWithWeights
117OT_WeightedExperiment_generateWithWeights_doc
118
119// ---------------------------------------------------------------------
120
121%define OT_WeightedExperiment_getDistribution_doc
122"Accessor to the distribution.
123
124Returns
125-------
126distribution : :class:`~openturns.Distribution`
127    Distribution used to generate the set of input data."
128%enddef
129%feature("docstring") OT::WeightedExperimentImplementation::getDistribution
130OT_WeightedExperiment_getDistribution_doc
131
132// ---------------------------------------------------------------------
133
134%define OT_WeightedExperiment_setDistribution_doc
135"Accessor to the distribution.
136
137Parameters
138----------
139distribution : :class:`~openturns.Distribution`
140    Distribution used to generate the set of input data."
141%enddef
142%feature("docstring") OT::WeightedExperimentImplementation::setDistribution
143OT_WeightedExperiment_setDistribution_doc
144
145// ---------------------------------------------------------------------
146
147%define OT_WeightedExperiment_getSize_doc
148"Accessor to the size of the generated sample.
149
150Returns
151-------
152size : positive int
153    Number :math:`cardI` of points constituting the design of experiments."
154%enddef
155%feature("docstring") OT::WeightedExperimentImplementation::getSize
156OT_WeightedExperiment_getSize_doc
157
158// ---------------------------------------------------------------------
159
160%define OT_WeightedExperiment_setSize_doc
161"Accessor to the size of the generated sample.
162
163Parameters
164----------
165size : positive int
166    Number :math:`cardI` of points constituting the design of experiments."
167%enddef
168%feature("docstring") OT::WeightedExperimentImplementation::setSize
169OT_WeightedExperiment_setSize_doc
170
171// ---------------------------------------------------------------------
172
173%define OT_WeightedExperiment_hasUniformWeights_doc
174"Ask whether the experiment has uniform weights.
175
176Returns
177-------
178hasUniformWeights : bool
179    Whether the experiment has uniform weights."
180%enddef
181%feature("docstring") OT::WeightedExperimentImplementation::hasUniformWeights
182OT_WeightedExperiment_hasUniformWeights_doc
183