Documentation

Running MPSolve

MPSolve works by reading a .pol file where the polynomial is defined. The kind of algorithm to be used on the output options can be configured using command-line options, which are documented in the help text obtained by running mpsolve -h:

mpsolve [-a alg] [-b] -c [-G goal] [-o digits] [-i digits] [-j n] [-t type] [-S set] 
  [-D detect] [-O format] [-l] [-r] [filename | -p poly] [-x] [-d] [-v] [infile]

Options:
 -a alg      Select the algorithm used to solve the polynomial/secular equation:
              u: Classic unisolve algorithm (Aberth iterations and dynamic precision)
              s: Secular algorithm, using regeneration of increasingly better-conditioned
                 secular equations with the same roots of the polynomial
 -b          Perform Aberth iterations in Jacobi-style instead of Gauss-Seidel
 -c          Enable crude approximation mode. Fast but not always effective
 -G goal     Select the goal to reach. Possible values are:
              a: Approximate the roots
              i: Isolate the roots
              c: Count the roots in the search set
 -o digits   Number of guaranteed digits of the roots
 -i digits   Digits of precision of the input coefficients
 -j n        Number of threads to spawn as workers
 -t type     Type can be 'f' for floating point or 'd' for DPE
 -S set      Restrict the search set for the roots 
             set can be one of:
               u: upper half-plane { x | Im(x) > 0 } 
               d: lower half-plane { x | Im(x) < 0 } 
               l: left half-plane { x | Re(x) < 0 } 
               r: right half-plane { x | Re(x) > 0 } 
               i: inside the unit circle: { x | |x| < 1 } 
               o: outside the unit circle { x | |x| > 1 } 
               R: real axis { x | Im(x) = 0 } 
               I: imaginary axis { x | Re(x) = 0 }
 -D detect   Detect properties of the roots:
               r: real roots
               i: imaginary roots
               b: both
 -O format   Select format for output:
               f: full output
               b: bare output
               c: compact output
               v: verbose output
               g: gnuplot-ready output
               gf: gnuplot-full mode, can be piped to gnuplot and display error bars. 
                   For example:
                     mpsolve -as -Ogf myfile.pol | gnuplot 
               gp: The same as gf but only with points (suitable for high degree polynomials)
 -l filename Set filename as the output for the log, instead of the tty. Use this option with
             -d[domains] to activate the desired debug domains. 
 -x          Enable graphic visualization of convergence
 -d[domains] Activate debug on selected domains, that can be one of:
               t: trace
               a: approximation
               c: cluster
               i: improvement
               w: timings
               o: input/Output
               m: memory management
               f: function calls
               p: debug stop condition and development of iteration packets
               r: regeneration
               Example: -dfi for function calls and improvement
 -p poly     Solve the polynomial specified on the command line. 
               Example: mpsolve -p "x^4-6x^9+6/7x + 5" 
 -r          Use a recursive strategy to dispose the initial approximations.
             This option is available only for monomial polynomials. 
             Note: this option is considered experimental.
 -s file     Read the starting approximations from the given file, instead
             of relying on the internal algorithm of MPSolve.
 -v          Print the version and exit

If you installed MPSolve using the Ubuntu packages you can also read the man page by running man mpsolve.

Polynomials files

The Polynomial files, usually saved with the extension .pol, can be used to describe a polynomial input for MPSolve (or a secular equation). Secular equations are equations of the form $$ \sum_{i = 1}^n \frac{a_i}{x - b_i} - 1 = 0 $$

They are composed of two different parts: 1. The preface, containing the information on the characteristics and structure of the polynomial 2. The coefficient list, that explicitly lists the coefficients of the polynomial (or of the secular equation).

These parts are separated by an empty line. You may find xmpsolve useful to author .pol files, since it provides basic syntax highlighting for this format.

The preface

The preface is composed by single line statements that end with the symbol ;. They can be simple statements or assignments. Some examples are:

Monomial; 
Degree=5;
Integer;

In this case the preface is saying that we are inserting a polynomial, represented in the monomial basis, of degree 5 that has integer coefficients.

All the possible options are listed below:

  1. Complex: This option is used to specify that the polynomial has complex coefficients, that will be listed giving the real and complex part, separately.
  2. Real: The polynomial has real coefficients, so that no imaginary part of the coefficients will be specified.
  3. Degree: This option needs a value, and is used to set the degree of the polynomial. An example is Degree=5.
  4. Integer: The coefficients are integer numbers.
  5. Rational: The coefficients are rational and will be specified in the form a/b or simply a.
  6. FloatingPoint: The polynomials are floating point numbers, and so will be listed in the standard notation 1.234e5. Integer input is also accepted.
  7. Monomial: The input is given in the monomial basis, and so n + 1 coefficients will be inserted (2n + 2 if the polynomial is complex) where n is the degree of the polynomial. The coefficients must be listed in increasing degree order.
  8. Secular: The input is given as a secular equation. The coefficients a,,i,, and b,,i,, need to be specified and need to be listed in pairs a,,i,, b,,i,,.
  9. Precision: Set the bits of precision of the input coefficients.
  10. Dense: The input polynomial has a dense coefficient list.
  11. Sparse: The input polynomial has a sparse coefficient list; in this case each coefficient must be inserted with its degree as a pair degree, coefficient.

The coefficient list

The second part of the input file is composed by a list of the coefficients of the selected polynomial or secular equation. The coefficients that shall be listed depends on the options that have been previously selected in the preface.

More precisely:

  1. If the option Dense has been set, the coefficient list should report the coefficients in blocks starting from the lowest degree to the higher (where this makes sense, i.e., for polynomials; for secular equations the coefficient order does not matter).
  2. If the option Sparse has been set, the coefficients should be listed in pairs (degree, coefficient block), and only zero coefficients can be omitted.

The coefficient block

A single coefficient block is generally composed by the real part and imaginary part of the coefficient, unless the options Real has been specified. In this case the imaginary part must be omitted. For secular equations a coefficient block contains the a,,i,, coefficient followed by the b,,i,, coefficient (each one with its imaginary part unless the Real options has been specified).

Some examples follow to further clarify the syntax.

Some examples

Here is the code for the polynomial x^3^ - 1, in its Dense and Sparse version, respectively.

! Dense version of the polynomial x^3 - 1
Dense;
Monomial;
Degree=3;
Real;
Integer;

-1 0 0 1
! Sparse version of the polynomial x^3 - 1. This is handier to write but also
! more efficient since sparsity is exploited in the algorithm. 
Sparse;
Monomial;
Real;
Integer;

3 1
0 -1

Here is an example of a polynomial that has complex coefficients.

! Input file for the polynomial x^2 - 2ix + 1. 
Monomial;
Integer;
Complex;
Degree = 2;

1 0
0 −2
1 0

Here is another example of a polynomial that has complex rational coefficients.

! Input file for the polynomial x^2 - (2/3)ix + 1/7 + (4/3)i. 
Monomial;
Rational;
Complex;
Degree = 2;

1/7 4/3
0 −2/3
1 0

And finally an example of a secular equation:

! Input file for the secular equation 1/(x + 2) - 4/(x + 5) - 1 = 0
Secular;
Integer;
Real;
Degree = 2;

1 −2
−4 −5

Assume that we have a polynomial whose coefficients are know only as standard IEEE binary64 floating point numbers, therefore we can trust only 53 bits of them. Then we can use the following syntax

Monomial; 
Degree=5;
FloatingPoint;
Precision=53;
Real;

-8.73034291342546e-01
-3.83927162594602e-01
 2.92460236740457e-01
-1.32393807521688e-01
 4.43052170254926e-01
-1.02507687627188e+00