# NAME

Math::Bacovia - Symbolic math library with support for alternative representations.

Version 0.04

# SYNOPSIS

Math::Bacovia is an experimental symbolic math library, with support for alternative representations, simplification of expressions and numerical evaluation.

``````    use 5.014;
use Math::Bacovia qw(:all);

my \$x = Symbol('x');
my \$y = Symbol('y');

say \$x+\$y;               #=> Sum(Symbol("x"), Symbol("y"))
say \$x-\$y;               #=> Difference(Symbol("x"), Symbol("y"))
say \$x*\$y;               #=> Product(Symbol("x"), Symbol("y"))
say \$x/\$y;               #=> Fraction(Symbol("x"), Symbol("y"))

say \$x**\$y;              #=> Power(Symbol("x"), Symbol("y"))

say Log(\$x);             #=> Log(Symbol("x"))
say Log(\$x)+Log(\$y);     #=> Log(Product(Symbol("x"), Symbol("y")))

say Exp(\$x);             #=> Exp(Symbol("x"))
say Exp(\$x)*Exp(\$y);     #=> Exp(Sum(Symbol("x"), Symbol("y")))

say "\n=> Sum:";
my \$sum = Fraction(0, 1);

for my \$n (1..10) {
\$sum += Fraction(1, \$n);
}
say \$sum;                     #=> Fraction(10628640, 3628800)
say \$sum->numeric;            #=> 7381/2520

say "\n=> Product:";
my \$prod = Product();

for my \$n (1..3) {
\$prod *= Exp(Fraction(1, \$n));
}

say \$prod->pretty;            #=> (exp(1) * exp(1/2) * exp(1/3))
say \$prod->simple->pretty;    #=> exp(11/6)
say \$prod->numeric;           #=> 6.25470095193632871640207...

say "\n=> Alternative representations:";
say join ', ', Power(3, 5)->alternatives(full => 1);   #=> Power(3, 5), Exp(Product(Log(3), 5)), 243``````

# TYPES

The types supported by this library are described bellow:

## Symbol(name, value=undef)

Represents a symbolic value. Optionally, it can have a numerical value (or any other value).

## Number(value)

Represents a numerical value.

## Fraction(numerator, denominator)

Represents a symbolic fraction.

## Difference(minuend, subtrahend)

Represents a symbolic difference.

## Power(base, power)

Represents a symbolic exponentiation in a symbolic base.

## Log(x)

Represents the natural logarithm of a symbolic value.

## Exp(x)

Represents the natural exponentiation of a symbolic value.

## Sum(a, b, c, ...)

Represents a summation of an arbitrary (finite) number of symbolic values.

## Product(a, b, c, ...)

Represents a product of an arbitrary (finite) number of symbolic values.

# EXPORT

Importing a name from Math::Bacovia can be done using the following syntax:

``    use Math::Bacovia qw(Fraction);     # imports the Fraction() function``

## i / e / pi / tau

Math::Bacovia also provides a small list of useful constants which can be imported:

``````    i      the imaginary unit                sqrt(-1)
e      the e mathematical constant       Exp(1)
pi     the PI mathematical constant      Log(-1) * -sqrt(-1)
tau    the TAU mathmematical constant    Log(-1) * -sqrt(-1) * 2``````

For importing a constant, the same syntax can be used as in importing a function:

``    use Math::Bacovia qw(i tau);``

By specifying the :all special keyword, Math::Bacovia will export all the provided functions and constants.

``    use Math::Bacovia qw(:all);``

Nothing is exported by default.

# METHODS

This section describes the special methods provided by Math::Bacovia.

## inv

``````    1 / \$x
\$x->inv``````

Multiplicative inverse of `x`, defined as:

``    Fraction(1, \$x)``

## neg

``````    -\$x
\$x->neg``````

Additive inverse of `x`, defined as:

``    Difference(0, \$x)``

``````    \$x + \$y

Summation of `x` and `y`, defined as:

``    Sum(\$x, \$y)``

## sub

``````    \$x - \$y
\$x->sub(\$y)``````

Difference of `x` from `y`, defined as:

``    Difference(\$x, \$y)``

## mul

``````    \$x * \$y
\$x->mul(\$y)``````

Product of `x` and `y`, defined as:

``    Product(\$x, \$y)``

## div

``````    \$x / \$y
\$x->div(\$y)``````

Fraction `x` over `y`, defined as:

``    Fraction(\$x, \$y)``

## pow

``````    \$x ** \$y
\$x->pow(\$y)``````

`x` to the power `y`, defined as:

``    Power(\$x, \$y)``

## sqrt

``````    sqrt(\$x)
\$x->sqrt``````

Square root of `x`, defined as:

``    \$x ** Fraction(1, 2)``

## log

``````    log(\$x)
\$x->log``````

Natural logarithm of `x`, defined as:

``    Log(\$x)``

## exp

``````    exp(\$x)
\$x->exp``````

Natural exponentiation of `x`, defined as:

