diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/polexpr/polexpr.txt')
-rw-r--r-- | Master/texmf-dist/doc/latex/polexpr/polexpr.txt | 713 |
1 files changed, 544 insertions, 169 deletions
diff --git a/Master/texmf-dist/doc/latex/polexpr/polexpr.txt b/Master/texmf-dist/doc/latex/polexpr/polexpr.txt index 19d5ccdf9c9..2825128f004 100644 --- a/Master/texmf-dist/doc/latex/polexpr/polexpr.txt +++ b/Master/texmf-dist/doc/latex/polexpr/polexpr.txt @@ -1,29 +1,35 @@ .. comment: -*- fill-column: 72; mode: rst; -*- -Package polexpr documentation -============================= +=============================== + Package polexpr documentation +=============================== + +0.3.1 (2018/01/18) +================== + +.. contents:: First Examples -------------- The syntax is:: - \poldef <name>(x):=<expression in variable x>; + \poldef polname(x):= expression in variable x; where in place of ``x`` an arbitrary *dummy variable* is authorized -(i.e. per default any of ``[a..z|A..Z]``; more letters can be declared +(i.e. per default any of ``[a-z|A-Z]``; more letters can be declared under Unicode engines.) One can also issue:: - \PolDef{name}{expression in variable x} + \PolDef{polname}{expression in variable x} which admits an optional first argument to modify the variable letter from its default ``x``. ``\poldef f(x):= 1-x+x^2;`` - defines polynomial ``f``. Polynomial names must start with a letter - and may contain letters, digits, and underscores. The variable must - be a single letter. The colon character is optional. The semi-colon - at end of expression is mandatory. + defines polynomial ``f``. Polynomial names must start with a + letter and may contain letters, digits, and underscores. The + variable must be a single letter. The colon character is optional. + The semi-colon at end of expression is mandatory. ``\PolDef{f}{1-x+x^2}`` does the same as ``\poldef f(x):= 1-x+x^2;`` To use another letter @@ -31,9 +37,9 @@ from its default ``x``. argument to ``\PolDef``. Useful if the semi-colon has been assigned some non-standard catcode by some package. -``\PolLet{g}{f}`` - saves a copy of ``f`` under name ``g``. - +``\PolLet{g}={f}`` + saves a copy of ``f`` under name ``g``. Also usable without ``=``. + ``\poldef f(z):= f(z)^2;`` redefines ``f`` in terms of itself. @@ -46,7 +52,7 @@ from its default ``x``. ``\PolDiff{f}{df_dx}`` sets ``df_dx`` to the derivative of ``f``. - + ``\PolDiff{df_dx}{f_xx}`` obtains second derivative. @@ -77,73 +83,141 @@ from its default ``x``. \poldef k(x):= (x-1)(x-2)(x-3)(x-4)/(x^2-5x+4); +.. _warningtacit: + .. attention:: - ``1/2 x`` skips the space and is treated like ``1/(2x)`` because of - the tacit multiplication rules of \xintexpr. But this means it gives - zero! Thus one must use ``(1/2)x`` or ``1/2*x`` or ``(1/2)*x`` for - disambiguation: ``x-1/2*x^2+1/3*x^3...`` + ``1/2 x^2`` skips the space and is treated like ``1/(2*x^2)`` because + of the tacit multiplication rules of \xintexpr. But this means it + gives zero! Thus one must use ``(1/2)x^2`` or ``1/2*x^2`` or + ``(1/2)*x^2`` for disambiguation: ``x - 1/2*x^2 + 1/3*x^3...``. It is + even simpler to move the denominator to the right: ``x - x^2/2 + + x^3/3 - ...``. + + It is worth noting that ``1/2(x-1)(x-2)`` suffers the same issue: + xint_ tacit multiplication always "ties more", hence this gets + interpreted as ``1/(2*(x-1)*(x-2))`` which gives zero by polynomial + division. Thus, use one of ``(1/2)(x-1)(x-2)``, ``1/2*(x-1)(x-2)`` or + ``(x-1)(x-2)/2``. After:: - \poldef f1(x):= 25(x-1)(x^2-2)(x-3)(x-4)(x-5);% - \poldef f2(x):= 37(x-1)(x^2-2)(x-6)(x-7)(x-8);% + \poldef f_1(x):= 25(x-1)(x^2-2)(x-3)(x-4)(x-5);% + \poldef f_2(x):= 37(x-1)(x^2-2)(x-6)(x-7)(x-8);% -the macro call ``\PolGCD{f1}{f2}{k}`` sets ``k`` to the (unitary) GCD of -``f1`` and ``f2``. +the macro call ``\PolGCD{f_1}{f_2}{k}`` sets ``k`` to the (unitary) GCD of +``f_1`` and ``f_2`` (hence to the expansion of ``(x-1)(x^2-2)``.) ``\PolToExpr{k}`` - will thus (expandably) give in this case ``2-2*x^1-1*x^2+1*x^3``. - This is useful for console or file output (the syntax is Maple- and - PSTricks-compatible; currently the letter ``x`` in output is not - customizable, but this can easily be added if requested from author.) + will (expandably) give in this case ``x^3-x^2-2*x+2``. This is + useful for console or file output (the syntax is Maple- and + PSTricks-compatible; the letter used in output can be + (non-expandably) changed via a redefinition of `\\PolToExprVar`_.) + +``\PolToExpr*{k}`` + gives ascending powers: ``2-2*x-x^2+x^3``. Non-expandable macros --------------------- -``\poldef name(letter):= polynomial expression using letter;`` - This evaluates the polynomial expression and stores the coefficients +.. _poldef;: + +``\poldef polname(letter):= expression in letter;`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This evaluates the *polynomial expression* and stores the coefficients in a private structure accessible later via other package macros, - under the user-chosen ``name``. Of course previously defined - polynomials are allowed in a new expression. Names must start with a + under the user-chosen ``polname``. Of course the *expression* can + use other previously defined polynomials. Names must start with a letter and are constituted of letters, digits and underscore - characters. See Examples above. + characters. The whole xintexpr_ syntax is authorized:: + + \poldef sin(z) := add((-1)^i z^(2i+1)/(2i+1)!, i = 0..10); + + With fractional coefficients, beware the `tacit multiplication issue + <warningtacit_>`_. + + As a side effect the function ``polname()`` is recognized as a + genuine ``\xintexpr...\relax`` function for (exact) numerical + evaluation (or within an ``\xintdefvar`` assignment.) It computes + values not according to the original expression but via the Horner + scheme corresponding to the polynomial coefficients. + + Also, a function with the same name is created for use within + ``\xintfloatexpr`` (or ``\xintdeffloatvar``.) This is indispensible + for numerical algorithms as exact computations very quickly lead to + very big fractions. Addition and multiplication steps of the Horner + scheme will be executed as floating-point operations. The + coefficients have already been rounded at time of definition, + according to the then prevailing ``\xinttheDigits`` value. + + .. important:: + + Package macros (such as derivatives or Euclidean division) + operate with the "exact" polynomials; "floating point" + polynomials are always obtained in a second step. + + To modifiy "in-place" the original coefficients of a polynomial + and round them to float precision:: - As a side effect the function ``name()`` is recognized as a genuine - ``\xintexpr...\relax`` function for (exact) numerical evaluation. It - computes values not according to the original expression but via - the Horner scheme corresponding to the polynomial coefficients. + \PolMapCoeffs{\xintFloat}{polname} + % or \xintFloat[P] for precision P digits + + See `\\PolMapCoeffs{\\macro}{polname}`_. The original expression is lost after parsing, and in particular the package provides no way to typeset it. This has to be done manually, if needed. -``\PolDef{name}{P(x)}`` - Does the same but the variable is assumed to be ``x``. To use - another letter, pass it as first optional argument: - ``\PolDef[X]{name}{P(X)}``. +.. _PolDef: + +``\PolDef[letter]{polname}{expression in letter}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Does the same in an undelimited macro format (thus avoiding + potential problems with the catcode of the semi-colon in presence of + some packages.) In absence of the ``[letter]`` optional argument, + the variable is assumed to be ``x``. + +``\PolLet{polname_2}={polname_1}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``\PolLet{g}{f}`` - Makes a copy of already defined polynomial f to new one g. Same - effect as ``\PolDef{g}{f(x)}`` but faster. + Makes a copy of the already defined polynomial ``polname_1`` to a + new one ``polname_2``. Same effect as + ``\PolDef{polname_2}{polname_1(x)}`` but with less overhead. The + ``=`` is optional. -``\PolAssign{f}\toarray\Array`` - Defines a one-argument expandable macro ``\Array{#1}`` which expands +``\PolAssign{polname}\toarray\macro`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Defines a one-argument expandable macro ``\macro{#1}`` which expands to the (raw) #1th polynomial coefficient. - Attention, coefficients here are indexed starting at 1. - - With #1=-1, -2, ..., ``\Array{#1}`` returns leading coefficients. + - With #1=-1, -2, ..., ``\macro{#1}`` returns leading coefficients. - With #1=0, returns the number of coefficients, i.e. ``1 + deg f`` for non-zero polynomials. - Out-of-range #1's return ``0/1[0]``. -``\PolGet{f}\fromarray\Array`` - Does the converse operation to ``\PolAssign{f}\toarray\Array``. No + See also `\\PolNthCoeff{polname}{number}`_. The main difference is that + with ``\PolAssign``, ``\macro`` is made a prefix to ``1 + deg f`` + already defined (hidden to user) macros holding individually the + coefficients but `\\PolNthCoeff{polname}{number}`_ does each time the job + to expandably recover the ``Nth`` coefficient, and due to + expandability can not store it in a macro for future usage (of course, + it can be an argument in an ``\edef``.) The other difference + is the shift by one in indexing, mentioned above (negative + indices act the same in both.) + +``\PolGet{polname}\fromarray\macro`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Does the converse operation to ``\PolAssign{polname}\toarray\macro``. No error checks on validity of coefficients as numbers. Each - ``\Array{index}`` is expanded in an ``\edef`` before being assigned + ``\macro{number}`` is expanded in an ``\edef`` before being assigned to a coefficient. Leading zero coefficients are removed from the polynomial. @@ -156,166 +230,432 @@ Non-expandable macros However the coefficients are still in their original form (i.e. they were not subjected to ``\xintRaw`` or similar xintfrac macro.) -``\PolFromCSV{f}{comma separated coefficients}`` - Defines a polynomial directly from the comma separated list (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 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). +``\PolFromCSV{polname}{<csv>}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Defines a polynomial directly from the comma separated list of + 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). Leading zero coefficients are removed:: - \PolFromCSV{J}{0, 0, 0, 0, 0, 0, 0, 0, 0, 0} + \PolFromCSV{f}{0, 0, 0, 0, 0, 0, 0, 0, 0, 0} defines the zero polynomial, which has only one (zero) coefficient. - See also expandable macro ``\PolToCSV``. + See also expandable macro `\\PolToCSV <\\PolToCSV{polname}_>`_. + +``\PolTypeset{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~ -``\PolTypeset{name}`` Typesets in descending powers in math mode. It uses letter ``x`` but this can be changed via an optional argument:: - \PolTypeset[z]{name} + \PolTypeset[z]{polname} By default zero coefficients are skipped (issue ``\poltypesetalltrue`` to get all of them in output). - Macros ``\PolTypesetCmd``, ``\PolTypesetPlus``, ``\PolTypesetMonomial`` - can help configure the output. See the package code. + These commands (whose meanings will be found in the package code) + can be re-defined for customization. Their default definitions are + expandable, but this is not a requirement. + +``\PolTypesetCmd{raw_coeff}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Basically will use ``\xintSignedFrac`` from xintfrac_, but checks if + the coefficient is ``1`` or ``-1`` and then skips printing the + ``1``, except for the constant term... + + One can do things such as for example: [#]_ + + :: + + \renewcommand\PolTypesetCmd[1]{\num{\xintPFloat[5]{#1}}} + \renewcommand\PolTypesetCmd[1]{\num{\xintRound{4}{#1}}} + + where e.g. we used the ``\num`` macro of ``siunitx`` as it + understands floating point notation. -``\PolTypeset*{name}`` - Typesets in ascending powers. Change the letter from its default - ``x`` by optional argument. + .. [#] the difference in the syntaxes of ``\xintPFloat`` and + ``\xintRound`` is explained from the fact that + ``\xintPFloat`` by default uses the prevailing precision + hence the extra argument like here ``5`` is an optional one. -``\PolDiff{f1}{f2}`` - This sets f2 to the first derivative of ``f1``. It is allowed to - issue ``\PolDiff{f}{f}``, effectively replacing ``f`` by ``f'``. +``\PolTypesetCmdPrefix{raw_coeff}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Coefficients of the result ``f2`` are irreducible fractions + Expands to a ``+`` if the ``raw_coeff`` is zero or positive, and to + nothing if ``raw_coeff`` is negative, as in latter case the + ``\xintSignedFrac`` used by `\\PolTypesetCmd{raw_coeff}`_ will put + the ``-`` sign in front of the fraction (if it is a fraction) and + this will thus serve as separator in the typeset formula. Not used + for the first term. + +``\PolTypesetMonomialCmd`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This decides how a monomial (in variable ``\PolVar`` and with + exponent ``\PolIndex``) is to be printed. The default does nothing + for the constant term, ``\PolVar`` for the first degree and + ``\PolVar^{\PolIndex}`` for higher degrees monomials. Beware that + ``\PolIndex`` expands to digit tokens and needs termination in + ``\ifnum`` tests. + +``\PolTypeset*{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + + Typesets in ascending powers. Use e.g. ``[h]`` optional argument + (after the ``*``) to use letter ``h`` rather than ``x``. + +``\PolDiff{polname_1}{polname_2}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This sets ``polname_2`` to the first derivative of ``polname_1``. It + is allowed to issue ``\PolDiff{f}{f}``, effectively replacing ``f`` + by ``f'``. + + Coefficients of the result ``polname_2`` are irreducible fractions (see `Technicalities`_ for the whole story.) -``\PolDiff[N]{f1}{f2}`` - This sets ``f2`` to the ``N``-th derivative of ``f1``. Identical - arguments is allowed. With ``N=0``, same effect as - ``\PolLet{f2}{f1}``. With negative ``N``, switches to using - ``\PolAntiDiff``. +``\PolDiff[N]{polname_1}{polname_2}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This sets ``polname_2`` to the ``N``-th derivative of ``polname_1``. + Identical arguments is allowed. With ``N=0``, same effect as + ``\PolLet{polname_2}={polname_1}``. With negative ``N``, switches to + using ``\PolAntiDiff``. -``\PolAntiDiff{f1}{f2}`` - This sets ``f2`` to the primitive of ``f1`` vanishing at zero. +``\PolAntiDiff{polname_1}{polname_2}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Coefficients of the result ``f2`` are irreducible fractions + This sets ``polname_2`` to the primitive of ``polname_1`` vanishing + at zero. + + Coefficients of the result ``polname_2`` are irreducible fractions (see `Technicalities`_ for the whole story.) -``\PolAntiDiff[N]{f1}{f2}`` - This sets ``f2`` to the result of ``N`` successive integrations on - ``f1``. With negative ``N``, it switches to using ``\PolDiff``. +``\PolAntiDiff[N]{polname_1}{polname_2}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This sets ``polname_2`` to the result of ``N`` successive integrations on + ``polname_1``. With negative ``N``, it switches to using ``\PolDiff``. + +``\PolDivide{polname_1}{polname_2}{polname_Q}{polname_R}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + This sets ``polname_Q`` and ``polname_R`` to be the quotient and + remainder in the Euclidean division of ``polname_1`` by + ``polname_2``. -``\PolDivide{f1}{f2}{Q}{R}`` - This sets ``Q`` and ``R`` to be the quotient and remainder in the - Euclidean division of ``f1`` by ``f2``. +``\PolGCD{polname_1}{polname_2}{polname_GCD}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``\PolGCD{f}{g}{k}`` - This sets ``k`` to be the G.C.D. It is a unitary polynomial except - if both ``f`` and ``g`` vanish, then ``k`` is the zero polynomial. + This sets ``polname_GCD`` to be the G.C.D. It is a unitary + polynomial except if both ``polname_1`` and ``polname_2`` vanish, + then ``polname_GCD`` is the zero polynomial. -``\PolMapCoeffs{\macro}{name}`` - It modifies each coefficient of the defined polynomial via the - *expandable* macro ``\macro``. The degree is adjusted as necessary - if some leading coefficients vanish after the operation. In - replacement text of ``\macro``, ``\index`` expands to the - coefficient index (which is defined to be zero for the constant - term). +``\PolMapCoeffs{\macro}{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + It modifies ('in-place': original coefficients get lost) each + coefficient of the defined polynomial via the *expandable* macro + ``\macro``. The degree is adjusted as necessary if some leading + coefficients vanish after the operation. In replacement text of + ``\macro``, ``\index`` expands to the coefficient index (which is + defined to be zero for the constant term). Notice that ``\macro`` will have to handle inputs of the shape - ``A/B[N]`` (xintfrac internal notation). This means that it probably + ``A/B[N]`` (xintfrac_ internal notation). This means that it probably will have to be expressed in terms of macros from xintfrac package. Example:: \def\foo#1{\xintMul{#1}{\the\numexpr\index*\index\relax}} - (or with ``\xintSqr{\xindex}``) to replace ``n``-th coefficient + (or with ``\xintSqr{\index}``) to replace ``n``-th coefficient ``f_n`` by ``f_n*n^2``. -``\PolReduceCoeffs{name}`` - About the same as ``\PolMapCoeffs{\xintIrr}{name}`` (but adds - ``[0]`` postfix which speeds up xintfrac operations when - evaluating.) +``\PolReduceCoeffs{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + About the same as ``\PolMapCoeffs{\xintIrr}{polname}`` (but + maintaining a ``[0]`` postfix for speedier xintfrac_ parsing when + polynomial function is used for computations.) This is a + one-argument macro, working 'in-place'. Expandable macros ----------------- All these macros expand completely in two steps except ``\PolToExpr`` -which needs a ``\write``, ``\edef`` or a ``\csname...\endcsname`` context. +and ``\PolToFloatExpr`` (and their auxiliaries) which need a +``\write``, ``\edef`` or a ``\csname...\endcsname`` context. -``\PolEval{name}\At{value}`` - It boils down to ``\xinttheexpr reduce(name(value))\relax``. +``\PolEval{polname}\At{numerical expression}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``\PolNthCoeff{name}{N}`` - It expands to the raw ``N``-th coefficient (``0/1[0]`` if index is - out of range). With ``N=-1``, ``-2``, ... expands to the leading - coefficients. + It boils down to ``\xinttheexpr polname(numerical expression)\relax``. + + .. note:: + + The ``0.2`` version stupidly tried to be clever and as a result + of a misguided optimization choked if ``value`` was not a number + but a numerical expression (a sum e.g.), but the more powerful + behaviour has been reinstored at ``0.3`` release. + + The ``0.1`` and ``0.2`` version did a ``reduce`` which however is + costly on big fractions and irrelevant if the output is served as + argument of ``\xintRound`` or ``\xintFloat``. Thus ``reduce`` was + removed, and former meaning is now available as + `\\PolEvalReduced{polname}\\At{numerical expression}`_ + +``\PolEvalReduced{polname}\At{numerical expression}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Boils down to ``\xinttheexpr reduce(polname(numerical expression))\relax``. + +``\PolFloatEval{polname}\At{numerical expression}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Boils down to ``\xintthefloatexpr polname(numerical expression)\relax``. + + This is done via a Horner Scheme (see `\\poldef <poldef;_>`_), with + already rounded coefficients. [#]_ To use the *exact coefficients* + (and *exact* additions and multiplications), just insert it in the + float expression as in this example: [#]_ + + :: + + \xintthefloatexpr 3.27*\xintexpr f(2.53)\relax^2\relax + + The ``f(2.53)`` is exactly computed then rounded at the time of + getting raised to the power ``2``. Moving the ``^2`` inside, that + operation would also be treated exactly. + + .. [#] Anyway each floating point operation starts by rounding its + operands to the floating point precision. + + .. [#] The ``\xintexpr`` could be ``\xinttheexpr`` but that would be + less efficient. Cf. xintexpr_ documentation about nested + expressions. + +``\PolNthCoeff{polname}{number}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + It expands to the raw ``N``-th coefficient (``0/1[0]`` if the index + number is out of range). With ``N=-1``, ``-2``, ... expands to the + leading coefficients. + +``\PolDegree{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~ -``\PolDegree{name}`` It expands to the degree. This is ``-1`` if zero polynomial but this may change in future. Should it then expand to ``-\infty`` ? -``\PolToExpr{f}`` - Expands to ``f_0 + f_1*x + f_2*x^2 + ...`` (ascending powers). [1]_, - [2]_ +``\PolToExpr{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~ - .. [1] in a ``\write``, ``\edef``, or ``\csname...\endcsname``, but - not under ``\romannumeral-`0``. + Expands [#]_ to ``coeff_N*x^N+...`` (descending powers.) - .. [2] the letter ``x`` is (in this release) not customizable. + .. [#] in a ``\write``, ``\edef``, or ``\csname...\endcsname``, but + not under ``\romannumeral-`0``. - By default zero coefficients are skipped (issue ``\poltoexprtrue`` to + By default zero coefficients are skipped (issue ``\poltoexpralltrue`` to get all of them in output). - No ``+`` sign before negative coefficients, for compliance with Maple - input format. This means though that parsing the result back via - naive delimited macros is difficult, see ``\PolToList`` and ``\PolToCSV`` - for more low-level formats making it easier to get expandably some - output of one's choice, which may possibly be parsed later on by - other macros of one's design, or from other packages. + By default, no ``+`` sign before negative coefficients, for + compliance with Maple input format (but see + `\\PolToExprTermPrefix{raw_coeff}`_.) Also, like the default + behaviour of `\\PolTypeset{polname}`_, does not print (for the non + constant terms) coefficients equal to plus or minus one. The degree + one monomial is output as ``x``, not ``x^1``. Complete customization is + possible, see next macros. - Of course ``\PolToExpr{f}`` can be inserted in a \poldef, as the + Of course ``\PolToExpr{f}`` can be inserted in a ``\poldef``, as the latter expands token by token, hence will force complete expansion - of ``\PolToExpr{f}``, but simply ``f(x)`` will be more efficient for the - identical result. + of ``\PolToExpr{f}``, but a simple ``f(x)`` is more efficient for + the identical result. + +``\PolToExprOneTerm{raw_coeff}{number}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This two argument expandable command takes care of the monomial and + its coefficient. The default definition is done in order for + coefficients of absolute value ``1`` not be printed explicitely + (except of course for the constant term). Also by default, the + monomial of degree one is ``x`` not ``x^1``, and ``x^0`` is skipped. + + For compatibility with Maple input requirements, by default a ``*`` + always precedes the ``x^number``, except if the coefficient is a one + or a minus one. See `\\PolToExprTimes`_. + +``\PolToExprOneTermStyleB{raw_coeff}{number}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + For output in this style:: + + 2*x^11/3+3*x^8/7-x^5−x^4/4−x^3−x^2/2−2*x+1 + + issue ``\let\PolToExprOneTerm\PolToExprOneTermStyleB`` before using + ``\PolToExpr``. Note that then ``\PolToExprCmd`` isn't used at all. + + To suppress the ``*``'s, cf. `\\PolToExprTimes`_. + +``\PolToExprCmd{raw_coeff}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + It is the one-argument macro used by the package definition of + ``\PolToExprOneTerm`` for the coefficients themselves (when not + equal to plus or minus one), and it defaults to + ``\xintPRaw{\xintRawWithZeros{#1}}``. One will have to redefine it + to ``\xintIrr{#1}`` or to ``\xintPRaw{\xintIrr{#1}}`` to obtain in the + output forcefully reduced coefficients. + +``\PolToExprTermPrefix{raw_coeff}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Defined identically as `\\PolTypesetCmdPrefix{raw_coeff}`_. It + prefixes with a plus sign for non-negative coefficients, because + they don't carry one by themselves. + +``\PolToExprVar`` +^^^^^^^^^^^^^^^^^ + + This expands to the variable to use in output (it does not have to + be a single letter, may be an expandable macro.) Initial definition + is ``x``. + +``\PolToExprTimes`` +^^^^^^^^^^^^^^^^^^^ + + This expands to the symbol used for multiplication of an + ``x^{number}`` by the corresponding coefficient. The default is + ``*``. Redefine the macro to expand to nothing to get rid of it (but + this will give output incompatible with some professional computer + algebra software). + +``\PolToExpr*{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~ + + Expands to ``coeff_0+coeff_1*x+coeff_2*x^2+...`` (ascending powers). + Customizable like `\\PolToExpr{polname}`_ via the same macros. + +``\PolToFloatExpr{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Similar to `\\PolToExpr{polname}`_ but uses `\\PolToFloatExprCmd + <\\PolToFloatExprCmd{raw_coeff}>`_ + which by default rounds and converts the coefficients to floating + point format. + + .. note:: + + The polynomial function for usage in ``\xintfloatexpr`` is + already prepared with the rounded coefficients, but the latter + are not easily recoverable (and especially not expandably) from + this. Thus ``\PolToFloatExprCmd`` operates from the *exact* + coefficients anew. This means though that if the prevailing float + precision was changed with ``\xintDigits:=P;`` syntax, the output + will obey this precision ``P``, but the polynomial function was + defined earlier and operates on floating point numbers with + coefficients which were rounded at time of definition. + + This may change in future, if the pre-rounded coefficients are + stored in a more easily accessible data structure. + +``\PolToFloatExprOneTerm{raw_coeff}{number}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Similar to `\\PolToExprOneTerm + <\\PolToExprOneTerm{raw_coeff}{number}>`_. But does not treat + especially coefficients equal to plus or minus one. + +``\PolToFloatExprCmd{raw_coeff}`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + It is the one-argument macro used by ``\PolToFloatExprOneTerm``. + Its package definition is ``\xintFloat{#1}``. + + .. caution:: + + Currently (xint_ ``1.2p``) ``\xintFloat{0}`` outputs ``0.e0`` + which is perfectly acceptable input for Python, but not for + Maple. Thus, one should better leave the `\\poltoexprallfalse`_ + toggle to its default ``\iffalse`` state, if one intends to use + the output in a Maple worksheet. - ``\PolToExprCmd`` is the one-argument macro used by ``\PolToExpr`` for the - coefficients, it defaults to ``\xintPRaw{\xintRawWithZeros{#1}}``. One - will have to redefine it to use ``\xintIrr{#1}`` in place of - ``\xintRawWithZeros{#1}`` to get in output reduced coefficients. + But even then the zero polynomial will cause a problem. Workaround:: -``\PolToList{f}`` - Expands to ``{f_0}{f_1}...{f_N}`` with ``N`` = degree of f (except - zero polynomial which does give ``{0/1[0]}`` and not an empty - output.) + \renewcommand\PolToFloatExprCmd[1]{\xintiiifZero{#1}{0.0}{\xintFloat{#1}}} + + Usage of ``\xintiiifZero`` and not ``\xintifZero`` is only for + optimization (I can't help it) because ``#1`` is known to be + in ``xintfrac`` raw format. + +``\PolToFloatExpr*{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Typesets in ascending powers. + +``\PolToList{polname}`` +~~~~~~~~~~~~~~~~~~~~~~~ + + Expands to ``{coeff_0}{coeff_1}...{coeff_N}`` with ``N`` = degree + (except zero polynomial which does give ``{0/1[0]}`` and not an + empty output.) + +``\PolToCSV{polname}`` +~~~~~~~~~~~~~~~~~~~~~~ + + Expands to ``coeff_0, coeff_1, coeff_2, ....., coeff_N``. Converse + to `\\PolFromCSV <\\PolFromCSV{polname}{\<csv\>}_>`_. + +Booleans (with default setting as indicated) +-------------------------------------------- + +``\xintverbosefalse`` +~~~~~~~~~~~~~~~~~~~~~ + + This is actually an xintexpr_ configuration. Setting it to + ``true`` triggers the writing of information to the log when new + polynomials are defined. + + .. caution:: + + The macro meanings as written to the log are to be considered + unstable and undocumented internal structures. + +``\poltypesetallfalse`` +~~~~~~~~~~~~~~~~~~~~~~~ + + If ``true``, `\\PolTypeset{polname}`_ will also typeset the vanishing + coefficients. + + +``\poltoexprallfalse`` +~~~~~~~~~~~~~~~~~~~~~~ + + If ``true``, `\\PolToExpr{polname}`_ and `\\PolToFloatExpr{polname}`_ will + also include the vanishing coefficients in their outputs. -``\PolToCSV{f}`` - Expands to ``f_0, f_1, f_2, ....., f_N``. Converse to - ``\PolFromCSV``. Technicalities -------------- -- The catcode of the semi-colon is reset temporarily by ``\poldef`` macro in - case some other package (for example the French babel module) may have - made it active. This will fail though if the whole thing was already - part of a macro argument, in such cases one can use ``\PolDef`` rather. - The colon in ``:=`` may be active with no consequences. - -- Beware the ``1/2 x`` problem: as mentioned above, it will be give zero due - to the tacit multiplication rules of ``\xintexpr`` and to the fact that - the package will do the Euclidean division of ``1`` by polynomial ``2x``. +- The catcode of the semi-colon is reset temporarily by `\\poldef + <poldef;_>`_ macro in case some other package (for example the French + babel module) may have made it active. This will fail though if the + whole thing was already part of a macro argument, in such cases one + can use `\\PolDef{f}{P(x)} <PolDef_>`_ + rather. The colon in ``:=`` may be active with no consequences. - During execution of polynomial operations by ``\poldef`` (but not during the initial purely numerical parsing of the expression), the - xintfrac macro ``\xintAdd`` is temporarily patched to always express + xintfrac_ macro ``\xintAdd`` is temporarily patched to always express ``a/b + c/d`` with ``l.c.m.(b,d)`` as denominator. Indeed the current (xint 1.2p) ``\xintAdd`` uses ``(ad+bc)/bd`` formula except if ``b`` divides ``d`` or ``d`` divides ``b``, which quickly leads in real life @@ -343,35 +683,43 @@ Technicalities where all coefficients have the same denominator 6 (which in this example is the ``l.c.m`` of the denominators of the reduced coefficients.) -- ``\PolDiff`` always applies ``\xintIrr`` to the resulting coefficients, except - that the *power of ten* part ``[N]`` (for example an input in scientific - notation such as ``1.23e5`` gives ``123/1[3]`` internally in xintfrac) is not - taken into account in the reduction of the fraction. This is tentative - and may change. +- `\\PolDiff{polname_1}{polname_2}`_ always applies ``\xintIrr`` to the + resulting coefficients, except that the *power of ten* part ``[N]`` + (for example an input in scientific notation such as ``1.23e5`` gives + ``123/1[3]`` internally in xintfrac) is not taken into account in the + reduction of the fraction. This is tentative and may change. - Same remark for ``\PolAntiDiff``. + 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``. -- If ``f`` was created from comma separated values by macro \PolFromCSV, - then the coefficients will be in the output of ``\PolToList`` and - ``\PolToCSV`` 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 is an unavoidable consequence of usage - by \poldef of ``\xintdeffunc`` which itself is based on ``\xintexpr.`` + the xintfrac *raw* format. This *raw* format speeds up expansion of xintfrac macros for numerical evaluations. -- Currently, the package does not as a result of ``\poldef`` add to the TeX - memory an already pre-computed *array* structure for the polynomial - coefficients, as would be constructed by ``\PolAssign{f}\toarray\macro``. - Such structures are used, but for internal calculations in temporarily - restricted scopes. Apart from the function ``f()`` known to the - (numerical) ``\xintexpr`` parser (whose meaning can be found in the log - file after \xintverbosetrue), the data is (currently) stored in a - single other macro encapsulating the degree, and the coefficients as a - list. This may evolve in future. +- 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 + high degree and few coefficients (as an example with ``\poldef + f(x):=x^1000 + x^500;`` the subsequent definition ``\poldef g(x):= + f(x)^2;`` will do of the order of 1,000,000 multiplications and + additions involvings only zeroes... which does take time). This + may change in the future. + +- Tests have been made with Newton's iteration (for which computing + exactly the derivative is precisely what this package is made for) or + Regula Falsi method for locating roots: using exact computations leads + quickly to gigantic fractions (but dichotomy method much less so). It + is thus recommended to use ``\xintdeffloatvar`` or + ``\xintthefloatexpr`` contexts for any kind of numerical mathematics. + Of course, exact computations are invaluable for number theory or + combinatorics... - As is to be expected internal structures of the package are barely documented and unstable. Don't use them. @@ -379,10 +727,24 @@ Technicalities RELEASES -------- -- 0.1 (2018/01/11): initial release (files README, polexpr.sty). -- 0.2 (2018/01/14): documentation moved to polexpr.{txt,html}. +- 0.1 (2018/01/11) + + Initial release (files README, polexpr.sty). -Files of 0.2 release: +- 0.2 (2018/01/14) + + Documentation moved to polexpr.{txt,html}. + +- 0.3 (2018/01/17) + + Make polynomials known to ``\xintfloatexpr`` and improve + documentation. + +- 0.3.1 (2018/01/18) + + Fix two typos in documentation. + +Files of 0.3.1 release: - README.md, - polexpr.sty (package file), @@ -391,4 +753,17 @@ Files of 0.2 release: __ http://docutils.sourceforge.net/docs/index.html -See README.md for the License and the change log. +See README.md for the License and the change log (there were +some breaking changes from 0.2 to 0.3). + +Acknowledgments +--------------- + +Thanks to Jürgen Gilg whose question about xint_ usage for +differentiating polynomials was the initial trigger leading to this +package, and to Jürgen Gilg and Thomas Söll for testing it on some +concrete problems. + +.. _xintfrac: +.. _xintexpr: +.. _xint: http://www.ctan.org/pkg/xint |