<commit_before># Math-Bacovia

Math::Bacovia is a symbolic math library, with support for numerical evaluation (including support for complex numbers).

# EXAMPLE

```perl
use utf8;
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))
```


# DESCRIPTION

The types supported by this library are described bellow:

#### # `Symbol(name, value=undef)`

Represents a symbolic value. Optionally, it can have a numeric value.

#### # `Fraction(numerator, denominator)`

Represents a symbolic fraction.

#### # `Difference(minuend, subtrahend)`

Represents a symbolic subtraction.

#### # `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.

# SPECIAL METHODS

An interesting feature is the support for alternative representations (provided by the method `alternatives()`),
which uses common mathematical identities to create symbolically equivalent expressions from the self-expression.

Bellow we describe the special methods provided by this library:

#### # `alternatives()`

Returns an array with alternative representations from the self-expression.

```perl
say for Exp(Log(3) * 2)->alternatives;
```

Output:

```perl
Exp(Product(Log(3), 2))
Power(3, 2)
9
```

This method also accepts currently two options:

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

The options can be provided as:

```perl
$obj->alternatives(
    full => 1,
    log  => 1,
)
```

#### # `simple()`

Returns a simplification of the self-expression.

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

Output:

```perl
Symbol("x")
```

The options that can be passed to the `alternatives()` method, can also be passed to this method, as:

```perl
$obj->simple(
    full => 1,
    log  => 1,
);
```

#### # `pretty()`

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

```perl
say Power(3, Log(Fraction(1, 2)))->pretty;
```

Output:
```ruby
3^log(1/2)
```

#### # `numeric()`

Evaluates the self-expression numerically and returns the result as a Number object.

```perl
my $x = Symbol('x');
my $expr = ($x**2 - $x + 41);
<commit_msg>Documented the `expand` method.<commit_after># Math-Bacovia

Math::Bacovia is a symbolic math library, with support for numerical evaluation (including support for complex numbers).

# EXAMPLE

```perl
use utf8;
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))
```


# DESCRIPTION

The types supported by this library are described bellow:

#### # `Symbol(name, value=undef)`

Represents a symbolic value. Optionally, it can have a numeric value.

#### # `Fraction(numerator, denominator)`

Represents a symbolic fraction.

#### # `Difference(minuend, subtrahend)`

Represents a symbolic subtraction.

#### # `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.

# SPECIAL METHODS

An interesting feature is the support for alternative representations (provided by the method `alternatives()`),
which uses common mathematical identities to create symbolically equivalent expressions from the self-expression.

Bellow we describe the special methods provided by this library:

#### # `alternatives()`

Returns an array with alternative representations from the self-expression.

```perl
say for Exp(Log(3) * 2)->alternatives;
```

Output:

```perl
Exp(Product(Log(3), 2))
Power(3, 2)
9
```

This method also accepts currently two options:

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

The options can be provided as:

```perl
$obj->alternatives(
    full => 1,
    log  => 1,
);
```

#### # `simple()`

Returns a simplification of the self-expression.

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

Output:

```perl
Symbol("x")
```

Accepts the same options as the `alternatives()` method.

#### # `expand()`

Returns an expanded version of the self-expression.

```perl
say Log(Symbol('x') * Symbol('y'))->expand(full => 1);
```

Output:
```perl
Sum(Log(Symbol("x")), Log(Symbol("y")))
```

Accepts the same options as the `alternatives()` method.

#### # `pretty()`

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

```perl
say Power(3, Log(Fraction(1, 2)))->pretty;
```

Output:
```ruby
3^log(1/2)
```

#### # `numeric()`

Evaluates the self-expression numerically and returns the result as a Number object.

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

{'fraction_non_alphanumeric': 0.18809930382240903, 'fraction_numerical': 0.02561408117693419, 'mean_word_length': 3.7380211574362168, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 74, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2380689', 'n_tokens_mistral': 2755, 'n_tokens_neox': 2480, 'n_words': 794}