Michael T Flanagan's Java Library: Complex Polynomials

Michael Thomas Flanagan's Java Scientific Library

ComplexPoly Class: Complex Polynomials

Last update: 14 April 2012 Main Page of Michael Thomas Flanagan's Java Scientific Library

This class defines an object that represents a complex polynomial:

The instance variables are:

a one dimensional array of length n holding the coefficients of the polynomial a[i] (Complex[] coeff).
an integer holding the degree n (int deg).
a double holding a global convergence test value used in root searching (double testConverge).

It includes the methods needed for performing arithmetic on, evaluating and finding the roots of complex polynomials.
The Complex constructor and the basic complex number methods may found in the Complex class.
See Polynomial for a real polynomial class

import directive: import flanagan.complex.ComplexPoly;

Summary table of constructors and methods
Details of constructors and methods
Java source file (Last update: 14 April 2012)
Other classes, in this library, used by this class
Main Page of Michael Thomas Flanagan's Java Scientific Library.

Related classes

Polynomial - real polynomial class.
Complex - Basic complex class.
ComplexMatrix - Complex Matrices: complex matrix operations, solution of a complex linear set of equations.
ComplexErrorProp - Error propation in complex numbers.

SUMMARY OF CONSTRUCTORS AND METHODS

Constructors	public ComplexPoly(int n)
	public ComplexPoly(Complex[] a)
	public ComplexPoly(float[] a)
	public ComplexPoly(double[] a)
	public ComplexPoly(int[] a)
	public ComplexPoly(ArrayList<Object> a)
	public ComplexPoly(Polynomial a)
	public ComplexPoly(Complex a)
	public ComplexPoly(double a)
	public ComplexPoly(Complex a, Complex b)
	public ComplexPoly(double a, double b)
	public ComplexPoly(Complex a, Complex b, Complex c)
	public ComplexPoly(double a, double b, double c)
	public ComplexPoly(Complex a, Complex b, Complex c, Complex d)
	public ComplexPoly(double a, double b, double c, double d)
Set Values	public void resetPoly(Complex[] aa)
	public void resetPoly(ArrayList<Object> aa)
	public void resetCoeff(int i, Complex aa)
		public static ComplexPoly rootsToPoly(Complex[] roots)
Get Values	public Complex[] polyNomCopy()
	public Complex[] polyNomReference()
	public Complex coeffCopy(int i)
	public Complex coeffReference(int i)
	public int getDeg()
Deep Copy	public ComplexPoly copy()	public static ComplexPoly copy(ComplexPoly aa)
Deep Copy	public Object clone()
Check if highest order coefficient is zero	public ComplexPoly reducePoly()	public static ComplexPoly reducePoly(ComplexPoly aa)
Convert Polynomial to a String	public String toString()
	public void seti()
	public void setj()
Print to the screen	public void print()
Print to the screen	public void println()
Write to a Text File	public void printToText(String title)
Write to a Text File	public void printToText()
Addition	public ComplexPoly plus(ComplexPoly b)	public static ComplexPoly plus(ComplexPoly a, ComplexPoly b)
	public ComplexPoly plus(Complex b)	public static ComplexPoly plus(ComplexPoly a, Complex b)
	public ComplexPoly plus(double b)	public static ComplexPoly plus(ComplexPoly a, double b)
	public ComplexPoly plus(int b)	public static ComplexPoly plus(ComplexPoly a, int b)
Subtraction	public ComplexPoly minus(ComplexPoly b)	public static ComplexPoly minus(ComplexPoly a, ComplexPoly b)
	public ComplexPoly minus(Complex b)	public static ComplexPoly minus(ComplexPoly a, Complex b)
	public ComplexPoly minus(double b)	public static ComplexPoly minus(ComplexPoly a, double b)
	public ComplexPoly minus(int b)	public static ComplexPoly minus(ComplexPoly a, int b)
Multiplication	public ComplexPoly times(ComplexPoly b)	public static ComplexPoly times(ComplexPoly a, ComplexPoly b)
	public ComplexPoly times(Complex b)	public static ComplexPoly times(ComplexPoly a, Complex b)
	public ComplexPoly times(double b)	public static ComplexPoly times(ComplexPoly a, double b)
