Difference between revisions of "ApCoCoA-1:MatlabCoCoAPoly"

From ApCoCoAWiki
m (Category added)
(Additional functions added)
 
(4 intermediate revisions by 2 users not shown)
Line 41: Line 41:
 
*A string can be passed as a single argument. For example: CoCoAPoly('x^2+2y'). The string must hold the following conventions:
 
*A string can be passed as a single argument. For example: CoCoAPoly('x^2+2y'). The string must hold the following conventions:
 
** Indeterminates: a-z
 
** Indeterminates: a-z
** + or - seperates two terms without blanks
+
** + or - seperates two terms
** Coefficients are placed left to the indeterminate without blanks and without a '*' character.
+
** Coefficients are placed left to the indeterminate and without a '*' character. Decimal delimiter is '.'. If coefficient=1 it is not needed to be typed.
** Note: The ring is build upon the found indeterminates over Q with a DegRevLex ordering.
+
** The ring is build upon the found indeterminates over Q with a DegRevLex ordering. If only a constant is given the constant polynomial over Q[x] is returned. To define a poly over an indeterminate which is not part of the current polynomial use coefficient = 0.
  
  
Line 49: Line 49:
  
 
=Attributes=
 
=Attributes=
* ring: A CoCoARing
+
<table border="1">
* terms: a polynomial representing matrix as described above.
+
      <tr>
 +
        <td>ring </td><td> A CoCoARing</td>
 +
      </tr>
 +
      <tr>
 +
        <td>terms </td><td> a polynomial representing matrix as described above.</td>
 +
      </tr>
 +
    </table>
  
 
=Methods=
 
=Methods=
* display: Is used by Matlab to print a CoCoAPoly to the command window. E.g. when a command is not terminated by a ';'.
+
<table border="1">
* end: returns the last coloumn or row of CoCoAPoly array
+
      <tr>
* eq: Compares two polynomials. Returns 1 if all attributes are equal. Of polynomials are not equal 0 is returned. This function is called when using the '==' operator.
+
        <td><b>Method</b></td><td><b>Operator</b></td><td><b>Description</b></td>
* get: get: Returns the attributes of a polynomial. Syntax: get(polyVar, 'Keyword'), where polyVar is a CoCoAPoly and 'Keyword' is one of the keywords listed in table 1. Additionaly the keyword 'String' can be used. This will return the polynomial as a string.  
+
      </tr>
* gt: ToDo: Implement based on ring ordering. Using LPP
+
      <tr>
* minus: Subtract one polynomial from another. This function is called when using the '-' operator.
+
        <td> display</td><td>&nbsp;</td><td> Is used by Matlab to print a CoCoAPoly to the command window.  
* mpower: Returns the i-th power of a polynomial. This function is called when using the '^' operator.
+
            E.g. when a command is not terminated by a ';'.</td>
* mtimes: Multiplies two polynomials. This function is called when using the '*' operator.
+
      </tr>
* ne: returns NOT eq. This function is called when using the '~=' operator.
+
      <tr>
* plus: Adds two polynomials. This function is called when using the '+' operator.
+
        <td> end</td><td>&nbsp;</td><td> returns the last coloumn or row of CoCoAPoly array</td>
* subsasgn: Writes a polynomial to the (i,j) coordinate of a CoCoAPoly array. This function is called when using the '()' operator.
+
      </tr>
* subsref: Returns the (i,j) element of a CoCoAPoly array, {i,j} returns the element as a string. This function is called when using the '()' operator.
+
      <tr>
* times: Multiplies arrays of polynomials elementwise. If both arrays have the same dimension than each element of poly1 is multiplied with the corresponding element in poly2. If one of the poly's is a single value, this value is multiplied to each element in the other poly. If both poly's are single values they are simply multiplied. This function is called when using the '*' operator on an array of CoCoAPoly.
+
        <td> eq</td><td>==</td><td> Compares two polynomials. Returns 1 if all attributes are equal.  
* uminus: support for leading minus symbol. This function is called when using the '-' operator.
+
            Of polynomials are not equal 0 is returned.</td>
