1%perlcode %{
2
3use strict;
4use warnings;
5use Carp qw/croak/;
6use Math::GSL::Errno qw/$GSL_SUCCESS/;
7
8our @EXPORT_OK = qw($gsl_qrng_niederreiter_2 $gsl_qrng_sobol
9                    $gsl_qrng_halton $gsl_qrng_reversehalton
10                gsl_qrng_alloc gsl_qrng_memcpy gsl_qrng_clone
11                gsl_qrng_free  gsl_qrng_init gsl_qrng_name
12                gsl_qrng_size gsl_qrng_state gsl_qrng_get
13            );
14our %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
15
16=encoding utf8
17
18=head1 NAME
19
20Math::GSL::QRNG - Quasi-random number generators
21
22=head1 SYNOPSIS
23
24    # use OO approach
25    use Math::GSL::QRNG;
26
27    my $QRNG = Math::GSL::QRNG::Sobol->new(2);
28    my @samples = $QRNG->get();
29
30    # use GSL interface
31    use Math::GSL::QRNG qw/:all/;
32
33=head1 DESCRIPTION
34
35This module interfaces with GNU Scientific Library quasi-random number generators (QRNG).
36
37=head1 OO Interface
38
39The OO Interface described in this documentation is available to all
40different subclasses, namely:
41
42=over
43
44=item Math::GSL::QRNG::Sobol
45
46=item Math::GSL::QRNG::Niederreiter2
47
48=item Math::GSL::QRNG::Halton
49
50=item Math::GSL::QRNG::ReverseHalton
51
52=back
53
54=cut
55
56sub _init {
57	my ($self, $qrng, $dimension) = @_;
58	$self->{qrng} = gsl_qrng_alloc($qrng, $dimension);
59	return $self;
60}
61
62=head2 reinit
63
64Reinitializes the generator to its starting point. Note that quasi-random
65sequences do not use a seed and always produce the same set of values.
66
67	$qrng->reinit();
68
69=cut
70
71sub reinit {
72	my $self = shift;
73	gsl_qrng_init($self->{qrng});
74}
75
76=head2 get
77
78Retrieves the next point from the sequence generator.
79Returns C<undef> on error.
80
81	my @points = $qrng->get();
82
83=cut
84
85sub get {
86	my $self = shift;
87	my ($status, @values) = gsl_qrng_get($self->{qrng});
88	return $status == $GSL_SUCCESS ? @values : undef;
89}
90
91=head2 name
92
93Retrieves the QRNG name.
94
95    my $name = $qrng->name();
96
97=cut
98
99sub name {
100	my $self = shift;
101	return gsl_qrng_name($self->{qrng});
102}
103
104=head2 state_size
105
106Returns the size of the QRNG state.
107
108=cut
109
110sub state_size {
111	my $self = shift;
112	return gsl_qrng_size($self->{qrng});
113}
114
115=head2 clone
116
117Returns an exact copy of the current QRNG.
118
119=cut
120
121sub clone {
122	my $self = shift;
123	my $new = { qrng => gsl_qrng_clone($self->{qrng})};
124	return bless $new, ref($self);
125}
126
127### gsl_qrng_state => TODO
128### gsl_qrng_memcpy => ignore?
129
130=head1 GSL API
131
132Here is a list of all the functions included in this module :
133
134=over
135
136=item C<gsl_qrng_alloc($T, $n)> - This function returns a pointer to a newly-created instance of a quasi-random sequence generator of type $T and dimension $d. The type $T must be one of the constants included in this module.
137
138=item C<gsl_qrng_clone($q)> - This function returns a pointer to a newly created generator which is an exact copy of the generator $q.
139
140=item C<gsl_qrng_memcpy($dest, $src)> - This function copies the quasi-random sequence generator $src into the pre-existing generator $dest, making $dest into an exact copy of $src. The two generators must be of the same type.
141
142=item C<gsl_qrng_free($q)> - This function frees all the memory associated with the generator $q.
143Don't call this function explicitly. It will be called automatically in DESTROY.
144
145=item C<gsl_qrng_init($q)> - This function reinitializes the generator $q to its starting point. Note that quasi-random sequences do not use a seed and always produce the same set of values.
146
147=item C<gsl_qrng_name($q)> - This function returns a pointer to the name of the generator $q.
148
149=item C<gsl_qrng_size($q)> - This function returns the size of the state of generator r from the generator $q. You can use this information to access the state directly.
150
151=item C<gsl_qrng_state($q)> - This function returns a pointer to the state of generator r from the generator $q. You can use this information to access the state directly.
152
153=item C<gsl_qrng_get>
154
155=back
156
157This module also contains the following constants :
158
159=over
160
161=item C<$gsl_qrng_niederreiter_2>
162
163=item C<$gsl_qrng_sobol>
164
165=item C<$gsl_qrng_halton>
166
167=item C<$gsl_qrng_reversehalton>
168
169=back
170
171For more informations on the functions, we refer you to the GSL official documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
172
173
174
175
176=head1 EXAMPLES
177
178=head1 AUTHORS
179
180Jonathan "Duke" Leto <jonathan@leto.net>
181Thierry Moisan <thierry.moisan@gmail.com>
182Alberto Simões <ambs@cpan.org>
183
184=head1 COPYRIGHT AND LICENSE
185
186Copyright (C) 2008-2021 Jonathan "Duke" Leto and Thierry Moisan
187
188This program is free software; you can redistribute it and/or modify it
189under the same terms as Perl itself.
190
191=cut
192
193
194package Math::GSL::QRNG::Sobol;
195use parent 'Math::GSL::QRNG';
196sub new {
197	my ($class, $dimension) = @_;
198
199	croak (__PACKAGE__.'::new($d) - supported dimensions are positive up to 40.')
200		if $dimension < 1 or $dimension > 40;
201
202	my $self = bless {}, $class;
203	$self->SUPER::_init($Math::GSL::QRNG::gsl_qrng_sobol, $dimension);
204	return $self;
205}
206
207# gsl_qrng_halton
208
209package Math::GSL::QRNG::Halton;
210use parent 'Math::GSL::QRNG';
211sub new {
212	my ($class, $dimension) = @_;
213
214	croak (__PACKAGE__.'::new($d) - supported dimensions are positive up to 1229.')
215		if $dimension < 1 or $dimension > 1229;
216
217	my $self = bless {}, $class;
218	$self->SUPER::_init($Math::GSL::QRNG::gsl_qrng_halton, $dimension);
219	return $self;
220}
221
222# gsl_qrng_reversehalton
223package Math::GSL::QRNG::ReverseHalton;
224use parent 'Math::GSL::QRNG';
225sub new {
226	my ($class, $dimension) = @_;
227
228	croak (__PACKAGE__.'::new($d) - supported dimensions are positive up to 1229.')
229		if $dimension < 1 or $dimension > 1229;
230
231	my $self = bless {}, $class;
232	$self->SUPER::_init($Math::GSL::QRNG::gsl_qrng_reversehalton, $dimension);
233	return $self;
234}
235
236# gsl_qrng_niederreiter_2
237package Math::GSL::QRNG::Niederreiter2;
238use parent 'Math::GSL::QRNG';
239sub new {
240	my ($class, $dimension) = @_;
241
242	croak (__PACKAGE__.'::new($d) - supported dimensions are positive up to 12.')
243		if $dimension < 1 or $dimension > 12;
244
245	my $self = bless {}, $class;
246	$self->SUPER::_init($Math::GSL::QRNG::gsl_qrng_niederreiter_2, $dimension);
247	return $self;
248}
249
250__END__
251
252
253%}
254
255