nth derivative	public ComplexPoly nthDerivative(int n)
Evaluate Polynomial or a Derivative	public Complex evaluate(Complex x)
	public Complex evaluate(double x)
	public Complex nthDerivEvaluate(int n, Complex x)
	public Complex nthDerivEvaluate(int n, double x)
Equality test	public boolean equals(ComplexPoly cp)
Equality test	public boolean isEqual(ComplexPoly cp)	public static boolean isEqual(ComplexPoly cp1, ComplexPoly cp2)
Roots	public Complex[] roots()
	public Complex[] roots(boolean polish)
	public Complex[] roots(Complex estx)
	public Complex[] roots(boolean polish, Complex estx)
	public static Complex[] quadratic(Complex a, Complex b, Complex c)	public static Complex[] quadratic(double a, double b, double c)
		public static Complex[] cubic(Complex a, Complex b, Complex c, Complex d)
		public static Complex[] cubic(double a, double b, double c, double d)
	public Complex[] laguerreAll()
	public Complex[] laguerreAll(boolean polish)
	public Complex[] laguerreAll(Complex estx)
	public Complex[] laguerreAll(boolean polish, Complex estx)
		public static Complex laguerre(Complex estx, Complex[] coeff, int deg)
		public static void resetTestConverge(double newtest)
		public static double getTestConverge()
		public static ComplexPoly rootsToPoly(Complex[] roots)

CONSTRUCTORS

public ComplexPoly(int n)
public ComplexPoly(Complex[] a)
public ComplexPoly(double[] a)
public ComplexPoly(float[] a)
public ComplexPoly(int[] a)
public ComplexPoly(ArrayList<Object> a)
public ComplexPoly(Polynomial a)
public ComplexPoly(Complex a)
public ComplexPoly(double a)
public ComplexPoly(Complex a, Complex b)
public ComplexPoly(double a, double b)
public ComplexPoly(Complex a, Complex b, Complex c)
public ComplexPoly(double a, double b, double c)
public ComplexPoly(Complex a, Complex b, Complex c, Complex d)
public ComplexPoly(double a, double b, double c, double d)

Argument: int
Usage:                      ComplexPoly cc = new ComplexPoly(n);
This creates a new instance of ComplexPoly(), cc, and initialises both the real part (real) and the imaginary part (imag) of all n degree polynomial coefficients to zero

Argument: an array Complex[], double[], float[] or int[]
Usage:                      ComplexPoly cc = new ComplexPoly(aa);
This creates a new instance of ComplexPoly(), cc, and initialises the coefficients to a copy of those in the existing array of coefficients, aa, which may be Complex[], double[], float[] or int[].

Argument: ArrayList<Object>
Usage:                      ComplexPoly cc = new ComplexPoly(aa);
This creates a new instance of ComplexPoly(), cc, and initialises the coefficients to the list passed as the elements of the ArrayList argument, aa. The elements must be in the order of the coefficients of the polynomial. They may be a single type or a mixture of types. The allowed types are Complex, Double, Float, Integer, Long, Short, Byte, BigDecimal, BigInteger or Phasor.

Argument: Polynomial
Usage:                      ComplexPoly cc = new ComplexPoly(aa);
This creates a new instance of ComplexPoly(), cc, and initialises the coefficients to the real coefficients passed in the Polynomial, aa.

Argument: Complex or double
Usage:                      ComplexPoly cc = new ComplexPoly(a);
This creates a new instance of ComplexPoly(), cc, and initialises an array of one coefficients (i.e. a constant, a) to a copy of the value in a. The variable, a, may be real (double) or Complex. This constructor is needed by the class Loop.

Argument: Complex, Complex or double, double
Usage:                      ComplexPoly cc = new ComplexPoly(a, b);
This creates a new instance of ComplexPoly(), cc, and initialises an array of two coefficients (i.e. a straight line, a + b.x) to a copy of the values in a and b. The variables, a and b, may be real (double) or Complex.

Argument: Complex, Complex, Complex or double, double, double
Usage:                      ComplexPoly cc = new ComplexPoly(a, b, c);
This creates a new instance of ComplexPoly(), cc, and initialises an array of three coefficients (i.e. a quadratic, a + b.x + c.x.x) to a copy of the values in a, b and c. The variables, a, b and c, may be real (double) or Complex.

