1%define OT_LowDiscrepancySequence_doc
2"Base class to generate low discrepancy sequences.
3
4Available constructors:
5    LowDiscrepancySequence(*dimension=1*)
6
7Parameters
8----------
9dimension : int
10    Dimension of the points of the low discrepancy sequence.
11
12Notes
13-----
14The low discrepancy sequences, also called 'quasi-random' sequences, are a
15deterministic alternative to random sequences for use in Monte Carlo methods.
16These sequences are sets of equidistributed points which the error in uniformity
17is measured by its discrepancy.
18
19The **discrepancy** of a set :math:`P = \{x_1, \hdots, x_N\}` is defined,
20using Niederreiter's notation, as:
21
22.. math::
23
24    D_N(P) = \sup_{B\in J} \left| \frac{A(B;P)}{N} - \lambda_s(B) \right|
25
26where :math:`\lambda_s` is the s-dimensional Lebesgue measure, :math:`A(B;P)`
27is the number of points in :math:`P` that fall into :math:`B`, and :math:`J` is
28the set of s-dimensional intervals or boxes of the form:
29
30.. math::
31
32    \prod_{i=1}^s [a_i, b_i) = \{ \mathbf{x} \in \mathbf{R}^s : a_i \le x_i < b_i \} \,
33
34where :math:`0 \le a_i < b_i \le 1`.
35
36The star-discrepancy :math:`D_N^*(P)` is defined similarly, except that the
37supremum is taken over the set :math:`J^*` of intervals of the form:
38
39.. math::
40
41    \prod_{i=1}^s [0, u_i)
42
43where :math:`u_i` is in the half-open interval :math:`[0, 1)`.
44
45A low-discrepancy sequence can be generated only through the derived classes of
46LowDiscrepancySequence. The sequences implemented are
47:class:`Faure <openturns.FaureSequence>`,
48:class:`Halton <openturns.HaltonSequence>`,
49:class:`Reverse Halton <openturns.ReverseHaltonSequence>`,
50:class:`Haselgrove <openturns.HaselgroveSequence>` and
51:class:`Sobol <openturns.SobolSequence>` sequences.
52
53Examples
54--------
55>>> import openturns as ot
56>>> # Create a sequence of 3 points of 2 dimensions
57>>> sequence = ot.LowDiscrepancySequence(ot.SobolSequence(2))
58>>> print(sequence.generate(3))
590 : [ 0.5  0.5  ]
601 : [ 0.75 0.25 ]
612 : [ 0.25 0.75 ]"
62%enddef
63%feature("docstring") OT::LowDiscrepancySequenceImplementation
64OT_LowDiscrepancySequence_doc
65
66// ---------------------------------------------------------------------
67
68%define OT_LowDiscrepancySequence_computeStarDiscrepancy_doc
69"Compute the star discrepancy of a sample uniformly distributed over [0, 1).
70
71Parameters
72----------
73sample : 2-d sequence of float
74
75Returns
76-------
77starDiscrepancy : float
78    Star discrepancy of a sample uniformly distributed over [0, 1).
79
80Examples
81--------
82>>> import openturns as ot
83>>> # Create a sequence of 3 points of 2 dimensions
84>>> sequence = ot.LowDiscrepancySequence(ot.SobolSequence(2))
85>>> sample = sequence.generate(16)
86>>> print(sequence.computeStarDiscrepancy(sample))
870.12890625
88>>> sample = sequence.generate(64)
89>>> print(sequence.computeStarDiscrepancy(sample))
900.0537109375"
91%enddef
92%feature("docstring") OT::LowDiscrepancySequenceImplementation::ComputeStarDiscrepancy
93OT_LowDiscrepancySequence_computeStarDiscrepancy_doc
94
95// ---------------------------------------------------------------------
96
97%define OT_LowDiscrepancySequence_generate_doc
98"Generate a sample of pseudo-random vectors of numbers uniformly distributed over [0, 1).
99
100Parameters
101----------
102size : int
103    Number of points to be generated. Default is 1.
104
105Returns
106-------
107sample : :class:`~openturns.Sample`
108    Sample of pseudo-random vectors of numbers uniformly distributed over
109    [0, 1).
110
111Examples
112--------
113>>> import openturns as ot
114>>> # Create a sequence of 3 points of 2 dimensions
115>>> sequence = ot.LowDiscrepancySequence(ot.SobolSequence(2))
116>>> print(sequence.generate(3))
1170 : [ 0.5  0.5  ]
1181 : [ 0.75 0.25 ]
1192 : [ 0.25 0.75 ]"
120%enddef
121%feature("docstring") OT::LowDiscrepancySequenceImplementation::generate
122OT_LowDiscrepancySequence_generate_doc
123
124// ---------------------------------------------------------------------
125
126%define OT_LowDiscrepancySequence_getDimension_doc
127"Accessor to the dimension of the points of the low discrepancy sequence.
128
129Returns
130-------
131dimension : int
132    Dimension of the points of the low discrepancy sequence."
133%enddef
134%feature("docstring") OT::LowDiscrepancySequenceImplementation::getDimension
135OT_LowDiscrepancySequence_getDimension_doc
136
137// ---------------------------------------------------------------------
138
139%define OT_LowDiscrepancySequence_initialize_doc
140"Initialize the sequence.
141
142Parameters
143----------
144dimension : int
145    Dimension of the points of the low discrepancy sequence.
146
147Examples
148--------
149>>> import openturns as ot
150>>> # Create a sequence of 3 points of 2 dimensions
151>>> sequence = ot.LowDiscrepancySequence(ot.SobolSequence(2))
152>>> print(sequence.generate(3))
1530 : [ 0.5  0.5  ]
1541 : [ 0.75 0.25 ]
1552 : [ 0.25 0.75 ]
156>>> print(sequence.generate(3))
1570 : [ 0.375 0.375 ]
1581 : [ 0.875 0.875 ]
1592 : [ 0.625 0.125 ]
160>>> sequence.initialize(2)
161>>> print(sequence.generate(3))
1620 : [ 0.5  0.5  ]
1631 : [ 0.75 0.25 ]
1642 : [ 0.25 0.75 ]"
165%enddef
166%feature("docstring") OT::LowDiscrepancySequenceImplementation::initialize
167OT_LowDiscrepancySequence_initialize_doc
168
169// ---------------------------------------------------------------------
170
171%define OT_LowDiscrepancySequence_getScramblingState_doc
172"Accessor to the linear congruential generator (LCG) used to scramble the sequences.
173
174Returns
175-------
176state : int
177    The state of the LCG, defined by the recursion :math:`x_{n+1}=(2862933555777941757 * x_n + 3037000493)\mbox{ mod }2^{64}`."
178%enddef
179%feature("docstring") OT::LowDiscrepancySequenceImplementation::getScramblingState
180OT_LowDiscrepancySequence_getScramblingState_doc
181
182// ---------------------------------------------------------------------
183
184%define OT_LowDiscrepancySequence_setScramblingState_doc
185"Accessor to the linear congruential generator (LCG) used to scramble the sequences.
186
187Parameters
188----------
189state : int
190    The state of the LCG, defined by the recursion :math:`x_{n+1}=2862933555777941757 * x_n + 3037000493\mbox{ mod }2^{64}`."
191
192%enddef
193%feature("docstring") OT::LowDiscrepancySequenceImplementation::setScramblingState
194OT_LowDiscrepancySequence_setScramblingState_doc
195