cln_mirror/doc/cln_9.html

<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from cln.texi on 14 January 2000 -->

<TITLE>CLN, a Class Library for Numbers - 9. Univariate polynomials</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_8.html">previous</A>, <A HREF="cln_10.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC54" HREF="cln_toc.html#TOC54">9. Univariate polynomials</A></H1>


<H2><A NAME="SEC55" HREF="cln_toc.html#TOC55">9.1 Univariate polynomial rings</A></H2>

<P>
CLN implements univariate polynomials (polynomials in one variable) over an
arbitrary ring. The indeterminate variable may be either unnamed (and will be
printed according to <CODE>cl_default_print_flags.univpoly_varname</CODE>, which
defaults to <SAMP>`x'</SAMP>) or carry a given name. The base ring and the
indeterminate are explicitly part of every polynomial. CLN doesn't allow you to
(accidentally) mix elements of different polynomial rings, e.g.
<CODE>(a^2+1) * (b^3-1)</CODE> will result in a runtime error. (Ideally this should
return a multivariate polynomial, but they are not yet implemented in CLN.)


<P>
The classes of univariate polynomial rings are


<PRE>
                           Ring
                         cl_ring
                        &#60;cl_ring.h&#62;
                            |
                            |
                 Univariate polynomial ring
                      cl_univpoly_ring
                      &#60;cl_univpoly.h&#62;
                            |
           +----------------+-------------------+
           |                |                   |
 Complex polynomial ring    |    Modular integer polynomial ring
 cl_univpoly_complex_ring   |        cl_univpoly_modint_ring
  &#60;cl_univpoly_complex.h&#62;   |        &#60;cl_univpoly_modint.h&#62;
                            |
           +----------------+
           |                |
   Real polynomial ring     |
   cl_univpoly_real_ring    |
    &#60;cl_univpoly_real.h&#62;    |
                            |
           +----------------+
           |                |
 Rational polynomial ring   |
 cl_univpoly_rational_ring  |
  &#60;cl_univpoly_rational.h&#62;  |
                            |
           +----------------+
           |
 Integer polynomial ring
 cl_univpoly_integer_ring
  &#60;cl_univpoly_integer.h&#62;
</PRE>

<P>
and the corresponding classes of univariate polynomials are


<PRE>
                   Univariate polynomial
                          cl_UP
                      &#60;cl_univpoly.h&#62;
                            |
           +----------------+-------------------+
           |                |                   |
   Complex polynomial       |      Modular integer polynomial
        cl_UP_N             |                cl_UP_MI
  &#60;cl_univpoly_complex.h&#62;   |        &#60;cl_univpoly_modint.h&#62;
                            |
           +----------------+
           |                |
     Real polynomial        |
        cl_UP_R             |
    &#60;cl_univpoly_real.h&#62;    |
                            |
           +----------------+
           |                |
   Rational polynomial      |
        cl_UP_RA            |
  &#60;cl_univpoly_rational.h&#62;  |
                            |
           +----------------+
           |
   Integer polynomial
        cl_UP_I
  &#60;cl_univpoly_integer.h&#62;
</PRE>

<P>
Univariate polynomial rings are constructed using the functions


<DL COMPACT>

<DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
This function returns the polynomial ring <SAMP>`R[X]'</SAMP>, unnamed or named.
<CODE>R</CODE> may be an arbitrary ring. This function takes care of finding out
about special cases of <CODE>R</CODE>, such as the rings of complex numbers,
real numbers, rational numbers, integers, or modular integer rings.
There is a cache table of rings, indexed by <CODE>R</CODE> and <CODE>varname</CODE>.
This ensures that two calls of this function with the same arguments will
return the same polynomial ring.

<DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
<DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
<DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
<DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
<DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R)</CODE>
<DD>
<DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R, const cl_symbol&#38; varname)</CODE>
<DD>
These functions are equivalent to the general <CODE>cl_find_univpoly_ring</CODE>,
only the return type is more specific, according to the base ring's type.
</DL>


<H2><A NAME="SEC56" HREF="cln_toc.html#TOC56">9.2 Functions on univariate polynomials</A></H2>

<P>
Given a univariate polynomial ring <CODE>R</CODE>, the following members can be used.


<DL COMPACT>

