 NAME
 VERSION
 SYNOPSIS
 DESCRIPTION
 DIAGNOSTICS
 DEPENDENCIES
 BUGS AND LIMITATIONS
 ROADMAP
 SEE ALSO
 AUTHOR
 CONTRIBUTING
 COPYRIGHT AND LICENSE
 DISCLAIMER OF WARRANTY
NAME
Math::Polynomial::Multivariate  Perl class for multivariate polynomials
VERSION
This documentation refers to version 0.007 of Math::Polynomial::Multivariate.
SYNOPSIS
use Math::Polynomial::Multivariate;
my $two = Math::Polynomial::Multivariate>const(2);
my $x = Math::Polynomial::Multivariate>var('x');
my $xy = Math::Polynomial::Multivariate>
monomial(1, {'x' => 1, 'y' => 1});
my $pol = $x**2 + $xy  $two;
print "$pol\n"; # prints: (2 + x^2 + x*y)
my @mon = $pol>as_monomials;
# assigns: ([2, {}], [1, {x => 2}], [1, {x => 1, y => 1}])
my $n_terms = $pol>as_monomials;
print "$n_terms\n"; # prints: 3
my $rat = Math::BigRat>new('1/3');
my $c = Math::Polynomial::Multivariate>const($rat);
my $y = $c>var('y');
my $lin = $x  $c;
print "$lin\n"; # prints: (1/3 + x)
my $zero = $c  $c; # zero polynomial on rationals
my $null = $c>null; # dito
my $p = $c>monomial($rat, { 'a' => 2, 'b' => 1 });
print "$p\n"; # prints: (1/3*a^2*b)
my $f = $p>coefficient({'a' => 2, 'b' => 1});
print "$f\n"; # prints: 1/3
my $q = $p>subst('a', $c);
print "$q\n"; # prints: (1/27*b)
my $v = $p>evaluate({'a' => 6, 'b' => 1});
print "$v\n"; # prints: 12
my @vars = $pol>variables;
print "@vars\n"; # prints: x y
my @exp = $pol>exponents_of('x');
print "@exp\n"; # prints: 0 1 2
my $r = $pol>factor_of('x', 1);
print "$r\n"; # prints: (y)
my $d = $pol>degree;
print "$d\n"; # prints: 2
my $z = $zero>degree;
print "$z\n"; # prints:
# platformdependent equivalent of minus infinity
my $pd = $pol>partial_derivative('x');
print "$pd\n"; # prints: (2*x + y)
my $by_x = $pol>extract('x');
print "$by_x\n"; # prints: ((2) + (y)*x + x^2)
print "yes\n"
if $pol == $by_x>flatten; # prints: yes
DESCRIPTION
Math::Polynomial::Multivariate is a Perl class representing polynomials in any number of variables. It provides a set of operations defined for these polynomials, like addition, multiplication, evaluation, variable substitution, etc., as well as attribute inspection and formatting capabilities.
Objects of this class can be created using some simple constructors and expressions with overloaded arithmetic operators. They are immutable.
Each polynomial object is bound to specific variables. For practical purposes, variables are identified by unique names given as strings. Polynomials bound to different variables can be combined in a single expression, resulting in a new polynomial bound to the union of all contributing variables. Any polynomial will be treated as a polynomial of degree zero with respect to a variable it is not already bound to. Therefore, all polynomials sharing a common coefficient space are compatible to each other.
Polynomials are considered equal if they are bound to the same set of variables and have equal nonzero coefficients. Zero coefficients do not bind, thus the zero polynomial is not bound to any variable.
Constructors
 null

Invoked as a class method,
Math::Polynomial::Multivariate>null
returns a null polynomial on Perl numerical values.Invoked as an object method,
$obj>null
returns a null polynomial on the coefficient space of$obj
.  const

Invoked as a class method,
Math::Polynomial::Multivariate>const($value)
returns a constant polynomial on the coefficent space containing$value
.Invoked as an object method,
$obj>const($value)
returns a constant polynomial on the coefficient space of$obj
.$value
must belong to the same coefficient space.  var

Invoked as a class method,
Math::Polynomial::Multivariate>var($varname)
returns an identity polynomial in the named variable on Perl numerical values.Invoked as an object method,
$obj>var($varname)
returns an identity polynomial in the named variable on the coefficient space of$obj
.  monomial

Invoked as a class method,
Math::Polynomial::Multivariate>monomial($const, $vars)
returns a oneterm polynomial on the coefficent space containing$const
.Invoked as an object method,
$obj>monomial($const, $vars)
returns a oneterm polynomial on the coefficient space of$obj
.$const
must belong to the same coefficient space.In both cases,
$vars
is a hashref mapping variable names to nonnegative integer exponents.Example:
$p>monomial(1, {'x' => 1})
is equivalent to$p>var('x')
.
Overloaded Perl Operators
 Negation

If
$p
is a polynomial,$p
evaluates as the negative of$p
.  Addition

If
$p
and$q
are polynomials on the same coefficient space,$p + $q
evaluates as the sum of$p
and$q
.  Subtraction

