.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Math::Cephes::Polynomial 3pm"
.TH Math::Cephes::Polynomial 3pm "2021-06-22" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Math::Cephes::Polynomial \- Perl interface to the cephes math polynomial routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Math::Cephes::Polynomial qw(poly);
\&  # \*(Aqpoly\*(Aq is a shortcut for Math::Cephes::Polynomial\->new
\&
\&  require Math::Cephes::Fraction; # if coefficients are fractions
\&  require Math::Cephes::Complex;  # if coefficients are complex
\&
\&  my $a = poly([1, 2, 3]);           # a(x) = 1 + 2x + 3x^2
\&  my $b = poly([4, 5, 6, 7];         # b(x) = 4 + 5x + 6x^2 + 7x^3
\&  my $c = $a\->add($b);               # c(x) = 5 + 7x + 9x^2 + 7x^3
\&  my $cc = $c\->coef;
\&  for (my $i=0; $i<4; $i++) {
\&     print "term $i: $cc\->[$i]\en";
\&  }
\&  my $x = 2;
\&  my $r = $c\->eval($x);
\&  print "At x=$x, c(x) is $r\en";
\&
\&  my $u1 = Math::Cephes::Complex\->new(2,1);
\&  my $u2 = Math::Cephes::Complex\->new(1,\-3);
\&  my $v1 = Math::Cephes::Complex\->new(1,3);
\&  my $v2 = Math::Cephes::Complex\->new(2,4);
\&  my $z1 = Math::Cephes::Polynomial\->new([$u1, $u2]);
\&  my $z2 = Math::Cephes::Polynomial\->new([$v1, $v2]);
\&  my $z3 = $z1\->add($z2);
\&  my $z3c = $z3\->coef;
\&  for (my $i=0; $i<2; $i++) {
\&     print "term $i: real=$z3c\->{r}\->[$i], imag=$z3c\->{i}\->[$i]\en";
\&  }
\&  $r = $z3\->eval($x);
\&  print "At x=$x, z3(x) has real=", $r\->r, " and imag=", $r\->i, "\en";
\&
\&  my $a1 = Math::Cephes::Fraction\->new(1,2);
\&  my $a2 = Math::Cephes::Fraction\->new(2,1);
\&  my $b1 = Math::Cephes::Fraction\->new(1,2);
\&  my $b2 = Math::Cephes::Fraction\->new(2,2);
\&  my $f1 = Math::Cephes::Polynomial\->new([$a1, $a2]);
\&  my $f2 = Math::Cephes::Polynomial\->new([$b1, $b2]);
\&  my $f3 = $f1\->add($f2);
\&  my $f3c = $f3\->coef;
\&  for (my $i=0; $i<2; $i++) {
\&     print "term $i: num=$f3c\->{n}\->[$i], den=$f3c\->{d}\->[$i]\en";
\&  }
\&  $r = $f3\->eval($x);
\&  print "At x=$x, f3(x) has num=", $r\->n, " and den=", $r\->d, "\en";
\&  $r = $f3\->eval($a1);
\&  print "At x=", $a1\->n, "/", $a1\->d,
\&      ", f3(x) has num=", $r\->n, " and den=", $r\->d, "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a layer on top of the basic routines in the
cephes math library to handle polynomials. In the following,
a Math::Cephes::Polynomial object is created as
.PP
.Vb 1
\&  my $p = Math::Cephes::Polynomial\->new($arr_ref);
.Ve
.PP
where \f(CW$arr_ref\fR is a reference to an array which can
consist of one of
.IP "\(bu" 4
floating point numbers, for polynomials with floating
point coefficients,
.IP "\(bu" 4
\&\fIMath::Cephes::Fraction\fR or \fIMath::Fraction\fR objects,
for polynomials with fractional coefficients,
.IP "\(bu" 4
\&\fIMath::Cephes::Complex\fR or \fIMath::Complex\fR objects,
for polynomials with complex coefficients,
.PP
The maximum degree of the polynomials handled is set by default
to 256 \- this can be changed by setting \fI\f(CI$Math::Cephes::Polynomial::MAXPOL\fI\fR.
.PP
A copy of a \fIMath::Cephes::Polynomial\fR object may be done as
.PP
.Vb 1
\&  my $p_copy = $p\->new();
.Ve
.PP
and a string representation of the polynomial may be gotten through
.PP
.Vb 1
\&  print $p\->as_string;
.Ve
.SS "Methods"
.IX Subsection "Methods"
The following methods are available.
.IP "\fIcoef\fR: get coefficients of the polynomial" 4
.IX Item "coef: get coefficients of the polynomial"
.Vb 1
\& SYNOPSIS:
\&
\& my $c = $p\->coef;
\&
\& DESCRIPTION:
.Ve
.Sp
This returns an array reference containing the coefficients of
the polynomial.
.IP "\fIclr\fR: set a polynomial identically equal to zero" 4
.IX Item "clr: set a polynomial identically equal to zero"
.Vb 1
\& SYNOPSIS:
\&
\& $p\->clr($n);
\&
\& DESCRIPTION:
.Ve
.Sp
This sets the coefficients of the polynomial identically to 0,
up to \f(CW$p\fR\->[$n]. If \f(CW$n\fR is omitted, all elements are set to 0.
.IP "\fIadd\fR: add two polynomials" 4
.IX Item "add: add two polynomials"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->add($b);
\&
\& DESCRIPTION:
.Ve
.Sp
This sets \f(CW$c\fR equal to \f(CW$a\fR + \f(CW$b\fR.
.IP "\fIsub\fR: subtract two polynomials" 4
.IX Item "sub: subtract two polynomials"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->sub($b);
\&
\& DESCRIPTION:
.Ve
.Sp
This sets \f(CW$c\fR equal to \f(CW$a\fR \- \f(CW$b\fR.
.IP "\fImul\fR: multiply two polynomials" 4
.IX Item "mul: multiply two polynomials"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->mul($b);
\&
\& DESCRIPTION:
.Ve
.Sp
This sets \f(CW$c\fR equal to \f(CW$a\fR * \f(CW$b\fR.
.IP "\fIdiv\fR: divide two polynomials" 4
.IX Item "div: divide two polynomials"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->div($b);
\&
\& DESCRIPTION:
.Ve
.Sp
This sets \f(CW$c\fR equal to \f(CW$a\fR / \f(CW$b\fR, expanded by a Taylor series. Accuracy
is approximately equal to the degree of the polynomial, with an
internal limit of about 16.
.IP "\fIsbt\fR: change of variables" 4
.IX Item "sbt: change of variables"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->sbt($b);
\&
\& DESCRIPTION:
.Ve
.Sp
If a(x) and b(x) are polynomials, then
.Sp
.Vb 1
\&     c(x) = a(b(x))
.Ve
.Sp
is a polynomial found by substituting b(x) for x in a(x). This method is
not available for polynomials with complex coefficients.
.IP "\fIeval\fR: evaluate a polynomial" 4
.IX Item "eval: evaluate a polynomial"
.Vb 1
\& SYNOPSIS:
\&
\& $s = $a\->eval($x);
\&
\& DESCRIPTION:
.Ve
.Sp
This evaluates the polynomial at the value \f(CW$x\fR. The returned value
is of the same type as that used to represent the coefficients of
the polynomial.
.IP "\fIsqt\fR: square root of a polynomial" 4
.IX Item "sqt: square root of a polynomial"
.Vb 1
\& SYNOPSIS:
\&
\& $b = $a\->sqt();
\&
\& DESCRIPTION:
.Ve
.Sp
This finds the square root of a polynomial, evaluated by a
Taylor expansion. Accuracy is approximately equal to the
degree of the polynomial, with an internal limit of about 16.
This method is not available for polynomials with complex coefficients.
.IP "\fIsin\fR: sine of a polynomial" 4
.IX Item "sin: sine of a polynomial"
.Vb 1
\& SYNOPSIS:
\&
\& $b = $a\->sin();
\&
\& DESCRIPTION:
.Ve
.Sp
This finds the sine of a polynomial, evaluated by a
Taylor expansion. Accuracy is approximately equal to the
degree of the polynomial, with an internal limit of about 16.
This method is not available for polynomials with complex coefficients.
.IP "\fIcos\fR: cosine of a polynomial" 4
.IX Item "cos: cosine of a polynomial"
.Vb 1
\& SYNOPSIS:
\&
\& $b = $a\->cos();
\&
\& DESCRIPTION:
.Ve
.Sp
This finds the cosine of a polynomial, evaluated by a
Taylor expansion. Accuracy is approximately equal to the
degree of the polynomial, with an internal limit of about 16.
This method is not available for polynomials with complex coefficients.
.IP "\fIatn\fR: arctangent of the ratio of two polynomials" 4
.IX Item "atn: arctangent of the ratio of two polynomials"
.Vb 1
\& SYNOPSIS:
\&
\& $c = $a\->atn($b);
\&
\& DESCRIPTION:
.Ve
.Sp
This finds the arctangent of the ratio \f(CW$a\fR / \f(CW$b\fR of two polynomial,
evaluated by a Taylor expansion. Accuracy is approximately equal to the
degree of the polynomial, with an internal limit of about 16.
This method is not available for polynomials with complex coefficients.
.IP "\fIrts\fR: roots of a polynomial" 4
.IX Item "rts: roots of a polynomial"
.Vb 1
\& SYNOPSIS:
\&
\&  my $w = Math::Cephes::Polynomial\->new([\-2, 0, \-1, 0, 1]);
\&  my ($flag, $r) = $w\->rts();
\&  for (my $i=0; $i<4; $i++) {
\&    print "Root $i has real=", $r\->[$i]\->r, " and imag=", $r\->[$i]\->i, "\en";
\&  }
\&
\& DESCRIPTION:
.Ve
.Sp
This finds the roots of a polynomial. \fI\f(CI$flag\fI\fR, if non-zero, indicates
a failure of some kind. \fI\f(CI$roots\fI\fR in an array reference of
\&\fIMath::Cephes::Complex\fR objects holding the
real and complex values of the roots found.
This method is not available for polynomials with complex coefficients.
.Sp
.Vb 1
\& ACCURACY:
.Ve
.Sp
Termination depends on evaluation of the polynomial at
the trial values of the roots.  The values of multiple roots
or of roots that are nearly equal may have poor relative
accuracy after the first root in the neighborhood has been
found.
.SH "BUGS"
.IX Header "BUGS"
Please report any to Randy Kobes <randy@theoryx5.uwinnipeg.ca>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
The C code for the Cephes Math Library is
Copyright 1984, 1987, 1989, 2002 by Stephen L. Moshier,
and is available at http://www.netlib.org/cephes/.
Direct inquiries to 30 Frost Street, Cambridge, \s-1MA 02140.\s0
.PP
The perl interface is copyright 2000, 2002 by Randy Kobes.
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.