diff --git a/.gitattributes b/.gitattributes index 893326ed4f7..9e7a539d547 100644 --- a/.gitattributes +++ b/.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_Principal_sturm_habicht_sequence.tex -text -Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex -text +Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex -text +Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.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_Sturm_habicht_sequence_with_cofactors.tex -text +Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.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 diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d.tex index 91d10f791bd..0d07d10c207 100644 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d.tex +++ b/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} -%{ A model of \ccc{PolynomialTraits_d::PolynomialSubresultant}.} -%\ccNestedType{Principal_subresultants} -%{ A model of \ccc{PolynomialTraits_d::PrincipalSubresultant}.} -%\ccNestedType{Sturm_habicht_sequence} -%{ A model of \ccc{PolynomialTraits_d::SturmHabichtSequence}.} -%\ccNestedType{Sturm_habicht_sequence_with_cofactors} -%{ A model of \ccc{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}.} -%\ccNestedType{Principal_sturm_habicht_sequence} -%{ A model of \ccc{PolynomialTraits_d::PrincipalSturmHabichtSequence}.} +\ccNestedType{Polynomial_subresultants} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PolynomialSubresultants}.} +\ccNestedType{Polynomial_subresultants_with_cofactors} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PolynomialSubresultants_with_cofactors}.} +\ccNestedType{Principal_subresultants} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PrincipalSubresultants}.} +\ccNestedType{Sturm_habicht_sequence} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::SturmHabichtSequence}.} +\ccNestedType{Sturm_habicht_sequence_with_cofactors} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::SturmHabichtSequenceWithCofactors}.} +\ccNestedType{Principal_sturm_habicht_sequence} +{ Either \ccc{CGAL::Null_functor} or a model of \ccc{PolynomialTraits_d::PrincipalSturmHabichtSequence}.} \ccSeeAlso @@ -209,4 +210,4 @@ is not a model of \ccc{UniqueFactorizationDomain}, this is of type \ccc{CGAL::Nu \ccRefIdfierPage{CGAL::Polynomial_traits_d} -\end{ccRefConcept} \ No newline at end of file +\end{ccRefConcept} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex new file mode 100644 index 00000000000..bd5ee163f15 --- /dev/null +++ b/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 + 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 + 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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex new file mode 100644 index 00000000000..c67f0ef0e89 --- /dev/null +++ b/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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex deleted file mode 100644 index 1406ba18543..00000000000 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Polynomial_subresultants.tex +++ /dev/null @@ -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 - 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 - 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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex similarity index 64% rename from Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex rename to Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex index 41c5e74f8dd..16c3ad15bbd 100644 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex +++ b/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 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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex new file mode 100644 index 00000000000..4f7e3cfcf64 --- /dev/null +++ b/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 + 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 + 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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex deleted file mode 100644 index 9b7fd025fe9..00000000000 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex +++ /dev/null @@ -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 - 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 - 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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex similarity index 52% rename from Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex rename to Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex index 9df32829d62..dc0ef4a9b8c 100644 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex +++ b/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 -are multiplied by $-1$. With that, it becomes possible to count -the number of real roots of (univariate) polynomials. -Sturm-Habicht sequences are also sometimes -called signed subresultant sequences in the literature. +of $f$ and its derivative $f':=\frac{\partial f}{\partial x_i}$ +with respect to $x_i$. The implementation is based on the following definition: + +Let $n:=\deg f$ and $\delta_k:=(-1)^{k(k+1)/2}$. +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 @@ -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} diff --git a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex b/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex similarity index 61% rename from Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex rename to Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex index f3ae1ec7447..d3f1fab6cb5 100644 --- a/Polynomial/doc_tex/Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex +++ b/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} diff --git a/Polynomial/doc_tex/Polynomial_ref/intro.tex b/Polynomial/doc_tex/Polynomial_ref/intro.tex index 0cf234c168b..8f176c28cb7 100644 --- a/Polynomial/doc_tex/Polynomial_ref/intro.tex +++ b/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::Principal_subresultants}\\ -%\ccRefConceptPage{PolynomialTraits_d::Sturm_habicht_sequence}\\ -%\ccRefConceptPage{PolynomialTraits_d::Sturm_habicht_sequence_with_cofactors}\\ -%\ccRefConceptPage{PolynomialTraits_d::Principal_sturm_habicht_sequence}\\ +\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultants}\\ +\ccRefConceptPage{PolynomialTraits_d::PolynomialSubresultantsWithCofactors}\\ +\ccRefConceptPage{PolynomialTraits_d::PrincipalSubresultants}\\ +\ccRefConceptPage{PolynomialTraits_d::SturmHabichtSequence}\\ +\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::Principal_subresultants}\\ -%\ccRefIdfierPage{CGAL::Sturm_habicht_sequence}\\ -%\ccRefIdfierPage{CGAL::Sturm_habicht_sequence_with_cofactors}\\ -%\ccRefIdfierPage{CGAL::Principal_sturm_habicht_sequence}\\ \ No newline at end of file +\ccRefIdfierPage{CGAL::polynomial_subresultants}\\ +\ccRefIdfierPage{CGAL::polynomial_subresultants_with_cofactors}\\ +\ccRefIdfierPage{CGAL::principal_subresultants}\\ +\ccRefIdfierPage{CGAL::sturm_habicht_sequence}\\ +\ccRefIdfierPage{CGAL::sturm_habicht_sequence_with_cofactors}\\ +\ccRefIdfierPage{CGAL::principal_sturm_habicht_sequence}\\ +\ccRefIdfierPage{CGAL::stha_count_number_of_real_roots}\\ diff --git a/Polynomial/doc_tex/Polynomial_ref/main.tex b/Polynomial/doc_tex/Polynomial_ref/main.tex index d389f08951e..8d9c398af7a 100644 --- a/Polynomial/doc_tex/Polynomial_ref/main.tex +++ b/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_Polynomial_subresultants.tex} -%%\input{Polynomial_ref/PolynomialTraits_d_Principal_subresultants.tex} -%%\input{Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence.tex} -%%\input{Polynomial_ref/PolynomialTraits_d_Sturm_habicht_sequence_with_cofactors.tex} -%%\input{Polynomial_ref/PolynomialTraits_d_Principal_sturm_habicht_sequence.tex} +\input{Polynomial_ref/PolynomialTraits_d_PolynomialSubresultants.tex} +\input{Polynomial_ref/PolynomialTraits_d_PolynomialSubresultantsWithCofactors.tex} +\input{Polynomial_ref/PolynomialTraits_d_PrincipalSubresultants.tex} +\input{Polynomial_ref/PolynomialTraits_d_SturmHabichtSequence.tex} +\input{Polynomial_ref/PolynomialTraits_d_SturmHabichtSequenceWithCofactors.tex} +\input{Polynomial_ref/PolynomialTraits_d_PrincipalSturmHabichtSequence.tex} \input{Polynomial_ref/Polynomial.tex} \input{Polynomial_ref/Polynomial_traits_d.tex} diff --git a/Polynomial/doc_tex/Polynomial_ref/polynomial_utils.tex b/Polynomial/doc_tex/Polynomial_ref/polynomial_utils.tex index b3774ebc5d7..06bf4d8595e 100644 --- a/Polynomial/doc_tex/Polynomial_ref/polynomial_utils.tex +++ b/Polynomial/doc_tex/Polynomial_ref/polynomial_utils.tex @@ -802,3 +802,202 @@ Adapts \ccc{Polynomial_traits_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 + 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 + 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 + 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 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 + 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 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 + 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}