Argument: Complex, Complex, Complex, Complex or double, double, double, double
Usage:                      ComplexPoly cc = new ComplexPoly(a, b, c, d);
This creates a new instance of ComplexPoly(), cc, and initialises an array of four coefficients (i.e. a cubic, a + b.x + c.x.x + d.x.x.x) to a copy of the values in a, b, c and d. The variables, a, b, c and d, may be real (double) or Complex.

METHODS

SET VALUES
public void resetPoly(Complex[] aa)
Usage:                      bb.resetPoly(aa);
Resets the coefficients of bb to copies of those in the argument array Complex[] aa.

public void resetPoly(ArrayList<Object> aa)
Usage:                      bb.resetPoly(aa);
Resets the coefficients of bb to the list passed as the elements of the ArrayList argument, aa. The elements must be in the order of the coefficients of the polynomial. They may be a single type or a mixture of types. The allowed types are Complex, Double, Float, Integer, Long, Short, Byte, BigDecimal, BigInteger or Phasor.

public void resetCoeff(int i, Complex aa)
Usage:                      bb.resetCoeff(i, aa);
Resets the ith coefficient of bb to a copy of aa where aa is Complex.

public static ComplexPoly rootsToPoly(Complex[ ] roots)
Usage:                      aa = ComplexPoly(roots);
Returns a ComplexPoly, aa, given the roots of this polynomial, stored in the Complex array, roots.

GET VALUES
public Complex[] polyNomCopy()
Usage:                      bb = aa.polyNomCopy();
Returns a copy of the polynomial coefficients in the ComplexPoly, aa, to the coefficient array in the Complex array, bb.

public Complex[] polyNomReference()
Usage:                      bb = aa.polyNomReference();
Returns a reference (a pointer) to the polynomial coefficients in the ComplexPoly, aa, to bb.

public Complex coeffCopy(int i)
Usage:                      bb = aa.coeffCopy(i);
Returns a copy of the ith coefficient in the ComplexPoly, aa, to the Complex, bb.

public Complex coeffReference(int i)
Usage:                      bb = aa.coeffReference(i);
Returns a reference (a pointer) to the ith coefficient in the ComplexPoly, aa, to the Complex, bb.

public int getDeg()
Usage:                      i = aa.getDeg();
Returns the degree of the polynomial.

DEEP COPY
public ComplexPoly copy()
public Object clone()
public static ComplexPoly copy(ComplexPoly aa)
Usage:                      bb = aa.copy();
Usage:                      bb = ComplexPoly.copy(aa);
Returns a deep copy of the ComplexPoly, aa, to the ComplexPoly, bb.

Clone ComplexPoly
Usage:                      bb = (ComplexPoly) aa.clone();
Returns a deep copy of the ComplexPoly, aa, to the ComplexPoly, bb. This method overrides java.lang.Object.clone()

RETURN A MATCHING POLYNOMIAL IN WHICH THE HIGHEST ORDER COEFFICIENT IS NOT ZERO
public ComplexPoly reducePoly()
public static ComplexPoly reducePoly(ComplexPoly aa)
Usage: bb = aa.reducePoly();
Usage: bb = ComplexPoly.reducePoly(aa);
Returns a polynomial, ComplexPoly bb, in which the highest order coefficient has been removed if it is zero. The entered ComplexPoly, aa, is examined iteratively until the highest order coefficient is non-zero, e.g.
(3 + i2) + (-8 + i6).x would be returned as bb if aa was entered as
(3 + i2) + (-8 + i6).x + (0 + i0).x^2 + (0 + i0).x^3

CONVERT THE POLYNOMIAL TO A STRING
public String toString()
Usage:
                     ss = aa.toString();
Converts the polynomial (in aaa in the above usage) to a String (ss in the above usage) of the form (a + jb)[0] + (a + jb)[1].x + (a + jb)[2].x^2 etc.
or (a + ib)[0] + (a + ib)[1].x + (a + ib)[2].x^2 etc.
.
The representation of the square root of minus one by i or j is set by seti() or setj() [see below].

public void seti()
Usage:
                     aa.seti();
Sets the representation of the square root of minus one in Strings to i. The default option is j.

