summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/polexpr/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/polexpr/README')
-rw-r--r--Master/texmf-dist/doc/latex/polexpr/README373
1 files changed, 373 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/polexpr/README b/Master/texmf-dist/doc/latex/polexpr/README
new file mode 100644
index 00000000000..a258011f9dd
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/polexpr/README
@@ -0,0 +1,373 @@
+-*- fill-column: 72; mode: text; -*-
+
+Package polexpr
+===============
+
+License
+-------
+
+Copyright (C) 2018 Jean-Francois Burnol
+
+See documentation of package xint for contact information.
+
+This Work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License version 1.3c.
+This version of this license is in
+
+ http://www.latex-project.org/lppl/lppl-1-3c.txt
+
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+
+This Work has the LPPL maintenance status author-maintained.
+
+The Author of this Work is Jean-Francois Burnol.
+
+This Work consists of the package file polexpr.sty and this README.
+
+
+Abstract
+--------
+
+The package provides "\poldef": a parser of polynomial expressions
+based upon the "\xintdeffunc" mechanism of package xintexpr.
+
+The syntax is
+
+ \poldef <name>(x):=<expression in variable x>;
+
+where in place of "x" an arbitrary letter is authorized. The expression
+uses the operations of algebra (including composition of functions) with
+standard operators, fractional numbers (possibly in scientific notation)
+and previously defined polynomial functions or other constructs as
+recognized by the \xintexpr numerical parser.
+
+The so-defined name() \xintexpr-function is also known to the package
+via its polynomial coefficients, thus allowing dedicated macros to
+implement polynomial algorithmics.
+
+Examples
+--------
+
+\poldef f(x):= 1-x+x^2;
+
+This 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 than x in the expression, one must pass it as
+an extra optional 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".
+
+\poldef f(z):= f(z)^2; redefines "f" in terms of itself.
+
+\poldef f(T):= f(f(T)); again redefines "f" in terms of its (new) self.
+
+\poldef k(z):= f(z)-g(g(z)^2)^2; should now define the zero
+polynomial... Let's check:
+\[ k(z) = \PolTypeset[z]{k} \]
+
+\PolDiff{f}{df_dx} sets "df_dx" to the derivative of "f".
+
+\PolDiff{df_dx}{f_xx} obtains second derivative
+
+\PolDiff[3]{f}{d3f_dx3} computes directly the third derivative
+
+$f(z) = \PolTypeset[z]{f} $\newline
+$f'(z) = \PolTypeset[z]{df_dx}$\newline
+$f''(z) = \PolTypeset[z]{f_xx}$\newline
+$f'''(z)= \PolTypeset[z]{d3f_dx3}$\par
+
+*Important*: the package does not currently know rational functions.
+and "/" in a parsed polynomial expression does the Euclidean quotient:
+
+ (1-x^2)/(1-x) does give 1+x but (1/(1-x))*(1-x^2) evaluates to zero.
+
+*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.
+
+\poldef k(x):= (x-1)(x-2)(x-3)(x-4)/(x^2-5x+4);%
+
+\PolTypeset{k} gives the expected x^2-5x+6
+
+\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);%
+
+\PolGCD{f1}{f2}{k} sets "k" to the (unitary) GCD of "f1" and "f2".
+
+\PolToExpr{k} expandably gives 2-2*x^1-1*x^2+1*x^3 for console
+or file output (this is Maple-compatible input syntax).
+
+Non-expandable macros
+---------------------
+
+\poldef name(letter):= polynomial expression using 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 letter and are constituted of letters,
+ digits and underscore characters. See Examples above.
+
+ 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.
+
+ 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.
+
+\PolLet{g}{f}
+ Makes a copy of already defined polynomial f to new one g.
+ Same effect as \PolDef{g}{f(x)} but faster.
+
+\PolAssign{f}\toarray\Array
+ Defines a one-argument expandable macro \Array{#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=0, returns the number of coefficients, i.e. 1+degree(f)
+ for non-zero polynomials.
+
+ - Out-of-range #1's return 0/1[0].
+
+\PolGet{f}\fromarray\Array
+ Does the reverse operation to \PolAssign{f}\toarray\Array. No error
+ checks on validity of coefficients as numbers. Each \Array{index}
+ is expanded in an \edef before being assigned to a coefficient.
+ Leading zero coefficients are removed from the polynomial.
+
+ (contrived) Example: \xintAssignArray{1}{-2}{5}{-3}\to\foo
+ \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.)
+
+\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 they are 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} defines the zero
+ polynomial, which has only one (zero) coefficient.
+
+ See also expandable macro \PolToCSV.
+
+\PolTypeset[x]{name}
+ Typesets in descending powers in math mode using the specified
+ variable (default x.) 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.
+
+\PolTypeset*[x]{name}
+ Typesets in ascending powers.
+
+\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'.
+
+ Coefficients of the result f2 are irreducible fractions
+ (see `Technicalities`_ for the whole story.)
+
+\PolDiff[N]{f1}{f2}
+ This sets f2 to the Nth derivative of f1. Identical arguments
+ is allowed. With N=0, same effect as \PolLet{f2}{f1}.
+ With negative N, switched to using \PolAntiDiff.
+
+\PolAntiDiff{f1}{f2}
+ This sets f2 to the primitive of f1 vanishing at zero.
+
+ Coefficients of the result f2 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.
+
+\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{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.
+
+\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).
+
+ Notice that \macro will have to handle inputs of the shape 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^2\relax}}
+ to replace nth 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.)
+
+Expandable macros
+-----------------
+
+All these macros expand completely in two steps except \PolToExpr
+which needs a \write, \edef or a \csname...\endcsname context.
+
+\PolEval{name}\At{value}
+ It boils down to \xinttheexpr reduce(name(value))\relax.
+
+\PolNthCoeff{name}{N}
+ It expands to the raw Nth coefficient (0/1[0] if index is out of
+ range). With N=-1, -2, ... expands to the leading coefficients.
+
+\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]
+
+ [1] in a \write, \edef, or \csname...\endcsname, but not under
+ \romannumeral-`0
+
+ [2] the letter x is (in this release) not customizable.
+
+ By default zero coefficients are skipped (issue \poltoexprtrue 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.
+
+ 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.
+
+ \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.
+
+\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.)
+
+\PolToCSV{f}
+ Expands to f_0, f_1, f_2, ....., f_N. Converse of \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.
+
+- 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 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 to big denominators.
+
+ It is probable that this convention will be backported as default
+ behaviour of xintfrac's \xintAdd in a future xint release. When this
+ change is merged, there will be an impact on coefficients computed by
+ \poldef because the change will apply even to the pure numerical
+ evaluations arising during the initial stage of the parsing. Of course
+ the coefficients are still the same rational numbers, only
+ representation as fractions may change.
+
+- As a consequence of previous rule, user-chosen common denominators
+ survive addition and multiplications:
+
+ \poldef P(x):= 1/2 + 2/2*x + 3/2*x^3 + 4/2*x^4;
+ \poldef Q(x):= 1/3 + (2/3)x + (3/3)x^3 + (4/3)x^4;
+ \poldef PQ(x):= P(x)*Q(x);
+
+ gives the polynomial
+
+ 1/6+4/6*x^1+4/6*x^2+6/6*x^3+20/6*x^4+16/6*x^5+9/6*x^6+24/6*x^7+16/6*x^8
+
+ 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 "decimal" 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.
+
+- If f was created from comma separated values by macro \PolFromCSV,
+ then the exact same coefficients (except those zero coefficients
+ beyond the leading monomial) will be in the output of \PolToList and
+ \PolToCSV in their original input form: 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. 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.
+
+- As is to be expected internal structures of the package are barely
+ documented and unstable. Don't use them.
+
+
+CHANGE LOG
+----------
+
+- v0.1 (2018/01/11): initial release. Features:
+
+ *. differentiation and anti-differentiation,
+ *. Euclidean division and GCDs,
+ *. various utilities such as \PolFromCSV, \PolToCSV, \PolToExpr.
+
+ Only one-variable polynomials so far.
+
+ Due to lack of available time I have not really yet set-up a
+ sufficient enough test suite. Bug reports very welcome!