pod/Complex.pod

   1 %perlcode %{
   2
   3 @EXPORT_OK = qw(
   4     gsl_complex_arg gsl_complex_abs gsl_complex_rect gsl_complex_polar doubleArray_getitem
   5     gsl_complex_rect gsl_complex_polar gsl_complex_arg gsl_complex_abs gsl_complex_abs2
   6     gsl_complex_logabs gsl_complex_add gsl_complex_sub gsl_complex_mul gsl_complex_div
   7     gsl_complex_add_real gsl_complex_sub_real gsl_complex_mul_real gsl_complex_div_real
   8     gsl_complex_add_imag gsl_complex_sub_imag gsl_complex_mul_imag gsl_complex_div_imag
   9     gsl_complex_conjugate gsl_complex_inverse gsl_complex_negative gsl_complex_sqrt
  10     gsl_complex_sqrt_real gsl_complex_pow gsl_complex_pow_real gsl_complex_exp
  11     gsl_complex_log gsl_complex_log10 gsl_complex_log_b gsl_complex_sin
  12     gsl_complex_cos gsl_complex_sec gsl_complex_csc gsl_complex_tan
  13     gsl_complex_cot gsl_complex_arcsin gsl_complex_arcsin_real gsl_complex_arccos
  14     gsl_complex_arccos_real gsl_complex_arcsec gsl_complex_arcsec_real gsl_complex_arccsc
  15     gsl_complex_arccsc_real gsl_complex_arctan gsl_complex_arccot gsl_complex_sinh
  16     gsl_complex_cosh gsl_complex_sech gsl_complex_csch gsl_complex_tanh
  17     gsl_complex_coth gsl_complex_arcsinh gsl_complex_arccosh gsl_complex_arccosh_real
  18     gsl_complex_arcsech gsl_complex_arccsch gsl_complex_arctanh gsl_complex_arctanh_real
  19     gsl_complex_arccoth new_doubleArray delete_doubleArray doubleArray_setitem
  20     gsl_real gsl_imag gsl_parts
  21     gsl_complex_eq gsl_set_real gsl_set_imag gsl_set_complex
  22     $GSL_COMPLEX_ONE $GSL_COMPLEX_ZERO $GSL_COMPLEX_NEGONE
  23 );
  24 # macros to implement
  25 # gsl_set_complex gsl_set_complex_packed
  26 our ($GSL_COMPLEX_ONE, $GSL_COMPLEX_ZERO, $GSL_COMPLEX_NEGONE) = map { gsl_complex_rect($_, 0) } qw(1 0 -1);
  27
  28
  29 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
  30
  31 sub new {
  32     my ($class, @values) = @_;
  33     my $this = {};
  34     $this->{_complex} = gsl_complex_rect($values[0], $values[1]);
  35     bless $this, $class;
  36 }
  37 sub real {
  38     my ($self) = @_;
  39     gsl_real($self->{_complex}->{dat});
  40 }
  41
  42 sub imag {
  43     my ($self) = @_;
  44     gsl_imag($self->{_complex}->{dat});
  45 }
  46
  47 sub parts {
  48     my ($self) = @_;
  49     gsl_parts($self->{_complex}->{dat});
  50 }
  51
  52 sub raw  { (shift)->{_complex} }
  53
  54
  55 ### some important macros that are in gsl_complex.h
  56 sub gsl_complex_eq {
  57     my ($z,$w) = @_;
  58     gsl_real($z) == gsl_real($w) && gsl_imag($z) == gsl_imag($w) ? 1 : 0;
  59 }
  60
  61 sub gsl_set_real {
  62     my ($z,$r) = @_;
  63     doubleArray_setitem($z->{dat}, 0, $r);
  64 }
  65
  66 sub gsl_set_imag {
  67     my ($z,$i) = @_;
  68     doubleArray_setitem($z->{dat}, 1, $i);
  69 }
  70
  71 sub gsl_real {
  72     my $z = shift;
  73     return doubleArray_getitem($z->{dat}, 0 );
  74 }
  75
  76 sub gsl_imag {
  77     my $z = shift;
  78     return doubleArray_getitem($z->{dat}, 1 );
  79 }
  80
  81 sub gsl_parts {
  82     my $z = shift;
  83     return (gsl_real($z), gsl_imag($z));
  84 }
  85
  86 sub gsl_set_complex {
  87     my ($z, $r, $i) = @_;
  88     gsl_set_real($z, $r);
  89     gsl_set_imag($z, $i);
  90 }
  91
  92 =head1 NAME
  93
  94 Math::GSL::Complex - Complex Numbers
  95
  96 =head1 SYNOPSIS
  97
  98     use Math::GSL::Complex qw/:all/;
  99     my $complex = Math::GSL::Complex->new([3,2]); # creates a complex number 3+2*i
 100     my $real = $complex->real;                    # returns the real part
 101     my $imag = $complex->imag;                    # returns the imaginary part
 102     $complex->gsl_set_real(5);                    # changes the real part to 5
 103     $complex->gsl_set_imag(4);                    # changes the imaginary part to 4
 104     $complex->gsl_set_complex(7,6);               # changes it to 7 + 6*I
 105     ($real, $imag) = $complex->parts;
 106
 107 =head1 DESCRIPTION
 108
 109 Here is a list of all the functions included in this module :
 110
 111 =over 1
 112
 113 =item C<gsl_complex_arg($z)> - return the argument of the complex number $z
 114
 115 =item C<gsl_complex_abs($z)> - return |$z|, the magnitude of the complex number $z
 116
 117 =item C<gsl_complex_rect($x,$y)> - create a complex number in cartesian form $x + $y*I
 118
 119 =item C<gsl_complex_polar($r,$theta)> - create a complex number in polar form $r*exp(I*$theta)
 120
 121 =item C<gsl_complex_abs2($z)> - return |$z|^2, the squared magnitude of the complex number $z
 122
 123 =item C<gsl_complex_logabs($z)> - return log(|$z|), the natural logarithm of the magnitude of the complex number $z
 124
 125 =item C<gsl_complex_add($c1, $c2)> - return a complex number which is the sum of the complex numbers $c1 and $c2
 126
 127 =item C<gsl_complex_sub($c1, $c2)> - return a complex number which is the difference between $c1 and $c2 ($c1 - $c2)
 128
 129 =item C<gsl_complex_mul($c1, $c2)> - return a complex number which is the product of the complex numbers $c1 and $c2
 130
 131 =item C<gsl_complex_div($c1, $c2)> - return a complex number which is the quotient of the complex numbers $c1 and $c2 ($c1 / $c2)
 132
 133 =item C<gsl_complex_add_real($c, $x)> - return the sum of the complex number $c and the real number $x
 134
 135 =item C<gsl_complex_sub_real($c, $x)> - return the difference of the complex number $c and the real number $x
 136
 137 =item C<gsl_complex_mul_real($c, $x)> - return the product of the complex number $c and the real number $x
 138
 139 =item C<gsl_complex_div_real($c, $x)> - return the quotient of the complex number $c and the real number $x
 140
 141 =item C<gsl_complex_add_imag($c, $y)> - return sum of the complex number $c and the imaginary number i*$x
 142
 143 =item C<gsl_complex_sub_imag($c, $y)> - return the diffrence of the complex number $c and the imaginary number i*$x
 144
 145 =item C<gsl_complex_mul_imag($c, $y)> - return the product of the complex number $c and the imaginary number i*$x
 146
 147 =item C<gsl_complex_div_imag($c, $y)> - return the quotient of the complex number $c and the imaginary number i*$x
 148
 149 =item C<gsl_complex_conjugate($c)> - return the conjugate of the of the complex number $c (x - i*y)
 150
 151 =item C<gsl_complex_inverse($c)> - return the inverse, or reciprocal of the complex number $c (1/$c)
 152
 153 =item C<gsl_complex_negative($c)> - return the negative of the complex number $c (-x -i*y)
 154
 155 =item C<gsl_complex_sqrt($c)> - return the square root of the complex number $c
 156
 157 =item C<gsl_complex_sqrt_real($x)> - return the complex square root of the real number $x, where $x may be negative
 158
 159 =item C<gsl_complex_pow($c1, $c2)> - return the complex number $c1 raised to the complex power $c2
 160
 161 =item C<gsl_complex_pow_real($c, $x)> - return the complex number raised to the real power $x
 162
 163 =item C<gsl_complex_exp($c)> - return the complex exponential of the complex number $c
 164
 165 =item C<gsl_complex_log($c)> - return the complex natural logarithm (base e) of the complex number $c
 166
 167 =item C<gsl_complex_log10($c)> - return the complex base-10 logarithm of the complex number $c
 168
 169 =item C<gsl_complex_log_b($c, $b)> - return the complex base-$b of the complex number $c
 170
 171 =item C<gsl_complex_sin($c)> - return the complex sine of the complex number $c
 172
 173 =item C<gsl_complex_cos($c)> - return the complex cosine of the complex number $c
 174
 175 =item C<gsl_complex_sec($c)> - return the complex secant of the complex number $c
 176
 177 =item C<gsl_complex_csc($c)> - return the complex cosecant of the complex number $c
 178
 179 =item C<gsl_complex_tan($c)> - return the complex tangent of the complex number $c
 180
 181 =item C<gsl_complex_cot($c)> - return the complex cotangent of the complex number $c
 182
 183 =item C<gsl_complex_arcsin($c)> - return the complex arcsine of the complex number $c
 184
 185 =item C<gsl_complex_arcsin_real($x)> - return the complex arcsine of the real number $x
 186
 187 =item C<gsl_complex_arccos($c)> - return the complex arccosine of the complex number $c
 188
 189 =item C<gsl_complex_arccos_real($x)> - return the complex arccosine of the real number $x
 190
 191 =item C<gsl_complex_arcsec($c)> - return the complex arcsecant of the complex number $c
 192
 193 =item C<gsl_complex_arcsec_real($x)> - return the complex arcsecant of the real number $x
 194
 195 =item C<gsl_complex_arccsc($c)> - return the complex arccosecant of the complex number $c
 196
 197 =item C<gsl_complex_arccsc_real($x)> - return the complex arccosecant of the real number $x
 198
 199 =item C<gsl_complex_arctan($c)> - return the complex arctangent of the complex number $c
 200
 201 =item C<gsl_complex_arccot($c)> - return the complex arccotangent of the complex number $c
 202
 203 =item C<gsl_complex_sinh($c)> - return the complex hyperbolic sine of the complex number $c
 204
 205 =item C<gsl_complex_cosh($c)> - return the complex hyperbolic cosine of the complex number $cy
 206
 207 =item C<gsl_complex_sech($c)> - return the complex hyperbolic secant of the complex number $c
 208
 209 =item C<gsl_complex_csch($c)> - return the complex hyperbolic cosecant of the complex number $c
 210
 211 =item C<gsl_complex_tanh($c)> - return the complex hyperbolic tangent of the complex number $c
 212
 213 =item C<gsl_complex_coth($c)> - return the complex hyperbolic cotangent of the complex number $c
 214
 215 =item C<gsl_complex_arcsinh($c)> - return the complex hyperbolic arcsine of the complex number $c
 216
 217 =item C<gsl_complex_arccosh($c)> - return the complex hyperbolic arccosine of the complex number $c
 218
 219 =item C<gsl_complex_arccosh_real($x)> - return the complex hyperbolic arccosine of the real number $x
 220
 221 =item C<gsl_complex_arcsech($c)> - return the complex hyperbolic arcsecant of the complex number $c
 222
 223 =item C<gsl_complex_arccsch($c)> - return the complex hyperbolic arccosecant of the complex number $c
 224
 225 =item C<gsl_complex_arctanh($c)> - return the complex hyperbolic arctangent of the complex number $c
 226
 227 =item C<gsl_complex_arctanh_real($x)> - return the complex hyperbolic arctangent of the real number $x
 228
 229 =item C<gsl_complex_arccoth($c)> - return the complex hyperbolic arccotangent of the complex number $c
 230
 231 =item C<gsl_real($z)> - return the real part of $z
 232
 233 =item C<gsl_imag($z)> - return the imaginary part of $z
 234
 235 =item C<gsl_parts($z)> - return a list of the real and imaginary parts of $z
 236
 237 =item C<gsl_set_real($z, $x)> - sets the real part of $z to $x
 238
 239 =item C<gsl_set_imag($z, $y)> - sets the imaginary part of $z to $y
 240
 241 =item C<gsl_set_complex($z, $x, $h)> - sets the real part of $z to $x and the imaginary part to $y
 242
 243 =back
 244
 245 =head1 EXAMPLES
 246
 247 This code defines $z as 6 + 4*I, takes the complex conjugate of that number, then prints it out.
 248
 249 =over 1
 250
 251     my $z = gsl_complex_rect(6,4);
 252     my $y = gsl_complex_conjugate($z);
 253     my ($real, $imag) = gsl_parts($y);
 254     print "z = $real + $imag*I\n";
 255
 256 =back
 257
 258 This code defines $z as 5 + 3*I, multiplies it by 2 and then prints it out.
 259
 260 =over 1
 261
 262     my $x = gsl_complex_rect(5,3);
 263     my $z = gsl_complex_mul_real($x, 2);
 264     my $real = gsl_real($z);
 265     my $imag = gsl_imag($z);
 266     print "Re(\$z) = $real\n";
 267
 268 =back
 269
 270 =head1 AUTHORS
 271
 272 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 273
 274 =head1 COPYRIGHT AND LICENSE
 275
 276 Copyright (C) 2008-2009 Jonathan Leto and Thierry Moisan
 277
 278 This program is free software; you can redistribute it and/or modify it
 279 under the same terms as Perl itself.
 280
 281 =cut
 282 %}