001/*
002 * $Id: RealRoots.java 5566 2016-08-03 17:03:24Z kredel $
003 */
004
005package edu.jas.root;
006
007
008import java.io.Serializable;
009import java.util.List;
010
011import edu.jas.arith.BigRational;
012import edu.jas.arith.Rational;
013import edu.jas.poly.GenPolynomial;
014import edu.jas.structure.RingElem;
015
016
017/**
018 * Real roots interface.
019 * @param <C> coefficient type.
020 * @author Heinz Kredel
021 */
022public interface RealRoots<C extends RingElem<C> & Rational> extends Serializable {
023
024
025    /**
026     * Real root bound. With f(M) * f(-M) != 0.
027     * @param f univariate polynomial.
028     * @return M such that -M &lt; root(f) &gt; M.
029     */
030    public C realRootBound(GenPolynomial<C> f);
031
032
033    /**
034     * Isolating intervals for the real roots.
035     * @param f univariate polynomial.
036     * @return a list of isolating intervalls for the real roots of f.
037     */
038    public List<Interval<C>> realRoots(GenPolynomial<C> f);
039
040
041    /**
042     * Isolating intervals for the real roots.
043     * @param f univariate polynomial.
044     * @param eps requested intervals length.
045     * @return a list of isolating intervals v such that |v| &lt; eps.
046     */
047    public List<Interval<C>> realRoots(GenPolynomial<C> f, C eps);
048
049
050    /**
051     * Isolating intervals for the real roots.
052     * @param f univariate polynomial.
053     * @param eps requested intervals length.
054     * @return a list of isolating intervals v such that |v| &lt; eps.
055     */
056    public List<Interval<C>> realRoots(GenPolynomial<C> f, BigRational eps);
057
058
059    /**
060     * Sign changes on interval bounds.
061     * @param iv root isolating interval with f(left) * f(right) != 0.
062     * @param f univariate polynomial.
063     * @return true if f(left) * f(right) &lt; 0, else false
064     */
065    public boolean signChange(Interval<C> iv, GenPolynomial<C> f);
066
067
068    /**
069     * Number of real roots in interval.
070     * @param iv interval with f(left) * f(right) != 0.
071     * @param f univariate polynomial.
072     * @return number of real roots of f in I.
073     */
074    public long realRootCount(Interval<C> iv, GenPolynomial<C> f);
075
076
077    /**
078     * Refine interval.
079     * @param iv root isolating interval with f(left) * f(right) &lt; 0.
080     * @param f univariate polynomial, non-zero.
081     * @param eps requested interval length.
082     * @return a new interval v such that |v| &lt; eps.
083     */
084    public Interval<C> refineInterval(Interval<C> iv, GenPolynomial<C> f, BigRational eps);
085
086
087    /**
088     * Refine intervals.
089     * @param V list of isolating intervals with f(left) * f(right) &lt; 0.
090     * @param f univariate polynomial, non-zero.
091     * @param eps requested intervals length.
092     * @return a list of new intervals v such that |v| &lt; eps.
093     */
094    public List<Interval<C>> refineIntervals(List<Interval<C>> V, GenPolynomial<C> f, BigRational eps);
095
096
097    /**
098     * Real algebraic number sign.
099     * @param iv root isolating interval for f, with f(left) * f(right) &lt; 0.
100     * @param f univariate polynomial, non-zero.
101     * @param g univariate polynomial, gcd(f,g) == 1.
102     * @return sign(g(v)), with v a new interval contained in iv such that g(v)
103     *         != 0.
104     */
105    public int realSign(Interval<C> iv, GenPolynomial<C> f, GenPolynomial<C> g);
106
107
108    /**
109     * Real algebraic number magnitude.
110     * @param iv root isolating interval for f, with f(left) * f(right) &lt; 0.
111     * @param f univariate polynomial, non-zero.
112     * @param g univariate polynomial, gcd(f,g) == 1.
113     * @param eps length limit for interval length.
114     * @return g(iv).
115     */
116    public C realMagnitude(Interval<C> iv, GenPolynomial<C> f, GenPolynomial<C> g, BigRational eps);
117
118}