public void setj()
Usage:
                     aa.setj();
Sets the representation of the square root of minus one in Strings to j. The default option is j.

PRINT THE POLYNOMIAL TO THE SCREEN
public void print()
public void println()
Usage:
aa.print();
Writes the polynomial to the screen in the form (a + jb)[0] + (a + jb)[1].x + (a + jb)[2].x^2 etc.
or (a + ib)[0] + (a + ib)[1].x + (a + ib)[2].x^2 etc.
The representation of the square root of minus one by i or j is set by seti() or setj() [see above].

Usage:
aa.println();
Writes the polynomial to the screen, in the form (a + jb)[0] + (a + jb)[1].x + (a + jb)[2].x^2 etc.
or (a + ib)[0] + (a + ib)[1].x + (a + ib)[2].x^2 etc., followed by a line return.
The representation of the square root of minus one by i or j is set by seti() or setj() [see above].

WRITE THE POLYNOMIAL TO A TEXT FILE
public void printToText(public void)
public void printToText()
Usage:
aa.printToText(title);
Opens a text file with the name in the String in the argument, title, with .txt appended. Writes, to this file, the file name, the time and date, the degree of the polynomial in the ComplexPoly aa and the coefficients of the polynomial in aa.
Usage:
aa.printToText();
Opens a text file ComplexPolyOutput.txt. Writes, to this file, the file name, the time and date, the degree of the polynomial in the ComplexPoly aa and the coefficients of the polynomial in aa.

ADDITION OF TWO POLYNOMIALS
public ComplexPoly plus(ComplexPoly b)
public ComplexPoly plus(Complex b)
public ComplexPoly plus(double b)
public ComplexPoly plus(int b)
public static ComplexPoly plus(ComplexPoly a, ComplexPoly b)
public static ComplexPoly plus(ComplexPoly a, Complex b)
public static ComplexPoly plus(ComplexPoly a, double b)
public static ComplexPoly plus(ComplexPoly a, int b)
Usage:
                     c = a.plus(b);
                     c = ComplexPoly.plus(a,b);
Returns the polynomial, e.g. c, that is the sum of two polynomials (a and b), a polynomial (a) and a complex number (b) or a polynomial (a) and a real number (b), e.g. a + b.

SUBTRACTION OF TWO POLYNOMIALS
public ComplexPoly minus(ComplexPoly b)
public ComplexPoly minus(Complex b)
public ComplexPoly minus(double b)
public ComplexPoly minus(int b)
public static ComplexPoly minus(ComplexPoly a, ComplexPoly b)
public static ComplexPoly minus(ComplexPoly a, Complex b)
public static ComplexPoly minus(ComplexPoly a, double b)
public static ComplexPoly minus(ComplexPoly a, int b)
Usage:
                     c = a.minus(b);
                     c = ComplexPoly.minus(a,b);
Returns the polynomial, e.g. c, that is the difference between two polynomials (a and b), a polynomial (a) and a complex number (b) or a polynomial (a) and a real number (b), e.g. a - b.

MULTIPLICATION OF TWO POLYNOMIALS
public ComplexPoly times(ComplexPoly b)
public ComplexPoly times(Complex b)
public ComplexPoly times(double b)
public static ComplexPoly times(ComplexPoly a, ComplexPoly b)
public static ComplexPoly times(ComplexPoly a, Complex b)
public static ComplexPoly times(ComplexPoly a, double b)
Usage:
                     c = a.times(b);
                     c = ComplexPoly.times(a,b);
Returns the polynomial, e.g. c, that is the product of two polynomials (a and b), a polynomial (a) and a complex number (b) or a polynomial (a) and a real number (b), e.g. a*b.

OBTAIN THE nTH DERIVATIVE COEFFICIENTS
public ComplexPoly nthDerivative(int n)
Usage: yy = aa.nthDerivative(n);
Returns, as a new ComplexPoly (yy in the above example), the coefficients and degree of the nth derivative of the polynomial, represented in the above example by aa. The value of n is passed as an integer argument.

EVALUATE A POLYNOMIAL AND ITS DERIVATIVES
Evaluate a polynomial
public Complex evaluate(Complex x)
public Complex evaluate(double x)
Usage: y = aa.evaluate(x);
Evaluates the polynomial, represented by aa, at a value of x. The variable x may be complex or real (double).

