Math::GComplex(3)

NAME
Math::GComplex - Generic complex number library.

VERSION
Version 0.13

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)

DESCRIPTION
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 Math::AnyNum.

In most cases, it can be used as a drop-in replacement for Math::Complex.

Due to its simple and elegant design, Math::GComplex is between 2x up to 8x faster than Math::Complex.

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, "i = sqrt(-1)", is also exportable, as:

    use Math::GComplex qw(i);

Additionally, by specifying the ":all" keyword, all the exportable functions, including the "i" constant, will be exported:

    use Math::GComplex qw(:all);

The ":overload" keyword enables constant overloading, which makes each number a Math::GComplex object and also exports the "i" constant:

    use Math::GComplex qw(:overload);
    CORE::say 3 + 4*i;                          #=> (3 4)
    CORE::say log(-1);                          #=> (0 3.14159265358979)

NOTE: ":overload" is lexical to the current scope only.

The syntax for disabling the ":overload" behavior in the current scope, is:

    no Math::GComplex;        # :overload will be disabled in the current scope

Nothing is exported by default.

INITIALIZATION

  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.

  cplxe / emake
    my $z = cplxe($r, $theta);
    my $z = Math::GComplex->emake($r, $theta);

Create a new complex number, given its polar form.

  i
    my $i = Math::GComplex::i();

Returns the imaginary unit as a Math::GComplex object, equivalent with "cplx(0, 1)".

BASIC OPERATIONS
This section describes all the basic operations provided by this module.

  add
    my $z = $x + $y;
    my $z = $x->add($y);

Addition of "x" and "y", defined as:

    (a + b*i) + (x + y*i) = (a + x) + (b + y)*i

  sub
    my $z = $x - $y;
    my $z = $x->sub($y);

Subtraction of "y" from "x", defined as:

    (a + b*i) - (x + y*i) = (a - x) + (b - y)*i

  mul
    my $z = $x * $y;
    my $z = $x->mul($y);

Multiplication of "x" and "y", defined as:

    (a + b*i) * (x + y*i) = (a*x - b*y) + (a*y + b*x)*i

  div
    my $z = $x / $y;
    my $z = $x->div($y);

Division of "x" by "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

  mod
    my $z = $x % $y;
    my $z = $x->mod($y);

Remainder of "x" when divided by "y", defined as:

    mod(a, b) = a - b * floor(a/b)

  neg
    my $z = -$x;
    my $z = $x->neg;

Additive inverse of "x", defined as:

    neg(a + b*i) = -a - b*i

  conj
    my $z = ~$x;
    my $z = $x->conj;

Complex conjugate of "x", defined as:

    conj(a + b*i) = a - b*i

  inv
    my $z = $x->inv;

Multiplicative inverse of "x", defined as:

    inv(x) = 1/x

  norm
    my $z = $x->norm;

Normalized value of "x", defined as:

    norm(a + b*i) = a^2 + b^2

  abs
    my $z = $x->abs;

Absolute value of "x", defined as:

    abs(a + b*i) = sqrt(a^2 + b^2)

  sgn
    my $z = $x->sgn;

The sign of "x", defined as:

    sgn(x) = x / abs(x)

SPECIAL FUNCTIONS
This section describes the special mathematical functions provided by this module.

  log
    my $z = log($x);
    my $z = $x->log;

Natural logarithm of "x", defined as:

    log(a + b*i) = log(a^2 + b^2)/2 + atan2(b, a) * i

  logn
    my $z = $x->logn($y);

Logarithm of "x" to base "y", defined as:

    logn(a, b) = log(a) / log(b)

  exp
    my $z = exp($x);
    my $z = $x->exp;

Natural exponentiation of "x", defined as:

    exp(a + b*i) = exp(a) * cos(b) + exp(a) * sin(b) * i

  pow
    my $z = $x**$y;
    my $z = $x->pow($y);

Raises "x" to power "y" and returns the result, defined as:

    a^b = exp(log(a) * b)

  pown
    my $z = $x->pown($n);

Raises "x" to power "n", using the exponentiation by squaring method, and returns the result, where "n" is a native integer.

  powmod
    my $z = $x->powmod($n, $m);

Modular exponentiation "x^n mod m", where "n" in an arbitrary large integer.

  gcd
    my $z = $n->gcd($k);

Greatest common divisors of two complex numbers.

  invmod
    my $x = $n->invmod($m);

Modular multiplicative inverse of two complex numbers.

The returned value is the solution to "x" in:

    n*x = 1 (mod m)

Returns "undef" when a multiplicative inverse mod "m" does not exist.

  root
    my $z = $x->root($y);

Nth root of "x", defined as:

    root(a, b) = exp(log(a) / b)

  sqrt
    my $z = sqrt($x);
    my $z = $x->sqrt;

Square root of "x", defined as:

    sqrt(x) = exp(log(x) / 2)

  cbrt
    my $z = $x->cbrt;

