macro librarywork/xetal-libraries/libs/Equations/src/Equations.xtlm

The value of an equation written as a paper prints it. The left names the result, its free indices and their extents ("Y[o,h,w] | O Ho Wo", or "L[] | " for a scalar). The right is an expression over the free indices in which a parenthesized sum is a term: "(sum j:=0..M-1 | W[i,j] * x[j]) + b[i]" A sum is an operator word (sum, prod, max, min), an index, := and an inclusive range low..high, then | and its body; several, separated by commas, nest outermost first. A right side that is one bare sum needs no parentheses: "sum c:=0..C-1, sum r:=0..Kh-1 | X[c,h+r] * W[c,r]". The word integral binds a continuous variable over Float bounds and takes the value of its body by a quadrature rule written after by: "integral tau:=0..1 by simpson 64 | exp(tau)" (trapezoid or simpson, then the number of steps; without by, trapezoid 64; simpson needs an even number). The variable is the grid of n + 1 points a, a + h, ..., b; a bound of inf is refused (write a truncation and show the tail is small, or change variables). Trapezoid is exact on lines, simpson on cubics; at a jump of the body the sample takes the body's value at that point as written. Expressions follow math precedence: ^ binds tightest (right to left), then * and /, then + and - (left to right); parentheses group; the functions are exp(x), log(x), sqrt(x), abs(x), sin(x), cos(x), max(a, b) and min(a, b); A[e1,e2] reads one element of the caller's array A, one index per axis, from 0. Every reading rule uses all of its text or refuses the call, and what was read is written back and compared with the text at every call, so nothing written is ever dropped. Both sides are notations (X_eTaL MC32): where a program is drawn (the pages, the live demo, xetal render --html) the call's two strings are shown as one math box, what e:t_ex< gives for them, after the macro's name; the value and the text are unchanged. draws: t_ex<

