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
 154 sub as_list
 155 {
 156     my $self = shift;
 157     my $line;
 158     my @part;
 159     my @total;
 160     for($line=0; $line<$self->rows; $line++){
 161        @part = map {
 162          gsl_matrix_complex_get($self->raw, $line, $_)
 163        } (0 .. $self->cols-1 );
 164        push(@total, @part);
 165     }
 166     return @total;
 167 }
 168
 169 =head2 row()
 170
 171 Returns a row matrix of the row you enter.
 172
 173     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 174     ...
 175     my $matrix_row = $matrix->row(0);
 176
 177 =cut
 178
 179 sub row
 180 {
 181     my ($self, $row) = @_;
 182     croak (__PACKAGE__.'::$matrix->row($row) - invalid $row value')
 183         unless (($row < $self->rows) and $row >= 0);
 184
 185    my $rowmat = Math::GSL::MatrixComplex->new(1,$self->cols);
 186
 187    for my $n (0 .. $self->cols-1) {
 188         gsl_matrix_complex_set( $rowmat->raw, 0, $n,
 189             gsl_matrix_complex_get($self->raw, $row, $n)
 190         );
 191    }
 192
 193     return $rowmat;
 194 }
 195
 196 =head2 col()
 197
 198 Returns a col matrix of the column you enter.
 199
 200     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 201     ...
 202     my $matrix_col = $matrix->col(0);
 203
 204 =cut
 205
 206 sub col
 207 {
 208     my ($self, $col) = @_;
 209     croak (__PACKAGE__."::\$matrix->col(\$col) - $col not a valid column")
 210         unless ($col < $self->cols and $col >= 0);
 211
 212     my $colmat = Math::GSL::MatrixComplex->new($self->rows, 1);
 213
 214     map { gsl_matrix_complex_set($colmat->raw, $_, 0,
 215             gsl_matrix_complex_get($self->raw, $_, $col),
 216             )
 217         } (0 .. $self->rows-1);
 218
 219     return $colmat;
 220 }
 221
 222 =head2 set_row()
 223
 224 Sets a the values of a row with the elements of an array.
 225
 226     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 227     $matrix->set_row(0, [8, 6, 2]);
 228
 229 You can also set multiple rows at once with chained calls:
 230     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 231     $matrix->set_row(0, [8, 6, 2])
 232            ->set_row(1, [2, 4, 1]);
 233     ...
 234
 235 =cut
 236
 237 sub set_row {
 238     my ($self, $row, $values) = @_;
 239     my $length = $#$values;
 240     die __PACKAGE__.'::set_row($x, $values) - $values must be a nonempty array reference' if $length == -1;
 241     die __PACKAGE__.'::set_row($x, $values) - $x must be a valid row number' if ($row < 0 || $row >= $self->rows);
 242     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);
 243     # $values may have Math::Complex objects
 244     @$values = map { Math::GSL::Complex::gsl_complex_rect(Re($_), Im($_)) } @$values;
 245     # warn Dumper [ @$values ];
 246     map { gsl_matrix_complex_set($self->raw, $row, $_, $values->[$_]) } (0..$length);
 247     return $self;
 248 }
 249
 250 =head2 set_col()
 251
 252 Sets a the values of a column with the elements of an array.
 253
 254     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 255     $matrix->set_col(0, [8, 6, 2]);
 256
 257 You can also set multiple columns at once with chained calls:
 258     my $matrix = Math::GSL::MatrixComplex->new(3,3);
 259     $matrix->set_col(0, [8, 6, 2])
 260            ->set_col(1, [2, 4, 1]);
 261     ...
 262
 263 =cut
 264
 265 sub set_col {
 266     my ($self, $col, $values) = @_;
 267     my $length = $#$values;
 268     die __PACKAGE__.'::set_col($x, $values) - $values must be a nonempty array reference' if $length == -1;
 269     die __PACKAGE__.'::set_col($x, $values) - $x must be a valid column number' if ($col < 0 || $col >= $self->cols);
 270     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);
 271     # $values may have Math::Complex objects
 272     @$values = map { gsl_complex_rect(Re($_), Im($_)) } @$values;
 273     map { gsl_matrix_complex_set($self->raw, $_, $col, $values->[$_]) } (0..$length);
 274     return $self;
 275 }
 276
 277 =head1 DESCRIPTION
 278
 279 =over 1
 280
 281 =item C<gsl_matrix_complex_alloc >
 282
 283 =item C<gsl_matrix_complex_calloc >
 284
 285 =item C<gsl_matrix_complex_alloc_from_block >
 286
 287 =item C<gsl_matrix_complex_alloc_from_matrix >
 288
 289 =item C<gsl_vector_complex_alloc_row_from_matrix >
 290
 291 =item C<gsl_vector_complex_alloc_col_from_matrix >
 292
 293 =item C<gsl_matrix_complex_free >
 294
 295 =item C<gsl_matrix_complex_submatrix >
 296
 297 =item C<gsl_matrix_complex_row >
 298
 299 =item C<gsl_matrix_complex_column >
 300
 301 =item C<gsl_matrix_complex_diagonal >
 302
 303 =item C<gsl_matrix_complex_subdiagonal >
 304
 305 =item C<gsl_matrix_complex_superdiagonal >
 306
 307 =item C<gsl_matrix_complex_subrow >
 308
 309 =item C<gsl_matrix_complex_subcolumn >
 310
 311 =item C<gsl_matrix_complex_view_array >
 312
 313 =item C<gsl_matrix_complex_view_array_with_tda >
 314
 315 =item C<gsl_matrix_complex_view_vector >
 316
 317 =item C<gsl_matrix_complex_view_vector_with_tda >
 318
 319 =item C<gsl_matrix_complex_const_submatrix >
 320
 321 =item C<gsl_matrix_complex_const_row >
 322
 323 =item C<gsl_matrix_complex_const_column >
 324
 325 =item C<gsl_matrix_complex_const_diagonal >
 326
 327 =item C<gsl_matrix_complex_const_subdiagonal >
 328
 329 =item C<gsl_matrix_complex_const_superdiagonal >
 330
 331 =item C<gsl_matrix_complex_const_subrow >
 332
 333 =item C<gsl_matrix_complex_const_subcolumn >
 334
 335 =item C<gsl_matrix_complex_const_view_array >
 336
 337 =item C<gsl_matrix_complex_const_view_array_with_tda >
 338
 339 =item C<gsl_matrix_complex_const_view_vector >
 340
 341 =item C<gsl_matrix_complex_const_view_vector_with_tda >
 342
 343 =item C<gsl_matrix_complex_get>
 344
 345 =item C<gsl_matrix_complex_set>
 346
 347 =item C<gsl_matrix_complex_ptr>
 348
 349 =item C<gsl_matrix_complex_const_ptr>
 350
 351 =item C<gsl_matrix_complex_set_zero >
 352
 353 =item C<gsl_matrix_complex_set_identity >
 354
 355 =item C<gsl_matrix_complex_set_all >
 356
 357 =item C<gsl_matrix_complex_fread >
 358
 359 =item C<gsl_matrix_complex_fwrite >
 360
 361 =item C<gsl_matrix_complex_fscanf >
 362
 363 =item C<gsl_matrix_complex_fprintf >
 364
 365 =item C<gsl_matrix_complex_memcpy>
 366
 367 =item C<gsl_matrix_complex_swap>
 368
 369 =item C<gsl_matrix_complex_swap_rows>
 370
 371 =item C<gsl_matrix_complex_swap_columns>
 372
 373 =item C<gsl_matrix_complex_swap_rowcol>
 374
 375 =item C<gsl_matrix_complex_transpose >
 376
 377 =item C<gsl_matrix_complex_transpose_memcpy >
 378
 379 =item C<gsl_matrix_complex_isnull >
 380
 381 =item C<gsl_matrix_complex_ispos >
 382
 383 =item C<gsl_matrix_complex_isneg >
 384
 385 =item C<gsl_matrix_complex_add >
 386
 387 =item C<gsl_matrix_complex_sub >
 388
 389 =item C<gsl_matrix_complex_mul_elements >
 390
 391 =item C<gsl_matrix_complex_div_elements >
 392
 393 =item C<gsl_matrix_complex_scale >
 394
 395 =item C<gsl_matrix_complex_add_constant >
 396
 397 =item C<gsl_matrix_complex_add_diagonal >
 398
 399 =item C<gsl_matrix_complex_get_row>
 400
 401 =item C<gsl_matrix_complex_get_col>
 402
 403 =item C<gsl_matrix_complex_set_row>
 404
 405 =item C<gsl_matrix_complex_set_col>
 406
 407 =back
 408
 409 For more informations on the functions, we refer you to the GSL offcial documentation
 410 L<http://www.gnu.org/software/gsl/manual/html_node/>
 411
 412
 413 =head1 AUTHORS
 414
 415 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 416
 417 =head1 COPYRIGHT AND LICENSE
 418
 419 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 420
 421 This program is free software; you can redistribute it and/or modify it
 422 under the same terms as Perl itself.
 423
 424 =cut
 425
 426 %}
 427