123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685 |
- =encoding utf8
- =head1 NAME
- Math::GComplex - Generic complex number library.
- =head1 VERSION
- Version 0.13
- =head1 SYNOPSIS
- use 5.010;
- use Math::GComplex;
- use Math::AnyNum qw(:overload);
- my $x = Math::GComplex->new(3, 4);
- my $y = Math::GComplex->new(7, 5);
- say $x + $y; #=> (10 9)
- say $x - $y; #=> (-4 -1)
- say $x * $y; #=> (1 43)
- say $x / $y; #=> (41/74 13/74)
- =head1 DESCRIPTION
- B<Math::GComplex> is a lightweight library, providing a generic interface to complex number operations, accepting any type of number as a component of a complex number, including native Perl numbers and numerical objects provided by other mathematical libraries, such as L<Math::AnyNum>.
- In most cases, it can be used as a drop-in replacement for L<Math::Complex>.
- Due to its simple and elegant design, Math::GComplex is between 2x up to 8x faster than L<Math::Complex>.
- =head1 EXPORT
- The following functions are exportable:
- :trig
- sin sinh asin asinh
- cos cosh acos acosh
- tan tanh atan atanh
- cot coth acot acoth
- sec sech asec asech
- csc csch acsc acsch
- atan2 deg2rad rad2deg
- :special
- gcd invmod powmod
- log logn exp pow pown sqrt cbrt root
- :misc
- cplx polar abs acmp sgn conj norm
- inv real imag reals floor ceil round
- Multiple functions can be exported as:
- use Math::GComplex qw(acos acosh);
- There is also the possibility of exporting an entire group of functions, by specifying their group name, as:
- use Math::GComplex qw(:trig);
- The imaginary unit, C<i = sqrt(-1)>, is also exportable, as:
- use Math::GComplex qw(i);
- Additionally, by specifying the C<:all> keyword, all the exportable functions, including the C<i> constant, will be exported:
- use Math::GComplex qw(:all);
- The C<:overload> keyword enables constant overloading, which makes
- each number a Math::GComplex object and also exports the C<i> constant:
- use Math::GComplex qw(:overload);
- CORE::say 3 + 4*i; #=> (3 4)
- CORE::say log(-1); #=> (0 3.14159265358979)
- B<NOTE:> C<:overload> is lexical to the current scope only.
- The syntax for disabling the C<:overload> behavior in the current scope, is:
- no Math::GComplex; # :overload will be disabled in the current scope
- Nothing is exported by default.
- =head1 INITIALIZATION
- =head2 new / cplx / make
- my $z = cplx($real, $imag);
- my $z = Math::GComplex->new($real, $imag);
- my $z = Math::GComplex->make($real, $imag);
- Create a new complex number, given its Cartesian coordinate form.
- =head2 cplxe / emake
- my $z = cplxe($r, $theta);
- my $z = Math::GComplex->emake($r, $theta);
- Create a new complex number, given its polar form.
- =head2 i
- my $i = Math::GComplex::i();
- Returns the imaginary unit as a B<Math::GComplex> object, equivalent with C<cplx(0, 1)>.
- =head1 BASIC OPERATIONS
- This section describes all the basic operations provided by this module.
- =head2 add
- my $z = $x + $y;
- my $z = $x->add($y);
- Addition of C<x> and C<y>, defined as:
- (a + b*i) + (x + y*i) = (a + x) + (b + y)*i
- =head2 sub
- my $z = $x - $y;
- my $z = $x->sub($y);
- Subtraction of C<y> from C<x>, defined as:
- (a + b*i) - (x + y*i) = (a - x) + (b - y)*i
- =head2 mul
- my $z = $x * $y;
- my $z = $x->mul($y);
- Multiplication of C<x> and C<y>, defined as:
- (a + b*i) * (x + y*i) = (a*x - b*y) + (a*y + b*x)*i
- =head2 div
- my $z = $x / $y;
- my $z = $x->div($y);
- Division of C<x> by C<y>, defined as:
- (a + b*i) / (x + y*i) = (a*x + b*y)/(x^2 + y^2) + (b*x - a*y)/(x^2 + y^2)*i
- =head2 mod
- my $z = $x % $y;
- my $z = $x->mod($y);
- Remainder of C<x> when divided by C<y>, defined as:
- mod(a, b) = a - b * floor(a/b)
- =head2 neg
- my $z = -$x;
- my $z = $x->neg;
- Additive inverse of C<x>, defined as:
- neg(a + b*i) = -a - b*i
- =head2 conj
- my $z = ~$x;
- my $z = $x->conj;
- Complex conjugate of C<x>, defined as:
- conj(a + b*i) = a - b*i
- =head2 inv
- my $z = $x->inv;
- Multiplicative inverse of C<x>, defined as:
- inv(x) = 1/x
- =head2 norm
- my $z = $x->norm;
- Normalized value of C<x>, defined as:
- norm(a + b*i) = a^2 + b^2
- =head2 abs
- my $z = $x->abs;
- Absolute value of C<x>, defined as:
- abs(a + b*i) = sqrt(a^2 + b^2)
- =head2 sgn
- my $z = $x->sgn;
- The sign of C<x>, defined as:
- sgn(x) = x / abs(x)
- =head1 SPECIAL FUNCTIONS
- This section describes the special mathematical functions provided by this module.
- =head2 log
- my $z = log($x);
- my $z = $x->log;
- Natural logarithm of C<x>, defined as:
- log(a + b*i) = log(a^2 + b^2)/2 + atan2(b, a) * i
- =head2 logn
- my $z = $x->logn($y);
- Logarithm of C<x> to base C<y>, defined as:
- logn(a, b) = log(a) / log(b)
- =head2 exp
- my $z = exp($x);
- my $z = $x->exp;
- Natural exponentiation of C<x>, defined as:
- exp(a + b*i) = exp(a) * cos(b) + exp(a) * sin(b) * i
- =head2 pow
- my $z = $x**$y;
- my $z = $x->pow($y);
- Raises C<x> to power C<y> and returns the result, defined as:
- a^b = exp(log(a) * b)
- =head2 pown
- my $z = $x->pown($n);
- Raises C<x> to power C<n>, using the exponentiation by squaring method, and returns the result, where C<n> is a native integer.
- =head2 powmod
- my $z = $x->powmod($n, $m);
- Modular exponentiation C<x^n mod m>, where C<n> in an arbitrary large integer.
- =head2 gcd
- my $z = $n->gcd($k);
- Greatest common divisors of two complex numbers.
- =head2 invmod
- my $x = $n->invmod($m);
- Modular multiplicative inverse of two complex numbers.
- The returned value is the solution to C<x> in:
- n*x = 1 (mod m)
- Returns C<undef> when a multiplicative inverse mod C<m> does not exist.
- =head2 root
- my $z = $x->root($y);
- Nth root of C<x>, defined as:
- root(a, b) = exp(log(a) / b)
- =head2 sqrt
- my $z = sqrt($x);
- my $z = $x->sqrt;
- Square root of C<x>, defined as:
- sqrt(x) = exp(log(x) / 2)
- =head2 cbrt
- my $z = $x->cbrt;
- Cube root of C<x>, defined as:
- cbrt(x) = exp(log(x) / 3)
- =head1 TRIGONOMETRIC FUNCTIONS
- This section includes all the trigonometric functions provided by Math::GComplex.
- =head2 sin / sinh / asin / asinh
- my $z = $x->sin;
- my $z = $x->sinh;
- my $z = $x->asin;
- my $z = $x->asinh;
- Sine, hyperbolic sine, inverse sine and inverse hyperbolic sine.
- Defined as:
- sin(x) = (exp(x * i) - exp(-i * x))/(2 * i)
- sinh(x) = (exp(2 * x) - 1) / (2 * exp(x))
- asin(x) = -i * log(i * x + sqrt(1 - x^2))
- asinh(x) = log(sqrt(x^2 + 1) + x)
- =head2 cos / cosh / acos / acosh
- my $z = $x->cos;
- my $z = $x->cosh;
- my $z = $x->acos;
- my $z = $x->acosh;
- Cosine, hyperbolic cosine, inverse cosine and inverse hyperbolic cosine.
- Defined as:
- cos(x) = (exp(-i * x) + exp(i * x)) / 2
- cosh(x) = (exp(2 * x) + 1) / (2 * exp(x))
- acos(x) = -2 * i * log(i * sqrt((1 - x)/2) + sqrt((1 + x)/2))
- acosh(x) = log(x + sqrt(x - 1) * sqrt(x + 1))
- =head2 tan / tanh / atan / atanh
- my $z = $x->tan;
- my $z = $x->tanh;
- my $z = $x->atan;
- my $z = $x->atanh;
- Tangent, hyperbolic tangent, inverse tangent and inverse hyperbolic tangent.
- Defined as:
- tan(x) = (2 * i)/(exp(2 * i * x) + 1) - i
- tanh(x) = (exp(2 * x) - 1) / (exp(2 * x) + 1)
- atan(x) = i * (log(1 - i * x) - log(1 + i * x)) / 2
- atanh(x) = (log(1 + x) - log(1 - x)) / 2
- =head2 cot / coth / acot / acoth
- my $z = $x->cot;
- my $z = $x->coth;
- my $z = $x->acot;
- my $z = $x->acoth;
- Cotangent, hyperbolic cotangent, inverse cotangent and inverse hyperbolic cotangent.
- Defined as:
- cot(x) = (2 * i)/(exp(2 * i * x) - 1) + i
- coth(x) = (exp(2 * x) + 1) / (exp(2 * x) - 1)
- acot(x) = atan(1/x)
- acoth(x) = atanh(1/x)
- =head2 sec / sech / asec / asech
- my $z = $x->sec;
- my $z = $x->sech;
- my $z = $x->asec;
- my $z = $x->asech;
- Secant, hyperbolic secant, inverse secant and inverse hyperbolic secant.
- Defined as:
- sec(x) = 2/(exp(-i * x) + exp(i * x))
- sech(x) = (2 * exp(x)) / (exp(2 * x) + 1)
- asec(x) = acos(1/x)
- asech(x) = acosh(1/x)
- =head2 csc / csch / acsc / acsch
- my $z = $x->csc;
- my $z = $x->csch;
- my $z = $x->acsc;
- my $z = $x->acsch;
- Cosecant, hyperbolic cosecant, inverse cosecant and inverse hyperbolic cosecant.
- Defined as:
- csc(x) = -(2 * i)/(exp(-i * x) - exp(i * x))
- csch(x) = (2 * exp(x)) / (exp(2 * x) - 1)
- acsc(x) = asin(1/x)
- acsch(x) = asinh(1/x)
- =head2 atan2
- my $z = atan2($x, $y);
- my $z = $x->atan2($y);
- The arc tangent of C<x> and C<y>, defined as:
- atan2(a, b) = -i * log((b + a*i) / sqrt(a^2 + b^2))
- =head2 deg2rad
- my $rad = $x->deg2rad;
- Returns the value of C<x> converted from degrees to radians.
- Defined as:
- deg2rad(x) = x / 180 * atan2(0, -abs(x))
- =head2 rad2deg
- my $deg = $x->rad2deg;
- Returns the value of C<x> converted from radians to degrees.
- Defined as:
- rad2deg(x) = x * 180 / atan2(0, -abs(x))
- =head1 MISCELLANEOUS FUNCTIONS
- This section describes the various useful methods provided by this module.
- =head2 floor
- my $z = $x->floor;
- The floor function, defined as:
- floor(a + b*i) = floor(a) + floor(b)*i
- =head2 ceil
- my $z = $x->ceil;
- The ceil function, defined as:
- ceil(a + b*i) = ceil(a) + ceil(b)*i
- =head2 round
- my $z = $x->round;
- The round function, rounding C<x> to the nearest Gaussian integer, defined as:
- round(a + b*i) = round(a) + round(b)*i
- This function uses the half-away-from-zero tie-breaking method, defined as:
- round(+0.5) = +1
- round(-0.5) = -1
- =head2 int
- my $z = int($x);
- my $z = $x->int;
- The integer-truncation function, defined as:
- int(a + b*i) = int(a) + int(b)*i
- =head2 and
- my $z = $x & $y;
- my $z = $x->and($y);
- Bitwise AND-logical operation, defined as:
- (a + b*i) & (x + y*i) = (a & x) + (b & y)*i
- =head2 or
- my $z = $x | $y;
- my $z = $x->or($y);
- Bitwise OR-logical operation, defined as:
- (a + b*i) | (x + y*i) = (a | x) + (b | y)*i
- =head2 xor
- my $z = $x ^ $y;
- my $z = $x->xor($y);
- Bitwise XOR-logical operation, defined as:
- (a + b*i) ^ (x + y*i) = (a ^ x) + (b ^ y)*i
- =head2 lsft
- my $z = $x << $n;
- my $z = $x->lsft($n);
- Bitwise left-shift operation, defined as:
- (a + b*i) << n = (a << n) + (b << n)*i
- (a + b*i) << (x + y*i) = int((a + b*i) * 2**(x + y*i))
- =head2 rsft
- my $z = $x >> $n;
- my $z = $x->rsft($n);
- Bitwise right-shift operation, defined as:
- (a + b*i) >> n = (a >> n) + (b >> n)*i
- (a + b*i) >> (x + y*i) = int((a + b*i) / 2**(x + y*i))
- =head2 real
- my $re = $x->real;
- Return the real part of C<x>.
- =head2 imag
- my $im = $x->imag;
- Returns the imaginary part of C<x>.
- =head2 reals
- my ($re, $im) = $x->reals
- Returns the real and the imaginary part of C<x>, as real numbers.
- =head1 * Comparisons
- =head2 eq
- my $bool = $x == $y;
- my $bool = $x->eq($y);
- Equality check: returns a true value when C<x> and C<y> are equal.
- =head2 ne
- my $bool = $x != $y;
- my $bool = $x->ne($y);
- Inequality check: returns a true value when C<x> and C<y> are not equal.
- =head2 gt
- my $bool = $x > $y;
- my $bool = $x->gt($y);
- Returns a true value when C<x> is greater than C<y>.
- =head2 ge
- my $bool = $x >= $y;
- my $bool = $x->ge($y);
- Returns a true value when C<x> is equal or greater than C<y>.
- =head2 lt
- my $bool = $x < $y;
- my $bool = $x->lt($y);
- Returns a true value when C<x> is less than C<y>.
- =head2 le
- my $bool = $x <= $y;
- my $bool = $x->le($y)
- Returns a true value when C<x> is equal or less than C<y>.
- =head2 cmp
- my $int = $x <=> $y;
- my $int = $x->cmp($y);
- Compares C<x> to C<y> and returns a negative value when C<x> is less than C<y>,
- 0 when C<x> and C<y> are equal, and a positive value when C<x> is greater than C<y>.
- Complex numbers are compared as:
- (real($x) <=> real($y)) ||
- (imag($x) <=> imag($y))
- =head2 acmp
- my $int = $x->acmp($y);
- Absolute comparison of C<x> and C<y>, defined as:
- acmp(a, b) = abs(a) <=> abs(b)
- =head1 * Conversions
- =head2 polar
- my ($rho, $theta) = $x->polar;
- Returns the polar form of C<x>, such that:
- x = rho * exp(theta * i)
- =head2 boolify
- my $bool = $x->boolify;
- Returns a true value when either the real part or the imaginary part of C<x> is non-zero.
- =head2 numify
- my $num = $x->numify;
- Returns the real part of C<x>.
- =head2 stringify
- my $str = $x->stringify;
- Returns a stringification version of C<x>.
- Example:
- Math::GComplex->new( 3, -4)->stringify; # "(3 -4)"
- Math::GComplex->new(-5, 6)->stringify; # "(-5 6)"
- =head1 LIMITATIONS
- Being a generic interface, it assumes that all the special cases (such as division by zero) are handled by the library of which type the components of a complex number are.
- When the components of a complex number are native Perl numbers, the "division by zero" and the "logarithm of zero" cases are implicitly handled by this library.
- However the user may still encounter incorrect results due to rounding errors and/or overflow/underflow in some special cases, such as:
- coth(1e6) = (NaN NaN)
- cosh(1e6) = (NaN NaN)
- =head1 SEE ALSO
- =over 4
- =item * Other math libraries
- L<Math::AnyNum> - Arbitrary size precision for integers, rationals, floating-points and complex numbers.
- L<Math::GMP> - High speed arbitrary size integer math.
- L<Math::GMPz> - perl interface to the GMP library's integer (mpz) functions.
- L<Math::GMPq> - perl interface to the GMP library's rational (mpq) functions.
- L<Math::MPFR> - perl interface to the MPFR (floating point) library.
- L<Math::MPC> - perl interface to the MPC (multi precision complex) library.
- L<Math::Complex> - complex numbers and associated mathematical functions.
- =back
- =head1 REPOSITORY
- L<https://github.com/trizen/Math-GComplex>
- =head1 AUTHOR
- Daniel Șuteu, C<< <trizen at cpan.org> >>
- =head1 COPYRIGHT AND LICENSE
- Copyright (C) 2018-2019 Daniel Șuteu
- This library is free software; you can redistribute it and/or modify
- it under the same terms as Perl itself, either Perl version 5.22.0 or,
- at your option, any later version of Perl 5 you may have available.
- =cut
|