If
$p
and$q
are polynomials on the same coefficient space,$p  $q
evaluates as the difference of$p
and$q
.  Multiplication

If
$p
and$q
are polynomials on the same coefficient space,$p * $q
evaluates as the product of$p
and$q
.  Exponentiation

If
$p
is a polynomial and$n
is a nonnegative integer number,$p ** $n
evaluates as the$n
th power of$p
.  Checks for Equality

If
$p
and$q
are polynomials on the same coefficient space,$p == $q
and$p != $q
are boolean expressions telling whether$p
and$q
are equal or unequal, respectively.Equality implies that both polynomials are bound to the same variables and are composed of the same terms.
 Boolean Context

In boolean context, null polynomials evaluate as false and all other polynomials as true.
 String Context

In string context, polynomials are converted to a string representation. See "as_string".
Other Operators
 subst

If
$p
and$q
are polynomials on the same coefficient space,$p>subst($varname, $q)
returns a polynomial obtained from$p
by substituting the variable named$varname
by the polynomial$q
.  partial_derivative

If
$p
is a polynomial on a coefficient space compatible to Perl integer numbers,$p>partial_derivative($varname)
returns the first partial derivative of$p
with respect to the variable named$varname
.If
$p
is a polynomial on any coefficient space and$cast
is a coderef referencing a subroutine that takes a positive integer n and returns the element representing n times the unit element of this coefficient space,$p>partial_derivative($varname, $cast)
returns the first partial derivative of$p
with respect to the variable named$varname
.Example: For the coefficient space of 4×4 matrices of Perl numerical values,
$cast
could be a reference to a function taking a single value and returning a 4×4 diagonal matrix with this value.  extract

If
$p
is an arbitrary polynomial and$var
is one of its variables,$p>extract($var)
returns the same polynomial as a univariate polynomial in only that variable and with coefficients that are polynomials themselves, but without that variable.  flatten

If
$p
is a polynomial in hierarchical form, i.e. with coefficients that might be polynomials themselves (either flat or hierarchical again),$p>flatten
returns the same polynomial in flat form, i.e. as a plain sum of multivariate monomials with nonpolynomial coefficients.Note that flatten and extract are the only methods that will switch coefficient spaces.
Note also that, currently, most of this module assumes polynomials being flat.
Inspection Methods
 is_null

If
$p
is a polynomial,$p>is_null
returns a boolean value telling whether$p
is the null polynomial.  is_not_null

If
$p
is a polynomial,$p>is_not_null
returns a boolean value telling whether$p
is not the null polynomial.  variables

If
$p
is a polynomial,$p>variables
returns an alphabetically ordered list of names of variables this polynomial is bound to.Note that only variables in terms with nonzero coefficients are taken into account. For example, a null polynomial will yield an empty list even if it was the result of an addition of nonzero polynomials.
 exponents_of

If
$p
is a polynomial,$p>exponents_of($varname)
returns a list of nonnegative integer exponents in ascending numerical order, specifying all powers of the named variable that are present in terms with nonzero coefficients of the polynomial.Note that if
$p
is not bound to the named variable and not zero, a single exponent of zero will be returned. If$p
is the null polynomial, an empty list will be returned.  factor_of

If
$p
is a polynomial,$p>factor_of($varname, $exponent)
returns the polynomial factor of the given variable power in that polynomial. In other words, the terms in$p
are grouped by powers of the named variable, the specific power is selected, and factored out.Example:
$c = Math::Polynomial::Multivariate>const(3); $x = $c>var('x'); $y = $c>var('y'); $p = ($y**2 + $c * $y  $c) * $x**2 + ($y  $c) * $x**3; $q = $p>factor_of('x', 2); # (I) $q = $y**2 + $c * $y  $c; # same as (I)
 coefficient

If
$p
is a polynomial and$variables
is a hashref mapping variable names to nonnegative integer exponents,$p>coefficient($variables)
returns the coefficient of an individual term in$p
with the given signature.Example:
$c = Math::Polynomial::Multivariate>const(4); $x = $c>var('x'); $y = $c>var('y'); $p = $x**2 * $y  $c * $x * $y**2; $a = $p>coefficient( {'x' => 2, 'y' => 1} ); $b = $p>coefficient( {'x' => 1, 'y' => 2} ); $c = $p>coefficient( {'x' => 0, 'y' => 3} ); # now $a is 1, $b is 4, $c is 0
Note that in the
$variables
hashref, variables with zero exponent may be omitted.  degree

If
$p
is a polynomial with only one term with nonzero coefficient,$p>degree
returns the sum of all exponents of the variables present there.If
$p
is an arbitrary polynomial other than null,$p>degree
returns the largest degree of all its terms with nonzero coefficients.If
$p
is the null polynomial,$p>degree
returns minus infinity.Example:
$c = Math::Polynomial::Multivariate>const(5); $x = $c>var('x'); $y = $c>var('y'); $p = $x**3 * $y**3  $c * $x**2 * $y**5; $d = $p>degree; # now $d is 7
 multidegree