The LaTeX of the same call, a string: the result as written (L for a scalar, Y_{o,h,w} for an array), then = and the expression, with \sum \prod \max \min, \int_{a}^{b} ... \, d\tau for an integral (a Greek letter's name as its command), \frac for a quotient, \sqrt \exp \log \sin \cos, and the brackets as subscripts.

The same LaTeX with each symbol the caller supplies marked for a page: the result, every array reference with its subscripts and every named scalar (in a body or a range bound) wrapped in KaTeX's \htmlClass{sym sym-NAME}{...}, NAME as written (a Greek letter by its word: sym-tau). Indices, an integral's variable, prev, functions and numbers are not wrapped (the classes idx and idx-NAME are kept for indices). Everything else is e:t_ex<'s output, unchanged. KaTeX draws \htmlClass only with trust allowing it and strict letting the htmlExtension through.

Both from one call: the pair (value, LaTeX); drawn as e:e_q< is. draws: t_ex<

Discrete 1-D convolution and cross-correlation, written as the sums they are (X_eTaL Saga 42 decision 5: library macros over sum, not words of the grammar). The left names the result, its index and the boundary mode, "y[n] | full"; the right names the signal and the kernel, two of the caller's vectors, "x h". The modes: full gives L + M - 1 values (every overlap, the signal padded with M - 1 zeros at each end), same the L centered on full (as numpy centers them), valid the L - M + 1 complete overlaps (a kernel longer than the signal stops the program when it runs); no mode is implicit. Convolution is y[n] = sum over m of x[n - m] h[m], the kernel reversed as it slides; correlation y[n] = sum over m of x[n + m] h[m], not reversed, so correlation is convolution with the kernel reversed. xetal expand shows the sum each call becomes. Both sides are notations (MC32), drawn by e:c_onvolveTex<. draws: c_onvolveTex<

Cross-correlation, the same call shape (see c_onvolve<); drawn by e:c_orrelateTex<. draws: c_orrelateTex<

The LaTeX of a convolution call, a string: the textbook sum, y_{n} = \sum_{m} x_{n-m} \, h_{m}, with the mode after it in words.

The LaTeX of a correlation call (x_{n+m}, the kernel not reversed).

The boundary modes.

The expansion of a convolution or correlation call: a block that measures the signal (L) and the kernel (M), pads the signal with M - 1 zeros of its own type at each end (full and same), checks the lengths (valid), then the equation over the free index, computed as any equation is.

The LaTeX of a convolution or correlation call as a string literal: the result and its index, = , the sum over the kernel's index of the signal at n - m (convolution) or n + m (correlation) times the kernel at m, then the mode in words; the sides read as the call is.

"+" and t, or "" for an empty t.

The left side "y[n] | mode" as (result, index, mode): one index, a mode the library has.

The right side "x h" as (signal, kernel): two names.

The first of the candidates that is not the free index, as the sum's index.

The free indices and their extents, from "Y[o,h,w] | O Ho Wo", as (names, extents), boxed texts; "L[] | " gives none of either.

The right text, checked: its characters are the grammar's, a bare sum is wrapped as the term it is, and the reading written back equals the text with its spaces removed (so no rule dropped a character); the text to read.

A right side that is one bare sum, "sum i:=0..n | body", as the term it is, parenthesized; anything else as written.

Characters of names and numbers.

Every character an equation may hold.

The operator words and the functions.

The quadrature rules an integral may be taken by, and the default option text when a call writes none.

The spellings of an infinite bound.

a when c holds, else b, both already computed: texts or counts (one each: a library's helpers form one binding group, in which a helper used at two types is not yet generalized).

What a term is, from its text (trimmed, not empty): "add" (a chain of + and -, a leading - a negation), "mul" (* and /), "pow" (^), "sum" (a parenthesized sum), "group" (parentheses), "fn" (a function applied), "ref" (an array indexed) or "atom" (a name or a number). One place decides, so the value, the LaTeX and the reprint agree.

Whether t is a function applied: a word, then one parenthesized group that ends the text (pa:a_pplied?'s shape alone): the fixed math functions and the program's own are both read this way (X_eTaL-ML ask E3), told apart only in h:v_alueFn/h:t_exFn.

A function applied, as (name, arguments), the arguments cut at the top-level commas. The count is checked only for a fixed math function (its own, not the caller's): a named function is trusted with however many it is given, since nothing here knows its real arity -- a wrong count is caught only when the expanded code fails to compile (X_eTaL-ML ask E3, decided with the user).

A parenthesized sum as (words, indices, lows, highs, options, body): the bindings before the top-level |, each "word i:=low..high" (the word an operator word), an integral's followed by its by options (the text after by as written, "" for none).

One binding, "word i:=low..high", "integral x:=a..b by rule n" or "scan t:=lo..hi by seed", as (word, index, low, high, options): the by options cut off before Parsing reads the range, then checked (an integral's rule and grid; a scan's seed, any expression of the caller's values, checked only when it is read as one; a sum has neither; an integral's bounds are finite).

Whether a bound is written infinite (inf, -inf, infinity, oo).

The by options checked when there are any (at is where by was found, 0 for none): an integral's rule and grid; a scan's seed is any expression, read when the scan itself is (h:v_alueScan).

Whether an integral's by options are a rule the library has and a whole number of steps (even for simpson); else a refusal.

The rule and the steps of an integral's options ("" for the default).

s before position k (all of s when k is 0), and s after a separator of length m at position k ("" when k is 0).

A binding's (word, index, low, high, options), boxed, so a sum's bindings can be taken apart by position.

An atom checked: a name or a number.

The whole expansion: a block defining the checks, the grid of the free indices, and the expression's value over it.

The lines defining a grid over spans and its cell function (the coordinates along axis k, shaped like the grid).

The value of a term in env (the indices in scope, their spans and lows, the grid's cell function, the helpers), as X_eTaL text.

A chain folded left: ((a + b) - c); a leading minus is 0 - a.

The left fold of a chain: acc, then each operator with the next part.

a ^ b, right to left: the text cut at its first top-level ^.

A parenthesized sum: a block with its own grid over the indices in scope and then its own, the body on that grid, and one reduction per binding (innermost first), leaving an array over the indices in scope. A scan is not a reduction (its term may use the one before, X_eTaL-ML ask E2) and is handled on its own, h:v_alueScan, before any of this -- it must be the term's only binding. Outside a scan, prev is refused wherever it is written: the word is reserved for the term a scan folds into the one before it.

The length of the leading run of name characters in t (0 if t does not start with one): how h:r_enamed and h:h_asPrev? find a whole word instead of matching part of a longer name.

t with every whole-word occurrence of from replaced by to, anything else untouched: how a scan's index and prev become plain generated names before the body is translated like any other expression (its own grammar has no notion of either, so they are never looked up through the grid env the other bindings use).

Whether prev appears as a whole word anywhere in t: the word a scan's own body may use (its term before), refused everywhere else.

A scan's value: a genuine fold, not a reduction -- the array machinery's reduce is a right fold (B6), only the same as a running left-to-right accumulation when the combining step is associative, which a scan's body need not be. Built instead from p_ower: one state-threading step function, (t, prev) to (t's successor, the body at that successor), applied once per point of the range, starting one step before the low end so the first real application lands there. prev starts at the seed (by, X_eTaL-ML ask E2); a scan with no seed and a body that never names prev folds in a seed of 0 harmlessly, since it is never read. The index and prev are substituted into the body's own translation (not its text: that would be reparsed as if it were the equation's grammar, which it is not) by name, so a scan's free indices, references and nested terms still translate through the ordinary env.

A binding's span, coordinate prefix, defining lines and weights name, as texts: a sum's span is its range's length, checked at run time (low and high are the caller's values, not known until then): a negative length -- the range runs high..low, backwards -- signals error[bad-equation] naming the word and the range as written, rather than falling through to the array machinery's own count error (X_eTaL-ML ask E1); its coordinate is its low plus the cell, no lines, no weights; an integral's span is its grid's n + 1 points, its coordinate a + h * the cell, its lines define a, b, h and the weights (fresh names, so the body may name any of a, b, h or w), the weights holding the rule's and the step.

The rule's weights over k steps (k + 1 points), as code: trapezoid 1/2, 1, ..., 1, 1/2; simpson (1, 4, 2, 4, ..., 4, 1) / 3.

The factor an integral's binding puts before the body: its weights laid over the grid along its axis; "" for a sum.

The reduction an operator word stands for.

A bound or extent: an expression of the caller's values, with no index in scope; one that names an index is refused.

t with its operators and brackets spaced out, so its words are its names.

A function applied to its arguments' values: the fixed math functions by their own rule, any other name as the caller's own u: function, applied to however many arguments it was given (X_eTaL-ML ask E3) -- u:name(args), not a quoted call, so a name that is not a function, or not one of this arity, is the expanded code's own compile error, naming the equation's call.

A[e1,...,en] as a gather from A's ravel, the index by Horner's rule over A's shape (0-origin, as the equation writes it); A is checked to have n axes, and each index to lie within its axis.

The ravel position of A[e1,...,ek] by Horner's rule: ek + (k-th extent of A) * (the same for e1 ... e(k-1)), down to e1; each ek passes through the bounds check.

An index in scope as its coordinates on the grid (its low added), anything else as written: the caller's name or a number.

The two run-time checks the expansion defines: an index within its axis (0 to the extent less one), and a reference with as many indices as its array has axes; each names the array, the axis and the expression as written, and gives its argument back when it holds.

The LaTeX text of the call (no quotes): the result as written (L for a scalar), = and the expression; a bare sum without the parentheses the reader gave it. on is 1 to mark the symbols (e:t_exSymbols<), 0 for plain LaTeX; every helper below takes the marking mk = (on, the index names in scope), the free indices here, and each sum adds its own for its bounds and body.

The LaTeX tex of the symbol name, wrapped in its classes when the marking mk is on.

The right side as LaTeX: a bare sum without the parentheses the reader gives it, anything else as a term.

A term as LaTeX.

A name or a number: a Greek letter's name as its command; a named scalar marked (not a number, an index in scope or prev).

A chain: a + b - c; a \, b for a product; \frac{a}{b} for a quotient.

A term without the parentheses it was written in, where what holds it already sets it apart: the numerator or denominator of \frac, the argument of \sqrt.

Two operands joined by an operator: \frac for /, a thin space for *.

A sum's bindings as \sum_{i=low}^{high} (the operator word's symbol), then its body, wrapped as asked; its indices are in scope for its bounds and its body.

A sum's index and = before its low; an integral's lower bound stands alone (\int_{a}^{b}).

A Greek letter's name as its LaTeX command (a capital's too: Phi, Sigma); any other name as is.

The symbol of an operator word.

A function applied: \exp(x), \log(x), \sqrt{x}, \lvert x \rvert, \max(a, b).

A reference as a subscript: A_{i,j}, the indices as written without spaces, a product among them as a thin space; marked as a whole.

A term as it was read, with no spaces: the same text it came from, or a rule dropped something.

An integral's by options as written, squeezed; "" for none.

The boxed texts b joined by sep.