Cube root of "x", defined as:

    cbrt(x) = exp(log(x) / 3)

TRIGONOMETRIC FUNCTIONS
This section includes all the trigonometric functions provied by Math::GComplex.

  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)

  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))

  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

  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)

  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)

  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)

  atan2
    my $z = atan2($x, $y);
    my $z = $x->atan2($y);

The arc tangent of "x" and "y", defined as:

    atan2(a, b) = -i * log((b + a*i) / sqrt(a^2 + b^2))

  deg2rad
    my $rad = $x->deg2rad;

Returns the value of "x" converted from degrees to radians.

Defined as:

    deg2rad(x) = x / 180 * atan2(0, -abs(x))

  rad2deg
    my $deg = $x->rad2deg;

Returns the value of "x" converted from radians to degrees.

Defined as:

    rad2deg(x) = x * 180 / atan2(0, -abs(x))

MISCELLANEOUS FUNCTIONS
This section describes the various useful methods provided by this module.

  floor
    my $z = $x->floor;

The floor function, defined as:

    floor(a + b*i) = floor(a) + floor(b)*i

  ceil
    my $z = $x->ceil;

The ceil function, defined as:

    ceil(a + b*i) = ceil(a) + ceil(b)*i

  round
    my $z = $x->round;

The round function, rounding "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

  int
    my $z = int($x);
    my $z = $x->int;

The integer-truncation function, defined as:

    int(a + b*i) = int(a) + int(b)*i

  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

  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

  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

  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))

  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))

  real
    my $re = $x->real;

Return the real part of "x".

  imag
    my $im = $x->imag;

Returns the imaginary part of "x".

  reals
    my ($re, $im) = $x->reals

Returns the real and the imaginary part of "x", as real numbers.

* Comparisons

  eq
    my $bool = $x == $y;
    my $bool = $x->eq($y);

Equality check: returns a true value when "x" and "y" are equal.

  ne
    my $bool = $x != $y;
    my $bool = $x->ne($y);

Inequality check: returns a true value when "x" and "y" are not equal.

  gt
    my $bool = $x > $y;
    my $bool = $x->gt($y);

Returns a true value when "x" is greater than "y".

  ge
    my $bool = $x >= $y;
    my $bool = $x->ge($y);

Returns a true value when "x" is equal or greater than "y".

  lt
    my $bool = $x < $y;
    my $bool = $x->lt($y);

Returns a true value when "x" is less than "y".

  le
    my $bool = $x <= $y;
    my $bool = $x->le($y)

Returns a true value when "x" is equal or less than "y".

  cmp
    my $int = $x <=> $y;
    my $int = $x->cmp($y);

Compares "x" to "y" and returns a negative value when "x" is less than "y", 0 when "x" and "y" are equal, and a positive value when "x" is greater than "y".

Complex numbers are compared as:

    (real($x) <=> real($y)) ||
    (imag($x) <=> imag($y))

  acmp
    my $int = $x->acmp($y);

Absolute comparison of "x" and "y", defined as:

    acmp(a, b) = abs(a) <=> abs(b)

* Conversions

  polar
    my ($rho, $theta) = $x->polar;

Returns the polar form of "x", such that:

    x = rho * exp(theta * i)

  boolify
    my $bool = $x->boolify;

Returns a true value when either the real part or the imaginary part of "x" is non-zero.

  numify
    my $num = $x->numify;

Returns the real part of "x".

  stringify
    my $str = $x->stringify;

Returns a stringification version of "x".

Example:

    Math::GComplex->new( 3, -4)->stringify;    # "(3 -4)"
    Math::GComplex->new(-5,  6)->stringify;    # "(-5 6)"

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)

AUTHOR
Daniel Șuteu, "<trizen at cpan.org>"

BUGS
Please report any bugs or feature requests at <https://github.com/trizen/Math-GComplex/issues>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc Math::GComplex

You can also look for information at:

•   Github

    <https://github.com/trizen/Math-GComplex>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Math-GComplex>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Math-GComplex>

•   Search CPAN

    <http://search.cpan.org/dist/Math-GComplex/>

SEE ALSO

•   Other math libraries

    Math::AnyNum - Arbitrary size precision for integers, rationals, floating-points and complex numbers.

    Math::GMP - High speed arbitrary size integer math.

    Math::GMPz - perl interface to the GMP library's integer (mpz) functions.

    Math::GMPq - perl interface to the GMP library's rational (mpq) functions.

    Math::MPFR - perl interface to the MPFR (floating point) library.

    Math::MPC - perl interface to the MPC (multi precision complex) library.

    Math::Complex - complex numbers and associated mathematical functions.

LICENSE AND COPYRIGHT
Copyright 2018-2019 Daniel Șuteu.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

<http://www.perlfoundation.org/artistic_license_2_0>

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.