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