* uplus: support for leading plus symbol. This function is called when using the '+' operator.
+
      </tr>
 +
      <tr>
 +
        <td> ge</td><td>>=</td><td> Compares two polynomials accordingto the given term ordering. Returns 1 if
 +
            first polynomial is greater equal the second polynomial.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> get</td><td>&nbsp;</td><td>Returns the attributes of a polynomial. Syntax: get(polyVar, 'Keyword'), where polyVar is a CoCoAPoly and 'Keyword' is one of the keywords listed in table 1. Additionaly the keyword 'String' can be used. This will return the polynomial as a string. The keyword 'Latex' will return a string using Latex syntax.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> gt</td><td>></td><td> Compares two polynomials accordingto the given term ordering. Returns 1 if
 +
            first polynomial is greater than the second polynomial.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> le</td><td><=</td><td> Compares two polynomials accordingto the given term ordering. Returns 1 if
 +
            first polynomial is less equal the second polynomial.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> lt</td><td><</td><td> Compares two polynomials accordingto the given term ordering. Returns 1 if
 +
            first polynomial is less than the second polynomial.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> minus</td><td>-</td><td> Subtract one polynomial from another.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> mpower</td><td>^</td><td> Returns the i-th power of a polynomial.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> mtimes</td><td>*</td><td> Multiplies two polynomials.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> ne</td><td>~=</td><td> returns NOT eq.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> plus</td><td>+</td><td> Adds two polynomials.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> subsasgn</td><td>()</td><td> Writes a polynomial to the (i,j) coordinate of a CoCoAPoly array.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> subsref</td><td>()</td><td> Returns the (i,j) element of a CoCoAPoly array, {i,j} returns  
 +
            the element as a string.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> times</td><td>.*</td><td> Multiplies arrays of polynomials elementwise. If both arrays have the same dimension than each element of poly1 is multiplied with the corresponding element in poly2. If one of the poly's is a single value, this value is multiplied to each element in the other poly. If both poly's are single values they are simply multiplied.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> uminus</td><td>-</td><td> support for leading minus symbol.</td>
 +
      </tr>
 +
      <tr>
 +
        <td> uplus</td><td>+</td><td> support for leading plus symbol.</td>
 +
      </tr>
 +
    </table>
 +
 
 +
=Additional methods=
 +
All coefficients are stored in Matlab as of typ double. Thus the conversion in the
 +
Interface between Matlab and the lib's rounding error's are introduced.
 +
This is in particular relevant when comparing polynomials. To overcome rounding issues
 +
the CoCoAPoly class provides six approximate compare functions.<br><br>
 +
 +
<table border="1">
 +
      <tr>
 +
        <td><b>Method</b></td><td><b>Description</b></td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxeq</td><td>Approximative equal. Each term is compared.</td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxge</td><td>Approximative greater equal. For the greater part only leading terms are compared, for equal all terms are compared.</td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxgt</td><td>Approximative greater. Only leading terms are compared.</td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxle</td><td>Approximative less equal. For the greater part only leading terms are compared, for equal all terms are compared.</td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxlt</td><td>Approximative less. Only leading terms are compared.</td>
 +
      </tr>
 +
  <tr>
 +
        <td>approxne</td><td>Approximative not equal. Each term is compared.</td>
 +
      </tr>
 +
</table>
 +
<br>
 +
The coefficients are compared within a range of precision: |coeff1 - coeff2| < precLevel => coeff1 = coeff2<br>
 +
Default precLevel = 10^-15 [Min. diff. between two doubles is: 2.22044604925031e-16]<br>
 +
The precision level is offered as a third optional argument.
  
 
=Examples=
 
=Examples=
Line 98: Line 189:
 
pArray = [p1,p2 ; p2,p1];
 
pArray = [p1,p2 ; p2,p1];
 
pElement = pArray(1,2);
 
pElement = pArray(1,2);
 +
</matlab>
 +
 +
* Passing a string to create a CoCoAPoly
 +
<matlab>
 +
poly = CoCoAPoly('45.4x^2x-x^1y^2+0z+5');
 
</matlab>
 
</matlab>
  
 
[[Category:MatlabToolbox]]
 
[[Category:MatlabToolbox]]

Latest revision as of 14:43, 2 July 2008

Introduction

The CoCoAPoly class represents a polynomial over a given polynomial ring (See CoCoARing).

It is based on a representation of the terms by using the logarithm of the term. For example the polynomial x^2+2y+3xy+4 defined over the Ring Q[x,y] can be represented in a matrix of the following form:

coeffpower xpower y
120
201
311
400

Constructor

The constructor for a CoCoAPoly can be used in one of the three different forms:

  • CoCoAPoly('keyword1',value1,'keyword2','value2',...).

Available keywords are listed below:

KeywordDescriptionDefault
RingA CoCoARing objectQ[x[1]]
TermsA term representing matrix as described above.
Can also be the string 'One' or 'Zero'.
This will generate the constant 1 or 0 polynomial.
[0 0]