``    Exp(\$x)``

## int

``````    int(\$x)
\$x->int``````

Evaluates `x` numerically and truncates the result to an integer, returing a Math::AnyNum object.

It may return `NaN` when this conversion is not possible.

Defined as:

``    \$x->numeric->int``

# TRIGONOMETRIC METHODS

## sin / sinh / asin / asinh

``````    sin(\$x)
\$x->sin
\$x->sinh
\$x->asin
\$x->asinh``````

Sine, hyperbolic sine, inverse sine and inverse hyperbolic sine.

## cos / cosh / acos / acosh

``````    cos(\$x)
\$x->cos
\$x->cosh
\$x->acos
\$x->acosh``````

Cosine, hyperbolic cosine, inverse cosine and inverse hyperbolic cosine.

## tan / tanh / atan / atanh

``````    \$x->tan
\$x->tanh
\$x->atan
\$x->atanh``````

Tangent, hyperbolic tangent, inverse tangent and inverse hyperbolic tangent.

## cot / coth / acot / acoth

``````    \$x->cot
\$x->coth
\$x->acot
\$x->acoth``````

Cotangent, hyperbolic cotangent, inverse cotangent and inverse hyperbolic cotangent.

## sec / sech / asec / asech

``````    \$x->sec
\$x->sech
\$x->asec
\$x->asech``````

Secant, hyperbolic secant, inverse secant and inverse hyperbolic secant.

## csc / csch / acsc / acsch

``````    \$x->csc
\$x->csch
\$x->acsc
\$x->acsch``````

Cosecant, hyperbolic cosecant, inverse cosecant and inverse hyperbolic cosecant.

## atan2

``````    atan2(\$x, \$y)
\$x->atan2(\$y)``````

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

``    atan2(x, y) = -i * log((y + x*i) / sqrt(x^2 + y^2))``

# SPECIAL METHODS

Each type provided by Math::Bacovia includes the same set of methods, defined bellow:

## alternatives

``    \$x->alternatives(%opt)``

This method uses common mathematical identities to create symbolically equivalent expressions from the self-expression.

Example:

``    say for Exp(Log(Fraction(1,3)) * 2)->alternatives;``

Output:

``````    Exp(Product(2, Log(Fraction(1, 3))))
Power(Fraction(1, 3), 2)
Exp(Product(2, Log(1/3)))
Power(1/3, 2)``````

The options supported by this method are:

``````    log  => 1,    # will try to generate logarithmic alternatives
full => 1,    # will try to generate more alternatives (it may be slow)``````

Example:

``    say for Power(3, 5)->alternatives(full => 1);``

Output:

``````    Power(3, 5)
Exp(Product(Log(3), 5))
243``````

WARNING: The number of alternative representations grows exponentially! For non-trivial expressions, this process may take a very long time and use lots of memory. In combination with the full option (set to a true value), the returned list may contain hundreds or even thousands of alternative representations.

## simple

``    \$x->simple(%opt)``

Returns a simplification of the self-expression, taking the same options as the `alternatives()` method.

``    say Exp(Log(Log(Exp(Exp(Log(Symbol('x')))))))->simple;``

Output:

``    Symbol("x")``

The simplification of an expression is done by generating the list of alternative representations for it, then selecting the shortest expression from this list.

This approach works pretty well even on relatively complex expressions, such as:

``    say Log(Symbol('x'))->cosh->simple->pretty;     #=> ((1 + x^2)/(2 * x))``

However, the returned simplified expression is not guaranteed to always be "optimal". In some cases, calling the `simple()` method on an already simplified expression, the simplified expression may get simplified even further:

``    \$x->simple(full => 1)->simple(full => 1);``

WARNING: On long expressions, this process may take a very long time and use lots of memory.

## expand

``    \$x->expand(%opt)``

Returns an expanded version of the self-expression, taking the same options as the `alternatives()` method.

``    say Power(Fraction(5, 7), Fraction(1, 3))->expand(full => 1);``

Output:

``    Exp(Product(Log(Fraction(5, 7)), Fraction(1, 3)))``

The expansion of an expression is done by generating the list of alternative representations for it, then selecting the longest expression from this list.

WARNING: On long expressions, this process may take a very long time and use lots of memory.

## numeric

``    \$x->numeric``

Evaluates the self-expression numerically and returns the result as a Math::AnyNum object.

Example:

``````    my \$x = Symbol('x', 13);
my \$expr = (\$x**2 - \$x + 41);

say \$expr->numeric;   #=> 197``````

## pretty

``    \$x->pretty``

Returns a human-readable stringification of the self-expression.

Example:

``    say Power(3, Log(Fraction(1, 2)))->pretty;    #=> 3^log(1/2)``

For a detailed documentation of each class, please see:

# AUTHOR

Daniel Șuteu, `<trizen at protonmail.com>`

# BUGS

Please report any bugs or feature requests to https://github.com/trizen/Math-Bacovia. 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::Bacovia``

You can also look for information at:

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: