/ 
Math-BigSym-0.01
/ Math::BigSym

NAME

Math::BigSym - Fast symbolic calculations with arbitrary large rationals.

VERSION

Version 0.01

SYNOPSIS

use 5.014;
use Math::BigSym qw(:constant);

# Rational operations
my $x = 2/3;
say $x * 3;                    # => 2
say 2 / $x;                    # => 3
say $x;                        # => "2/3"
say 1 + 4.5**(-3);             # => "737/729"

# Floating-point operations
say "equal" if (1.1 + 2.2 == 3.3);  # => "equal"

# Symbolic operations
say log(-5) / 2;               # => "1/2*log(-5)"
say sqrt(exp(-1));             # => "sqrt(exp(-1))"

DESCRIPTION

Math::BigSym provides a transparent interface to Math::GMPq and Math::Algebra::Symbols, focusing on performance and easy-to-use.

HOW IT WORKS

Math::BigSym tries really hard to do the right thing and as efficiently as possible. For example, if you say $x**$y, it first checks to see if $x and $y are integers, so it can optimize the operation to integer exponentiation, by calling the corresponding mpz function. Otherwise, it will check to see if $y is an integer and will do rational exponentiation, by multiplying $x by itself $y times. If both conditions fail, it will do symbolic exponentiation, using the relation: a^b = exp(log(a) * b).

All numbers in Math::BigSym are stored as rational Math::GMPq objects. Each operation outside the functions provided by Math::GMPq, is done symbolically, calling the corresponding Math::Algebra::Symbols functions.

IMPORT/EXPORT

Math::BigSym does not export anything by default, but it recognizes the following list of words:

:constant       # will make any number a Math::BigSym object
i               # "i" number (sqrt(-1))
e               # "e" constant (2.7182...)
pi              # "pi" constant (3.1415...)
tau             # "tau" constant (2*pi)
phi             # Golden ratio constant (1.618...)
ln2             # Natural logarithm of two (log(2))

The syntax for importing something, is:

use Math::BigSym qw(:constant pi);
say cos(2*pi);

NOTE: :constant is lexical to the current scope only.

SUBROUTINES/METHODS

pi

BigSym->pi                     # => BigSym

Returns a symbolic object to represent the number PI.

tau

BigSym->tau                    # => BigSym

Returns a symbolic object to represent the number TAU (which is 2*PI).

i

BigSym->i                      # => BigSym

Returns a symbolic object to represent the number i.

e

BigSym->e                      # => BigSym

Returns a symbolic object to represent the e mathematical constant.

ln2

BigSym->ln2                    # => BigSym

Returns a symbolic object to represent the natural logarithm of two (log(2)).

phi

BigSym->phi                    # => BigSym

Returns a symbolic object to represent the Golden Ratio constant ((sqrt(5)+1)/2).

new

BigSym->new(Scalar)            # => BigSym
BigSym->new(Scalar, Scalar)    # => BigSym

Returns a new BigSym object with the value specified in the first argument, which can be a Perl numerical value, a string representing a number in a rational form, such as "1/2", a string holding a floating-point number, such as "0.5", or a string holding an integer, such as "255", or a symbol.

The second argument specifies the base of the number, which can range from 2 to 36 inclusive and defaults to 10.

This sets a symbol:

my $x = Math::BigSym->new('x');

This sets an hexadecimal number:

my $y = Math::BigSym->new("deadbeef", 16);

NOTE: no prefix, such as "0x" or "0b", is allowed as part of the number.

stringify

$x->stringify                  # => Scalar

Returns a string representing the value of $x.

numify

$x->numify                     # => Scalar

If $x is a rational number, it returns a Perl numerical scalar with the value of $x, truncated if needed. Otherwise, it just returns the symbolic value stored inside $x.

boolify

$x->boolify                    # => Bool

Returns a true value when the number is not zero. False otherwise.

neg

$x->neg                        # => BigSym
-$x                            # => BigSym

Returns the negated value of $x.

abs

$x->abs                        # => BigSym
abs($x)                        # => BigSym

Absolute value of $x.

add

$x->add(BigSym)                # => BigSym
$x->add(Scalar)                # => BigSym

BigSym + BigSym                # => BigSym
BigSym + Scalar                # => BigSym
Scalar + BigSym                # => BigSym

Adds $y to $x and returns the result.

sub

$x->sub(BigSym)                # => BigSym
$x->sub(Scalar)                # => BigSym

BigSym - BigSym                # => BigSym
BigSym - Scalar                # => BigSym
Scalar - BigSym                # => BigSym

Subtracts $y from $x and returns the result.

mul

$x->mul(BigSym)                # => BigSym
$x->mul(Scalar)                # => BigSym

BigSym * BigSym                # => BigSym
BigSym * Scalar                # => BigSym
Scalar * BigSym                # => BigSym

Multiplies $x by $y and returns the result.

div

$x->div(BigSym)                # => BigSym
$x->div(Scalar)                # => BigSym

BigSym / BigSym                # => BigSym
BigSym / Scalar                # => BigSym
Scalar / BigSym                # => BigSym

Divides $x by $y and returns the result. Returns log(0) * +/-1 when $y is zero.

pow

$x->pow(BigSym)                # => BigSym
$x->pow(Scalar)                # => BigSym

