/*
 * $Id$
 */

package edu.jas.root;


import java.io.Serializable;
import java.util.List;

import edu.jas.arith.Rational;
import edu.jas.arith.BigRational;
import edu.jas.poly.GenPolynomial;
import edu.jas.structure.RingElem;
import edu.jas.structure.GcdRingElem;


/**
 * Real roots interface.
 * @param  coefficient type.
 * @author Heinz Kredel
 */
public interface RealRoots & Rational> extends Serializable {


    /**
     * Real root bound. With f(M) * f(-M) != 0.
     * @param f univariate polynomial.
     * @return M such that -M < root(f) > M.
     */
    public C realRootBound(GenPolynomial f);


    /**
     * Isolating intervals for the real roots.
     * @param f univariate polynomial.
     * @return a list of isolating intervalls for the real roots of f.
     */
    public List> realRoots(GenPolynomial f);


    /**
     * Isolating intervals for the real roots.
     * @param f univariate polynomial.
     * @param eps requested intervals length.
     * @return a list of isolating intervals v such that |v| < eps.
     */
    public List> realRoots(GenPolynomial f, C eps);


    /**
     * Isolating intervals for the real roots.
     * @param f univariate polynomial.
     * @param eps requested intervals length.
     * @return a list of isolating intervals v such that |v| < eps.
     */
    public List> realRoots(GenPolynomial f, BigRational eps);


    /**
     * Sign changes on interval bounds.
     * @param iv root isolating interval with f(left) * f(right) != 0.
     * @param f univariate polynomial.
     * @return true if f(left) * f(right) < 0, else false
     */
    public boolean signChange(Interval iv, GenPolynomial f);


    /**
     * Number of real roots in interval.
     * @param iv interval with f(left) * f(right) != 0.
     * @param f univariate polynomial.
     * @return number of real roots of f in I.
     */
    public long realRootCount(Interval iv, GenPolynomial f);


    /**
     * Refine interval.
     * @param iv root isolating interval with f(left) * f(right) < 0.
     * @param f univariate polynomial, non-zero.
     * @param eps requested interval length.
     * @return a new interval v such that |v| < eps.
     */
    public Interval refineInterval(Interval iv, GenPolynomial f, C eps);


    /**
     * Refine intervals.
     * @param V list of isolating intervals with f(left) * f(right) < 0.
     * @param f univariate polynomial, non-zero.
     * @param eps requested intervals length.
     * @return a list of new intervals v such that |v| < eps.
     */
    public List> refineIntervals(List> V, GenPolynomial f, C eps);


    /**
     * Real algebraic number sign.
     * @param iv root isolating interval for f, with f(left) * f(right) < 0.
     * @param f univariate polynomial, non-zero.
     * @param g univariate polynomial, gcd(f,g) == 1.
     * @return sign(g(v)), with v a new interval contained in iv such that g(v) !=
     *         0.
     */
    public int realSign(Interval iv, GenPolynomial f, GenPolynomial g);


    /**
     * Real algebraic number magnitude.
     * @param iv root isolating interval for f, with f(left) * f(right) < 0.
     * @param f univariate polynomial, non-zero.
     * @param g univariate polynomial, gcd(f,g) == 1.
     * @param eps length limit for interval length.
     * @return g(iv).
     */
    public C realMagnitude(Interval iv, GenPolynomial f, GenPolynomial g, C eps);

}