Updated Manual wrt to new functionality

.gitattributes

@@ -2864,13 +2864,14 @@ Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_IsZeroAtHomogeneous.tex -te
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_MonomialRepresentation.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Move.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Permute.tex -text
-Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex -text
-Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex -text
-Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SignAt.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SignAtHomogeneous.tex -text
-Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex -text
-Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex -text
+Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Substitute.tex -text
 Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SubstituteHomogeneous.tex -text
 Polynomial/doc_tex/Polynomial_ref/Polynomial_1.tex -text

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d.tex

@@ -188,17 +188,18 @@ is not a model of \ccc{UniqueFactorizationDomain}, this is of type \ccc{CGAL::Nu
 %resultant
 \ccNestedType{Resultant}{ A model of \ccc{PolynomialTraits_d::Resultant}.}
 
-% This was added by Michael Kerber, no review so far
+\ccNestedType{Polynomial_subresultants}
-%\ccNestedType{Polynomial_subresultants}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PolynomialSubresultants}.}
-%{ A model of \ccc{PolynomialTraits_d::PolynomialSubresultant}.}
+\ccNestedType{Polynomial_subresultants_with_cofactors}
-%\ccNestedType{Principal_subresultants}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PolynomialSubresultants_with_cofactors}.}
-%{ A model of \ccc{PolynomialTraits_d::PrincipalSubresultant}.}
+\ccNestedType{Principal_subresultants}
-%\ccNestedType{Sturm_habicht_sequence}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PrincipalSubresultants}.}
-%{ A model of \ccc{PolynomialTraits_d::SturmHabichtSequence}.}
+\ccNestedType{Sturm_habicht_sequence}
-%\ccNestedType{Sturm_habicht_sequence_with_cofactors}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::SturmHabichtSequence}.}
-%{ A model of \ccc{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}.}
+\ccNestedType{Sturm_habicht_sequence_with_cofactors}
-%\ccNestedType{Principal_sturm_habicht_sequence}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}.}
-%{ A model of \ccc{PolynomialTraits_d::PrincipalSturmHabichtSequence}.}
+\ccNestedType{Principal_sturm_habicht_sequence}
+{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PrincipalSturmHabichtSequence}.}
 
 
 \ccSeeAlso 

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex

@@ -0,0 +1,55 @@
+\begin{ccRefConcept}{PolynomialTraits_d::PolynomialSubresultants}
+\ccDefinition
+
+Computes the polynomial subresultant of two polynomials $p$ and $q$ of 
+type \ccc{PolynomialTraits_d::Polynomial_d} with respect to outermost variable.
+Let $p=\sum_{i=0}^n p_i t^i$ and $q\sum_{i=0}^m q_i t^i$, where $t$
+is the outermost variable.
+The $i$th subresultant (with $i=0,\ldots,\min\{n,m\}$) is defined by
+\begin{eqnarray*}
+\mathrm{Sres}_i(p,q)&=&\det \left(\begin{array}{cccccc}
+p_n & \ldots &\ldots& p_{2i-m+2}&t^{m-i-1}p \\
+&\ddots&&\vdots&\vdots\\
+&p_n&\ldots&p_{i+1}&p\\
+q_m & \ldots &\ldots & q_{2i-n+2}&t^{n-i-1}q \\
+&\ddots&&\vdots&\vdots\\
+&q_m&\ldots&q_{i+1}&q
+\end{array}\right)
+\end{eqnarray*}
+In the exceptional case that $n=m$, $\mathrm{Sres_n}$ is set to $q$.
+
+The result is written in an output range, starting with the $0$th subresultant
+$\mathrm{Sres}_0(p,q)$
+(aka as the resultant of $p$ and $q$).
+
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_domain_without_division}
+is provided by the function \ccc{CGAL::polynomial_subresultants}.
+
+\ccOperations
+\ccMethod{template<typename OutputIterator>
+        OutputIterator operator()(Polynomial_d   p,
+                                  Polynomial_d   q,
+                                  OutputIterator out);}
+         { computes the polynomial subresultants of $p$ and $q$, 
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+
+\ccMethod{template<typename OutputIterator>
+        OutputIterator operator()(Polynomial_d   p,
+                                  Polynomial_d   q,
+                                  OutputIterator out,
+                                  int i);}
+         { computes the polynomial subresultants of $p$ and $q$, 
+           with respect to the variable $x_i$.}
+
+%\ccHasModels
+
+\ccSeeAlso
+
+\ccRefIdfierPage{Polynomial_d}\\
+\ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{CGAL::polynomial_subresultants}\\
+
+\end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex

@@ -0,0 +1,56 @@
+\begin{ccRefConcept}{PolynomialTraits_d::PolynomialSubresultantsWithCofactors}
+\ccDefinition
+
+Computes the polynomial subresultant of two polynomials $p$ and $q$ of degree
+$n$ and $m$, respectively, 
+as defined in the documentation of \ccc{PolynomialTraits_d::PolynomialSubresultants}.
+Moreover, for $\mathrm{Sres}_i(p,q)$, polynomials $u_i$ and $v_i$
+with $\deg u_i\leq m-i-1$ and $\deg v_i\leq n-i-1$ are computed 
+such that $\mathrm{Sres}_i(p,q)=u_i p + v_i q$. $u_i$ and $v_i$ are called
+the \emph{cofactors} of $\mathrm{Sres}_i(p,q)$.
+ 
+The result is written in three output ranges, each of length $\min\{n,m\}+1$, 
+starting with the $0$th subresultant and the corresponding cofactors.
+
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_division}
+is provided by the function \ccc{CGAL::polynomial_subresultants_with_cofactors}.
+
+\ccCreationVariable{fo}
+\ccOperations
+\ccMethod{template< typename OutputIterator1,
+                    typename OutputIterator2,
+                    typename OutputIterator3 >
+        OutputIterator1 operator()(Polynomial_d   p,
+                                   Polynomial_d   q,
+                                   OutputIterator1 sres,
+                                   OutputIterator2 co_p,
+                                   OutputIterator3 co_q);}
+         { computes the subresultants of $p$ and $q$, and the cofactors, 
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+
+\ccMethod{template< typename OutputIterator1,
+                    typename OutputIterator2,
+                    typename OutputIterator3 >
+        OutputIterator1 operator()(Polynomial_d   p,
+                                   Polynomial_d   q,
+                                   OutputIterator1 sres,
+                                   OutputIterator2 co_p,
+                                   OutputIterator3 co_q,
+                                   int i);}
+         { computes the subresultants of $p$ and $q$, and the cofactors, 
+           with respect to $x_i$. Each element is of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+
+%\ccHasModels
+
+\ccSeeAlso
+
+\ccRefIdfierPage{Polynomial_d}\\
+\ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{PolynomialTraits_d::PolynomialSubresultants}\\
+\ccRefIdfierPage{CGAL::polynomial_subresultants_with_cofactors}\\
+
+\end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex

@@ -1,33 +0,0 @@
-\begin{ccRefConcept}{PolynomialTraits_d::Polynomial_subresultants}
-\ccDefinition
-
-Computes the polynomial subresultant of two polynomials $f$ and $g$ of 
-type \ccc{PolynomialTraits_d::Polynomial_d} with respect a certain variable.
-The result is written in an output range, starting with the $0$th subresultant
-(aka as the resultant of $f$ and $g$).
-
-\ccOperations
-\ccMethod{template<typename OutputIterator>
-        OutputIterator operator()(Polynomial_d   f,
-                                  Polynomial_d   g,
-                                  OutputIterator out);}
-         { computes the polynomial subresultants of $f$ and $g$, 
-           with respect to the outermost variable. Each element is of type
-           \ccc{PolynomialTraits_d::Polynomial_d}.}
-
-\ccMethod{template<typename OutputIterator>
-        OutputIterator operator()(Polynomial_d   f,
-                                  Polynomial_d   g,
-                                  OutputIterator out,
-                                  int i);}
-         { computes the polynomial subresultants of $f$ and $g$, 
-           with respect to the variable $x_i$.}
-
-%\ccHasModels
-
-\ccSeeAlso
-
-\ccRefIdfierPage{Polynomial_d}\\
-\ccRefIdfierPage{PolynomialTraits_d}\\
-
-\end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex

@@ -1,7 +1,7 @@
-\begin{ccRefConcept}{PolynomialTraits_d::Principal_sturm_habicht_sequence}
+\begin{ccRefConcept}{PolynomialTraits_d::PrincipalSturmHabichtSequence}
 \ccDefinition
 
-Computes the principal coefficients of the Sturm-Habicht sequence 
+Computes the principal leading coefficients of the Sturm-Habicht sequence 
 of a polynomials $f$ of type \ccc{PolynomialTraits_d::Polynomial_d} 
 with respect a certain variable $x_i$.
 This means that for the $j$th Sturm-Habicht polynomial, this methods returns
@@ -11,6 +11,15 @@ Note that the degree of the $j$th Sturm-Habicht polynomial is at most $j$,
 but the principal coefficient might be zero, thus, this functor does not
 necessarily give the leading coefficient of the Sturm-Habicht polynomials
 
+In case that \ccc{PolynomialTraits_d::Coefficient_type} is \ccc{RealEmbeddable}, the function \ccc{CGAL::stha_count_number_of_real_roots} can be used
+on the resulting sequence to count the number of distinct real roots of
+the polynomial~$f$.
+
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_domain_without_division}
+is provided by the function \ccc{CGAL::principal_sturm_habicht_sequence}.
+
 \ccOperations
 \ccMethod{template<typename OutputIterator>
         OutputIterator operator()(Polynomial_d   f,
@@ -34,5 +43,7 @@ necessarily give the leading coefficient of the Sturm-Habicht polynomials
 
 \ccRefIdfierPage{Polynomial_d}\\
 \ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{CGAL::principal_sturm_habicht_sequence}\\
+\ccRefIdfierPage{CGAL::stha_count_number_of_real_roots}\\
 
 \end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex

@@ -0,0 +1,48 @@
+\begin{ccRefConcept}{PolynomialTraits_d::PrincipalSubresultants}
+\ccDefinition
+
+Computes the principal subresultant of two polynomials $p$ and $q$ of 
+type \ccc{PolynomialTraits_d::Coefficient_type} 
+with respect to the outermost variable.
+The $i$th principal subresultant, $\mathrm{sres}_i(p,q)$,
+is defined as the coefficient at $t^i$ of the $i$th polynomial
+subresultant $\mathrm{Sres}_i(p,q)$. Thus, it is either the leading
+coefficient of $\mathrm{Sres}_i$, or zero in the case where its degree is 
+below $i$.
+
+The result is written in an output range, starting with the $0$th subresultant
+$\mathrm{sres}_0(p,q)$
+,aka as the resultant of $p$ and $q$.
+(Note that $\mathrm{sres}_0(p,q)=\mathrm{Sres}_0(p,q)$ by definition)
+
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_domain_without_division}
+is provided by the function \ccc{CGAL::principal_subresultants}.
+
+\ccOperations
+\ccMethod{template<typename OutputIterator>
+        OutputIterator operator()(Polynomial_d   p,
+                                  Polynomial_d   q,
+                                  OutputIterator out);}
+         { computes the principal subresultants of $p$ and $q$, 
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Coefficient_type}.}
+
+\ccMethod{template<typename OutputIterator>
+        OutputIterator operator()(Polynomial_d   p,
+                                  Polynomial_d   q,
+                                  OutputIterator out,
+                                  int i);}
+         { computes the principal subresultants of $p$ and $q$, 
+           with respect to the variable $x_i$.}
+
+%\ccHasModels
+
+\ccSeeAlso
+
+\ccRefIdfierPage{Polynomial_d}\\
+\ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{CGAL::principal_subresultants}\\
+
+\end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex

@@ -1,43 +0,0 @@
-\begin{ccRefConcept}{PolynomialTraits_d::Principal_subresultants}
-\ccDefinition
-
-Computes the principal subresultant of two polynomials $f$ and $g$ of 
-type \ccc{PolynomialTraits_d::Polynomial_d} 
-with respect a certain variable $x_i$.
-The principal subresultants are also known as {\it scalar} subresultants.
-
-The $j$th such principal subresultant is defined to be the coefficient 
-of $x_i^j$ in the $j$-th subresultant polynomial of $f$ and $g$.
-Since the degree of the $j$-th subresultant polynomial is at most $j$,
-this principal coefficients are sometimes called the 
-{\tt formal leading coefficients} (``formal'' because they might vanish).
-
-The result is written in an output range, 
-starting with the $0$th principal subresultant
-(aka as the resultant of $f$ and $g$).
-
-\ccOperations
-\ccMethod{template<typename OutputIterator>
-        OutputIterator operator()(Polynomial_d   f,
-                                  Polynomial_d   g,
-                                  OutputIterator out);}
-         { computes the principal subresultants of $f$ and $g$, 
-           with respect to the outermost variable. Each element is of type
-           \ccc{PolynomialTraits_d::Coefficient_type}.}
-
-\ccMethod{template<typename OutputIterator>
-        OutputIterator operator()(Polynomial_d   f,
-                                  Polynomial_d   g,
-                                  OutputIterator out,
-                                  int i);}
-         { computes the principal subresultants of $f$ and $g$, 
-           with respect to the variable $x_i$.}
-
-%\ccHasModels
-
-\ccSeeAlso
-
-\ccRefIdfierPage{Polynomial_d}\\
-\ccRefIdfierPage{PolynomialTraits_d}\\
-
-\end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex

@@ -1,18 +1,34 @@
-\begin{ccRefConcept}{PolynomialTraits_d::Sturm_habicht_sequence}
+\begin{ccRefConcept}{PolynomialTraits_d::SturmHabichtSequence}
 \ccDefinition
 
-Computes the Sturm-Habicht sequence of a polynomials $f$ of type 
+Computes the Sturm-Habicht sequence 
+(aka the signed subresultant sequence)
+of a polynomials $f$ of type 
 \ccc{PolynomialTraits_d::Polynomial_d} with respect a certain variable $x_i$.
 The Sturm-Habicht sequence is similar to the polynomial subresultant sequence
-of $f$ and its derivative with respect to $x_i$, but some entries
+of $f$ and its derivative $f':=\frac{\partial f}{\partial x_i}$
-are multiplied by $-1$. With that, it becomes possible to count
+with respect to $x_i$. The implementation is based on the following definition:
-the number of real roots of (univariate) polynomials.
+
-Sturm-Habicht sequences are also sometimes 
+Let $n:=\deg f$ and $\delta_k:=(-1)^{k(k+1)/2}$. 
-called signed subresultant sequences in the literature.
+For $k\in\{0,\ldots,n\}$, the {\it $k$th Sturm-Habicht polynomial} 
+of $f$ is defined as:
+$$\mathrm{Stha}_k(f)=\left\{\begin{array}{cc}
+f & \textrm{if\ } k=n\\
+f' & \textrm{if\ } k=n-1\\
+\delta_{n-k-1}\mathrm{Sres}_k(f,f') &\textrm{if\ } 0\leq k\leq n-2
+\end{array}\color{white}\right\}\color{black}$$
+where $\mathrm{Sres}_k(f,f')$ is defined 
+as in the concept \ccc{PolynomialTraits_d::PolynomialSubresultants}.
+
 The result is written in an output range, 
 starting with the $0$th Sturm-Habicht polynomial (which is equal to
 the discriminant of $f$ up to a multiple of the leading coefficient)
 
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_domain_without_division}
+is provided by the function \ccc{CGAL::sturm_habicht_sequence}.
+
 \ccCreationVariable{fo}
 \ccOperations
 \ccMethod{template<typename OutputIterator>
@@ -35,5 +51,6 @@ the discriminant of $f$ up to a multiple of the leading coefficient)
 
 \ccRefIdfierPage{Polynomial_d}\\
 \ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{CGAL::sturm_habicht_sequence}\\
 
 \end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex

@@ -1,6 +1,22 @@
-\begin{ccRefConcept}{PolynomialTraits_d::Sturm_habicht_sequence_with_cofactors}
+\begin{ccRefConcept}{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}
 \ccDefinition
 
+Computes the Sturm-Habicht polynomials of a polynomial $f$ of degree $n$, 
+as defined in the documentation of \ccc{PolynomialTraits_d::SturmHabichtSequence}.
+Moreover, for $\mathrm{Stha}_i(f)$, polynomials $u_i$ and $v_i$
+with $\deg u_i\leq n-i-2$ and $\deg v_i\leq n-i-1$ are computed 
+such that $\mathrm{Sres}_i(p,q)=u_i f + v_i f'$. $u_i$ and $v_i$ are called
+the \emph{cofactors} of $\mathrm{Stha}_i(f)$.
+ 
+The result is written in three output ranges, each of length $\min\{n,m\}+1$, 
+starting with the $0$th Sturm-Habicht polynomial $\mathrm{Stha_0(f)}$ 
+and the corresponding cofactors.
+
+A default implementation for the case that 
+\ccc{Polynomial_traits_d::Coefficient_type} 
+is a model of \ccc{CGAL::Integral_division}
+is provided by the function \ccc{CGAL::sturm_habicht_sequence_with_cofactors}.
+
 Computes the Sturm-Habicht sequence of a polynomials $f$ of type 
 \ccc{PolynomialTraits_d::Polynomial_d} with respect a certain variable $x_i$.
 Additionally, it computes two ranges of cofactors, {\tt co\_f} and {\tt co\_fx}
@@ -37,5 +53,7 @@ with the property that {\tt stha[i] == co\_f[i] f + co\_fx[i] f'}.
 
 \ccRefIdfierPage{Polynomial_d}\\
 \ccRefIdfierPage{PolynomialTraits_d}\\
+\ccRefIdfierPage{PolynomialTraits_d::SturmHabichtSequence}\\
+\ccRefIdfierPage{CGAL::sturm_habicht_sequence_with_cofactors}\\
 
 \end{ccRefConcept}

Polynomial/doc_tex/Polynomial_ref/intro.tex

@@ -80,11 +80,12 @@
 %\ccRefConceptPage{PolynomialTraits_d::ScaleDown}\\
 
 \ccRefConceptPage{PolynomialTraits_d::Resultant}\\
-%\ccRefConceptPage{PolynomialTraits_d::Polynomial_subresultants}\\
+\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultants}\\
-%\ccRefConceptPage{PolynomialTraits_d::Principal_subresultants}\\
+\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultantsWithCofactors}\\
-%\ccRefConceptPage{PolynomialTraits_d::Sturm_habicht_sequence}\\
+\ccRefConceptPage{PolynomialTraits_d::PrincipalSubresultants}\\
-%\ccRefConceptPage{PolynomialTraits_d::Sturm_habicht_sequence_with_cofactors}\\
+\ccRefConceptPage{PolynomialTraits_d::SturmHabichtSequence}\\
-%\ccRefConceptPage{PolynomialTraits_d::Principal_sturm_habicht_sequence}\\
+\ccRefConceptPage{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}\\
+\ccRefConceptPage{PolynomialTraits_d::PrincipalSturmHabichtSequence}\\
 
 
 \subsubsection*{Classes} 
@@ -152,8 +153,10 @@
 %\ccRefIdfierPage{CGAL::ScaleDown}\\
 
 \ccRefIdfierPage{CGAL::resultant}\\
-%\ccRefIdfierPage{CGAL::Polynomial_subresultants}\\
+\ccRefIdfierPage{CGAL::polynomial_subresultants}\\
-%\ccRefIdfierPage{CGAL::Principal_subresultants}\\
+\ccRefIdfierPage{CGAL::polynomial_subresultants_with_cofactors}\\
-%\ccRefIdfierPage{CGAL::Sturm_habicht_sequence}\\
+\ccRefIdfierPage{CGAL::principal_subresultants}\\
-%\ccRefIdfierPage{CGAL::Sturm_habicht_sequence_with_cofactors}\\
+\ccRefIdfierPage{CGAL::sturm_habicht_sequence}\\
-%\ccRefIdfierPage{CGAL::Principal_sturm_habicht_sequence}\\
+\ccRefIdfierPage{CGAL::sturm_habicht_sequence_with_cofactors}\\
+\ccRefIdfierPage{CGAL::principal_sturm_habicht_sequence}\\
+\ccRefIdfierPage{CGAL::stha_count_number_of_real_roots}\\

Polynomial/doc_tex/Polynomial_ref/main.tex

@@ -71,12 +71,12 @@
 
 \input{Polynomial_ref/PolynomialTraits_d_Resultant.tex}
 
-%// This was added by Michael Kerber, missing review 
+\input{Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex}
-%%\input{Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex}
+\input{Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex}
-%%\input{Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex}
+\input{Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex}
-%%\input{Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex}
+\input{Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex}
-%%\input{Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex}
+\input{Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex}
-%%\input{Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex}
+\input{Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex}
 
 \input{Polynomial_ref/Polynomial.tex}
 \input{Polynomial_ref/Polynomial_traits_d.tex}

Polynomial/doc_tex/Polynomial_ref/polynomial_utils.tex

@@ -802,3 +802,202 @@ Adapts \ccc{Polynomial_traits_d<Polynomial_d>::Resultant}.
 \ccRefConceptPage{PolynomialTraits_d}\\
 \ccRefConceptPage{PolynomialTraits_d::Resultant}\\
 \end{ccRefFunction}
+
+% polynomial_subresultants
+\begin{ccRefFunction}{polynomial_subresultants}
+\ccDefinition
+
+Computes the polynomial subresultants
+of two polynomials, defined as in the concept 
+\ccc{Polynomial_traits_d::PolynomialSubresultants}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_domain_without_division}.
+
+The computation method depends on the algebraic category of
+\ccc{PolynomialTraits_d::Coefficient_type}.
+if it models \ccc{CGAL::Integral_division}, 
+the subresultants are computed
+by a pseudo-division approach~\cite{ducos-optimizations}. 
+If they only model a
+\ccc{CGAL::Integral_domain_without_division}, the subresultants
+are computed by evaluating the determinants directly, avoiding divisions
+completely~\cite{kerber-division}.
+
+\ccOperations
+\ccFunction{template<typename Polynomial_traits_d,typename OutputIterator>
+        OutputIterator polynomial_subresultants
+            (typename Polynomial_traits_d::Polynomial_d   p,
+             typename Polynomial_traits_d::Polynomial_d   q,
+             OutputIterator out);}
+         { computes the polynomial subresultants of $p$ and $q$, 
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultants}\\
+\end{ccRefFunction}
+
+% polynomial_subresultants_with_cofactors
+\begin{ccRefFunction}{polynomial_subresultants_with_cofactors}
+\ccDefinition
+
+Computes the polynomial subresultants
+of two polynomials and their cofactors, defined as in the concept 
+\ccc{Polynomial_traits_d::PolynomialSubresultantsWithCofactors}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_division}.
+
+\ccOperations
+\ccFunction{template<typename Polynomial_traits_d,
+    typename OutputIterator1, 
+    typename OutputIterator2,
+    typename OutputIterator3>
+    OutputIterator1 polynomial_subresultants_with_cofactors
+      (typename Polynomial_traits_d::Polynomial_d p,
+       typename Polynomial_traits_d::Polynomial_d q,
+       OutputIterator1 sres_out,
+       OutputIterator2 coP_out,
+       OutputIterator3 coQ_out);}
+         { computes the polynomial subresultants of $p$ and $q$, 
+           \ccc{sres_out}, with respect to the outermost variable, and
+           the cofactors for $P$, \ccc{coP_out} and $Q$, \ccc{coQ_out}. 
+           The elements  of each output range are of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultantsWithCofactors}\\
+\end{ccRefFunction}
+
+
+% principal_subresultants
+\begin{ccRefFunction}{principal_subresultants}
+\ccDefinition
+
+Computes the principal subresultants
+of two polynomials, defined as in the concept 
+\ccc{Polynomial_traits_d::PrincipalSubresultants}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_domain_without_division}.
+
+\ccOperations
+\ccFunction{template<typename Polynomial_traits_d,typename OutputIterator>
+        OutputIterator principal_subresultants
+            (typename Polynomial_traits_d::Polynomial_d   p,
+             typename Polynomial_traits_d::Polynomial_d   q,
+             OutputIterator out);}
+         { computes the principal subresultants of $p$ and $q$, 
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Coefficient_type}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::PrincipalSubresultants}\\
+\end{ccRefFunction}
+
+% sturm_habicht_sequence
+\begin{ccRefFunction}{sturm_habicht_sequence}
+\ccDefinition
+
+Computes the Sturm-Habicht-polynomials
+of a polynomial, defined as in the concept 
+\ccc{Polynomial_traits_d::SturmHabichtSequence}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_domain_without_division}.
+
+The computation works simply by calling \ccc{CGAL::polynomial_subresultants},
+and adjusting the signs.
+
+\ccOperations
+\ccFunction{template<typename Polynomial_traits_d,typename OutputIterator> OutputIterator
+    sturm_habicht_sequence(typename Polynomial_traits_d::Polynomial_d f, 
+                           OutputIterator out);}
+         { computes the Sturm-Habicht-sequence of $f$
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::SturmHabichtSequence}\\
+\ccRefIdfierPage{CGAL::polynomial_subresultants}\\
+\end{ccRefFunction}
+
+% sturm_habicht_sequence_with_cofactors
+\begin{ccRefFunction}{sturm_habicht_sequence_with_cofactors}
+\ccDefinition
+
+Computes the Sturm-Habicht-sequence of a polynomial
+and its cofactors, defined as in the concept 
+\ccc{Polynomial_traits_d::SturmHabichtSequenceWithCofactors}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_division}.
+
+\ccOperations
+\ccFunction{template<typename Polynomial_traits_d,
+    typename OutputIterator1,
+    typename OutputIterator2,
+    typename OutputIterator3> 
+    OutputIterator1
+    sturm_habicht_sequence_with_cofactors
+      (typename Polynomial_traits_d::Polynomial_d f,
+       OutputIterator1 stha_out,
+       OutputIterator2 cof_out,
+       OutputIterator3 cofx_out);}
+         { computes the Sturm-Habicht sequence of $f$
+           \ccc{stha_out}, with respect to the outermost variable, and
+           the cofactors for $f$, \ccc{cof_out} and $f'$, \ccc{cofx_out}. 
+           The elements  of each output range are of type
+           \ccc{PolynomialTraits_d::Polynomial_d}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}\\
+\end{ccRefFunction}
+
+
+% principal_subresultants
+\begin{ccRefFunction}{principal_sturm_habicht_sequence}
+\ccDefinition
+
+Computes the principal Sturm-Habicht coefficients
+of a polynomial, defined as in the concept 
+\ccc{Polynomial_traits_d::PrincipalSturmHabichtSequence}, 
+if \ccc{PolynomialTraits_d::Coefficient_type}
+is at least a model of \ccc{CGAL::Integral_domain_without_division}.
+
+\ccOperations
+\ccFunction{  template <typename Polynomial_traits_d,typename OutputIterator> inline
+    OutputIterator
+    principal_sturm_habicht_sequence
+      (typename Polynomial_traits_d::Polynomial_d A, 
+       OutputIterator out);}
+         { computes the principal Sturm-Habicht coefficients of $f$
+           with respect to the outermost variable. Each element is of type
+           \ccc{PolynomialTraits_d::Coefficient_type}.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::PrincipalSturmHabichtSequence}\\
+\end{ccRefFunction}
+
+% stha_count_number_of_real_roots
+\begin{ccRefFunction}{stha_count_number_of_real_roots}
+\ccDefinition
+
+Given a range that is interpreted as the principal Sturm-Habicht coefficients
+of a polynomial $f$, the function computes
+$$m:=\# \{\alpha\in\mathbb{R}\mid f(\alpha)=0\}$$
+that is, the number of distinct real roots of $f$.
+
+The value type of the iterator range must be a model of \ccc{RealEmbeddable}.
+
+\ccOperations
+\ccFunction{  template<typename InputIterator>
+    int stha_count_number_of_real_roots(InputIterator start,InputIterator end);}
+         { computes the number of distinct real roots of $f$ whose principal Sturm-Habicht coefficients are passed by the iterator range.}
+\ccSeeAlso
+\ccRefConceptPage{Polynomial_d}\\
+\ccRefConceptPage{PolynomialTraits_d}\\
+\ccRefConceptPage{PolynomialTraits_d::PrincipalSturmHabichtSequence}\\
+\end{ccRefFunction}