If
$p
is a polynomial,$p>multidegree
returns a hashref mapping variable names to positive integer exponents, denoting the largest degree of each variable in any term of$p
with nonzero coefficient. Zero exponents are omitted. Thus, the null polynomial as well as constant polynomials will yield an empty hashref.Example:
$c = Math::Polynomial::Multivariate>const(6); $x = $c>var('x'); $y = $c>var('y'); $p = $x**3 * $y**3  $c * $x**2 * $y**5; $m = $p>multidegree; # now $m is { 'x' => 3, 'y' => 5 }
 number_of_terms

If
$p
is a polynomial,$p>number_of_terms
returns the number of distinct terms with nonzero coefficients of$p
.This number will be at least 0 and at most the product of all values, incremented by one, of the multidegree hashref.
 evaluate

If
$p
is a polynomial and $values is a hashref mapping variable names to values in the coefficient space of$p
,$p>evaluate($values)
returns the value of the polynomial at the given coordinates. The$values
hashref must contain all names of variables that appear in terms with nonzero coefficients. It may contain values of additional variables.Example:
$c = Math::Polynomial::Multivariate>const(7); $x = $c>var('x'); $y = $c>var('y'); $p = $c + $x + $y; $z = $p>evaluate({'x' => 8, 'y' => 9}); # now $z is 24
 as_string

If
$p
is a polynomial,$p>as_string
returns a text representation of it. It is the same as the value of$p
in string context.Variables are ordered lexically, terms are ordered from lowest exponent to highest, exponents of last variables taking precedence over earlier ones. Each term is represented as a product of the coefficient and the variable powers, with an asterisk as a multiplication symbol and a plus as addition symbol between terms. A caret is used as exponentiation symbol. Terms with zero coefficient are suppressed except for the null polynomial which is represented by the constant zero. Variables are given by their name. Coefficients appear in whatever form they take on in string context. Values of one as a coefficient or as an exponent are omitted where possible. The whole expression is surrounded by parentheses.
Example:
(1 + 2*x + x^2 + 2*y + 2*x*y + y^2)
 as_monomials

If
$p
is a polynomial,$p>as_monomials
returns a list of monomial term descriptors in the same order as as_string. A descriptor is an arrayref of a coefficient and a variables hashref (like the pair of parameters for the "monomial" constructor).For the zero polynomial, a single term with a zero coefficient and an empty variables hash is returned.
In scalar context, the number of nonzero terms is returned.
EXPORT
None.
DIAGNOSTICS
This module generally croaks on usage errors it detects. This means, outside of an eval block program execution will terminate with an error message indicating the offending method call.
 illegal exponent

The power operator (
**
) was used with a negative or noninteger exponent. In the domain of polynomials, only exponentiation by nonnegative integers is defined in general.  missing variable: %s
 missing variables: %s

The evaluate method was called with a hashref not containing all required variable names. The missing name or names are listed in the message.
DEPENDENCIES
This version of Math::Polynomial::Multivariate requires these other modules and libraries to run:
perl version 5.8.0 or higher
overload (usually bundled with perl)
Carp (usually bundled with perl)
Additional requirements to run the test suite are:
Test::More (usually bundled with perl)
Recommended modules for increased functionality are:
Math::BigRat (usually bundled with perl)
Any other module providing a coefficient space with overloaded arithmetic operators
+
,
,*
,**
,==
,!=
, and stringification.
BUGS AND LIMITATIONS
Currently, not a lot of usage errors are caught and reported via individual diagnostics. Notably, there are no safeguards against mixing incompatible coefficients within one polynomial expression.
Some constructors may look more generic than they actually are: It would be best, perhaps, not to use null and var as class methods at all, as this usage implies a coefficient space, and one with many shortcomings at that.
There may be a hidden limitation on the maximal exponent of a variable on some platforms. This will go away or become an explicit limitation before this library is declared stable. If your exponents stay well below 2**32 you probably should not worry.
The functionality of this module should not be taken as final.
Bug reports and suggestions are always welcome. Please submit them through the github issue tracker, https://github.com/mhasch/perlMathPolynomialMultivariate/issues.
ROADMAP
As of version 0.007, the module interface is still in beta state. While upcoming improvements are intended to be mostly extensions, changes breaking backwards compatibility may yet be considered.
Features planned for future releases include:
Polynomial substitution, using remainder decomposition. This generalizes simple variable substitution.
Interoperability with, or conversion functions to/from, Math::Polynomial objects.
Division with remainder.
More string formatting options.
Resultants and discriminants.
SEE ALSO
Math::Polynomial  perl class for univariate polynomials
Math::Symbolic  perl class for more general arithmetic expressions
AUTHOR
Martin Becker, Blaubeuren, <beckercpanmp (at) cozap.com>
CONTRIBUTING
Contributions to this library are welcome (see the CONTRIBUTING file).
COPYRIGHT AND LICENSE
Copyright (c) 20112022 by Martin Becker, Blaubeuren.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 (see the LICENSE file).
DISCLAIMER OF WARRANTY
This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.