summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/polexpr/polexpr.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/polexpr/polexpr.txt')
-rw-r--r--Master/texmf-dist/doc/latex/polexpr/polexpr.txt167
1 files changed, 124 insertions, 43 deletions
diff --git a/Master/texmf-dist/doc/latex/polexpr/polexpr.txt b/Master/texmf-dist/doc/latex/polexpr/polexpr.txt
index 16cdff04d1e..dd2ab246900 100644
--- a/Master/texmf-dist/doc/latex/polexpr/polexpr.txt
+++ b/Master/texmf-dist/doc/latex/polexpr/polexpr.txt
@@ -4,8 +4,8 @@
Package polexpr documentation
===============================
-0.4.2 (2018/03/03)
-==================
+0.5 (2018/04/08)
+================
.. contents::
@@ -120,7 +120,13 @@ the macro call ``\PolGCD{f_1}{f_2}{k}`` sets ``k`` to the (unitary) GCD of
Examples of localization of roots
---------------------------------
-First some remarks about auxiliaries.
+.. attention::
+
+ At ``0.5``, `\\PolToSturm{P}{S} <PolToSturm_>`_ was modified to
+ create a chain of primitive integer coefficients polynomials. This
+ speeds up evaluations, hence localization of roots afterwards. Thus
+ ``S_1`` will not necessarily be the derivative of ``S_0``, even if
+ ``P`` is square-free.
- To make printed decimal numbers more enjoyable than via
``\xintSignedFrac``::
@@ -137,9 +143,10 @@ First some remarks about auxiliaries.
to modify output of `\\PolToExpr{polname}`_.
-- for extra info in log file ``\xintverbosetrue``. In fact one can also
- work from command line then (I recommend ``rlwrap`` for encapsulating
- ``latex``).
+- For extra info in log file use ``\xintverbosetrue``.
+
+- To make producing this documentation simpler, the results from execution
+ of the code snippets are not included. Please try them out yourself...
A typical example
@@ -166,8 +173,10 @@ was no further reduction.
And here is the first root with twenty digits after decimal mark:
\PolEnsureIntervalLength{f}{1}{-20}
\[\PolSturmIsolatedZeroLeft{f}{1}<Z_1<\PolSturmIsolatedZeroRight{f}{1}\]
- The derivative polynomial is \PolTypeset{f_1} (from
- $\PolDegree{f_0}=7$ we know that original polynomial was square-free).
+ The first element of the Sturm chain has degree $\PolDegree{f_0}$. As
+ this same as $\PolDegree{f}$ we know that the latter was square free.
+ So the derivative is up to a constant \PolTypeset{f_1} (in fact here
+ it is identical with it).
\PolToSturm{f_1}{f_1}\PolSturmIsolateZeros{f_1}%
It has \PolSturmNbOfIsolatedZeros{f_1} distinct real
roots:
@@ -238,23 +247,27 @@ A Mignotte type polynomial
\PolTypeset{P} % prints it in expanded form
\PolToSturm{P}{P} % we can use same prefix for Sturm chain
\PolSturmIsolateZeros{P} % finds 4 real roots
+ This polynomial has \PolSturmNbOfIsolatedZeros{P} distinct real roots:
\PolPrintIntervals{P}%
% reports -2 < Z_1 < -1, 0 < Z_2 < 0.1, 0.1 < Z_3 < 0.2, 1 < Z_4 < 2
+ Let us refine the second and third intervals to separate the corresponding
+ roots:
\PolRefineInterval*{P}{2}% will refine to 0.0999990 < Z_2 < 0.0999991
\PolRefineInterval*{P}{3}% will refine to 0.100001 < Z_3 < 0.100002
\PolPrintIntervals{P}%
+ Let us now get to know all roots with 10 digits after decimal mark:
\PolEnsureIntervalLengths{P}{-10}%
\PolPrintIntervals{P}% now all roots are known 10 decimal digits after mark
+ Finally, we display 20 digits of the second root:
\PolEnsureIntervalLength{P}{2}{-20}% makes Z_2 known with 20 digits after mark
- There are $\PolSturmNbOfIsolatedZeros{P}$ distinct real roots and there holds
- $\PolSturmIsolatedZeroLeft{P}{2}<Z_2<\PolSturmIsolatedZeroRight{P}{2}$.
+ \[\PolSturmIsolatedZeroLeft{P}{2}<Z_2<\PolSturmIsolatedZeroRight{P}{2}\]
The last line produces::
0.09999900004999650028 < Z_2 < 0.09999900004999650029
The degree 41 polynomial with -2, -1.9, -1.8, ..., 0, 0.1, ..., 1.9, 2 as roots
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
@@ -299,9 +312,24 @@ Stress test: not a hard challenge to ``xint + polexpr``, but be a bit patient!
::
\PolDef{P}{mul((x-i*1e-1), i=-20..20)}%
- \PolToSturm{P}{S} % dutifully computes S_0, ..., S_{41}
- \PolSturmIsolateZeros{S} % finds *exactly* (but a bit slowly) all 41 roots!
- \PolPrintIntervals{S} % nice, isn't it?
+ \PolToSturm{P}{S} % dutifully computes S_0, ..., S_{41}
+ \PolSturmIsolateZeros[1]{S} % finds *exactly* (but a bit slowly) all 41 roots!
+ \PolPrintIntervals{S} % nice, isn't it?
+
+.. note::
+
+ Release ``0.5`` has experimental addition of optional argument
+ ``E`` to ``\PolSturmIsolateZeros``. It instructs to search roots only
+ in interval ``(-10^E, 10^E)``, extremities assumed to not be roots.
+ Thus here::
+
+ \PolSturmIsolateZeros[1]{S}
+
+ gives some speed gain; without it, it turns out in this case that
+ ``polexpr`` would have started with ``(-10^6, 10^6)`` interval.
+
+ This will probably get replaced in future by the specification of
+ a general interval.
Roots of Chebyshev polynomials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -453,11 +481,12 @@ Non-expandable macros
``\PolGet{polname}\fromarray\macro``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Does the converse operation to ``\PolAssign{polname}\toarray\macro``. No
- error checks on validity of coefficients as numbers. Each
- ``\macro{number}`` is expanded in an ``\edef`` before being assigned
- to a coefficient. Leading zero coefficients are removed from the
- polynomial.
+ Does the converse operation to
+ ``\PolAssign{polname}\toarray\macro``. Each individual
+ ``\macro{number}`` gets expanded in an ``\edef`` and then normalized
+ via xintfrac_\ 's macro ``\xintRaw``.
+
+ The leading zeros are removed from the polynomial.
(contrived) Example::
@@ -465,8 +494,11 @@ Non-expandable macros
\PolGet{f}\fromarray\foo
This will define ``f`` as would have ``\poldef f(x):=1-2x+5x^2-3x^3;``.
- However the coefficients are still in their original form (i.e.
- they were not subjected to ``\xintRaw`` or similar xintfrac_ macro.)
+
+ .. note::
+
+ Prior to ``0.5``, coefficients were not normalized via
+ ``\xintRaw`` for internal storage.
.. _PolFromCSV:
@@ -477,9 +509,8 @@ Non-expandable macros
values (or a macro expanding to such a list) of its coefficients,
the constant term being the first item. No validity checks. Spaces
from the list argument are trimmed. List items are each expanded in
- an ``\edef``, but currently left in their original form like e.g.
- ``1.5e3`` which is not converted to ``15/1[2]`` *raw* xintfrac_
- format (this may change).
+ an ``\edef`` and then put into normalized form via xintfrac_\ 's
+ macro ``\xintRaw``.
Leading zero coefficients are removed::
@@ -489,6 +520,11 @@ Non-expandable macros
See also expandable macro `\\PolToCSV <\\PolToCSV{polname}_>`_.
+ .. note::
+
+ Prior to ``0.5``, coefficients were not normalized via
+ ``\xintRaw`` for internal storage.
+
.. _PolTypeset:
``\PolTypeset{polname}``
@@ -679,15 +715,22 @@ Non-expandable macros
With, for example, ``polname`` being ``P`` and ``sturmname`` being
``S``, the macro starts by computing polynomials ``S_0 = P``, ``S_1
= P'``, ..., with ``S_{n+1}`` the opposite of the remainder of
- euclidean division of ``S_{n-1}`` by ``S_{n}``. The last non-zero
- remainder ``S_N`` is up to a factor the GCD of ``P`` and ``P'``
- hence a constant if and only if ``P`` is square-free.
+ euclidean division of ``S_{n-1}`` by ``S_{n}``.
+
+ .. attention::
+
+ Since ``0.5``, it further normalizes all these polynomials by making
+ them primitive (see `\\PolMakePrimitive`_).
+
+ The last non-zero remainder ``S_N`` is up to a factor the GCD of
+ ``P`` and ``P'`` hence it is a constant (i.e. ``1`` or ``-1`` since
+ ``0.5``) if and only if ``P`` is square-free.
In case ``S_N`` is not a constant, the macro then goes on with
- dividing all ``S_k``'s with ``S_N`` (which becomes ``1``).
+ dividing all ``S_k``'s with ``S_N`` (which then becomes ``1``).
- Thus ``S_0`` now has exactly the same real and complex
- roots as polynomial ``polname``, but each with multiplicity one.
+ Thus ``S_0`` has exactly the same real and complex roots as
+ polynomial ``polname``, but each root being now with multiplicity one.
.. _PolToSturm*:
@@ -999,6 +1042,16 @@ Non-expandable macros
coefficients and we want to keep the leading one as common
denominator.
+.. _PolMakePrimitive:
+
+``\PolMakePrimitive{polname}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Divides by the integer content see (`\\PolIContent
+ <PolIContent_>`_). This thus produces a polynomial with integer
+ coefficients having no common factor. The sign of the leading
+ coefficient is not modified.
+
Expandable macros
-----------------
@@ -1142,6 +1195,17 @@ and ``\PolToFloatExpr`` (and their auxiliaries) which need a
It expands to the degree. This is ``-1`` if zero polynomial but this
may change in future. Should it then expand to ``-\infty`` ?
+.. _PolIContent:
+
+``\PolIContent{polname}``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ It expands to the contents of the polynomial, i.e. to the positive
+ fraction such that dividing by this fraction produces a polynomial
+ with integer coefficients having no common prime divisor.
+
+ See `\\PolMakePrimitive <PolMakePrimitive_>`_.
+
.. _PolToExpr:
``\PolToExpr{polname}``
@@ -1365,7 +1429,6 @@ and ``\PolToFloatExpr`` (and their auxiliaries) which need a
There is also an out-of-range check done for some reasonable
error message (right before everything goes haywire).
-
.. _PolSturmIsolatedZeroLeft:
``\PolSturmIsolatedZeroLeft{sturmname}{index}``
@@ -1551,18 +1614,6 @@ Technicalities
Same remark for `\\PolAntiDiff{polname_1}{polname_2}`_.
-- If ``f`` was created from comma separated values by macro
- `\\PolFromCSV{polname}{\<csv\>}`_, then the coefficients will be in
- the output of `\\PolToList{polname}`_ and `\\PolToCSV{polname}`_ in
- the same format as originally in input: a ``1.3e2`` will again be a
- ``1.3e2``.
-
- In contrast when such coefficients are used in a ``\poldef`` (or
- ``\PolDef``) expression, they get transformed during the parsing to
- the xintfrac *raw* format.
- This *raw* format speeds up expansion of xintfrac macros for numerical
- evaluations.
-
- Currently, the package stores all coefficients from index ``0`` to
index equal to the polynomial degree inside a single macro, as a list.
This data structure is obviously very inefficient for polynomials of
@@ -1737,6 +1788,36 @@ CHANGE LOG
Documentation fix.
+- v0.5 (2018/04/08)
+
+ * bug fixes:
+
+ - `\\PolGet{polname}\\fromarray\\macro`_ crashed when ``\macro`` was
+ an xinttools_ array macro with no items. It now produces the zero
+ polynomial.
+ * breaking changes:
+
+ - `\\PolToSturm`_ creates primitive integer coefficients polynomials.
+ This speeds up localization of roots via
+ `\\PolSturmIsolateZeros`_. In case of user protests the author
+ will make available again the code producing the bona fide Sturm
+ polynomials as used formerly.
+ - polynomials created from `\\PolFromCSV`_ or `\\PolGet <PolGet_>`_
+ get their coefficients normalized via xintfrac_\ 's ``\xintRaw``.
+ * experimental change:
+
+ - optional argument to `\\PolSturmIsolateZeros`_ (see `The
+ degree 41 polynomial with -2, -1.9, -1.8, ..., 0, 0.1, ..., 1.9, 2
+ as roots`_ for usage). It will presumably be replaced in future by
+ an interval specification.
+ * new non-expandable macros:
+
+ - `\\PolMakePrimitive`_
+ * new expandable macros:
+
+ - `\\PolIContent`_
+
+
Acknowledgments
---------------