1%feature("docstring") OT::LowDiscrepancyExperiment
2"LowDiscrepancy experiment.
3
4Available constructors:
5    LowDiscrepancyExperiment(*size, restart*)
6
7    LowDiscrepancyExperiment(*sequence, size, restart*)
8
9    LowDiscrepancyExperiment(*sequence, distribution, size, restart*)
10
11Parameters
12----------
13size : positive int
14    Number :math:`N` of points of the sequence.
15sequence : :class:`~openturns.LowDiscrepancySequence`
16    Sequence of points :math:`(u_1, \cdots, u_N)` with low discrepancy.
17    If not specified, the sequence is a :class:`~openturns.SobolSequence`.
18distribution : :class:`~openturns.Distribution`
19    Distribution :math:`\mu` of dimension :math:`n`.
20    The low discrepancy sequence :math:`(u_1, \cdots, u_N)` is uniformly
21    distributed over :math:`[0,1]^n`. We use an iso-probabilistic transformation
22    from the independent copula of dimension :math:`n` to the given distribution.
23    The weights are all equal to :math:`1/N`.
24restart : bool
25    Flag to tell if the low discrepancy sequence must be restarted from
26    its initial state at each change of distribution or not.
27    Default is *True*: the sequence is restarted at each change of
28    distribution.
29
30Notes
31-----
32The :meth:`generate` method generates points :math:`(\Xi_i)_{i \in I}`
33according to the distribution :math:`\mu`. When the :meth:`generate`
34method is called again, the generated sample changes. In case of dependent
35marginals, the approach based on [cambou2017]_ is used.
36
37See also
38--------
39WeightedExperiment
40
41Examples
42--------
43>>> import openturns as ot
44>>> distribution = ot.ComposedDistribution([ot.Uniform(0.0, 1.0)] * 2)
45
46Generate the sample with a reinitialization of the sequence at each change
47of distribution:
48
49>>> experiment = ot.LowDiscrepancyExperiment(ot.SobolSequence(), distribution, 5, True)
50>>> print(experiment.generate())
51    [ y0    y1    ]
520 : [ 0.5   0.5   ]
531 : [ 0.75  0.25  ]
542 : [ 0.25  0.75  ]
553 : [ 0.375 0.375 ]
564 : [ 0.875 0.875 ]
57>>> print(experiment.generate())
58    [ y0     y1     ]
590 : [ 0.625  0.125  ]
601 : [ 0.125  0.625  ]
612 : [ 0.1875 0.3125 ]
623 : [ 0.6875 0.8125 ]
634 : [ 0.9375 0.0625 ]
64>>> experiment.setDistribution(distribution)
65>>> print(experiment.generate())
66    [ y0    y1    ]
670 : [ 0.5   0.5   ]
681 : [ 0.75  0.25  ]
692 : [ 0.25  0.75  ]
703 : [ 0.375 0.375 ]
714 : [ 0.875 0.875 ]
72
73Generate the sample keeping the previous state of the sequence at each change
74of distribution:
75
76>>> experiment = ot.LowDiscrepancyExperiment(ot.SobolSequence(), distribution, 5, False)
77>>> print(experiment.generate())
78    [ y0    y1    ]
790 : [ 0.5   0.5   ]
801 : [ 0.75  0.25  ]
812 : [ 0.25  0.75  ]
823 : [ 0.375 0.375 ]
834 : [ 0.875 0.875 ]
84>>> print(experiment.generate())
85    [ y0     y1     ]
860 : [ 0.625  0.125  ]
871 : [ 0.125  0.625  ]
882 : [ 0.1875 0.3125 ]
893 : [ 0.6875 0.8125 ]
904 : [ 0.9375 0.0625 ]
91>>> experiment.setDistribution(distribution)
92>>> print(experiment.generate())
93    [ y0     y1     ]
940 : [ 0.4375 0.5625 ]
951 : [ 0.3125 0.1875 ]
962 : [ 0.8125 0.6875 ]
973 : [ 0.5625 0.4375 ]
984 : [ 0.0625 0.9375 ]
99
100Generate a sample according to a distribution with dependent marginals:
101
102>>> distribution = ot.Normal([0.0]*2, ot.CovarianceMatrix(2, [4.0, 1.0, 1.0, 9.0]))
103>>> experiment = ot.LowDiscrepancyExperiment(ot.SobolSequence(), distribution, 5, False)
104>>> print(experiment.generate())
105    [ y0        y1        ]
1060 : [  0         0        ]
1071 : [  1.34898  -1.65792  ]
1082 : [ -1.34898   1.65792  ]
1093 : [ -0.637279 -1.10187  ]
1104 : [  2.3007    3.97795  ]
111"
112// ---------------------------------------------------------------------
113
114%feature("docstring") OT::LowDiscrepancyExperiment::getSequence
115"Return the sequence.
116
117Returns
118-------
119sequence : :class:`~openturns.LowDiscrepancySequence`
120    Sequence of points :math:`(u_1, \cdots, u_N)` with low discrepancy."
121
122// ---------------------------------------------------------------------
123
124%feature("docstring") OT::LowDiscrepancyExperiment::getRestart
125"Return the value of the *restart* flag.
126
127Returns
128-------
129restart : bool
130    The value of the *restart* flag."
131
132// ---------------------------------------------------------------------
133
134%feature("docstring") OT::LowDiscrepancyExperiment::setRestart
135"Set the value of the *restart* flag.
136
137Parameters
138----------
139restart : bool
140    The value of the *restart* flag. If equals to *True*, the low
141    discrepancy sequence is restarted at each change of distribution,
142    else it is changed only if the new distribution has a dimension
143    different from the current one.
144"
145
146// ---------------------------------------------------------------------
147
148%feature("docstring") OT::LowDiscrepancyExperiment::getRandomize
149"Return the value of the *randomize* flag.
150
151Returns
152-------
153randomize : bool
154    The value of the *randomize* flag."
155
156// ---------------------------------------------------------------------
157
158%feature("docstring") OT::LowDiscrepancyExperiment::setRandomize
159"Set the value of the *randomize* flag.
160
161Parameters
162----------
163randomize : bool
164    Use a cyclic scrambling of the low discrepancy sequence, it means, the whole
165    low discrepancy sequence is translated by a random vector modulo 1.
166    See [lecuyer2005]_ for the interest of such a scrambling.
167    Default is False.
168"
169