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 exitIf 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:
- The preamble, containing the information on the characteristics and structure of the polynomial
- 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 preamble
The preamble 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 preamble 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:
- Complex: This option is used to specify that the polynomial has complex coefficients, that will be listed giving the real and complex part, separately.
- Real: The polynomial has real coefficients, so that no imaginary part of the coefficients will be specified.
- Degree: This option needs a value, and is used to set the degree of the polynomial. An example is Degree=5.
- Integer: The coefficients are integer numbers.
- Rational: The coefficients are rational and will be specified in the form a/b or simply a.
- FloatingPoint: The polynomials are floating point numbers, and so will be listed in the standard notation 1.234e5. Integer input is also accepted.
- 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.
- 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$.
- Precision: Set the bits of precision of the input coefficients.
- Dense: The input polynomial has a dense coefficient list.
- 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:
- 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).
- 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