Table 1: Keywords for CoCoAPoly


  • A string can be passed as a single argument. For example: CoCoAPoly('x^2+2y'). The string must hold the following conventions:
    • Indeterminates: a-z
    • + or - seperates two terms
    • Coefficients are placed left to the indeterminate and without a '*' character. Decimal delimiter is '.'. If coefficient=1 it is not needed to be typed.
    • The ring is build upon the found indeterminates over Q with a DegRevLex ordering. If only a constant is given the constant polynomial over Q[x] is returned. To define a poly over an indeterminate which is not part of the current polynomial use coefficient = 0.


  • A real numeric value can be passed as a single argument. For example: CoCoAPoly(2). This will return a constant polynomial over Q[x[1]].

Attributes

ring A CoCoARing
terms a polynomial representing matrix as described above.

Methods

MethodOperatorDescription
display  Is used by Matlab to print a CoCoAPoly to the command window. E.g. when a command is not terminated by a ';'.
end  returns the last coloumn or row of CoCoAPoly array
eq== Compares two polynomials. Returns 1 if all attributes are equal. Of polynomials are not equal 0 is returned.
ge>= Compares two polynomials accordingto the given term ordering. Returns 1 if first polynomial is greater equal the second polynomial.
get Returns the attributes of a polynomial. Syntax: get(polyVar, 'Keyword'), where polyVar is a CoCoAPoly and 'Keyword' is one of the keywords listed in table 1. Additionaly the keyword 'String' can be used. This will return the polynomial as a string. The keyword 'Latex' will return a string using Latex syntax.
gt> Compares two polynomials accordingto the given term ordering. Returns 1 if first polynomial is greater than the second polynomial.
le<= Compares two polynomials accordingto the given term ordering. Returns 1 if first polynomial is less equal the second polynomial.
lt< Compares two polynomials accordingto the given term ordering. Returns 1 if first polynomial is less than the second polynomial.
minus- Subtract one polynomial from another.
mpower^ Returns the i-th power of a polynomial.
mtimes* Multiplies two polynomials.
ne~= returns NOT eq.
plus+ Adds two polynomials.
subsasgn() Writes a polynomial to the (i,j) coordinate of a CoCoAPoly array.
subsref() Returns the (i,j) element of a CoCoAPoly array, {i,j} returns the element as a string.
times.* Multiplies arrays of polynomials elementwise. If both arrays have the same dimension than each element of poly1 is multiplied with the corresponding element in poly2. If one of the poly's is a single value, this value is multiplied to each element in the other poly. If both poly's are single values they are simply multiplied.
uminus- support for leading minus symbol.
uplus+ support for leading plus symbol.

Additional methods

All coefficients are stored in Matlab as of typ double. Thus the conversion in the Interface between Matlab and the lib's rounding error's are introduced. This is in particular relevant when comparing polynomials. To overcome rounding issues the CoCoAPoly class provides six approximate compare functions.

MethodDescription
approxeqApproximative equal. Each term is compared.
approxgeApproximative greater equal. For the greater part only leading terms are compared, for equal all terms are compared.
approxgtApproximative greater. Only leading terms are compared.
approxleApproximative less equal. For the greater part only leading terms are compared, for equal all terms are compared.
approxltApproximative less. Only leading terms are compared.
approxneApproximative not equal. Each term is compared.


The coefficients are compared within a range of precision: |coeff1 - coeff2| < precLevel => coeff1 = coeff2
Default precLevel = 10^-15 [Min. diff. between two doubles is: 2.22044604925031e-16]
The precision level is offered as a third optional argument.

Examples

A collection of examples is provided in the file TestCoCoAPoly.m. This file defines the function TestCoCoAPoly which will run and display many examples. A few common examples are presented below.

  • Default polynomial: Constant 0 over Q[x[1]]

<matlab> pDefault = CoCoAPoly(); </matlab>

  • Create two polynomials over same ring

<matlab> r1 = CoCoARing('Typ','Q','Indets',{'x','y'},'Ordering','DegRevLex'); p1 = CoCoAPoly('Ring', r1, 'Terms', [1 1 2 ; 1 2 1 ; 1 1 1]); p2 = CoCoAPoly('Ring', r1, 'Terms', [1 1 2 ; 1 0 0 ; 1 0 1]); </matlab>

  • Add the two polynomials

<matlab> pAdded = p1+p2; </matlab>

  • To read the attributes of a CoCoARing use the following command (this examples reads all attributes):

<matlab> [a1,a2] = get(p1,'Ring','Terms'); </matlab>

  • Create an array of CoCoAPolys and access an element

<matlab> pArray = [p1,p2 ; p2,p1]; pElement = pArray(1,2); </matlab>

  • Passing a string to create a CoCoAPoly

<matlab> poly = CoCoAPoly('45.4x^2x-x^1y^2+0z+5'); </matlab>