BigSym ** BigSym               # => BigSym
BigSym ** Scalar               # => BigSym
Scalar ** BigSym               # => BigSym

Raises $x to power $y symbolically, based on the relation: a^b = exp(log(a) * b). When $x and $y are both integers, or when $x is a rational and $y is an integer smaller than 2^12, it will perform the actual calculation.

root

$x->root(BigSym)               # => BigSym
$x->root(Scalar)               # => BigSym

Returns a symbolic representation for the nth root of $x, based on the relation: a^(1/b) = exp(log(a) / b).

sqrt

$x->sqrt                       # => BigSym
sqrt($x)                       # => BigSym

Returns a symbolic representation for the square root of $x. When $x is an integer that is a perfect square, it will perform the actual calculation.

ln

$x->ln                         # => BigSym

Returns a symbolic representation for the logarithm of $x in base e.

log

$x->log                        # => BigSym
$x->log(BigSym)                # => BigSym
$x->log(Scalar)                # => BigSym
log(BigSym)                    # => BigSym

Returns a symbolic representation for the logarithm of $x in base $y. When $y is not specified, it defaults to base e.

exp

$x->exp                        # => BigSym

Returns a symbolic representation for the exponential of $x in base e. (e**$x)

tan

$x->tan                        # => BigSym

Returns a symbolic representation for the tangent of $x.

sec

$x->sec                        # => BigSym

Returns a symbolic representation for the secant of $x.

csc

$x->csc                        # => BigSym

Returns a symbolic representation for the cosecant of $x.

cot

$x->cot                        # => BigSym

Returns a symbolic representation for the cotangent of $x.

sin

$x->sin                        # => BigSym

Returns a symbolic representation for the sine of $x.

cos

$x->cos                        # => BigSym

Returns a symbolic representation for the cosine of $x.

sinh

$x->sinh                       # => BigSym

Returns a symbolic representation for the hyperbolic sine of $x.

cosh

$x->cosh                       # => BigSym

Returns a symbolic representation for the hyperbolic cosine of $x.

tanh

$x->tanh                       # => BigSym

Returns a symbolic representation for the hyperbolic tangent of $x.

sech

$x->sech                       # => BigSym

Returns a symbolic representation for the hyperbolic secant of $x.

csch

$x->csch                       # => BigSym

Returns a symbolic representation for the hyperbolic cosecant of $x.

coth

$x->coth                       # => BigSym

Returns a symbolic representation for the hyperbolic cotangent of $x.

conjugate

~$x                            # => BigSym
$x->conjugate                  # => BigSym

Returns the complex conjugate of $x.

cross

$x->cross(BigSym)              # => BigSym

Returns the complex cross product of $x and $y.

dot

$x->dot(BigSym)                # => BigSym

Returns the complex dot product of $x and $y.

unit

$x->unit                       # => BigSym

Returns a complex number of unit length pointing in the same direction as $x.

re

$x->re                         # => BigSym

Returns the real part of the complex number $x.

im

$x->im                         # => BigSym

Returns the imaginary part of the complex number $x.

eq

$x->eq(BigSym)                 # => Bool
$x->eq(Scalar)                 # => Bool

$x == $y                       # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

ne

$x->ne(BigSym)                 # => Bool
$x->ne(Scalar)                 # => Bool

$x != $y                       # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

gt

$x->gt(BigSym)                 # => Bool
$x->gt(Scalar)                 # => Bool

BigSym > BigSym                # => Bool
BigSym > Scalar                # => Bool
Scalar > BigSym                # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

ge

$x->ge(BigSym)                 # => Bool
$x->ge(Scalar)                 # => Bool

BigSym >= BigSym               # => Bool
BigSym >= Scalar               # => Bool
Scalar >= BigSym               # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

lt

$x->lt(BigSym)                 # => Bool
$x->lt(Scalar)                 # => Bool

BigSym < BigSym                # => Bool
BigSym < Scalar                # => Bool
Scalar < BigSym                # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

le

$x->le(BigSym)                 # => Bool
$x->le(Scalar)                 # => Bool

BigSym <= BigSym               # => Bool
BigSym <= Scalar               # => Bool
Scalar <= BigSym               # => Bool

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

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

cmp

$x->cmp(BigSym)                # => Scalar
$x->cmp(Scalar)                # => Scalar

BigSym <=> BigSym              # => Scalar
BigSym <=> Scalar              # => Scalar
Scalar <=> BigSym              # => Scalar

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.

NOTE: expects $x and $y to have rational values. Symbolic representations, such as sqrt(2), are treated literally.

AUTHOR

Daniel Șuteu, <trizenx at gmail.com>

BUGS and LIMITATIONS

Please report any bugs or feature requests to bug-math-bignum at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-BigSym. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

The currently known issues are:

  • multiplication of logarithms is not currently supported by Math::Algebra::Symbols.

  • there are some "division by zero" exceptions raised by Math::Algebra::Symbols in some trigonometric functions.

  • integer operations, such as |, &, ^, <<<<>>, <<>>>>, are not supported.

  • the modulo operator (%) is also not supported.

SUPPORT

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

perldoc Math::BigSym

You can also look for information at:

SEE ALSO

Math::Algebra::Symbols, Math::Symbolic.

LICENSE AND COPYRIGHT

Copyright 2016 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.