<DT><CODE>cl_ring R-&#62;basering()</CODE>
<DD>
This returns the base ring, as passed to <SAMP>`cl_find_univpoly_ring'</SAMP>.

<DT><CODE>cl_UP R-&#62;zero()</CODE>
<DD>
This returns <CODE>0 in R</CODE>, a polynomial of degree -1.

<DT><CODE>cl_UP R-&#62;one()</CODE>
<DD>
This returns <CODE>1 in R</CODE>, a polynomial of degree &#60;= 0.

<DT><CODE>cl_UP R-&#62;canonhom (const cl_I&#38; x)</CODE>
<DD>
This returns <CODE>x in R</CODE>, a polynomial of degree &#60;= 0.

<DT><CODE>cl_UP R-&#62;monomial (const cl_ring_element&#38; x, uintL e)</CODE>
<DD>
This returns a sparse polynomial: <CODE>x * X^e</CODE>, where <CODE>X</CODE> is the
indeterminate.

<DT><CODE>cl_UP R-&#62;create (sintL degree)</CODE>
<DD>
Creates a new polynomial with a given degree. The zero polynomial has degree
<CODE>-1</CODE>. After creating the polynomial, you should put in the coefficients,
using the <CODE>set_coeff</CODE> member function, and then call the <CODE>finalize</CODE>
member function.
</DL>

<P>
The following are the only destructive operations on univariate polynomials.


<DL COMPACT>

<DT><CODE>void set_coeff (cl_UP&#38; x, uintL index, const cl_ring_element&#38; y)</CODE>
<DD>
This changes the coefficient of <CODE>X^index</CODE> in <CODE>x</CODE> to be <CODE>y</CODE>.
After changing a polynomial and before applying any "normal" operation on it,
you should call its <CODE>finalize</CODE> member function.

<DT><CODE>void finalize (cl_UP&#38; x)</CODE>
<DD>
This function marks the endpoint of destructive modifications of a polynomial.
It normalizes the internal representation so that subsequent computations have
less overhead. Doing normal computations on unnormalized polynomials may
produce wrong results or crash the program.
</DL>

<P>
The following operations are defined on univariate polynomials.


<DL COMPACT>

<DT><CODE>cl_univpoly_ring x.ring ()</CODE>
<DD>
Returns the ring to which the univariate polynomial <CODE>x</CODE> belongs.

<DT><CODE>cl_UP operator+ (const cl_UP&#38;, const cl_UP&#38;)</CODE>
<DD>
Returns the sum of two univariate polynomials.

<DT><CODE>cl_UP operator- (const cl_UP&#38;, const cl_UP&#38;)</CODE>
<DD>
Returns the difference of two univariate polynomials.

<DT><CODE>cl_UP operator- (const cl_UP&#38;)</CODE>
<DD>
Returns the negative of a univariate polynomial.

<DT><CODE>cl_UP operator* (const cl_UP&#38;, const cl_UP&#38;)</CODE>
<DD>
Returns the product of two univariate polynomials. One of the arguments may
also be a plain integer or an element of the base ring.

<DT><CODE>cl_UP square (const cl_UP&#38;)</CODE>
<DD>
Returns the square of a univariate polynomial.

<DT><CODE>cl_UP expt_pos (const cl_UP&#38; x, const cl_I&#38; y)</CODE>
<DD>
<CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.

<DT><CODE>bool operator== (const cl_UP&#38;, const cl_UP&#38;)</CODE>
<DD>
<DT><CODE>bool operator!= (const cl_UP&#38;, const cl_UP&#38;)</CODE>
<DD>
Compares two univariate polynomials, belonging to the same univariate
polynomial ring, for equality.

<DT><CODE>cl_boolean zerop (const cl_UP&#38; x)</CODE>
<DD>
Returns true if <CODE>x</CODE> is <CODE>0 in R</CODE>.

<DT><CODE>sintL degree (const cl_UP&#38; x)</CODE>
<DD>
Returns the degree of the polynomial. The zero polynomial has degree <CODE>-1</CODE>.

<DT><CODE>cl_ring_element coeff (const cl_UP&#38; x, uintL index)</CODE>
<DD>
Returns the coefficient of <CODE>X^index</CODE> in the polynomial <CODE>x</CODE>.

<DT><CODE>cl_ring_element x (const cl_ring_element&#38; y)</CODE>
<DD>
Evaluation: If <CODE>x</CODE> is a polynomial and <CODE>y</CODE> belongs to the base ring,
then <SAMP>`x(y)'</SAMP> returns the value of the substitution of <CODE>y</CODE> into
<CODE>x</CODE>.

<DT><CODE>cl_UP deriv (const cl_UP&#38; x)</CODE>
<DD>
Returns the derivative of the polynomial <CODE>x</CODE> with respect to the
indeterminate <CODE>X</CODE>.
</DL>

<P>
The following output functions are defined (see also the chapter on
input/output).


<DL COMPACT>

<DT><CODE>void fprint (cl_ostream stream, const cl_UP&#38; x)</CODE>
<DD>
<DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_UP&#38; x)</CODE>
<DD>
Prints the univariate polynomial <CODE>x</CODE> on the <CODE>stream</CODE>. The output may
depend on the global printer settings in the variable
<CODE>cl_default_print_flags</CODE>.
</DL>


<H2><A NAME="SEC57" HREF="cln_toc.html#TOC57">9.3 Special polynomials</A></H2>

<P>
The following functions return special polynomials.


<DL COMPACT>

<DT><CODE>cl_UP_I cl_tschebychev (sintL n)</CODE>
<DD>
Returns the n-th Tchebychev polynomial (n &#62;= 0).

<DT><CODE>cl_UP_I cl_hermite (sintL n)</CODE>
<DD>
Returns the n-th Hermite polynomial (n &#62;= 0).

<DT><CODE>cl_UP_RA cl_legendre (sintL n)</CODE>
<DD>
Returns the n-th Legendre polynomial (n &#62;= 0).

<DT><CODE>cl_UP_I cl_laguerre (sintL n)</CODE>
<DD>
Returns the n-th Laguerre polynomial (n &#62;= 0).
</DL>

<P>
Information how to derive the differential equation satisfied by each
of these polynomials from their definition can be found in the
<CODE>doc/polynomial/</CODE> directory.


<P><HR><P>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_8.html">previous</A>, <A HREF="cln_10.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
</BODY>
</HTML>