pod/MatrixComplex.pod

   1 %perlcode %{
   2
   3 use Carp qw/croak/;
   4 use Math::GSL qw/:all/;
   5 use Math::GSL::Complex qw/:all/;
   6 use Math::GSL::Errno qw/:all/;
   7 use Math::Complex;
   8 use Data::Dumper;
   9
  10 @EXPORT_OK = qw/
  11                 gsl_matrix_complex_alloc
  12                 gsl_matrix_complex_calloc
  13                 gsl_matrix_complex_alloc_from_block
  14                 gsl_matrix_complex_alloc_from_matrix
  15                 gsl_vector_complex_alloc_row_from_matrix
  16                 gsl_vector_complex_alloc_col_from_matrix
  17                 gsl_matrix_complex_free
  18                 gsl_matrix_complex_submatrix
  19                 gsl_matrix_complex_row
  20                 gsl_matrix_complex_column
  21                 gsl_matrix_complex_diagonal
  22                 gsl_matrix_complex_subdiagonal
  23                 gsl_matrix_complex_superdiagonal
  24                 gsl_matrix_complex_subrow
  25                 gsl_matrix_complex_subcolumn
  26                 gsl_matrix_complex_view_array
  27                 gsl_matrix_complex_view_array_with_tda
  28                 gsl_matrix_complex_view_vector
  29                 gsl_matrix_complex_view_vector_with_tda
  30                 gsl_matrix_complex_const_submatrix
  31                 gsl_matrix_complex_const_row
  32                 gsl_matrix_complex_const_column
  33                 gsl_matrix_complex_const_diagonal
  34                 gsl_matrix_complex_const_subdiagonal
  35                 gsl_matrix_complex_const_superdiagonal
  36                 gsl_matrix_complex_const_subrow
  37                 gsl_matrix_complex_const_subcolumn
  38                 gsl_matrix_complex_const_view_array
  39                 gsl_matrix_complex_const_view_array_with_tda
  40                 gsl_matrix_complex_const_view_vector
  41                 gsl_matrix_complex_const_view_vector_with_tda
  42                 gsl_matrix_complex_get
  43                 gsl_matrix_complex_set
  44                 gsl_matrix_complex_ptr
  45                 gsl_matrix_complex_const_ptr
  46                 gsl_matrix_complex_set_zero
  47                 gsl_matrix_complex_set_identity
  48                 gsl_matrix_complex_set_all
  49                 gsl_matrix_complex_fread
  50                 gsl_matrix_complex_fwrite
  51                 gsl_matrix_complex_fscanf
  52                 gsl_matrix_complex_fprintf
  53                 gsl_matrix_complex_memcpy
  54                 gsl_matrix_complex_swap
  55                 gsl_matrix_complex_swap_rows
  56                 gsl_matrix_complex_swap_columns
  57                 gsl_matrix_complex_swap_rowcol
  58                 gsl_matrix_complex_transpose
  59                 gsl_matrix_complex_transpose_memcpy
  60                 gsl_matrix_complex_isnull
  61                 gsl_matrix_complex_ispos
  62                 gsl_matrix_complex_isneg
  63                 gsl_matrix_complex_add
  64                 gsl_matrix_complex_sub
  65                 gsl_matrix_complex_mul_elements
  66                 gsl_matrix_complex_div_elements
  67                 gsl_matrix_complex_scale
  68                 gsl_matrix_complex_add_constant
  69                 gsl_matrix_complex_add_diagonal
  70                 gsl_matrix_complex_get_row
  71                 gsl_matrix_complex_get_col
  72                 gsl_matrix_complex_set_row
  73                 gsl_matrix_complex_set_col
  74 /;
  75
  76 %EXPORT_TAGS = ( all => \@EXPORT_OK ,  );
  77
  78 =head1 NAME
  79
  80 Math::GSL::MatrixComplex - Complex Matrices
  81
  82 =head1 SYNOPSIS
  83
  84     use Math::GSL::MatrixComplex qw/:all/;
  85     my $matrix1 = Math::GSL::MatrixComplex->new(5,5);  # OO interface
  86     my $matrix2 = gsl_matrix_complex_alloc(5,5);        # standard interface
  87
  88
  89 =head1 Objected Oriented Interface to GSL Math::GSL::MatrixComplex
  90
  91 =head2 new()
  92
  93 Creates a new MatrixComplex object of the given size.
  94
  95     my $matrix = Math::GSL::MatrixComplex->new(10,10);
  96 =cut
  97
  98 sub new
  99 {
 100     my ($class, $rows, $cols) = @_;
 101     my $this = {};
 102     my $matrix;
 103     if ( defined $rows       && defined $cols &&
 104         $rows > 0            && $cols > 0     &&
 105         (int $rows == $rows) && (int $cols == $cols)){
 106
 107         $matrix  = gsl_matrix_complex_alloc($rows,$cols);
 108     } else {
 109         croak( __PACKAGE__.'::new($x,$y) - $x and $y must be positive integers');
 110     }
 111     gsl_matrix_complex_set_zero($matrix);
 112     $this->{_matrix} = $matrix;
 113     ($this->{_rows}, $this->{_cols}) = ($rows,$cols);
 114     bless $this, $class;
 115 }
 116 =head2 raw()
 117
 118 Get the underlying GSL matrix object created by SWIG, useful for using gsl_matrix_* functions which do not have an OO counterpart.
 119
 120     my $matrix     = Math::GSL::MatrixComplex->new(3,3);
 121     my $gsl_matrix = $matrix->raw;
 122     my $stuff      = gsl_matrix_complex_get($gsl_matrix, 1, 2);
 123
 124 =cut
 125 sub raw  { (shift)->{_matrix} }
 126 =head2 rows()
 127
 128 Returns the number of rows in the matrix.
 129
 130     my $rows = $matrix->rows;
 131 =cut
 132
 133 sub rows { (shift)->{_rows}   }
 134
 135 =head2 cols()
 136
 137 Returns the number of columns in the matrix.
 138
 139     my $cols = $matrix->cols;
 140 =cut
 141
 142 sub cols { (shift)->{_cols}   }
 143
 144 =head2  as_list()
 145
 146 Get the contents of a Math::GSL::Matrix object as a Perl list.
 147
 148     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 149     ...
 150     my @matrix = $matrix->as_list;
 151 =cut
 152
 153 sub as_list($)
 154 {
 155     my $self = shift;
 156     my @matrix;
 157     for my $row ( 0 .. $self->rows-1) {
 158        push @matrix, map { gsl_matrix_complex_get($self->raw, $row, $_) } (0 .. $self->cols-1 );
 159     }
 160     return @matrix;
 161 }
 162
 163 =head2 row()
 164
 165 Returns a row matrix of the row you enter.
 166
 167     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 168     ...
 169     my $matrix_row = $matrix->row(0);
 170
 171 =cut
 172
 173 sub row
 174 {
 175     my ($self, $row) = @_;
 176     croak (__PACKAGE__.'::$matrix->row($row) - invalid $row value')
 177         unless (($row < $self->rows) and $row >= 0);
 178
 179    my $rowmat = Math::GSL::MatrixComplex->new(1,$self->cols);
 180
 181    for my $n (0 .. $self->cols-1) {
 182         gsl_matrix_complex_set( $rowmat->raw, 0, $n,
 183             gsl_matrix_complex_get($self->raw, $row, $n)
 184         );
 185    }
 186
 187     return $rowmat;
 188 }
 189
 190 =head2 col()
 191
 192 Returns a col matrix of the column you enter.
 193
 194     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 195     ...
 196     my $matrix_col = $matrix->col(0);
 197
 198 =cut
 199
 200 sub col
 201 {
 202     my ($self, $col) = @_;
 203     croak (__PACKAGE__."::\$matrix->col(\$col) - $col not a valid column")
 204         unless (defined $col && $col < $self->cols and $col >= 0);
 205
 206     my $colmat = Math::GSL::MatrixComplex->new($self->rows, 1);
 207
 208     map { gsl_matrix_complex_set($colmat->raw, $_, 0,
 209             gsl_matrix_complex_get($self->raw, $_, $col),
 210             )
 211         } (0 .. $self->rows-1);
 212
 213     return $colmat;
 214 }
 215
 216 =head2 set_row()
 217
 218 Sets a the values of a row with the elements of an array.
 219
 220     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 221     $matrix->set_row(0, [8, 6, 2]);
 222
 223 You can also set multiple rows at once with chained calls:
 224     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 225     $matrix->set_row(0, [8, 6, 2])
 226            ->set_row(1, [2, 4, 1]);
 227     ...
 228
 229 =cut
 230
 231 sub set_row {
 232     my ($self, $row, $values) = @_;
 233     my $length = $#$values;
 234     die __PACKAGE__.'::set_row($x, $values) - $values must be a nonempty array reference' if $length == -1;
 235     die __PACKAGE__.'::set_row($x, $values) - $x must be a valid row number' if ($row < 0 || $row >= $self->rows);
 236     die __PACKAGE__.'::set_row($x, $values) - $values must contains the same number of elements as there is columns in the matrix' if($length != $self->cols-1);
 237     # $values may have Math::Complex objects
 238     @$values = map { Math::GSL::Complex::gsl_complex_rect(Re($_), Im($_)) } @$values;
 239     # warn Dumper [ @$values ];
 240     map { gsl_matrix_complex_set($self->raw, $row, $_, $values->[$_]) } (0..$length);
 241     return $self;
 242 }
 243
 244 =head2 set_col()
 245
 246 Sets a the values of a column with the elements of an array.
 247
 248     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 249     $matrix->set_col(0, [8, 6, 2]);
 250
 251 You can also set multiple columns at once with chained calls:
 252     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 253     $matrix->set_col(0, [8, 6, 2])
 254            ->set_col(1, [2, 4, 1]);
 255     ...
 256
 257 =cut
 258
 259 sub set_col {
 260     my ($self, $col, $values) = @_;
 261     my $length = $#$values;
 262     die __PACKAGE__.'::set_col($x, $values) - $values must be a nonempty array reference' if $length == -1;
 263     die __PACKAGE__.'::set_col($x, $values) - $x must be a valid column number' if ($col < 0 || $col >= $self->cols);
 264     die __PACKAGE__.'::set_col($x, $values) - $values must contains the same number of elements as there is rowss in the matrix' if($length != $self->rows-1);
 265     # $values may have Math::Complex objects
 266     @$values = map { gsl_complex_rect(Re($_), Im($_)) } @$values;
 267     map { gsl_matrix_complex_set($self->raw, $_, $col, $values->[$_]) } (0..$length);
 268     return $self;
 269 }
 270
 271 =head1 DESCRIPTION
 272
 273 =over 1
 274
 275 =item C<gsl_matrix_complex_alloc >
 276
 277 =item C<gsl_matrix_complex_calloc >
 278
 279 =item C<gsl_matrix_complex_alloc_from_block >
 280
 281 =item C<gsl_matrix_complex_alloc_from_matrix >
 282
 283 =item C<gsl_vector_complex_alloc_row_from_matrix >
 284
 285 =item C<gsl_vector_complex_alloc_col_from_matrix >
 286
 287 =item C<gsl_matrix_complex_free >
 288
 289 =item C<gsl_matrix_complex_submatrix >
 290
 291 =item C<gsl_matrix_complex_row >
 292
 293 =item C<gsl_matrix_complex_column >
 294
 295 =item C<gsl_matrix_complex_diagonal >
 296
 297 =item C<gsl_matrix_complex_subdiagonal >
 298
 299 =item C<gsl_matrix_complex_superdiagonal >
 300
 301 =item C<gsl_matrix_complex_subrow >
 302
 303 =item C<gsl_matrix_complex_subcolumn >
 304
 305 =item C<gsl_matrix_complex_view_array >
 306
 307 =item C<gsl_matrix_complex_view_array_with_tda >
 308
 309 =item C<gsl_matrix_complex_view_vector >
 310
 311 =item C<gsl_matrix_complex_view_vector_with_tda >
 312
 313 =item C<gsl_matrix_complex_const_submatrix >
 314
 315 =item C<gsl_matrix_complex_const_row >
 316
 317 =item C<gsl_matrix_complex_const_column >
 318
 319 =item C<gsl_matrix_complex_const_diagonal >
 320
 321 =item C<gsl_matrix_complex_const_subdiagonal >
 322
 323 =item C<gsl_matrix_complex_const_superdiagonal >
 324
 325 =item C<gsl_matrix_complex_const_subrow >
 326
 327 =item C<gsl_matrix_complex_const_subcolumn >
 328
 329 =item C<gsl_matrix_complex_const_view_array >
 330
 331 =item C<gsl_matrix_complex_const_view_array_with_tda >
 332
 333 =item C<gsl_matrix_complex_const_view_vector >
 334
 335 =item C<gsl_matrix_complex_const_view_vector_with_tda >
 336
 337 =item C<gsl_matrix_complex_get>
 338
 339 =item C<gsl_matrix_complex_set>
 340
 341 =item C<gsl_matrix_complex_ptr>
 342
 343 =item C<gsl_matrix_complex_const_ptr>
 344
 345 =item C<gsl_matrix_complex_set_zero >
 346
 347 =item C<gsl_matrix_complex_set_identity >
 348
 349 =item C<gsl_matrix_complex_set_all >
 350
 351 =item C<gsl_matrix_complex_fread >
 352
 353 =item C<gsl_matrix_complex_fwrite >
 354
 355 =item C<gsl_matrix_complex_fscanf >
 356
 357 =item C<gsl_matrix_complex_fprintf >
 358
 359 =item C<gsl_matrix_complex_memcpy>
 360
 361 =item C<gsl_matrix_complex_swap>
 362
 363 =item C<gsl_matrix_complex_swap_rows>
 364
 365 =item C<gsl_matrix_complex_swap_columns>
 366
 367 =item C<gsl_matrix_complex_swap_rowcol>
 368
 369 =item C<gsl_matrix_complex_transpose >
 370
 371 =item C<gsl_matrix_complex_transpose_memcpy >
 372
 373 =item C<gsl_matrix_complex_isnull >
 374
 375 =item C<gsl_matrix_complex_ispos >
 376
 377 =item C<gsl_matrix_complex_isneg >
 378
 379 =item C<gsl_matrix_complex_add >
 380
 381 =item C<gsl_matrix_complex_sub >
 382
 383 =item C<gsl_matrix_complex_mul_elements >
 384
 385 =item C<gsl_matrix_complex_div_elements >
 386
 387 =item C<gsl_matrix_complex_scale >
 388
 389 =item C<gsl_matrix_complex_add_constant >
 390
 391 =item C<gsl_matrix_complex_add_diagonal >
 392
 393 =item C<gsl_matrix_complex_get_row>
 394
 395 =item C<gsl_matrix_complex_get_col>
 396
 397 =item C<gsl_matrix_complex_set_row>
 398
 399 =item C<gsl_matrix_complex_set_col>
 400
 401 =back
 402
 403 For more informations on the functions, we refer you to the GSL offcial documentation
 404 L<http://www.gnu.org/software/gsl/manual/html_node/>
 405
 406
 407 =head1 AUTHORS
 408
 409 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 410
 411 =head1 COPYRIGHT AND LICENSE
 412
 413 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 414
 415 This program is free software; you can redistribute it and/or modify it
 416 under the same terms as Perl itself.
 417
 418 =cut
 419
 420 %}
 421