Evaluate the nth derivative of a polynomial
public Complex nthDerivEvaluate(int n, Complex x)
public Complex nthDerivEvaluate(int n, double x)
Usage: y = aa.nthDerivEvaluate(n, x);
Evaluates the nth derivative of the polynomial, represented by aa, at a value of x. The variable x may be complex or real (double).

CHECK WHETHER TWO POLYNOLMIALS ARE EQUAL
public boolean equals(ComplexPoly cp)
public boolean isEqual(ComplexPoly cp)
public static boolean isEqual(ComplexPoly cp1, ComplexPoly cp2)
Usage:                      test = cp1.equals(cp2);
Usage:                      test = cp1.isEqual(cp2);
Usage:                      test = ComplexPoly.isEqual(cp1, cp2);
Returns true if all the instance variables of the ComlexPoly, cp1, are identical to those of the ComplexPoly, cp2. Returns false if they are not.

ROOT OF A POLYNOMIAL
For general details of root searching and a discussion of the rounding errors in root searching see Numerical Recipes, The Art of Scientific Computing by W H Press, S A Teukolsky, W T Vetterling & B P Flannery, Cambridge University Press (http://www.nr.com/).

All roots are returned as Complex though they may, in some cases, all be real. See isReal and isRealPerCent methods in the Complex class for checking whether an array of complex are all real and see the ArrayMaths class for methods for converting Complex[] to a real array, e.g. double[]

GENERAL
public Complex[] roots()
public Complex[] roots(boolean polish)
public Complex[] roots(Complex estx)
public Complex[] roots(boolean polish, Complex estx)

Usage:                      x = aa.roots();
Usage:                      x = aa.roots(polish);
Usage:                      x = aa.roots(estx);
Usage:                      x = aa.roots(polish, estx);

Returns the roots of the polynomial, represented by aa, into the Complex array, x.

Polynomial degree>3: The method roots(..) uses the Laguerre procedure as described in the methods laguerre() and laguerreAll()
The boolean variable polish invokes root polishing, as described under Laguerre, if true. If polish is not included in the argument list its default value is true. [see below under LAGUERRE for a detailed discussion of polish].
The Complex variable estx is the initial estimate of the roots needed by the method laguerre(...). If estx is not included in the argument list its default value is zero. The default value of zero is the preferred value of estx. [see below under LAGUERRE for a detailed discussion of estx].
Though the Laguerre procedure is a robust method it is not possible to guarantee the return of the exact roots for polynomials of degree>3, where laguerre(..) is used. If possible the results should be inspected as to their reasonableness in the light of the physical model that the polynomial represents.
If the number of iterations allowed in laguerre() is exceeded a message to this effect will be printed to screen and the current estimate of the root returned. This may be a good estimate of the exact value as it is difficult to set the convergence criteria to automatically cover all polynomials. Try reseting the convergence parameter testConverge to a value larger than the default value of 1e-7 and compare the results [see LAGUERRE - CONVERGENCE below]. See Press et al. for details of the Laguerre procedure.
Polynomial degree=3: The method roots(..) uses the solution of a cubic as described in the method cubic(a,b,c,d) [see below]
polish and estx are NOT required.
Polynomial degree=2: The method roots(..) uses the solution of a quadratic as described in the method quadratic(a,b,c) [see below]
polish and estx are NOT required.
Polynomial degree=1: The method roots(..) returns -a[0]/a[1]. polish and estx are NOT required.
Polynomial degree=0: The method roots(..) throws an IllegalArgumentException.

QUADRATIC
public static Complex[] quadratic(Complex a, Complex b, Complex c)
public static Complex[] quadratic( double a, double b, double c)
Usage:                      xx = ComplexPoly.quadratic(a, b, c);
Returns the roots of the quadratic
                     a + b.x + c.x²
into the Complex array, xx. NB the order of the coefficients a, b and c.
Uses the procedures needed to avoid rounding errors as described by Press et al.
The coeffients a, b and c may be Complex or real (double).

CUBIC
public static Complex[] cubic(Complex a, Complex b, Complex c, Complex d)
public static Complex[] cubic(double a, double b, double c, double d)
Usage:                      xx = ComplexPoly.cubic(a, b, c, d);
Returns the roots of the cubic
                     a + b.x + c.x² + d.x³
into the Complex array, xx. NB the order of the coefficients a, b, c and d.
Uses the procedures needed to avoid rounding errors as described by Press et al.
The coeffients a, b, c and d may be Complex or real (double).

LAGUERRE - ALL ROOTS
public Complex[] laguerreAll()
public Complex[] laguerreAll(boolean polish)
public Complex[] laguerreAll(Complex estx)
public Complex[] laguerreAll(boolean polish, Complex estx)

Returns all the roots of the polynomial, represented by aa, into the Complex array, x. It uses the Laguerre procedure. It repetitively invokes the method laguerre() [see below], which finds a single root, deflating the polynomial by synthetic division after finding each root. If the boolean argument, polish, is true it then polishes the roots, using laguerre() and the undeflated coefficients. If polish is false the roots are returned without polishing to be polished elsewhere at the users choice. The complex variable, estx, is the initial estimate of each root. Zero is the preferred default option for estx but if laguerre fails changing estx may help. The method laguerreAll(..) returns the roots sorted by their real parts.

Usage:                      x = aa.laguerreAll();
Default values: polish is true; initial estimates are all zero

Usage:                      x = aa.laguerreAll(polish);
polish is boolean.
Default values: initial estimates of the roots are all zero

Usage:                      x = aa.laguerreAll(estx);
The initial estimate of the roots, estx, is Complex.
Default values: polish is true

Usage:                      x = aa.laguerreAll(polish, estx);
polish is boolean and the initial estimate of the roots, estx, is Complex.

Though this is a robust method it is not possible to guarantee the return of the exact roots. If possible the results should be inspected as to their reasonableness in the light of the physical model that the polynomial represents. If the number of iterations allowed in laguerre() is exceeded a message to this effect will be printed to screen and the current estimate of the root returned. This may be a good estimate of the exact value as it is difficult to set the convergence criteria to automatically cover all polynomials. Try reseting the convergence parameter testConverge to a value larger than the default value of 1e-7 and compare the results [see LAGUERRE - CONVERGENCE below].
See Press et al. for details.

LAGUERRE - A SINGLE ROOT
public static Complex laguerre(Complex estx, Complex[] coeff, int deg)
Usage:                      x = Complex.laguerre(xx, aa, deg);
Returns a single root of the polynomial, of degree, deg, whose coefficients are stored in the complex array aa, given an initial estimate of the root, xx. It uses the Laguerre procedure.
Though this is a robust method it is not possible to guarantee the return of the exact root. If possible the result should be inspected as to its reasonableness in the light of the physical model that the polynomial represents. If the number of iterations allowed in laguerre() is exceeded a message to this effect will be printed to screen and the current estimate of the root returned. This may be a good estimate of the exact value as it is difficult to set the convergence criteria to automatically cover all polynomials. Try reseting the convergence parameter testConverge to a value larger than the default value of 1e-7 and compare the results [see LAGUERRE - CONVERGENCE below].
The method laguerreAll() [see above] calls this method repetitively to obtain all the roots deflating the polynomial, after finding each root, by synthetic division.
See the method laguerre() above and Press et al. for details.

LAGUERRE - TEST FOR CONVERGENCE
The variable testConverge is a private static double member of the class ComplexPoly that is an estimate of the round-off error used in testing for convergence by laguerre(..) and laguerreAll(..). Its default value is 1.0e-7.

Reset testConverge
testConverge may be reset to the users desired value using the following method:
public static void resetTestConverge(double newtest)
Usage:                      ComplexPoly.resetTestConverge(newvalue);

Get testConverge
public static double getTestConverge()
Usage:                      value = ComplexPoly.getTestConverge();
Returns the current value of testConverge.

CREATE A ComplexPoly GIVEN THE POLYNOMIAL'S ROOTS
public static ComplexPoly rootsToPoly(Complex[ ] roots)
Usage:                      aa = ComplexPoly(roots);
Returns a ComplexPoly, aa, given the roots of this polynomial, stored in the Complex array, roots.

OTHER CLASSES USED BY THIS CLASS

This class uses the following classes in this library:

This page was prepared by Dr Michael Thomas Flanagan